codex-tools: extract collaboration tool specs (#16141)

## Why

The recent `codex-tools` migration steps have moved shared tool models
and low-coupling spec helpers out of `codex-core`, but
`core/src/tools/spec.rs` still owned a large block of pure
collaboration-tool spec construction. Those builders do not need session
state or runtime behavior; they only need a small amount of core-owned
configuration injected at the seam.

Moving that cohesive slice into `codex-tools` makes the crate boundary
more honest and removes a substantial amount of passive tool-spec logic
from `codex-core` without trying to move the runtime-coupled multi-agent
handlers at the same time.

## What changed

- added `agent_tool.rs`, `request_user_input_tool.rs`, and
`agent_job_tool.rs` to `codex-tools`, with sibling `*_tests.rs` coverage
and an exports-only `lib.rs`
- moved the pure `ToolSpec` builders for:
- collaboration tools such as `spawn_agent`, `send_input`,
`send_message`, `assign_task`, `resume_agent`, `wait_agent`,
`list_agents`, and `close_agent`
  - `request_user_input`
  - agent-job specs `spawn_agents_on_csv` and `report_agent_job_result`
- rewired `core/src/tools/spec.rs` to call the extracted builders while
still supplying the core-owned inputs, such as spawn-agent role
descriptions and wait timeout bounds
- updated the `core/src/tools/spec.rs` seam tests to build expected
collaboration specs through `codex-tools`
- updated `codex-rs/tools/README.md` so the crate documentation reflects
the broader collaboration-tool boundary

## Test plan

- `CARGO_TARGET_DIR=/tmp/codex-tools-collab-specs cargo test -p
codex-tools`
- `CARGO_TARGET_DIR=/tmp/codex-core-collab-specs cargo test -p
codex-core --lib tools::spec::`
- `just fix -p codex-tools -p codex-core`
- `just argument-comment-lint`

## References

- #15923
- #15928
- #15944
- #15953
- #16031
- #16047
- #16129
- #16132
- #16138

codex-rs/core/src/mcp_connection_manager.rs

@@ -94,7 +94,7 @@ const MCP_TOOL_NAME_DELIMITER: &str = "__";
 const MAX_TOOL_NAME_LENGTH: usize = 64;
 
 /// Default timeout for initializing MCP server & initially listing tools.
-pub const DEFAULT_STARTUP_TIMEOUT: Duration = Duration::from_secs(10);
+pub const DEFAULT_STARTUP_TIMEOUT: Duration = Duration::from_secs(30);
 
 /// Default timeout for individual tool calls.
 const DEFAULT_TOOL_TIMEOUT: Duration = Duration::from_secs(120);

codex-rs/core/src/mcp_connection_manager_tests.rs

@@ -612,7 +612,7 @@ fn mcp_init_error_display_includes_startup_timeout_hint() {
     let display = mcp_init_error_display(server_name, /*entry*/ None, &err);
 
     assert_eq!(
-        "MCP client for `slow` timed out after 10 seconds. Add or adjust `startup_timeout_sec` in your config.toml:\n[mcp_servers.slow]\nstartup_timeout_sec = XX",
+        "MCP client for `slow` timed out after 30 seconds. Add or adjust `startup_timeout_sec` in your config.toml:\n[mcp_servers.slow]\nstartup_timeout_sec = XX",
         display
     );
 }

codex-rs/core/src/tools/spec_tests.rs

@@ -16,14 +16,27 @@ use codex_tools::ConfiguredToolSpec;
 use codex_tools::FreeformTool;
 use codex_tools::ResponsesApiWebSearchFilters;
 use codex_tools::ResponsesApiWebSearchUserLocation;
+use codex_tools::SpawnAgentToolOptions;
 use codex_tools::ViewImageToolOptions;
+use codex_tools::WaitAgentTimeoutOptions;
+use codex_tools::create_close_agent_tool_v1;
+use codex_tools::create_close_agent_tool_v2;
 use codex_tools::create_exec_command_tool;
 use codex_tools::create_request_permissions_tool;
+use codex_tools::create_request_user_input_tool;
+use codex_tools::create_resume_agent_tool;
+use codex_tools::create_send_input_tool_v1;
+use codex_tools::create_send_message_tool;
+use codex_tools::create_spawn_agent_tool_v1;
+use codex_tools::create_spawn_agent_tool_v2;
 use codex_tools::create_view_image_tool;
+use codex_tools::create_wait_agent_tool_v1;
+use codex_tools::create_wait_agent_tool_v2;
 use codex_tools::create_write_stdin_tool;
 use codex_tools::mcp_tool_to_deferred_responses_api_tool;
 use codex_utils_absolute_path::AbsolutePathBuf;
 use pretty_assertions::assert_eq;
+use serde_json::json;
 use std::path::PathBuf;
 
 use super::*;
@@ -153,6 +166,27 @@ fn shell_tool_name(config: &ToolsConfig) -> Option<&'static str> {
     }
 }
 
+fn request_user_input_tool_spec(default_mode_request_user_input: bool) -> ToolSpec {
+    create_request_user_input_tool(request_user_input_tool_description(
+        default_mode_request_user_input,
+    ))
+}
+
+fn spawn_agent_tool_options(config: &ToolsConfig) -> SpawnAgentToolOptions<'_> {
+    SpawnAgentToolOptions {
+        available_models: &config.available_models,
+        agent_type_description: crate::agent::role::spawn_tool_spec::build(&config.agent_roles),
+    }
+}
+
+fn wait_agent_timeout_options() -> WaitAgentTimeoutOptions {
+    WaitAgentTimeoutOptions {
+        default_timeout_ms: DEFAULT_WAIT_TIMEOUT_MS,
+        min_timeout_ms: MIN_WAIT_TIMEOUT_MS,
+        max_timeout_ms: MAX_WAIT_TIMEOUT_MS,
+    }
+}
+
 fn find_tool<'a>(tools: &'a [ConfiguredToolSpec], expected_name: &str) -> &'a ConfiguredToolSpec {
     tools
         .iter()
