Let spawn_agent carry an output schema

codex-rs/core/src/agent/control/spawn.rs

@@ -925,6 +925,7 @@ impl LocalAgentControl {
             turn_trigger: options.turn_trigger,
             root_turn_id: options.root_turn_id,
             cyber_access_program: options.cyber_access_program,
+            final_output_json_schema: options.final_output_json_schema,
             ..Default::default()
         };
         let input_admission_started_at = Instant::now();

codex-rs/core/src/agent/types.rs

@@ -36,6 +36,9 @@ pub struct SpawnAgentOptions {
     pub environments: Option<TurnEnvironmentSnapshot>,
     pub multi_agent_v2_usage_hints: Option<ResolvedMultiAgentV2UsageHints>,
     pub cyber_access_program: Option<CyberAccessProgram>,
+    /// JSON schema the child's first turn must satisfy as its final output.
+    /// Plumbed into `TurnStartOptions::final_output_json_schema`; not re-validated here.
+    pub final_output_json_schema: Option<serde_json::Value>,
 }
 
 /// Identity and status observed from a loaded agent, without a handle to its runtime.

codex-rs/core/src/tools/handlers/multi_agents/spawn.rs

@@ -134,6 +134,7 @@ async fn handle_spawn_agent(
                 environments: Some(step_context.environments.clone()),
                 multi_agent_v2_usage_hints: None,
                 cyber_access_program: turn.cyber_access_program,
+                final_output_json_schema: args.output_schema,
             },
         })
         .await
@@ -224,6 +225,9 @@ struct SpawnAgentArgs {
     reasoning_effort: Option<ReasoningEffort>,
     #[serde(default)]
     fork_context: bool,
+    /// JSON schema the child's first turn must satisfy as its final output.
+    #[serde(default)]
+    output_schema: Option<serde_json::Value>,
 }
 
 #[derive(Debug, Serialize)]

codex-rs/core/src/tools/handlers/multi_agents_spec.rs

@@ -643,6 +643,16 @@ fn spawn_agent_common_properties_v1(agent_type_description: &str) -> BTreeMap<St
                     .to_string(),
             )),
         ),
+        (
+            "output_schema".to_string(),
+            // No type: a caller-supplied JSON schema is itself any JSON value.
+            JsonSchema {
+                description: Some(
+                    "JSON schema the spawned agent's first turn must satisfy as its final output. Omit for an unconstrained reply.".to_string(),
+                ),
+                ..Default::default()
+            },
+        ),
     ])
 }
 
@@ -680,6 +690,16 @@ fn spawn_agent_common_properties_v2(agent_type_description: &str) -> BTreeMap<St
                     .to_string(),
             )),
         ),
+        (
+            "output_schema".to_string(),
+            // No type: a caller-supplied JSON schema is itself any JSON value.
+            JsonSchema {
+                description: Some(
+                    "JSON schema the spawned agent's first turn must satisfy as its final output. Omit for an unconstrained reply.".to_string(),
+                ),
+                ..Default::default()
+            },
+        ),
     ])
 }
 

codex-rs/core/src/tools/handlers/multi_agents_spec_tests.rs

@@ -63,6 +63,17 @@ fn spawn_agent_tool_v2_requires_task_name() {
         Some("Reasoning effort override for the new agent. Omit to inherit the parent effort.")
     );
     assert!(!properties.contains_key("service_tier"));
+    // A caller-supplied schema is any JSON value, so the property carries no type.
+    let output_schema_arg = properties
+        .get("output_schema")
+        .expect("spawn_agent should accept an output schema");
+    assert_eq!(output_schema_arg.schema_type, None);
+    assert!(
+        output_schema_arg
+            .description
+            .as_deref()
+            .is_some_and(|description| description.contains("final output"))
+    );
     assert_eq!(
         parameters.required.as_ref(),
         Some(&vec!["task_name".to_string(), "message".to_string()])

codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs

@@ -203,6 +203,7 @@ async fn handle_spawn_agent(
                 environments: Some(step_context.environments.clone()),
                 multi_agent_v2_usage_hints,
                 cyber_access_program: turn.cyber_access_program,
+                final_output_json_schema: args.output_schema,
             },
         })
         .await
