Merge origin/main into etraut/alarm

codex-rs/tools/src/agent_tool.rs

@@ -66,7 +66,7 @@ pub fn create_spawn_agent_tool_v2(options: SpawnAgentToolOptions<'_>) -> ToolSpe
         defer_loading: None,
         parameters: JsonSchema::Object {
             properties,
-            required: Some(vec!["task_name".to_string(), "items".to_string()]),
+            required: Some(vec!["task_name".to_string(), "message".to_string()]),
             additional_properties: Some(false.into()),
         },
         output_schema: Some(spawn_agent_output_schema_v2()),
@@ -127,7 +127,12 @@ pub fn create_send_message_tool() -> ToolSpec {
                 ),
             },
         ),
-        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "message".to_string(),
+            JsonSchema::String {
+                description: Some("Message text to queue on the target agent.".to_string()),
+            },
+        ),
     ]);
 
     ToolSpec::Function(ResponsesApiTool {
@@ -138,14 +143,14 @@ pub fn create_send_message_tool() -> ToolSpec {
         defer_loading: None,
         parameters: JsonSchema::Object {
             properties,
-            required: Some(vec!["target".to_string(), "items".to_string()]),
+            required: Some(vec!["target".to_string(), "message".to_string()]),
             additional_properties: Some(false.into()),
         },
         output_schema: Some(send_input_output_schema()),
     })
 }
 
