Files
codex/codex-rs/tools
tongzhou wang f226c9ccfb Recheck rollout budgets before starting tool work (#61578)
## Why

A rollout budget can be exhausted while a tool call waits for an execution slot, approval, or a lifecycle callback. Checking only when scheduling the call can allow new work to start after the budget is exhausted.

## What changed

- Recheck the budget after acquiring an execution slot, immediately before starting a handler, and immediately before handing an MCP request to the server.
- Report refused calls as aborted in tool outputs, lifecycle callbacks, and dispatch traces, while allowing already-running work to complete.
- Track handler start time separately from dispatch waiting and preserve terminal outcomes when cancellation arrives during completion callbacks.

## Testing

Add regression coverage for queued calls and calls paused in start callbacks when the budget is exhausted. Verify MCP requests are blocked before handoff and retain successful results after handoff, and assert budget-stop state during remote compaction.

GitOrigin-RevId: 573730391452256592d3512f15929a2fbdf03c57
2026-11-14 23:52:50 +00:00
..

codex-tools

codex-tools is the shared support crate for building, adapting, and executing model-visible tools outside codex-core.

Today this crate owns the host-facing tool models and helpers that no longer need to live in core/src/tools/spec.rs or core/src/client_common.rs:

  • aggregate host models such as ToolSpec, ConfiguredToolSpec, LoadableToolSpec, ResponsesApiNamespace, and ResponsesApiNamespaceTool
  • host discovery models used while assembling tool sets, including discoverable-tool models and request-plugin-install helpers
  • host adapters such as schema sanitization, MCP/dynamic conversion, code-mode augmentation, and image-detail normalization
  • shared executable-tool contracts such as ToolExecutor, ToolCall, and ToolOutput

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 host-side tool machinery that is shared by multiple consumers, for example:

  • host-visible aggregate tool models
  • tool-set planning and discovery helpers
  • MCP and dynamic-tool adaptation into Responses API shapes
  • code-mode compatibility shims that do not depend on codex-core
  • other narrowly scoped host utilities that multiple crates need

The corresponding non-goals are just as important:

  • do not move codex-core orchestration 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:

  1. Keep extension-owned executable-tool authoring in codex-extension-api.
  2. Move host-side planning/adaptation helpers here when they no longer need to stay coupled to codex-core.
  3. Leave compatibility-sensitive adapters in codex-core while downstream call sites are updated.
  4. Only extract higher-level host infrastructure after the crate boundaries are clear and independently testable.

Crate conventions

This crate should start with stricter structure than core/src/tools so it stays easy to grow:

  • src/lib.rs should remain exports-only.
  • Business logic should live in named module files such as foo.rs.
  • Unit tests for foo.rs should live in a sibling foo_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.