@@ -307,7 +341,7 @@ fn test_full_toolset_specs_for_gpt5_codex_unified_exec_web_search() {
         }),
         create_write_stdin_tool(),
         PLAN_TOOL.clone(),
-        create_request_user_input_tool(CollaborationModesConfig::default()),
+        request_user_input_tool_spec(/*default_mode_request_user_input*/ false),
         create_apply_patch_freeform_tool(),
         ToolSpec::WebSearch {
             external_web_access: Some(true),
@@ -324,16 +358,16 @@ fn test_full_toolset_specs_for_gpt5_codex_unified_exec_web_search() {
     }
     let collab_specs = if config.multi_agent_v2 {
         vec![
-            create_spawn_agent_tool_v2(&config),
+            create_spawn_agent_tool_v2(spawn_agent_tool_options(&config)),
             create_send_message_tool(),
-            create_wait_agent_tool_v2(),
+            create_wait_agent_tool_v2(wait_agent_timeout_options()),
             create_close_agent_tool_v2(),
         ]
     } else {
         vec![
-            create_spawn_agent_tool_v1(&config),
+            create_spawn_agent_tool_v1(spawn_agent_tool_options(&config)),
             create_send_input_tool_v1(),
-            create_wait_agent_tool_v1(),
+            create_wait_agent_tool_v1(wait_agent_timeout_options()),
             create_close_agent_tool_v1(),
         ]
     };
@@ -734,7 +768,7 @@ fn request_user_input_description_reflects_default_mode_feature_flag() {
     let request_user_input_tool = find_tool(&tools, "request_user_input");
     assert_eq!(
         request_user_input_tool.spec,
-        create_request_user_input_tool(CollaborationModesConfig::default())
+        request_user_input_tool_spec(/*default_mode_request_user_input*/ false)
     );
 
     features.enable(Feature::DefaultModeRequestUserInput);
@@ -758,9 +792,7 @@ fn request_user_input_description_reflects_default_mode_feature_flag() {
     let request_user_input_tool = find_tool(&tools, "request_user_input");
     assert_eq!(
         request_user_input_tool.spec,
-        create_request_user_input_tool(CollaborationModesConfig {
-            default_mode_request_user_input: true,
-        })
+        request_user_input_tool_spec(/*default_mode_request_user_input*/ true)
     );
 }
 

codex-rs/tools/README.md

@@ -23,6 +23,8 @@ schema and Responses API tool primitives that no longer need to live in
 - `ResponsesApiNamespaceTool`
 - code-mode `ToolSpec` adapters
 - local host tool spec builders for shell/exec/request-permissions/view-image
+- collaboration and agent-job `ToolSpec` builders for spawn/send/wait/close,
+  `request_user_input`, and CSV fanout/reporting
 - `parse_tool_input_schema()`
 - `parse_dynamic_tool()`
 - `parse_mcp_tool()`

codex-rs/tools/src/agent_job_tool.rs

@@ -0,0 +1,141 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use std::collections::BTreeMap;
+
+pub fn create_spawn_agents_on_csv_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "csv_path".to_string(),
+            JsonSchema::String {
+                description: Some("Path to the CSV file containing input rows.".to_string()),
+            },
+        ),
+        (
+            "instruction".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Instruction template to apply to each CSV row. Use {column_name} placeholders to inject values from the row."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "id_column".to_string(),
+            JsonSchema::String {
+                description: Some("Optional column name to use as stable item id.".to_string()),
+            },
+        ),
+        (
+            "output_csv_path".to_string(),
+            JsonSchema::String {
+                description: Some("Optional output CSV path for exported results.".to_string()),
+            },
+        ),
+        (
+            "max_concurrency".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum concurrent workers for this job. Defaults to 16 and is capped by config."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "max_workers".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Alias for max_concurrency. Set to 1 to run sequentially.".to_string(),
+                ),
+            },
+        ),
+        (
+            "max_runtime_seconds".to_string(),
+            JsonSchema::Number {
+                description: Some(
+                    "Maximum runtime per worker before it is failed. Defaults to 1800 seconds."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "output_schema".to_string(),
+            JsonSchema::Object {
+                properties: BTreeMap::new(),
+                required: None,
+                additional_properties: None,
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "spawn_agents_on_csv".to_string(),
+        description: "Process a CSV by spawning one worker sub-agent per row. The instruction string is a template where `{column}` placeholders are replaced with row values. Each worker must call `report_agent_job_result` with a JSON object (matching `output_schema` when provided); missing reports are treated as failures. This call blocks until all rows finish and automatically exports results to `output_csv_path` (or a default path)."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["csv_path".to_string(), "instruction".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+pub fn create_report_agent_job_result_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "job_id".to_string(),
+            JsonSchema::String {
+                description: Some("Identifier of the job.".to_string()),
+            },
+        ),
+        (
+            "item_id".to_string(),
+            JsonSchema::String {
+                description: Some("Identifier of the job item.".to_string()),
+            },
+        ),
+        (
+            "result".to_string(),
+            JsonSchema::Object {
+                properties: BTreeMap::new(),
+                required: None,
+                additional_properties: None,
+            },
+        ),
+        (
+            "stop".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "Optional. When true, cancels the remaining job items after this result is recorded."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "report_agent_job_result".to_string(),
+        description:
+            "Worker-only tool to report a result for an agent job item. Main agents should not call this."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec![
+                "job_id".to_string(),
+                "item_id".to_string(),
+                "result".to_string(),
+            ]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "agent_job_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/agent_job_tool_tests.rs

@@ -0,0 +1,140 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn spawn_agents_on_csv_tool_requires_csv_and_instruction() {
+    assert_eq!(
+        create_spawn_agents_on_csv_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "spawn_agents_on_csv".to_string(),
+            description: "Process a CSV by spawning one worker sub-agent per row. The instruction string is a template where `{column}` placeholders are replaced with row values. Each worker must call `report_agent_job_result` with a JSON object (matching `output_schema` when provided); missing reports are treated as failures. This call blocks until all rows finish and automatically exports results to `output_csv_path` (or a default path)."
+                .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "csv_path".to_string(),
+                        JsonSchema::String {
+                            description: Some("Path to the CSV file containing input rows.".to_string()),
+                        },
+                    ),
+                    (
+                        "instruction".to_string(),
+                        JsonSchema::String {
+                            description: Some(
+                                "Instruction template to apply to each CSV row. Use {column_name} placeholders to inject values from the row."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "id_column".to_string(),
+                        JsonSchema::String {
+                            description: Some("Optional column name to use as stable item id.".to_string()),
+                        },
+                    ),
+                    (
+                        "output_csv_path".to_string(),
+                        JsonSchema::String {
+                            description: Some("Optional output CSV path for exported results.".to_string()),
+                        },
+                    ),
+                    (
+                        "max_concurrency".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "Maximum concurrent workers for this job. Defaults to 16 and is capped by config."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "max_workers".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "Alias for max_concurrency. Set to 1 to run sequentially.".to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "max_runtime_seconds".to_string(),
+                        JsonSchema::Number {
+                            description: Some(
+                                "Maximum runtime per worker before it is failed. Defaults to 1800 seconds."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                    (
+                        "output_schema".to_string(),
+                        JsonSchema::Object {
+                            properties: BTreeMap::new(),
+                            required: None,
+                            additional_properties: None,
+                        },
+                    ),
+                ]),
+                required: Some(vec!["csv_path".to_string(), "instruction".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}
+
+#[test]
+fn report_agent_job_result_tool_requires_result_payload() {
+    assert_eq!(
+        create_report_agent_job_result_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "report_agent_job_result".to_string(),
+            description:
+                "Worker-only tool to report a result for an agent job item. Main agents should not call this."
+                    .to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([
+                    (
+                        "job_id".to_string(),
+                        JsonSchema::String {
+                            description: Some("Identifier of the job.".to_string()),
+                        },
+                    ),
+                    (
+                        "item_id".to_string(),
+                        JsonSchema::String {
+                            description: Some("Identifier of the job item.".to_string()),
+                        },
+                    ),
+                    (
+                        "result".to_string(),
+                        JsonSchema::Object {
+                            properties: BTreeMap::new(),
+                            required: None,
+                            additional_properties: None,
+                        },
+                    ),
+                    (
+                        "stop".to_string(),
+                        JsonSchema::Boolean {
+                            description: Some(
+                                "Optional. When true, cancels the remaining job items after this result is recorded."
+                                    .to_string(),
+                            ),
+                        },
+                    ),
+                ]),
+                required: Some(vec![
+                    "job_id".to_string(),
+                    "item_id".to_string(),
+                    "result".to_string(),
+                ]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}

codex-rs/tools/src/agent_tool.rs

@@ -0,0 +1,729 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use codex_protocol::openai_models::ModelPreset;
+use serde_json::Value;
+use serde_json::json;
+use std::collections::BTreeMap;
+
+#[derive(Debug, Clone)]
+pub struct SpawnAgentToolOptions<'a> {
+    pub available_models: &'a [ModelPreset],
+    pub agent_type_description: String,
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct WaitAgentTimeoutOptions {
+    pub default_timeout_ms: i64,
+    pub min_timeout_ms: i64,
+    pub max_timeout_ms: i64,
+}
+
+pub fn create_spawn_agent_tool_v1(options: SpawnAgentToolOptions<'_>) -> ToolSpec {
+    let available_models_description = spawn_agent_models_description(options.available_models);
+    let return_value_description =
+        "Returns the spawned agent id plus the user-facing nickname when available.";
+    let properties = spawn_agent_common_properties(&options.agent_type_description);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "spawn_agent".to_string(),
+        description: spawn_agent_tool_description(
+            &available_models_description,
+            return_value_description,
+        ),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(spawn_agent_output_schema_v1()),
+    })
+}
+
+pub fn create_spawn_agent_tool_v2(options: SpawnAgentToolOptions<'_>) -> ToolSpec {
+    let available_models_description = spawn_agent_models_description(options.available_models);
+    let return_value_description = "Returns the canonical task name for the spawned agent, plus the user-facing nickname when available.";
+    let mut properties = spawn_agent_common_properties(&options.agent_type_description);
+    properties.insert(
+        "task_name".to_string(),
+        JsonSchema::String {
+            description: Some(
+                "Task name for the new agent. Use lowercase letters, digits, and underscores."
+                    .to_string(),
+            ),
+        },
+    );
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "spawn_agent".to_string(),
+        description: spawn_agent_tool_description(
+            &available_models_description,
+            return_value_description,
+        ),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["task_name".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(spawn_agent_output_schema_v2()),
+    })
+}
+
+pub fn create_send_input_tool_v1() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "target".to_string(),
+            JsonSchema::String {
+                description: Some("Agent id to message (from spawn_agent).".to_string()),
+            },
+        ),
+        (
+            "message".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Legacy plain-text message to send to the agent. Use either message or items."
+                        .to_string(),
+                ),
+            },
+        ),
+        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "interrupt".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "When true, stop the agent's current task and handle this immediately. When false (default), queue this message."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "send_input".to_string(),
+        description: "Send a message to an existing agent. Use interrupt=true to redirect work immediately. You should reuse the agent by send_input if you believe your assigned task is highly dependent on the context of a previous task."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["target".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(send_input_output_schema()),
+    })
+}
+
+pub fn create_send_message_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "target".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Agent id or canonical task name to message (from spawn_agent).".to_string(),
+                ),
+            },
+        ),
+        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "interrupt".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "When true, stop the agent's current task and handle this immediately. When false (default), queue this message."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "send_message".to_string(),
+        description: "Add a message to an existing agent without triggering a new turn. Use interrupt=true to stop the current task first. In MultiAgentV2, this tool currently supports text content only."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["target".to_string(), "items".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(send_input_output_schema()),
+    })
+}
+
+pub fn create_assign_task_tool() -> ToolSpec {
+    let properties = BTreeMap::from([
+        (
+            "target".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Agent id or canonical task name to message (from spawn_agent).".to_string(),
+                ),
+            },
+        ),
+        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "interrupt".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "When true, stop the agent's current task and handle this immediately. When false (default), queue this message."
+                        .to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "assign_task".to_string(),
+        description: "Add a message to an existing agent and trigger a turn in the target. Use interrupt=true to redirect work immediately. In MultiAgentV2, this tool currently supports text content only."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["target".to_string(), "items".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(send_input_output_schema()),
+    })
+}
+
+pub fn create_resume_agent_tool() -> ToolSpec {
+    let properties = BTreeMap::from([(
+        "id".to_string(),
+        JsonSchema::String {
+            description: Some("Agent id to resume.".to_string()),
+        },
+    )]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "resume_agent".to_string(),
+        description:
+            "Resume a previously closed agent by id so it can receive send_input and wait_agent calls."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["id".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(resume_agent_output_schema()),
+    })
+}
+
+pub fn create_wait_agent_tool_v1(options: WaitAgentTimeoutOptions) -> ToolSpec {
+    ToolSpec::Function(ResponsesApiTool {
+        name: "wait_agent".to_string(),
+        description: "Wait for agents to reach a final status. Completed statuses may include the agent's final message. Returns empty status when timed out. Once the agent reaches a final status, a notification message will be received containing the same completed status."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: wait_agent_tool_parameters_v1(options),
+        output_schema: Some(wait_output_schema_v1()),
+    })
+}
+
+pub fn create_wait_agent_tool_v2(options: WaitAgentTimeoutOptions) -> ToolSpec {
+    ToolSpec::Function(ResponsesApiTool {
+        name: "wait_agent".to_string(),
+        description: "Wait for agents to reach a final status. Returns a brief wait summary instead of the agent's final content. Returns a timeout summary when no agent reaches a final status before the deadline."
+            .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: wait_agent_tool_parameters_v2(options),
+        output_schema: Some(wait_output_schema_v2()),
+    })
+}
+
+pub fn create_list_agents_tool() -> ToolSpec {
+    let properties = BTreeMap::from([(
+        "path_prefix".to_string(),
+        JsonSchema::String {
+            description: Some(
+                "Optional task-path prefix. Accepts the same relative or absolute task-path syntax as other MultiAgentV2 agent targets."
+                    .to_string(),
+            ),
+        },
+    )]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "list_agents".to_string(),
+        description:
+            "List live agents in the current root thread tree. Optionally filter by task-path prefix."
+                .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(list_agents_output_schema()),
+    })
+}
+
+pub fn create_close_agent_tool_v1() -> ToolSpec {
+    let properties = BTreeMap::from([(
+        "target".to_string(),
+        JsonSchema::String {
+            description: Some("Agent id to close (from spawn_agent).".to_string()),
+        },
+    )]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "close_agent".to_string(),
+        description: "Close an agent and any open descendants when they are no longer needed, and return the target agent's previous status before shutdown was requested. Don't keep agents open for too long if they are not needed anymore.".to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["target".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(close_agent_output_schema()),
+    })
+}
+
+pub fn create_close_agent_tool_v2() -> ToolSpec {
+    let properties = BTreeMap::from([(
+        "target".to_string(),
+        JsonSchema::String {
+            description: Some(
+                "Agent id or canonical task name to close (from spawn_agent).".to_string(),
+            ),
+        },
+    )]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "close_agent".to_string(),
+        description: "Close an agent and any open descendants when they are no longer needed, and return the target agent's previous status before shutdown was requested. Don't keep agents open for too long if they are not needed anymore.".to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["target".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: Some(close_agent_output_schema()),
+    })
+}
+
+fn agent_status_output_schema() -> Value {
+    json!({
+        "oneOf": [
+            {
+                "type": "string",
+                "enum": ["pending_init", "running", "shutdown", "not_found"]
+            },
+            {
+                "type": "object",
+                "properties": {
+                    "completed": {
+                        "type": ["string", "null"]
+                    }
+                },
+                "required": ["completed"],
+                "additionalProperties": false
+            },
+            {
+                "type": "object",
+                "properties": {
+                    "errored": {
+                        "type": "string"
+                    }
+                },
+                "required": ["errored"],
+                "additionalProperties": false
+            }
+        ]
+    })
+}
+
+fn spawn_agent_output_schema_v1() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "agent_id": {
+                "type": "string",
+                "description": "Thread identifier for the spawned agent."
+            },
+            "nickname": {
+                "type": ["string", "null"],
+                "description": "User-facing nickname for the spawned agent when available."
+            }
+        },
+        "required": ["agent_id", "nickname"],
+        "additionalProperties": false
+    })
+}
+
+fn spawn_agent_output_schema_v2() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "agent_id": {
+                "type": ["string", "null"],
+                "description": "Legacy thread identifier for the spawned agent."
+            },
+            "task_name": {
+                "type": "string",
+                "description": "Canonical task name for the spawned agent."
+            },
+            "nickname": {
+                "type": ["string", "null"],
+                "description": "User-facing nickname for the spawned agent when available."
+            }
+        },
+        "required": ["agent_id", "task_name", "nickname"],
+        "additionalProperties": false
+    })
+}
+
+fn send_input_output_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "submission_id": {
+                "type": "string",
+                "description": "Identifier for the queued input submission."
+            }
+        },
+        "required": ["submission_id"],
+        "additionalProperties": false
+    })
+}
+
+fn list_agents_output_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "agents": {
+                "type": "array",
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "agent_name": {
+                            "type": "string",
+                            "description": "Canonical task name for the agent when available, otherwise the agent id."
+                        },
+                        "agent_status": {
+                            "description": "Last known status of the agent.",
+                            "allOf": [agent_status_output_schema()]
+                        },
+                        "last_task_message": {
+                            "type": ["string", "null"],
+                            "description": "Most recent user or inter-agent instruction received by the agent, when available."
+                        }
+                    },
+                    "required": ["agent_name", "agent_status", "last_task_message"],
+                    "additionalProperties": false
+                },
+                "description": "Live agents visible in the current root thread tree."
+            }
+        },
+        "required": ["agents"],
+        "additionalProperties": false
+    })
+}
+
+fn resume_agent_output_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "status": agent_status_output_schema()
+        },
+        "required": ["status"],
+        "additionalProperties": false
+    })
+}
+
+fn wait_output_schema_v1() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "status": {
+                "type": "object",
+                "description": "Final statuses keyed by agent id.",
+                "additionalProperties": agent_status_output_schema()
+            },
+            "timed_out": {
+                "type": "boolean",
+                "description": "Whether the wait call returned due to timeout before any agent reached a final status."
+            }
+        },
+        "required": ["status", "timed_out"],
+        "additionalProperties": false
+    })
+}
+
+fn wait_output_schema_v2() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "message": {
+                "type": "string",
+                "description": "Brief wait summary without the agent's final content."
+            },
+            "timed_out": {
+                "type": "boolean",
+                "description": "Whether the wait call returned due to timeout before any agent reached a final status."
+            }
+        },
+        "required": ["message", "timed_out"],
+        "additionalProperties": false
+    })
+}
+
+fn close_agent_output_schema() -> Value {
+    json!({
+        "type": "object",
+        "properties": {
+            "previous_status": {
+                "description": "The agent status observed before shutdown was requested.",
+                "allOf": [agent_status_output_schema()]
+            }
+        },
+        "required": ["previous_status"],
+        "additionalProperties": false
+    })
+}
+
+fn create_collab_input_items_schema() -> JsonSchema {
+    let properties = BTreeMap::from([
+        (
+            "type".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Input item type: text, image, local_image, skill, or mention.".to_string(),
+                ),
+            },
+        ),
+        (
+            "text".to_string(),
+            JsonSchema::String {
+                description: Some("Text content when type is text.".to_string()),
+            },
+        ),
+        (
+            "image_url".to_string(),
+            JsonSchema::String {
+                description: Some("Image URL when type is image.".to_string()),
+            },
+        ),
+        (
+            "path".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Path when type is local_image/skill, or structured mention target such as app://<connector-id> or plugin://<plugin-name>@<marketplace-name> when type is mention."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "name".to_string(),
+            JsonSchema::String {
+                description: Some("Display name when type is skill or mention.".to_string()),
+            },
+        ),
+    ]);
+
+    JsonSchema::Array {
+        items: Box::new(JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        }),
+        description: Some(
+            "Structured input items. Use this to pass explicit mentions (for example app:// connector paths)."
+                .to_string(),
+        ),
+    }
+}
+
+fn spawn_agent_common_properties(agent_type_description: &str) -> BTreeMap<String, JsonSchema> {
+    BTreeMap::from([
+        (
+            "message".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Initial plain-text task for the new agent. Use either message or items."
+                        .to_string(),
+                ),
+            },
+        ),
+        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "agent_type".to_string(),
+            JsonSchema::String {
+                description: Some(agent_type_description.to_string()),
+            },
+        ),
+        (
+            "fork_context".to_string(),
+            JsonSchema::Boolean {
+                description: Some(
+                    "When true, fork the current thread history into the new agent before sending the initial prompt. This must be used when you want the new agent to have exactly the same context as you."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "model".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional model override for the new agent. Replaces the inherited model."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "reasoning_effort".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Optional reasoning effort override for the new agent. Replaces the inherited reasoning effort."
+                        .to_string(),
+                ),
+            },
+        ),
+    ])
+}
+
+fn spawn_agent_tool_description(
+    available_models_description: &str,
+    return_value_description: &str,
+) -> String {
+    format!(
+        r#"
+        Only use `spawn_agent` if and only if the user explicitly asks for sub-agents, delegation, or parallel agent work.
+        Requests for depth, thoroughness, research, investigation, or detailed codebase analysis do not count as permission to spawn.
+        Agent-role guidance below only helps choose which agent to use after spawning is already authorized; it never authorizes spawning by itself.
+        Spawn a sub-agent for a well-scoped task. {return_value_description} This spawn_agent tool provides you access to smaller but more efficient sub-agents. A mini model can solve many tasks faster than the main model. You should follow the rules and guidelines below to use this tool.
+
+{available_models_description}
+### When to delegate vs. do the subtask yourself
+- First, quickly analyze the overall user task and form a succinct high-level plan. Identify which tasks are immediate blockers on the critical path, and which tasks are sidecar tasks that are needed but can run in parallel without blocking the next local step. As part of that plan, explicitly decide what immediate task you should do locally right now. Do this planning step before delegating to agents so you do not hand off the immediate blocking task to a submodel and then waste time waiting on it.
+- Use the smaller subagent when a subtask is easy enough for it to handle and can run in parallel with your local work. Prefer delegating concrete, bounded sidecar tasks that materially advance the main task without blocking your immediate next local step.
+- Do not delegate urgent blocking work when your immediate next step depends on that result. If the very next action is blocked on that task, the main rollout should usually do it locally to keep the critical path moving.
+- Keep work local when the subtask is too difficult to delegate well and when it is tightly coupled, urgent, or likely to block your immediate next step.
+
+### Designing delegated subtasks
+- Subtasks must be concrete, well-defined, and self-contained.
+- Delegated subtasks must materially advance the main task.
+- Do not duplicate work between the main rollout and delegated subtasks.
+- Avoid issuing multiple delegate calls on the same unresolved thread unless the new delegated task is genuinely different and necessary.
+- Narrow the delegated ask to the concrete output you need next.
+- For coding tasks, prefer delegating concrete code-change worker subtasks over read-only explorer analysis when the subagent can make a bounded patch in a clear write scope.
+- When delegating coding work, instruct the submodel to edit files directly in its forked workspace and list the file paths it changed in the final answer.
+- For code-edit subtasks, decompose work so each delegated task has a disjoint write set.
+
+### After you delegate
+- Call wait_agent very sparingly. Only call wait_agent when you need the result immediately for the next critical-path step and you are blocked until it returns.
+- Do not redo delegated subagent tasks yourself; focus on integrating results or tackling non-overlapping work.
+- While the subagent is running in the background, do meaningful non-overlapping work immediately.
+- Do not repeatedly wait by reflex.
+- When a delegated coding task returns, quickly review the uploaded changes, then integrate or refine them.
+
+### Parallel delegation patterns
+- Run multiple independent information-seeking subtasks in parallel when you have distinct questions that can be answered independently.
+- Split implementation into disjoint codebase slices and spawn multiple agents for them in parallel when the write scopes do not overlap.
+- Delegate verification only when it can run in parallel with ongoing implementation and is likely to catch a concrete risk before final integration.
+- The key is to find opportunities to spawn multiple independent subtasks in parallel within the same round, while ensuring each subtask is well-defined, self-contained, and materially advances the main task."#
+    )
+}
+
+fn spawn_agent_models_description(models: &[ModelPreset]) -> String {
+    let visible_models: Vec<&ModelPreset> =
+        models.iter().filter(|model| model.show_in_picker).collect();
+    if visible_models.is_empty() {
+        return "No picker-visible models are currently loaded.".to_string();
+    }
+
+    visible_models
+        .into_iter()
+        .map(|model| {
+            let efforts = model
+                .supported_reasoning_efforts
+                .iter()
+                .map(|preset| format!("{} ({})", preset.effort, preset.description))
+                .collect::<Vec<_>>()
+                .join(", ");
+            format!(
+                "- {} (`{}`): {} Default reasoning effort: {}. Supported reasoning efforts: {}.",
+                model.display_name,
+                model.model,
+                model.description,
+                model.default_reasoning_effort,
+                efforts
+            )
+        })
+        .collect::<Vec<_>>()
+        .join("\n")
+}
+
+fn wait_agent_tool_parameters_v1(options: WaitAgentTimeoutOptions) -> JsonSchema {
+    let properties = BTreeMap::from([
+        (
+            "targets".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some(
+                    "Agent ids to wait on. Pass multiple ids to wait for whichever finishes first."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(format!(
+                    "Optional timeout in milliseconds. Defaults to {}, min {}, max {}. Prefer longer waits (minutes) to avoid busy polling.",
+                    options.default_timeout_ms, options.min_timeout_ms, options.max_timeout_ms,
+                )),
+            },
+        ),
+    ]);
+
+    JsonSchema::Object {
+        properties,
+        required: Some(vec!["targets".to_string()]),
+        additional_properties: Some(false.into()),
+    }
+}
+
+fn wait_agent_tool_parameters_v2(options: WaitAgentTimeoutOptions) -> JsonSchema {
+    let properties = BTreeMap::from([
+        (
+            "targets".to_string(),
+            JsonSchema::Array {
+                items: Box::new(JsonSchema::String { description: None }),
+                description: Some(
+                    "Agent ids or canonical task names to wait on. Pass multiple targets to wait for whichever finishes first."
+                        .to_string(),
+                ),
+            },
+        ),
+        (
+            "timeout_ms".to_string(),
+            JsonSchema::Number {
+                description: Some(format!(
+                    "Optional timeout in milliseconds. Defaults to {}, min {}, max {}. Prefer longer waits (minutes) to avoid busy polling.",
+                    options.default_timeout_ms, options.min_timeout_ms, options.max_timeout_ms,
+                )),
+            },
+        ),
+    ]);
+
+    JsonSchema::Object {
+        properties,
+        required: Some(vec!["targets".to_string()]),
+        additional_properties: Some(false.into()),
+    }
+}
+
+#[cfg(test)]
+#[path = "agent_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/agent_tool_tests.rs

