220 Commits

• [codex] Move pending input into input queue (#22728)

  ## Why
  
  Pending model input was split across `Session`, `TurnState`, and the
  agent mailbox. That made it easy for new paths to manage queued user
  input or mailbox delivery outside the intended ownership boundary.
  
  This PR consolidates the model-facing input lifecycle behind the session
  input queue so turn-local pending input, next-turn queued items, and
  mailbox delivery coordination are owned in one place.
  
  ## What Changed
  
  - Added `session/input_queue.rs` to own pending input queues and mailbox
  delivery coordination.
  - Removed the standalone `agent/mailbox.rs` channel wrapper and store
  mailbox items directly in the input queue.
  - Moved pending-input mutations off `TurnState`; `TurnState` now exposes
  the queue-owned storage directly for now.
  - Routed abort cleanup, mailbox delivery phase changes, next-turn queued
  items, and active-turn pending input through `InputQueue`.
  - Boxed stack-heavy agent resume/fork startup futures that the refactor
  pushed over the default test stack.
  - Updated session, task, goal, stream-event, and multi-agent call sites
  and tests to use the new queue ownership.
  
  ## Verification
  
  - `cargo test -p codex-core --lib agent::control::tests`
  - `cargo test -p codex-core --lib
  agent::control::tests::resume_closed_child_reopens_open_descendants --
  --exact`
  - `cargo test -p codex-core --lib
  agent::control::tests::spawn_agent_fork_last_n_turns_keeps_only_recent_turns
  -- --exact`
  - `cargo test -p codex-core --lib
  agent::control::tests::resume_thread_subagent_restores_stored_nickname_and_role
  -- --exact`
  - `cargo test -p codex-core` was also run; it completed with 1814
  passed, 4 ignored, and one timeout in
  `agent::control::tests::resume_thread_subagent_restores_stored_nickname_and_role`,
  which passed when rerun in isolation.

  pakrym-oai · 2026-05-18 15:43:01 -07:00
  afa0101ae2
• [codex] Trim unused TurnContextItem fields (#22709)

  ## Why
  
  `TurnContextItem` is the durable baseline used to reconstruct context
  diffs across resume/fork. Most of the old persisted-only fields on it
  are no longer read, so keeping them in rollout snapshots adds schema
  surface and state that can drift without affecting reconstruction.
  
  `summary` is the exception: older Codex versions require it to
  deserialize `turn_context` records, so keep writing a default
  compatibility value until that schema surface can be removed safely.
  
  ## What changed
  
  - Removed the unused persisted fields from `TurnContextItem`: trace ids,
  user/developer instructions, output schema, and truncation policy.
  - Kept `summary` with a compatibility comment and made
  `TurnContext::to_turn_context_item` write `ReasoningSummary::Auto`
  instead of live turn state.
  - Updated rollout/context reconstruction fixtures for the retained
  summary field.
  
  ## Verification
  
  - `cargo test -p codex-protocol --lib turn_context_item`
  - `cargo test -p codex-rollout
  resume_candidate_matches_cwd_reads_latest_turn_context`
  - `cargo test -p codex-state turn_context`
  - `cargo test -p codex-core --lib
  new_default_turn_captures_current_span_trace_id`
  - `cargo test -p codex-core --lib
  record_initial_history_resumed_turn_context_after_compaction_reestablishes_reference_context_item`
  - `cargo test -p codex-core --test all
  emits_warning_when_resumed_model_differs`
  - `git diff --check`

  pakrym-oai · 2026-05-18 21:54:36 +00:00
  f2368b7de6
• goals: keep pause transitions explicit (#23088)

  ## Problem
  
  This addresses several user-reported cases where active goals were
  paused even though the user had not explicitly asked for that
  transition:
  
  - the guardian approval-review circuit breaker interrupted a turn and
  implicitly paused the goal
  - a shutdown in one app-server instance could pause a goal while a
  second instance was still actively running the same thread
  - steering-style interrupts could also pause the goal even though they
  are meant to redirect work, not stop the goal lifecycle
  
  The common problem was that core treated `TurnAbortReason::Interrupted`
  as an implicit request to transition the persisted goal to `paused`.
  That made unrelated interrupt paths mutate goal state as a side effect,
  and in the multi-app-server case it allowed stale process teardown to
  pause a live goal owned by another running client.
  
  After this change, transitioning a goal to `paused` is always an
  explicit action performed by a client or another intentional goal-state
  mutation. It is never an implicit transition triggered by generic
  interrupt handling.
  
  Refs #22884.
  
  ## What changed
  
  - Remove the goal runtime path that paused active goals after
  interrupted task aborts.
  - Drop the now-unused abort reason from `GoalRuntimeEvent::TaskAborted`.
  - Update the focused regression coverage so an interrupted active goal
  still accounts usage but remains `active`.

  Eric Traut · 2026-05-18 11:58:40 -07:00
  55f6bbc667
• goal: pause continuation loops on usage limits and blockers (#23094)

  Addresses #22833, #22245, #23067
  
  ## Why
  `/goal` can keep synthesizing turns even when the next turn cannot make
  meaningful progress. Hard usage exhaustion can replay failing turns, and
  repeated permission or external-resource blockers can keep burning
  tokens while waiting for user or system intervention.
  
  ## What changed
  - Add resumable `blocked` and `usageLimited` goal states. As with
  `paused`, goal continuation stops with these states.
  - Move to `usageLimited` after usage-limit failures.
  - Allow the built-in `update_goal` tool to set `blocked` only under
  explicit repeated-impasse guidance. Updated goal continuation prompt to
  specify that agent should use `blocked` only when it has made at least
  three attempts to get past an impasse.
  
  Most of the files touched by this PR are because of the small app server
  protocol update.
  
  ## Validation
  
  I manually reproduced a number of situations where an agent can run into
  a true impasse and verified that it properly enters `blocked` state. I
  then resumed and verified that it once again entered `blocked` state
  several turns later if the impasse still exists.
  
  I also manually reproduced the usage-limit condition by creating a
  simulated responses API endpoint that returns 429 errors with the
  appropriate error message. Verified that the goal runtime properly moves
  the goal into `usageLimited` state and TUI UI updates appropriately.
  Verified that `/goal resume` resumes (and immediately goes back into
  `ussageLImited` state if appropriate).
  
  
  ## Follow-up PRs
  
  Small changes will be needed to the GUI clients to properly handle the
  two new states.

  Eric Traut · 2026-05-18 11:28:53 -07:00
  0d344aca9b
• Fix remote turn diff display roots (#23261)

  ## Why
  
  `TurnDiffTracker` computes a display root so turn diffs can be rendered
  repo-relative. For remote exec-server turns, the selected turn `cwd` may
  exist only inside the selected environment, but `run_turn` was
  discovering the git root through the local host filesystem. When that
  lookup failed, nested remote-session diffs fell back to the nested `cwd`
  and showed `/tmp/...`-prefixed paths instead of repo-relative paths.
  
  ## What changed
  
  - Resolve the diff display root from the primary selected turn
  environment when one exists, using that environment's filesystem and
  `cwd`.
  - Add `codex_git_utils::get_git_repo_root_with_fs(...)` so git-root
  discovery can run against an `ExecutorFileSystem`, including remote
  environments.
  - Reuse that helper from `resolve_root_git_project_for_trust(...)` and
  add coverage for `.git` gitdir-pointer detection.
  
  ## Validation
  
  - Devbox Bazel: `//codex-rs/core:core-unit-tests
  --test_filter=get_git_repo_root_with_fs_detects_gitdir_pointer`
  - Devbox Docker-backed remote-env repro: `//codex-rs/core:core-all-test
  --test_filter=apply_patch_turn_diff_paths_stay_repo_relative_when_session_cwd_is_nested`

  starr-openai · 2026-05-18 10:53:49 -07:00
  9286ff2805
• chore: make token usage async (#23305)

  Make the `TokenUsageContributor` async. This will be required for future
  extension and it's basically free

  jif-oai · 2026-05-18 15:59:06 +02:00
  b631d92170
• chore: isolate thread goal storage behind GoalStore (#23295)

  ## Why
  
  Thread goal persistence is being prepared for a dedicated storage
  boundary. Before that split, goal-specific reads, writes, accounting,
  and cleanup were exposed directly on `StateRuntime`, so core and
  app-server callsites stayed coupled to the full runtime instead of a
  goal-specific store.
  
  This PR introduces that boundary without changing the goal wire API or
  current persistence behavior. Callers now go through
  `StateRuntime::thread_goals()` and the new `GoalStore`, while
  `GoalStore` still uses the existing state DB pool underneath.
  
  ## What changed
  
  - Added `GoalStore` in `state/src/runtime/goals.rs` and exposed it from
  `StateRuntime` via `thread_goals()`.
  - Moved thread-goal reads, writes, status updates, pause, delete, and
  usage accounting onto `GoalStore`.
  - Updated core session goal handling, app-server goal RPCs, resume
  snapshots, and goal tests to use the store boundary.
  - Kept thread deletion responsible for cascading goal cleanup by
  deleting the goal through the store only after a thread row is removed.
  
  ## Testing
  
  - Existing goal persistence, resume, and accounting tests were updated
  to exercise the new `GoalStore` access path.

  jif-oai · 2026-05-18 14:47:05 +02:00
  7ee7fe239f
• Make extension lifecycle hooks async (#23291)

  ## Why
  
  Extension lifecycle hooks sit on the host/extension boundary, but the
  current trait surface only allows synchronous callbacks. That forces
  extensions that need to seed, rehydrate, observe, or flush
  extension-owned state during thread and turn transitions to either block
  inside the callback or move async work into separate host plumbing.
  
  This PR makes those lifecycle callbacks awaitable so extension
  implementations can perform async work directly at the lifecycle point
  where the host already has the relevant session, thread, or turn stores
  available.
  
  ## What changed
  
  - Makes `ThreadLifecycleContributor` and `TurnLifecycleContributor`
  async in `codex-extension-api`.
  - Awaits thread start/resume/stop and turn start/stop/abort lifecycle
  callbacks from `codex-core`.
  - Updates the guardian and memories extensions to implement the async
  lifecycle trait surface.
  - Updates the existing lifecycle tests to use async contributor
  implementations.
  - Adds `async-trait` to the crates that now expose or implement these
  async object-safe lifecycle traits.
  
  ## Testing
  
  - Existing `codex-core` lifecycle tests were updated to cover async
  implementations for thread stop and turn abort ordering.

  jif-oai · 2026-05-18 13:53:58 +02:00
  9531e932ef
• 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
• test: construct permission profiles directly (#23030)

  ## Why
  
  `SandboxPolicy` is now a legacy compatibility shape, but several tests
  still built a `SandboxPolicy` only to immediately convert it into
  `PermissionProfile` for APIs that already accept canonical runtime
  permissions. Those detours make it harder to audit where legacy sandbox
  policy is still required, because boundary-only usages are mixed
  together with ordinary test setup.
  
  ## What Changed
  
  - Updated tests in `codex-core`, `codex-exec`, `codex-analytics`, and
  `codex-config` to construct `PermissionProfile` values directly when the
  code under test takes a permission profile.
  - Changed exec-policy, request-permissions, session, and sandbox test
  helpers to pass `PermissionProfile` through instead of converting from
  `SandboxPolicy` internally.
  - Left `SandboxPolicy` in place where tests are explicitly exercising
  legacy compatibility or request/response boundaries.
  
  ## Test Plan
  
  - `cargo test -p codex-analytics -p codex-config`
  - `cargo test -p codex-core --lib safety::tests`
  - `cargo test -p codex-core --lib exec_policy::tests::`
  - `cargo test -p codex-core --lib exec::tests`
  - `cargo test -p codex-core --lib guardian_review_session_config`
  - `cargo test -p codex-core --lib tools::network_approval::tests`
  - `cargo test -p codex-core --lib
  tools::runtimes::shell::unix_escalation::tests`
  - `cargo test -p codex-core --lib managed_network`
  - `cargo test -p codex-core --test all request_permissions::`
  - `cargo test -p codex-exec sandbox`
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/23030).
  * #23036
  * __->__ #23030

  Michael Bolin · 2026-05-16 12:12:37 -07:00
  d91bc15618
• Improve goal completion usage reporting (#22907)

  ## Why
  
  Goal completion follow-up turns currently receive a preformatted English
  usage sentence such as `time used: 2586 seconds`. That nudges the model
  to echo an awkward raw seconds count in the final reply, even though the
  tool result already exposes structured usage fields like
  `goal.timeUsedSeconds`, `goal.tokensUsed`, and `goal.tokenBudget`.
  
  ## What changed
  
  - Replace the preformatted completion usage sentence with guidance to
  read the structured goal fields from the tool result.
  - Preserve token-budget reporting while allowing the model to phrase
  elapsed time in a concise, human-friendly way that fits the response
  language.
  - Update core coverage for both the generated completion guidance and
  the session flow that forwards it back to the model.
  
  ## Verification
  
  Previously, it would have output a final message indicating that it
  "worked for 303 seconds". Now it shows the following:
  
  <img width="286" height="35" alt="image"
  src="https://github.com/user-attachments/assets/d7011880-9449-46a7-856f-4e50ae00eb45"
  />

  Eric Traut · 2026-05-16 11:49:40 -07:00
  941e7f825e
• core: set permission profiles from snapshots (#22920)

  ## Why
  
  #22891 moved the TUI turn-command path to pass `ActivePermissionProfile`
  instead of the full `PermissionProfile`, but the remaining
  config/session bridge still accepted the concrete `PermissionProfile`
  and active profile id as separate arguments. That shape made it too easy
  for future callers to update the concrete profile and active profile id
  out of sync.
  
  This PR makes the trusted session snapshot path pass one coherent value
  into `Permissions`, while keeping `requirements.toml` enforcement owned
  by the existing constrained permission state.
  
  ## What Changed
  
  - Added `PermissionProfileSnapshot` as the public snapshot value for
  trusted session/config synchronization.
  - Changed `Permissions::set_permission_profile_from_session_snapshot()`
  and `replace_permission_profile_from_session_snapshot()` to take a
  `PermissionProfileSnapshot`.
  - Updated the replacement path to derive its constrained
  `PermissionProfile` from the snapshot, so callers cannot pass a separate
  profile that disagrees with the snapshot.
  - Removed the internal tuple-style
  `PermissionProfileState::set_active_permission_profile()` mutation path.
  - Updated core session projection and TUI call sites to construct
  explicit legacy or active snapshots.
  - Documented the snapshot constructors so legacy use and id/profile
  mismatch hazards are called out at the API boundary.
  - Added a focused config test that verifies snapshot updates still
  respect existing permission constraints.
  
  ## How To Review
  
  1. Start with `codex-rs/core/src/config/resolved_permission_profile.rs`;
  `PermissionProfileSnapshot` is the public wrapper, while
  `ResolvedPermissionProfile` stays internal.
  2. Check `codex-rs/core/src/config/mod.rs` to confirm both
  session-snapshot setters validate through `PermissionProfileState` and
  no longer accept loose profile/id pairs.
  3. Skim `codex-rs/core/src/session/session.rs` for the session
  projection path; it now builds the snapshot before installing it.
  4. Skim the TUI changes as call-site migration from loose argument pairs
  to explicit snapshot construction.
  
  ## Verification
  
  - `cargo test -p codex-core
  permission_snapshot_setter_preserves_permission_constraints`
  - `cargo test -p codex-tui status_permissions_`
  - `cargo test -p codex-tui
  session_configured_preserves_profile_workspace_roots`
  - `just fix -p codex-core -p codex-tui`

  Michael Bolin · 2026-05-16 07:26:18 -07:00
  108234b5eb
• Preserve image detail in app-server inputs (#20693)

  ## Summary
  
  - Add optional image detail to user image inputs across core, app-server
  v2, thread history/event mapping, and the generated app-server
  schemas/types.
  - Preserve requested detail when serializing Responses image inputs:
  omitted detail stays on the existing `high` default, while explicit
  `original` keeps local images on the original-resolution path.
  - Support `high`/`original` consistently for tool image outputs,
  including MCP `codex/imageDetail`, code-mode image helpers, and
  `view_image`.

  Curtis 'Fjord' Hawthorne · 2026-05-15 15:04:04 -07:00
  8543e39885
• core: construct test permission profiles directly (#22795)

  ## Why
  
  The core migration is trying to make `PermissionProfile` the shape tests
  and runtime code reason about, leaving `SandboxPolicy` only where legacy
  behavior is explicitly under test. The local
  `permission_profile_for_sandbox_policy()` test helpers kept new
  permission-profile tests mentally tied to the old sandbox model even
  when the equivalent profile is straightforward.
  
  ## What Changed
  
  - Removed the `permission_profile_for_sandbox_policy()` helper from the
  network proxy spec tests and session tests.
  - Replaced legacy conversions for read-only, workspace-write, and
  full-access cases with `PermissionProfile::read_only()`,
  `PermissionProfile::workspace_write()`, and
  `PermissionProfile::Disabled`.
  - Constructed the external-sandbox session test's
  `PermissionProfile::External` directly, while preserving the legacy
  `SandboxPolicy` only where the test still exercises legacy config update
  behavior.
  
  ## How To Review
  
  This PR is intentionally test-only. Review the two touched files and
  check that each replacement preserves the old legacy mapping:
  
  - `SandboxPolicy::new_read_only_policy()` ->
  `PermissionProfile::read_only()`
  - `SandboxPolicy::new_workspace_write_policy()` ->
  `PermissionProfile::workspace_write()`
  - `SandboxPolicy::DangerFullAccess` -> `PermissionProfile::Disabled`
  - `SandboxPolicy::ExternalSandbox { network_access: Restricted }` ->
  `PermissionProfile::External { network: Restricted }`
  
  ## Verification
  
  - `cargo test -p codex-core
  requirements_allowed_domains_are_a_baseline_for_user_allowlist`
  - `cargo test -p codex-core
  start_managed_network_proxy_applies_execpolicy_network_rules`
  - `cargo test -p codex-core
  session_configured_reports_permission_profile_for_external_sandbox`
  - `cargo test -p codex-core
  managed_network_proxy_decider_survives_full_access_start`
  - `just fix -p codex-core`
  
  
  
  
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22795).
  * #22891
  * __->__ #22795

  Michael Bolin · 2026-05-15 13:09:25 -07:00
  8df2d96860
• Move memory prompt injection to app-server extension (#22841)

  ## Why
  
  Memory prompt injection should be owned by the extension path that
  app-server composes at runtime, not by an inlined special case inside
  `codex-core`. This keeps `codex-core` focused on session orchestration
  while allowing the memories extension to own its app-server prompt
  behavior.
  
  ## What Changed
  
  - Registers `codex-memories-extension` in the app-server extension
  registry.
  - Moves the memory developer-instruction injection out of
  `core/src/session/mod.rs` and into the memories extension prompt
  contributor.
  - Adds config-change handling so the extension keeps its per-thread
  memory settings in sync after startup.
  - Leaves memories read/retrieval tools unregistered for now so this PR
  only changes prompt injection.
  - Removes the stale `cargo-shear` ignore now that app-server depends on
  the extension crate.
  
  ## Validation
  
  Not run locally; validation is left to CI.

  jif-oai · 2026-05-15 16:19:34 +02:00
  cccde930ce
• Remove zombie tools spec module (#22820)

  ## Summary
  
  - move tool_user_shell_type out of the old tools::spec module and call
  it from tools directly
  - attach the remaining spec planning model tests under spec_plan
  - delete core/src/tools/spec.rs
  
  ## Tests
  
  - just fmt
  - cargo test -p codex-core tools::spec_plan
  
  Note: a broader cargo test -p codex-core run on the earlier PR-head
  worktree still hit the pre-existing stack overflow in
  agent::control::tests::spawn_agent_fork_last_n_turns_keeps_only_recent_turns.

  jif-oai · 2026-05-15 13:44:58 +02:00
  c03cea4ca2
• 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
• [codex] Use compaction_trigger item for remote compaction v2 (#22809)

  ## Why
  
  Remote compaction v2 was still using `context_compaction` as both the
  request trigger and the compacted output shape. The Responses API now
  has the landed contract for this flow: Codex sends a dedicated `{
  "type": "compaction_trigger" }` input item, and the backend returns the
  standard `compaction` output item with encrypted content.
  
  This aligns the v2 path with that wire contract while preserving the
  existing local compacted-history post-processing behavior.
  
  ## What changed
  
  - Add `ResponseItem::CompactionTrigger` and regenerate the app-server
  protocol schema fixtures.
  - Send `compaction_trigger` from `remote_compaction_v2` instead of a
  payload-less `context_compaction`.
  - Collect exactly one backend `compaction` output item, then reuse the
  existing compacted-history rebuilding path.
  - Treat the trigger item as a transient request marker rather than model
  output or persisted rollout/memory content.
  
  ## Verification
  
  - `cargo test -p codex-protocol compaction_trigger`
  - `cargo test -p codex-core remote_compact_v2`
  - `cargo test -p codex-core compact_remote_v2`
  - `cargo test -p codex-core
  responses_websocket_sends_response_processed_after_remote_compaction_v2`
  - `just write-app-server-schema`
  - `cargo test -p codex-app-server-protocol schema_fixtures`

  jif-oai · 2026-05-15 11:40:35 +02:00
  0322ac3df8
• app-server: use permission ids and runtime workspace roots (#22611)

  ## Why
  
  This PR builds on [#22610](https://github.com/openai/codex/pull/22610)
  and is the app-server side of the migration from mutable per-turn
  `SandboxPolicy` replacement toward selecting immutable permission
  profiles by id plus mutable runtime workspace roots.
  
  Once permission profiles can carry their own immutable
  `workspace_roots`, app-server no longer needs to mutate the selected
  `PermissionProfile` just to represent thread-specific filesystem
  context. The mutable part now lives on the thread as explicit
  `runtimeWorkspaceRoots`, while `:workspace_roots` remains symbolic until
  the sandbox is realized for a turn.
  
  ## What Changed
  
  - Replaced the v2 permission-selection wrapper surface with plain
  profile ids for `thread/start`, `thread/resume`, `thread/fork`, and
  `turn/start`.
  - Removed the API surface for profile modifications
  (`PermissionProfileSelectionParams`,
  `PermissionProfileModificationParams`,
  `ActivePermissionProfileModification`).
  - Added experimental `runtimeWorkspaceRoots` fields to the thread
  lifecycle and turn-start APIs.
  - Threaded runtime workspace roots through core session/thread
  snapshots, turn overrides, app-server request handling, and command
  execution permission resolution.
  - Kept session permission state symbolic so later runtime root updates
  and cwd-only implicit-root retargeting rebind `:workspace_roots`
  correctly.
  - Updated the embedded clients just enough to send and restore the new
  thread state.
  - Refreshed the generated schema/TypeScript artifacts and the app-server
  README to match the new contract.
  
  ## Verification
  
  Targeted coverage for this layer lives in:
  
  - `codex-rs/app-server-protocol/src/protocol/v2/tests.rs`
  - `codex-rs/app-server/tests/suite/v2/thread_start.rs`
  - `codex-rs/app-server/tests/suite/v2/thread_resume.rs`
  - `codex-rs/app-server/tests/suite/v2/turn_start.rs`
  - `codex-rs/core/src/session/tests.rs`
  
  The key regression checks exercise that:
  
  - `runtimeWorkspaceRoots` resolve against the effective cwd on thread
  start.
  - Profile-declared workspace roots are excluded from the runtime
  workspace roots returned by app-server.
  - A turn-level runtime workspace-root update persists onto the thread
  and is returned by `thread/resume`.
  - A named permission profile selected on one turn remains symbolic so a
  later runtime-root-only turn update changes the actual sandbox writes.
  - A cwd-only turn update retargets the implicit runtime cwd root while
  preserving additional runtime roots.
  - The protocol fixtures and generated client artifacts stay in sync with
  the string-based permission selection contract.
  
  
  
  
  
  
  
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22611).
  * #22612
  * __->__ #22611

  Michael Bolin · 2026-05-14 23:00:05 -07:00
  8a5306ff88
• permissions: resolve profile identity with constraints (#22683)

  ## Why
  
  This PR is the invariant-cleanup layer that follows the workspace-roots
  base merged in [#22610](https://github.com/openai/codex/pull/22610).
  
  #22610 adds `[permissions.<id>.workspace_roots]` and keeps runtime
  workspace roots separate from the raw permission profile, but its
  in-memory representation is intentionally transitional: `Permissions`
  still carries the selected profile identity next to a constrained
  `PermissionProfile`. That makes APIs such as
  `set_constrained_permission_profile_with_active_profile()` fragile
  because the id and value only mean the right thing when every caller
  keeps them in sync.
  
  This PR introduces a single resolved profile state so profile identity,
  `extends`, the profile value, and profile-declared workspace roots
  travel together. The next PR,
  [#22611](https://github.com/openai/codex/pull/22611), builds on this by
  changing the app-server turn API to select permission profiles by id
  plus runtime workspace roots.
  
  ## Stack Context
  
  - #22610, now merged: adds profile-declared `workspace_roots`, runtime
  workspace roots, and `:workspace_roots` materialization.
  - This PR: replaces the parallel active-profile/profile-value fields
  with `PermissionProfileState`.
  - #22611: switches app-server turn updates toward profile ids plus
  runtime workspace roots.
  - #22612: updates TUI/exec summaries to show the effective workspace
  roots.
  
  Keeping this separate from #22611 is deliberate: reviewers can validate
  the internal state invariant before reviewing the app-server protocol
  migration.
  
  ## What Changed
  
  - Added `ResolvedPermissionProfile::{Legacy, BuiltIn, Named}` and
  `PermissionProfileState`.
  - Typed built-in profile ids with `BuiltInPermissionProfileId`.
  - Moved selected profile identity and profile-declared workspace roots
  into the resolved state.
  - Replaced `Permissions` parallel profile fields with one
  `permission_profile_state`.
  - Removed `set_constrained_permission_profile_with_active_profile()`
  from session sync paths.
  - Kept trusted session replay/`SessionConfigured` compatibility through
  explicit session snapshot helpers.
  - Updated session configuration, MCP initialization, app-server, exec,
  TUI, and guardian call sites to consume `&PermissionProfile` directly.
  
  ## Review Guide
  
  Start with `codex-rs/core/src/config/resolved_permission_profile.rs`; it
  is the new invariant boundary. Then review
  `codex-rs/core/src/config/mod.rs` to see how config loading records
  active profile identity and profile workspace roots. The remaining
  call-site changes are mostly mechanical fallout from
  `Permissions::permission_profile()` returning `&PermissionProfile`
  instead of `&Constrained<PermissionProfile>`.
  
  ## Verification
  
  The existing config/session coverage now constructs and asserts through
  `PermissionProfileState`. The workspace-root config test also asserts
  that profile-declared roots are preserved in the resolved state, which
  is the behavior #22611 relies on when runtime roots become mutable
  through the app-server API.
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22683).
  * #22612
  * #22611
  * __->__ #22683

  Michael Bolin · 2026-05-14 18:47:44 -07:00
  3c6d727810
• Add user_input_requested_during_turn to MCP turn metadata (#22237)

  ## Why
  - Similar change as https://github.com/openai/codex/pull/21219
  - Without change: MCP tool calls receive
  `_meta["x-codex-turn-metadata"]` with various key values.
  - Issue: MCP servers currently do not know if user input was requested
  during the turn (Ex: Model decides to prompt the user for approval
  mid-turn before making a possibly risky tool call). MCP servers may want
  to know this when tracking latency metrics because these instances are
  inflated.
  
  ## What Changed
  - With change: MCP turn metadata now includes
  `user_input_requested_during_turn` when a model-visible
  `request_user_input` call happened earlier in the turn, propagated in
  `_meta["x-codex-turn-metadata"]`.
  - `mark_turn_user_input_requested()` is called when user input is
  requested through either MCP elicitation (`mcp.rs`) or the
  `request_user_input` tool (`mod.rs`).
  - MCP tool call `_meta` is now built immediately before execution
  (`mcp_tool_call.rs`) so user input requested earlier in the same turn,
  including within the same tool call via elicitation, is reflected in the
  metadata.
  - Normal `/responses` turn metadata headers are unchanged.
  
  ## Verification
  - `codex-rs/core/src/session/mcp_tests.rs`
  - `codex-rs/core/src/tools/handlers/request_user_input_tests.rs`
  - `codex-rs/core/src/turn_metadata_tests.rs`
  - `codex-rs/core/tests/suite/search_tool.rs`

  mchen-oai · 2026-05-15 01:26:50 +00:00
  10cf1f79dd
• permissions: support workspace roots in profiles (#22610)

  ## Why
  
  This is the configuration/model half of the alternative permissions
  migration we discussed as a comparison point for
  [#22401](https://github.com/openai/codex/pull/22401) and
  [#22402](https://github.com/openai/codex/pull/22402).
  
  The old `workspace-write` model mixes three concerns that we want to
  keep separate:
  - reusable profile rules that should stay immutable once selected
  - user/runtime workspace roots from `cwd`, `--add-dir`, and legacy
  workspace-write config
  - internal Codex writable roots such as memories, which should not be
  shown as user workspace roots
  
  This PR gives permission profiles first-class `workspace_roots` so users
  can opt multiple repositories into the same `:workspace_roots` rules
  without using broad absolute-path write grants. It also starts
  separating the raw selected profile from the effective runtime profile
  by making `Permissions` expose explicit accessors instead of public
  mutable fields.
  
  A representative `config.toml` looks like this:
  
  ```toml
  default_permissions = "dev"
  
  [permissions.dev.workspace_roots]
  "~/code/openai" = true
  "~/code/developers-website" = true
  
  [permissions.dev.filesystem.":workspace_roots"]
  "." = "write"
  ".codex" = "read"
  ".git" = "read"
  ".vscode" = "read"
  ```
  
  If Codex starts in `~/code/codex` with that profile selected, the
  effective workspace-root set becomes:
  - `~/code/codex` from the runtime `cwd`
  - `~/code/openai` from the profile
  - `~/code/developers-website` from the profile
  
  The `:workspace_roots` rules are materialized across each root, so
  `.git`, `.codex`, and `.vscode` stay scoped the same way everywhere.
  Runtime additions such as `--add-dir` can still layer on later stack
  entries without mutating the selected profile.
  
  ## Stack Shape
  
  This PR intentionally stops before the profile-identity cleanup in
  [#22683](https://github.com/openai/codex/pull/22683) so the base review
  stays focused on config loading, workspace-root materialization, and
  compatibility with legacy `workspace-write`.
  
  The representation in this PR is therefore transitional: `Permissions`
  carries enough state to distinguish the raw constrained profile from the
  effective runtime profile, and there are still call sites that must keep
  the active profile identity and constrained profile value in sync. The
  follow-up PR replaces that with a single resolved profile state
  (`ResolvedPermissionProfile` / `PermissionProfileState`) that keeps the
  profile id, immutable `PermissionProfile`, and profile-declared
  workspace roots together. That follow-up removes APIs such as
  `set_constrained_permission_profile_with_active_profile()` where
  separate arguments could drift out of sync.
  
  Downstream PRs then build on this base to switch app-server turn updates
  to profile ids plus runtime workspace roots and to finish the
  user-visible summary behavior. Reviewers should judge this PR as the
  workspace-roots foundation, not as the final in-memory shape of selected
  permission profiles.
  
  ## Review Guide
  
  Suggested review order:
  
  1. Start with `codex-rs/core/src/config/mod.rs`.
  This is the main shape change in the base slice. `Permissions` now
  stores a private raw `Constrained<PermissionProfile>` plus runtime
  `workspace_roots`. Callers use `permission_profile()` when they need the
  raw constrained value and `effective_permission_profile()` when they
  need a materialized runtime profile. As noted above,
  [#22683](https://github.com/openai/codex/pull/22683) replaces this
  transitional shape with a resolved profile state that keeps identity and
  profile data together.
  
  2. Review `codex-rs/config/src/permissions_toml.rs` and
  `codex-rs/core/src/config/permissions.rs`.
  These add `[permissions.<id>.workspace_roots]`, resolve enabled entries
  relative to the policy cwd, and keep `:workspace_roots` deny-read glob
  patterns symbolic until the actual roots are known.
  
  3. Review `codex-rs/protocol/src/permissions.rs` and
  `codex-rs/protocol/src/models.rs`.
  These add the policy/profile materialization helpers that expand exact
  `:workspace_roots` entries and scoped deny-read globs over every
  workspace root. This is also where `ActivePermissionProfileModification`
  is removed from the core model.
  
  4. Review the legacy bridge in
  `Config::load_from_base_config_with_overrides` and
  `Config::set_legacy_sandbox_policy`.
  This is where legacy `workspace-write` roots become runtime workspace
  roots, while Codex internal writable roots stay internal and do not
  appear as user-facing workspace roots.
  
  5. Then skim downstream call sites.
  The interesting pattern is raw-vs-effective access: state/proxy/bwrap
  paths keep the raw constrained profile, while execution, summaries, and
  user-visible status use the effective profile and workspace-root list.
  
  ## What Changed
  
  - added `[permissions.<id>.workspace_roots]` to the config model and
  schema
  - added runtime `workspace_roots` state to `Config`/`Permissions` and
  `ConfigOverrides`
  - made `Permissions` profile fields private and replaced direct mutation
  with accessors/setters
  - added `PermissionProfile` and `FileSystemSandboxPolicy` helpers for
  materializing `:workspace_roots` exact paths and deny-read globs across
  all roots
  - moved legacy additional writable roots into runtime workspace-root
  state instead of active profile modifications
  - removed `ActivePermissionProfileModification` and its app-server
  protocol/schema export
  - updated sandbox/status summary paths so internal writable roots are
  not reported as user workspace roots
  
  ## Verification Strategy
  
  The targeted tests cover the behavior at the layers where regressions
  are most likely:
  - `codex-rs/core/src/config/config_tests.rs` verifies config loading,
  legacy workspace-root seeding, effective profile materialization, and
  memory-root handling.
  - `codex-rs/core/src/config/permissions_tests.rs` verifies profile
  `workspace_roots` parsing and `:workspace_roots` scoped/glob
  compilation.
  - `codex-rs/protocol/src/permissions.rs` unit tests verify exact and
  glob materialization over multiple workspace roots.
  - `codex-rs/tui/src/status/tests.rs` and
  `codex-rs/utils/sandbox-summary/src/sandbox_summary.rs` verify the
  user-facing summaries show effective workspace roots and hide internal
  writes.
  
  I also ran `cargo check --tests` locally after the latest stack refresh
  to catch cross-crate API breakage from the private-field/accessor
  changes.
  
  
  
  
  
  
  
  ---
  [//]: # (BEGIN SAPLING FOOTER)
  Stack created with [Sapling](https://sapling-scm.com). Best reviewed
  with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22610).
  * #22612
  * #22611
  * #22683
  * __->__ #22610

  Michael Bolin · 2026-05-14 18:25:23 -07:00
  c25d905f61
• [codex] Remove experimental instructions file config (#22724)

  ## Summary
  
  Remove the deprecated `experimental_instructions_file` config setting
  from the typed config surface and the remaining deprecation-notice
  plumbing. `model_instructions_file` remains the supported setting and
  its loading path is unchanged.
  
  The setting was deprecated when it was renamed to
  `model_instructions_file` on January 20, 2026 in
  https://github.com/openai/codex/pull/9555.
  
  ## Changes
  
  - Remove `experimental_instructions_file` from `ConfigToml` and
  `ConfigProfile`.
  - Delete the custom config-layer scan and session deprecation notice for
  the removed setting.
  - Stop clearing the removed field from generated session config locks.
  - Remove the obsolete deprecation-notice test case while keeping
  `model_instructions_file` coverage intact.
  
  ## Validation
  
  - `just write-config-schema`
  - `just fmt`
  - `cargo test -p codex-config`
  - `cargo test -p codex-core model_instructions_file`
  - `just fix -p codex-core`
  - `git diff --check`
  
  Co-authored-by: Codex <noreply@openai.com>

  Dylan Hurd · 2026-05-14 18:04:26 -07:00
  7dbe1c9498
• permissions: canonicalize workspace_roots and danger-full-access names (#22624)

  ## Why
  
  This is a small precursor to the larger permissions-migration work. Both
  the comparison stack in
  [#22401](https://github.com/openai/codex/pull/22401) /
  [#22402](https://github.com/openai/codex/pull/22402) and the alternate
  stack in [#22610](https://github.com/openai/codex/pull/22610) /
  [#22611](https://github.com/openai/codex/pull/22611) /
  [#22612](https://github.com/openai/codex/pull/22612) are easier to
  review if the terminology is already settled underneath them.
  
  Because `:project_roots` and `:danger-no-sandbox` have not shipped as
  stable user-facing surface area, carrying them forward as aliases would
  just add more migration logic to the later stacks. This PR removes that
  ambiguity now so the follow-on work can rely on one spelling for each
  built-in concept.
  
  ## What Changed
  
  - renamed the config-facing special filesystem key from `:project_roots`
  to `:workspace_roots`
  - dropped unpublished `:project_roots` parsing support in
  `core/src/config/permissions.rs`, so new config only recognizes
  `:workspace_roots`
  - renamed the built-in full-access permission profile id from
  `:danger-no-sandbox` to `:danger-full-access`
  - dropped unpublished `:danger-no-sandbox` support entirely, including
  the old active-profile canonicalization path, and added explicit
  rejection coverage for the legacy id
  - introduced shared built-in permission-profile id constants in
  `codex-rs/protocol/src/models.rs`
  - updated `core`, `app-server`, and `tui` call sites that special-case
  built-in profiles to use the shared constants and canonical ids
  - updated tests and the Linux sandbox README to use `:workspace_roots` /
  `:danger-full-access`
  
  ## Verification
  
  I focused verification on the three places this rename can regress:
  config parsing, active-profile identity surfaced back out of `core`, and
  user/server call sites that special-case built-in profiles.
  
  Targeted checks:
  
  -
  `config::tests::default_permissions_can_select_builtin_profile_without_permissions_table`
  -
  `config::tests::default_permissions_read_only_applies_additional_writable_roots_as_modifications`
  -
  `config::tests::default_permissions_can_select_builtin_full_access_profile`
  - `config::tests::legacy_danger_no_sandbox_is_rejected`
  - `workspace_root` filtered `codex-core` tests
  -
  `request_processors::thread_processor::thread_processor_tests::thread_processor_behavior_tests::requested_permissions_trust_project_uses_permission_profile_intent`
  -
  `suite::v2::turn_start::turn_start_rejects_invalid_permission_selection_before_starting_turn`
  - `status::tests::status_snapshot_shows_auto_review_permissions`
  -
  `status::tests::status_permissions_full_disk_managed_with_network_is_danger_full_access`
  -
  `app_server_session::tests::embedded_turn_permissions_use_active_profile_selection`

  Michael Bolin · 2026-05-14 08:45:54 -07:00
  01d93fd9fc
• Fix turn extension data task plumbing (#22646)

  ## Summary
  - carry the per-turn extension data through RunningTask so abort
  handling can rebuild SessionTaskContext
  - update stale test ExtensionData::new() callsites to pass the turn id
  
  ## Testing
  - Not run after PR branch creation; CI will cover.

  jif-oai · 2026-05-14 16:00:06 +02:00
  12bfb57139
• feat: add layered --profile-v2 config files (#17141)

  ## Why
  
  `--profile-v2 <name>` gives launchers and runtime entry points a named
  profile config without making each profile duplicate the base user
  config. The base `$CODEX_HOME/config.toml` still loads first, then
  `$CODEX_HOME/<name>.config.toml` layers above it and becomes the active
  writable user config for that session.
  
  That keeps shared defaults, plugin/MCP setup, and managed/user
  constraints in one place while letting a named profile override only the
  pieces that need to differ.
  
  ## What Changed
  
  - Added the shared `--profile-v2 <name>` runtime option with validated
  plain names, now represented by `ProfileV2Name`.
  - Extended config layer state so the base user config and selected
  profile config are both `User` layers; APIs expose the active user layer
  and merged effective user config.
  - Threaded profile selection through runtime entry points: `codex`,
  `codex exec`, `codex review`, `codex resume`, `codex fork`, and `codex
  debug prompt-input`.
  - Made user-facing config writes go to the selected profile file when
  active, including TUI/settings persistence, app-server config writes,
  and MCP/app tool approval persistence.
  - Made plugin, marketplace, MCP, hooks, and config reload paths read
  from the merged user config so base and profile layers both participate.
  - Updated app-server config layer schemas to mark profile-backed user
  layers.
  
  ## Limits
  
  `--profile-v2` is still rejected for config-management subcommands such
  as feature, MCP, and marketplace edits. Those paths remain tied to the
  base `config.toml` until they have explicit profile-selection semantics.
  
  Some adjacent background writes may still update base or global state
  rather than the selected profile:
  
  - marketplace auto-upgrade metadata
  - automatic MCP dependency installs from skills
  - remote plugin sync or uninstall config edits
  - personality migration marker/default writes
  
  ## Verification
  
  Added targeted coverage for profile name validation, layer
  ordering/merging, selected-profile writes, app-server config writes,
  session hot reload, plugin config merging, hooks/config fixture updates,
  and MCP/app approval persistence.
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  jif-oai · 2026-05-14 15:16:15 +02:00
  deedf3b2c4
• Wire turn item contributors into stream output (#22494)

  ## Summary
  - run registered TurnItemContributor hooks for parsed stream output
  items
  - plumb the active turn extension store into stream item handling
  - preserve existing memory citation parsing as fallback after
  contributors run
  
  ## Tests
  - cargo test -p codex-core stream_events_utils -- --nocapture
  - just fmt
  - just fix -p codex-core
  - git diff --check

  jif-oai · 2026-05-14 14:48:17 +02:00
  17cd321c32
• chore(config) rm experimental_use_freeform_apply_patch (#22565)

  ## Summary
  Get rid of the `experimental_use_freeform_apply_patch` config option,
  since it is now encoded in model config. No deprecation message since it
  has been experimental this entire time.
  
  ## Testing
  - [x] Updated unit tests
  
  ---------
  
  Co-authored-by: Codex <noreply@openai.com>

  Dylan Hurd · 2026-05-13 17:52:15 -07:00
  e33cf9ae28
• Make multi_agent_v2 wait_agent timeouts configurable (#22528)

  ## Why
  
  `multi_agent_v2` already allowed configuring the minimum `wait_agent`
  timeout, but the default timeout and upper bound were still hard-coded.
  That made it hard to tune waits for subagent mailbox activity in
  sessions that need either faster wakeups or longer waits, and it meant
  the model-visible `wait_agent` schema could not fully reflect the
  resolved runtime limits.
  
  ## What Changed
  
  - Added `features.multi_agent_v2.max_wait_timeout_ms` and
  `features.multi_agent_v2.default_wait_timeout_ms` alongside the existing
  `min_wait_timeout_ms` setting.
  - Validated all three timeouts in config as `0..=3_600_000`, with
  `min_wait_timeout_ms <= default_wait_timeout_ms <= max_wait_timeout_ms`.
  - Thread and review session tool config now passes the resolved
  min/default/max values into the `wait_agent` tool schema.
  - `wait_agent` now uses the configured default when `timeout_ms` is
  omitted and rejects explicit values outside the configured min/max range
  instead of silently clamping them.
  - Updated the generated config schema and config-lock test coverage for
  the new fields.

  Andrey Mishchenko · 2026-05-13 14:43:06 -07:00
  7c57a59f51
• Use selected environment cwd for filesystem helpers (#22542)

  ## Why
  
  `TurnContext::cwd` is deprecated in favor of resolving paths from the
  selected turn environment cwd. A few filesystem-oriented paths were
  still constructing sandbox context from the legacy cwd and then mutating
  it afterward, or resolving local file paths through the deprecated
  helper.
  
  ## What changed
  
  - Make `TurnContext::file_system_sandbox_context` take the trusted cwd
  explicitly.
  - Pass the selected turn environment cwd directly from `apply_patch` and
  `view_image` call sites.
  - Restrict `spawn_agents_on_csv` to exactly one local environment and
  resolve input/output CSV paths from that local environment cwd.
  - Remove a redundant test setup assignment that only synchronized
  deprecated `TurnContext::cwd` with a replaced config.
  
  ## Validation
  
  - `cargo test -p codex-core view_image`
  - `cargo test -p codex-core
  maybe_persist_mcp_tool_approval_writes_project_config_for_project_server`
  - `cargo test -p codex-core parse_csv_supports_quotes_and_commas`
  - `git diff --check`

  pakrym-oai · 2026-05-13 13:18:56 -07:00
  3ac1d15598
• chore(config) rm Feature::CodexGitCommit (#22412)

  ## Summary
  Removes the unused Feature::CodexGitCommit
  
  ## Testing
  - [x] tests pass

  Dylan Hurd · 2026-05-13 12:33:36 -07:00
  d18a7c982e
• 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
• [codex] Remove unused legacy shell tools (#22246)

  ## Why
  
  Recent session history showed no active use of the raw `shell`,
  `local_shell`, or `container.exec` execution surfaces. Keeping those
  handlers/specs wired into core leaves duplicate shell execution paths
  alongside the supported `shell_command` and unified exec tools.
  
  ## What changed
  
  - Removed the raw `shell` handler/spec and its `ShellToolCallParams`
  protocol helper.
  - Removed the legacy `local_shell` and `container.exec` handler/spec
  plumbing while preserving persisted-history compatibility for old
  response items.
  - Normalized model/config `default` and `local` shell selections to
  `shell_command`.
  - Pruned tests that exercised removed raw-shell/local-shell/apply-patch
  variants and kept coverage on `shell_command`, unified exec, and
  freeform `apply_patch`.
  
  ## Verification
  
  - `git diff --check`
  - `cargo test -p codex-protocol`
  - `cargo test -p codex-tools`
  - `cargo test -p codex-core tools::handlers::shell`
  - `cargo test -p codex-core tools::spec`
  - `cargo test -p codex-core tools::router`
  - `cargo test -p codex-core
  active_call_preserves_triggering_command_context`
  - `cargo test -p codex-core guardian_tests`
  - `cargo test -p codex-core --test all shell_serialization`
  - `cargo test -p codex-core --test all apply_patch_cli`
  - `cargo test -p codex-core --test all shell_command_`
  - `cargo test -p codex-core --test all local_shell`
  - `cargo test -p codex-core --test all otel::`
  - `cargo test -p codex-core --test all hooks::`
  - `just fix -p codex-core`
  - `just fix -p codex-tools`

  pakrym-oai · 2026-05-13 16:43:25 +00:00
  83decfa300
• fix: main (#22503)

  Fix main due to conflicting merge

  jif-oai · 2026-05-13 17:28:37 +02:00
  441c2f818f
• feat: add config-change extension contributor (#22488)

  ## Why
  
  Extensions can observe thread and turn lifecycle events today, but there
  was no single host-owned hook for changes to the effective thread
  configuration. That makes features that need to react to model,
  permission, or tool-suggest updates either depend on individual mutation
  paths or risk going stale after runtime config refreshes.
  
  This adds a typed config-change contributor so extension-owned state can
  stay synchronized with the effective thread config while the host
  remains responsible for deciding when config changed.
  
  ## What Changed
  
  - Added `ConfigContributor<C>` to `codex_extension_api`, with
  before/after immutable snapshots of the effective config plus
  session/thread extension stores.
  - Added registry builder/accessor support through `config_contributor`
  and `config_contributors`.
  - Emits config-change callbacks after committed updates from session
  settings, per-turn setting updates, and `refresh_runtime_config`.
  - Builds effective config snapshots only when config contributors are
  registered, and suppresses no-op callbacks when the before/after
  snapshots are equal.
  - Added a core session regression test that verifies contributors
  observe both model changes and user-layer runtime config changes,
  including access to session and thread extension stores.
  
  ## Validation
  
  Added `config_change_contributor_observes_effective_config_changes` in
  `codex-rs/core/src/session/tests.rs` to cover the new contributor path.

  jif-oai · 2026-05-13 17:13:34 +02:00
  34bb85519f
• Make context contributors async (#22491)

  ## Summary
  - make ContextContributor return a boxed Send future
  - await context contributors during initial context assembly
  - update existing contributors and extension-api examples for the async
  contract
  
  ## Testing
  - cargo test -p codex-extension-api --examples
  - cargo test -p codex-git-attribution
  - cargo test -p codex-core
  build_initial_context_includes_git_attribution_from_extensions --
  --nocapture
  - cargo test -p codex-core
  build_initial_context_omits_git_attribution_when_feature_is_disabled --
  --nocapture
  - cargo test -p codex-core (fails in unrelated
  agent::control::tests::spawn_agent_fork_last_n_turns_keeps_only_recent_turns
  stack overflow)
  - just fix -p codex-extension-api
  - just fix -p codex-git-attribution
  - just fix -p codex-core
  - cargo clippy -p codex-extension-api --examples

  jif-oai · 2026-05-13 16:43:28 +02:00
  68e045a631
• feat: move extension scope ids into ExtensionData (#22490)

  ## Summary
  - add a scoped level_id to ExtensionData and expose it through
  level_id()
  - remove thread_id/turn_id parameters from extension contributor inputs
  where the scoped ExtensionData already carries that identity
  - move turn-scoped extension data onto TurnContext so token usage and
  lifecycle contributors can share the same turn store
  
  ## Testing
  - cargo check -p codex-extension-api -p codex-core --tests
  - cargo test -p codex-extension-api
  - cargo test -p codex-guardian
  - cargo test -p codex-core --lib
  record_token_usage_info_notifies_extension_contributors
  - cargo test -p codex-core --lib
  submission_loop_channel_close_emits_thread_stop_lifecycle
  - cargo test -p codex-core --lib
  submission_loop_channel_close_aborts_active_turn_before_thread_stop_lifecycle
  - just fix -p codex-extension-api
  - just fix -p codex-guardian
  - just fix -p codex-core
  - just fmt
  
  ## Note
  - Attempted cargo test -p codex-core; it aborted in
  agent::control::tests::spawn_agent_fork_last_n_turns_keeps_only_recent_turns
  with the existing stack overflow before the full suite completed.

  jif-oai · 2026-05-13 16:13:16 +02:00
  1dcc89f1d4
• feat: add token usage contributor hook (#22485)

  ## Why
  
  Extensions need a stable place to observe token accounting after Codex
  folds model-provider usage into the session's cached `TokenUsageInfo`.
  Without a contributor hook, extension-owned features that need last-turn
  or cumulative token usage have to duplicate session plumbing or infer
  state from client-facing `TokenCount` notifications.
  
  ## What changed
  
  - Added `TokenUsageContributor` to `codex-extension-api`, passing
  session/thread `ExtensionData`, `ThreadId`, turn id, and the current
  `TokenUsageInfo`.
  - Added registry builder/storage support for token-usage contributors.
  - Invoked registered contributors from
  `Session::record_token_usage_info` after the session token cache is
  updated and before the client `TokenCount` notification is emitted.
  
  ## Testing
  
  - Added `record_token_usage_info_notifies_extension_contributors`,
  covering cumulative token usage updates and access to both extension
  stores.

  jif-oai · 2026-05-13 14:32:23 +02:00
  083c1962f9
• fix: emit thread stop lifecycle on implicit shutdown (#22482)

  ## Why
  
  The thread lifecycle contributor hooks from #22476 should observe every
  session teardown. The explicit `Op::Shutdown` path already emitted
  `on_thread_stop`, but when `submission_loop` exited because its
  submission channel closed, it only tore down runtime services. That
  meant extensions could miss the thread-stop lifecycle signal on implicit
  runtime shutdown.
  
  ## What Changed
  
  - Split shared runtime teardown into `shutdown_runtime_services(...)`.
  - Split thread-stop lifecycle emission into
  `emit_thread_stop_lifecycle(...)`.
  - Reused those helpers from both explicit shutdown and the channel-close
  shutdown path.
  - Tracked whether `Op::Shutdown` was received so the explicit path does
  not double-emit lifecycle events after it exits the loop.
  - Added a regression test that closes the submission channel and asserts
  `ThreadLifecycleContributor::on_thread_stop` runs once with the expected
  thread/session stores.
  
  ## Testing
  
  - `cargo test -p codex-core
  submission_loop_channel_close_emits_thread_stop_lifecycle`

  jif-oai · 2026-05-13 14:19:57 +02:00
  fcc2a92743
• feat: add thread lifecycle contributor hooks (#22476)

  ## Why
  
  Extensions that need thread-scoped state currently only get a start-time
  callback. That is enough for seeding stores, but it leaves the host
  without a shared extension seam for later thread rehydrate and flush
  work as thread ownership evolves. This PR turns that start-only seam
  into a host-owned thread lifecycle contributor contract so
  extension-private state can stay behind the extension API instead of
  leaking extra orchestration through core.
  
  ## What changed
  
  - Replaced `ThreadStartContributor` with `ThreadLifecycleContributor`
  and added typed lifecycle inputs for thread start, resume, and stop. The
  contract lives in
  [`contributors/thread_lifecycle.rs`](https://github.com/openai/codex/blob/d0e9211f70e58d6b07ef07e84f359d1b9aa25955/codex-rs/ext/extension-api/src/contributors/thread_lifecycle.rs#L1-L64).
  - Kept the existing start-time behavior intact by routing session
  construction through `on_thread_start`.
  - Invoked `on_thread_stop` during session shutdown before thread-scoped
  extension state is dropped, while isolating contributor failures behind
  warning logs.
  - Migrated `git-attribution` and `guardian` onto the lifecycle
  registration path.
  - Renamed the extension registry plumbing from start-specific
  contributors to lifecycle-specific contributors.
  
  ## Notes
  
  `on_thread_resume` is introduced at the API boundary here so extensions
  can target the final lifecycle shape; host resume dispatch can be wired
  where that runtime path is finalized.

  jif-oai · 2026-05-13 13:11:30 +02:00
  5ab7e6b4c6
• 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
• add --dangerously-bypass-hook-trust CLI flag (#21768)

  # Why
  
  Hook trust happens through the TUI in `/hooks` so it can block
  non-interactive use cases. This flag will allow users that are using
  codex headlessly to bypass hooks when they want to.
  
  # What
  
  This adds one invocation-scoped escape hatch.
  
  - the CLI flag sets a runtime-only `bypass_hook_trust` override; there
  is no durable `config.toml` setting
  - hook discovery still respects normal enablement, so explicitly
  disabled hooks remain disabled
  - we show a `--dangerously-bypass-hook-trust is enabled. Enabled hooks
  may run without review for this invocation.` message on startup so
  accidental use is visible in both interactive and exec flows
  
  This keeps “enabled” and “trusted” as separate concepts in the normal
  path, while giving CI/E2E callers a stable way to opt into the
  exceptional path when they already control the hook set.

  Abhinav · 2026-05-13 07:13:57 +00:00
  392e94e9ea
• 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
• 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
• Unify thread metadata updates above store (#22236)

  - make ThreadStore::update_thread_metadata accept a broad range of
  metadata patches
  - keep ThreadStore::append_items as raw canonical history append (no
  metadata side effects)
  - in the local store, write these metadata updates to a combination of
  sqlite and rollout jsonl files for backwards-compat. It special cases
  which fields need to go into jsonl vs sqlite vs whatever, confining the
  awkwardness to just this implementation
  - in remote stores we can simply persist the metadata directly to a
  database, no special casing required.
  - move the "implicit metadata updates triggered by appending rollout
  items" from the RolloutRecorder (which is local-threadstore-specific) to
  the LiveThread layer above the ThreadStore, inside of a private helper
  utility called ThreadMetadataSync. LiveThread calls ThreadStore
  append_items and update_metadata separately.
  - Add a generic update metadata method to ThreadManager that works on
  both live threads and "cold" threads
  - Call that ThreadManager method from app server code, so app server
  doesn't need to worry about whether the thread is live or not

  Tom · 2026-05-13 00:28:15 +00:00
  c51c65ad09
• chore(config) include_collaboration_mode_instructions (#22383)

  ## Summary
  Adds include_collaboration_mode_instructions, which is a config
  equivalent to include_permissions_instructions for collaboration modes.
  Desired for situations where we want to disable this instruction from
  entering the context
  
  ## Testing
  - [x] Added unit test

  Dylan Hurd · 2026-05-12 15:50:10 -07:00
  8123bddb16
• 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
• feat: guardian as an extension (contributors part) (#22216)

  Part 1 of guardian as extension. This bind all the logic to spawn
  another agent from an extension and it adds `ThreadId` in the start
  thread collaborator

  jif-oai · 2026-05-12 14:41:45 +02:00
  d996f5366f