@@ -273,6 +274,9 @@ struct SpawnAgentArgs {
     reasoning_effort: Option<ReasoningEffort>,
     fork_turns: Option<String>,
     fork_context: Option<bool>,
+    /// JSON schema the child's first turn must satisfy as its final output.
+    #[serde(default)]
+    output_schema: Option<serde_json::Value>,
 }
 
 impl SpawnAgentArgs {

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_active_environment_selection.snap

@@ -6,15 +6,15 @@ Scenario: Astra starts in one workspace, switches for the next step of the activ
 
 ## Window 1
 -- request 1 (turn) --
-00:additional_tools/developer (3; hash=62160ed28e692c35):
+00:additional_tools/developer (3; hash=299a25860327c501):
         - namespace/functions; hash=4261ffb241688b3d
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_async_question_and_answer.snap

@@ -7,15 +7,15 @@ Scenario: Astra uses the catalog question schema to ask who a launch update is f
 
 ## Window 1
 -- request 1 (request) --
-00:additional_tools/developer (3; hash=f181967456befa67):
+00:additional_tools/developer (3; hash=4bdada565c53ed1b):
         - namespace/functions; hash=7e611b8ddd5621cf
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_disabled_executor_skills.snap

@@ -16,15 +16,15 @@ Settings:
   text: {"verbosity":"low"}
   tool_choice: "auto"
 -- request 1 (request) --
-00:additional_tools/developer (3; hash=5e8370540461db70):
+00:additional_tools/developer (3; hash=832399eb45cc415c):
         - namespace/functions; hash=7d26e086c1dbba28
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_input_interrupts_response.snap

@@ -6,15 +6,15 @@ Scenario: Astra receives new user input after its unfinished response is interru
 
 ## Window 1
 -- request 1 (request) --
-00:additional_tools/developer (3; hash=bf2e30605ff5dc17):
+00:additional_tools/developer (3; hash=82ca56c2b440b56b):
         - namespace/functions; hash=fada4a476a3754dd
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__astra_kickoff_remote_compaction_windows.snap

@@ -16,15 +16,15 @@ Settings:
   text: {"verbosity":"low"}
   tool_choice: "auto"
 -- request 1 (turn) --
-00:additional_tools/developer (3; hash=bf2e30605ff5dc17):
+00:additional_tools/developer (3; hash=82ca56c2b440b56b):
         - namespace/functions; hash=fada4a476a3754dd
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents
@@ -187,15 +187,15 @@ Settings:
 ## Window 2 (after request 3: input diverged at item 02)
 Settings: same as window 1
 -- request 4 (turn) --
-00:additional_tools/developer (3; hash=bf2e30605ff5dc17):
+00:additional_tools/developer (3; hash=82ca56c2b440b56b):
         - namespace/functions; hash=fada4a476a3754dd
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__compaction__remote_slash_compact.snap

@@ -16,15 +16,15 @@ Settings:
   text: {"verbosity":"low"}
   tool_choice: "auto"
 -- request 1 (turn; Before /compact) --
-00:additional_tools/developer (3; hash=bf2e30605ff5dc17):
+00:additional_tools/developer (3; hash=82ca56c2b440b56b):
         - namespace/functions; hash=fada4a476a3754dd
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents
@@ -164,15 +164,15 @@ Settings: unavailable (items only)
 ## Window 3 (after request 3: input diverged at item 00)
 Settings: same as window 1
 -- request 4 (turn; First turn after /compact) --
-00:additional_tools/developer (3; hash=bf2e30605ff5dc17):
+00:additional_tools/developer (3; hash=82ca56c2b440b56b):
         - namespace/functions; hash=fada4a476a3754dd
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__model_catalog_refresh_preserves_tools_and_history.snap

@@ -14,12 +14,12 @@ Settings:
   store: false
   stream: true
   tool_choice: "auto"
-  tools (6; hash=1ea0fa9abde186d4):
+  tools (6; hash=cfc3c98a78e70ca0):
     - function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5
     - function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2
     - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6
     - function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[path]; hash=1908de9c0be7118a
-    - namespace/multi_agent_v1: Tools for spawning and managing sub-agents.; hash=94c598b3c6ca141b
+    - namespace/multi_agent_v1: Tools for spawning and managing sub-agents.; hash=3600df73976fc1a7
       - function/close_agent
       - function/resume_agent
       - function/send_input

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__multi_agent_catalog_parameters.snap

@@ -16,15 +16,15 @@ Settings:
   text: {"verbosity":"low"}
   tool_choice: "auto"
 -- request 1 (turn) --
-00:additional_tools/developer (3; hash=2b84850bc279e5ed):
+00:additional_tools/developer (3; hash=29ec89a35debc3c9):
         - namespace/functions; hash=fada4a476a3754dd
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=7e156cf57f85af87
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=c9dc64d781a79893
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__provider_capabilities__custom_provider_capabilities.snap

@@ -15,12 +15,12 @@ Settings:
   stream: true
   text: {"verbosity":"low"}
   tool_choice: "auto"
-  tools (6; hash=dde875513b2c7cff):
+  tools (6; hash=7034b0984ef6658b):
     - function/exec_command: Runs a command in a PTY, returning output or a session ID for ongoing interaction.; args=[cmd, justification, login, max_output_tokens, prefix_rule, sandbox_permissions, shell, tty, workdir, yield_time_ms]; hash=c04108e51a8548c5
     - function/write_stdin: Writes characters to an existing unified exec session and returns recent output.; args=[chars, max_output_tokens, session_id, yield_time_ms]; hash=7fb62d8a3e2df4e2
     - function/request_user_input: Request user input for one to three short questions and wait for the response. This tool is only ...; args=[questions]; hash=64a729b25c424fc6
     - function/view_image: View a local image file from the filesystem when visual inspection is needed. Use this for images...; args=[detail, path]; hash=3b766d5bdec5d50e
-    - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=3cbf715dc154e1b7
+    - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=9cb3fe3bf82d4343
       - function/followup_task
       - function/interrupt_agent
       - function/list_agents

codex-rs/core/tests/suite/snapshots/all__suite__scenarios__skill_catalog_dedup__dedup_before_budgeting.snap

@@ -16,15 +16,15 @@ Settings:
   text: {"verbosity":"low"}
   tool_choice: "auto"
 -- request 1 (turn) --
-00:additional_tools/developer (3; hash=e80da11342c6e6dd):
+00:additional_tools/developer (3; hash=11140157658710d9):
         - namespace/functions; hash=bd9e182b4235cdc1
           - custom/exec
           - function/wait
           - function/request_user_input
           - function/request_user_input_async
         - namespace/clock: Tools for reading and waiting on time.; hash=f402e8c5e9b5e317
           - function/sleep
-        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=2c8d6295978dbe63
+        - namespace/collaboration: Tools for spawning and managing sub-agents.; hash=48f7a334813023a7
           - function/followup_task
           - function/interrupt_agent
           - function/list_agents