## 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
## Why
Thread settings can change while a turn is running, and delegated review or
compaction steps can select a different model. Each request needs a consistent
set of settings resolved against the model that will execute it.
## What changed
- Capture immutable resolved settings for each model step, including model
metadata, reasoning options, service tier, approvals, and personality.
- Keep in-flight steps on their captured settings while applying thread updates
to subsequent work.
- Resolve inherited reasoning summaries and filter service tiers against the
selected model and feature configuration for review and compaction steps.
## Testing
Added coverage for settings updates during paused turns, model changes,
previous-model compaction, review-model defaults, and service-tier filtering.
GitOrigin-RevId: fca4b3b305379f1bf26a5cac75ee0dd1747ac1f6
## Why
History estimation and executed-tool-call limits only need the size of serialized JSON, not the serialized output itself.
## What changed
- Add a shared `serialized_json_bytes` helper that streams JSON into a byte counter.
- Use it for response-item size estimates and executed-tool-call argument limits.
- Preserve serialization errors so callers can apply their existing fallback behavior.
## Testing
- Cover response-item sizing with escaped characters, newlines, and multibyte text.
GitOrigin-RevId: a4417996df96df5c51cae62830adc496912f69c7
## What changed
- Add a dedicated contextual fragment for developer instructions that emits the
`generic.developer_instructions` content kind.
- Use the fragment when adding child-specific developer instructions to a
full-history subagent fork, preserving their classification and ensuring they
reach the child exactly once without appearing in the parent request.
## Testing
- Extend full-history subagent coverage to verify the child-only instructions'
annotation, placement, and count.
GitOrigin-RevId: 82589d311535225fed76d500a19458fda72f40f2
## Why
Remote compaction's retained-message budget counted text but not images, so
image-heavy history could retain more context than the budget represented.
## What changed
- Add the opt-in `compaction_image_budget` feature to charge retained images
using the existing image size estimate.
- Keep images and their adjacent labels atomic when truncating a boundary
message, while preserving existing text, audio, metadata, and
client-authored developer-message behavior.
- Stop backfilling older messages when an image at the truncation boundary
does not fit.
## Testing
- Add unit coverage for image boundaries, annotations, audio, text-only
messages, and client-authored developer messages.
- Add an integration test covering repeated remote compaction with the feature
enabled, disabled, and left at its default.
GitOrigin-RevId: 88868bbd09d2858939dbae3f8402e1f497b4e3c6
## What changed
- Render omitted image and audio inputs as contextual fragments tagged with
`images.unsupported` and `audio.unsupported` content kinds.
- Normalize message media through annotated content so metadata for surrounding
content remains intact when switching to a model without media support.
## Testing
- Extend history and model-switching tests to verify content-kind annotations
before and after unsupported media is replaced.
GitOrigin-RevId: 4ee6577f8b78bd5a850ee01ea9d4590c20272850
## What changed
- Filter rolled-back model-switch instructions through annotated content so the
surviving developer fragments retain their matching content-kind metadata.
- Add regression coverage for annotation preservation and request-level metadata
alignment after rolling back a first-turn model change.
GitOrigin-RevId: 42a3c0cf4c5727bc6fe40990254467f40f4686f9
## What changed
- Carry each contextual fragment's `ContentItemKind` through initial context assembly and world-state updates.
- Attach the classifications to merged response messages through `content_item_kinds`, preserving their order alongside the message content.
- Convert extension prompt fragments into annotated developer fragments and classify built-in developer and guardian instructions.
## Testing
- Add an integration test covering roles and content annotations in the first request.
- Update world-state and persisted-history tests to account for annotation metadata.
GitOrigin-RevId: 71c48dad5b17bffd47ba03263e3eb6d5e74fbf4b
## What changed
- Retain bounded evidence from completed synchronous Guardian allow and deny reviews and supply it to subsequent Guardian v2 async classifier samples as trusted developer context.
- Keep review evidence isolated from the conversation transcript, escape and truncate its fields, and ignore failed or incomplete reviews.
- Invalidate retained evidence after conversation history rewrites or new user messages, including authorization changes in a worker's root thread.
## Testing
- Cover approved, denied, malformed, and forged review inputs, plus root rollback and authorization-change scenarios.
GitOrigin-RevId: 27817e1fde9a136de727048c4220d148fcf72f42
## Why
External tool events may need to enter thread history without a preceding function call and therefore do not have a `call_id`.
## What changed
- Allow `function_call_output` items to omit `call_id` and carry optional `name` and `namespace` fields.
- Preserve named standalone outputs during history normalization and agent forks while retaining existing pairing behavior for outputs with a `call_id`.
- Accept, persist, and forward these outputs through `thread/inject_items`, and update the app-server schemas and documentation.
## Testing
- Cover paired and standalone JSON round trips, history normalization, agent forks, and injected thread history.
GitOrigin-RevId: a3258163a7dc93777c7c3023116fe204819bdbb0
## What changed
- Add `additional_developer_instructions` to managed requirements and expose it through `configRequirements/read` as `additionalDeveloperInstructions`, independently of ordinary developer instructions.
- Include the managed instructions in model context, emit explicit replacement or removal messages when requirements change, and preserve the current value across compaction, resume, and agent forks without duplication.
- Reject managed instructions whose rendered context exceeds 10,000 estimated tokens.
## Testing
- Cover requirements layering and API serialization, context updates and removal, size validation, repeated model requests, compaction and resume, rollout migration, and agent forks.
GitOrigin-RevId: bc0b70fb7988944c2f68176dff55f5ed61eb46c8
## What changed
- Add the optional `active_permission_profile` field to `TurnContextItem` to record the built-in or named profile that produced the effective permission profile.
- Populate the field when serializing a turn context while preserving compatibility with records where it is absent.
## Testing
- Add coverage verifying that turn-context serialization stores the active permission profile.
GitOrigin-RevId: d69142ab1b26595ab406235f89818ef41370e963
## What changed
- Add model-catalog messages for root and subagent roles, explicit delegation, and delegation hints.
- Resolve role instructions in config, catalog, then bundled-default order, while preserving empty values as an explicit way to suppress fallback text.
- Refresh catalog-provided role and mode instructions when the model changes, and give full-history forks the selected child model's subagent role without retaining the parent's role guidance.
- Keep existing config overrides and reasoning-effort behavior, including proactive delegation for ultra reasoning effort.
## Testing
- Cover message deserialization and preservation through model overrides.
- Cover precedence, empty overrides, model switches, resumed sessions, and full-history subagent forks.
GitOrigin-RevId: 4625cf7c6a5490176adddfaa0fb99100707daea9
## What changed
- Add a shared, read-only `ConversationHistorySnapshot` capability to the extension API.
- Include the snapshot in `ToolStartInput`, preserving conversation order while excluding contextual user messages.
- Avoid acquiring a history snapshot when no tool lifecycle contributors are registered.
## Testing
- Verify snapshots share existing response items, remain stable as history changes, and filter contextual user messages.
- Verify tool-start callbacks receive the history available for successive tool calls.
GitOrigin-RevId: 822cae33781dd876ea628f104be08d8a449a4900
## What changed
- Collect borrowed call IDs in a single pass instead of cloning IDs across
separate sets.
- Record orphan positions and compact the history only when orphan outputs are
present, while preserving the existing matching and error behavior.
GitOrigin-RevId: de399ba92ff451cb12fc69218d60d3ac29fccb3d
## Why
World-state snapshots and merge patches are keyed collections of sections. Allowing
their persisted `state` field to contain any JSON value required replay code to
handle shapes that cannot represent world state.
## What changed
- Type `WorldStateItem.state` and snapshot patches as JSON object maps.
- Reconstruct full snapshots directly from those maps and apply patches without
fallible arbitrary-value conversions.
- Regenerate the app-server protocol schema for the object-only representation.
GitOrigin-RevId: 3d7662b74f3dd1f3ccc5fdd0200074c13a73cbe5
## What changed
- Wrap response items with optional harness-owned metadata while keeping the persisted response payload shape backward compatible.
- Store compacted-history metadata in an aligned sidecar and reject malformed sidecars.
- Carry metadata through history normalization, compaction, resume, fork, truncation, migration, and rollout recording without sending it to model providers.
## Testing
- Cover legacy rollout compatibility, metadata serialization and validation, compaction retention, and resume/fork reconstruction.
GitOrigin-RevId: 17a6127c9048ff984cb4df4d97c0751a38c29f5f
## What changed
- Add `ResponseItemEnvelope` as the history-owned wrapper for a `ResponseItem`.
- Store envelopes in `ContextManager` while keeping raw-item iteration and consuming APIs for existing callers.
- Preserve envelopes when compaction and history normalization rewrite retained items, and wrap newly synthesized items.
## Testing
- Cover envelope access, mutation, and conversion back to raw response items.
- Cover annotated history replacement and annotated user-message collection for compaction.
GitOrigin-RevId: 3fa2e7bdd981b08cc7aec410c80deccaecdabab4
## Why
Persisted base instructions need to retain whether they were explicitly customized or generated from a model template. Without that distinction, forks and config-lock replays can treat model-generated instructions as custom and keep the wrong template after a model or personality change.
## What changed
- Record custom or model provenance with base instructions in rollouts and config locks.
- Preserve custom instructions across model changes, while allowing model-generated instructions to follow the selected model and personality.
- Keep legacy rollouts without provenance compatible and propagate provenance through forks and spawned agents.
## Testing
- Cover provenance serialization and legacy rollout decoding.
- Cover role personality changes, forked model changes, config-lock replay, and multi-agent configuration.
GitOrigin-RevId: 801c26559835f558027ce5112700c0cd31fcb21b
## Why
A model switch on the first turn has no prior turn settings to compare, and rolling that turn back could leave its model instructions in history.
## What changed
- Track the model that supplied the session's base instructions so first-turn switches inject the target model's instructions, including the selected personality.
- Preserve inherited custom base instructions when starting from an empty fork.
- Remove first-turn model-switch developer content during rollback so retries and cold resumes do not retain or duplicate stale instructions.
## Testing
Add integration coverage for first-turn switches, personality changes, empty-prefix forks, rollback retries, and cold resume.
GitOrigin-RevId: 9df532e9e337521ad3b315b77f8c98e039fb384e
## What changed
- Add `codex-utils-audio` as a workspace crate for canonicalizing audio inputs
and estimating their token usage.
- Update `codex-core` to consume the new crate while preserving the existing
audio preparation tests.
GitOrigin-RevId: d719ecc08363ef52778aa37f3df0ca14f7778324
## What changed
- Track approved command prefixes separately from the stable permissions
instructions in world-state snapshots.
- Emit only newly approved prefixes after an exec-policy amendment instead of
appending the full permissions block again.
- Preserve prefix updates when full permissions instructions are disabled and
remain compatible with legacy world-state snapshots.
## Testing
- Cover incremental prefix additions, removals, legacy snapshots, history
rollback, and approval flows with permissions instructions enabled or disabled.
GitOrigin-RevId: e6f68c6a91be82750e70e28456f2b7c58607fbd8
## What changed
- Retain bounded, non-completion agent messages in remote v2 compaction history so delegated tasks remain available on follow-up turns.
- Account for encrypted agent-message content when estimating token usage and place restored initial context before the latest real user or agent message.
- Exclude child completion messages from retained follow-up history and strip inherited parent agent messages when forking a child.
## Testing
- Extend compaction, history-estimation, and agent-fork tests to cover encrypted delegated tasks, child completions, context ordering, and fork sanitization.
GitOrigin-RevId: ba4392e9cfdf4ecbcdc9c7d8581d58a8d2d78260
## What changed
- Preserve `encrypted_function_args` on function calls so an empty list can mark plaintext collaboration arguments across request replay.
- Deliver `spawn_agent`, `send_message`, and `followup_task` payloads as structured plaintext agent messages when that marker is present; retain encrypted delivery otherwise.
- Redact plaintext collaboration arguments from tool and communication logs, and omit the metadata when sending requests to non-OpenAI providers.
## Testing
- Cover serialization of empty encrypted-argument metadata and plaintext versus encrypted subagent message delivery.
- Verify plaintext tool arguments are redacted and provider-specific metadata is removed from non-OpenAI requests.
GitOrigin-RevId: 64db98ff0b61a3af2f04ed609292363f2e2362a8
## What changed
- Add protocol types and `ResponseItem` helpers for attaching and clearing
locally recorded tool-call names and arguments.
- Bound serialized metadata across a prompt, replacing oversized arguments and
omitted calls with trusted truncation details.
- Prevent deserialized response items or model-provided arguments from forging
locally generated tool-call and truncation metadata.
## Testing
- Cover prompt-wide size limits, omission accounting, idempotent bounding, and
forged truncation markers.
GitOrigin-RevId: 960a223437ce81fe6b4cbb5fc7a9774408b2755b
## What changed
- Add model and personality sections to the persisted world-state snapshot.
- Generate model-switch and personality instructions through world-state diffs, including when prior state must be inferred during replay.
- Keep those instruction fragments in standalone developer messages instead of merging them with adjacent context updates.
## Testing
- Cover initial, unchanged, and changed model and personality states.
- Verify that model changes are recorded in rollout world-state items.
GitOrigin-RevId: 497e29cf38cac08e992e546df900f6f8b01120f9
## Why
Multi-agent mode instructions are durable model context and need to survive
history changes without re-emitting unrelated setup hints.
## What changed
- Add a `multi_agent_mode` world-state section that diffs, retains, and restores
the effective mode instructions.
- Persist mode changes in world-state snapshots while keeping the legacy
`TurnContextItem.multi_agent_mode` field for reading older rollouts.
- Keep initial mode instructions after the root-agent usage hint so the active
mode takes precedence, and bound custom mode text before snapshotting it.
## Testing
- Add snapshot coverage for mode transitions, retained history, and custom-text
truncation.
- Verify live mode changes preserve instruction ordering, avoid duplicating the
usage hint, and record both modes in world state.
GitOrigin-RevId: 96b9964d6e5299b07a011c559b68e3d948a49226
## Why
Remote compaction can process large histories. Repeatedly estimating and replacing the full history, and cloning it when tracing is disabled, adds avoidable CPU and memory overhead.
## What changed
- Estimate each history item's token count once, update the total as trailing tool outputs are rewritten, and replace history only after all rewrites are selected.
- Preserve unclamped token totals while calculating removed tokens so saturated estimates do not hide overflow.
- Snapshot compaction input history only when rollout tracing is enabled.
- Reuse the v2 request input instead of cloning it before adding the compaction trigger.
## Testing
- Cover enabled and disabled compaction trace contexts through `is_enabled()` assertions.
GitOrigin-RevId: 8de9c9704ba29532fba05430eb204bbae2e8bf83
## What changed
- Assert truncated audio history through `ContextManager::raw_items()`.
- Initialize `additional_context_limit` in the quoted Windows hook command test.
GitOrigin-RevId: 43c19804e558b7a11fc17590506ec6ec7f3a9897
## Why
Cloning a `ContextManager` deep-copies every `ResponseItem`, even when callers only need a read-only history snapshot.
## What changed
- Store history items in an `Arc<Vec<ResponseItem>>` so cloned snapshots share their items until one is mutated.
- Reuse an owned vector when consuming an unshared snapshot and clone it only when other snapshots still reference it.
- Estimate session token counts from a snapshot after releasing the session-state lock.
## Testing
Added a regression test that verifies cloned histories share their backing items before mutation and diverge without affecting each other afterward.
GitOrigin-RevId: 24605888209ae9ff78cadb04d9c36463f7e2dbe0
## Why
Audio attachments could be dropped from tool outputs and reconstructed thread history, while inline base64 payload size could overstate their model context cost.
## What changed
- Preserve remote and local audio attachments in legacy user-message events and thread history.
- Keep audio from function and custom tool outputs when the model supports it and the output fits the truncation budget; otherwise replace it with an omission marker.
- Estimate inline audio cost from its duration, with a serialized-size fallback for malformed or unsupported data URLs, so compaction and truncation use model-visible cost instead of raw base64 size.
- Replace audio in messages and tool outputs with an explanatory placeholder for models without audio input support.
## Testing
Add coverage for history round trips, dynamic tool responses, modality filtering, duration-based context estimates, output-budget truncation, and remote compaction.
GitOrigin-RevId: 5ed4628850a668f8383b7cd73db71b144cc02cd1
## What changed
Remove the fallback that replaced image content in the latest tool output with
`Invalid image` and retried the model request. Invalid-image responses now use
the existing bad-request error path without modifying conversation history.
GitOrigin-RevId: f4ea782f16c5451feb261694caa73b77f24c3e4e
## What changed
- Tell the model that generated images are already displayed to the user and should not be repeated as Markdown images or file links.
- Keep generated-image artifact paths and output hints owned by the image generation extension.
- Centralize the availability check for the image generation tool across feature, provider, namespace-tool, model modality, and authentication requirements.
## Testing
- Verify artifact paths sanitize session and call identifiers.
- Verify the model-facing output hint reports that the generated image is already displayed.
GitOrigin-RevId: 6c865b6a96d6a71bb2c33246d1518a00e7c8b840
## What changed
- Add `audio` to the model input modalities exposed by the protocol and generated app-server schemas.
- Preserve audio in prompts for models that advertise audio input, and replace historical audio with an omission marker for models that do not.
## Testing
- Cover prompt normalization with and without audio support.
- Extend the model-switching integration test to verify that switching from a multimodal model to a text-only model strips prior image and audio content.
GitOrigin-RevId: c18e47ad602720216303ff9abb5bca4d508391ee
## What changed
- Model permission instructions as a world-state section keyed by a stable hash of their rendered developer message.
- Re-emit permission context when its model-visible contents change or the retained fragment is missing, while avoiding duplicates when matching instructions already exist in history, including bundled developer messages.
- Normalize CRLF line endings when hashing world-state fragments so equivalent content produces the same snapshot.
## Testing
- Add snapshot coverage for unchanged, changed, absent, and unknown permission state.
- Cover bundled retained permissions and restored world-state baselines during rollout reconstruction.
GitOrigin-RevId: 7d8d212460c1690ca617859f66dcd825987f1e23
## What changed
- Represent whether realtime is active as a persisted world-state section.
- Emit start and end instructions from world-state transitions, including when
reconstructing context after resume.
- Retain existing realtime start fragments and avoid emitting another start when
custom instructions change while realtime remains active.
## Testing
- Add snapshot coverage for absent, unknown, active, and inactive realtime state
transitions.
- Cover realtime start and end updates plus resuming with changed custom start
instructions.
GitOrigin-RevId: ec670b8132b0f1c9317738bfdeb272069927d91d
## What changed
- Model collaboration mode as a world-state section whose persisted snapshot is
the active mode.
- Emit collaboration instructions when the mode changes, while ignoring
instruction text changes within the same mode.
- Restore persisted collaboration instructions when they are missing from
retained history, including after a fork.
## Testing
- Add snapshot coverage for initial, unchanged, changed, and unknown mode state.
- Cover retained-history restoration and same-mode instruction changes.
GitOrigin-RevId: ffd1683499f09acef6516b0bfcb5bcb4d3f28df4
## What changed
- Treat an empty custom `multi_agent_mode_hint_text` as having no instructions to emit.
- Avoid adding an empty multi-agent mode message both on the initial turn and when the configured hint changes after resuming a session.
## Testing
- Update the empty-hint integration test to assert that no mode message is sent.
- Add resume coverage that verifies changing a custom hint to an empty string emits no update.
GitOrigin-RevId: 8033292115936fac2cf22f85141278595804ee61
## Why
An execution environment marked `starting` is not yet usable, but unrelated work can continue while it becomes ready.
## What changed
- Add developer guidance that explains execution-environment isolation and the resources that become available after startup.
- Tell the model to wait only when the current task needs the starting environment.
- Retain the guidance across world-state updates without duplicating it in request history.
## Testing
- Cover world-state transitions, history retention, rollback handling, and deferred-environment request deduplication.
GitOrigin-RevId: f12f9204d4cbddce50a70eb0998beb6b66cd2fa9
## What changed
- Add per-sandbox-mode permission messages to `ModelMessages` and preserve them when applying model configuration overrides.
- Use the selected catalog message in permission instructions, substituting `{{ network_access }}` with the active network policy. Fall back to the existing sandbox text when no override is provided, and allow an empty override to omit only the sandbox section.
- Apply catalog permission messages when a session starts and when its model changes.
## Testing
- Cover catalog deserialization, mode selection, network substitution, fallback and empty-message behavior, remote model catalogs, and model changes.
GitOrigin-RevId: cd5ed3aee3155dca0e7b2358c0f09bae73236856
## Why
`TurnContext` stored model and reasoning settings both as resolved turn fields and inside `CollaborationMode`, requiring the copies to stay synchronized when the model changed.
## What changed
- Store the mode and collaboration-mode developer instructions directly on `TurnContext`.
- Reconstruct `CollaborationMode` from those values plus the turn's current model and reasoning effort when callers need it.
- Read the mode directly for plan-mode checks, lifecycle events, and telemetry.
GitOrigin-RevId: b8fccafdd5d5cbccc84bc70d542588087ddf0093
## What changed
- Add a `ResponseItemId` type that generates item-specific prefixes with UUIDv7 suffixes and use it across response items.
- Keep deserialization permissive for legacy histories, but omit empty or unprefixed item IDs from HTTP and WebSocket requests.
- Export the new type in the generated TypeScript protocol schema.
## Testing
- Cover prefixed ID generation, legacy deserialization, prefix recognition, and outbound request filtering.
GitOrigin-RevId: 0209fe430c826d0ae88bc4648652c4ebf390c4a4
## Why
A thread resumed without an explicit reviewer could pick up the reviewer
from the current config instead of preserving the reviewer already in
use by the thread. After an app restart, this meant a thread running
with auto review could silently switch back to user review, and the next
turn could continue under the wrong reviewer.
## What changed
Persist the effective reviewer with each turn and restore the latest
persisted value when the thread resumes. If the resume request
explicitly provides a reviewer, that value still takes precedence.
## Test plan
- Added a regression test that starts a thread with auto review, records
a turn, restarts with user review in config, resumes without an
override, and verifies that auto review is preserved.
- `just test -p codex-protocol`
- `just test -p codex-state`
- `just test -p codex-rollout`
- `just test -p codex-app-server
thread_resume_preserves_persisted_approvals_reviewer`
- Clippy for the affected crates
## Why
Approval guidance is currently assembled entirely by the client. Model
Messages V2 needs model catalogs to provide model-specific `on_request`
guidance for both user-reviewed and auto-reviewed approval flows while
retaining the existing generated prompt as a compatibility fallback.
## What changed
- add nullable `on_request` and `on_request_auto_review` catalog
messages
- select the message matching the active approvals reviewer for
`on_request` policies
- replace the complete legacy approval section when the selected catalog
value exists, including support for an empty string that suppresses the
section
- retain legacy rendering when the object or selected key is absent, and
for non-`on_request` policies
- preserve approval messages when base-instruction or personality
overrides clear instruction templates
- refresh permissions instructions when the active model changes
- pass catalog messages through initial and incremental permissions
construction
## Relationship to reviewer persistence
PR #31309 independently persists the approvals reviewer in turn context
and refreshes permissions when that reviewer changes. This PR is based
directly on `main` and does not duplicate that rollout migration; once
both land, reviewer switches will also select and append the new catalog
variant.
## Testing
- `just test -p codex-protocol`
- `just test -p codex-prompts`
- `just test -p codex-models-manager`
- `just test -p codex-core permissions_messages`
## Why
Generic Apps guidance is emitted only while building static initial
context. If the Apps MCP is unavailable then and recovers later in the
same turn, its tools can become usable without the model receiving the
guidance for using them.
## What
- move generic Apps guidance into a persisted `apps_instructions` World
State section
- derive availability from the request's MCP runtime while preserving
the existing feature, auth, orchestrator-MCP, and config gates
- recognize legacy and retained Apps fragments so resume and compaction
do not duplicate guidance
- register Apps guidance as rollback-trimmable context
- remove the old static injection path and its now-unused connector
helper
- keep tool construction on its existing independent `list_all_tools()`
read rather than adding a request-wide cache; a reconnect between the
two reads can differ for one request and reconciles on the next request
Apps and plugin guidance now render after the remaining static
host-skills block, with Apps before Plugins.
## Testing
- `just fmt`
- `just test -p codex-core apps_instructions`
- `just test -p codex-core
apps_guidance_appears_after_background_recovery_within_a_turn`
- `just test -p codex-core
drop_last_n_user_turns_trims_context_updates_above_rolled_back_turn`
## Why
Generic plugin guidance is currently emitted only with initial context
from host plugin state. An executor-selected plugin can become available
later in the same turn, making its skills and tools usable without ever
telling the model how plugin capabilities should be used.
## What
- project every ready selected plugin package, including skill-only
plugins
- carry plugin availability with the exact MCP runtime projection while
preserving MCP manager reuse when servers and connectors are unchanged
- move generic plugin guidance from the static initial-context path into
persisted World State
- recognize legacy and retained plugin fragments so resume and
compaction do not duplicate guidance
## Testing
- `just test -p codex-mcp-extension`
- `just test -p codex-core plugins_instructions`
- `just test -p codex-core
plugin_availability_change_reuses_the_mcp_manager`
- `just test -p codex-app-server --test all selected_capabilit`
## Why
Multi-agent V2 normally derives its mode instructions from reasoning
effort: Ultra enables proactive delegation, while other efforts require
an explicit request. Some deployments need to provide one configured
delegation policy that replaces those built-ins and remains stable when
reasoning effort changes.
## What changed
- Add `features.multi_agent_v2.multi_agent_mode_hint_text` alongside the
existing root and subagent hint settings.
- Treat any configured value, including an empty string, as
`MultiAgentMode::Custom(hint_text)`, so the configured text replaces the
built-in explicit-only and proactive policies.
- Persist the full custom variant and hint text in the turn-context
snapshot, so the durable comparison baseline detects both
reasoning-effort changes and configured policy-text changes.
- Preserve the existing explicit-only/proactive behavior when the
setting is absent.
- Replace the ambiguous `MultiAgentMode::None` variant with
`MultiAgentMode::Custom(String)` in new rollouts and API schemas. A
compatibility wire type maps legacy serialized `none` values to
`Custom("")` when resuming existing rollouts.
- Regenerate the config and app-server schemas.
## Configuration examples
The distinction is whether `multi_agent_mode_hint_text` is present. An
empty string is still a configured value and intentionally suppresses
the built-in mode instructions.
### Unset: preserve existing effort-derived behavior
```toml
[features.multi_agent_v2]
enabled = true
# multi_agent_mode_hint_text is omitted
```
- Ultra reasoning uses the built-in proactive delegation instructions.
- Other reasoning efforts use the built-in explicit-request-only
instructions.
### Empty: suppress all mode hint text
```toml
[features.multi_agent_v2]
enabled = true
multi_agent_mode_hint_text = ""
```
This selects effective mode `custom` at every reasoning effort and
injects an empty mode body, suppressing both built-in policies.
### Set: always use the configured text
```toml
[features.multi_agent_v2]
enabled = true
multi_agent_mode_hint_text = "Delegate to subagents when it will materially improve the result."
```
This selects effective mode `custom` at every reasoning effort and
injects the configured text verbatim instead of either built-in policy.
## Verification
- `just test -p codex-core multi_agent_mode`
- Covers a configured hint across High and Ultra reasoning efforts and
verifies the full custom hint is recorded for both turns.
- Covers an empty-string override suppressing both built-in instruction
bodies.
- `just test -p codex-protocol -p codex-app-server-protocol`
- Covers legacy `none` turn-context deserialization as `Custom("")` and
verifies the regenerated schemas.
## Why
Response item IDs represent stable conversation identity.
`ContextManager::for_prompt` repairs an unmatched call by synthesizing
an `"aborted"` output in the disposable prompt projection, but that
output previously had no ID. Assigning a fresh ID on every prompt build
would make retries and resumes change otherwise identical model context
and reduce prompt-cache reuse.
The concrete bug is that these normalization-created outputs bypass the
regular item-ID allocation path. Even with item IDs enabled, a prompt
could therefore contain an identified call paired with a synthetic
output whose `id` was missing. This change closes that gap by deriving
the output ID from the source call's item ID. For legacy calls that have
no item ID, the output remains ID-less because there is no stable source
identity to derive from.
The originating call already has a stable item ID under the item-ID
model introduced in #28814. A prompt-only output can therefore derive
stable identity from that call without mutating canonical history or
persisted rollouts. This addresses the failure exposed by #30311 while
keeping normalization read-only outside its detached prompt snapshot.
UUIDv5 is intentional here because it is the standard namespaced,
deterministic UUID construction. Using the output kind and source call
ID as the name produces the same UUID on every projection while keeping
output kinds in separate name domains. UUIDv7 would introduce randomness
and time, so keeping it stable would require persisting the synthetic
repair. UUIDv5 uses SHA-1 internally, but this is only an identity
mapping—not an authenticity or security boundary.
## What changed
- Derive a deterministic UUIDv5 ID for each synthesized call output from
the source call item ID.
- Use the Responses API prefix appropriate for function, custom-tool,
tool-search, and local-shell outputs.
- Preserve the existing insertion position immediately after the
unmatched call.
- Keep synthesized outputs prompt-only; no rollout, task-lifecycle,
compaction, or raw-response behavior changes.
## Testing
- `just test -p codex-core
for_prompt_assigns_stable_id_to_synthetic_output_without_reordering_history`
- `just test -p codex-core
synthetic_call_output_id_is_stable_across_resumes`
- `just test -p codex-core normalize_adds_missing_output`
- `just test -p codex-core response_item_ids`
## Summary
- Preserve the optional namespace on custom tool calls during response
deserialization and app-server replay.
- Use the namespaced tool identifier for streaming argument handling and
tool dispatch.
- Regenerate app-server protocol schemas.
- Add regression tests covering namespace serialization and routing.
## Testing
- Ran affected protocol and app-server test suites.
- Ran the full core test suite; two load-sensitive timing tests passed
when rerun individually.
- Ran Clippy and formatting checks.
- Verified with a local end-to-end app-server replay that the namespace
is preserved through the complete request/response flow.
## Why
Older rollouts can retain model-visible context for a WorldState section
without having a persisted snapshot for that section. Treating the
missing snapshot as definitely absent can duplicate old context or fail
to tell the model that it was replaced or removed.
This provides a generic migration path for sections moving into
WorldState, beginning with AGENTS.md.
Builds on #29810.
## What changed
- distinguish section state that is absent, known from a persisted
snapshot, or unknown because matching legacy context remains in history
- let WorldState sections identify their own legacy fragments while
`ContextManager` owns history reconciliation and baseline persistence
- make AGENTS.md emit one conservative replacement or removal update for
legacy history, then deduplicate from the newly persisted baseline
- preserve existing environment rendering when persisted section data is
missing or malformed
## Testing
- `just test -p codex-core world_state`
- `just test -p codex-core
cold_resume_invalidates_deleted_legacy_agents_md_once -- --exact`