@@ -0,0 +1,152 @@
+use super::*;
+use codex_protocol::openai_models::ModelPreset;
+use codex_protocol::openai_models::ReasoningEffort;
+use codex_protocol::openai_models::ReasoningEffortPreset;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+fn model_preset(id: &str, show_in_picker: bool) -> ModelPreset {
+    ModelPreset {
+        id: id.to_string(),
+        model: format!("{id}-model"),
+        display_name: format!("{id} display"),
+        description: format!("{id} description"),
+        default_reasoning_effort: ReasoningEffort::Medium,
+        supported_reasoning_efforts: vec![ReasoningEffortPreset {
+            effort: ReasoningEffort::Medium,
+            description: "Balanced".to_string(),
+        }],
+        supports_personality: false,
+        is_default: false,
+        upgrade: None,
+        show_in_picker,
+        availability_nux: None,
+        supported_in_api: true,
+        input_modalities: Vec::new(),
+    }
+}
+
+#[test]
+fn spawn_agent_tool_v2_requires_task_name_and_lists_visible_models() {
+    let tool = create_spawn_agent_tool_v2(SpawnAgentToolOptions {
+        available_models: &[
+            model_preset("visible", /*show_in_picker*/ true),
+            model_preset("hidden", /*show_in_picker*/ false),
+        ],
+        agent_type_description: "role help".to_string(),
+    });
+
+    let ToolSpec::Function(ResponsesApiTool {
+        description,
+        parameters,
+        output_schema,
+        ..
+    }) = tool
+    else {
+        panic!("spawn_agent should be a function tool");
+    };
+    let JsonSchema::Object {
+        properties,
+        required,
+        ..
+    } = parameters
+    else {
+        panic!("spawn_agent should use object params");
+    };
+    assert!(description.contains("visible display (`visible-model`)"));
+    assert!(!description.contains("hidden display (`hidden-model`)"));
+    assert!(properties.contains_key("task_name"));
+    assert_eq!(
+        properties.get("agent_type"),
+        Some(&JsonSchema::String {
+            description: Some("role help".to_string()),
+        })
+    );
+    assert_eq!(required, Some(vec!["task_name".to_string()]));
+    assert_eq!(
+        output_schema.expect("spawn_agent output schema")["required"],
+        json!(["agent_id", "task_name", "nickname"])
+    );
+}
+
+#[test]
+fn send_message_tool_requires_items_and_uses_submission_output() {
+    let ToolSpec::Function(ResponsesApiTool {
+        parameters,
+        output_schema,
+        ..
+    }) = create_send_message_tool()
+    else {
+        panic!("send_message should be a function tool");
+    };
+    let JsonSchema::Object {
+        properties,
+        required,
+        ..
+    } = parameters
+    else {
+        panic!("send_message should use object params");
+    };
+    assert!(properties.contains_key("target"));
+    assert!(properties.contains_key("items"));
+    assert!(!properties.contains_key("message"));
+    assert_eq!(
+        required,
+        Some(vec!["target".to_string(), "items".to_string()])
+    );
+    assert_eq!(
+        output_schema.expect("send_message output schema")["required"],
+        json!(["submission_id"])
+    );
+}
+
+#[test]
+fn wait_agent_tool_v2_uses_task_targets_and_summary_output() {
+    let ToolSpec::Function(ResponsesApiTool {
+        parameters,
+        output_schema,
+        ..
+    }) = create_wait_agent_tool_v2(WaitAgentTimeoutOptions {
+        default_timeout_ms: 30_000,
+        min_timeout_ms: 10_000,
+        max_timeout_ms: 3_600_000,
+    })
+    else {
+        panic!("wait_agent should be a function tool");
+    };
+    let JsonSchema::Object { properties, .. } = parameters else {
+        panic!("wait_agent should use object params");
+    };
+    let Some(JsonSchema::Array {
+        description: Some(description),
+        ..
+    }) = properties.get("targets")
+    else {
+        panic!("wait_agent should define targets array");
+    };
+    assert!(description.contains("canonical task names"));
+    assert_eq!(
+        output_schema.expect("wait output schema")["properties"]["message"]["description"],
+        json!("Brief wait summary without the agent's final content.")
+    );
+}
+
+#[test]
+fn list_agents_tool_includes_path_prefix_and_agent_fields() {
+    let ToolSpec::Function(ResponsesApiTool {
+        parameters,
+        output_schema,
+        ..
+    }) = create_list_agents_tool()
+    else {
+        panic!("list_agents should be a function tool");
+    };
+    let JsonSchema::Object { properties, .. } = parameters else {
+        panic!("list_agents should use object params");
+    };
+    assert!(properties.contains_key("path_prefix"));
+    assert_eq!(
+        output_schema.expect("list_agents output schema")["properties"]["agents"]["items"]["required"],
+        json!(["agent_name", "agent_status", "last_task_message"])
+    );
+}

