codex-tools: extract dynamic tool adapters (#15944)

## Why

`codex-tools` already owned the shared JSON schema parser and the MCP
tool schema adapter, but `core/src/tools/spec.rs` still parsed dynamic
tools directly.

That left the tool-schema boundary split in two different ways:

- MCP tools flowed through `codex-tools`, while dynamic tools were still
parsed in `codex-core`
- the extracted dynamic-tool path initially introduced a
dynamic-specific parsed shape even though `codex-tools` already had very
similar MCP adapter output

This change finishes that extraction boundary in one step. `codex-core`
still owns `ResponsesApiTool` assembly, but both MCP tools and dynamic
tools now enter that layer through `codex-tools` using the same parsed
tool-definition shape.

## What changed

- added `tools/src/dynamic_tool.rs` and sibling
`tools/src/dynamic_tool_tests.rs`
- introduced `parse_dynamic_tool()` in `codex-tools` and switched
`core/src/tools/spec.rs` to use it for dynamic tools
- added `tools/src/parsed_tool_definition.rs` so both MCP and dynamic
adapters return the same `ParsedToolDefinition`
- updated `core/src/tools/spec.rs` to build `ResponsesApiTool` through a
shared local adapter helper instead of separate MCP and dynamic assembly
paths
- expanded `core/src/tools/spec_tests.rs` so the dynamic-tool adapter
test asserts the full converted `ResponsesApiTool`, including
`defer_loading`
- updated `codex-rs/tools/README.md` to reflect the shared parsed
tool-definition boundary

## Test plan

- `cargo test -p codex-tools`
- `cargo test -p codex-core --lib tools::spec::`

---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/15944).
* #15953
* __->__ #15944

codex-rs/tools/src/dynamic_tool.rs

@@ -0,0 +1,24 @@
+use crate::ParsedToolDefinition;
+use crate::parse_tool_input_schema;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
+
+pub fn parse_dynamic_tool(
+    tool: &DynamicToolSpec,
+) -> Result<ParsedToolDefinition, serde_json::Error> {
+    let DynamicToolSpec {
+        name: _,
+        description,
+        input_schema,
+        defer_loading,
+    } = tool;
+    Ok(ParsedToolDefinition {
+        description: description.clone(),
+        input_schema: parse_tool_input_schema(input_schema)?,
+        output_schema: None,
+        defer_loading: *defer_loading,
+    })
+}
+
+#[cfg(test)]
+#[path = "dynamic_tool_tests.rs"]
+mod tests;

codex-rs/tools/src/dynamic_tool_tests.rs

@@ -0,0 +1,68 @@
+use super::parse_dynamic_tool;
+use crate::JsonSchema;
+use crate::ParsedToolDefinition;
+use codex_protocol::dynamic_tools::DynamicToolSpec;
+use pretty_assertions::assert_eq;
+use std::collections::BTreeMap;
+
+#[test]
+fn parse_dynamic_tool_sanitizes_input_schema() {
+    let tool = DynamicToolSpec {
+        name: "lookup_ticket".to_string(),
+        description: "Fetch a ticket".to_string(),
+        input_schema: serde_json::json!({
+            "properties": {
+                "id": {
+                    "description": "Ticket identifier"
+                }
+            }
+        }),
+        defer_loading: false,
+    };
+
+    assert_eq!(
+        parse_dynamic_tool(&tool).expect("parse dynamic tool"),
+        ParsedToolDefinition {
+            description: "Fetch a ticket".to_string(),
+            input_schema: JsonSchema::Object {
+                properties: BTreeMap::from([(
+                    "id".to_string(),
+                    JsonSchema::String {
+                        description: Some("Ticket identifier".to_string()),
+                    },
+                )]),
+                required: None,
+                additional_properties: None,
+            },
+            output_schema: None,
+            defer_loading: false,
+        }
+    );
+}
+
+#[test]
+fn parse_dynamic_tool_preserves_defer_loading() {
+    let tool = DynamicToolSpec {
+        name: "lookup_ticket".to_string(),
+        description: "Fetch a ticket".to_string(),
+        input_schema: serde_json::json!({
+            "type": "object",
+            "properties": {}
+        }),
+        defer_loading: true,
+    };
+
+    assert_eq!(
+        parse_dynamic_tool(&tool).expect("parse dynamic tool"),
+        ParsedToolDefinition {
+            description: "Fetch a ticket".to_string(),
+            input_schema: JsonSchema::Object {
+                properties: BTreeMap::new(),
+                required: None,
+                additional_properties: None,
+            },
+            output_schema: None,
+            defer_loading: true,
+        }
+    );
+}

codex-rs/tools/src/lib.rs

@@ -1,11 +1,14 @@
 //! Shared tool-schema parsing primitives that can live outside `codex-core`.
 
+mod dynamic_tool;
 mod json_schema;
 mod mcp_tool;
+mod parsed_tool_definition;
 
+pub use dynamic_tool::parse_dynamic_tool;
 pub use json_schema::AdditionalProperties;
 pub use json_schema::JsonSchema;
 pub use json_schema::parse_tool_input_schema;
-pub use mcp_tool::ParsedMcpTool;
 pub use mcp_tool::mcp_call_tool_result_output_schema;
 pub use mcp_tool::parse_mcp_tool;
