d7f99b0fa6
- [x] Expand tool search to custom MCPs.
- [x] Rename several variables/fields to be more generic.
Updated tool & server name lifecycles:
**Raw Identity**
ToolInfo.server_name is raw MCP server name.
ToolInfo.tool.name is raw MCP tool name.
MCP calls route back to raw via parse_tool_name() returning
(tool.server_name, tool.tool.name).
mcpServerStatus/list now groups by raw server and keys tools by
Tool.name: mod.rs:599
App-server just forwards that grouped raw snapshot:
codex_message_processor.rs:5245
**Callable Names**
On list-tools, we create provisional callable_namespace / callable_name:
mcp_connection_manager.rs:1556
For non-app MCP, provisional callable name starts as raw tool name.
For codex-apps, provisional callable name is sanitized and strips
connector name/id prefix; namespace includes connector name.
Then qualify_tools() sanitizes callable namespace + name to ASCII alnum
/ _ only: mcp_tool_names.rs:128
Note: this is stricter than Responses API. Hyphen is currently replaced
with _ for code-mode compatibility.
**Collision Handling**
We do initially collapse example-server and example_server to the same
base.
Then qualify_tools() detects distinct raw namespace identities behind
the same sanitized namespace and appends a hash to the callable
namespace: mcp_tool_names.rs:137
Same idea for tool-name collisions: hash suffix goes on callable tool
name.
Final list_all_tools() map key is callable_namespace + callable_name:
mcp_connection_manager.rs:769
**Direct Model Tools**
Direct MCP tool declarations use the full qualified sanitized key as the
Responses function name.
The raw rmcp Tool is converted but renamed for model exposure.
**Tool Search / Deferred**
Tool search result namespace = final ToolInfo.callable_namespace:
tool_search.rs:85
Tool search result nested name = final ToolInfo.callable_name:
tool_search.rs:86
Deferred tool handler is registered as "{namespace}:{name}":
tool_registry_plan.rs:248
When a function call comes back, core recombines namespace + name, looks
up the full qualified key, and gets the raw server/tool for MCP
execution: codex.rs:4353
**Separate Legacy Snapshot**
collect_mcp_snapshot_from_manager_with_detail() still returns a map
keyed by qualified callable name.
mcpServerStatus/list no longer uses that; it uses
McpServerStatusSnapshot, which is raw-inventory shaped.
codex-tools
codex-tools is intended to become the home for tool-related code that is
shared across multiple crates and does not need to stay coupled to
codex-core.
Today this crate is intentionally small. It currently owns the shared tool
schema and Responses API tool primitives that no longer need to live in
core/src/tools/spec.rs or core/src/client_common.rs:
JsonSchemaAdditionalPropertiesToolDefinitionToolSpecConfiguredToolSpecResponsesApiToolFreeformToolFreeformToolFormatToolSearchOutputToolResponsesApiWebSearchFiltersResponsesApiWebSearchUserLocationResponsesApiNamespaceResponsesApiNamespaceTool- code-mode
ToolSpecadapters andexec/waitspec builders - JS REPL spec builders
- MCP resource,
list_dir, andtest_sync_toolspec builders - local host tool spec builders for shell/exec/request-permissions/view-image
- collaboration and agent-job
ToolSpecbuilders for spawn/send/wait/close,request_user_input, and CSV fanout/reporting - discoverable-tool models, client filtering, and
ToolSpecbuilders fortool_searchandtool_suggest parse_tool_input_schema()parse_dynamic_tool()parse_mcp_tool()create_tools_json_for_responses_api()mcp_call_tool_result_output_schema()tool_definition_to_responses_api_tool()dynamic_tool_to_responses_api_tool()mcp_tool_to_responses_api_tool()mcp_tool_to_deferred_responses_api_tool()augment_tool_spec_for_code_mode()tool_spec_to_code_mode_tool_definition()
That extraction is the first step in a longer migration. The goal is not to
move all of core/src/tools into this crate in one shot. Instead, the plan is
to peel off reusable pieces in reviewable increments while keeping
compatibility-sensitive orchestration in codex-core until the surrounding
boundaries are ready.
Vision
Over time, this crate should hold tool-facing primitives that are shared by multiple consumers, for example:
- schema and spec data models
- tool input/output parsing helpers
- tool metadata and compatibility shims that do not depend on
codex-core - other narrowly scoped utility code that multiple crates need
The corresponding non-goals are just as important:
- do not move
codex-coreorchestration here prematurely - do not pull
Session/TurnContext/ approval flow / runtime execution logic into this crate unless those dependencies have first been split into stable shared interfaces - do not turn this crate into a grab-bag for unrelated helper code
Migration approach
The expected migration shape is:
- Move low-coupling tool primitives here.
- Switch non-core consumers to depend on
codex-toolsdirectly. - Leave compatibility-sensitive adapters in
codex-corewhile downstream call sites are updated. - Only extract higher-level tool infrastructure after the crate boundaries are clear and independently testable.
That means it is normal for codex-core to temporarily re-export types or
helpers from codex-tools during the transition.
Crate conventions
This crate should start with stricter structure than core/src/tools so it
stays easy to grow:
src/lib.rsshould remain exports-only.- Business logic should live in named module files such as
foo.rs. - Unit tests for
foo.rsshould live in a siblingfoo_tests.rs. - The implementation file should wire tests with:
#[cfg(test)]
#[path = "foo_tests.rs"]
mod tests;
If this crate starts accumulating code that needs runtime state from
codex-core, that is a sign to revisit the extraction boundary before adding
more here.