codex-rs/tools/src/lib.rs

@@ -1,16 +1,34 @@
 //! Shared tool definitions and Responses API tool primitives that can live
 //! outside `codex-core`.
 
+mod agent_job_tool;
+mod agent_tool;
 mod code_mode;
 mod dynamic_tool;
 mod json_schema;
 mod local_tool;
 mod mcp_tool;
+mod request_user_input_tool;
 mod responses_api;
 mod tool_definition;
 mod tool_spec;
 mod view_image;
 
+pub use agent_job_tool::create_report_agent_job_result_tool;
+pub use agent_job_tool::create_spawn_agents_on_csv_tool;
+pub use agent_tool::SpawnAgentToolOptions;
+pub use agent_tool::WaitAgentTimeoutOptions;
+pub use agent_tool::create_assign_task_tool;
+pub use agent_tool::create_close_agent_tool_v1;
+pub use agent_tool::create_close_agent_tool_v2;
+pub use agent_tool::create_list_agents_tool;
+pub use agent_tool::create_resume_agent_tool;
+pub use agent_tool::create_send_input_tool_v1;
+pub use agent_tool::create_send_message_tool;
+pub use agent_tool::create_spawn_agent_tool_v1;
+pub use agent_tool::create_spawn_agent_tool_v2;
+pub use agent_tool::create_wait_agent_tool_v1;
+pub use agent_tool::create_wait_agent_tool_v2;
 pub use code_mode::augment_tool_spec_for_code_mode;
 pub use code_mode::tool_spec_to_code_mode_tool_definition;
 pub use dynamic_tool::parse_dynamic_tool;