-pub fn create_assign_task_tool() -> ToolSpec {
+pub fn create_followup_task_tool() -> ToolSpec {
     let properties = BTreeMap::from([
         (
             "target".to_string(),
@@ -155,7 +160,12 @@ pub fn create_assign_task_tool() -> ToolSpec {
                 ),
             },
         ),
-        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "message".to_string(),
+            JsonSchema::String {
+                description: Some("Message text to send to the target agent.".to_string()),
+            },
+        ),
         (
             "interrupt".to_string(),
             JsonSchema::Boolean {
@@ -168,14 +178,14 @@ pub fn create_assign_task_tool() -> ToolSpec {
     ]);
 
     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."
+        name: "followup_task".to_string(),
+        description: "Add a message to an existing non-root 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()]),
+            required: Some(vec!["target".to_string(), "message".to_string()]),
             additional_properties: Some(false.into()),
         },
         output_schema: Some(send_input_output_schema()),
@@ -221,7 +231,7 @@ pub fn create_wait_agent_tool_v1(options: WaitAgentTimeoutOptions) -> ToolSpec {
 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."
+        description: "Wait for a mailbox update from any live agent, including queued messages and final-status notifications. Returns a brief wait summary instead of agent content, or a timeout summary if no mailbox update arrives before the deadline."
             .to_string(),
         strict: false,
         defer_loading: None,
@@ -308,7 +318,7 @@ fn agent_status_output_schema() -> Value {
         "oneOf": [
             {
                 "type": "string",
-                "enum": ["pending_init", "running", "shutdown", "not_found"]
+                "enum": ["pending_init", "running", "interrupted", "shutdown", "not_found"]
             },
             {
                 "type": "object",
@@ -585,7 +595,12 @@ fn spawn_agent_common_properties_v1(agent_type_description: &str) -> BTreeMap<St
 
 fn spawn_agent_common_properties_v2(agent_type_description: &str) -> BTreeMap<String, JsonSchema> {
     BTreeMap::from([
-        ("items".to_string(), create_collab_input_items_schema()),
+        (
+            "message".to_string(),
+            JsonSchema::String {
+                description: Some("Initial plain-text task for the new agent.".to_string()),
+            },
+        ),
         (
             "agent_type".to_string(),
             JsonSchema::String {

codex-rs/tools/src/agent_tool_tests.rs

@@ -56,9 +56,9 @@ fn spawn_agent_tool_v2_requires_task_name_and_lists_visible_models() {
     assert!(description.contains("visible display (`visible-model`)"));
     assert!(!description.contains("hidden display (`hidden-model`)"));
     assert!(properties.contains_key("task_name"));
-    assert!(properties.contains_key("items"));
+    assert!(properties.contains_key("message"));
     assert!(properties.contains_key("fork_turns"));
-    assert!(!properties.contains_key("message"));
+    assert!(!properties.contains_key("items"));
     assert!(!properties.contains_key("fork_context"));
     assert_eq!(
         properties.get("agent_type"),
@@ -68,7 +68,7 @@ fn spawn_agent_tool_v2_requires_task_name_and_lists_visible_models() {
     );
     assert_eq!(
         required,
-        Some(vec!["task_name".to_string(), "items".to_string()])
+        Some(vec!["task_name".to_string(), "message".to_string()])
     );
     assert_eq!(
         output_schema.expect("spawn_agent output schema")["required"],
@@ -95,7 +95,7 @@ fn spawn_agent_tool_v1_keeps_legacy_fork_context_field() {
 }
 
 #[test]
-fn send_message_tool_requires_items_and_uses_submission_output() {
+fn send_message_tool_requires_message_and_uses_submission_output() {
     let ToolSpec::Function(ResponsesApiTool {
         parameters,
         output_schema,
@@ -113,12 +113,12 @@ fn send_message_tool_requires_items_and_uses_submission_output() {
         panic!("send_message should use object params");
     };
     assert!(properties.contains_key("target"));
-    assert!(properties.contains_key("items"));
+    assert!(properties.contains_key("message"));
     assert!(!properties.contains_key("interrupt"));
-    assert!(!properties.contains_key("message"));
+    assert!(!properties.contains_key("items"));
     assert_eq!(
         required,
-        Some(vec!["target".to_string(), "items".to_string()])
+        Some(vec!["target".to_string(), "message".to_string()])
     );
     assert_eq!(
         output_schema.expect("send_message output schema")["required"],
@@ -126,6 +126,38 @@ fn send_message_tool_requires_items_and_uses_submission_output() {
     );
 }
 
+#[test]
+fn followup_task_tool_requires_message_and_uses_submission_output() {
+    let ToolSpec::Function(ResponsesApiTool {
+        parameters,
+        output_schema,
+        ..
+    }) = create_followup_task_tool()
+    else {
+        panic!("followup_task should be a function tool");
+    };
+    let JsonSchema::Object {
+        properties,
+        required,
+        ..
+    } = parameters
+    else {
+        panic!("followup_task should use object params");
+    };
+    assert!(properties.contains_key("target"));
+    assert!(properties.contains_key("message"));
+    assert!(properties.contains_key("interrupt"));
+    assert!(!properties.contains_key("items"));
+    assert_eq!(
+        required,
+        Some(vec!["target".to_string(), "message".to_string()])
+    );
+    assert_eq!(
+        output_schema.expect("followup_task output schema")["required"],
+        json!(["submission_id"])
+    );
+}
+
 #[test]
 fn wait_agent_tool_v2_uses_timeout_only_summary_output() {
     let ToolSpec::Function(ResponsesApiTool {
@@ -176,3 +208,23 @@ fn list_agents_tool_includes_path_prefix_and_agent_fields() {
         json!(["agent_name", "agent_status", "last_task_message"])
     );
 }
+
+#[test]
+fn list_agents_tool_status_schema_includes_interrupted() {
+    let ToolSpec::Function(ResponsesApiTool { output_schema, .. }) = create_list_agents_tool()
+    else {
+        panic!("list_agents should be a function tool");
+    };
+
+    assert_eq!(
+        output_schema.expect("list_agents output schema")["properties"]["agents"]["items"]["properties"]
+            ["agent_status"]["allOf"][0]["oneOf"][0]["enum"],
+        json!([
+            "pending_init",
+            "running",
+            "interrupted",
+            "shutdown",
+            "not_found"
+        ])
+    );
+}

codex-rs/tools/src/apply_patch_tool.rs

@@ -0,0 +1,126 @@
+use crate::FreeformTool;
+use crate::FreeformToolFormat;
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use serde::Deserialize;
+use serde::Serialize;
+use std::collections::BTreeMap;
+
+const APPLY_PATCH_LARK_GRAMMAR: &str = include_str!("tool_apply_patch.lark");
+
+const APPLY_PATCH_JSON_TOOL_DESCRIPTION: &str = r#"Use the `apply_patch` tool to edit files.
+Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+
+*** Begin Patch
+[ one or more file sections ]
+*** End Patch
+
+Within that envelope, you get a sequence of file operations.
+You MUST include a header to specify the action you are taking.
+Each operation starts with one of three headers:
+
+*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).
+*** Delete File: <path> - remove an existing file. Nothing follows.
+*** Update File: <path> - patch an existing file in place (optionally with a rename).
+
+May be immediately followed by *** Move to: <new path> if you want to rename the file.
+Then one or more “hunks”, each introduced by @@ (optionally followed by a hunk header).
+Within a hunk each line starts with:
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single `@@` statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	 def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+The full grammar definition is below:
+Patch := Begin { FileOp } End
+Begin := "*** Begin Patch" NEWLINE
+End := "*** End Patch" NEWLINE
+FileOp := AddFile | DeleteFile | UpdateFile
+AddFile := "*** Add File: " path NEWLINE { "+" line NEWLINE }
+DeleteFile := "*** Delete File: " path NEWLINE
+UpdateFile := "*** Update File: " path NEWLINE [ MoveTo ] { Hunk }
+MoveTo := "*** Move to: " newPath NEWLINE
+Hunk := "@@" [ header ] NEWLINE { HunkLine } [ "*** End of File" NEWLINE ]
+HunkLine := (" " | "-" | "+") text NEWLINE
+
+A full patch can combine several operations:
+
+*** Begin Patch
+*** Add File: hello.txt
++Hello world
+*** Update File: src/app.py
+*** Move to: src/main.py
+@@ def greet():
+-print("Hi")
++print("Hello, world!")
+*** Delete File: obsolete.txt
+*** End Patch
+
+It is important to remember:
+
+- You must include a header with your intended action (Add/Delete/Update)
+- You must prefix new lines with `+` even when creating a new file
+- File references can only be relative, NEVER ABSOLUTE.
+"#;
+
+/// TODO(dylan): deprecate once we get rid of json tool
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ApplyPatchToolArgs {
+    pub input: String,
+}
+
+/// Returns a custom tool that can be used to edit files. Well-suited for GPT-5 models
+/// https://platform.openai.com/docs/guides/function-calling#custom-tools
+pub fn create_apply_patch_freeform_tool() -> ToolSpec {
+    ToolSpec::Freeform(FreeformTool {
+        name: "apply_patch".to_string(),
+        description: "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.".to_string(),
+        format: FreeformToolFormat {
+            r#type: "grammar".to_string(),
+            syntax: "lark".to_string(),
+            definition: APPLY_PATCH_LARK_GRAMMAR.to_string(),
+        },
+    })
+}
+
+/// Returns a json tool that can be used to edit files. Should only be used with gpt-oss models
+pub fn create_apply_patch_json_tool() -> ToolSpec {
+    let properties = BTreeMap::from([(
+        "input".to_string(),
+        JsonSchema::String {
+            description: Some("The entire contents of the apply_patch command".to_string()),
+        },
+    )]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "apply_patch".to_string(),
+        description: APPLY_PATCH_JSON_TOOL_DESCRIPTION.to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["input".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}
+
+#[cfg(test)]
+#[path = "apply_patch_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/apply_patch_tool_tests.rs

@@ -0,0 +1,47 @@
+use super::*;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn create_apply_patch_freeform_tool_matches_expected_spec() {
+    assert_eq!(
+        create_apply_patch_freeform_tool(),
+        ToolSpec::Freeform(FreeformTool {
+            name: "apply_patch".to_string(),
+            description:
+                "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON."
+                    .to_string(),
+            format: FreeformToolFormat {
+                r#type: "grammar".to_string(),
+                syntax: "lark".to_string(),
+                definition: APPLY_PATCH_LARK_GRAMMAR.to_string(),
+            },
+        })
+    );
+}
+
+#[test]
+fn create_apply_patch_json_tool_matches_expected_spec() {
+    assert_eq!(
+        create_apply_patch_json_tool(),
+        ToolSpec::Function(ResponsesApiTool {
+            name: "apply_patch".to_string(),
+            description: APPLY_PATCH_JSON_TOOL_DESCRIPTION.to_string(),
+            strict: false,
+            defer_loading: None,
+            parameters: JsonSchema::Object {
+                properties: BTreeMap::from([(
+                    "input".to_string(),
+                    JsonSchema::String {
+                        description: Some(
+                            "The entire contents of the apply_patch command".to_string(),
+                        ),
+                    },
+                )]),
+                required: Some(vec!["input".to_string()]),
+                additional_properties: Some(false.into()),
+            },
+            output_schema: None,
+        })
+    );
+}

codex-rs/tools/src/code_mode.rs

@@ -37,6 +37,18 @@ pub fn tool_spec_to_code_mode_tool_definition(spec: &ToolSpec) -> Option<CodeMod
         .then(|| codex_code_mode::augment_tool_definition(definition))
 }
 
+pub fn collect_code_mode_tool_definitions<'a>(
+    specs: impl IntoIterator<Item = &'a ToolSpec>,
+) -> Vec<CodeModeToolDefinition> {
+    let mut tool_definitions = specs
+        .into_iter()
+        .filter_map(tool_spec_to_code_mode_tool_definition)
+        .collect::<Vec<_>>();
+    tool_definitions.sort_by(|left, right| left.name.cmp(&right.name));
+    tool_definitions.dedup_by(|left, right| left.name == right.name);
+    tool_definitions
+}
+
 pub fn create_wait_tool() -> ToolSpec {
     let properties = BTreeMap::from([
         (

codex-rs/tools/src/image_detail.rs

@@ -0,0 +1,25 @@
+use codex_features::Feature;
+use codex_features::Features;
+use codex_protocol::models::ImageDetail;
+use codex_protocol::openai_models::ModelInfo;
+
+pub fn can_request_original_image_detail(features: &Features, model_info: &ModelInfo) -> bool {
+    model_info.supports_image_detail_original && features.enabled(Feature::ImageDetailOriginal)
+}
+
+pub fn normalize_output_image_detail(
+    features: &Features,
+    model_info: &ModelInfo,
+    detail: Option<ImageDetail>,
+) -> Option<ImageDetail> {
+    match detail {
+        Some(ImageDetail::Original) if can_request_original_image_detail(features, model_info) => {
+            Some(ImageDetail::Original)
+        }
+        Some(ImageDetail::Original) | Some(_) | None => None,
+    }
+}
+
+#[cfg(test)]
+#[path = "image_detail_tests.rs"]
+mod tests;

codex-rs/tools/src/image_detail_tests.rs

@@ -0,0 +1,90 @@
+use super::*;
+use codex_features::Feature;
+use codex_features::Features;
+use codex_protocol::models::ImageDetail;
+use codex_protocol::openai_models::ModelInfo;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+fn model_info() -> ModelInfo {
+    serde_json::from_value(json!({
+        "slug": "test-model",
+        "display_name": "Test Model",
+        "description": null,
+        "supported_reasoning_levels": [],
+        "shell_type": "shell_command",
+        "visibility": "list",
+        "supported_in_api": true,
+        "priority": 1,
+        "availability_nux": null,
+        "upgrade": null,
+        "base_instructions": "base",
+        "model_messages": null,
+        "supports_reasoning_summaries": false,
+        "default_reasoning_summary": "auto",
+        "support_verbosity": false,
+        "default_verbosity": null,
+        "apply_patch_tool_type": null,
+        "truncation_policy": {
+            "mode": "bytes",
+            "limit": 10000
+        },
+        "supports_parallel_tool_calls": false,
+        "supports_image_detail_original": true,
+        "context_window": null,
+        "auto_compact_token_limit": null,
+        "effective_context_window_percent": 95,
+        "experimental_supported_tools": [],
+        "input_modalities": ["text", "image"],
+        "supports_search_tool": false
+    }))
+    .expect("deserialize test model")
+}
+
+#[test]
+fn image_detail_original_feature_enables_explicit_original_without_force() {
+    let model_info = model_info();
+    let mut features = Features::with_defaults();
+    features.enable(Feature::ImageDetailOriginal);
+
+    assert!(can_request_original_image_detail(&features, &model_info));
+    assert_eq!(
+        normalize_output_image_detail(&features, &model_info, Some(ImageDetail::Original)),
+        Some(ImageDetail::Original)
+    );
+    assert_eq!(
+        normalize_output_image_detail(&features, &model_info, /*detail*/ None),
+        None
+    );
+}
+
+#[test]
+fn explicit_original_is_dropped_without_feature_or_model_support() {
+    let mut model_info = model_info();
+    let features = Features::with_defaults();
+
+    assert_eq!(
+        normalize_output_image_detail(&features, &model_info, Some(ImageDetail::Original)),
+        None
+    );
+
+    let mut features = Features::with_defaults();
+    features.enable(Feature::ImageDetailOriginal);
+    model_info.supports_image_detail_original = false;
+    assert_eq!(
+        normalize_output_image_detail(&features, &model_info, Some(ImageDetail::Original)),
+        None
+    );
+}
+
+#[test]
+fn unsupported_non_original_detail_is_dropped() {
+    let model_info = model_info();
+    let mut features = Features::with_defaults();
+    features.enable(Feature::ImageDetailOriginal);
+
+    assert_eq!(
+        normalize_output_image_detail(&features, &model_info, Some(ImageDetail::Low)),
+        None
+    );
+}

codex-rs/tools/src/lib.rs

@@ -4,18 +4,25 @@
 mod agent_job_tool;
 mod agent_tool;
 mod alarm_tool;
+mod apply_patch_tool;
 mod code_mode;
 mod dynamic_tool;
+mod image_detail;
 mod js_repl_tool;
 mod json_schema;
 mod local_tool;
 mod mcp_resource_tool;
 mod mcp_tool;
+mod plan_tool;
 mod request_user_input_tool;
 mod responses_api;
+mod tool_config;
 mod tool_definition;
 mod tool_discovery;
+mod tool_registry_plan;
+mod tool_registry_plan_types;
 mod tool_spec;
+mod tool_suggest;
 mod utility_tool;
 mod view_image;
 
@@ -23,9 +30,9 @@ 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_followup_task_tool;
 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;
@@ -37,11 +44,17 @@ pub use agent_tool::create_wait_agent_tool_v2;
 pub use alarm_tool::create_alarm_create_tool;
 pub use alarm_tool::create_alarm_delete_tool;
 pub use alarm_tool::create_alarm_list_tool;
+pub use apply_patch_tool::ApplyPatchToolArgs;
+pub use apply_patch_tool::create_apply_patch_freeform_tool;
+pub use apply_patch_tool::create_apply_patch_json_tool;
 pub use code_mode::augment_tool_spec_for_code_mode;
+pub use code_mode::collect_code_mode_tool_definitions;
 pub use code_mode::create_code_mode_tool;
 pub use code_mode::create_wait_tool;
 pub use code_mode::tool_spec_to_code_mode_tool_definition;
 pub use dynamic_tool::parse_dynamic_tool;
+pub use image_detail::can_request_original_image_detail;
+pub use image_detail::normalize_output_image_detail;
 pub use js_repl_tool::create_js_repl_reset_tool;
 pub use js_repl_tool::create_js_repl_tool;
 pub use json_schema::AdditionalProperties;
@@ -54,12 +67,18 @@ pub use local_tool::create_request_permissions_tool;
 pub use local_tool::create_shell_command_tool;
 pub use local_tool::create_shell_tool;
 pub use local_tool::create_write_stdin_tool;
+pub use local_tool::request_permissions_tool_description;
 pub use mcp_resource_tool::create_list_mcp_resource_templates_tool;
 pub use mcp_resource_tool::create_list_mcp_resources_tool;
 pub use mcp_resource_tool::create_read_mcp_resource_tool;
 pub use mcp_tool::mcp_call_tool_result_output_schema;
 pub use mcp_tool::parse_mcp_tool;
+pub use plan_tool::create_update_plan_tool;
+pub use request_user_input_tool::REQUEST_USER_INPUT_TOOL_NAME;
 pub use request_user_input_tool::create_request_user_input_tool;
+pub use request_user_input_tool::normalize_request_user_input_args;
+pub use request_user_input_tool::request_user_input_tool_description;
+pub use request_user_input_tool::request_user_input_unavailable_message;
 pub use responses_api::FreeformTool;
 pub use responses_api::FreeformToolFormat;
 pub use responses_api::ResponsesApiNamespace;
@@ -70,21 +89,52 @@ pub use responses_api::dynamic_tool_to_responses_api_tool;
 pub use responses_api::mcp_tool_to_deferred_responses_api_tool;
 pub use responses_api::mcp_tool_to_responses_api_tool;
 pub use responses_api::tool_definition_to_responses_api_tool;
+pub use tool_config::ShellCommandBackendConfig;
+pub use tool_config::ToolUserShellType;
+pub use tool_config::ToolsConfig;
+pub use tool_config::ToolsConfigParams;
+pub use tool_config::UnifiedExecShellMode;
+pub use tool_config::ZshForkConfig;
 pub use tool_definition::ToolDefinition;
 pub use tool_discovery::DiscoverablePluginInfo;
 pub use tool_discovery::DiscoverableTool;
 pub use tool_discovery::DiscoverableToolAction;
 pub use tool_discovery::DiscoverableToolType;
+pub use tool_discovery::TOOL_SEARCH_DEFAULT_LIMIT;
+pub use tool_discovery::TOOL_SEARCH_TOOL_NAME;
+pub use tool_discovery::TOOL_SUGGEST_TOOL_NAME;
 pub use tool_discovery::ToolSearchAppInfo;
+pub use tool_discovery::ToolSearchAppSource;
+pub use tool_discovery::ToolSearchResultSource;
 pub use tool_discovery::ToolSuggestEntry;
+pub use tool_discovery::collect_tool_search_app_infos;
+pub use tool_discovery::collect_tool_search_output_tools;
+pub use tool_discovery::collect_tool_suggest_entries;
 pub use tool_discovery::create_tool_search_tool;
 pub use tool_discovery::create_tool_suggest_tool;
 pub use tool_discovery::filter_tool_suggest_discoverable_tools_for_client;
+pub use tool_registry_plan::build_tool_registry_plan;
+pub use tool_registry_plan_types::ToolHandlerKind;
+pub use tool_registry_plan_types::ToolHandlerSpec;
+pub use tool_registry_plan_types::ToolRegistryPlan;
+pub use tool_registry_plan_types::ToolRegistryPlanAppTool;
+pub use tool_registry_plan_types::ToolRegistryPlanParams;
 pub use tool_spec::ConfiguredToolSpec;
 pub use tool_spec::ResponsesApiWebSearchFilters;
 pub use tool_spec::ResponsesApiWebSearchUserLocation;
 pub use tool_spec::ToolSpec;
+pub use tool_spec::WebSearchToolOptions;
+pub use tool_spec::create_image_generation_tool;
+pub use tool_spec::create_local_shell_tool;
 pub use tool_spec::create_tools_json_for_responses_api;
+pub use tool_spec::create_web_search_tool;
+pub use tool_suggest::TOOL_SUGGEST_APPROVAL_KIND_VALUE;
+pub use tool_suggest::ToolSuggestArgs;
+pub use tool_suggest::ToolSuggestMeta;
+pub use tool_suggest::ToolSuggestResult;
+pub use tool_suggest::all_suggested_connectors_picked_up;
+pub use tool_suggest::build_tool_suggestion_elicitation_request;
+pub use tool_suggest::verified_connector_suggestion_completed;
 pub use utility_tool::create_list_dir_tool;
 pub use utility_tool::create_test_sync_tool;
 pub use view_image::ViewImageToolOptions;

codex-rs/tools/src/local_tool.rs

@@ -318,6 +318,11 @@ pub fn create_request_permissions_tool(description: String) -> ToolSpec {
     })
 }
 
+pub fn request_permissions_tool_description() -> String {
+    "Request additional filesystem or network permissions from the user and wait for the client to grant a subset of the requested permission profile. Granted permissions apply automatically to later shell-like commands in the current turn, or for the rest of the session if the client approves them at session scope."
+        .to_string()
+}
+
 fn unified_exec_output_schema() -> Value {
     json!({
         "type": "object",

codex-rs/tools/src/plan_tool.rs

@@ -0,0 +1,51 @@
+use crate::JsonSchema;
+use crate::ResponsesApiTool;
+use crate::ToolSpec;
+use std::collections::BTreeMap;
+
+pub fn create_update_plan_tool() -> ToolSpec {
+    let plan_item_properties = BTreeMap::from([
+        ("step".to_string(), JsonSchema::String { description: None }),
+        (
+            "status".to_string(),
+            JsonSchema::String {
+                description: Some("One of: pending, in_progress, completed".to_string()),
+            },
+        ),
+    ]);
+
+    let properties = BTreeMap::from([
+        (
+            "explanation".to_string(),
+            JsonSchema::String { description: None },
+        ),
+        (
+            "plan".to_string(),
+            JsonSchema::Array {
+                description: Some("The list of steps".to_string()),
+                items: Box::new(JsonSchema::Object {
+                    properties: plan_item_properties,
+                    required: Some(vec!["step".to_string(), "status".to_string()]),
+                    additional_properties: Some(false.into()),
+                }),
+            },
+        ),
+    ]);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "update_plan".to_string(),
+        description: r#"Updates the task plan.
+Provide an optional explanation and a list of plan items, each with a step and status.
+At most one step can be in_progress at a time.
+"#
+        .to_string(),
+        strict: false,
+        defer_loading: None,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["plan".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+        output_schema: None,
+    })
+}

codex-rs/tools/src/request_user_input_tool.rs

@@ -1,8 +1,13 @@
 use crate::JsonSchema;
 use crate::ResponsesApiTool;
 use crate::ToolSpec;
+use codex_protocol::config_types::ModeKind;
+use codex_protocol::config_types::TUI_VISIBLE_COLLABORATION_MODES;
+use codex_protocol::request_user_input::RequestUserInputArgs;
 use std::collections::BTreeMap;
 
+pub const REQUEST_USER_INPUT_TOOL_NAME: &str = "request_user_input";
+
 pub fn create_request_user_input_tool(description: String) -> ToolSpec {
     let option_props = BTreeMap::from([
         (
@@ -76,7 +81,7 @@ pub fn create_request_user_input_tool(description: String) -> ToolSpec {
     let properties = BTreeMap::from([("questions".to_string(), questions_schema)]);
 
     ToolSpec::Function(ResponsesApiTool {
-        name: "request_user_input".to_string(),
+        name: REQUEST_USER_INPUT_TOOL_NAME.to_string(),
         description,
         strict: false,
         defer_loading: None,
@@ -89,6 +94,65 @@ pub fn create_request_user_input_tool(description: String) -> ToolSpec {
     })
 }
 
+pub fn request_user_input_unavailable_message(
+    mode: ModeKind,
+    default_mode_request_user_input: bool,
+) -> Option<String> {
+    if request_user_input_is_available(mode, default_mode_request_user_input) {
+        None
+    } else {
+        let mode_name = mode.display_name();
+        Some(format!(
+            "request_user_input is unavailable in {mode_name} mode"
+        ))
+    }
+}
+
+pub fn normalize_request_user_input_args(
+    mut args: RequestUserInputArgs,
+) -> Result<RequestUserInputArgs, String> {
+    let missing_options = args
+        .questions
+        .iter()
+        .any(|question| question.options.as_ref().is_none_or(Vec::is_empty));
+    if missing_options {
+        return Err("request_user_input requires non-empty options for every question".to_string());
+    }
+
+    for question in &mut args.questions {
+        question.is_other = true;
+    }
+
+    Ok(args)
+}
+
+pub fn request_user_input_tool_description(default_mode_request_user_input: bool) -> String {
+    let allowed_modes = format_allowed_modes(default_mode_request_user_input);
+    format!(
+        "Request user input for one to three short questions and wait for the response. This tool is only available in {allowed_modes}."
+    )
+}
+
+fn request_user_input_is_available(mode: ModeKind, default_mode_request_user_input: bool) -> bool {
+    mode.allows_request_user_input()
+        || (default_mode_request_user_input && mode == ModeKind::Default)
+}
+
+fn format_allowed_modes(default_mode_request_user_input: bool) -> String {
+    let mode_names: Vec<&str> = TUI_VISIBLE_COLLABORATION_MODES
+        .into_iter()
+        .filter(|mode| request_user_input_is_available(*mode, default_mode_request_user_input))
+        .map(ModeKind::display_name)
+        .collect();
+
+    match mode_names.as_slice() {
+        [] => "no modes".to_string(),
+        [mode] => format!("{mode} mode"),
+        [first, second] => format!("{first} or {second} mode"),
+        [..] => format!("modes: {}", mode_names.join(",")),
+    }
+}
+
 #[cfg(test)]
 #[path = "request_user_input_tool_tests.rs"]
 mod tests;

codex-rs/tools/src/request_user_input_tool_tests.rs

@@ -1,4 +1,5 @@
 use super::*;
+use codex_protocol::config_types::ModeKind;
 use pretty_assertions::assert_eq;
 use std::collections::BTreeMap;
 
@@ -100,3 +101,54 @@ fn request_user_input_tool_includes_questions_schema() {
         })
     );
 }
+
+#[test]
+fn request_user_input_unavailable_messages_respect_default_mode_feature_flag() {
+    assert_eq!(
+        request_user_input_unavailable_message(
+            ModeKind::Plan,
+            /*default_mode_request_user_input*/ false
+        ),
+        None
+    );
+    assert_eq!(
+        request_user_input_unavailable_message(
+            ModeKind::Default,
+            /*default_mode_request_user_input*/ false
+        ),
+        Some("request_user_input is unavailable in Default mode".to_string())
+    );
+    assert_eq!(
+        request_user_input_unavailable_message(
+            ModeKind::Default,
+            /*default_mode_request_user_input*/ true
+        ),
+        None
+    );
+    assert_eq!(
+        request_user_input_unavailable_message(
+            ModeKind::Execute,
+            /*default_mode_request_user_input*/ false
+        ),
+        Some("request_user_input is unavailable in Execute mode".to_string())
+    );
+    assert_eq!(
+        request_user_input_unavailable_message(
+            ModeKind::PairProgramming,
+            /*default_mode_request_user_input*/ false
+        ),
+        Some("request_user_input is unavailable in Pair Programming mode".to_string())
+    );
+}
+
+#[test]
+fn request_user_input_tool_description_mentions_available_modes() {
+    assert_eq!(
+        request_user_input_tool_description(/*default_mode_request_user_input*/ false),
+        "Request user input for one to three short questions and wait for the response. This tool is only available in Plan mode.".to_string()
+    );
+    assert_eq!(
+        request_user_input_tool_description(/*default_mode_request_user_input*/ true),
+        "Request user input for one to three short questions and wait for the response. This tool is only available in Default or Plan mode.".to_string()
+    );
+}

codex-rs/tools/src/tool_apply_patch.lark

@@ -0,0 +1,19 @@
+start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+
+%import common.LF

codex-rs/tools/src/tool_config.rs

@@ -0,0 +1,297 @@
+use crate::can_request_original_image_detail;
+use codex_features::Feature;
+use codex_features::Features;
+use codex_protocol::config_types::WebSearchConfig;
+use codex_protocol::config_types::WebSearchMode;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::openai_models::ApplyPatchToolType;
+use codex_protocol::openai_models::ConfigShellToolType;
+use codex_protocol::openai_models::InputModality;
+use codex_protocol::openai_models::ModelInfo;
+use codex_protocol::openai_models::ModelPreset;
+use codex_protocol::openai_models::WebSearchToolType;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::SubAgentSource;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use std::path::PathBuf;
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub enum ShellCommandBackendConfig {
+    Classic,
+    ZshFork,
+}
+
+#[derive(Debug, Clone, Copy, Eq, PartialEq)]
+pub enum ToolUserShellType {
+    Zsh,
+    Bash,
+    PowerShell,
+    Sh,
+    Cmd,
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub enum UnifiedExecShellMode {
+    Direct,
+    ZshFork(ZshForkConfig),
+}
+
+#[derive(Debug, Clone, Eq, PartialEq)]
+pub struct ZshForkConfig {
+    pub shell_zsh_path: AbsolutePathBuf,
+    pub main_execve_wrapper_exe: AbsolutePathBuf,
+}
+
+impl UnifiedExecShellMode {
+    pub fn for_session(
+        shell_command_backend: ShellCommandBackendConfig,
+        user_shell_type: ToolUserShellType,
+        shell_zsh_path: Option<&PathBuf>,
+        main_execve_wrapper_exe: Option<&PathBuf>,
+    ) -> Self {
+        if cfg!(unix)
+            && shell_command_backend == ShellCommandBackendConfig::ZshFork
+            && matches!(user_shell_type, ToolUserShellType::Zsh)
+            && let (Some(shell_zsh_path), Some(main_execve_wrapper_exe)) =
+                (shell_zsh_path, main_execve_wrapper_exe)
+            && let (Ok(shell_zsh_path), Ok(main_execve_wrapper_exe)) = (
+                AbsolutePathBuf::try_from(shell_zsh_path.as_path()).inspect_err(|err| {
+                    tracing::warn!(
+                        "Failed to convert shell_zsh_path `{shell_zsh_path:?}`: {err:?}"
+                    )
+                }),
+                AbsolutePathBuf::try_from(main_execve_wrapper_exe.as_path()).inspect_err(
+                    |err| {
+                        tracing::warn!(
+                            "Failed to convert main_execve_wrapper_exe `{main_execve_wrapper_exe:?}`: {err:?}"
+                        )
+                    },
+                ),
+            )
+        {
+            Self::ZshFork(ZshForkConfig {
+                shell_zsh_path,
+                main_execve_wrapper_exe,
+            })
+        } else {
+            Self::Direct
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ToolsConfig {
+    pub available_models: Vec<ModelPreset>,
+    pub shell_type: ConfigShellToolType,
+    pub shell_command_backend: ShellCommandBackendConfig,
+    pub unified_exec_shell_mode: UnifiedExecShellMode,
+    pub allow_login_shell: bool,
+    pub apply_patch_tool_type: Option<ApplyPatchToolType>,
+    pub web_search_mode: Option<WebSearchMode>,
+    pub web_search_config: Option<WebSearchConfig>,
+    pub web_search_tool_type: WebSearchToolType,
+    pub image_gen_tool: bool,
+    pub search_tool: bool,
+    pub tool_suggest: bool,
+    pub exec_permission_approvals_enabled: bool,
+    pub request_permissions_tool_enabled: bool,
+    pub code_mode_enabled: bool,
+    pub code_mode_only_enabled: bool,
+    pub js_repl_enabled: bool,
+    pub js_repl_tools_only: bool,
+    pub can_request_original_image_detail: bool,
+    pub collab_tools: bool,
+    pub multi_agent_v2: bool,
+    pub request_user_input: bool,
+    pub alarm_scheduler: bool,
+    pub default_mode_request_user_input: bool,
+    pub experimental_supported_tools: Vec<String>,
+    pub agent_jobs_tools: bool,
+    pub agent_jobs_worker_tools: bool,
+    pub agent_type_description: String,
+}
+
+pub struct ToolsConfigParams<'a> {
+    pub model_info: &'a ModelInfo,
+    pub available_models: &'a [ModelPreset],
+    pub features: &'a Features,
+    pub web_search_mode: Option<WebSearchMode>,
+    pub session_source: SessionSource,
+    pub sandbox_policy: &'a SandboxPolicy,
+    pub windows_sandbox_level: WindowsSandboxLevel,
+}
+
+impl ToolsConfig {
+    pub fn new(params: &ToolsConfigParams<'_>) -> Self {
+        let ToolsConfigParams {
+            model_info,
+            available_models,
+            features,
+            web_search_mode,
+            session_source,
+            sandbox_policy,
+            windows_sandbox_level,
+        } = params;
+        let include_apply_patch_tool = features.enabled(Feature::ApplyPatchFreeform);
+        let include_code_mode = features.enabled(Feature::CodeMode);
+        let include_code_mode_only = include_code_mode && features.enabled(Feature::CodeModeOnly);
+        let include_js_repl = features.enabled(Feature::JsRepl);
+        let include_js_repl_tools_only =
+            include_js_repl && features.enabled(Feature::JsReplToolsOnly);
+        let include_collab_tools = features.enabled(Feature::Collab);
+        let include_multi_agent_v2 = features.enabled(Feature::MultiAgentV2);
+        let include_agent_jobs = features.enabled(Feature::SpawnCsv);
+        let include_request_user_input = !matches!(session_source, SessionSource::SubAgent(_));
+        let include_alarm_scheduler = features.enabled(Feature::AlarmScheduler);
+        let include_default_mode_request_user_input =
+            include_request_user_input && features.enabled(Feature::DefaultModeRequestUserInput);
+        let include_search_tool =
+            model_info.supports_search_tool && features.enabled(Feature::ToolSearch);
+        let include_tool_suggest = features.enabled(Feature::ToolSuggest)
+            && features.enabled(Feature::Apps)
+            && features.enabled(Feature::Plugins);
+        let include_original_image_detail = can_request_original_image_detail(features, model_info);
+        let include_image_gen_tool =
+            features.enabled(Feature::ImageGeneration) && supports_image_generation(model_info);
+        let exec_permission_approvals_enabled = features.enabled(Feature::ExecPermissionApprovals);
+        let request_permissions_tool_enabled = features.enabled(Feature::RequestPermissionsTool);
+        let shell_command_backend =
+            if features.enabled(Feature::ShellTool) && features.enabled(Feature::ShellZshFork) {
+                ShellCommandBackendConfig::ZshFork
+            } else {
+                ShellCommandBackendConfig::Classic
+            };
+        let unified_exec_allowed = unified_exec_allowed_in_environment(
+            cfg!(target_os = "windows"),
+            sandbox_policy,
+            *windows_sandbox_level,
+        );
+        let shell_type = if !features.enabled(Feature::ShellTool) {
+            ConfigShellToolType::Disabled
+        } else if features.enabled(Feature::ShellZshFork) {
+            ConfigShellToolType::ShellCommand
+        } else if features.enabled(Feature::UnifiedExec) && unified_exec_allowed {
+            if codex_utils_pty::conpty_supported() {
+                ConfigShellToolType::UnifiedExec
+            } else {
+                ConfigShellToolType::ShellCommand
+            }
+        } else if model_info.shell_type == ConfigShellToolType::UnifiedExec && !unified_exec_allowed
+        {
+            ConfigShellToolType::ShellCommand
+        } else {
+            model_info.shell_type
+        };
+
+        let apply_patch_tool_type = match model_info.apply_patch_tool_type {
+            Some(ApplyPatchToolType::Freeform) => Some(ApplyPatchToolType::Freeform),
+            Some(ApplyPatchToolType::Function) => Some(ApplyPatchToolType::Function),
+            None => include_apply_patch_tool.then_some(ApplyPatchToolType::Freeform),
+        };
+
+        let agent_jobs_worker_tools = include_agent_jobs
+            && matches!(
+                session_source,
+                SessionSource::SubAgent(SubAgentSource::Other(label))
+                    if label.starts_with("agent_job:")
+            );
+
+        Self {
+            available_models: available_models.to_vec(),
+            shell_type,
+            shell_command_backend,
+            unified_exec_shell_mode: UnifiedExecShellMode::Direct,
+            allow_login_shell: true,
+            apply_patch_tool_type,
+            web_search_mode: *web_search_mode,
+            web_search_config: None,
+            web_search_tool_type: model_info.web_search_tool_type,
+            image_gen_tool: include_image_gen_tool,
+            search_tool: include_search_tool,
+            tool_suggest: include_tool_suggest,
+            exec_permission_approvals_enabled,
+            request_permissions_tool_enabled,
+            code_mode_enabled: include_code_mode,
+            code_mode_only_enabled: include_code_mode_only,
+            js_repl_enabled: include_js_repl,
+            js_repl_tools_only: include_js_repl_tools_only,
+            can_request_original_image_detail: include_original_image_detail,
+            collab_tools: include_collab_tools,
+            multi_agent_v2: include_multi_agent_v2,
+            request_user_input: include_request_user_input,
+            alarm_scheduler: include_alarm_scheduler,
+            default_mode_request_user_input: include_default_mode_request_user_input,
+            experimental_supported_tools: model_info.experimental_supported_tools.clone(),
+            agent_jobs_tools: include_agent_jobs,
+            agent_jobs_worker_tools,
+            agent_type_description: String::new(),
+        }
+    }
+
+    pub fn with_agent_type_description(mut self, agent_type_description: String) -> Self {
+        self.agent_type_description = agent_type_description;
+        self
+    }
+
+    pub fn with_allow_login_shell(mut self, allow_login_shell: bool) -> Self {
+        self.allow_login_shell = allow_login_shell;
+        self
+    }
+
+    pub fn with_unified_exec_shell_mode(
+        mut self,
+        unified_exec_shell_mode: UnifiedExecShellMode,
+    ) -> Self {
+        self.unified_exec_shell_mode = unified_exec_shell_mode;
+        self
+    }
+
+    pub fn with_unified_exec_shell_mode_for_session(
+        mut self,
+        user_shell_type: ToolUserShellType,
+        shell_zsh_path: Option<&PathBuf>,
+        main_execve_wrapper_exe: Option<&PathBuf>,
+    ) -> Self {
+        self.unified_exec_shell_mode = UnifiedExecShellMode::for_session(
+            self.shell_command_backend,
+            user_shell_type,
+            shell_zsh_path,
+            main_execve_wrapper_exe,
+        );
+        self
+    }
+
+    pub fn with_web_search_config(mut self, web_search_config: Option<WebSearchConfig>) -> Self {
+        self.web_search_config = web_search_config;
+        self
+    }
+
+    pub fn for_code_mode_nested_tools(&self) -> Self {
+        let mut nested = self.clone();
+        nested.code_mode_enabled = false;
+        nested.code_mode_only_enabled = false;
+        nested
+    }
+}
+
+fn supports_image_generation(model_info: &ModelInfo) -> bool {
+    model_info.input_modalities.contains(&InputModality::Image)
+}
+
+fn unified_exec_allowed_in_environment(
+    is_windows: bool,
+    sandbox_policy: &SandboxPolicy,
+    windows_sandbox_level: WindowsSandboxLevel,
+) -> bool {
+    !(is_windows
+        && windows_sandbox_level != WindowsSandboxLevel::Disabled
+        && !matches!(
+            sandbox_policy,
+            SandboxPolicy::DangerFullAccess | SandboxPolicy::ExternalSandbox { .. }
+        ))
+}
+
+#[cfg(test)]
+#[path = "tool_config_tests.rs"]
+mod tests;

codex-rs/tools/src/tool_config_tests.rs

@@ -0,0 +1,200 @@
+use super::*;
+use codex_features::Feature;
+use codex_features::Features;
+use codex_protocol::config_types::WebSearchMode;
+use codex_protocol::config_types::WindowsSandboxLevel;
+use codex_protocol::openai_models::ConfigShellToolType;
+use codex_protocol::openai_models::InputModality;
+use codex_protocol::openai_models::ModelInfo;
+use codex_protocol::protocol::SandboxPolicy;
+use codex_protocol::protocol::SessionSource;
+use codex_protocol::protocol::SubAgentSource;
+use codex_utils_absolute_path::AbsolutePathBuf;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+use std::path::PathBuf;
+
+fn model_info() -> ModelInfo {
+    serde_json::from_value(json!({
+        "slug": "test-model",
+        "display_name": "Test Model",
+        "description": null,
+        "supported_reasoning_levels": [],
+        "shell_type": "unified_exec",
+        "visibility": "list",
+        "supported_in_api": true,
+        "priority": 1,
+        "availability_nux": null,
+        "upgrade": null,
+        "base_instructions": "base",
+        "model_messages": null,
+        "supports_reasoning_summaries": false,
+        "default_reasoning_summary": "auto",
+        "support_verbosity": false,
+        "default_verbosity": null,
+        "apply_patch_tool_type": null,
+        "truncation_policy": {
+            "mode": "bytes",
+            "limit": 10000
+        },
+        "supports_parallel_tool_calls": false,
+        "supports_image_detail_original": false,
+        "context_window": null,
+        "auto_compact_token_limit": null,
+        "effective_context_window_percent": 95,
+        "experimental_supported_tools": [],
+        "input_modalities": ["text", "image"],
+        "supports_search_tool": false
+    }))
+    .expect("deserialize test model")
+}
+
+#[test]
+fn unified_exec_is_blocked_for_windows_sandboxed_policies_only() {
+    assert!(!unified_exec_allowed_in_environment(
+        /*is_windows*/ true,
+        &SandboxPolicy::new_read_only_policy(),
+        WindowsSandboxLevel::RestrictedToken,
+    ));
+    assert!(!unified_exec_allowed_in_environment(
+        /*is_windows*/ true,
+        &SandboxPolicy::new_workspace_write_policy(),
+        WindowsSandboxLevel::RestrictedToken,
+    ));
+    assert!(unified_exec_allowed_in_environment(
+        /*is_windows*/ true,
+        &SandboxPolicy::DangerFullAccess,
+        WindowsSandboxLevel::RestrictedToken,
+    ));
+    assert!(unified_exec_allowed_in_environment(
+        /*is_windows*/ true,
+        &SandboxPolicy::DangerFullAccess,
+        WindowsSandboxLevel::Disabled,
+    ));
+}
+
+#[test]
+fn shell_zsh_fork_prefers_shell_command_over_unified_exec() {
+    let model_info = model_info();
+    let mut features = Features::with_defaults();
+    features.enable(Feature::UnifiedExec);
+    features.enable(Feature::ShellZshFork);
+
+    let available_models = Vec::new();
+    let tools_config = ToolsConfig::new(&ToolsConfigParams {
+        model_info: &model_info,
+        available_models: &available_models,
+        features: &features,
+        web_search_mode: Some(WebSearchMode::Live),
+        session_source: SessionSource::Cli,
+        sandbox_policy: &SandboxPolicy::DangerFullAccess,
+        windows_sandbox_level: WindowsSandboxLevel::Disabled,
+    });
+
+    assert_eq!(tools_config.shell_type, ConfigShellToolType::ShellCommand);
+    assert_eq!(
+        tools_config.shell_command_backend,
+        ShellCommandBackendConfig::ZshFork
+    );
+    assert_eq!(
+        tools_config.unified_exec_shell_mode,
+        UnifiedExecShellMode::Direct
+    );
+    assert_eq!(
+        tools_config
+            .with_unified_exec_shell_mode_for_session(
+                ToolUserShellType::Zsh,
+                Some(&PathBuf::from(if cfg!(windows) {
+                    r"C:\opt\codex\zsh"
+                } else {
+                    "/opt/codex/zsh"
+                })),
+                Some(&PathBuf::from(if cfg!(windows) {
+                    r"C:\opt\codex\codex-execve-wrapper"
+                } else {
+                    "/opt/codex/codex-execve-wrapper"
+                })),
+            )
+            .unified_exec_shell_mode,
+        if cfg!(unix) {
+            UnifiedExecShellMode::ZshFork(ZshForkConfig {
+                shell_zsh_path: AbsolutePathBuf::from_absolute_path("/opt/codex/zsh").unwrap(),
+                main_execve_wrapper_exe: AbsolutePathBuf::from_absolute_path(
+                    "/opt/codex/codex-execve-wrapper",
+                )
+                .unwrap(),
+            })
+        } else {
+            UnifiedExecShellMode::Direct
+        }
+    );
+}
+
+#[test]
+fn subagents_disable_request_user_input_and_agent_jobs_workers_opt_in_by_label() {
+    let model_info = model_info();
+    let mut features = Features::with_defaults();
+    features.enable(Feature::SpawnCsv);
+
+    let available_models = Vec::new();
+    let tools_config = ToolsConfig::new(&ToolsConfigParams {
+        model_info: &model_info,
+        available_models: &available_models,
+        features: &features,
+        web_search_mode: Some(WebSearchMode::Cached),
+        session_source: SessionSource::SubAgent(SubAgentSource::Other(
+            "agent_job:test".to_string(),
+        )),
+        sandbox_policy: &SandboxPolicy::DangerFullAccess,
+        windows_sandbox_level: WindowsSandboxLevel::Disabled,
+    });
+
+    assert!(!tools_config.request_user_input);
+    assert!(!tools_config.default_mode_request_user_input);
+    assert!(tools_config.agent_jobs_tools);
+    assert!(tools_config.agent_jobs_worker_tools);
+}
+
+#[test]
+fn image_generation_requires_feature_and_supported_model() {
+    let supported_model_info = model_info();
+    let mut unsupported_model_info = supported_model_info.clone();
+    unsupported_model_info.input_modalities = vec![InputModality::Text];
+
+    let default_features = Features::with_defaults();
+    let mut image_generation_features = default_features.clone();
+    image_generation_features.enable(Feature::ImageGeneration);
+
+    let available_models = Vec::new();
+    let default_tools_config = ToolsConfig::new(&ToolsConfigParams {
+        model_info: &supported_model_info,
+        available_models: &available_models,
+        features: &default_features,
+        web_search_mode: Some(WebSearchMode::Cached),
+        session_source: SessionSource::Cli,
+        sandbox_policy: &SandboxPolicy::DangerFullAccess,
+        windows_sandbox_level: WindowsSandboxLevel::Disabled,
+    });
+    let supported_tools_config = ToolsConfig::new(&ToolsConfigParams {
+        model_info: &supported_model_info,
+        available_models: &available_models,
+        features: &image_generation_features,
+        web_search_mode: Some(WebSearchMode::Cached),
+        session_source: SessionSource::Cli,
+        sandbox_policy: &SandboxPolicy::DangerFullAccess,
+        windows_sandbox_level: WindowsSandboxLevel::Disabled,
+    });
+    let unsupported_tools_config = ToolsConfig::new(&ToolsConfigParams {
+        model_info: &unsupported_model_info,
+        available_models: &available_models,
+        features: &image_generation_features,
+        web_search_mode: Some(WebSearchMode::Cached),
+        session_source: SessionSource::Cli,
+        sandbox_policy: &SandboxPolicy::DangerFullAccess,
+        windows_sandbox_level: WindowsSandboxLevel::Disabled,
+    });
+
+    assert!(!default_tools_config.image_gen_tool);
+    assert!(supported_tools_config.image_gen_tool);
+    assert!(!unsupported_tools_config.image_gen_tool);
+}

codex-rs/tools/src/tool_discovery.rs

@@ -1,12 +1,19 @@
 use crate::JsonSchema;
+use crate::ResponsesApiNamespace;
+use crate::ResponsesApiNamespaceTool;
 use crate::ResponsesApiTool;
+use crate::ToolSearchOutputTool;
 use crate::ToolSpec;
+use crate::mcp_tool_to_deferred_responses_api_tool;
 use codex_app_server_protocol::AppInfo;
 use serde::Deserialize;
 use serde::Serialize;
 use std::collections::BTreeMap;
 
 const TUI_CLIENT_NAME: &str = "codex-tui";
+pub const TOOL_SEARCH_TOOL_NAME: &str = "tool_search";
+pub const TOOL_SEARCH_DEFAULT_LIMIT: usize = 8;
+pub const TOOL_SUGGEST_TOOL_NAME: &str = "tool_suggest";
 
 #[derive(Clone, Debug, PartialEq, Eq)]
 pub struct ToolSearchAppInfo {
@@ -14,6 +21,22 @@ pub struct ToolSearchAppInfo {
     pub description: Option<String>,
 }
 
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ToolSearchAppSource<'a> {
+    pub server_name: &'a str,
+    pub connector_name: Option<&'a str>,
+    pub connector_description: Option<&'a str>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq)]
+pub struct ToolSearchResultSource<'a> {
+    pub tool_namespace: &'a str,
+    pub tool_name: &'a str,
+    pub tool: &'a rmcp::model::Tool,
+    pub connector_name: Option<&'a str>,
+    pub connector_description: Option<&'a str>,
+}
+
 #[derive(Clone, Copy, Debug, Deserialize, Serialize, PartialEq, Eq)]
 #[serde(rename_all = "snake_case")]
 pub enum DiscoverableToolType {
@@ -164,7 +187,7 @@ pub fn create_tool_search_tool(app_tools: &[ToolSearchAppInfo], default_limit: u
     };
 
     let description = format!(
-        "# Apps (Connectors) tool discovery\n\nSearches over apps/connectors tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to all the tools of the following apps/connectors:\n{app_descriptions}\nSome of the tools may not have been provided to you upfront, and you should use this tool (`tool_search`) to search for the required tools and load them for the apps mentioned above. For the apps mentioned above, always use `tool_search` instead of `list_mcp_resources` or `list_mcp_resource_templates` for tool discovery."
+        "# Apps (Connectors) tool discovery\n\nSearches over apps/connectors tool metadata with BM25 and exposes matching tools for the next model call.\n\nYou have access to all the tools of the following apps/connectors:\n{app_descriptions}\nSome of the tools may not have been provided to you upfront, and you should use this tool (`{TOOL_SEARCH_TOOL_NAME}`) to search for the required tools and load them for the apps mentioned above. For the apps mentioned above, always use `{TOOL_SEARCH_TOOL_NAME}` instead of `list_mcp_resources` or `list_mcp_resource_templates` for tool discovery."
     );
 
     ToolSpec::ToolSearch {
@@ -178,6 +201,75 @@ pub fn create_tool_search_tool(app_tools: &[ToolSearchAppInfo], default_limit: u
     }
 }
 
+pub fn collect_tool_search_output_tools<'a>(
+    tool_sources: impl IntoIterator<Item = ToolSearchResultSource<'a>>,
+) -> Result<Vec<ToolSearchOutputTool>, serde_json::Error> {
+    let grouped = tool_sources.into_iter().fold(
+        BTreeMap::<&'a str, Vec<ToolSearchResultSource<'a>>>::new(),
+        |mut grouped, tool| {
+            grouped.entry(tool.tool_namespace).or_default().push(tool);
+            grouped
+        },
+    );
+
+    let mut results = Vec::with_capacity(grouped.len());
+    for (tool_namespace, tools) in grouped {
+        let Some(first_tool) = tools.first() else {
+            continue;
+        };
+
+        let description = first_tool
+            .connector_description
+            .map(str::to_string)
+            .or_else(|| {
+                first_tool
+                    .connector_name
+                    .map(str::trim)
+                    .filter(|connector_name| !connector_name.is_empty())
+                    .map(|connector_name| format!("Tools for working with {connector_name}."))
+            });
+
+        let tools = tools
+            .iter()
+            .map(|tool| {
+                mcp_tool_to_deferred_responses_api_tool(tool.tool_name.to_string(), tool.tool)
+                    .map(ResponsesApiNamespaceTool::Function)
+            })
+            .collect::<Result<Vec<_>, _>>()?;
+
+        results.push(ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+            name: tool_namespace.to_string(),
+            description: description.unwrap_or_default(),
+            tools,
+        }));
+    }
+
+    Ok(results)
+}
+
+pub fn collect_tool_search_app_infos<'a>(
+    app_tools: impl IntoIterator<Item = ToolSearchAppSource<'a>>,
+    codex_apps_server_name: &str,
+) -> Vec<ToolSearchAppInfo> {
+    app_tools
+        .into_iter()
+        .filter(|tool| tool.server_name == codex_apps_server_name)
+        .filter_map(|tool| {
+            let name = tool
+                .connector_name
+                .map(str::trim)
+                .filter(|connector_name| !connector_name.is_empty())?
+                .to_string();
+            let description = tool
+                .connector_description
+                .map(str::trim)
+                .filter(|connector_description| !connector_description.is_empty())
+                .map(str::to_string);
+            Some(ToolSearchAppInfo { name, description })
+        })
+        .collect()
+}
+
 pub fn create_tool_suggest_tool(discoverable_tools: &[ToolSuggestEntry]) -> ToolSpec {
     let discoverable_tool_ids = discoverable_tools
         .iter()
@@ -223,11 +315,11 @@ pub fn create_tool_suggest_tool(discoverable_tools: &[ToolSuggestEntry]) -> Tool
 
     let discoverable_tools = format_discoverable_tools(discoverable_tools);
     let description = format!(
-        "# Tool suggestion discovery\n\nSuggests a missing connector in an installed plugin, or in narrower cases a not installed but discoverable plugin, when the user clearly wants a capability that is not currently available in the active `tools` list.\n\nUse this ONLY when:\n- You've already tried to find a matching available tool for the user's request but couldn't find a good match. This includes `tool_search` (if available) and other means.\n- For connectors/apps that are not installed but needed for an installed plugin, suggest to install them if the task requirements match precisely.\n- For plugins that are not installed but discoverable, only suggest discoverable and installable plugins when the user's intent very explicitly and unambiguously matches that plugin itself. Do not suggest a plugin just because one of its connectors or capabilities seems relevant.\n\nTool suggestions should only use the discoverable tools listed here. DO NOT explore or recommend tools that are not on this list.\n\nDiscoverable tools:\n{discoverable_tools}\n\nWorkflow:\n\n1. Ensure all possible means have been exhausted to find an existing available tool but none of them matches the request intent.\n2. Match the user's request against the discoverable tools list above. Apply the stricter explicit-and-unambiguous rule for *discoverable tools* like plugin install suggestions; *missing tools* like connector install suggestions continue to use the normal clear-fit standard.\n3. If one tool clearly fits, call `tool_suggest` with:\n   - `tool_type`: `connector` or `plugin`\n   - `action_type`: `install` or `enable`\n   - `tool_id`: exact id from the discoverable tools list above\n   - `suggest_reason`: concise one-line user-facing reason this tool can help with the current request\n4. After the suggestion flow completes:\n   - if the user finished the install or enable flow, continue by searching again or using the newly available tool\n   - if the user did not finish, continue without that tool, and don't suggest that tool again unless the user explicitly asks for it."
+        "# Tool suggestion discovery\n\nSuggests a missing connector in an installed plugin, or in narrower cases a not installed but discoverable plugin, when the user clearly wants a capability that is not currently available in the active `tools` list.\n\nUse this ONLY when:\n- You've already tried to find a matching available tool for the user's request but couldn't find a good match. This includes `{TOOL_SEARCH_TOOL_NAME}` (if available) and other means.\n- For connectors/apps that are not installed but needed for an installed plugin, suggest to install them if the task requirements match precisely.\n- For plugins that are not installed but discoverable, only suggest discoverable and installable plugins when the user's intent very explicitly and unambiguously matches that plugin itself. Do not suggest a plugin just because one of its connectors or capabilities seems relevant.\n\nTool suggestions should only use the discoverable tools listed here. DO NOT explore or recommend tools that are not on this list.\n\nDiscoverable tools:\n{discoverable_tools}\n\nWorkflow:\n\n1. Ensure all possible means have been exhausted to find an existing available tool but none of them matches the request intent.\n2. Match the user's request against the discoverable tools list above. Apply the stricter explicit-and-unambiguous rule for *discoverable tools* like plugin install suggestions; *missing tools* like connector install suggestions continue to use the normal clear-fit standard.\n3. If one tool clearly fits, call `{TOOL_SUGGEST_TOOL_NAME}` with:\n   - `tool_type`: `connector` or `plugin`\n   - `action_type`: `install` or `enable`\n   - `tool_id`: exact id from the discoverable tools list above\n   - `suggest_reason`: concise one-line user-facing reason this tool can help with the current request\n4. After the suggestion flow completes:\n   - if the user finished the install or enable flow, continue by searching again or using the newly available tool\n   - if the user did not finish, continue without that tool, and don't suggest that tool again unless the user explicitly asks for it."
     );
 
     ToolSpec::Function(ResponsesApiTool {
-        name: "tool_suggest".to_string(),
+        name: TOOL_SUGGEST_TOOL_NAME.to_string(),
         description,
         strict: false,
         defer_loading: None,
@@ -245,6 +337,34 @@ pub fn create_tool_suggest_tool(discoverable_tools: &[ToolSuggestEntry]) -> Tool
     })
 }
 
+pub fn collect_tool_suggest_entries(
+    discoverable_tools: &[DiscoverableTool],
+) -> Vec<ToolSuggestEntry> {
+    discoverable_tools
+        .iter()
+        .map(|tool| match tool {
+            DiscoverableTool::Connector(connector) => ToolSuggestEntry {
+                id: connector.id.clone(),
+                name: connector.name.clone(),
+                description: connector.description.clone(),
+                tool_type: DiscoverableToolType::Connector,
+                has_skills: false,
+                mcp_server_names: Vec::new(),
+                app_connector_ids: Vec::new(),
+            },
+            DiscoverableTool::Plugin(plugin) => ToolSuggestEntry {
+                id: plugin.id.clone(),
+                name: plugin.name.clone(),
+                description: plugin.description.clone(),
+                tool_type: DiscoverableToolType::Plugin,
+                has_skills: plugin.has_skills,
+                mcp_server_names: plugin.mcp_server_names.clone(),
+                app_connector_ids: plugin.app_connector_ids.clone(),
+            },
+        })
+        .collect()
+}
+
 fn format_discoverable_tools(discoverable_tools: &[ToolSuggestEntry]) -> String {
     let mut discoverable_tools = discoverable_tools.to_vec();
     discoverable_tools.sort_by(|left, right| {

codex-rs/tools/src/tool_discovery_tests.rs

@@ -1,8 +1,28 @@
 use super::*;
 use codex_app_server_protocol::AppInfo;
 use pretty_assertions::assert_eq;
+use rmcp::model::JsonObject;
+use rmcp::model::Tool;
 use serde_json::json;
 use std::collections::BTreeMap;
+use std::sync::Arc;
+
+fn mcp_tool(name: &str, description: &str) -> Tool {
+    Tool {
+        name: name.to_string().into(),
+        title: None,
+        description: Some(description.to_string().into()),
+        input_schema: Arc::new(JsonObject::from_iter([(
+            "type".to_string(),
+            json!("object"),
+        )])),
+        output_schema: None,
+        annotations: None,
+        execution: None,
+        icons: None,
+        meta: None,
+    }
+}
 
 #[test]
 fn create_tool_search_tool_deduplicates_and_renders_enabled_apps() {
@@ -135,6 +155,124 @@ fn create_tool_suggest_tool_uses_plugin_summary_fallback() {
     );
 }
 
+#[test]
+fn collect_tool_search_output_tools_groups_results_by_namespace() {
+    let calendar_create_event = mcp_tool("calendar-create-event", "Create a calendar event.");
+    let gmail_read_email = mcp_tool("gmail-read-email", "Read an email.");
+    let calendar_list_events = mcp_tool("calendar-list-events", "List calendar events.");
+
+    let tools = collect_tool_search_output_tools([
+        ToolSearchResultSource {
+            tool_namespace: "mcp__codex_apps__calendar",
+            tool_name: "_create_event",
+            tool: &calendar_create_event,
+            connector_name: Some("Calendar"),
+            connector_description: Some("Plan events"),
+        },
+        ToolSearchResultSource {
+            tool_namespace: "mcp__codex_apps__gmail",
+            tool_name: "_read_email",
+            tool: &gmail_read_email,
+            connector_name: Some("Gmail"),
+            connector_description: Some("Read mail"),
+        },
+        ToolSearchResultSource {
+            tool_namespace: "mcp__codex_apps__calendar",
+            tool_name: "_list_events",
+            tool: &calendar_list_events,
+            connector_name: Some("Calendar"),
+            connector_description: Some("Plan events"),
+        },
+    ])
+    .expect("collect tool search output tools");
+
+    assert_eq!(
+        tools,
+        vec![
+            ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+                name: "mcp__codex_apps__calendar".to_string(),
+                description: "Plan events".to_string(),
+                tools: vec![
+                    ResponsesApiNamespaceTool::Function(ResponsesApiTool {
+                        name: "_create_event".to_string(),
+                        description: "Create a calendar event.".to_string(),
+                        strict: false,
+                        defer_loading: Some(true),
+                        parameters: JsonSchema::Object {
+                            properties: Default::default(),
+                            required: None,
+                            additional_properties: None,
+                        },
+                        output_schema: None,
+                    }),
+                    ResponsesApiNamespaceTool::Function(ResponsesApiTool {
+                        name: "_list_events".to_string(),
+                        description: "List calendar events.".to_string(),
+                        strict: false,
+                        defer_loading: Some(true),
+                        parameters: JsonSchema::Object {
+                            properties: Default::default(),
+                            required: None,
+                            additional_properties: None,
+                        },
+                        output_schema: None,
+                    }),
+                ],
+            }),
+            ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+                name: "mcp__codex_apps__gmail".to_string(),
+                description: "Read mail".to_string(),
+                tools: vec![ResponsesApiNamespaceTool::Function(ResponsesApiTool {
+                    name: "_read_email".to_string(),
+                    description: "Read an email.".to_string(),
+                    strict: false,
+                    defer_loading: Some(true),
+                    parameters: JsonSchema::Object {
+                        properties: Default::default(),
+                        required: None,
+                        additional_properties: None,
+                    },
+                    output_schema: None,
+                })],
+            }),
+        ],
+    );
+}
+
+#[test]
+fn collect_tool_search_output_tools_falls_back_to_connector_name_description() {
+    let gmail_batch_read_email = mcp_tool("gmail-batch-read-email", "Read multiple emails.");
+
+    let tools = collect_tool_search_output_tools([ToolSearchResultSource {
+        tool_namespace: "mcp__codex_apps__gmail",
+        tool_name: "_batch_read_email",
+        tool: &gmail_batch_read_email,
+        connector_name: Some("Gmail"),
+        connector_description: None,
+    }])
+    .expect("collect tool search output tools");
+
+    assert_eq!(
+        tools,
+        vec![ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+            name: "mcp__codex_apps__gmail".to_string(),
+            description: "Tools for working with Gmail.".to_string(),
+            tools: vec![ResponsesApiNamespaceTool::Function(ResponsesApiTool {
+                name: "_batch_read_email".to_string(),
+                description: "Read multiple emails.".to_string(),
+                strict: false,
+                defer_loading: Some(true),
+                parameters: JsonSchema::Object {
+                    properties: Default::default(),
+                    required: None,
+                    additional_properties: None,
+                },
+                output_schema: None,
+            })],
+        })],
+    );
+}
+
 #[test]
 fn discoverable_tool_enums_use_expected_wire_names() {
     assert_eq!(

codex-rs/tools/src/tool_registry_plan.rs

@@ -0,0 +1,516 @@
+use crate::CommandToolOptions;
+use crate::REQUEST_USER_INPUT_TOOL_NAME;
+use crate::ShellToolOptions;
+use crate::SpawnAgentToolOptions;
+use crate::TOOL_SEARCH_DEFAULT_LIMIT;
+use crate::TOOL_SEARCH_TOOL_NAME;
+use crate::TOOL_SUGGEST_TOOL_NAME;
+use crate::ToolHandlerKind;
+use crate::ToolRegistryPlan;
+use crate::ToolRegistryPlanParams;
+use crate::ToolSearchAppSource;
+use crate::ToolSpec;
+use crate::ToolsConfig;
+use crate::ViewImageToolOptions;
+use crate::WebSearchToolOptions;
+use crate::collect_code_mode_tool_definitions;
+use crate::collect_tool_search_app_infos;
+use crate::collect_tool_suggest_entries;
+use crate::create_alarm_create_tool;
+use crate::create_alarm_delete_tool;
+use crate::create_alarm_list_tool;
+use crate::create_apply_patch_freeform_tool;
+use crate::create_apply_patch_json_tool;
+use crate::create_close_agent_tool_v1;
+use crate::create_close_agent_tool_v2;
+use crate::create_code_mode_tool;
+use crate::create_exec_command_tool;
+use crate::create_followup_task_tool;
+use crate::create_image_generation_tool;
+use crate::create_js_repl_reset_tool;
+use crate::create_js_repl_tool;
+use crate::create_list_agents_tool;
+use crate::create_list_dir_tool;
+use crate::create_list_mcp_resource_templates_tool;
+use crate::create_list_mcp_resources_tool;
+use crate::create_local_shell_tool;
+use crate::create_read_mcp_resource_tool;
+use crate::create_report_agent_job_result_tool;
+use crate::create_request_permissions_tool;
+use crate::create_request_user_input_tool;
+use crate::create_resume_agent_tool;
+use crate::create_send_input_tool_v1;
+use crate::create_send_message_tool;
+use crate::create_shell_command_tool;
+use crate::create_shell_tool;
+use crate::create_spawn_agent_tool_v1;
+use crate::create_spawn_agent_tool_v2;
+use crate::create_spawn_agents_on_csv_tool;
+use crate::create_test_sync_tool;
+use crate::create_tool_search_tool;
+use crate::create_tool_suggest_tool;
+use crate::create_update_plan_tool;
+use crate::create_view_image_tool;
+use crate::create_wait_agent_tool_v1;
+use crate::create_wait_agent_tool_v2;
+use crate::create_wait_tool;
+use crate::create_web_search_tool;
+use crate::create_write_stdin_tool;
+use crate::dynamic_tool_to_responses_api_tool;
+use crate::mcp_tool_to_responses_api_tool;
+use crate::request_permissions_tool_description;
+use crate::request_user_input_tool_description;
+use crate::tool_registry_plan_types::agent_type_description;
+use codex_protocol::openai_models::ApplyPatchToolType;
+use codex_protocol::openai_models::ConfigShellToolType;
+use rmcp::model::Tool as McpTool;
+
+pub fn build_tool_registry_plan(
+    config: &ToolsConfig,
+    params: ToolRegistryPlanParams<'_>,
+) -> ToolRegistryPlan {
+    let mut plan = ToolRegistryPlan::new();
+    let exec_permission_approvals_enabled = config.exec_permission_approvals_enabled;
+
+    if config.code_mode_enabled {
+        let nested_config = config.for_code_mode_nested_tools();
+        let nested_plan = build_tool_registry_plan(
+            &nested_config,
+            ToolRegistryPlanParams {
+                discoverable_tools: None,
+                ..params
+            },
+        );
+        let enabled_tools = collect_code_mode_tool_definitions(
+            nested_plan
+                .specs
+                .iter()
+                .map(|configured_tool| &configured_tool.spec),
+        )
+        .into_iter()
+        .map(|tool| (tool.name, tool.description))
+        .collect::<Vec<_>>();
+        plan.push_spec(
+            create_code_mode_tool(&enabled_tools, config.code_mode_only_enabled),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler(
+            codex_code_mode::PUBLIC_TOOL_NAME,
+            ToolHandlerKind::CodeModeExecute,
+        );
+        plan.push_spec(
+            create_wait_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler(
+            codex_code_mode::WAIT_TOOL_NAME,
+            ToolHandlerKind::CodeModeWait,
+        );
+    }
+
+    match &config.shell_type {
+        ConfigShellToolType::Default => {
+            plan.push_spec(
+                create_shell_tool(ShellToolOptions {
+                    exec_permission_approvals_enabled,
+                }),
+                /*supports_parallel_tool_calls*/ true,
+                config.code_mode_enabled,
+            );
+        }
+        ConfigShellToolType::Local => {
+            plan.push_spec(
+                create_local_shell_tool(),
+                /*supports_parallel_tool_calls*/ true,
+                config.code_mode_enabled,
+            );
+        }
+        ConfigShellToolType::UnifiedExec => {
+            plan.push_spec(
+                create_exec_command_tool(CommandToolOptions {
+                    allow_login_shell: config.allow_login_shell,
+                    exec_permission_approvals_enabled,
+                }),
+                /*supports_parallel_tool_calls*/ true,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_write_stdin_tool(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.register_handler("exec_command", ToolHandlerKind::UnifiedExec);
+            plan.register_handler("write_stdin", ToolHandlerKind::UnifiedExec);
+        }
+        ConfigShellToolType::Disabled => {}
+        ConfigShellToolType::ShellCommand => {
+            plan.push_spec(
+                create_shell_command_tool(CommandToolOptions {
+                    allow_login_shell: config.allow_login_shell,
+                    exec_permission_approvals_enabled,
+                }),
+                /*supports_parallel_tool_calls*/ true,
+                config.code_mode_enabled,
+            );
+        }
+    }
+
+    if config.shell_type != ConfigShellToolType::Disabled {
+        plan.register_handler("shell", ToolHandlerKind::Shell);
+        plan.register_handler("container.exec", ToolHandlerKind::Shell);
+        plan.register_handler("local_shell", ToolHandlerKind::Shell);
+        plan.register_handler("shell_command", ToolHandlerKind::ShellCommand);
+    }
+
+    if params.mcp_tools.is_some() {
+        plan.push_spec(
+            create_list_mcp_resources_tool(),
+            /*supports_parallel_tool_calls*/ true,
+            config.code_mode_enabled,
+        );
+        plan.push_spec(
+            create_list_mcp_resource_templates_tool(),
+            /*supports_parallel_tool_calls*/ true,
+            config.code_mode_enabled,
+        );
+        plan.push_spec(
+            create_read_mcp_resource_tool(),
+            /*supports_parallel_tool_calls*/ true,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("list_mcp_resources", ToolHandlerKind::McpResource);
+        plan.register_handler("list_mcp_resource_templates", ToolHandlerKind::McpResource);
+        plan.register_handler("read_mcp_resource", ToolHandlerKind::McpResource);
+    }
+
+    plan.push_spec(
+        create_update_plan_tool(),
+        /*supports_parallel_tool_calls*/ false,
+        config.code_mode_enabled,
+    );
+    plan.register_handler("update_plan", ToolHandlerKind::Plan);
+
+    if config.js_repl_enabled {
+        plan.push_spec(
+            create_js_repl_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.push_spec(
+            create_js_repl_reset_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("js_repl", ToolHandlerKind::JsRepl);
+        plan.register_handler("js_repl_reset", ToolHandlerKind::JsReplReset);
+    }
+
+    if config.request_user_input {
+        plan.push_spec(
+            create_request_user_input_tool(request_user_input_tool_description(
+                config.default_mode_request_user_input,
+            )),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler(
+            REQUEST_USER_INPUT_TOOL_NAME,
+            ToolHandlerKind::RequestUserInput,
+        );
+    }
+
+    if config.request_permissions_tool_enabled {
+        plan.push_spec(
+            create_request_permissions_tool(request_permissions_tool_description()),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("request_permissions", ToolHandlerKind::RequestPermissions);
+    }
+
+    if config.alarm_scheduler {
+        plan.push_spec(
+            create_alarm_create_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.push_spec(
+            create_alarm_delete_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.push_spec(
+            create_alarm_list_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("AlarmCreate", ToolHandlerKind::AlarmCreate);
+        plan.register_handler("AlarmDelete", ToolHandlerKind::AlarmDelete);
+        plan.register_handler("AlarmList", ToolHandlerKind::AlarmList);
+    }
+
+    if config.search_tool
+        && let Some(app_tools) = params.app_tools
+    {
+        let search_app_infos = collect_tool_search_app_infos(
+            app_tools.iter().map(|tool| ToolSearchAppSource {
+                server_name: tool.server_name,
+                connector_name: tool.connector_name,
+                connector_description: tool.connector_description,
+            }),
+            params.codex_apps_mcp_server_name,
+        );
+        plan.push_spec(
+            create_tool_search_tool(&search_app_infos, TOOL_SEARCH_DEFAULT_LIMIT),
+            /*supports_parallel_tool_calls*/ true,
+            config.code_mode_enabled,
+        );
+        plan.register_handler(TOOL_SEARCH_TOOL_NAME, ToolHandlerKind::ToolSearch);
+
+        for tool in app_tools {
+            plan.register_handler(
+                format!("{}:{}", tool.tool_namespace, tool.tool_name),
+                ToolHandlerKind::Mcp,
+            );
+        }
+    }
+
+    if config.tool_suggest
+        && let Some(discoverable_tools) =
+            params.discoverable_tools.filter(|tools| !tools.is_empty())
+    {
+        plan.push_spec(
+            create_tool_suggest_tool(&collect_tool_suggest_entries(discoverable_tools)),
+            /*supports_parallel_tool_calls*/ true,
+            /*code_mode_enabled*/ false,
+        );
+        plan.register_handler(TOOL_SUGGEST_TOOL_NAME, ToolHandlerKind::ToolSuggest);
+    }
+
+    if let Some(apply_patch_tool_type) = &config.apply_patch_tool_type {
+        match apply_patch_tool_type {
+            ApplyPatchToolType::Freeform => {
+                plan.push_spec(
+                    create_apply_patch_freeform_tool(),
+                    /*supports_parallel_tool_calls*/ false,
+                    config.code_mode_enabled,
+                );
+            }
+            ApplyPatchToolType::Function => {
+                plan.push_spec(
+                    create_apply_patch_json_tool(),
+                    /*supports_parallel_tool_calls*/ false,
+                    config.code_mode_enabled,
+                );
+            }
+        }
+        plan.register_handler("apply_patch", ToolHandlerKind::ApplyPatch);
+    }
+
+    if config
+        .experimental_supported_tools
+        .iter()
+        .any(|tool| tool == "list_dir")
+    {
+        plan.push_spec(
+            create_list_dir_tool(),
+            /*supports_parallel_tool_calls*/ true,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("list_dir", ToolHandlerKind::ListDir);
+    }
+
+    if config
+        .experimental_supported_tools
+        .iter()
+        .any(|tool| tool == "test_sync_tool")
+    {
+        plan.push_spec(
+            create_test_sync_tool(),
+            /*supports_parallel_tool_calls*/ true,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("test_sync_tool", ToolHandlerKind::TestSync);
+    }
+
+    if let Some(web_search_tool) = create_web_search_tool(WebSearchToolOptions {
+        web_search_mode: config.web_search_mode,
+        web_search_config: config.web_search_config.as_ref(),
+        web_search_tool_type: config.web_search_tool_type,
+    }) {
+        plan.push_spec(
+            web_search_tool,
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+    }
+
+    if config.image_gen_tool {
+        plan.push_spec(
+            create_image_generation_tool("png"),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+    }
+
+    plan.push_spec(
+        create_view_image_tool(ViewImageToolOptions {
+            can_request_original_image_detail: config.can_request_original_image_detail,
+        }),
+        /*supports_parallel_tool_calls*/ true,
+        config.code_mode_enabled,
+    );
+    plan.register_handler("view_image", ToolHandlerKind::ViewImage);
+
+    if config.collab_tools {
+        if config.multi_agent_v2 {
+            let agent_type_description =
+                agent_type_description(config, params.default_agent_type_description);
+            plan.push_spec(
+                create_spawn_agent_tool_v2(SpawnAgentToolOptions {
+                    available_models: &config.available_models,
+                    agent_type_description,
+                }),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_send_message_tool(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_followup_task_tool(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_wait_agent_tool_v2(params.wait_agent_timeouts),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_close_agent_tool_v2(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_list_agents_tool(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.register_handler("spawn_agent", ToolHandlerKind::SpawnAgentV2);
+            plan.register_handler("send_message", ToolHandlerKind::SendMessageV2);
+            plan.register_handler("followup_task", ToolHandlerKind::FollowupTaskV2);
+            plan.register_handler("wait_agent", ToolHandlerKind::WaitAgentV2);
+            plan.register_handler("close_agent", ToolHandlerKind::CloseAgentV2);
+            plan.register_handler("list_agents", ToolHandlerKind::ListAgentsV2);
+        } else {
+            let agent_type_description =
+                agent_type_description(config, params.default_agent_type_description);
+            plan.push_spec(
+                create_spawn_agent_tool_v1(SpawnAgentToolOptions {
+                    available_models: &config.available_models,
+                    agent_type_description,
+                }),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_send_input_tool_v1(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_resume_agent_tool(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.register_handler("resume_agent", ToolHandlerKind::ResumeAgentV1);
+            plan.push_spec(
+                create_wait_agent_tool_v1(params.wait_agent_timeouts),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.push_spec(
+                create_close_agent_tool_v1(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.register_handler("spawn_agent", ToolHandlerKind::SpawnAgentV1);
+            plan.register_handler("send_input", ToolHandlerKind::SendInputV1);
+            plan.register_handler("wait_agent", ToolHandlerKind::WaitAgentV1);
+            plan.register_handler("close_agent", ToolHandlerKind::CloseAgentV1);
+        }
+    }
+
+    if config.agent_jobs_tools {
+        plan.push_spec(
+            create_spawn_agents_on_csv_tool(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+        plan.register_handler("spawn_agents_on_csv", ToolHandlerKind::AgentJobs);
+        if config.agent_jobs_worker_tools {
+            plan.push_spec(
+                create_report_agent_job_result_tool(),
+                /*supports_parallel_tool_calls*/ false,
+                config.code_mode_enabled,
+            );
+            plan.register_handler("report_agent_job_result", ToolHandlerKind::AgentJobs);
+        }
+    }
+
+    if let Some(mcp_tools) = params.mcp_tools {
+        let mut entries: Vec<(String, &McpTool)> = mcp_tools
+            .iter()
+            .map(|(name, tool)| (name.clone(), tool))
+            .collect();
+        entries.sort_by(|left, right| left.0.cmp(&right.0));
+
+        for (name, tool) in entries {
+            match mcp_tool_to_responses_api_tool(name.clone(), tool) {
+                Ok(converted_tool) => {
+                    plan.push_spec(
+                        ToolSpec::Function(converted_tool),
+                        /*supports_parallel_tool_calls*/ false,
+                        config.code_mode_enabled,
+                    );
+                    plan.register_handler(name, ToolHandlerKind::Mcp);
+                }
+                Err(error) => {
+                    tracing::error!(
+                        "Failed to convert {name:?} MCP tool to OpenAI tool: {error:?}"
+                    );
+                }
+            }
+        }
+    }
+
+    for tool in params.dynamic_tools {
+        match dynamic_tool_to_responses_api_tool(tool) {
+            Ok(converted_tool) => {
+                plan.push_spec(
+                    ToolSpec::Function(converted_tool),
+                    /*supports_parallel_tool_calls*/ false,
+                    config.code_mode_enabled,
+                );
+                plan.register_handler(tool.name.clone(), ToolHandlerKind::DynamicTool);
+            }
+            Err(error) => {
+                tracing::error!(
+                    "Failed to convert dynamic tool {:?} to OpenAI tool: {error:?}",
+                    tool.name
+                );
+            }
+        }
+    }
+
+    plan
+}
+
+#[cfg(test)]
+#[path = "tool_registry_plan_tests.rs"]
+mod tests;

codex-rs/tools/src/tool_registry_plan_types.rs

@@ -0,0 +1,121 @@
+use crate::ConfiguredToolSpec;
+use crate::DiscoverableTool;
+use crate::ToolSpec;
+use crate::ToolsConfig;
+use crate::WaitAgentTimeoutOptions;
+use crate::augment_tool_spec_for_code_mode;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
+use rmcp::model::Tool as McpTool;
+use std::collections::HashMap;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ToolHandlerKind {
+    AlarmCreate,
+    AlarmDelete,
+    AlarmList,
+    AgentJobs,
+    ApplyPatch,
+    CloseAgentV1,
+    CloseAgentV2,
+    CodeModeExecute,
+    CodeModeWait,
+    DynamicTool,
+    FollowupTaskV2,
+    JsRepl,
+    JsReplReset,
+    ListAgentsV2,
+    ListDir,
+    Mcp,
+    McpResource,
+    Plan,
+    RequestPermissions,
+    RequestUserInput,
+    ResumeAgentV1,
+    SendInputV1,
+    SendMessageV2,
+    Shell,
+    ShellCommand,
+    SpawnAgentV1,
+    SpawnAgentV2,
+    TestSync,
+    ToolSearch,
+    ToolSuggest,
+    UnifiedExec,
+    ViewImage,
+    WaitAgentV1,
+    WaitAgentV2,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct ToolHandlerSpec {
+    pub name: String,
+    pub kind: ToolHandlerKind,
+}
+
+#[derive(Debug, Clone, PartialEq)]
+pub struct ToolRegistryPlan {
+    pub specs: Vec<ConfiguredToolSpec>,
+    pub handlers: Vec<ToolHandlerSpec>,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct ToolRegistryPlanParams<'a> {
+    pub mcp_tools: Option<&'a HashMap<String, McpTool>>,
+    pub app_tools: Option<&'a [ToolRegistryPlanAppTool<'a>]>,
+    pub discoverable_tools: Option<&'a [DiscoverableTool]>,
+    pub dynamic_tools: &'a [DynamicToolSpec],
+    pub default_agent_type_description: &'a str,
+    pub wait_agent_timeouts: WaitAgentTimeoutOptions,
+    pub codex_apps_mcp_server_name: &'a str,
+}
+
+#[derive(Debug, Clone, Copy)]
+pub struct ToolRegistryPlanAppTool<'a> {
+    pub tool_name: &'a str,
+    pub tool_namespace: &'a str,
+    pub server_name: &'a str,
+    pub connector_name: Option<&'a str>,
+    pub connector_description: Option<&'a str>,
+}
+
+impl ToolRegistryPlan {
+    pub(crate) fn new() -> Self {
+        Self {
+            specs: Vec::new(),
+            handlers: Vec::new(),
+        }
+    }
+
+    pub(crate) fn push_spec(
+        &mut self,
+        spec: ToolSpec,
+        supports_parallel_tool_calls: bool,
+        code_mode_enabled: bool,
+    ) {
+        let spec = if code_mode_enabled {
+            augment_tool_spec_for_code_mode(spec)
+        } else {
+            spec
+        };
+        self.specs
+            .push(ConfiguredToolSpec::new(spec, supports_parallel_tool_calls));
+    }
+
+    pub(crate) fn register_handler(&mut self, name: impl Into<String>, kind: ToolHandlerKind) {
+        self.handlers.push(ToolHandlerSpec {
+            name: name.into(),
+            kind,
+        });
+    }
+}
+
+pub(crate) fn agent_type_description(
+    config: &ToolsConfig,
+    default_agent_type_description: &str,
+) -> String {
+    if config.agent_type_description.is_empty() {
+        default_agent_type_description.to_string()
+    } else {
+        config.agent_type_description.clone()
+    }
+}

codex-rs/tools/src/tool_spec.rs

@@ -1,13 +1,18 @@
 use crate::FreeformTool;
 use crate::JsonSchema;
 use crate::ResponsesApiTool;
+use codex_protocol::config_types::WebSearchConfig;
 use codex_protocol::config_types::WebSearchContextSize;
 use codex_protocol::config_types::WebSearchFilters as ConfigWebSearchFilters;
+use codex_protocol::config_types::WebSearchMode;
 use codex_protocol::config_types::WebSearchUserLocation as ConfigWebSearchUserLocation;
 use codex_protocol::config_types::WebSearchUserLocationType;
+use codex_protocol::openai_models::WebSearchToolType;
 use serde::Serialize;
 use serde_json::Value;
 
+const WEB_SEARCH_TEXT_AND_IMAGE_CONTENT_TYPES: [&str; 2] = ["text", "image"];
+
 /// When serialized as JSON, this produces a valid "Tool" in the OpenAI
 /// Responses API.
 #[derive(Debug, Clone, Serialize, PartialEq)]
@@ -61,6 +66,54 @@ impl ToolSpec {
     }
 }
 
+pub fn create_local_shell_tool() -> ToolSpec {
+    ToolSpec::LocalShell {}
+}
+
+pub fn create_image_generation_tool(output_format: &str) -> ToolSpec {
+    ToolSpec::ImageGeneration {
+        output_format: output_format.to_string(),
+    }
+}
+
+pub struct WebSearchToolOptions<'a> {
+    pub web_search_mode: Option<WebSearchMode>,
+    pub web_search_config: Option<&'a WebSearchConfig>,
+    pub web_search_tool_type: WebSearchToolType,
+}
+
+pub fn create_web_search_tool(options: WebSearchToolOptions<'_>) -> Option<ToolSpec> {
+    let external_web_access = match options.web_search_mode {
+        Some(WebSearchMode::Cached) => Some(false),
+        Some(WebSearchMode::Live) => Some(true),
+        Some(WebSearchMode::Disabled) | None => None,
+    }?;
+
+    let search_content_types = match options.web_search_tool_type {
+        WebSearchToolType::Text => None,
+        WebSearchToolType::TextAndImage => Some(
+            WEB_SEARCH_TEXT_AND_IMAGE_CONTENT_TYPES
+                .into_iter()
+                .map(str::to_string)
+                .collect(),
+        ),
+    };
+
+    Some(ToolSpec::WebSearch {
+        external_web_access: Some(external_web_access),
+        filters: options
+            .web_search_config
+            .and_then(|config| config.filters.clone().map(Into::into)),
+        user_location: options
+            .web_search_config
+            .and_then(|config| config.user_location.clone().map(Into::into)),
+        search_context_size: options
+            .web_search_config
+            .and_then(|config| config.search_context_size),
+        search_content_types,
+    })
+}
+
 #[derive(Debug, Clone, PartialEq)]
 pub struct ConfiguredToolSpec {
     pub spec: ToolSpec,

codex-rs/tools/src/tool_suggest.rs

@@ -0,0 +1,125 @@
+use std::collections::BTreeMap;
+
+use codex_app_server_protocol::AppInfo;
+use codex_app_server_protocol::McpElicitationObjectType;
+use codex_app_server_protocol::McpElicitationSchema;
+use codex_app_server_protocol::McpServerElicitationRequest;
+use codex_app_server_protocol::McpServerElicitationRequestParams;
+use serde::Deserialize;
+use serde::Serialize;
+use serde_json::json;
+
+use crate::DiscoverableTool;
+use crate::DiscoverableToolAction;
+use crate::DiscoverableToolType;
+
+pub const TOOL_SUGGEST_APPROVAL_KIND_VALUE: &str = "tool_suggestion";
+
+#[derive(Debug, Deserialize)]
+pub struct ToolSuggestArgs {
+    pub tool_type: DiscoverableToolType,
+    pub action_type: DiscoverableToolAction,
+    pub tool_id: String,
+    pub suggest_reason: String,
+}
+
+#[derive(Debug, Serialize, PartialEq, Eq)]
+pub struct ToolSuggestResult {
+    pub completed: bool,
+    pub user_confirmed: bool,
+    pub tool_type: DiscoverableToolType,
+    pub action_type: DiscoverableToolAction,
+    pub tool_id: String,
+    pub tool_name: String,
+    pub suggest_reason: String,
+}
+
+#[derive(Debug, Serialize, PartialEq, Eq)]
+pub struct ToolSuggestMeta<'a> {
+    pub codex_approval_kind: &'static str,
+    pub tool_type: DiscoverableToolType,
+    pub suggest_type: DiscoverableToolAction,
+    pub suggest_reason: &'a str,
+    pub tool_id: &'a str,
+    pub tool_name: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub install_url: Option<&'a str>,
+}
+
+pub fn build_tool_suggestion_elicitation_request(
+    server_name: &str,
+    thread_id: String,
+    turn_id: String,
+    args: &ToolSuggestArgs,
+    suggest_reason: &str,
+    tool: &DiscoverableTool,
+) -> McpServerElicitationRequestParams {
+    let tool_name = tool.name().to_string();
+    let install_url = tool.install_url().map(ToString::to_string);
+    let message = suggest_reason.to_string();
+
+    McpServerElicitationRequestParams {
+        thread_id,
+        turn_id: Some(turn_id),
+        server_name: server_name.to_string(),
+        request: McpServerElicitationRequest::Form {
+            meta: Some(json!(build_tool_suggestion_meta(
+                args.tool_type,
+                args.action_type,
+                suggest_reason,
+                tool.id(),
+                tool_name.as_str(),
+                install_url.as_deref(),
+            ))),
+            message,
+            requested_schema: McpElicitationSchema {
+                schema_uri: None,
+                type_: McpElicitationObjectType::Object,
+                properties: BTreeMap::new(),
+                required: None,
+            },
+        },
+    }
+}
+
+pub fn all_suggested_connectors_picked_up(
+    expected_connector_ids: &[String],
+    accessible_connectors: &[AppInfo],
+) -> bool {
+    expected_connector_ids.iter().all(|connector_id| {
+        verified_connector_suggestion_completed(connector_id, accessible_connectors)
+    })
+}
+
+pub fn verified_connector_suggestion_completed(
+    tool_id: &str,
+    accessible_connectors: &[AppInfo],
+) -> bool {
+    accessible_connectors
+        .iter()
+        .find(|connector| connector.id == tool_id)
+        .is_some_and(|connector| connector.is_accessible)
+}
+
+fn build_tool_suggestion_meta<'a>(
+    tool_type: DiscoverableToolType,
+    action_type: DiscoverableToolAction,
+    suggest_reason: &'a str,
+    tool_id: &'a str,
+    tool_name: &'a str,
+    install_url: Option<&'a str>,
+) -> ToolSuggestMeta<'a> {
+    ToolSuggestMeta {
+        codex_approval_kind: TOOL_SUGGEST_APPROVAL_KIND_VALUE,
+        tool_type,
+        suggest_type: action_type,
+        suggest_reason,
+        tool_id,
+        tool_name,
+        install_url,
+    }
+}
+
+#[cfg(test)]
+#[path = "tool_suggest_tests.rs"]
+mod tests;

codex-rs/tools/src/tool_suggest_tests.rs

@@ -0,0 +1,207 @@
+use super::*;
+use crate::DiscoverablePluginInfo;
+use pretty_assertions::assert_eq;
+use serde_json::json;
+
+#[test]
+fn build_tool_suggestion_elicitation_request_uses_expected_shape() {
+    let args = ToolSuggestArgs {
+        tool_type: DiscoverableToolType::Connector,
+        action_type: DiscoverableToolAction::Install,
+        tool_id: "connector_2128aebfecb84f64a069897515042a44".to_string(),
+        suggest_reason: "Plan and reference events from your calendar".to_string(),
+    };
+    let connector = DiscoverableTool::Connector(Box::new(AppInfo {
+        id: "connector_2128aebfecb84f64a069897515042a44".to_string(),
+        name: "Google Calendar".to_string(),
+        description: Some("Plan events and schedules.".to_string()),
+        logo_url: None,
+        logo_url_dark: None,
+        distribution_channel: None,
+        branding: None,
+        app_metadata: None,
+        labels: None,
+        install_url: Some(
+            "https://chatgpt.com/apps/google-calendar/connector_2128aebfecb84f64a069897515042a44"
+                .to_string(),
+        ),
+        is_accessible: false,
+        is_enabled: true,
+        plugin_display_names: Vec::new(),
+    }));
+
+    let request = build_tool_suggestion_elicitation_request(
+        "codex-apps",
+        "thread-1".to_string(),
+        "turn-1".to_string(),
+        &args,
+        "Plan and reference events from your calendar",
+        &connector,
+    );
+
+    assert_eq!(
+        request,
+        McpServerElicitationRequestParams {
+            thread_id: "thread-1".to_string(),
+            turn_id: Some("turn-1".to_string()),
+            server_name: "codex-apps".to_string(),
+            request: McpServerElicitationRequest::Form {
+                meta: Some(json!(ToolSuggestMeta {
+                    codex_approval_kind: TOOL_SUGGEST_APPROVAL_KIND_VALUE,
+                    tool_type: DiscoverableToolType::Connector,
+                    suggest_type: DiscoverableToolAction::Install,
+                    suggest_reason: "Plan and reference events from your calendar",
+                    tool_id: "connector_2128aebfecb84f64a069897515042a44",
+                    tool_name: "Google Calendar",
+                    install_url: Some(
+                        "https://chatgpt.com/apps/google-calendar/connector_2128aebfecb84f64a069897515042a44"
+                    ),
+                })),
+                message: "Plan and reference events from your calendar".to_string(),
+                requested_schema: McpElicitationSchema {
+                    schema_uri: None,
+                    type_: McpElicitationObjectType::Object,
+                    properties: BTreeMap::new(),
+                    required: None,
+                },
+            },
+        },
+    );
+}
+
+#[test]
+fn build_tool_suggestion_elicitation_request_for_plugin_omits_install_url() {
+    let args = ToolSuggestArgs {
+        tool_type: DiscoverableToolType::Plugin,
+        action_type: DiscoverableToolAction::Install,
+        tool_id: "sample@openai-curated".to_string(),
+        suggest_reason: "Use the sample plugin's skills and MCP server".to_string(),
+    };
+    let plugin = DiscoverableTool::Plugin(Box::new(DiscoverablePluginInfo {
+        id: "sample@openai-curated".to_string(),
+        name: "Sample Plugin".to_string(),
+        description: Some("Includes skills, MCP servers, and apps.".to_string()),
+        has_skills: true,
+        mcp_server_names: vec!["sample-docs".to_string()],
+        app_connector_ids: vec!["connector_calendar".to_string()],
+    }));
+
+    let request = build_tool_suggestion_elicitation_request(
+        "codex-apps",
+        "thread-1".to_string(),
+        "turn-1".to_string(),
+        &args,
+        "Use the sample plugin's skills and MCP server",
+        &plugin,
+    );
+
+    assert_eq!(
+        request,
+        McpServerElicitationRequestParams {
+            thread_id: "thread-1".to_string(),
+            turn_id: Some("turn-1".to_string()),
+            server_name: "codex-apps".to_string(),
+            request: McpServerElicitationRequest::Form {
+                meta: Some(json!(ToolSuggestMeta {
+                    codex_approval_kind: TOOL_SUGGEST_APPROVAL_KIND_VALUE,
+                    tool_type: DiscoverableToolType::Plugin,
+                    suggest_type: DiscoverableToolAction::Install,
+                    suggest_reason: "Use the sample plugin's skills and MCP server",
+                    tool_id: "sample@openai-curated",
+                    tool_name: "Sample Plugin",
+                    install_url: None,
+                })),
+                message: "Use the sample plugin's skills and MCP server".to_string(),
+                requested_schema: McpElicitationSchema {
+                    schema_uri: None,
+                    type_: McpElicitationObjectType::Object,
+                    properties: BTreeMap::new(),
+                    required: None,
+                },
+            },
+        },
+    );
+}
+
+#[test]
+fn build_tool_suggestion_meta_uses_expected_shape() {
+    let meta = build_tool_suggestion_meta(
+        DiscoverableToolType::Connector,
+        DiscoverableToolAction::Install,
+        "Find and reference emails from your inbox",
+        "connector_68df038e0ba48191908c8434991bbac2",
+        "Gmail",
+        Some("https://chatgpt.com/apps/gmail/connector_68df038e0ba48191908c8434991bbac2"),
+    );
+
+    assert_eq!(
+        meta,
+        ToolSuggestMeta {
+            codex_approval_kind: TOOL_SUGGEST_APPROVAL_KIND_VALUE,
+            tool_type: DiscoverableToolType::Connector,
+            suggest_type: DiscoverableToolAction::Install,
+            suggest_reason: "Find and reference emails from your inbox",
+            tool_id: "connector_68df038e0ba48191908c8434991bbac2",
+            tool_name: "Gmail",
+            install_url: Some(
+                "https://chatgpt.com/apps/gmail/connector_68df038e0ba48191908c8434991bbac2"
+            ),
+        },
+    );
+}
+
+#[test]
+fn verified_connector_suggestion_completed_requires_accessible_connector() {
+    let accessible_connectors = vec![AppInfo {
+        id: "calendar".to_string(),
+        name: "Google Calendar".to_string(),
+        description: None,
+        logo_url: None,
+        logo_url_dark: None,
+        distribution_channel: None,
+        branding: None,
+        app_metadata: None,
+        labels: None,
+        install_url: None,
+        is_accessible: true,
+        is_enabled: false,
+        plugin_display_names: Vec::new(),
+    }];
+
+    assert!(verified_connector_suggestion_completed(
+        "calendar",
+        &accessible_connectors,
+    ));
+    assert!(!verified_connector_suggestion_completed(
+        "gmail",
+        &accessible_connectors,
+    ));
+}
+
+#[test]
+fn all_suggested_connectors_picked_up_requires_every_expected_connector() {
+    let accessible_connectors = vec![AppInfo {
+        id: "calendar".to_string(),
+        name: "Google Calendar".to_string(),
+        description: None,
+        logo_url: None,
+        logo_url_dark: None,
+        distribution_channel: None,
+        branding: None,
+        app_metadata: None,
+        labels: None,
+        install_url: None,
+        is_accessible: true,
+        is_enabled: false,
+        plugin_display_names: Vec::new(),
+    }];
+
+    assert!(all_suggested_connectors_picked_up(
+        &["calendar".to_string()],
+        &accessible_connectors,
+    ));
+    assert!(!all_suggested_connectors_picked_up(
+        &["calendar".to_string(), "gmail".to_string()],
+        &accessible_connectors,
+    ));
+}