Move subagent context to developer envelope

charley-oai · codex · charley-oai · commit 38fdc27d8de4 · 2026-03-04T19:06:09.000-08:00
Co-authored-by: Codex &lt;noreply@openai.com&gt;
diff --git a/codex-rs/core/src/agent/control.rs b/codex-rs/core/src/agent/control.rs
@@ -430,7 +430,7 @@ impl AgentControl {
                 return;
             };
             parent_thread
-                .inject_user_message_without_turn(format_subagent_notification_message(
+                .inject_developer_message_without_turn(format_subagent_notification_message(
                     &child_thread_id.to_string(),
                     &status,
                 ))
@@ -560,7 +560,7 @@ mod tests {
             let ResponseItem::Message { role, content, .. } = item else {
                 return false;
             };
-            if role != "user" {
+            if role != "developer" {
                 return false;
             }
             content.iter().any(|content_item| match content_item {
diff --git a/codex-rs/core/src/codex.rs b/codex-rs/core/src/codex.rs
@@ -3133,7 +3133,7 @@ impl Session {
         }
         if let Some(subagent_roster) = crate::session_prefix::SubagentRosterContext::new(subagents)
         {
-            contextual_user_envelope.push_fragment(subagent_roster);
+            developer_envelope.push(subagent_roster);
         }
 
         let mut items = Vec::with_capacity(2);
diff --git a/codex-rs/core/src/codex_thread.rs b/codex-rs/core/src/codex_thread.rs
@@ -101,10 +101,9 @@ impl CodexThread {
         self.codex.session.total_token_usage().await
     }
 
-    /// Records a user-role session-prefix message without creating a new user turn boundary.
-    pub(crate) async fn inject_user_message_without_turn(&self, message: String) {
+    async fn inject_message_without_turn(&self, role: &str, message: String) {
         let pending_item = ResponseInputItem::Message {
-            role: "user".to_string(),
+            role: role.to_string(),
             content: vec![ContentItem::InputText { text: message }],
         };
         let pending_items = vec![pending_item];
@@ -128,6 +127,17 @@ impl CodexThread {
             .await;
     }
 
+    /// Records a user-role session-prefix message without creating a new user turn boundary.
+    #[cfg(test)]
+    pub(crate) async fn inject_user_message_without_turn(&self, message: String) {
+        self.inject_message_without_turn("user", message).await;
+    }
+
+    /// Records a developer-role session-prefix message without creating a new user turn boundary.
+    pub(crate) async fn inject_developer_message_without_turn(&self, message: String) {
+        self.inject_message_without_turn("developer", message).await;
+    }
+
     pub fn rollout_path(&self) -> Option<PathBuf> {
         self.rollout_path.clone()
     }
diff --git a/codex-rs/core/src/context_manager/history_tests.rs b/codex-rs/core/src/context_manager/history_tests.rs
@@ -70,6 +70,18 @@ fn user_input_text_msg(text: &str) -> ResponseItem {
     }
 }
 
+fn developer_input_text_msg(text: &str) -> ResponseItem {
+    ResponseItem::Message {
+        id: None,
+        role: "developer".to_string(),
+        content: vec![ContentItem::InputText {
+            text: text.to_string(),
+        }],
+        end_turn: None,
+        phase: None,
+    }
+}
+
 fn custom_tool_call_output(call_id: &str, output: &str) -> ResponseItem {
     ResponseItem::CustomToolCallOutput {
         call_id: call_id.to_string(),
@@ -616,7 +628,7 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
             "<skill>\n<name>demo</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>",
         ),
         user_input_text_msg("<user_shell_command>echo 42</user_shell_command>"),
-        user_input_text_msg(
+        developer_input_text_msg(
             "<subagent_notification>{\"agent_id\":\"a\",\"status\":\"completed\"}</subagent_notification>",
         ),
         user_input_text_msg("turn 1 user"),
@@ -638,7 +650,7 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
             "<skill>\n<name>demo</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>",
         ),
         user_input_text_msg("<user_shell_command>echo 42</user_shell_command>"),
-        user_input_text_msg(
+        developer_input_text_msg(
             "<subagent_notification>{\"agent_id\":\"a\",\"status\":\"completed\"}</subagent_notification>",
         ),
         user_input_text_msg("turn 1 user"),
@@ -659,7 +671,7 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
             "<skill>\n<name>demo</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>",
         ),
         user_input_text_msg("<user_shell_command>echo 42</user_shell_command>"),
-        user_input_text_msg(
+        developer_input_text_msg(
             "<subagent_notification>{\"agent_id\":\"a\",\"status\":\"completed\"}</subagent_notification>",
         ),
     ];
@@ -673,7 +685,7 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
             "<skill>\n<name>demo</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>",
         ),
         user_input_text_msg("<user_shell_command>echo 42</user_shell_command>"),
-        user_input_text_msg(
+        developer_input_text_msg(
             "<subagent_notification>{\"agent_id\":\"a\",\"status\":\"completed\"}</subagent_notification>",
         ),
         user_input_text_msg("turn 1 user"),
@@ -693,7 +705,7 @@ fn drop_last_n_user_turns_ignores_session_prefix_user_messages() {
             "<skill>\n<name>demo</name>\n<path>skills/demo/SKILL.md</path>\nbody\n</skill>",
         ),
         user_input_text_msg("<user_shell_command>echo 42</user_shell_command>"),
-        user_input_text_msg(
+        developer_input_text_msg(
             "<subagent_notification>{\"agent_id\":\"a\",\"status\":\"completed\"}</subagent_notification>",
         ),
         user_input_text_msg("turn 1 user"),
diff --git a/codex-rs/core/src/contextual_user_message.rs b/codex-rs/core/src/contextual_user_message.rs
@@ -185,22 +185,13 @@ pub(crate) const USER_SHELL_COMMAND_FRAGMENT: ModelVisibleFragmentSpec =
     );
 pub(crate) const TURN_ABORTED_FRAGMENT: ModelVisibleFragmentSpec =
     ModelVisibleFragmentSpec::contextual_user(TURN_ABORTED_OPEN_TAG, TURN_ABORTED_CLOSE_TAG);
-pub(crate) const SUBAGENTS_FRAGMENT: ModelVisibleFragmentSpec =
-    ModelVisibleFragmentSpec::contextual_user(SUBAGENTS_OPEN_TAG, SUBAGENTS_CLOSE_TAG);
-pub(crate) const SUBAGENT_NOTIFICATION_FRAGMENT: ModelVisibleFragmentSpec =
-    ModelVisibleFragmentSpec::contextual_user(
-        SUBAGENT_NOTIFICATION_OPEN_TAG,
-        SUBAGENT_NOTIFICATION_CLOSE_TAG,
-    );
 
 const CONTEXTUAL_USER_FRAGMENTS: &[ModelVisibleFragmentSpec] = &[
     AGENTS_MD_FRAGMENT,
     ENVIRONMENT_CONTEXT_FRAGMENT,
     SKILL_FRAGMENT,
     USER_SHELL_COMMAND_FRAGMENT,
     TURN_ABORTED_FRAGMENT,
-    SUBAGENTS_FRAGMENT,
-    SUBAGENT_NOTIFICATION_FRAGMENT,
 ];
 
 pub(crate) fn is_contextual_user_fragment(content_item: &ContentItem) -> bool {
@@ -241,21 +232,6 @@ mod tests {
         }));
     }
 
-    #[test]
-    fn detects_subagent_notification_fragment_case_insensitively() {
-        assert!(
-            SUBAGENT_NOTIFICATION_FRAGMENT
-                .matches_text("<SUBAGENT_NOTIFICATION>{}</subagent_notification>")
-        );
-    }
-
-    #[test]
-    fn detects_subagents_fragment() {
-        assert!(is_contextual_user_fragment(&ContentItem::InputText {
-            text: "<subagents>\n  - agent-1: atlas\n</subagents>".to_string(),
-        }));
-    }
-
     #[test]
     fn ignores_regular_user_text() {
         assert!(!is_contextual_user_fragment(&ContentItem::InputText {
diff --git a/codex-rs/core/src/session_prefix.rs b/codex-rs/core/src/session_prefix.rs
@@ -1,10 +1,13 @@
 use codex_protocol::protocol::AgentStatus;
 
-/// Helpers for model-visible session state markers that are stored in user-role
-/// messages but are not user intent.
+/// Helpers for model-visible subagent session state rendered in the developer
+/// envelope.
+use crate::contextual_user_message::DEVELOPER_FRAGMENT;
 use crate::contextual_user_message::ModelVisibleFragment;
-use crate::contextual_user_message::SUBAGENT_NOTIFICATION_FRAGMENT;
-use crate::contextual_user_message::SUBAGENTS_FRAGMENT;
+use crate::contextual_user_message::SUBAGENT_NOTIFICATION_CLOSE_TAG;
+use crate::contextual_user_message::SUBAGENT_NOTIFICATION_OPEN_TAG;
+use crate::contextual_user_message::SUBAGENTS_CLOSE_TAG;
+use crate::contextual_user_message::SUBAGENTS_OPEN_TAG;
 
 pub(crate) struct SubagentRosterContext {
     subagents: String,
@@ -22,7 +25,7 @@ impl SubagentRosterContext {
 
 impl ModelVisibleFragment for SubagentRosterContext {
     fn spec(&self) -> crate::contextual_user_message::ModelVisibleFragmentSpec {
-        SUBAGENTS_FRAGMENT
+        DEVELOPER_FRAGMENT
     }
 
     fn render_text(&self) -> String {
@@ -32,7 +35,7 @@ impl ModelVisibleFragment for SubagentRosterContext {
             .map(|line| format!("  {line}"))
             .collect::<Vec<_>>()
             .join("\n");
-        SUBAGENTS_FRAGMENT.wrap_body(lines)
+        format!("{SUBAGENTS_OPEN_TAG}\n{lines}\n{SUBAGENTS_CLOSE_TAG}")
     }
 }
 
@@ -43,7 +46,7 @@ struct SubagentNotification<'a> {
 
 impl ModelVisibleFragment for SubagentNotification<'_> {
     fn spec(&self) -> crate::contextual_user_message::ModelVisibleFragmentSpec {
-        SUBAGENT_NOTIFICATION_FRAGMENT
+        DEVELOPER_FRAGMENT
     }
 
     fn render_text(&self) -> String {
@@ -52,7 +55,9 @@ impl ModelVisibleFragment for SubagentNotification<'_> {
             "status": self.status,
         })
         .to_string();
-        SUBAGENT_NOTIFICATION_FRAGMENT.wrap_body(payload_json)
+        format!(
+            "{SUBAGENT_NOTIFICATION_OPEN_TAG}\n{payload_json}\n{SUBAGENT_NOTIFICATION_CLOSE_TAG}"
+        )
     }
 }
 
diff --git a/codex-rs/core/tests/common/context_snapshot.rs b/codex-rs/core/tests/common/context_snapshot.rs
@@ -345,7 +345,7 @@ mod tests {
     fn redacted_text_mode_normalizes_subagents_fragment() {
         let items = vec![json!({
             "type": "message",
-            "role": "user",
+            "role": "developer",
             "content": [{
                 "type": "input_text",
                 "text": "<subagents>\n  - agent-1: atlas\n  - agent-2\n</subagents>"
@@ -357,7 +357,7 @@ mod tests {
             &ContextSnapshotOptions::default().render_mode(ContextSnapshotRenderMode::RedactedText),
         );
 
-        assert_eq!(rendered, "00:message/user:<SUBAGENTS:count=2>");
+        assert_eq!(rendered, "00:message/developer:<SUBAGENTS:count=2>");
     }
 
     #[test]
diff --git a/codex-rs/core/tests/suite/model_visible_layout.rs b/codex-rs/core/tests/suite/model_visible_layout.rs
@@ -54,26 +54,40 @@ fn agents_message_count(request: &ResponsesRequest) -> usize {
 }
 
 fn format_subagents_fragment_snapshot(subagents: &[&str]) -> String {
-    let mut content = vec![json!({
-        "type": "input_text",
-        "text": "<environment_context>\n  <cwd>/tmp/example</cwd>\n  <shell>bash</shell>\n</environment_context>",
-    })];
-    if !subagents.is_empty() {
+    let items = if subagents.is_empty() {
+        vec![json!({
+            "type": "message",
+            "role": "user",
+            "content": [{
+                "type": "input_text",
+                "text": "<environment_context>\n  <cwd>/tmp/example</cwd>\n  <shell>bash</shell>\n</environment_context>",
+            }],
+        })]
+    } else {
         let lines = subagents
             .iter()
             .map(|line| format!("  {line}"))
             .collect::<Vec<_>>()
             .join("\n");
-        content.push(json!({
-            "type": "input_text",
-            "text": format!("<subagents>\n{lines}\n</subagents>"),
-        }));
-    }
-    let items = vec![json!({
-        "type": "message",
-        "role": "user",
-        "content": content,
-    })];
+        vec![
+            json!({
+                "type": "message",
+                "role": "developer",
+                "content": [{
+                    "type": "input_text",
+                    "text": format!("<subagents>\n{lines}\n</subagents>"),
+                }],
+            }),
+            json!({
+                "type": "message",
+                "role": "user",
+                "content": [{
+                    "type": "input_text",
+                    "text": "<environment_context>\n  <cwd>/tmp/example</cwd>\n  <shell>bash</shell>\n</environment_context>",
+                }],
+            }),
+        ]
+    };
     context_snapshot::format_response_items_snapshot(items.as_slice(), &context_snapshot_options())
 }
 
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__model_visible_layout__model_visible_layout_subagents_fragment_includes_one_subagent.snap b/codex-rs/core/tests/suite/snapshots/all__suite__model_visible_layout__model_visible_layout_subagents_fragment_includes_one_subagent.snap
@@ -1,8 +1,7 @@
 ---
 source: core/tests/suite/model_visible_layout.rs
-assertion_line: 481
+assertion_line: 495
 expression: "format_subagents_fragment_snapshot(&[\"- agent-1: Atlas\"])"
 ---
-00:message/user[2]:
-    [01] <ENVIRONMENT_CONTEXT:cwd=<CWD>>
-    [02] <SUBAGENTS:count=1>
+00:message/developer:<SUBAGENTS:count=1>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
diff --git a/codex-rs/core/tests/suite/snapshots/all__suite__model_visible_layout__model_visible_layout_subagents_fragment_includes_two_subagents.snap b/codex-rs/core/tests/suite/snapshots/all__suite__model_visible_layout__model_visible_layout_subagents_fragment_includes_two_subagents.snap
@@ -1,8 +1,7 @@
 ---
 source: core/tests/suite/model_visible_layout.rs
-assertion_line: 491
+assertion_line: 505
 expression: "format_subagents_fragment_snapshot(&[\"- agent-1: Atlas\",\n\"- agent-2: Juniper\"])"
 ---
-00:message/user[2]:
-    [01] <ENVIRONMENT_CONTEXT:cwd=<CWD>>
-    [02] <SUBAGENTS:count=2>
+00:message/developer:<SUBAGENTS:count=2>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
diff --git a/codex-rs/core/tests/suite/subagent_notifications.rs b/codex-rs/core/tests/suite/subagent_notifications.rs
@@ -47,7 +47,7 @@ fn body_contains(req: &wiremock::Request, text: &str) -> bool {
 }
 
 fn has_subagent_notification(req: &ResponsesRequest) -> bool {
-    req.message_input_texts("user")
+    req.message_input_texts("developer")
         .iter()
         .any(|text| text.contains("<subagent_notification>"))
 }
diff --git a/docs/model-visible-context.md b/docs/model-visible-context.md
@@ -27,6 +27,7 @@ Use the developer envelope for developer-role guidance:
 - collaboration-mode developer guidance
 - model switch and realtime notices
 - personality guidance
+- subagent roster and subagent notifications
 - other developer-only instructions
 
 `DeveloperInstructions` remains the standard string-backed fragment for most developer text. It already participates in the shared fragment system.
@@ -36,10 +37,8 @@ Use the contextual-user envelope for contextual state or runtime markers that sh
 - AGENTS / user instructions
 - environment context
 - skill instructions
-- subagent roster
 - user shell command records
 - turn-aborted markers
-- subagent notifications
 
 Contextual-user fragments must have stable markers because history parsing uses those markers to distinguish contextual state from real user intent.
 

Original file line number	Diff line number	Diff line change
`@@ -3133,7 +3133,7 @@ impl Session {`
`3133`	`3133`	`}`
`3134`	`3134`	`if let Some(subagent_roster) = crate::session_prefix::SubagentRosterContext::new(subagents)`
`3135`	`3135`	`{`
`3136`		`- contextual_user_envelope.push_fragment(subagent_roster);`
	`3136`	`+ developer_envelope.push(subagent_roster);`
`3137`	`3137`	`}`
`3138`	`3138`
`3139`	`3139`	`let mut items = Vec::with_capacity(2);`