Tool Registry and Configuration

Relevant source files

• codex-rs/core/src/features.rs
• codex-rs/core/src/features/legacy.rs
• codex-rs/core/src/tools/handlers/mod.rs
• codex-rs/core/src/tools/spec.rs
• codex-rs/core/tests/suite/deprecation_notice.rs
• codex-rs/core/tests/suite/model_tools.rs
• codex-rs/core/tests/suite/prompt_caching.rs

This page documents how tools are registered and made available to the model during conversation turns. It covers the ToolsConfig creation process, tool specification structure, JSON schema parameter definitions, and how feature flags and model capabilities determine which tools are exposed.

For information about specific tool implementations (shell, patch, etc.), see their respective sections under Tool System. For MCP tool integration, see Model Context Protocol. For the feature flag system that controls tool availability, see Feature Flags and Stages.

Overview

Tools are functions that the model can invoke to interact with the system. The tool registry determines which tools are available for a given session based on:

• Feature flags - User-configured toggles that enable/disable tool categories
• Model capabilities - Which tools the model supports (e.g., some models require specific shell tool variants)
• Runtime configuration - Settings like web search mode, agent roles, etc.

The central configuration object is ToolsConfig, which is constructed once per turn and drives tool registration.

Sources: codex-rs/core/src/tools/spec.rs36-122

ToolsConfig Creation Flow

ToolsConfig Creation Process

The ToolsConfig::new() method evaluates features and model capabilities to produce an effective tool configuration. Key decisions include:

Configuration Field	Decision Logic
shell_type	If ShellTool disabled → Disabled If ShellZshFork enabled → ShellCommand If UnifiedExec enabled + ConPTY supported → UnifiedExec Otherwise → model's preferred shell_type
apply_patch_tool_type	Model specifies type (Function/Freeform), or ApplyPatchFreeform feature enables Freeform variant
web_search_mode	From config (Live/Cached/Disabled)
search_tool	Enabled if Apps feature is enabled
js_repl_enabled	Enabled if JsRepl feature is enabled
collab_tools	Enabled if Collab feature is enabled

Sources: codex-rs/core/src/tools/spec.rs56-122

Tool Specification Structure

Tools are defined as ToolSpec enums with two variants:

Function Tools (ResponsesApiTool) are structured tools with strict JSON schemas. Examples:

• exec_command - Execute shell commands with structured parameters
• apply_patch - Apply file patches with JSON-defined changes
• spawn_agent - Create sub-agents with typed configuration

Freeform Tools (FreeformTool) accept unstructured text or line-based input. Examples:

• apply_patch (freeform variant) - Apply patches using natural diff format
• Legacy tools that predate structured function calling

Sources: codex-rs/core/src/client_common/tools.rs codex-rs/core/src/tools/spec.rs1-31

JSON Schema Parameter Definitions

Tool parameters are defined using the JsonSchema enum, which supports a subset of JSON Schema sufficient for tool definitions:

Example: exec_command Tool Parameters

The create_exec_command_tool() function builds a complex parameter schema:

Parameter	Type	Description
cmd	String	Shell command to execute (required)
workdir	String	Working directory (optional)
shell	String	Shell binary to use (optional)
tty	Boolean	Allocate TTY for command (optional)
login	Boolean	Run with login shell semantics (optional, if allow_login_shell)
yield_time_ms	Number	Wait time before yielding (optional)
max_output_tokens	Number	Token limit for output (optional)
sandbox_permissions	String	Sandbox permission level (from create_approval_parameters())
justification	String	User approval justification (from create_approval_parameters())
prefix_rule	Array[String]	Suggested command prefix pattern (from create_approval_parameters())

All shell and execution tools include approval parameters via create_approval_parameters(), which adds fields for sandbox escalation requests.

Sources: codex-rs/core/src/tools/spec.rs180-295

Feature-to-Tool Mapping

The following table shows which features enable specific tools or tool variants:

Feature Flag	Affected Tools	Effect
Feature::ShellTool	shell/shell_command/exec_command/write_stdin	Disables all shell execution when disabled
Feature::UnifiedExec	exec_command, write_stdin	Switches to PTY-based unified exec system (non-Windows default)
Feature::ShellZshFork	shell_command	Routes shell through zsh exec bridge
Feature::ApplyPatchFreeform	apply_patch (freeform)	Enables freeform patch variant instead of/in addition to JSON
Feature::JsRepl	js_repl, js_repl_reset	Enables JavaScript REPL tools backed by persistent Node kernel
Feature::JsReplToolsOnly	(all non-js_repl tools)	When combined with JsRepl, exposes ONLY js_repl tools
Feature::Apps	search_tool_bm25	Enables BM25 search over connected app tools
Feature::Collab	spawn_agent, send_input, resume_agent, wait, close_agent, test_sync_tool	Enables multi-agent collaboration tools
Feature::CollaborationModes	update_plan	Enables plan tracking tool (distinct from multi-agent)
Feature::WebSearchRequest	web_search	Deprecated: controlled by web_search_mode config instead
Feature::WebSearchCached	web_search	Deprecated: controlled by web_search_mode config instead

