[tool search] support namespaced deferred dynamic tools (#18413)

Deferred dynamic tools need to round-trip a namespace so a tool returned
by `tool_search` can be called through the same registry key that core
uses for dispatch.

This change adds namespace support for dynamic tool specs/calls,
persists it through app-server thread state, and routes dynamic tool
calls by full `ToolName` while still sending the app the leaf tool name.
Deferred dynamic tools must provide a namespace; non-deferred dynamic
tools may remain top-level.

It also introduces `LoadableToolSpec` as the shared
function-or-namespace Responses shape used by both `tool_search` output
and dynamic tool registration, so dynamic tools use the same wrapping
logic in both paths.

Validation:
- `cargo test -p codex-tools`
- `cargo test -p codex-core tool_search`

---------

Co-authored-by: Sayan Sisodiya <sayan@openai.com>

codex-rs/tools/src/code_mode.rs

@@ -37,7 +37,7 @@ pub fn augment_tool_spec_for_code_mode(spec: ToolSpec) -> ToolSpec {
                         let tool_name =
                             ToolName::namespaced(namespace.name.clone(), tool.name.clone());
                         let definition = CodeModeToolDefinition {
-                            name: tool_name.display(),
+                            name: code_mode_name_for_tool_name(&tool_name),
                             tool_name,
                             description: tool.description.clone(),
                             kind: CodeModeToolKind::Function,
@@ -208,7 +208,7 @@ fn code_mode_tool_definitions_for_spec(spec: &ToolSpec) -> Vec<CodeModeToolDefin
                 ResponsesApiNamespaceTool::Function(tool) => {
                     let tool_name = ToolName::namespaced(namespace.name.clone(), tool.name.clone());
                     CodeModeToolDefinition {
-                        name: tool_name.display(),
+                        name: code_mode_name_for_tool_name(&tool_name),
                         tool_name,
                         description: tool.description.clone(),
                         kind: CodeModeToolKind::Function,
@@ -225,6 +225,16 @@ fn code_mode_tool_definitions_for_spec(spec: &ToolSpec) -> Vec<CodeModeToolDefin
     }
 }
 
+pub fn code_mode_name_for_tool_name(tool_name: &ToolName) -> String {
+    match tool_name.namespace.as_deref() {
+        Some(namespace) if namespace.ends_with('_') || tool_name.name.starts_with('_') => {
+            format!("{namespace}{}", tool_name.name)
+        }
+        Some(namespace) => format!("{namespace}_{}", tool_name.name),
+        None => tool_name.name.clone(),
+    }
+}
+
 #[cfg(test)]
 #[path = "code_mode_tests.rs"]
 mod tests;

codex-rs/tools/src/dynamic_tool.rs

@@ -3,18 +3,12 @@ use crate::parse_tool_input_schema;
 use codex_protocol::dynamic_tools::DynamicToolSpec;
 
 pub fn parse_dynamic_tool(tool: &DynamicToolSpec) -> Result<ToolDefinition, serde_json::Error> {
-    let DynamicToolSpec {
-        name,
-        description,
-        input_schema,
-        defer_loading,
-    } = tool;
     Ok(ToolDefinition {
-        name: name.clone(),
-        description: description.clone(),
-        input_schema: parse_tool_input_schema(input_schema)?,
+        name: tool.name.clone(),
+        description: tool.description.clone(),
+        input_schema: parse_tool_input_schema(&tool.input_schema)?,
         output_schema: None,
-        defer_loading: *defer_loading,
+        defer_loading: tool.defer_loading,
     })
 }
 

codex-rs/tools/src/dynamic_tool_tests.rs

@@ -8,6 +8,7 @@ use std::collections::BTreeMap;
 #[test]
 fn parse_dynamic_tool_sanitizes_input_schema() {
     let tool = DynamicToolSpec {
+        namespace: None,
         name: "lookup_ticket".to_string(),
         description: "Fetch a ticket".to_string(),
         input_schema: serde_json::json!({
@@ -42,6 +43,7 @@ fn parse_dynamic_tool_sanitizes_input_schema() {
 #[test]
 fn parse_dynamic_tool_preserves_defer_loading() {
     let tool = DynamicToolSpec {
+        namespace: None,
         name: "lookup_ticket".to_string(),
         description: "Fetch a ticket".to_string(),
         input_schema: serde_json::json!({

codex-rs/tools/src/lib.rs

@@ -44,6 +44,7 @@ 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::code_mode_name_for_tool_name;
 pub use code_mode::collect_code_mode_exec_prompt_tool_definitions;
 pub use code_mode::collect_code_mode_tool_definitions;
 pub use code_mode::create_code_mode_tool;
@@ -82,11 +83,13 @@ 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::LoadableToolSpec;
 pub use responses_api::ResponsesApiNamespace;
 pub use responses_api::ResponsesApiNamespaceTool;
 pub use responses_api::ResponsesApiTool;
-pub use responses_api::ToolSearchOutputTool;
+pub use responses_api::coalesce_loadable_tool_specs;
 pub(crate) use responses_api::default_namespace_description;
+pub use responses_api::dynamic_tool_to_loadable_tool_spec;
 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;
@@ -114,7 +117,7 @@ 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_discovery::tool_search_result_source_to_output_tool;
+pub use tool_discovery::tool_search_result_source_to_loadable_tool_spec;
 pub use tool_registry_plan::build_tool_registry_plan;
 pub use tool_registry_plan_types::ToolHandlerKind;
 pub use tool_registry_plan_types::ToolHandlerSpec;

codex-rs/tools/src/responses_api.rs

@@ -40,7 +40,7 @@ pub struct ResponsesApiTool {
 #[derive(Debug, Clone, Serialize, PartialEq)]
 #[serde(tag = "type")]
 #[allow(clippy::large_enum_variant)]
-pub enum ToolSearchOutputTool {
+pub enum LoadableToolSpec {
     #[allow(dead_code)]
     #[serde(rename = "function")]
     Function(ResponsesApiTool),
@@ -74,6 +74,51 @@ pub fn dynamic_tool_to_responses_api_tool(
     )?))
 }
 
+pub fn dynamic_tool_to_loadable_tool_spec(
+    tool: &DynamicToolSpec,
+) -> Result<LoadableToolSpec, serde_json::Error> {
+    let output_tool = dynamic_tool_to_responses_api_tool(tool)?;
+    Ok(match tool.namespace.as_ref() {
+        Some(namespace) => LoadableToolSpec::Namespace(ResponsesApiNamespace {
+            name: namespace.clone(),
+            // the user doesn't provide a description for dynamic tools, so we use the default
+            description: default_namespace_description(namespace),
+            tools: vec![ResponsesApiNamespaceTool::Function(output_tool)],
+        }),
+        None => LoadableToolSpec::Function(output_tool),
+    })
+}
+
+pub fn coalesce_loadable_tool_specs(
+    specs: impl IntoIterator<Item = LoadableToolSpec>,
+) -> Vec<LoadableToolSpec> {
+    let mut coalesced_specs = Vec::new();
+    for spec in specs {
+        match spec {
+            LoadableToolSpec::Function(tool) => {
+                coalesced_specs.push(LoadableToolSpec::Function(tool));
+            }
+            LoadableToolSpec::Namespace(mut namespace) => {
+                if let Some(existing_namespace) =
+                    coalesced_specs.iter_mut().find_map(|spec| match spec {
+                        LoadableToolSpec::Namespace(existing_namespace)
+                            if existing_namespace.name == namespace.name =>
+                        {
+                            Some(existing_namespace)
+                        }
+                        LoadableToolSpec::Function(_) | LoadableToolSpec::Namespace(_) => None,
+                    })
+                {
+                    existing_namespace.tools.append(&mut namespace.tools);
+                } else {
+                    coalesced_specs.push(LoadableToolSpec::Namespace(namespace));
+                }
+            }
+        }
+    }
+    coalesced_specs
+}
+
 pub fn mcp_tool_to_responses_api_tool(
     tool_name: &ToolName,
     tool: &rmcp::model::Tool,

codex-rs/tools/src/responses_api_tests.rs

@@ -1,7 +1,7 @@
+use super::LoadableToolSpec;
 use super::ResponsesApiNamespace;
 use super::ResponsesApiNamespaceTool;
 use super::ResponsesApiTool;
-use super::ToolSearchOutputTool;
 use super::dynamic_tool_to_responses_api_tool;
 use super::mcp_tool_to_deferred_responses_api_tool;
 use super::tool_definition_to_responses_api_tool;
@@ -51,6 +51,7 @@ fn tool_definition_to_responses_api_tool_omits_false_defer_loading() {
 #[test]
 fn dynamic_tool_to_responses_api_tool_preserves_defer_loading() {
     let tool = DynamicToolSpec {
+        namespace: None,
         name: "lookup_order".to_string(),
         description: "Look up an order".to_string(),
         input_schema: json!({
@@ -130,8 +131,8 @@ fn mcp_tool_to_deferred_responses_api_tool_sets_defer_loading() {
 }
 
 #[test]
-fn tool_search_output_namespace_serializes_with_deferred_child_tools() {
-    let namespace = ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+fn loadable_tool_spec_namespace_serializes_with_deferred_child_tools() {
+    let namespace = LoadableToolSpec::Namespace(ResponsesApiNamespace {
         name: "mcp__codex_apps__calendar".to_string(),
         description: "Plan events".to_string(),
         tools: vec![ResponsesApiNamespaceTool::Function(ResponsesApiTool {

codex-rs/tools/src/tool_discovery.rs

@@ -1,9 +1,9 @@
 use crate::JsonSchema;
+use crate::LoadableToolSpec;
 use crate::ResponsesApiNamespace;
 use crate::ResponsesApiNamespaceTool;
 use crate::ResponsesApiTool;
 use crate::ToolName;
-use crate::ToolSearchOutputTool;
 use crate::ToolSpec;
 use crate::default_namespace_description;
 use crate::mcp_tool_to_deferred_responses_api_tool;
@@ -203,10 +203,10 @@ pub fn create_tool_search_tool(
     }
 }
 
-pub fn tool_search_result_source_to_output_tool(
+pub fn tool_search_result_source_to_loadable_tool_spec(
     source: ToolSearchResultSource<'_>,
-) -> Result<ToolSearchOutputTool, serde_json::Error> {
-    Ok(ToolSearchOutputTool::Namespace(ResponsesApiNamespace {
+) -> Result<LoadableToolSpec, serde_json::Error> {
+    Ok(LoadableToolSpec::Namespace(ResponsesApiNamespace {
         name: source.tool_namespace.to_string(),
         description: tool_search_result_source_namespace_description(source),
         tools: vec![tool_search_result_source_to_namespace_tool(source)?],

codex-rs/tools/src/tool_registry_plan.rs

@@ -8,6 +8,7 @@ use crate::TOOL_SEARCH_DEFAULT_LIMIT;
 use crate::TOOL_SEARCH_TOOL_NAME;
 use crate::TOOL_SUGGEST_TOOL_NAME;
 use crate::ToolHandlerKind;
+use crate::ToolName;
 use crate::ToolRegistryPlan;
 use crate::ToolRegistryPlanParams;
 use crate::ToolSearchSource;
@@ -16,6 +17,7 @@ use crate::ToolSpec;
 use crate::ToolsConfig;
 use crate::ViewImageToolOptions;
 use crate::WebSearchToolOptions;
+use crate::coalesce_loadable_tool_specs;
 use crate::collect_code_mode_exec_prompt_tool_definitions;
 use crate::collect_tool_search_source_infos;
 use crate::collect_tool_suggest_entries;
@@ -57,7 +59,7 @@ use crate::create_wait_tool;
 use crate::create_web_search_tool;
 use crate::create_write_stdin_tool;
 use crate::default_namespace_description;
-use crate::dynamic_tool_to_responses_api_tool;
+use crate::dynamic_tool_to_loadable_tool_spec;
 use crate::mcp_tool_to_responses_api_tool;
 use crate::request_permissions_tool_description;
 use crate::request_user_input_tool_description;
@@ -555,15 +557,13 @@ pub fn build_tool_registry_plan(
         }
     }
 
+    let mut dynamic_tool_specs = Vec::new();
     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);
+        match dynamic_tool_to_loadable_tool_spec(tool) {
+            Ok(loadable_tool) => {
+                let handler_name = ToolName::new(tool.namespace.clone(), tool.name.clone());
+                dynamic_tool_specs.push(loadable_tool);
+                plan.register_handler(handler_name, ToolHandlerKind::DynamicTool);
             }
             Err(error) => {
                 tracing::error!(
@@ -573,6 +573,13 @@ pub fn build_tool_registry_plan(
             }
         }
     }
+    for spec in coalesce_loadable_tool_specs(dynamic_tool_specs) {
+        plan.push_spec(
+            spec.into(),
+            /*supports_parallel_tool_calls*/ false,
+            config.code_mode_enabled,
+        );
+    }
 
     plan
 }

codex-rs/tools/src/tool_registry_plan_tests.rs

@@ -1423,23 +1423,36 @@ fn search_tool_registers_for_deferred_dynamic_tools() {
         sandbox_policy: &SandboxPolicy::DangerFullAccess,
         windows_sandbox_level: WindowsSandboxLevel::Disabled,
     });
-    let dynamic_tool = DynamicToolSpec {
-        name: "automation_update".to_string(),
-        description: "Create, update, view, or delete recurring automations.".to_string(),
-        input_schema: json!({
-            "type": "object",
-            "properties": {
-                "mode": { "type": "string" },
-            },
-        }),
-        defer_loading: true,
-    };
+    let dynamic_tools = vec![
+        DynamicToolSpec {
+            namespace: Some("codex_app".to_string()),
+            name: "automation_update".to_string(),
+            description: "Create, update, view, or delete recurring automations.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {
+                    "mode": { "type": "string" },
+                },
+            }),
+            defer_loading: true,
+        },
+        DynamicToolSpec {
+            namespace: Some("codex_app".to_string()),
+            name: "automation_list".to_string(),
+            description: "List recurring automations.".to_string(),
+            input_schema: json!({
+                "type": "object",
+                "properties": {},
+            }),
+            defer_loading: true,
+        },
+    ];
 
     let (tools, handlers) = build_specs(
         &tools_config,
         /*mcp_tools*/ None,
         /*deferred_mcp_tools*/ None,
-        &[dynamic_tool],
+        &dynamic_tools,
     );
 
     let search_tool = find_tool(&tools, TOOL_SEARCH_TOOL_NAME);
@@ -1447,13 +1460,35 @@ fn search_tool_registers_for_deferred_dynamic_tools() {
         panic!("expected tool_search tool");
     };
     assert!(description.contains("- Dynamic tools: Tools provided by the current Codex thread."));
-    assert_contains_tool_names(&tools, &[TOOL_SEARCH_TOOL_NAME, "automation_update"]);
+    assert_contains_tool_names(&tools, &[TOOL_SEARCH_TOOL_NAME, "codex_app"]);
+    assert_eq!(
+        tools
+            .iter()
+            .filter(|tool| tool.name() == "codex_app")
+            .count(),
+        1
+    );
+    assert_eq!(
+        namespace_function_names(&tools, "codex_app"),
+        vec![
+            "automation_update".to_string(),
+            "automation_list".to_string()
+        ]
+    );
+    for tool_name in ["automation_update", "automation_list"] {
+        let dynamic_tool = find_namespace_function_tool(&tools, "codex_app", tool_name);
+        assert_eq!(dynamic_tool.defer_loading, Some(true));
+    }
     assert!(handlers.contains(&ToolHandlerSpec {
         name: ToolName::plain(TOOL_SEARCH_TOOL_NAME),
         kind: ToolHandlerKind::ToolSearch,
     }));
     assert!(handlers.contains(&ToolHandlerSpec {
-        name: ToolName::plain("automation_update"),
+        name: ToolName::namespaced("codex_app", "automation_update"),
+        kind: ToolHandlerKind::DynamicTool,
+    }));
+    assert!(handlers.contains(&ToolHandlerSpec {
+        name: ToolName::namespaced("codex_app", "automation_list"),
         kind: ToolHandlerKind::DynamicTool,
     }));
 }

codex-rs/tools/src/tool_spec.rs

@@ -1,5 +1,6 @@
 use crate::FreeformTool;
 use crate::JsonSchema;
+use crate::LoadableToolSpec;
 use crate::ResponsesApiNamespace;
 use crate::ResponsesApiTool;
 use codex_protocol::config_types::WebSearchConfig;
@@ -70,6 +71,15 @@ impl ToolSpec {
     }
 }
 
+impl From<LoadableToolSpec> for ToolSpec {
+    fn from(value: LoadableToolSpec) -> Self {
+        match value {
+            LoadableToolSpec::Function(tool) => ToolSpec::Function(tool),
+            LoadableToolSpec::Namespace(namespace) => ToolSpec::Namespace(namespace),
+        }
+    }
+}
+
 pub fn create_local_shell_tool() -> ToolSpec {
     ToolSpec::LocalShell {}
 }