## Why
A first user turn and a concurrent raw response-item injection can both
observe that the session has no reference context. Both can then append
the initial prompt prefix and persist a full world-state snapshot.
## What changed
Allow context preparation to run concurrently, then serialize publication
of the initial prefix and its checkpoints. If injection publishes first,
the user turn computes its context updates against the published baseline.
If the user turn publishes first, injection appends only the
caller-provided items.
## Testing
Add an integration test that forces the overlap in both preparation
orders. It checks the first request's world-state updates, verifies that
the follow-up request contains the initial instructions and injected
content once each, and checks that history contains one full snapshot.
GitOrigin-RevId: b66f9c6ccc5d42a2be0e852b4d83b78adbc9e5b2
## What changed
Allow `thread/inject_items` to accept wrapped items with `retention: "default"` or `retention: "always"`, while preserving support for raw response items. Persist explicit policies separately from legacy client-authored metadata.
Carry explicitly retained items through local and remote compaction, context-window changes, and child-agent creation, subject to retention budgets. Preserve history order and keep retained tool exchanges together; require matching calls and outputs to be adjacent in the injection request and both marked `always`.
Update Quinn dependencies and record exceptions for additional Hickory DNSSEC advisories where DNSSEC is disabled.
## Testing
Update injection tests for explicit retention metadata and extend the compaction scenario to cover a retained tool exchange across repeated compaction and restart.
GitOrigin-RevId: 1195a4ed62dc162a62e58bc2ad733262fbabea27
## What changed
- Add the disabled-by-default `safe_image_decoder` feature to decode and re-encode prompt images without source metadata, with byte and decoded-pixel limits.
- Apply JPEG orientation and supported ICC color conversion to sRGB, emitting PNG for PNG/GIF inputs and JPEG for JPEG/WebP inputs.
- Use the selected decoder for image preparation, `view_image` validation, and MCP image validation. Include the decoder in image cache keys.
- Preserve original inline images in history metadata so resume and fork can regenerate prepared images without repeated JPEG encoding changing their bytes.
## Testing
Add regression tests for identical JPEG replay after history serialization and for preventing legacy cache entries from bypassing sanitization.
GitOrigin-RevId: 718cd83d0a233e2eb8efd1a64c14d8944e44c350
## Why
Converting message content to tool output previously reduced file-backed audio to a text file ID, losing its audio type.
## What changed
- Allow `input_audio` tool output items to carry either `audio_url` or `file_id`, preserving both forms during content conversion.
- Account for file-backed tool audio in history estimates and output truncation, and prepare only inline audio data.
- Reject uploaded audio in raw function and custom tool output injection, extending the existing requirement to submit uploaded audio through typed turn input.
- Regenerate app-server schemas and TypeScript/Python types while preserving the Python inline audio class name.
## Testing
Add coverage for tool audio wire-format round trips, repeated file audio sharing text and audio output budgets, and rejection of raw uploaded audio injection across messages and tool outputs. Extend Python SDK coverage for the inline tool audio shape.
GitOrigin-RevId: f4704466e6151662d2c8b8dc3f5ca2ab2f5710a2
## What changed
Introduce `ItemIdGenerator` and pass the runtime-owned generator through sessions, model clients, history, hooks, tool outputs, and memory requests. Keep UUIDv7 generation as the default and replace direct calls to `ResponseItemId::new` with the shared callable.
Preserve existing item IDs and backfill missing or empty IDs through the same generator, including forked history before reconstruction and persistence.
## Testing
Extend coverage for UUIDv7 IDs on user messages, agent messages, and additional tools, and assert that forked model context matches the backfilled items persisted to history.
GitOrigin-RevId: 0dd9ccf0f46f0f1005a6acfc740133b03ce82259
## What changed
Tag untrusted additional context rendered as tool outputs with history metadata and apply `guardian_include_additional_context` when building Guardian review history. Preserve this metadata across session resume and apply the current session's setting to restored review checkpoints.
Keep ordinary tool outputs in review history and preserve the acting model's additional-context payload.
## Testing
Add coverage for inclusion and exclusion after restart, restored checkpoints after compaction, and asynchronous Guardian review. Verify both line and JSON transcripts and check that metadata does not alter the acting model's request.
GitOrigin-RevId: 8ba270a6aac16398c88db3282e9d666702f462fe
## Why
Injected agent messages need to reach active sampling before stale tool calls execute, while messages queued around a final answer must wait for the next task without requesting another response.
## What changed
- Include injected `agent_message` items in mailbox preemption checks when the matching turn still accepts mail and `DeferMailboxPreemption` is disabled.
- Treat injected agent messages as queue-only mail so they do not reopen delivery after a final answer or force a follow-up response.
## Testing
Add a streaming scenario and context snapshot covering idle injection, active sampling preemption, deferred delivery around a final answer, and preservation of message payloads and ordering before the next task.
GitOrigin-RevId: 70f49cbe5074725c11e1fcb33eea05e0e92e17f7
## What changed
- Allow audio inputs to carry uploaded file references via `fileId` in the app-server API and `file_id` in model content, preserving existing inline audio shapes and Python class names.
- Preserve mixed inline and file-backed audio ordering through history reconstruction and migration, and budget file-backed audio conservatively when duration is unknown.
- Keep uploaded audio disabled at runtime: reject it before inference or raw history injection, preserve accompanying text, and prevent rejected attachments from reaching follow-up or resumed requests.
## Testing
Add coverage for wire-format round trips, SDK compatibility, mixed audio history ordering, and rejection during turn start, steering, task completion, and raw injection.
GitOrigin-RevId: 70895c47a2494c0c9936348ad1250eb1b7b892a6
## Why
Inputs arriving during turn finalization could be queued after the final batch had already been drained, or recorded ahead of that batch.
## What changed
Mark active turns as finishing before draining pending input. Reject injection into finishing turns and make late client responses and notifications wait until the final batch is recorded before appending to history. Continue accepting input into turns reserved but not yet started.
## Testing
Extend the task-completion test to block final recording, verify that input admission is closed, and confirm that a late notification is recorded after queued input while preserving the notification truncation budget. Strengthen the retained-tool-output scenario to assert tool output names and ordering.
GitOrigin-RevId: a57e44bd974e60e134183dab989795e2c3538596
## Why
Reused Guardian sessions already contain previously delivered instructions. Follow-up reviews can avoid repeating that evidence, but must deliver it again if it changes or compaction removes it.
## What changed
- Track retained source identity, revision, and completeness in host-owned history metadata, preserving revisions during replay.
- Omit retained instructions from synchronous review inputs only when the same complete revision remains in reviewer history.
- Restore missing evidence after reviewer compaction, enforcing the request budget before persisting additions. Classify restored evidence as context rather than new user authorization.
- Keep source-order labels stable across eviction and retain full delivery for legacy records without reliable provenance.
## Testing
Add coverage for consecutive-review deduplication, changed revisions, missing or incomplete metadata, and restoring compacted evidence exactly once. Extend compaction and resume coverage to verify retained revisions.
GitOrigin-RevId: e90fca16cde0a0970da36dd873af2ca1dbaaf4d3
## Why
Image preparation replaces uploaded images with file references in model history, but user message events still retain the original local paths or inline image URLs. Live and persisted display history should carry the prepared file IDs as well.
## What changed
- Prepare images before emitting user message events, and copy uploaded file IDs into the corresponding user inputs.
- Track original input positions through content expansion so failed image reads, omitted inputs, and duplicate URLs do not misassociate images.
- Preserve text spans, image detail settings, and inputs without a prepared file reference.
## Testing
Add a protocol test for image position mapping and an integration test covering file IDs in model requests, live user message events, and persisted display history, including failed images and duplicate URLs.
GitOrigin-RevId: 55e7ab97925b5db049c5c2403d90349635eee740
## What changed
Upload prepared images from messages and tool outputs through the session's `AttachmentStore` before recording history. Use the returned inline bytes or file reference, and fall back to the prepared inline image if upload fails.
Keep history replay on `InlineAttachmentStore` so it does not upload recorded images, and preserve existing file references. Reuse image resizing directly for guardian review comparisons without uploading.
## Testing
Add coverage for upload failure preserving resized inline images. Extend rollout coverage to verify that only new images are uploaded, uploaded bytes have the expected dimensions, and file references and resize notices survive replay.
GitOrigin-RevId: e9966297c3579ef1e52376f0235fe3a7e3ec7ecc
## Why
A yielded code mode cell can emit a notification after the session switches models. Its output should retain the originating model's truncation budget instead of using the receiving model's budget.
## What changed
Carry the cell's output token limit, including the serialization allowance, through notification dispatch and attach it as `history_truncation_token_limit` metadata. Allow `inject_if_running` to accept response item envelopes so queued notifications preserve this metadata in history and rollouts.
## Testing
Add regression coverage for delayed notifications across a model switch, verifying per-cell truncation budgets, full notification text in raw events, and persisted rollout metadata. Add a task-completion test that checks notification budgets are preserved alongside queued user input.
GitOrigin-RevId: 28380a039a6d41ea324401fcf1f611d81a279477
## Why
History recording used the model captured at turn start, so switching models within a turn could apply stale image preparation and tool-output truncation rules.
## What changed
Pass explicit model metadata through conversation recording. Record model responses and tool results using their originating step's settings, and capture the current model for pending input recorded during startup interruption or task completion.
## Testing
Add regression coverage for tool results across a model switch, explicit model selection for plain and annotated history, and image input retained during interruption and completion. Extend model-switching tests to verify that prepared media and item identity survive switching back to a multimodal model in live, resumed, and forked threads.
GitOrigin-RevId: 5bc750c30c334acb9b802cb80fdea01daffa84a1
## Why
Reasoning configuration changes need to retain their position and trusted provenance when model history is persisted and replayed. Client-injected history must not be able to forge these controls.
## What changed
- Add a typed `configuration_update` response item carrying reasoning effort, including custom model-defined values.
- Persist harness-authored updates with provenance and preserve them across history reconstruction, thread resume, raw response notifications, and agent forks.
- Exclude untrusted configuration updates from model history, strip client-supplied provenance metadata, and reject configuration updates supplied as turn input.
- Export the new item through the JSON and TypeScript app-server schemas and classify it in telemetry and persistence metrics.
## Testing
- Cover serialization, provenance persistence, history filtering and rollback, resume reconstruction, and injection attempts before and after restart.
GitOrigin-RevId: eb5559d2b52b7a931621e7c9812f009ff9fb8939
## Why
Resumed threads need to continue per-turn and per-thread token totals without scanning arbitrarily far beyond the latest compaction checkpoint.
## What changed
- Add durable `TokenUsageRecord` rollout items with response, turn, thread, session, and root-turn attribution.
- Restore accumulated usage on resume and snapshot the latest record plus the compaction response ID in compaction checkpoints.
- Preserve root-turn lineage in persisted turn context, while ensuring forked child threads start with their own usage totals.
## Testing
- Cover usage accumulation across multiple responses and resumed turns.
- Cover local and remote compaction checkpoints, invalid remote compaction output, rollout reconstruction, and fork isolation.
GitOrigin-RevId: ef9e0c4a9102a08a2c382be4cdac68c84353c90a
## Why
Automatic goal continuations should remain attributable to the turn that created the goal. External input, hook context, or goal edits can make that attribution ambiguous and must not leave stale lineage metadata behind.
## What changed
- Carry the trusted root and previous parent turn through successive automatic goal continuations.
- Invalidate stored lineage when external context reaches an active turn or when a goal is edited or cleared.
- Preserve lineage for async hook results only when they belong to the receiving turn.
## Testing
- Cover goal continuations across intervening user turns and external objective edits.
- Cover active, buffered, and externally injected hook or response context.
GitOrigin-RevId: 22ccc07961cd0ed8f4b17912b7efa416b342bf50
## What changed
- Add a positive `output_token_limit` setting to each entry under an MCP server's `tools` configuration.
- Apply the most restrictive limit when plugin and user policies overlap, while keeping approval policy independent.
- Carry the effective MCP output budget in conversation history so tool output, post-tool hook responses, and resumed sessions use the same truncation limit.
## Testing
- Cover configuration parsing, serialization, schema validation, and plugin policy merging.
- Cover MCP output below and above the configured limit, post-tool hook responses, and session resume.
GitOrigin-RevId: d0beb4fca9ba6055d9e1d31c137373b465d50d61
## 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
## What changed
- Mark developer messages received from clients with `client_authored` harness
metadata when `retain_client_developer_messages` is enabled.
- Carry that provenance through pending input and persist it alongside rollout
response items without adding it to provider requests or the serialized
`TurnInput` payload.
- Preserve existing behavior for unannotated response items and when the
feature is disabled.
## Testing
- Cover client item injection before and during turns, additional application
context, rollout replay, image resize notices, and serialization boundaries.
GitOrigin-RevId: f385c177732becde732272e4b8440eb91f5c1039
## Why
`parent_turn_id` identifies the immediate caller of a nested request, but not the
top-level turn that initiated a multi-level chain of work.
## What changed
- Add `root_turn_id` to turn state, submissions, and Responses API metadata.
- Propagate the root through spawned agents, delegated work, review sessions, and
turn-triggering inter-agent messages.
- Omit the root when background work has no user turn or combined input makes the
root ambiguous.
## Testing
Added coverage for nested agent resumes, reviews, mailbox delivery, steered input,
and reserved metadata handling.
GitOrigin-RevId: 60057db2ee81f4efefa946a9f63c74ff98b93929
## What changed
- Resolve user message admission when Core accepts the input as a new turn or a steer, without waiting for rollout persistence.
- Remove persistence- and hook-specific admission errors and task bookkeeping.
- Delete queued messages after Core accepts them for turn processing, including messages subsequently stopped by a prompt hook.
## Testing
- Update concurrent admission and queue service tests for acceptance-based admission.
GitOrigin-RevId: 7dcc311cfecd3d710733b420f2add546edb86153
## What changed
- Add a storage-neutral queue extension for listing, adding, editing, reordering, deleting, and explicitly starting queued user messages.
- Dispatch queued messages in FIFO order when a thread becomes idle after a completed turn, while leaving them queued after interruptions or failures.
- Wait for user input to be persisted before removing its queue item, and report hook rejection, task termination, and persistence failures distinctly.
- Snapshot local image and audio attachments into validated data URLs before storing them, enforce input limits, and emit `ThreadQueueChanged` events after mutations.
## Testing
- Cover queue mutations, automatic and explicit dispatch, interruption and failure behavior, hook rejection, invalid records, input limits, and local attachment snapshotting.
GitOrigin-RevId: 14f39d7c8cbaccb767a6da84b82cced0edfcb4b9
## What changed
- Generalize `CodexThread::try_start_turn_if_idle` to accept exported
`TurnInput` values, preserving user content and client IDs in the first model
request.
- Allow non-empty user input to start an idle turn in Plan mode while retaining
the Plan-mode rejection for automatic response items and empty user input.
- Process idle user input through the normal user-turn path so connector
selections are cleared, prompt telemetry is recorded, and referenced skill
instructions are included.
## Testing
- Cover idle user input in Default and Plan modes, response-item mailbox
merging, empty-input rejection, and skill instruction injection.
GitOrigin-RevId: 116667d160d4464b525d9e4c7e8cc05d23a94008
## What changed
- Propagate the initiating turn ID through agent spawns, follow-up tasks, reviews, and delegated Codex sessions.
- Add `parent_turn_id` to Responses client and turn metadata while keeping it out of external MCP metadata.
- Preserve parent-turn provenance across queued agent messages when their triggering parent is unambiguous.
## Testing
- Cover spawned, resumed, nested, reviewed, delegated, and WebSocket request metadata.
- Verify queued messages do not claim ambiguous or queue-only parent turns.
GitOrigin-RevId: 481fdebbe7df2031880fe259509273cce50b20a8
## Why
Queue-only child-agent updates that arrive around a final answer should not
restart sampling, but they must remain available to the next turn. Explicitly
injected response items still need to reopen the current turn.
## What changed
- Defer queue-only inter-agent mail after a final answer without treating it as
same-turn pending input.
- Re-enable current-turn mailbox delivery when the model requests a follow-up,
a stop hook continues the turn, or a response item is explicitly injected.
- Check for turn-triggering mailbox work after clearing the completed active
turn so pending work can start safely.
## Testing
Added coverage that queued child mail waits for the next user turn and that an
injected response item after a final answer triggers a follow-up request.
GitOrigin-RevId: aa81d00707943284b7ab069b60970e547908c895
## 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
## Why
Goal idle continuation is extension-triggered model-visible work, so it
should follow one core-owned rule for when automatic work may start. In
particular, it should not jump ahead of queued user/client work, start
while another task is active, or inject a continuation turn while the
thread is in Plan mode.
Keeping this policy in `try_start_turn_if_idle` avoids passing
`collaboration_mode` or review-specific state through
`ThreadLifecycleContributor::on_thread_idle`. Active `/review` is
covered by the same active-task gate because Review turns are not
steerable.
## What Changed
- Teach `Session::try_start_turn_if_idle` to reject automatic idle turns
in Plan mode, both before reserving an idle turn and after building the
turn context.
- Document `CodexThread::try_start_turn_if_idle` as the extension-facing
gate for automatic idle work, including Plan-mode and active Review-task
behavior.
- Add focused coverage for Plan-mode rejection and active Review-task
rejection without queuing synthetic input.
## Testing
- `just test -p codex-core try_start_turn_if_idle`
## Why
`try_start_turn_if_idle` is the core helper for starting injected input
only when the session is actually idle. It should stay focused on
generic turn-lifecycle safety. The previous `ModeKind::Plan` guard mixed
caller policy into that helper: Plan mode may choose not to auto-start
some extension work, but that decision belongs at the extension or
caller boundary rather than in the session injection primitive.
## What changed
- Removed the `ModeKind::Plan` early return from
`Session::try_start_turn_if_idle`.
- Removed the now-unused `ModeKind` import from
`core/src/session/inject.rs`.
## Testing
Not run locally.
## Why
The goal extension needs a way to resume an active goal after the thread
becomes idle, but the old core goal runtime should not be refactored as
part of this step. The missing piece is a small core-owned turn-start
primitive: let an extension ask for a normal model turn only when the
thread is idle, and otherwise fail without injecting into whatever is
currently active.
## What Changed
- Adds `CodexThread::try_start_turn_if_idle(...)` as the narrow
extension-facing primitive for synthetic idle work.
- Implements the session side so it refuses to start when:
- the provided input is empty,
- the session is in plan mode,
- a turn is already active, or
- trigger-turn mailbox work is pending.
- Gives trigger-turn mailbox work priority if it appears while the idle
turn is being prepared.
- Wires `GoalExtension::on_thread_idle` to read the active persisted
goal and submit the continuation prompt through this idle-only
primitive.
- Keeps the legacy core goal continuation implementation in place
instead of folding it into this PR.
## Behavior
This is intentionally best-effort. If `try_start_turn_if_idle` observes
that the thread is not idle, or that higher-priority mailbox work should
run first, it returns the input to the caller. The goal extension drops
that continuation prompt and waits for a future idle opportunity instead
of injecting stale synthetic goal text into an active turn.
## Validation
- `just test -p codex-core
try_start_turn_if_idle_rejects_active_turn_without_injecting`
- `just test -p codex-goal-extension`