## What changed
- Add an optional `toolOutput` to `turn/start` for starting or steering a turn with a named function-call output instead of user input.
- Emit standalone outputs as `functionCallOutput` thread items, persist them in durable history, and include them in resumed threads.
- Validate that tool outputs have a name, are not combined with nonempty `input`, satisfy the text-size limit, and use supported image URLs.
## Testing
- Cover standalone tool-output notifications, model input, and resumed history in both legacy and paginated history modes.
- Cover the text-size limit for structured tool output.
GitOrigin-RevId: a1eeec7b9b7de67b1a1c5e829a54552b85ec118b
## Why
Linux managed networking routed proxy connections through filesystem-backed Unix sockets, requiring an extra readable sandbox path and stale socket cleanup.
## What changed
- Transfer loopback TCP listeners from the sandbox namespace to host bridge processes over anonymous Unix socket pairs.
- Validate transferred descriptors, keep bootstrap channels private to each sandbox launch, and close them before running untrusted commands.
- Tie proxy bridge lifetime to the sandbox so cancellation closes active upstream connections.
## Testing
- Cover descriptor validation and interrupted handoffs.
- Verify concurrent sandboxes keep proxy endpoints isolated and do not inherit privileged sockets.
- Exercise managed networking end to end through `app-server`, confirming proxied access succeeds while direct host access remains blocked.
GitOrigin-RevId: 6561e09c83b927c604951bf2aa00ff532d179da5
## What changed
- Add the experimental `turn/start.cyberAccessProgram` option with `standard`,
`daybreakBlue`, and `daybreakRed` values.
- Forward the selection as `access_programs.cyber` on Responses, WebSocket,
and remote-compaction requests made with ChatGPT authentication, while
omitting it for API-key and custom-provider requests.
- Preserve the per-turn selection across recovery, compaction, and child-agent
turns without making it a persistent thread setting.
## Testing
- Cover app-server forwarding, authentication boundaries, WebSocket reuse,
turn recovery, compaction, and child-agent inheritance.
GitOrigin-RevId: d2eb468f365b2214c5099bc21741cf30f8bd2eb5
## What changed
- Add an optional `turnTrigger` field to app-server `turn/start` requests and
expose it in the generated protocol schemas.
- Propagate non-empty trigger values to Responses request metadata as the
reserved `turn_trigger` field, while preserving the original value when a
request steers an active turn.
- Classify turns started by queue dispatch, goal continuation, retry recovery,
and realtime handoff.
## Testing
- Cover HTTP and WebSocket metadata forwarding, steering behavior, reserved
metadata handling, and the built-in trigger classifications.
GitOrigin-RevId: c12fe2c522286db21b76081ae6154fbf6bfb3639
## What changed
- Add the experimental `turn/settings/update` method for changing `model`,
`effort`, `summary`, and `serviceTier` on a specific live turn without
changing future turns.
- Report whether the update was applied or the target turn was unavailable,
and reject unsupported fields, disabled feature use, unsafe model changes,
and direct updates to parent-owned subagents.
- Document the method's feature requirements, null handling, and limits.
## Testing
- Cover current-turn and future-turn isolation, rejected and unavailable
targets, feature and capability gates, saved threads, and subagent ownership.
GitOrigin-RevId: 18440f6d7ee5fcd06ae23bd41b22c492b62bb2b5
## What changed
- Add `serviceTierForTurn` to `turn/start` so a newly started turn can override the service tier without changing the thread's saved tier.
- Treat `"default"` as standard speed and omitted or `null` values as inheriting the thread tier.
- Keep `serviceTier` authoritative for subsequent turns when both fields are supplied, and ignore the turn-scoped override when steering an active turn.
## Testing
- Extend the app-server turn-start test to verify both the one-turn `"default"` override and inheritance on the following turn.
GitOrigin-RevId: 4c2c4db21d8d31617a7a6e6df65bf54834e72383
## Why
Analytics need to associate subagent activity with the top-level turn that
caused it, while avoiding a stale association when steering makes that origin
ambiguous.
## What changed
- Add `root_turn_id` to turn and tool-item analytics events.
- Read the root from live turn metadata when each event is built, reporting
`null` when the root is unknown or ambiguous.
- Propagate the metadata through control-tool and code-mode completion facts so
correlated and background tool events retain the correct root.
## Testing
- Cover root IDs for top-level turns, subagent turns, correlated code-mode
calls, and tool events emitted after turn completion.
- Verify that queued and subsequent events report `null` after the live root is
invalidated.
GitOrigin-RevId: 42fd76541c3c716cec74787d47b50adb2d22e6d2
## Why
Parent-owned Multi-Agent V2 subagents must remain controlled by their parent,
but several app-server endpoints could still mutate them directly.
## What changed
- Centralize the direct-input ownership check and apply it to turn injection,
MCP calls, reviews, compaction, rollback and revert, shell and Guardian
actions, realtime requests, and goal mutations.
- Enforce the same policy for goal mutations on unloaded threads while keeping
goal reads and turn interruption available.
- Document the affected endpoint behavior and continue exposing
`canAcceptDirectInput: false` for parent-owned subagents.
## Testing
- Cover direct-input rejection for both legacy and paginated thread history.
- Cover goal mutation ownership checks for unloaded V2 subagents, V1
subagents, and non-subagent V2 threads.
GitOrigin-RevId: 791b7af98490aed5eab4e672b90661acad11ec23
## What changed
- Apply the existing direct-input restriction to `thread/settings/update` for
parent-owned Multi-Agent V2 subagents.
- Document the restriction and extend the direct-input test to verify that the
request returns an invalid-request error.
GitOrigin-RevId: 2eead01c6f54ec637c68573378f3b56a7ee85652
## What changed
- Remove the legacy `shell_command` handler and runtime, leaving `exec_command`
and `write_stdin` as the shell execution tools.
- Treat legacy `shell_command` model metadata as `unified_exec`, and normalize
legacy user opt-outs so they do not disable command execution. Managed feature
requirements and `shell_tool` can still disable it.
- Preserve shell approvals, sandboxing, zsh-fork support, and output truncation
through the unified execution path.
## Testing
- Cover legacy configuration and model-metadata compatibility.
- Exercise unified shell execution, approvals, truncation, and `apply_patch`
serialization across the app-server and core test suites.
GitOrigin-RevId: 5c2fd6164fc3519cdae4944cb9db276b8467311c
## What changed
- Emit started and completed collaboration tool events for multi-agent v2
`spawn_agent` calls, including failed invocations.
- Record execution duration and successful child-agent configuration metadata
without including the spawn prompt.
- Deduplicate collaboration and subagent activity items by call ID when
calculating per-turn subagent tool counts.
## Testing
- Extend the app-server multi-agent v2 integration test to cover successful
and failed spawn telemetry, duration, prompt omission, and turn counts.
GitOrigin-RevId: c1c2fb9cc2a1a9b0f63ef68509ad36d11a92d1e5
## Why
Project instructions must respect the selected environment's filesystem read
permissions. Tightening those permissions for a later turn must not allow
previously cached instructions to reach the model.
## What changed
- Apply each environment's filesystem sandbox while discovering and reading
`AGENTS.md` files.
- Fail thread or turn setup when sandboxing blocks a discovered instruction
file, while allowing a restricted project with no instructions to start.
- Clear cached instructions before refresh and include the Windows sandbox
level in the cache key.
- Ignore inaccessible ancestor marker probes so readable instructions in the
selected working directory can still load.
## Testing
Added coverage for restricted projects, denied instruction files, cache
invalidation after permissions tighten, and unreadable ancestor markers.
GitOrigin-RevId: 6ea1a27b9c873a6260e4f87d42ae1317a6a4ae4b
## What changed
- Remove `untrusted` from the CLI, configuration schema, and MCP tool interface. Explicit `approval_policy = "untrusted"` settings now fail with an actionable error.
- Remove the known-safe command allowlist. Projects marked untrusted now request approval for every command unless an explicit exec policy rule allows it.
- Keep command parsing conservative by treating in-place `sed` forms as mutating and ignoring unrecognized commands when recording memory usage.
## Testing
- Cover rejection of the retired configuration value and approval requests for commands in untrusted projects.
GitOrigin-RevId: d6bf425edddfffbb325eee6acf383434af5fd33b
## What changed
- Emit `codex_control_tool_call_event` for built-in control tools such as
`request_user_input`, `update_plan`, `view_image`, and goal tools.
- Record correlation and timing metadata plus completed, failed, rejected, or
interrupted outcomes, and include these calls in turn-level tool counts.
- Keep tool arguments out of control-tool analytics events.
## Testing
- Extend the app-server turn profile test to cover successful and failed
control tools, event correlation, turn counts, and argument exclusion.
GitOrigin-RevId: c20f73dfb79654e31b4b5040eddb0e0d91cae10d
## Why
The model provider does not reliably identify which curated plugin catalog is
available. ChatGPT authentication can be used with a custom provider, while an
unauthenticated session should use the API-compatible catalog regardless of its
provider.
## What changed
- Select the ChatGPT curated catalog only for authentication modes that use the
Codex backend; use the API curated catalog for API-key and unauthenticated
sessions.
- Initialize standalone plugin managers with the current authentication mode
across CLI, app-server, MCP, and external-agent migration paths.
- Preserve authentication mode while detecting and importing migrated plugins.
## Testing
- Cover catalog and skill routing across ChatGPT, API-key, unauthenticated,
Bedrock, and custom-provider configurations.
- Verify authenticated plugin migration uses the ChatGPT curated marketplace.
GitOrigin-RevId: 660a339ee8891c33aad961078d3a979242a6a166
## What changed
- Add `TurnInputRequest` and typed submission results for atomically starting a turn, steering the active turn, or declining input with a specific reason.
- Expose `start_or_steer_turn`, `start_turn_if_idle`, and `steer_turn` on `CodexThread`, and migrate Core consumers to these APIs.
- Make app-server `turn/start` steer an active regular turn and return that turn's ID. Reject incompatible output schemas and non-steerable turns without applying settings or enqueueing input.
## Testing
- Cover concurrent start-or-steer submissions, accepted and rejected settings updates, output-schema compatibility, idle-start rejection, and app-server steering.
GitOrigin-RevId: dd9b5528d76ec650c019e97af420bc13190ea86a
## Why
Client-facing command execution items can include recognizable secrets in the
rendered command or parsed command actions.
## What changed
- Redact secrets in `commandExecution.command` and `commandActions` for live
items, completed items, and replayed thread history.
- Keep command approval requests backed by the original executable command and
parsed actions while using the redacted representation for display items.
- Document that execution item commands are redacted display values rather than
executable commands.
## Testing
- Cover redaction for command conversion, parsed search actions, legacy replay,
approval flows, completion notifications, and rejected commands.
GitOrigin-RevId: 2ad056f21882bf5166182ad1a4ff0bf6471d9c0e
## What changed
- Emit dynamic tool-call analytics for code mode `exec` and `wait` calls, including duration and terminal status.
- Associate code-mode cells and their nested tool calls with the originating and subsequent model response IDs.
- Buffer correlated tool events until the next response is known, while flushing pending events when turns, threads, or the analytics queue close.
## Testing
- Add reducer coverage for correlating `exec`, `wait`, and nested tool events across turns.
- Add an app-server test that verifies production analytics include the cell and response IDs for a code-mode `exec` call.
GitOrigin-RevId: 8b34ab59c1ad68ebbd57f9c8a05f19ab04df48a4
## What changed
- Record the effective detail setting and source and prepared dimensions for
successfully decoded images.
- Associate message images with their role and tool-output images with their
originating call ID.
- Include the collected image preparation metadata in the corresponding turn
analytics event.
## Testing
- Cover image resize metadata, tool-output attribution, turn aggregation, event
serialization, and app-server analytics output.
GitOrigin-RevId: dbfb5ba1ce7cb02dd93d9b579c5109817f16aef5
## What changed
- Load and cache the host skill provider catalog during world-state contribution.
- Render host skill listings from that catalog with Core-compatible budgeting, while preserving Core's full prompt injection for selected host skills.
- Reuse the cached host catalog for shadow selection, including when skill listings are disabled.
- Preserve an empty Core-compatible skills fragment when every entry exceeds the metadata budget, and make budget warnings independent of the configured percentage.
## Testing
- Cover provider-backed host listings, selected-skill prompt injection, shadow selection, disabled listings, oversized prompts, empty fragments, metrics, and warnings.
GitOrigin-RevId: b6b2d8ea14386356094cff5783d121d74657e9e3
## Why
The notification helper buffers unrelated server requests, so the session-scoped
file change approval test could overlook an unexpected second approval request.
## What changed
- Consume approval resolution and file change completion events directly and
verify their request, thread, turn, and item identities.
- Fail if the second patch requests approval after the first patch was accepted
for the session.
- Shut down the app server gracefully and assert that it exits successfully.
GitOrigin-RevId: 53a3f746940677043e097094862c28faf4db1a8d
## What changed
- Disable shell snapshot startup so the test stays focused on file change approval.
- Shut down the app server cleanly and assert that the turn makes exactly two Responses API requests.
GitOrigin-RevId: b19a67791d1bd371523e68ad6fae32d1dd426f2f
## What changed
- Enrich `thread/list` and `thread/search` results for loaded spawned threads with live status and `canAcceptDirectInput`.
- Report `true` for V1 agents that accept direct input and `false` for parent-owned V2 agents, while leaving the capability `null` when it is unavailable or inapplicable.
- Distinguish untracked threads from threads known to have shut down when resolving loaded status.
## Testing
- Cover list, search, ancestor-filtered list, and rejected V2 direct-input behavior.
GitOrigin-RevId: d5faf2fc379a236661ff9167391541473ce5c1eb
## What changed
- Add optional `plugin_id` and `script_path` fields to execution approval and guardian assessment events.
- Propagate validated plugin attribution through delegated approvals, guardian-reviewed command items, app-server notifications, thread history, and rollout traces.
- Preserve attribution on both started and completed command items, including declined commands.
## Testing
- Extend core, app-server, thread-history, and rollout-trace tests to cover plugin attribution propagation and serialization.
GitOrigin-RevId: 723684d010cab04142918d7a95e06ed95d008da1
## What changed
- Resolve shell and unified-exec commands against the trusted plugin roots loaded for each turn.
- Add optional `pluginId` and safe plugin-relative `scriptPath` fields to command execution items and legacy execution events, and propagate them through app-server notifications.
- Include the attribution in command execution analytics while rejecting absolute, unsafe, and unattributed script paths.
## Testing
- Cover attribution for cached curated and remote plugin scripts from command execution through core and app-server events.
- Verify analytics serialization and unsafe-path filtering.
GitOrigin-RevId: 02fac3a233284ccfc6642fa502a95f1881dba83d
## What changed
- Add typed helpers for initialized app-server instances, JSON-RPC requests,
responses, notifications, and thread startup.
- Add a composable `MockResponsesConfig` builder while preserving the existing
mock config writers.
- Migrate the app-server integration suite to the shared helpers, removing
repeated request ID management, deserialization, initialization, and config
assembly.
## Testing
- Add unit coverage for composing mock provider, feature, and extra config, and
for compatibility of the existing mock config writer.
GitOrigin-RevId: 62da177c1d6e8299400de64bd6766567bf1ba3d8
## Why
Streamed message deltas can be dropped when the transport is saturated, leaving
clients with a truncated final response.
## What changed
- Include the last non-empty final agent message in successful `turn/completed`
notifications and mark the items as a summary.
- Treat completed message content as authoritative in the TUI, repairing an
incomplete stream while avoiding duplicate messages when `item/completed` was
already received.
- Continue backfilling full turn items for persisted `codex exec` threads when a
completion contains only the summary view.
## Testing
Added coverage for completion summaries, dropped stream deltas, duplicate item
handling, and directive-only responses.
GitOrigin-RevId: ffe9d36d683d6b6690e4a468ff68aa9189fe6ab7
## Why
Permission profiles defined by `requirements.toml` can be selected as active,
but their network configuration was not included when resolving the network
proxy specification for that selection.
## What changed
Merge managed permission profiles from `requirements.toml` with configured
profiles before looking up the active profile's network proxy settings.
## Testing
- Verify config loading retains the proxy settings of an active managed
profile.
- Verify `turn/start` accepts a managed profile with network settings.
GitOrigin-RevId: 3374f82a8fb0ce8f338fa2cea77c28ea2eb89636
## What changed
- Change `ReviewDecision::Denied` to carry a rejection string and update the generated protocol schemas.
- Preserve specific rejection reasons through command, patch, network, MCP, delegated, and automatic approval flows so tool results can return them to the model.
- Distinguish invalid approval responses from user declines and truncate oversized rejection messages before adding them to model context.
## Testing
- Add coverage for denial serialization, invalid app-server approval responses, dropped automatic reviews, network rejection propagation, and rejection-message truncation.
GitOrigin-RevId: d48a55643aa03c7ecfa08a8e4b669913eec5464a
## What changed
Add `cacheWriteInputTokens` to the usage breakdown in the
`rawResponse/completed` JSON schema, defaulting it to zero. Update the
compaction and turn-start notification expectations for the expanded usage
breakdown.
GitOrigin-RevId: d9232b724d646b803c7f5a64c5daa311f77ad408
## Why
Clients that account for individual upstream Responses API calls need the exact
usage for each completion rather than accumulated or estimated thread usage.
## What changed
- Add the opt-in `rawResponse/completed` app-server notification with the
`threadId`, `turnId`, `responseId`, and upstream `usage` payload.
- Emit the transient event for normal turns and compaction requests when
`experimentalRawEvents` is enabled. The event is not persisted or replayed,
and `usage` is `null` when the upstream response omits it.
- Export the notification in the app-server schemas and document its behavior.
## Testing
- Cover exact token breakdowns for turn and compaction completions.
GitOrigin-RevId: 49040a060bf1784c1ff1dd62112efb4a778428c4
## Why
Multi-environment turns can run against different filesystems, so a single
thread-wide workspace-root list cannot accurately describe every selected
environment.
## What changed
- Add optional `runtimeWorkspaceRoots` to each app-server environment selection.
Omitted roots default to that environment's `cwd`, while an empty list selects
no roots.
- Carry environment-native roots through turn selection, model-visible context,
permission materialization, and tool sandboxing.
- Keep the top-level `runtimeWorkspaceRoots` field as a compatibility input when
constructing default environment selections; explicit selections use their
own roots.
## Testing
- Cover thread and turn API defaults, overrides, empty roots, and schema
round-tripping.
- Verify foreign roots remain model-visible and remote execution applies the
target environment's roots before sandbox selection.
GitOrigin-RevId: c6e7a62883c45c676c153055f46a55ee15a323a4
## What changed
- Stop the TUI and app server from inspecting existing sessions at startup to
set `personality = "pragmatic"` automatically.
- Remove the migration marker, helper APIs, and associated tests.
GitOrigin-RevId: 9e963bf113aff21651696bbc463f2749ac0f510a
## Why
We should be running as many integrations tests as possible against the
split cross-OS configuration.
## What
- migrate eligible thread starts and builders to auto env
- keep explicit custom/local-executor cases local with rationale
comments
- keep auto-env coverage where possible and add narrow `TODO(anp)` skips
for fixtures that are not target-native yet
## Why
Desktop Work threads and regular Codex threads can share the same
app-server connection. App-server analytics currently copy
`product_client_id` from connection metadata for every thread-scoped
event, so Work thread activity is attributed to the Desktop connection
instead of the thread's resolved originator. This prevents analytics
from distinguishing the two products on a shared connection.
## What changed
- Publish the resolved originator after a thread is materialized,
covering new, resumed, forked, and subagent threads.
- Store that originator in the analytics reducer's existing per-thread
state.
- Override only `app_server_client.product_client_id` for thread, turn,
tool, review, goal, guardian, and compaction events while preserving the
connection's client name, version, and transport metadata.
- Fall back to the connection-wide product client ID when a thread has
no originator override.
- Preserve persisted originators in thread initialization analytics for
resume and fork flows.
## Validation
- `just test -p codex-analytics
thread_originator_overrides_shared_connection_across_thread_events
subagent_events_keep_thread_originator_with_explicit_turn_connection`
- `just test -p codex-app-server
turn_start_tracks_thread_originator_in_analytics
thread_start_tracks_thread_initialized_analytics
thread_fork_tracks_thread_initialized_analytics
thread_resume_tracks_thread_initialized_analytics`
- `just test -p codex-core thread_manager`
## Why
Ultra should be one user-facing reasoning selection for work that
benefits from both maximum reasoning and proactive multi-agent
delegation. Without it, clients must coordinate maximum reasoning with
the experimental `multiAgentMode` setting, even though the inference
backend still expects its existing `max` effort value.
This change makes reasoning effort the source of truth: clients select
`ultra`, core derives proactive multi-agent behavior when the turn is
eligible for multi-agent V2, and inference requests continue to use the
backend-compatible `max` value.
## What changed
- Add `ultra` as a first-class reasoning effort and preserve
model-catalog ordering when exposing it to clients.
- Convert `ultra` to `max` at the inference request boundary, including
Responses HTTP/WebSocket requests, startup prewarm, compaction, and
memory summarization.
- Derive effective multi-agent mode per turn from effective reasoning
effort:
- eligible multi-agent V2 + `ultra` → `proactive`
- eligible multi-agent V2 + any other effort → `explicitRequestOnly`
- V1 or otherwise ineligible sessions → no multi-agent mode instruction
- Keep the derived effective mode in turn context history so successive
turns can emit a developer-message update only when the effective mode
changes.
- Remove selected multi-agent mode from core session configuration, turn
construction, thread settings, resume/fork restoration, and subagent
spawn plumbing. Subagents inherit reasoning effort and derive their own
effective mode.
- Retain the experimental app-server `multiAgentMode` fields for wire
compatibility while marking them deprecated. Request values are accepted
but ignored; compatibility response fields report `explicitRequestOnly`.
- Display Ultra in the TUI using the order supplied by `model/list`.
## Validation
- `just test -p codex-core ultra_reasoning_uses_max_for_requests`
- `just test -p codex-tui model_reasoning_selection_popup`
## Why
Topology-neutral app-server integration tests should exercise automatic
environment selection so the same setup covers local and remote
executors.
## What
Migrate eligible tests to `TestAppServer::new_with_auto_env()` and
`send_thread_start_request_with_auto_env()`. Leave explicit-topology
tests unchanged, and skip the request-permissions case on Windows with a
TODO for cross-platform tool routing.
## Validation
- `just test -p codex-app-server`
- `bazel test //codex-rs/app-server:app-server-all-wine-exec-test
--test_output=errors`
Stacked on #29788.
## Summary
Multi-agent v2 tools now use the fixed `collaboration` namespace when
namespace tools are available. This keeps the model-visible hint and the
actual tool surface aligned around `functions.collaboration.*`, without
exposing an unshipped namespace knob to users.
The PR also removes the old `features.multi_agent_v2.tool_namespace`
config/schema surface, updates the MAv2 test fixtures for namespaced
calls, and fixes stale `TurnContext.features` references that were
breaking `codex-core` builds.
## Changes
- Expose MAv2 tools under `collaboration` instead of relying on a
configurable namespace.
- Remove `tool_namespace` from MAv2 TOML config, resolved config,
validation, schema, and tests.
- Update tool-planning and integration fixtures to assert or emit
namespaced MAv2 tool calls.
- Read feature state through `TurnContext.config.features` in the
multi-agent mode context paths.
## Testing
- `just write-config-schema`
- `just test -p codex-features`
## Stack
Stacked on #29417. Review and land that PR first.
## Summary
- reject HTTP(S) image URLs in the handlers for `turn/start` and
`turn/steer`
- validate `thread/inject_items` after its existing
JSON-to-`ResponseItem` conversion, so each item is deserialized once
- turn invalid dynamic-tool image responses into the existing
unsuccessful text fallback; the model receives the validation message as
the function output
- leave `thread/resume.history` compatible with legacy history; #29417
replaces remote images before model input
- continue accepting inline data URLs and `localImage` inputs
- keep this policy in app-server; this PR does not add a shared protocol
API or change core image preparation
## Test plan
- `just test -p codex-app-server -E
'test(/request_handlers_reject_remote_image_urls|dynamic_tool_remote_image_response_becomes_model_visible_error|dynamic_tool_call_round_trip_sends_content_items_to_model|turn_start_tracks_turn_event_analytics|standalone_image_edit_uses_recent_pathless_image/)'`
(5 passed)
- `just fix -p codex-app-server`
- `just fmt`
## Why
Multi-agent delegation policy was split across `multiAgentMode`,
`features.multi_agent_mode`, and `usage_hint_enabled`. These controls
could disagree: a requested mode could be downgraded by the feature
flag, and disabling usage hints also disabled mode instructions.
Some clients also need multi-agent tools without adding
delegation-policy text to model context. The previous two-mode API could
not express that directly.
## What changed
`multiAgentMode` is now the only live delegation-policy control:
| Mode | Behavior |
| --- | --- |
| `none` | Keep multi-agent tools available without adding mode
instructions. |
| `explicitRequestOnly` | Only delegate after an explicit user request.
|
| `proactive` | Delegate when parallel work materially improves speed or
quality. |
- new threads default to `explicitRequestOnly`; omitting the mode on
later turns keeps the current value
- thread start, resume, fork, and settings responses always report the
concrete current mode instead of `null`
- mode selection remains sticky across turns and resume
- usage-hint text no longer controls whether mode instructions apply
- `features.multi_agent_mode` and `usage_hint_enabled` remain accepted
as ignored compatibility settings so existing configs continue to load
- app-server documentation and generated schemas describe the three-mode
API
## Tests
- `just test -p codex-core multi_agent_mode`
- `just test -p codex-core multi_agent_v2_config_from_feature_table`
- `just test -p codex-core spawn_agent_description`
- `just test -p codex-features`
- `just test -p codex-app-server-protocol`
- `just test -p codex-app-server multi_agent_mode`
## Why
Once multi-agent mode can be selected per turn, clients also need to
choose the initial selection when creating a thread and observe that
selection through lifecycle and settings APIs.
The selected value is intentionally distinct from the effective
model-visible value: no client selection is represented as `null`, even
though an eligible multi-agent v2 turn derives `explicitRequestOnly` as
its effective default.
## What changed
- Add the optional experimental `thread/start.multiAgentMode` parameter
and pass it through thread creation.
- Preserve an omitted initial value as an unset selection rather than
eagerly storing `explicitRequestOnly`.
- Apply an explicit `thread/start` selection to the first turn through
the session configuration established at thread creation.
- Restore the latest persisted effective mode as the selected baseline
on cold resume when rollout history contains one.
- Inherit the optional selected mode from a loaded parent when creating
related runtime threads.
- Return the current selected `multiAgentMode` from `thread/start`,
`thread/resume`, `thread/fork`, and thread settings, using `null` when
no mode is selected.
- Keep lifecycle reporting independent from model capability and feature
eligibility; core turn construction remains responsible for calculating
and persisting the effective mode.
## Not covered
- Clearing an existing loaded-session selection back to unset through
`turn/start`; omitted or `null` currently retains the session's
selection.
- A TUI control, slash command, or `config.toml` preference.
## Verification
- `CARGO_INCREMENTAL=0 just test -p codex-app-server-protocol`
- `CARGO_INCREMENTAL=0 just test -p codex-app-server multi_agent_mode`
The focused app-server coverage verifies explicit `thread/start`
initialization, first-turn prompting, nullable reporting for an omitted
selection, and retention of selections that are not currently
runtime-eligible.
## Stack
Stacked on #28685. This PR contains only the thread initialization and
lifecycle/settings API layer.
## Why
Multi-agent v2 currently carries an explicit-request-only delegation
rule in its static usage hint. That provides a safe default, but it
prevents clients from selecting proactive delegation per turn without
changing static guidance or rewriting prior model context.
This change makes delegation mode a session selection that can be
updated through `turn/start`, while deriving the effective model-visible
mode separately for each turn. Eligible multi-agent v2 turns remain
explicit-request-only unless proactive mode is both selected and
enabled.
## What changed
- Add the experimental `turn/start.multiAgentMode` parameter with
`explicitRequestOnly` and `proactive` values. Omission retains the
loaded session's current optional selection.
- Add the default-off `features.multi_agent_mode` feature gate. Eligible
multi-agent v2 turns use the selected mode when enabled; an unset
selection or disabled gate resolves to `explicitRequestOnly`.
- Treat mode prompting as inapplicable for multi-agent v1 and other
unsupported session configurations, producing no multi-agent mode
developer message rather than rejecting the turn.
- Move the explicit-request-only rule out of the static v2 usage hint
and into a bounded, tagged developer context fragment.
- Emit the effective mode in initial context and only when that
effective mode changes on later turns.
- Persist the effective mode in `TurnContextItem` as the durable
baseline for resume and context-update comparisons.
Historical rollout items are not rewritten. Later mode developer
messages establish the current rule incrementally.
## Not covered
- Initial selection through `thread/start` and selected-mode reporting
from thread lifecycle/settings APIs; those are isolated in the stacked
#28792.
- A TUI control or slash command for selecting the mode.
- Persisting a preferred mode to `config.toml`; selection remains
session/turn scoped.
- Changes to multi-agent concurrency limits, tool availability, or model
catalog capability declarations.
- Rewriting historical rollout prompt items. Cold resume restores the
latest persisted effective mode when available while leaving historical
developer messages intact.
## Verification
- `CARGO_INCREMENTAL=0 just test -p codex-core multi_agent_mode`
- Focused app-server coverage verifies that `turn/start.multiAgentMode`
produces proactive developer instructions for an eligible v2 turn.
## Stack
Followed by #28792, which adds `thread/start` initialization and
lifecycle/settings observability.
## Why
App-server must report command events containing foreign-platform paths
without changing existing client or rollout path-string formats.
## What changed
- retain `PathUri` through exec command begin/end events
- convert cwd values to `LegacyAppPathString` at the app-server
compatibility boundary
- drop command actions with foreign paths and log them
- serialize rollout-trace cwd values using their inferred native path
representation
- restore Wine coverage for retained Windows cwd values and successful
completion
## Why
Command approval cache keys included the command and working directory,
but not the execution environment. An approval for `/workspace` locally
could therefore be reused for the same command and path on an executor.
## What changed
- Include the selected environment ID in shell and unified-exec approval
cache keys.
- Carry that ID through the normal command approval request so clients
can show which environment is being approved.
- Expose the environment through app-server as a required nullable
`environmentId` and show it in the inline TUI approval prompt.
- Keep older recorded approval events compatible when the environment is
absent.
For example, `echo ok` in local `/workspace` and `echo ok` in executor
`/workspace` now produce different approval keys and separate prompts.
## Scope
This PR does not change network approvals, Guardian review actions, MCP
elicitation, full-screen TUI rendering, or environment-ID validation.
Remote `shell_command` execution itself remains in #28722; this PR only
makes its approval key environment-aware.
## Why
app-server may run on a different OS from the selected exec-server
environment. Parsing that environment’s cwd with the Codex host’s path
rules prevents thread startup.
## What
Carry environment cwd values as `LegacyAppPathString` at the app-server
boundary and `PathUri` internally. Existing tool-call schemas and
relative-path behavior stay host-native; remaining local-only consumers
convert explicitly and leave follow-up TODOs.
The Wine integration test verifies app-server can start a thread and
complete an ordinary turn with a Windows environment cwd from Linux.
## Validation
- `bazel test //codex-rs/core/tests/remote_env_windows:smoke-test
--test_output=errors`
- focused app-server environment-selection and protocol schema tests
- scoped Clippy for `codex-core` and `codex-app-server-protocol`
The workspace denies `clippy::expect_used` in production. Although
`clippy.toml` allows `expect` in tests, Bazel Clippy compiles
integration-test helper code in a way that does not receive that
exemption, which encouraged verbose `unwrap_or_else(... panic!(...))`
and equivalent `match`/`let else` forms.
This allows `clippy::expect_used` once at each integration-test crate
root (including aggregated suites and test-support libraries), then
replaces manual panic-based Result and Option unwraps with
`expect`/`expect_err`. Standalone `tests/*.rs` files remain their own
crate roots. Intentional assertion and unexpected-variant panics remain
unchanged, and the production `expect_used = "deny"` lint remains in
place.
The cleanup is mechanical and net-negative in line count.
rka-oai