+pub use parsed_tool_definition::ParsedToolDefinition;

codex-rs/tools/src/mcp_tool.rs

@@ -1,18 +1,9 @@
-use crate::JsonSchema;
+use crate::ParsedToolDefinition;
 use crate::parse_tool_input_schema;
 use serde_json::Value as JsonValue;
 use serde_json::json;
 
-/// Parsed MCP tool metadata and schemas that can be adapted into a higher-level
-/// tool spec by downstream crates.
-#[derive(Debug, PartialEq)]
-pub struct ParsedMcpTool {
-    pub description: String,
-    pub input_schema: JsonSchema,
-    pub output_schema: JsonValue,
-}
-
-pub fn parse_mcp_tool(tool: &rmcp::model::Tool) -> Result<ParsedMcpTool, serde_json::Error> {
+pub fn parse_mcp_tool(tool: &rmcp::model::Tool) -> Result<ParsedToolDefinition, serde_json::Error> {
     let mut serialized_input_schema = serde_json::Value::Object(tool.input_schema.as_ref().clone());
 
     // OpenAI models mandate the "properties" field in the schema. Some MCP
@@ -34,10 +25,13 @@ pub fn parse_mcp_tool(tool: &rmcp::model::Tool) -> Result<ParsedMcpTool, serde_j
         .map(|output_schema| serde_json::Value::Object(output_schema.as_ref().clone()))
         .unwrap_or_else(|| JsonValue::Object(serde_json::Map::new()));
 
-    Ok(ParsedMcpTool {
+    Ok(ParsedToolDefinition {
         description: tool.description.clone().map(Into::into).unwrap_or_default(),
         input_schema,
-        output_schema: mcp_call_tool_result_output_schema(structured_content_schema),
+        output_schema: Some(mcp_call_tool_result_output_schema(
+            structured_content_schema,
+        )),
+        defer_loading: false,
     })
 }
 

codex-rs/tools/src/mcp_tool_tests.rs

@@ -1,7 +1,7 @@
-use super::ParsedMcpTool;
 use super::mcp_call_tool_result_output_schema;
 use super::parse_mcp_tool;
 use crate::JsonSchema;
+use crate::ParsedToolDefinition;
 use pretty_assertions::assert_eq;
 use std::collections::BTreeMap;
 
@@ -31,14 +31,15 @@ fn parse_mcp_tool_inserts_empty_properties() {
 
     assert_eq!(
         parse_mcp_tool(&tool).expect("parse MCP tool"),
-        ParsedMcpTool {
+        ParsedToolDefinition {
             description: "No properties".to_string(),
             input_schema: JsonSchema::Object {
                 properties: BTreeMap::new(),
                 required: None,
                 additional_properties: None,
             },
-            output_schema: mcp_call_tool_result_output_schema(serde_json::json!({})),
+            output_schema: Some(mcp_call_tool_result_output_schema(serde_json::json!({}))),
+            defer_loading: false,
         }
     );
 }
@@ -67,14 +68,14 @@ fn parse_mcp_tool_preserves_top_level_output_schema() {
 
     assert_eq!(
         parse_mcp_tool(&tool).expect("parse MCP tool"),
-        ParsedMcpTool {
+        ParsedToolDefinition {
             description: "Has output schema".to_string(),
             input_schema: JsonSchema::Object {
                 properties: BTreeMap::new(),
                 required: None,
                 additional_properties: None,
             },
-            output_schema: mcp_call_tool_result_output_schema(serde_json::json!({
+            output_schema: Some(mcp_call_tool_result_output_schema(serde_json::json!({
                 "properties": {
                     "result": {
                         "properties": {
@@ -83,7 +84,8 @@ fn parse_mcp_tool_preserves_top_level_output_schema() {
                     }
                 },
                 "required": ["result"]
-            })),
+            }))),
+            defer_loading: false,
         }
     );
 }
@@ -105,16 +107,17 @@ fn parse_mcp_tool_preserves_output_schema_without_inferred_type() {
 
     assert_eq!(
         parse_mcp_tool(&tool).expect("parse MCP tool"),
-        ParsedMcpTool {
+        ParsedToolDefinition {
             description: "Has enum output schema".to_string(),
             input_schema: JsonSchema::Object {
                 properties: BTreeMap::new(),
                 required: None,
                 additional_properties: None,
             },
-            output_schema: mcp_call_tool_result_output_schema(serde_json::json!({
+            output_schema: Some(mcp_call_tool_result_output_schema(serde_json::json!({
                 "enum": ["ok", "error"]
-            })),
+            }))),
+            defer_loading: false,
         }
     );
 }

codex-rs/tools/src/parsed_tool_definition.rs

@@ -0,0 +1,12 @@
+use crate::JsonSchema;
+use serde_json::Value as JsonValue;
+
+/// Parsed tool metadata and schemas that downstream crates can adapt into
+/// higher-level tool specs.
+#[derive(Debug, PartialEq)]
+pub struct ParsedToolDefinition {
+    pub description: String,
+    pub input_schema: JsonSchema,
+    pub output_schema: Option<JsonValue>,
+    pub defer_loading: bool,
+}