@@ -26,6 +44,7 @@ pub use local_tool::create_shell_tool;
 pub use local_tool::create_write_stdin_tool;
 pub use mcp_tool::mcp_call_tool_result_output_schema;
 pub use mcp_tool::parse_mcp_tool;
+pub use request_user_input_tool::create_request_user_input_tool;
 pub use responses_api::FreeformTool;
 pub use responses_api::FreeformToolFormat;
 pub use responses_api::ResponsesApiNamespace;

codex-rs/tools/src/request_user_input_tool.rs

@@ -0,0 +1,94 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use std::collections::BTreeMap;
+
+pub fn create_request_user_input_tool(description: String) -> ToolSpec {
+    let option_props = BTreeMap::from([
+        (
+            "label".to_string(),
+            JsonSchema::String {
+                description: Some("User-facing label (1-5 words).".to_string()),
+            },
+        ),
+        (
+            "description".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "One short sentence explaining impact/tradeoff if selected.".to_string(),
+                ),
+            },
+        ),
+    ]);
+
+    let options_schema = JsonSchema::Array {
+        description: Some(
+            "Provide 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with \"(Recommended)\". Do not include an \"Other\" option in this list; the client will add a free-form \"Other\" option automatically."
+                .to_string(),
+        ),
+        items: Box::new(JsonSchema::Object {
+            properties: option_props,
+            required: Some(vec!["label".to_string(), "description".to_string()]),
+            additional_properties: Some(false.into()),
+        }),
+    };
+
+    let question_props = BTreeMap::from([
+        (
+            "id".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Stable identifier for mapping answers (snake_case).".to_string(),
+                ),
+            },
+        ),
+        (
+            "header".to_string(),
+            JsonSchema::String {
+                description: Some(
+                    "Short header label shown in the UI (12 or fewer chars).".to_string(),
+                ),
+            },
+        ),
+        (
+            "question".to_string(),
+            JsonSchema::String {
+                description: Some("Single-sentence prompt shown to the user.".to_string()),
+            },
+        ),
+        ("options".to_string(), options_schema),
+    ]);
+
+    let questions_schema = JsonSchema::Array {
+        description: Some("Questions to show the user. Prefer 1 and do not exceed 3".to_string()),
+        items: Box::new(JsonSchema::Object {
+            properties: question_props,
+            required: Some(vec![
+                "id".to_string(),
+                "header".to_string(),
+                "question".to_string(),
+                "options".to_string(),
+            ]),
+            additional_properties: Some(false.into()),
+        }),
+    };
+
+    let properties = BTreeMap::from([("questions".to_string(), questions_schema)]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "request_user_input".to_string(),
+        description,
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["questions".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "request_user_input_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/request_user_input_tool_tests.rs

@@ -0,0 +1,102 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn request_user_input_tool_includes_questions_schema() {
+    assert_eq!(
+        create_request_user_input_tool("Ask the user to choose.".to_string()),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "request_user_input".to_string(),
+            description: "Ask the user to choose.".to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([(
+                    "questions".to_string(),
+                    JsonSchema::Array {
+                        description: Some(
+                            "Questions to show the user. Prefer 1 and do not exceed 3".to_string(),
+                        ),
+                        items: Box::new(JsonSchema::Object {
+                            properties: BTreeMap::from([
+                                (
+                                    "header".to_string(),
+                                    JsonSchema::String {
+                                        description: Some(
+                                            "Short header label shown in the UI (12 or fewer chars)."
+                                                .to_string(),
+                                        ),
+                                    },
+                                ),
+                                (
+                                    "id".to_string(),
+                                    JsonSchema::String {
+                                        description: Some(
+                                            "Stable identifier for mapping answers (snake_case)."
+                                                .to_string(),
+                                        ),
+                                    },
+                                ),
+                                (
+                                    "options".to_string(),
+                                    JsonSchema::Array {
+                                        description: Some(
+                                            "Provide 2-3 mutually exclusive choices. Put the recommended option first and suffix its label with \"(Recommended)\". Do not include an \"Other\" option in this list; the client will add a free-form \"Other\" option automatically."
+                                                .to_string(),
+                                        ),
+                                        items: Box::new(JsonSchema::Object {
+                                            properties: BTreeMap::from([
+                                                (
+                                                    "description".to_string(),
+                                                    JsonSchema::String {
+                                                        description: Some(
+                                                            "One short sentence explaining impact/tradeoff if selected."
+                                                                .to_string(),
+                                                        ),
+                                                    },
+                                                ),
+                                                (
+                                                    "label".to_string(),
+                                                    JsonSchema::String {
+                                                        description: Some(
+                                                            "User-facing label (1-5 words)."
+                                                                .to_string(),
+                                                        ),
+                                                    },
+                                                ),
+                                            ]),
+                                            required: Some(vec![
+                                                "label".to_string(),
+                                                "description".to_string(),
+                                            ]),
+                                            additional_properties: Some(false.into()),
+                                        }),
+                                    },
+                                ),
+                                (
+                                    "question".to_string(),
+                                    JsonSchema::String {
+                                        description: Some(
+                                            "Single-sentence prompt shown to the user.".to_string(),
+                                        ),
+                                    },
+                                ),
+                            ]),
+                            required: Some(vec![
+                                "id".to_string(),
+                                "header".to_string(),
+                                "question".to_string(),
+                                "options".to_string(),
+                            ]),
+                            additional_properties: Some(false.into()),
+                        }),
+                    },
+                )]),
+                required: Some(vec!["questions".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}