86 Commits

• [codex] trace tools build latency (#28782)

  Add more tracing spans around tool building.

  Owen Lin · 2026-06-17 14:53:54 -07:00
  38211a3ff8
• Respect blocking PostToolUse hooks in code mode (#28365)

  ## Summary
  
  Make blocking hook behavior reliable for tools invoked from code mode.
  
  Previously, a `PostToolUse` hook could block a completed tool result,
  but code mode would still return the original typed result to
  JavaScript. The hook appeared blocked in hook telemetry while the
  running script continued with the result.
  
  This change:
  
  - rejects the nested JavaScript tool promise when `PostToolUse` blocks
  - normalizes `decision: "block"` and exit code 2 to the same blocking
  behavior
  - surfaces the hook feedback as the rejected promise's error
  - adds end-to-end coverage for the relevant PreToolUse and PostToolUse
  interactions
  
  ## Hook semantics in code mode
  
  | Hook behavior | Code-mode result |
  |---|---|
  | PreToolUse block | Reject the promise before the tool executes |
  | PreToolUse `updatedInput` | Execute the rewritten invocation and
  return its result |
  | PostToolUse `decision: "block"` | Execute the tool, then reject the
  promise with the hook reason |
  | PostToolUse exit code 2 | Same behavior as `decision: "block"` |
  | PostToolUse `continue: false` | Preserve the existing feedback-only
  behavior; do not reject the promise |
  
  ## Test coverage
  
  Added or strengthened end-to-end coverage proving that:
  
  - a PreToolUse block rejects the JavaScript promise before execution
  - a PreToolUse input rewrite executes only the rewritten command
  - JavaScript receives the rewritten command's result
  - PostToolUse `decision: "block"` rejects after the command executes
  - PostToolUse exit code 2 has the same behavior
  - the hook observes the original completed tool response
  - the blocked original result does not reach JavaScript
  - existing direct-mode replacement behavior remains intact
  - `continue: false` without a reason produces deterministic fallback
  feedback

  Abhinav · 2026-06-15 15:12:26 -07:00
  d7f298fe20
• [codex] simplify memory read metrics (#28164)

  ## Why
  
  Memory read telemetry currently reconstructs the executable shell
  command after a tool call finishes. That duplicates shell, login-policy,
  and cwd resolution owned by the tool handlers, and can diverge from the
  environment-specific command that unified exec actually ran.
  
  ## What changed
  
  - Expose the existing restricted shell-script parser directly for raw
  script text.
  - Parse `shell_command` and `exec_command` input into plain command argv
  before classifying memory reads.
  - Preserve all-or-nothing safe-command validation for multi-command
  scripts.
  - Remove cwd resolution, shell selection, and the unnecessary async
  boundary from memory read metric emission.
  
  ## Testing
  
  - `just test -p codex-shell-command`
  - `cargo check -p codex-core`

  pakrym-oai · 2026-06-15 08:28:02 -07:00
  42ad752f36
• [codex] Remove async_trait from ToolExecutor (#27304)

  ## Why
  
  We're now [discouraging use of
  `async_trait`](https://github.com/openai/codex/pull/20242).
  
  Removing use of `async_trait` from `ToolExecutor` yields a `codex_core`
  debug test build speedup of ~78% (from 227.5s to 50.3s) on my machine.
  
  Stacked on #27299, this PR applies the trait change after the handler
  bodies have been outlined.
  
  ## What
  
  Changed `ToolExecutor::handle` to return an explicit boxed
  `ToolExecutorFuture` instead of using `async_trait`.
  
  Updated ToolExecutor implementors to return `Box::pin(...)`, reexported
  the future alias through `codex-tools` and `codex-extension-api`, and
  removed `codex-tools` direct `async-trait` dependency.

  Adam Perry @ OpenAI · 2026-06-10 10:26:53 -07:00
  2704ecea9a
• [codex] Exclude external tool output from memories (#26821)

  ## Summary
  
  - add contains_external_context() to tool output so other tools can be
  opted out of influencing memory when disable_on_external_context=true
  - Classify standalone web-search output as external context (to match
  behavior as hosted web search)
  - Verify with integration test

  rka-oai · 2026-06-08 16:53:04 +00:00
  26d9329833
• [2 of 2] Finish moving goal runtime to extension (#26548)

  ## Stack
  
  1. [#26547](https://github.com/openai/codex/pull/26547) - [1 of 2] Align
  goal extension with core behavior
  2. [#26548](https://github.com/openai/codex/pull/26548) - [2 of 2] Move
  goal runtime to extension
  
  ## Why
  
  This PR completes the switch of the goal behavior to the
  extension-backed runtime and removes the old core goal implementation.
  
  ## What Changed
  
  - Installs the goal extension for app-server `ThreadManager` sessions.
  - Routes app-server thread goal `get`, `set`, and `clear` through
  `GoalService`.
  - Uses thread-idle lifecycle emission after goal resume and snapshot
  ordering so the extension can decide whether to continue the goal.
  - Forwards extension goal updates through a FIFO async app-server
  notification path so backpressure does not drop them or reorder updates.
  - Keeps review turns from enabling goal runtime behavior.
  - Plans extension tools before dynamic tools so built-in goal tool names
  keep their old precedence when goals are enabled.
  - Removes the old core goal runtime, core goal tool handlers, and core
  goal tool specs.
  - Updates tests that were coupled to the core-owned goal runtime while
  leaving the legacy `<goal_context>` compatibility path in core for old
  threads.
  - Removes the stale cargo-shear ignore now that `codex-goal-extension`
  is used by the workspace.
  - Keeps realtime event matching exhaustive after removing the old
  goal-specific realtime text path.
  
  
  ## Validation
  
  - Ran manual `/goal` runs in TUI. Validated time accounting matched
  wall-clock time and goal lifecycle state transitions.

  Eric Traut · 2026-06-05 14:17:30 -07:00
  479a14cf59
• Move tool search metadata onto ToolExecutor (#25684)

  Deferred tools need to be searchable even when they are not implemented
  inside `codex-core`. Extension-provided tools can be registered for
  later discovery, but the search metadata path was still owned by
  core-specific runtime hooks, which meant the shared `ToolExecutor`
  abstraction could not describe how a deferred extension tool should
  appear in `tool_search`.
  
  ## Changes
  
  - Move `ToolSearchEntry` and `ToolSearchInfo` into `codex-tools` and
  re-export them from the shared tools crate.
  - Add a default `ToolExecutor::search_info` implementation that derives
  loadable tool-search metadata from function and namespace specs.
  - Forward search metadata through extension adapters and exposure
  overrides while keeping custom search text/source metadata for dynamic,
  MCP, and multi-agent tools.
  - Remove the old core-local `tool_search_entry` module now that search
  metadata lives with the shared executor APIs.
  
  ## Testing
  
  - Added `deferred_extension_tools_are_discoverable_with_tool_search`
  coverage in `core/src/tools/spec_plan_tests.rs`.

  jif-oai · 2026-06-02 00:24:41 +02:00
  8d720feb69
• fix(linux-sandbox): preserve shell cleanup on interruption (#22729)

  ## Why
  Interrupted `shell_command` calls can race with the outer tool-dispatch
  cancellation path. When that happens, the runtime future may be dropped
  before the spawned process gets a chance to run `SIGTERM` cleanup. For
  bwrapd-backed Linux sandbox commands, that can leave synthetic
  protected-path mount bookkeeping such as `.git/.codex` registrations
  under `/tmp` behind after a TUI interruption.
  
  The relevant cancellation points are the outer dispatch race in
  [`core/src/tools/parallel.rs`](https://github.com/openai/codex/blob/bd184ba84703cc924921ed883f0cf17d3dba60ff/codex-rs/core/src/tools/parallel.rs#L91-L132)
  and the process shutdown logic in
  [`core/src/exec.rs`](https://github.com/openai/codex/blob/bd184ba84703cc924921ed883f0cf17d3dba60ff/codex-rs/core/src/exec.rs#L1367-L1393).
  
  ## What changed
  - Keep `shell_command` dispatch alive long enough for the runtime to
  finish cancellation cleanup instead of immediately returning the
  synthetic aborted response.
  - Fold shell-turn cancellation into the existing `ExecExpiration` path
  in
  [`core/src/tools/runtimes/shell.rs`](https://github.com/openai/codex/blob/bd184ba84703cc924921ed883f0cf17d3dba60ff/codex-rs/core/src/tools/runtimes/shell.rs#L267-L274),
  so cancellation and timeout behavior stay centralized.
  - On cancellation, send `SIGTERM` first, wait briefly for cleanup to
  run, then hard-kill any remaining descendants in the original process
  group.
  - Treat `ESRCH` as an already-gone process-group cleanup case in
  `codex-utils-pty`, which keeps best-effort teardown from surfacing a
  stale-process race as an error.
  
  ## Verification
  - `cargo test -p codex-core cancellation`
  - Added regression coverage for:
    - `shell_tool_cancellation_waits_for_runtime_cleanup`
    - `process_exec_tool_call_cancellation_allows_sigterm_cleanup`

  viyatb-oai · 2026-05-27 12:59:11 -07:00
  9152ebd289
• Default function tools into tool hooks (#23757)

  # Why
  
  `PreToolUse`, `PostToolUse`, and `updatedInput` coverage for local
  function tools currently depends on each handler remembering to wire up
  the hook contract itself. That makes coverage easy to miss as new
  function tools are added, even though most of them share the same basic
  shape: a model-facing function call with JSON arguments.
  
  # What
  
  This makes `CoreToolRuntime` provide the default hook contract for
  ordinary local function tools:
  
  - build generic `PreToolUse` and `PostToolUse` payloads from the
  function tool name and arguments
  - apply `updatedInput` rewrites back into function-tool arguments
  through the same default path
  - let tool outputs override the post-hook input or response when they
  have a more stable hook-facing contract
  
  The exceptions stay explicit:
  
  - hosted tools remain outside the generic local function path
  - code-mode `wait` and `write_stdin` opt out for now
  - `PostToolUse` feedback replaces only the model-visible response, so
  code mode keeps its typed tool result
  
  With the generic path in place, the MCP and extension-tool adapters no
  longer need their own duplicate pre/post hook plumbing. The new coverage
  exercises the registry default plus end-to-end local function behavior
  for pre-hook blocking, `updatedInput` rewriting, and post-hook context.

  Abhinav · 2026-05-23 00:56:58 +00:00
  5c20513a1b
• refactor: centralize tool exposure planning (#23876)

  ## Why
  
  Tool exposure is a planning concern, but the deferred MCP path and
  dispatch-only legacy shell path were carrying those decisions in handler
  constructors and a shell-only tool-family builder. Keeping those
  decisions in `spec_plan` makes the core tool plan easier to follow and
  keeps handlers focused on runtime behavior.
  
  ## What changed
  
  - add `PlannedTools` helpers for ordinary runtimes, exposure overrides,
  dispatch-only runtimes, and hosted specs
  - inline shell tool assembly into `core/src/tools/spec_plan.rs` and
  remove the shell-only `tool_family` module
  - remove exposure state and special exposure constructors from
  `McpHandler` and `ShellCommandHandler`
  - keep hidden runtime behavior centralized in `ExposureOverride`,
  including disabling parallel tool calls for hidden handlers
  
  ## Testing
  
  - Not run (refactor only)

  jif-oai · 2026-05-21 16:21:23 +02:00
  e6c8371e4e
• Make tool executor specs mandatory (#23870)

  ## Why
  
  `ToolExecutor` is the runtime contract that keeps a callable tool and
  its model-visible spec together. Leaving `spec()` optional lets a
  registered runtime silently omit that half of the contract, and it also
  overloads a missing spec as an exposure decision for tools that should
  stay dispatchable without being shown to the model.
  
  ## What
  
  - Make `ToolExecutor::spec()` required and update core, extension, and
  test tool executors to return a concrete `ToolSpec`.
  - Add `ToolExposure::Hidden` for dispatch-only tools. The legacy
  `shell_command` runtime in unified-exec sessions now uses that explicit
  exposure instead of hiding itself by omitting a spec.
  - Build MCP tool specs when `McpHandler` is constructed so invalid MCP
  specs are skipped before the handler is registered.
  - Keep tool planning aligned with the new contract for direct, deferred,
  hidden, code-mode, dynamic, and namespaced tool paths.
  
  ## Testing
  
  - Added tool-plan coverage that invalid MCP tool specs are not
  registered.
  - Updated shell-family coverage for the hidden legacy `shell_command`
  runtime and the affected tool executor test fixtures.

  jif-oai · 2026-05-21 15:25:56 +02:00
  516f134641
• Remove ToolsConfig from tool planning (#22835)

  ## Why
  
  `codex-tools` is meant to hold reusable tool primitives, but
  `ToolsConfig` had become a second copy of core runtime decisions instead
  of a small shared contract. It carried provider capabilities, auth/model
  gates, permission and environment state, web/search/image feature gates,
  multi-agent settings, and goal availability from core into `codex-tools`
  ([definition](https://github.com/openai/codex/blob/22dd9ad3929253ed24d7ee4f10f238e95ab25f37/codex-rs/tools/src/tool_config.rs#L97),
  [stored on each
  `TurnContext`](https://github.com/openai/codex/blob/22dd9ad3929253ed24d7ee4f10f238e95ab25f37/codex-rs/core/src/session/turn_context.rs#L87)).
  Every session/context variant then had to build and mutate that snapshot
  before assembling tools.
  
  This PR removes that master object instead of renaming it. Tool planning
  now reads the live `TurnContext`, where `codex-core` already owns those
  decisions, while `codex-tools` keeps only reusable primitives and a
  generic `ToolSetBuilder`/`ToolSet` accumulator.
  
  ## What Changed
  
  - Removed `ToolsConfig` / `ToolsConfigParams` from `codex-tools`; the
  crate keeps the shared helpers that still belong there, including
  request-user-input mode selection, shell backend/type resolution,
  `UnifiedExecShellMode`, and `ToolEnvironmentMode`.
  - Replaced config-snapshot planning with `ToolRouter::from_turn_context`
  and a `spec_plan` pipeline over `CoreToolPlanContext`, deriving provider
  capabilities, auth gates, model support, feature gates, environment
  count, goal support, multi-agent options, web search, and image
  generation from the authoritative turn state.
  - Added generic `codex_tools::ToolSetBuilder` / `ToolSet`, plus the
  small core adapter needed to accumulate `CoreToolRuntime` values and
  hosted model specs.
  - Added the `tool_family::shell` registration module and moved
  shell/unified-exec/memory accounting call sites to read the narrow
  per-turn fields directly.
  - Narrowed `TurnContext` to the remaining explicit per-turn fields
  needed by planning: `available_models`, `unified_exec_shell_mode`, and
  `goal_tools_supported`.
  - Reworked MCP exposure and tool-search setup so deferred/direct MCP
  behavior is driven by the current turn rather than a precomputed config
  snapshot.
  - Replaced the large expected-spec fixture tests with focused
  behavior-level coverage for shell tools, environments, goal and
  agent-job gates, MCP direct/deferred exposure, tool search,
  request-plugin-install, code mode, multi-agent mode, hosted tools, and
  extension executor dispatch.
  
  ## Verification
  
  - `cargo check -p codex-tools`
  - `cargo check -p codex-core --lib`
  - `cargo test -p codex-tools`
  - `cargo test -p codex-core spec_plan --lib`
  - `cargo test -p codex-core router --lib`

  jif-oai · 2026-05-19 11:24:09 +02:00
  05e171094d
• Add tool lifecycle extension contributor (#23309)

  ## Why
  
  Extensions that need to track runtime progress currently have no typed
  host signal for tool execution. The goal extension in particular needs
  to observe tool attempts without inspecting tool payloads, owning tool
  implementations, or staying coupled to core-only runtime plumbing.
  
  This adds a narrow lifecycle contributor API for host-owned tool
  execution: extensions can observe when an accepted tool call starts and
  how it finishes, while policy hooks and tool handlers continue to own
  payload rewriting, blocking, and execution.
  
  Relevant code:
  
  -
  [`ToolLifecycleContributor`](https://github.com/openai/codex/blob/3ad2850ffc7d8a1da19c65a92425637a59098f1b/codex-rs/ext/extension-api/src/contributors.rs#L119)
  defines the extension-facing observer contract.
  -
  [`tool_lifecycle.rs`](https://github.com/openai/codex/blob/3ad2850ffc7d8a1da19c65a92425637a59098f1b/codex-rs/ext/extension-api/src/contributors/tool_lifecycle.rs)
  defines the typed start/finish inputs, source, and outcome enums.
  - [`notify_tool_start` /
  `notify_tool_finish`](https://github.com/openai/codex/blob/3ad2850ffc7d8a1da19c65a92425637a59098f1b/codex-rs/core/src/tools/lifecycle.rs)
  bridges core tool dispatch into the extension registry.
  
  ## What Changed
  
  - Added `ToolLifecycleContributor` to `codex-extension-api`, including:
    - `ToolStartInput`
    - `ToolFinishInput`
    - `ToolCallSource`
    - `ToolCallOutcome`
  - Added registration and lookup support on `ExtensionRegistryBuilder` /
  `ExtensionRegistry`.
  - Wired core tool dispatch to notify lifecycle contributors for:
    - accepted tool starts
    - completed tool calls, including the tool output success marker
    - pre-tool-use blocks
    - failures before or after the handler runs
    - cancellation/abort in the parallel tool path
  - Registered the goal extension as a lifecycle contributor and added the
  outcome filter it will use for goal progress accounting.
  
  ## Test Coverage
  
  - Added `dispatch_notifies_tool_lifecycle_contributors` to cover
  lifecycle notification ordering and outcomes for successful and
  handler-failed tool calls.

  jif-oai · 2026-05-18 21:55:57 +02:00
  c69cde3547
• Make multi-agent v2 tool namespace configurable (#23147)

  ## Summary
  - Add `features.multi_agent_v2.tool_namespace` with config/schema
  validation for Responses-compatible namespace values.
  - Thread the resolved namespace into `ToolsConfig` for normal turns and
  review turns.
  - Wrap MultiAgentV2 tool specs and registry names in the configured
  namespace when namespace tools are supported, while falling back to the
  plain tool names when they are not.
  
  ## Validation
  - `just fmt`
  - `just write-config-schema`
  - `cargo test -p codex-features multi_agent_v2_feature_config --
  --nocapture`
  - `cargo test -p codex-core test_build_specs_multi_agent_v2 --
  --nocapture`
  - `cargo test -p codex-core multi_agent_v2_config -- --nocapture`
  - `cargo test -p codex-core
  multi_agent_v2_rejects_invalid_tool_namespace -- --nocapture`
  - `cargo test -p codex-tools`
  - `git diff --check`

  jif-oai · 2026-05-17 15:27:43 +02:00
  545ede569c
• Simplify tool executor and registry plumbing (#22636)

  ## Why
  
  The tool runtime path still had a typed output associated type on
  `ToolExecutor`, plus a core-only `RegisteredTool` adapter and
  extension-only executor aliases. That made every new shared tool runtime
  carry extra adapter plumbing before it could participate in core
  dispatch, extension tools, hook payloads, telemetry, and model-visible
  spec generation.
  
  This PR moves output erasure to the shared executor boundary so core and
  extension tools can use the same execution contract directly.
  
  ## What Changed
  
  - Changed `codex_tools::ToolExecutor` to return `Box<dyn ToolOutput>`
  instead of an associated `Output` type.
  - Removed the extension-specific `ExtensionToolExecutor` /
  `ExtensionToolOutput` aliases and exposed `ToolExecutor<ToolCall>` plus
  `ToolOutput` through `codex-extension-api`.
  - Reworked core tool registration around `CoreToolRuntime` and
  `ToolRegistry::from_tools`, removing the extra `RegisteredTool` /
  `ToolRegistryBuilder` layer.
  - Consolidated model-visible spec planning and registry construction in
  `core/src/tools/spec_plan.rs`, including deferred tool search and
  code-mode-only filtering.
  - Added `ToolOutput` helpers for post-tool-use hook ids and inputs so
  MCP, unified exec, extension, and other boxed outputs preserve the same
  hook payload behavior.
  - Updated core handlers, memories tools, and the related
  registry/spec/router tests to use the simplified contract.
  
  ## Test Coverage
  
  - Updated coverage for tool spec planning, registry lookup, deferred
  tool search registration, extension tool routing, post-tool-use hook
  payloads, dispatch tracing, guardian output extraction, and memories
  extension tool execution.

  jif-oai · 2026-05-15 11:47:54 +02:00
  6f1a01fbdd
• feat: make ToolExecutor an async trait (#22560)

  ## Why
  
  `codex_tools::ToolExecutor` keeps a tool spec attached to its runtime
  handler, but extension tools still carried a parallel
  `ExtensionToolFuture` / `ExtensionToolExecutor` shape. That made
  extension-owned tools look different from host tools even though
  routing, registration, and execution need the same abstraction.
  
  This PR makes the shared executor contract directly async and lets
  extension tools implement it too, so host tools and extension tools can
  move through the same registration path.
  
  ## What changed
  
  - Changed `ToolExecutor::handle` to an `async fn` using `async-trait`,
  and updated built-in tool handlers to implement the async trait
  directly.
  - Replaced the bespoke `ExtensionToolFuture` contract with a marker
  `ExtensionToolExecutor` over `ToolExecutor<ToolCall, Output =
  JsonToolOutput>`, re-exporting `ToolExecutor` from
  `codex-extension-api`.
  - Updated the memories extension tools to implement the shared executor
  trait.
  - Split tool-router construction into collected executors plus hosted
  model specs, keeping hosted tools like web search and image generation
  separate from executable handlers.
  - Updated spec/router tests and extension-tool stubs for the new
  executor shape.
  
  ## Verification
  
  - Not run locally.

  jif-oai · 2026-05-14 11:23:57 +02:00
  6d65686313
• feat: namespace in ext (#22556)
  jif-oai · 2026-05-14 00:37:48 +02:00
  e6939e3969
• Deprecate TurnContext cwd and resolve_path (#22519)

  ## Why
  
  `TurnContext::cwd` and `TurnContext::resolve_path` are being phased out
  in favor of using the selected turn environment cwd directly.
  Deprecating both APIs makes any new direct dependency visible while
  preserving the existing migration path for current callers.
  
  ## What Changed
  
  - Marked `TurnContext::cwd` and `TurnContext::resolve_path` as
  deprecated with guidance to use the selected turn environment cwd
  instead.
  - Added exact `#[allow(deprecated)]` suppressions at each existing
  direct usage site, including tests, rather than adding crate-wide
  suppression.
  - Kept the change behavior-preserving: current cwd reads, writes, and
  path resolution continue to use the same values.
  
  ## Verification
  
  - `just fmt`
  - `cargo check -p codex-core`
  - `cargo check -p codex-core --tests`
  - `git diff --check`

  pakrym-oai · 2026-05-13 11:15:25 -07:00
  4454e1411b
• feat: expose multi-agent v2 as model-only tools (#22514)

  ## Why
  
  `code_mode_only` filters code-mode nested tools out of the top-level
  tool list. For multi-agent v2, we need a rollout shape where the
  collaboration tools remain callable as normal model tools without also
  being embedded into the code-mode `exec` tool declaration.
  
  Related to this:
  https://openai-corpws.slack.com/archives/C0AQLHB4U75/p1778660267922549
  
  ## What Changed
  
  - Adds `features.multi_agent_v2.non_code_mode_only`, including config
  resolution, profile override handling, and generated schema coverage.
  - Introduces `ToolExposure::DirectModelOnly` so a tool can be included
  in the initial model-visible list while staying out of the nested
  code-mode tool surface.
  - Applies that exposure to the multi-agent v2 tools when the new flag is
  set: `spawn_agent`, `send_message`, `followup_task`, `wait_agent`,
  `close_agent`, and `list_agents`.
  - Updates code-mode-only filtering so direct-model-only tools remain
  visible while ordinary nested code-mode tools are still hidden.
  
  ## Verification
  
  - Added config parsing/profile tests for `non_code_mode_only`.
  - Added tool spec coverage for the code-mode-only multi-agent v2
  exposure behavior.

  jif-oai · 2026-05-13 19:49:47 +02:00
  fc26af377f
• Introduce tool exposure for deferred registration (#22489)

  ## Why
  
  Deferred tools were tracked with separate side-channel filtering after
  tool specs had already been assembled. That made the registry
  responsible for executing tools while the router/spec planner separately
  decided whether those same tools should be exposed to the model up
  front.
  
  This PR makes exposure part of the tool handler contract so direct
  versus deferred availability travels with the executable tool
  registration.
  
  Next step will be to simplify registration
  
  ## What Changed
  
  - Adds `ToolExposure` to `codex-tools` and exposes it through
  `ToolExecutor`, defaulting tools to `Direct`.
  - Teaches dynamic tools and MCP handlers to mark deferred tools as
  `Deferred` at construction time.
  - Renames the registry object-safe wrapper from `AnyToolHandler` to
  `RegisteredTool` and uses `ToolExposure` when deciding whether to
  include a handler's spec in the initial model-visible tool list.
  - Refactors tool spec planning to derive direct specs and deferred
  search entries from registered handlers, removing the router's
  special-case deferred dynamic tool filtering.
  
  ## Verification
  
  - Not run.

  jif-oai · 2026-05-13 18:16:51 +02:00
  fdda59c00b
• Refactor extension tools onto shared ToolExecutor (#22369)

  ## Why
  
  Extension tools were split across two public runtime contracts:
  `codex-tool-api` exposed `ToolBundle` plus its own call/spec/error
  types, while core native tools used `codex_tools::ToolExecutor`. That
  made contributed tool specs and execution behavior easy to drift apart
  and added another crate boundary for what should be one executable-tool
  seam.
  
  This PR makes `ToolExecutor` the single runtime contract and keeps
  extension-specific pinning in `codex-extension-api`.
  
  ## Remaining todo
  
  https://github.com/openai/codex/pull/22369/changes#diff-b935ea8245c3ce568a30cff660175fa6390b66b872ae409e1e2e965738250741R5
  Either generic `Invocation` or sub-extract the `ToolCall` and clean
  `ToolInvocation`
  
  ## What changed
  
  - Removed the `codex-tool-api` workspace crate and its dependencies from
  core and `codex-extension-api`.
  - Made `codex_tools::ToolExecutor` object-safe with `async_trait` so
  extension contributors can return a dyn executor.
  - Added the extension-facing aliases under
  `ext/extension-api/src/contributors/tools.rs`, including
  `ExtensionToolExecutor = dyn ToolExecutor<ToolCall, Output =
  ExtensionToolOutput>`.
  - Changed `ToolContributor::tools` to return extension executors
  directly instead of `ToolBundle`s.
  - Updated core’s extension tool handler/registry/router path to adapt
  those extension executors into the existing native `ToolInvocation`
  runtime path.
  - Added focused coverage for extension tools being registered,
  model-visible, dispatchable, and not replacing built-in tools.
  
  ## Verification
  
  - `cargo test -p codex-tools`
  - `cargo test -p codex-extension-api`

  jif-oai · 2026-05-13 12:12:06 +02:00
  9c5dfa7b1a
• feat: extract shared tool executor interface (#22359)

  ## Why
  
  Codex still models model-visible tools and executable behavior largely
  inside `codex-core`, which makes it harder to evolve the tool system
  toward a single reusable abstraction for built-ins, MCP-backed tools,
  dynamic tools, and later tools injected from outside core.
  
  This PR takes the next incremental step in that direction by moving the
  common execution-facing pieces out of core and separating them from
  core-only orchestration. The intent is to let shared tool abstractions
  improve in one place, while `codex-core` keeps the parts that are still
  inherently host-specific today, such as `ToolInvocation`, dispatch
  wiring, and hook integration.
  
  This PR is mostly moving things around. The only interesting piece is
  this abstraction:
  https://github.com/openai/codex/pull/22359/changes#diff-81af519002548ba51ed102bdaaf77e081d40a1e73a6e5f9b104bbbc96a6f1b3dR13
  
  ## What changed
  
  - Added `codex_tools::ToolExecutor<Invocation>` as the shared execution
  trait for model-visible tools.
  - Moved the reusable execution support types from `codex-core` into
  `codex-tools`:
    - `FunctionCallError`
    - `ToolPayload`
    - `ToolOutput`
  - Refactored core tool implementations so that execution behavior lives
  on `ToolExecutor<ToolInvocation>`, while `ToolHandler` remains the
  core-local extension point for hook payloads, telemetry tags, diff
  consumers, and other orchestration concerns.
  - Kept the registry and dispatch flow behaviorally unchanged while
  making the shared/extracted boundary explicit across built-in, MCP,
  dynamic, extension-backed, shell, and multi-agent tool handlers.
  
  ## Verification
  
  - `cargo test -p codex-tools`
  - `just fix -p codex-tools`
  - `just fix -p codex-core`
  - `cargo test -p codex-core` progressed through the updated tool
  surfaces and then hit the existing unrelated multi-agent stack overflow
  in
  `tools::handlers::multi_agents::tests::tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed`.

  jif-oai · 2026-05-13 11:31:27 +02:00
  1824685a00
• Remove unavailable MCP placeholder tool backfill (#22439)

  ## Why
  
  `UnavailableDummyTools` kept synthetic placeholder tools alive for
  historical tool calls whose backing MCP tool was no longer available.
  That path adds stale model-visible tool specs and special routing at the
  point where unavailable MCP calls should use ordinary current-tool
  handling. This removes the runtime backfill instead of preserving a
  second compatibility lane.
  
  ## Is it safe to remove?
  
  The unavailable tools were added in #17853 after a CS issue when a
  previously-called MCP tool failed to load and was omitted from the CS
  spec. Now that we have tool search, I think this is resolved:
  - API merges tools from previous TST output into effective tool set so
  theyre always in CS spec
  - if an MCP tool surfaced by TST later becomes unavailable, the model
  can still call it and it will just return model-visible error
  - both TST output and function call output are dropped on compaction so
  model will not remember old calls to MCP post compaction
  
  ## What changed
  
  - Delete unavailable-tool collection, placeholder handler, router/spec
  plumbing, and obsolete placeholder coverage.
  - Keep `features.unavailable_dummy_tools` as a removed no-op feature
  tombstone so existing configs still parse cleanly.
  - Add an integration-style `tool_search` regression test showing that a
  deferred MCP tool surfaced through `tool_search` still routes through
  MCP and returns a model-visible tool-call error rather than `unsupported
  call`.
  
  ## Verification
  
  - `cargo test -p codex-core tool_search`

  sayan-oai · 2026-05-12 23:30:13 -07:00
  2304ec45ca
• Encapsulate tool search entries in handlers (#22261)

  ## Why
  
  This builds on the handler-owned spec refactor by moving deferred
  tool-search metadata to the same handlers that already own tool specs.
  The registry builder no longer needs a separate prebuilt
  `tool_search_entries` path; it can collect searchable entries from
  deferred handlers directly.
  
  ## What changed
  
  - Added `search_info()` to tool handlers and implemented it for MCP and
  dynamic handlers.
  - Reused handler `spec()` output when constructing tool-search entries,
  adapting it into the deferred `LoadableToolSpec` shape expected by
  `tool_search`.
  - Simplified `build_tool_registry_builder(...)` so `tool_search`
  registration is based on deferred handlers with search info.
  - Removed the old standalone search-entry builders and now-unused
  `codex-tools` discovery helper exports.
  
  ## Verification
  
  - `cargo test -p codex-core tools::handlers::tool_search::tests:: --
  --nocapture`
  - `cargo test -p codex-core tools::spec_plan::tests::search_tool --
  --nocapture`
  - `cargo test -p codex-core tools::spec::tests:: -- --nocapture`
  - `cargo test -p codex-core tools::spec_plan::tests:: -- --nocapture`
  - `cargo test -p codex-tools`
  - `just fix -p codex-core`
  - `just fix -p codex-tools`

  pakrym-oai · 2026-05-12 20:48:02 -07:00
  104fc14956
• hooks: use new session IDs instead of thread IDs for hooks, apply parent's session ID to subagents' hooks (#22268)

  ## Why
  
  hook semantics treat `session_id` as shared across a root session and
  its subagents. Codex hooks were still emitting the current thread ID,
  which made spawned agents look like independent sessions and made it
  harder for hook integrations to correlate work across a root thread and
  its spawned helpers
  
  This change makes hooks use Codex's existing shared session identity so
  hook `session_id` matches the root-thread session across spawned
  subagents.
  
  ## What Changed
  
  - switch hook payloads to use the existing shared session identity from
  core instead of the current thread ID
  - cover all hook surfaces that expose `session_id`, including
  `SessionStart`, tool hooks, compact hooks, prompt-submit hooks, stop
  hooks, and legacy after-agent dispatch

  Andrei Eternal · 2026-05-12 19:05:10 -07:00
  fbfbfe5fc5
• Refactor namespaced tool spec registration (#22256)

  ## Summary
  
  This refactor makes tool handlers the owner of the specs they can
  publish, so registry construction can register handlers once and
  separately publish only the specs that should be model-visible.
  
  The main motivation is deferred tools: MCP and dynamic tools still need
  handlers registered up front, but deferred tools should be discoverable
  through `tool_search` rather than emitted in the initial tool spec list.
  
  ## What changed
  
  - `McpHandler` and `DynamicToolHandler` can return their own `ToolSpec`.
  - `build_tool_registry_builder` now collects handlers, registers them
  through the no-spec path, and publishes only non-deferred handler specs.
  - Deferred MCP and dynamic tool names are combined into one
  `all_deferred_tools` set that drives spec filtering, code-mode
  deferred-tool signaling, and `tool_search` registration.
  - `tool_search` registration now requires both deferred tools and
  `namespace_tools`.
  - Namespace specs are merged in `spec_plan`, preserving top-level spec
  order, sorting tools within each namespace, and backfilling empty
  namespace descriptions.
  - Hosted web search and image-generation specs are included in the
  collected spec vector before namespace merge/publication, and tool-name
  tests that should not care about hosted relative order now compare sets.
  
  ## Testing
  
  - `cargo test -p codex-core tools::spec::tests:: -- --nocapture`
  - `cargo test -p codex-core tools::spec_plan::tests:: -- --nocapture`
  - `cargo test -p codex-core
  tools::router::tests::specs_filter_deferred_dynamic_tools --
  --nocapture`
  - `cargo test -p codex-core
  suite::prompt_caching::prompt_tools_are_consistent_across_requests --
  --nocapture`
  - `just fmt`
  - `just fix -p codex-core`
  - `cargo test -p codex-core -- --skip
  tools::handlers::multi_agents::tests::tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed`
  passed the library suite after skipping the known stack-overflowing unit
  test.
  
  Full `cargo test -p codex-core` currently hits a stack overflow in
  `tools::handlers::multi_agents::tests::tool_handlers_cascade_close_and_resume_and_keep_explicitly_closed_subtrees_closed`;
  the same focused test reproduces on `origin/main`.

  pakrym-oai · 2026-05-12 17:09:14 -07:00
  0173f71143
• tools: remove is_mutating dispatch gating (#22382)

  ## Why
  
  Tool dispatch had two serialization mechanisms:
  
  - `supports_parallel_tool_calls` decides whether a tool participates in
  the shared parallel-execution lock.
  - `is_mutating` separately gated some calls inside dispatch.
  
  That second hook no longer carried its weight. The remaining
  parallel-support flag is already the per-tool concurrency policy, so
  keeping a second mutating gate made dispatch harder to follow and left
  behind extra session plumbing that only existed for that path.
  
  ## What changed
  
  - Removed `is_mutating` from tool handlers and deleted the
  `tool_call_gate` path that existed only to support it.
  - Simplified dispatch and routing to rely on the existing per-tool
  `supports_parallel_tool_calls` boolean.
  - Dropped the now-unused handler overrides and related session/test
  scaffolding.
  - Kept the router/parallel tests focused on the surviving per-tool
  behavior.
  - Removed the unused `codex-utils-readiness` dependency from
  `codex-core` as a follow-up fix for `cargo shear`.
  
  ## Testing
  
  - `cargo test -p codex-core
  parallel_support_does_not_match_namespaced_local_tool_names`
  - `cargo test -p codex-core mcp_parallel_support_uses_handler_data`
  - `cargo test -p codex-core
  tools_without_handlers_do_not_support_parallel`

  pakrym-oai · 2026-05-12 22:44:54 +00:00
  862b2122ee
• [codex] Make handlers own parallel tool support (#22254)

  ## Why
  
  `ToolRouter::tool_supports_parallel()` was still consulting configured
  specs when a handler lookup missed, even though parallel schedulability
  is really a property of the executable handler. Keeping that metadata on
  `ConfiguredToolSpec` duplicated state between the model-visible spec
  layer and the runtime handler layer.
  
  This change makes handlers the sole source of truth for parallel tool
  support and removes the extra spec wrapper that only existed to carry
  duplicated metadata.
  
  ## What changed
  
  - removed `ConfiguredToolSpec` and store plain `ToolSpec` values in the
  registry/router builder path
  - changed `ToolRouter::tool_supports_parallel()` to consult only the
  handler registry and fall back to `false`
  - simplified spec collection and test helpers to operate directly on
  `ToolSpec`
  - updated router/spec tests to cover handler-owned parallel behavior and
  the no-handler fallback
  
  ## Validation
  
  - `cargo test -p codex-tools`
  - `cargo test -p codex-core mcp_parallel_support_uses_handler_data`
  - `cargo test -p codex-core
  deferred_responses_api_tool_serializes_with_defer_loading`
  - `cargo test -p codex-core
  tools_without_handlers_do_not_support_parallel`
  - `cargo test -p codex-core
  request_plugin_install_can_be_registered_without_search_tool`
  
  ## Docs
  
  No documentation updates needed.

  pakrym-oai · 2026-05-11 22:26:33 -07:00
  c9e46ed639
• Support PreToolUse updatedInput rewrites (#20527)

  ## Why
  
  `PreToolUse` already exposes `updatedInput` in its hook output schema,
  but Codex currently rejects it instead of applying the rewrite. That
  leaves hook authors unable to make the documented pre-execution
  adjustment to a tool call before it runs.
  
  ## What
  
  - Accept `updatedInput` from `PreToolUse` hooks when paired with
  `permissionDecision: "allow"`.
  - Apply the rewritten input before dispatch so the tool executes the
  updated payload, not the original one.
  - Preserve the stable hook-facing compatibility shapes that
  participating tool handlers expose:
  - Bash-like tools (`shell`, `container.exec`, `local_shell`,
  `shell_command`, `exec_command`) use `{ "command": ... }`.
  - `apply_patch` exposes its patch body through the same command-shaped
  hook contract.
    - MCP tools expose their JSON argument object directly.
  - Keep each participating tool handler responsible for translating
  hook-facing `updatedInput` back into its concrete invocation shape.
  
  ## Verification
  
  Direct Bash-like rewrite coverage:
  
  - `pre_tool_use_rewrites_shell_before_execution`
  - `pre_tool_use_rewrites_container_exec_before_execution`
  - `pre_tool_use_rewrites_local_shell_before_execution`
  - `pre_tool_use_rewrites_shell_command_before_execution`
  - `pre_tool_use_rewrites_exec_command_before_execution`
  
  These cases assert that each supported Bash-like surface runs only the
  rewritten command while the hook still observes the original `{
  "command": ... }` input.
  
  `pre_tool_use_rewrites_apply_patch_before_execution`
  
  - Model emits one patch.
  - Hook swaps in a different patch.
  - Asserts only the rewritten file is created, and the hook saw the
  original patch.
  
  `pre_tool_use_rewrites_code_mode_nested_exec_command_before_execution`
  
  - Model runs one nested shell command from code mode.
  - Hook rewrites it.
  - Asserts only the rewritten command runs, and the hook saw the original
  nested input.
  
  `pre_tool_use_rewrites_mcp_tool_before_execution`
  
  - Model calls the RMCP echo tool.
  - Hook rewrites the MCP arguments.
  - Asserts the MCP server receives and returns the rewritten message, not
  the original one.

  Abhinav · 2026-05-11 22:27:24 -04:00
  d08906a944
• Simplify MCP tool handler plumbing (#21595)

  ## Why
  The MCP tool path had accumulated a few core-owned special cases: a
  dedicated payload variant, resolver plumbing, a legacy `AfterToolUse`
  translation path, and a side channel for parallel-call metadata. That
  made `ToolRegistry` and the spec builder know more about MCP than they
  needed to.
  
  This change moves MCP-specific execution details back onto `ToolInfo`
  and `McpHandler` so `codex-core` can treat MCP calls like normal
  function calls while still preserving MCP-specific dispatch and
  telemetry behavior where it belongs.
  
  ## What changed
  - removed `resolve_mcp_tool_info`, `ToolPayload::Mcp`, `ToolKind`, and
  the remaining registry-side MCP resolver path
  - stored MCP routing metadata directly on `McpHandler` and `ToolInfo`,
  including `supports_parallel_tool_calls`
  - deleted the legacy `AfterToolUse` consumer in `core`, which removes
  the need for handler-specific `after_tool_use_payload` implementations
  - switched tool-result telemetry to handler-provided tags and kept
  MCP-specific dispatch payload construction inside the handler
  - simplified tool spec planning/building by passing `ToolInfo` directly
  and dropping the direct/deferred MCP wrapper structs and the
  parallel-server side table
  
  ## Testing
  - `cargo check -p codex-core -p codex-mcp -p codex-otel`
  - `cargo test -p codex-core
  mcp_parallel_support_uses_exact_payload_server`
  - `cargo test -p codex-core
  direct_mcp_tools_register_namespaced_handlers`
  - `cargo test -p codex-core
  search_tool_description_lists_each_mcp_source_once`
  - `cargo test -p codex-mcp
  list_all_tools_uses_startup_snapshot_while_client_is_pending`
  - `just fix -p codex-core -p codex-mcp -p codex-otel`

  pakrym-oai · 2026-05-12 00:11:31 +00:00
  ed5944ba1d
• feat: move extensions tool (#22163)

  This PR is just moving stuff around

  jif-oai · 2026-05-11 17:14:43 +02:00
  8e12c12a07
• feat: wire extension tool bundles into core (#22147)

  ## Why
  
  This is the next narrow step toward moving concrete tool families out of
  core. After #22138 introduced `codex-tool-api`, we still needed a real
  end-to-end seam that lets an extension own an executable tool definition
  once and have core install it without the temporary `extension-api`
  wrapper or a dependency on `codex-tools`.
  
  `codex-tool-api` is the small extension-facing execution contract, while
  `codex-tools` still has a different job: host-side shared tool metadata
  and planning logic that is not “run this contributed tool”, like spec
  shaping, namespaces, discovery, code-mode augmentation, and
  MCP/dynamic-to-Responses API conversion
  
  ## What changed
  
  - Moved the shared leaf tool-spec and JSON Schema types into
  `codex-tool-api`, so the executable contract now lives with
  [`ToolBundle`](https://github.com/openai/codex/blob/c538758095337d4fe0a52a172363ccede4066bda/codex-rs/tool-api/src/bundle.rs#L19-L70).
  - Replaced the temporary extension-side tool wrapper with direct
  `ToolBundle` use in `codex-extension-api`.
  - Taught core to collect contributed bundles, include them in spec
  planning, register them through
  [`ToolRegistryBuilder::register_tool_bundle`](https://github.com/openai/codex/blob/c538758095337d4fe0a52a172363ccede4066bda/codex-rs/core/src/tools/registry.rs#L653-L667),
  and dispatch them through the existing router/runtime path.
  - Added focused coverage for contributed tools becoming model-visible
  and dispatchable, plus spec-planning coverage for contributed function
  and freeform tools.
  
  ## Verification
  
  - Added `extension_tool_bundles_are_model_visible_and_dispatchable` in
  `core/src/tools/router_tests.rs`.
  - Added spec-plan coverage in `core/src/tools/spec_plan_tests.rs` for
  contributed extension bundles.
  
  ## Related
  
  - Follow-up to #22138

  jif-oai · 2026-05-11 16:42:29 +02:00
  672cc1f669
• [codex] Remove legacy after tool use hooks (#21805)

  ## Why
  
  The legacy `AfterToolUse` hook path was still wired through core tool
  dispatch even though the hooks registry never populated any handlers for
  it. The supported hook surface is `PostToolUse`, so the old
  infrastructure was dead code on the hot path.
  
  ## What changed
  
  - Removed the legacy `AfterToolUse` dispatch from `codex-core` tool
  execution.
  - Removed the unused legacy hook payload types and exports from
  `codex-hooks`.
  - Simplified legacy notify handling now that `HookEvent` only carries
  `AfterAgent`.
  
  ## Validation
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-core registry`

  pakrym-oai · 2026-05-08 13:20:05 -07:00
  46e2250bcf
• Remove ToolName display helper (#21465)

  ## Why
  
  `ToolName::display()` made it too easy to flatten tool identity and
  accidentally compare rendered strings. Tool identity should stay
  structural until a legacy string boundary actually requires the
  flattened spelling.
  
  ## What
  
  - Removes `ToolName::display()` and relies on the existing `Display`
  impl for messages and errors.
  - Adds structural ordering for `ToolName` and uses it for
  sorting/deduping deferred tools.
  - Carries `ToolName` through tool/sandbox plumbing, flattening only at
  legacy boundaries such as hook payloads, telemetry tags, and Responses
  tool names.
  - Updates MCP normalization tests to assert `ToolName` structure instead
  of rendered strings.
  
  ## Testing
  
  - `cargo test -p codex-mcp test_normalize_tools`
  - `cargo test -p codex-core unavailable_tool`
  - `just fix -p codex-protocol`
  - `just fix -p codex-mcp`
  - `just fix -p codex-core`

  pakrym-oai · 2026-05-08 12:17:48 -07:00
  61142b6169
• [codex] Move tool specs onto handlers (#21461)

  ## Why
  
  This is the next stacked step after deleting the tool-handler kind
  indirection. Specs should come from the registered handlers themselves
  so registry construction has a single source of truth for handler
  behavior and exposed tool definitions.
  
  ## What changed
  
  - Added `ToolHandler::spec()` plus handler-provided parallel/code-mode
  metadata, and made `ToolRegistryBuilder::register_handler` automatically
  collect specs from registered handlers.
  - Moved builtin tool spec construction into the corresponding handlers
  and their adjacent `_spec` modules, including shell, unified exec, apply
  patch, view image, request plugin install, tool search, MCP resource,
  goals, planning, permissions, agent jobs, and multi-agent tools.
  - Reworked configurable handlers to receive their tool-building options
  through constructors, with non-optional handler options where the
  handler is always spec-backed. Shell fallback handlers keep an explicit
  no-spec mode because they are also registered as hidden dispatch
  aliases.
  - Kept `CodeModeExecuteHandler` on the explicit configured wrapper so
  the code-mode exec spec can still be built from the nested registry.
  
  ## Verification
  
  - `cargo check -p codex-core`
  - `cargo test -p codex-core tools::spec_plan::tests`
  - `cargo test -p codex-core tools::spec::tests`
  - `cargo test -p codex-core tools::handlers::multi_agents_spec::tests`
  - `RUST_MIN_STACK=16777216 cargo test -p codex-core
  tools::handlers::multi_agents::tests`
  - `cargo test -p codex-core tools::handlers::apply_patch::tests`
  - `cargo test -p codex-core tools::handlers::unified_exec::tests`
  - `just fix -p codex-core`
  - `git diff --check`

  pakrym-oai · 2026-05-07 10:48:36 -07:00
  566f2cb612
• [codex] Delete tool handler plan indirection (#21427)

  ## Why
  
  The spec split in the parent PR still left an intermediate registry plan
  that recorded `ToolHandlerKind` values and translated them into concrete
  handlers later. That kept tool registration dependent on static enum
  bookkeeping instead of registering handlers from the same code that
  assembles their specs.
  
  ## What Changed
  
  - Make `build_tool_registry_builder` register concrete handlers directly
  while adding specs.
  - Add small `ToolRegistryBuilder` helpers for spec augmentation and
  nested code-mode inspection.
  - Remove `ToolHandlerKind`, `ToolHandlerSpec`, and `ToolRegistryPlan`.
  - Update spec-plan tests to assert against the built `ToolRegistry`
  instead of static handler descriptors.
  
  ## Validation
  
  - `cargo check -p codex-core`
  - `cargo test -p codex-core tools::spec_plan::tests`
  - `cargo test -p codex-core tools::spec::tests`
  - `just fix -p codex-core`

  pakrym-oai · 2026-05-06 20:36:24 -07:00
  e394625ea2
• [codex] Split tool handlers by tool name (#20687)

  ## Why
  
  Tool registration used to bind a tool name to a handler externally,
  which left ownership split between the registry plan and the handler
  implementation. Some built-in handlers also multiplexed multiple in-core
  tools by switching on the invoked tool name internally.
  
  This moves the registry identity onto the handler itself and makes
  built-in multi-tool areas use separate concrete handlers, so each
  registered handler instance owns exactly one tool name and one dispatch
  path.
  
  ## What Changed
  
  - Added `ToolHandler::tool_name()` and changed
  `ToolRegistryBuilder::register_handler` to derive the registry key from
  the handler.
  - Split built-in multiplexed handlers into concrete per-tool handlers
  for unified exec, shell/local shell/container exec, MCP resources, goal
  tools, and agent job tools.
  - Kept name-carrying handler instances only where the runtime target is
  inherently external or dynamic, such as MCP tools, dynamic tools, and
  unavailable placeholders.
  - Updated `ToolHandlerKind` and registry-plan construction so plan
  entries map directly to concrete handler registrations.
  
  ## Verification
  
  - `cargo test -p codex-tools tool_registry_plan`
  - `cargo test -p codex-core --lib tools::registry_tests`
  - `just fix -p codex-tools`
  - `just fix -p codex-core`

  pakrym-oai · 2026-05-05 13:46:45 -07:00
  f593323ef1
• Support PreToolUse additionalContext (#20692)

  # Why
  
  `PreToolUse` already exposes `hookSpecificOutput.additionalContext` in
  the generated hook schema, but the runtime still rejected it as
  unsupported. That leaves `PreToolUse` out of step with the other
  context-injecting hooks and prevents hook authors from attaching
  model-visible guidance to a pending tool call before it runs.
  
  # What
  
  - Parse `PreToolUse.additionalContext` and carry it through the hook
  event pipeline.
  - Record `PreToolUse` context at the hook boundary so successful context
  is preserved for both allowed and blocked calls without widening the
  tool registry surface.
  - Preserve existing deny behavior when context is combined with either
  `permissionDecision: "deny"` or the legacy `decision: "block"` shape.

  Abhinav · 2026-05-05 10:29:30 -07:00
  af86be529c
• Stateful streaming apply_patch parser
  Akshay Nathan · 2026-04-30 21:41:15 +00:00
  8426edf71e
• chore: split memories part 1 (#19818)

  Extract memories into 2 different crates

  jif-oai · 2026-04-27 16:01:05 +02:00
  bb83eec825
• permissions: make runtime config profile-backed (#19606)

  ## Why
  
  This supersedes #19391. During stack repair, GitHub marked #19391 as
  merged into a temporary stack branch rather than into `main`, so the
  runtime-config change needed a fresh PR.
  
  `PermissionProfile` is now the canonical permissions shape after #19231
  because it can distinguish `Managed`, `Disabled`, and `External`
  enforcement while also carrying filesystem rules that legacy
  `SandboxPolicy` cannot represent cleanly. Core config and session state
  still needed to accept profile-backed permissions without forcing every
  profile through the strict legacy bridge, which rejected valid runtime
  profiles such as direct write roots.
  
  The unrelated CI/test hardening that previously rode along with this PR
  has been split into #19683 so this PR stays focused on the permissions
  model migration.
  
  ## What Changed
  
  - Adds `Permissions.permission_profile` and
  `SessionConfiguration.permission_profile` as constrained runtime state,
  while keeping `sandbox_policy` as a legacy compatibility projection.
  - Introduces profile setters that keep `PermissionProfile`, split
  filesystem/network policies, and legacy `SandboxPolicy` projections
  synchronized.
  - Uses a compatibility projection for requirement checks and legacy
  consumers instead of rejecting profiles that cannot round-trip through
  `SandboxPolicy` exactly.
  - Updates config loading, config overrides, session updates, turn
  context plumbing, prompt permission text, sandbox tags, and exec request
  construction to carry profile-backed runtime permissions.
  - Preserves configured deny-read entries and `glob_scan_max_depth` when
  command/session profiles are narrowed.
  - Adds `PermissionProfile::read_only()` and
  `PermissionProfile::workspace_write()` presets that match legacy
  defaults.
  
  ## Verification
  
  - `cargo test -p codex-core direct_write_roots`
  - `cargo test -p codex-core runtime_roots_to_legacy_projection`
  - `cargo test -p codex-app-server
  requested_permissions_trust_project_uses_permission_profile_intent`
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/19606).
  * #19395
  * #19394
  * #19393
  * #19392
  * __->__ #19606

  Michael Bolin · 2026-04-26 13:29:54 -07:00
  4d7ce3447d
• Add goal core runtime (4 / 5) (#18076)

  Adds the core runtime behavior for active goals on top of the model
  tools from PR 3.
  
  ## Why
  
  A long-running goal should be a core runtime concern, not something
  every client has to implement. Core owns the turn lifecycle, tool
  completion boundaries, interruptions, resume behavior, and token usage,
  so it is the right place to account progress, enforce budgets, and
  decide when to continue work.
  
  ## What changed
  
  - Centralized goal lifecycle side effects behind
  `Session::goal_runtime_apply(GoalRuntimeEvent::...)`.
  - Starts goal continuation turns only when the session is idle; pending
  user input and mailbox work take priority.
  - Accounts token and wall-clock usage at turn, tool, mutation,
  interrupt, and resume boundaries; `get_thread_goal` remains read-only.
  - Preserves sub-second wall-clock remainder across accounting boundaries
  so long-running goals do not drift downward over time.
  - Treats token budget exhaustion as a soft stop by marking the goal
  `budget_limited` and injecting wrap-up steering instead of aborting the
  active turn.
  - Suppresses budget steering when `update_goal` marks a goal complete.
  - Pauses active goals on interrupt and auto-reactivates paused goals
  when a thread resumes outside plan mode.
  - Suppresses repeated automatic continuation when a continuation turn
  makes no tool calls.
  - Added continuation and budget-limit prompt templates.
  
  ## Verification
  
  - Added focused core coverage for continuation scheduling, accounting
  boundaries, budget-limit steering, completion accounting, interrupt
  pause behavior, resume auto-activation, and wall-clock remainder
  accounting.

  Eric Traut · 2026-04-24 21:16:00 -07:00
  4167628622
• [rollout_trace] Trace tool and code-mode boundaries (#18878)

  ## Summary
  
  Extends rollout tracing across tool dispatch and code-mode runtime
  boundaries. This records canonical tool-call lifecycle events and links
  code-mode execution/wait operations back to the model-visible calls that
  caused them.
  
  ## Stack
  
  This is PR 3/5 in the rollout trace stack.
  
  - [#18876](https://github.com/openai/codex/pull/18876): Add rollout
  trace crate
  - [#18877](https://github.com/openai/codex/pull/18877): Record core
  session rollout traces
  - [#18878](https://github.com/openai/codex/pull/18878): Trace tool and
  code-mode boundaries
  - [#18879](https://github.com/openai/codex/pull/18879): Trace sessions
  and multi-agent edges
  - [#18880](https://github.com/openai/codex/pull/18880): Add debug trace
  reduction command
  
  ## Review Notes
  
  This PR is about attribution. Reviewers should focus on whether direct
  tool calls, code-mode-originated tool calls, waits, outputs, and
  cancellation boundaries are recorded with enough source information for
  deterministic reduction without coupling the reducer to live runtime
  internals.
  
  The stack remains valid after this layer: tool and code-mode traces
  reduce through the existing crate model, while the broader session and
  multi-agent relationships are added in the next PR.

  cassirer-openai · 2026-04-23 12:22:11 -07:00
  6d09b6752d
• Support MCP tools in hooks (#18385)

  ## Summary
  
  Lifecycle hooks currently treat `PreToolUse`, `PostToolUse`, and
  `PermissionRequest` as Bash-only flows
  - hook schema constrains `tool_name` to `Bash`
  - hook input assumes a command-shaped `tool_input`
  - core hook dispatch path passes only shell command strings
  
  That means hooks cannot target MCP tools even though MCP tool names are
  model-visible and stable
  
  This change generalizes those hook paths so they can match and receive
  payloads for MCP tools while preserving the existing Bash behavior.
  
  ## Reviewer Notes
  
  I think these are the key files
  - `codex-rs/core/src/tools/handlers/mcp.rs`
  - `codex-rs/core/src/mcp_tool_call.rs`
  
  Otherwise the changes across apply_patch, shell, and unified_exec are
  mainly to rewire everything to be `tool_input` based instead of just
  `command` so that it'll make sense for MCP tools.
  
  ## Changes
  
  - Allow `PreToolUse`, `PostToolUse`, and `PermissionRequest` hook inputs
  to carry arbitrary `tool_name` and `tool_input` values instead of
  hard-coding `Bash` and command-only payloads.
  - Add MCP hook payload support through `McpHandler`, using the
  model-visible tool name from `ToolInvocation` and the raw MCP arguments
  as `tool_input`.
  - Include MCP tool responses in `PostToolUse` by serializing
  `McpToolOutput` into the hook response payload.
  - Run `PermissionRequest` hooks for MCP approval requests after
  remembered approval checks and before falling back to user-facing MCP
  elicitation.
  - Preserve exact matching for literal hook matchers like `Bash` and
  `mcp__memory__create_entities`, while keeping regex matcher support for
  patterns like `mcp__memory__.*` and `mcp__.*__write.*`.
  
  ---------
  
  Co-authored-by: Andrei Eternal <eternal@openai.com>
  Co-authored-by: Codex <noreply@openai.com>

  Abhinav · 2026-04-23 07:33:57 +00:00
  305825abd9
• hooks: emit Bash PostToolUse when exec_command completes via write_stdin (#18888)

  Fixes #16246.
  
  ## Why
  
  `exec_command` already emits `PreToolUse`, but long-running unified exec
  commands that finish on a later `write_stdin` poll could miss the
  matching `PostToolUse`. That left the Bash hook lifecycle inconsistent,
  broke expectations around `tool_use_id` and `tool_input.command`, and
  meant `PostToolUse` block/replacement feedback could fail to replace the
  final session output before it reached model context.
  
  This keeps the fix scoped to the `exec_command` / `write_stdin`
  lifecycle. Broader non-Bash hook expansion is still out of scope here
  and remains tracked separately in #16732.
  
  ## What changed
  
  - Compute and store `PostToolUsePayload` while handlers still have
  access to their concrete output type, and carry `tool_use_id` through
  that payload.
  - Preserve the original hook-facing `exec_command` string through
  unified exec state (`ExecCommandRequest`, `ProcessEntry`,
  `PreparedProcessHandles`, and `ExecCommandToolOutput`) via
  `hook_command`, and remove the now-unused `session_command` output
  metadata.
  - Emit exactly one Bash `PostToolUse` for long-running `exec_command`
  sessions when a later `write_stdin` poll observes final completion,
  using the original `exec_command` call id and hook-facing command.
  - Keep one-shot `exec_command` behavior aligned with the same payload
  construction, including interactive completions that return a final
  result directly.
  - Apply `PostToolUse` block/replacement feedback before the final
  `write_stdin` completion output is sent back to the model.
  - Keep `write_stdin` itself out of `PreToolUse` matching so it continues
  to act as transport/polling for the original Bash tool call.
  - Restore plain matcher behavior for tool-name matchers such as `Bash`
  and `Edit|Write`, while still treating patterns with regex characters
  (for example `mcp__.*`) as regexes.
  - Add unit coverage for unified exec payload construction and parallel
  session separation, plus a core integration regression that verifies a
  blocked `PostToolUse` replaces the final `write_stdin` output in model
  context.
  
  ## Testing
  
  - `cargo test -p codex-hooks`
  - `cargo test -p codex-core post_tool_use_payload`
  - `cargo test -p codex-core
  post_tool_use_blocks_when_exec_session_completes_via_write_stdin`

  Andrei Eternal · 2026-04-22 17:14:22 -07:00
  eed0e07825
• fix(core): emit hooks for apply_patch edits (#18391)

  Fixes https://github.com/openai/codex/issues/16732.
  
  ## Why
  
  `apply_patch` is Codex's primary file edit path, but it was not emitting
  `PreToolUse` or `PostToolUse` hook events. That meant hook-based policy,
  auditing, and write coordination could observe shell commands while
  missing the actual file mutation performed by `apply_patch`.
  
  The issue also exposed that the hook runtime serialized command hook
  payloads with `tool_name: "Bash"` unconditionally. Even if `apply_patch`
  supplied hook payloads, hooks would either fail to match it directly or
  receive misleading stdin that identified the edit as a Bash tool call.
  
  ## What Changed
  
  - Added `PreToolUse` and `PostToolUse` payload support to
  `ApplyPatchHandler`.
  - Exposed the raw patch body as `tool_input.command` for both
  JSON/function and freeform `apply_patch` calls.
  - Taught tool hook payloads to carry a handler-supplied hook-facing
  `tool_name`.
  - Preserved existing shell compatibility by continuing to emit `Bash`
  for shell-like tools.
  - Serialized the selected hook `tool_name` into hook stdin instead of
  hardcoding `Bash`.
  - Relaxed the generated hook command input schema so `tool_name` can
  represent tools other than `Bash`.
  
  ## Verification
  
  Added focused handler coverage for:
  
  - JSON/function `apply_patch` calls producing a `PreToolUse` payload.
  - Freeform `apply_patch` calls producing a `PreToolUse` payload.
  - Successful `apply_patch` output producing a `PostToolUse` payload.
  - Shell and `exec_command` handlers continuing to expose `Bash`.
  
  Added end-to-end hook coverage for:
  
  - A `PreToolUse` hook matching `^apply_patch$` blocking the patch before
  the target file is created.
  - A `PostToolUse` hook matching `^apply_patch$` receiving the patch
  input and tool response, then adding context to the follow-up model
  request.
  - Non-participating tools such as the plan tool continuing not to emit
  `PreToolUse`/`PostToolUse` hook events.
  
  Also validated manually with a live `codex exec` smoke test using an
  isolated temp workspace and temp `CODEX_HOME`. The smoke test confirmed
  that a real `apply_patch` edit emits `PreToolUse`/`PostToolUse` with
  `tool_name: "apply_patch"`, a shell command still emits `tool_name:
  "Bash"`, and a denying `PreToolUse` hook prevents the blocked patch file
  from being created.

  Felipe Coury · 2026-04-21 22:00:40 -03:00
  09ebc34f17
• chore: document intentional await-holding cases (#18423)

  ## Why
  
  This PR prepares the stack to enable Clippy await-holding lints that
  were left disabled in #18178. The mechanical lock-scope cleanup is
  handled separately; this PR is the documentation/configuration layer for
  the remaining await-across-guard sites.
  
  Without explicit annotations, reviewers and future maintainers cannot
  tell whether an await-holding warning is a real concurrency smell or an
  intentional serialization boundary.
  
  ## What changed
  
  - Configures `clippy.toml` so `await_holding_invalid_type` also covers
  `tokio::sync::{MutexGuard,RwLockReadGuard,RwLockWriteGuard}`.
  - Adds targeted `#[expect(clippy::await_holding_invalid_type, reason =
  ...)]` annotations for intentional async guard lifetimes.
  - Documents the main categories of intentional cases: active-turn state
  transitions that must remain atomic, session-owned MCP manager accesses,
  remote-control websocket serialization, JS REPL kernel/process
  serialization, OAuth persistence, external bearer token refresh
  serialization, and tests that intentionally serialize shared global or
  session-owned state.
  - For external bearer token refresh, documents the existing
  serialization boundary: holding `cached_token` across the provider
  command prevents concurrent cache misses from starting duplicate refresh
  commands, and the current behavior is small enough that an explicit
  expectation is easier to maintain than adding another synchronization
  primitive.
  
  ## Verification
  
  - `cargo clippy -p codex-login --all-targets`
  - `cargo clippy -p codex-connectors --all-targets`
  - `cargo clippy -p codex-core --all-targets`
  - The follow-up PR #18698 enables `await_holding_invalid_type` and
  `await_holding_lock` as workspace `deny` lints, so any undocumented
  remaining offender will fail Clippy.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/18423).
  * #18698
  * __->__ #18423

  Michael Bolin · 2026-04-20 22:41:54 -07:00
  d62421d322
• Wire the PatchUpdated events through app_server (#18289)

  Wires patch_updated events through app_server. These events are parsed
  and streamed while apply_patch is being written by the model. Also adds 500ms of buffering to the patch_updated events in the diff_consumer.
  
  The eventual goal is to use this to display better progress indicators in
  the codex app.

  Akshay Nathan · 2026-04-20 10:44:03 -07:00
  34a3e85fcd
• Move codex module under session (#18249)

  ## Summary
  - rename the core codex module root to session/mod.rs without using
  #[path]
  - move the codex module directory and tests under core/src/session
  - remove session/mod.rs reexports so call sites use explicit child
  module paths
  
  ## Testing
  - cargo test -p codex-core --lib
  - cargo check -p codex-core --tests
  - just fmt
  - just fix -p codex-core
  - git diff --check

  pakrym-oai · 2026-04-17 16:18:53 +00:00
  71e4c6fa17
• Stream apply_patch changes (#17862)

  Adds new events for streaming apply_patch changes from responses api.
  This is to enable clients to show progress during file writes.
  
  Caveat: This does not work with apply_patch in function call mode, since
  that required adding streaming json parsing.

  Akshay Nathan · 2026-04-16 18:12:19 -07:00
  7995c66032