Special Cases:

• If JsReplToolsOnly is enabled but JsRepl is not, the flag is ignored with a warning
• Windows systems skip UnifiedExec if ConPTY is not supported, falling back to ShellCommand
• The search_tool_bm25 is only exposed when MCP app tools are available

Sources: codex-rs/core/src/tools/spec.rs56-111 codex-rs/core/src/features.rs73-146

Tool Creation Functions

Each tool is constructed by a dedicated function that returns a ToolSpec:

Common Parameter Patterns:

• Approval Parameters (create_approval_parameters()) - Added to all execution tools:

  • sandbox_permissions: "use_default" or "require_escalated"
  • justification: Explanation for sandbox escalation
  • prefix_rule: Suggested command pattern for future auto-approval

• Input Items Schema (create_collab_input_items_schema()) - Used by multi-agent tools for structured messages with text, images, skills, and app mentions

• Timing Parameters - Many tools include:

  • timeout_ms or yield_time_ms: Control execution duration
  • max_output_tokens: Limit response size

Sources: codex-rs/core/src/tools/spec.rs221-839

Tool Registry Building

The ToolRegistryBuilder constructs the final tool registry by evaluating ToolsConfig:

Tool Registration Order:

1. Shell tools - Based on shell_type configuration
2. File manipulation tools - apply_patch, read_file, list_dir, grep_files
3. Multi-agent tools - If collab_tools enabled
4. Search tools - If search_tool enabled and app tools available
5. JS REPL tools - If js_repl_enabled (unless js_repl_tools_only)
6. MCP tools - Dynamically loaded from external MCP servers
7. Standard utility tools - view_image, request_user_input (always included)

The registry builder filters and deduplicates tools, handles MCP tool naming with delimiters, and ensures tool specifications match the model's capabilities.

Sources: codex-rs/core/src/tools/registry.rs codex-rs/core/src/tools/spec.rs36-48

Model-Specific Tool Selection

Different models have different tool support levels. The ModelInfo struct communicates model capabilities:

Model Type	Shell Type	Apply Patch Type	Experimental Supported Tools
gpt-5	Shell	None (instructions appended)	web_search, update_plan, request_user_input, etc.
gpt-5.1	ShellCommand	Function	web_search, update_plan, request_user_input, etc.
gpt-5.1-codex	ShellCommand	Function	web_search, update_plan, request_user_input, etc.
gpt-5.1-codex-max	ShellCommand	Function	web_search, update_plan, request_user_input, etc.
o3	ShellCommand	Function	Limited set

Compatibility Handling:

• If a model doesn't support the apply_patch function but needs patch capabilities, the system appends APPLY_PATCH_TOOL_INSTRUCTIONS to the base instructions instead
• Models that don't support structured shell commands fall back to the shell tool (array-based arguments passed to execvp())
• Windows-specific behavior: PowerShell commands are always documented with platform-specific examples

The test suite verifies tool consistency across models to ensure prompt caching remains stable.

Sources: codex-rs/core/tests/suite/prompt_caching.rs66-175 codex-rs/core/tests/suite/model_tools.rs56-149 codex-rs/core/src/tools/spec.rs56-111

Configuration Validation and Testing

The system includes extensive testing to ensure tool configuration stability:

Prompt Caching Consistency Tests verify that:

• Tool lists remain constant across multiple turns in the same session
• Tool names and parameter schemas don't change between requests
• Models that lack native apply_patch support receive consistent instruction augmentation
• Tool selection is stable across session overrides (cwd, permissions, model changes)

Model Tool Selection Tests verify that:

• Each model family exposes the expected set of tools
• Shell tool variants match model capabilities
• Apply patch tools are included where supported

Feature Flag Tests verify that:

• Under-development features are disabled by default
• Default-enabled features are marked as stable
• Deprecated features emit appropriate warnings
• Legacy aliases map to canonical feature names

Sources: codex-rs/core/tests/suite/prompt_caching.rs73-807 codex-rs/core/tests/suite/model_tools.rs66-149 codex-rs/core/src/features.rs708-767