## Why
Shared routing cookies can change after a parent connection is established. Guardian reviews need the routing affinity captured with their parent response so unrelated traffic does not replace that hint.
## What changed
- Capture `__oailb` and `__cflb` cookies from successful ChatGPT WebSocket handshakes and pair them with the parent response ID.
- Retain the snapshot throughout a review and its retries, and apply it only to Guardian requests with the matching parent response. Reconnect cached reviewer sockets when the parent affinity changes.
- Preserve cookie expiry and restrict reuse to the original secure origin and endpoint path. Replace routing cookies while retaining unrelated cookies, and keep the captured affinity out of prompts, history, and serialized metadata.
## Testing
Add coverage for cookie scope, expiry, duplicate rejection, and merging; replaying a captured pin after shared cookies change or are deleted; and retaining the matching parent snapshot through compaction without exposing cookies in review prompts or metadata.
GitOrigin-RevId: d180679e6265b612a3617f20ca1f5dec89e73aa8
## Why
Native extensions need configured Responses metadata for request attribution, but extension calls used the MCP metadata template, which omits it. Image requests also did not forward the turn metadata to the backend.
## What changed
Use the Responses metadata template for native extension calls while continuing to exclude tool inventory. Forward the resulting metadata in the `x-codex-turn-metadata` header on image generation and edit requests.
## Testing
Extend metadata tests to cover configured values in extension calls and app-server tests to verify `display_name` and `turn_trigger` on image generation and edit requests, including a Unicode display name.
GitOrigin-RevId: a2ffaa4d15259c662917612391b8717ee34b9c6c
## Why
Clients need a way to update individual turn metadata entries without replacing the existing client metadata map.
## What changed
Add the experimental `responsesapiClientMetadataPatch` field to `turn/start` and `turn/steer`. Patches add or overwrite entries while retaining other keys and apply after `responsesapiClientMetadata` when both are supplied. The existing field retains replacement semantics, including clearing unprotected entries with an empty map.
Continue protecting reserved metadata keys and preserving targeted `misalignment_override` continuations across updates.
## Testing
Extend the app-server metadata integration test to cover replacement and patch steering, patch precedence at turn start, preservation of unrelated entries during patches, and protection of targeted continuations.
GitOrigin-RevId: 8c4da3ba1b87329da20b5295846bdcf3a88126de
## What changed
Add `history_initialization` to `x-codex-turn-metadata`, distinguishing `new`, `cleared`, `cold_resume`, `warm_fork`, `cold_fork`, and `supplied_history`.
Classify forks by whether the source runtime is loaded and has not shut down. Preserve the classification for the runtime's lifetime, including warm resumes and compaction. This records how history was initialized; it does not establish whether tool metadata is missing. Reserve the field against client-supplied overrides.
## Testing
Extend coverage for warm and cold forks, cold resumes, warm reconnects, supplied history, WebSocket metadata serialization, and reserved-field filtering.
GitOrigin-RevId: 468153512a84d0f4d4ea742198a29e0fa3873a72
## What changed
- Carry opaque `review_target` values through misalignment errors and expose optional `reviewTarget` in the app-server protocol and generated clients. Preserve the value verbatim and redact it from debug output.
- Keep target-based `misalignment_override` metadata on turn requests, preserve it across steering updates, and exclude it from compaction and external MCP metadata. Reject overrides from global Responses metadata while retaining legacy timestamp behavior for per-turn overrides.
## Testing
Extend coverage for error propagation, debug and rollout redaction, steering preservation, and metadata filtering. Verify that automatic compaction omits the review target while turn requests before and after compaction retain it.
GitOrigin-RevId: 8c1abb076a206ff5927a4acc31bd25e3efc2bff9
## What changed
- Record each MCP source and its first turn, including connector and plugin identifiers when available. Cover direct and Code Mode calls, including returned errors and results that are not printed.
- Persist cumulative attribution checkpoints and restore them across compaction, resume, and forks, including forks limited to recent turns.
- Attach fresh attribution to Responses API `client_metadata` under `mcp_attribution`, outside model-visible content. Restrict transmission to allowed OpenAI HTTPS destinations for both HTTP and WebSocket requests.
- Report `attribution_error` for legacy history without checkpoints, malformed or conflicting attribution, and serialized attribution exceeding 16 KiB.
## Testing
Add coverage for source deduplication, checkpoint persistence and restoration, recent-turn forks, direct and Code Mode calls, destination filtering, and the serialized size limit.
GitOrigin-RevId: fd285e152ca9e24bfa000debb20013709d67a86e
## What changed
- Accept `windows.sandbox = "mxc"` and preserve the selected backend through environment configuration, command execution, patch writes, and sandbox metadata.
- Treat MXC as enabled in the TUI and report Windows sandbox readiness as `ready`, avoiding legacy setup prompts.
- Keep `allowed_sandbox_implementations` scoped to the legacy elevated and unelevated backends without restricting MXC.
- Default `windows.sandbox_private_desktop` to `false` for MXC while retaining `true` for legacy sandboxes.
## Testing
Add coverage for MXC configuration precedence, legacy requirement handling, sandbox selection, and TUI state. Add a Wine integration test that verifies command and patch routing fails when native MXC is unavailable and reports `windows_mxc` in turn metadata.
GitOrigin-RevId: e2162447d0750f60753864c92a20e02a7f297bca
## Why
Model and reasoning effort updates during a turn can leave request metadata and tool hooks reporting the turn's initial settings. Metadata should describe the step that issued the request or tool call.
## What changed
- Share captured execution metadata across Responses, MCP, and extension tool calls, including model, reasoning effort, and automatic review and Node REPL flags.
- Build Responses tool inventory metadata from the issuing step's finalized tool router. Attach the finalized inventory separately for remote compaction.
- Use captured step settings for pre- and post-tool hooks, and captured review settings for permission-request hooks.
## Testing
Add and extend regression tests for model and effort changes during a turn, MCP metadata, pre-tool hook model attribution, captured review flags, and tool inventory matching the issuing request.
GitOrigin-RevId: 9dee46a8b4839de8b434cdad4ed441cc0bb6ff9b
## What changed
Add an optional `analytics_enabled` boolean to `x-codex-turn-metadata`, sourced from the session's selected analytics client. It reports collection state independently of event eligibility or delivery and is omitted without initialized session analytics context.
Reserve `analytics_enabled` so configured or client-supplied metadata cannot override it. Continue accepting existing configurations containing this key while filtering their values from request metadata.
## Testing
Add coverage for the selected analytics client's state taking precedence over turn configuration, reserved-key filtering and compatibility, enabled state in HTTP headers and body metadata, and disabled state in WebSocket prewarm and turn requests.
GitOrigin-RevId: d95375c5ebc27e9d763a7e1a98687a27e4a8d99c
## What changed
Populate `turn_trigger` in request metadata with `guardian_review` for guardian reviews, `guardian_classifier` for classifier requests, and `memory_consolidation` for both detached memory requests and consolidation agent turns.
## Testing
Extend request metadata assertions to cover each trigger across guardian reviews, classifier requests, and both memory startup phases.
GitOrigin-RevId: 2dc3c173ede6563b942b8099ad9901c32967b969
## Why
Background and empty-input turns could lack a `root_turn_id`, and detached memory requests omitted turn identity entirely. Tasks without a root could also adopt one from coalesced mailbox input.
## What changed
- Set `root_turn_id` to the task's turn ID at task start unless an inherited or recovered root is already present.
- Stop assigning roots from mailbox input or steering an active turn.
- Give detached memory requests a fresh UUID for both `turn_id` and `root_turn_id`, included in turn headers and client metadata while still omitting session and thread identity.
## Testing
Extend assertions for background turns, empty input, goal continuations, manual compaction, and detached memory requests. Exercise mailbox coalescing with both independent and inherited roots to verify the task keeps its established root.
GitOrigin-RevId: ee0f2f1b43542a9f5884f694c1d94341b476779c
## What changed
- Set `CODEX_VERSION` to the running package version in user shell and unified
exec environments, overriding stale shell-policy or snapshot values.
- Add the reserved `codex_version` field to MCP turn metadata.
## Testing
- Cover version propagation through shell policies, shell snapshots, unified
exec, and MCP metadata.
GitOrigin-RevId: 7846c70d668176530b1f467293b749dc9ddd79a0
## Why
Git root discovery is optional metadata work, but filesystem probes can block. They should not exhaust Tokio's blocking pool, delay runtime shutdown, or prevent later turns from observing repository changes.
## What changed
- Add a shared `GitRootDiscovery` service that coalesces concurrent lookups for the same working directory and limits probes across directories.
- Run probes on detached threads, retain in-flight work across caller cancellation, and discard completed results instead of caching them.
- Use the service for turn and memory metadata enrichment, abort unused turn enrichment when its state is dropped, and limit memory metadata waits to one second.
## Testing
Add coverage for probe sharing, capacity limits, cancellation, fresh discovery, runtime shutdown, memory timeouts, and repositories restored after startup prewarming.
GitOrigin-RevId: bca46fc263e7a12a2f69146d8a0b3e7c7e0846cb
## What changed
- Add `turn_trigger` and `codex_turn_source` to `codex_turn_event` analytics.
- Read the source from effective Responses metadata, preserving configured-over-client precedence and reflecting accepted steer metadata.
- Omit trigger and source values from analytics when they exceed the existing Responses metadata value limit.
## Testing
- Cover event serialization, turn lifecycle emission, configured and client source precedence, size limits, and source updates after steering.
GitOrigin-RevId: bbd45af4c6af52956d2394b722ea78e65e5b9bd7
## Why
Sandbox diagnostics could report `read-only` when a configured writable root did not yet exist, because policy labeling used filesystem-aware runtime root resolution.
## What changed
- Derive diagnostic policy labels from configured writable roots without inspecting the filesystem. Runtime sandbox authorization continues to use filesystem-aware resolution.
- Capture sandbox labels once per turn and reuse them for response metadata and tool-result metrics.
## Testing
Add coverage for missing project roots, denied roots, and deny rules on project subpaths.
GitOrigin-RevId: ccbdb8c32a1f44bfa63ae4d2ae1f9cc408e66b9c
## What changed
- Add the zero-based `window_number` to Responses turn metadata and include it in prewarm requests.
- Persist `forked_from_ordinal_exclusive` separately from the physical history base so fork lineage remains accurate after reverts and cold resumes.
- Report context-inheriting subagents through `parent_thread_id` without also emitting fork lineage.
- Reserve the new metadata keys while accepting and filtering previously valid configured values so Codex-owned values take precedence.
## Testing
- Cover window numbering across compaction, resume, and fork operations.
- Cover fork cutoff persistence across direct forks, legacy rollouts, reverts into inherited history, and cold resumes.
GitOrigin-RevId: 288f6cd632254814c1f166668b33828082d799a1
## Why
MCP tool calls can be issued by a model step whose settings differ from the
turn's initial settings. Request metadata must describe the issuing step.
## What changed
- Build MCP tool-call metadata from the captured `StepContext` model and its
effective reasoning effort.
- Populate `node_repl_disabled` from the issuing step while leaving turn-owned
Responses metadata unchanged.
- Apply the same step-scoped values to MCP requests emitted by stop hooks.
## Testing
Add coverage for configured and model-default reasoning effort, model changes,
Node REPL restrictions, and preservation of the original step and turn
metadata.
GitOrigin-RevId: f9cce52fbe559f15437bd19d699b657229c0d145
## 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
- Set `thread_source` to `memory_consolidation` in turn metadata for detached memory requests.
- Verify that startup requests carry matching turn metadata in the request header and nested `client_metadata`.
GitOrigin-RevId: 318d6f097e07463ac7a1c52b35a926532e67b83d
## What changed
- Track Git enrichment completion with a watch channel and unblock waiters when enrichment finishes or is canceled.
- Let the test sync tool wait for the current turn's enrichment with a bounded timeout.
- Replace polling in metadata tests and wait for enrichment before asserting workspace metadata in the guardian integration test.
GitOrigin-RevId: 8d35f75a0ebfe412674e1e797c6a13c03b1ea373
## What changed
- Add `context_window_id` to turn metadata for sampling and compaction requests, using the UUID for the model-visible context window.
- Keep the ID stable for requests in the same context window and advance it after compaction, independently of the existing thread-generation `window_id`.
- Reserve `context_window_id` so client metadata cannot override it.
## Testing
- Cover HTTP and WebSocket metadata, remote compaction, token-budget context alignment, resume behavior, and post-compaction window changes.
GitOrigin-RevId: 55cceea377ad509c8dd96ad668f2b5703ea46a63
## Why
The Linux sandbox represents missing protected metadata paths such as `.git`
with empty read-only directories. Repository and project discovery treated any
`.git` directory as a checkout root, so this synthetic directory could hide a
real parent repository and its trust configuration.
## What changed
- Treat a `.git` directory as repository metadata only when it contains
`HEAD`, while continuing to recognize file-based `.git` entries.
- Protect missing `.git` paths with the same read-only synthetic mounts as
other workspace metadata without disrupting parent-repository discovery.
- Canonicalize and read-only bind the synthetic-mount registry into the
sandbox, and make protected-path cleanup handle read-only directory trees.
## Testing
Added coverage for repository, project-root, trust, synthetic-mount, and
Landlock behavior, including nested incomplete `.git` directories and a
redirected `TMPDIR`.
GitOrigin-RevId: 0724c54d56531143bb28011e4ca414cd3b0212be
## What changed
- Add the canonical agent path as `agent_name` in Responses API turn metadata.
- Fall back to `/root` when a session has no canonical agent path.
- Reserve `agent_name` from client metadata overrides and omit it from MCP request metadata.
## Testing
- Cover root, named subagent, legacy subagent, MCP, and client metadata merge cases.
GitOrigin-RevId: a9adcc079a51beae7d621aba24bcd759ceaa408e
## What changed
- Parse `node_repl_auto_review_required` and `node_repl_disabled` from model catalog entries and include their values in each turn's Responses API metadata.
- Treat both fields as reserved metadata so client-provided values cannot override the selected model's policy.
- Use the selected review model's catalog entry when building metadata for review turns.
## Testing
- Cover metadata propagation across model switches, review turns, Responses API requests, and MCP tool calls.
GitOrigin-RevId: c1f63426eeb8e559abff439fbc618716a4908aff
## 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
- Add `auto_review_enabled` to serialized turn metadata for regular and review turns.
- Derive the value from approval-policy routing and reserve the metadata key so client-provided metadata cannot override it.
## Testing
- Cover enabled metadata, reserved-key handling, Guardian review requests, and updated compaction request snapshots.
GitOrigin-RevId: 52773e2bf7d4be251f8466332de9f9c9869dd084
## What changed
- Add `responses_api_metadata` for product-owned key/value metadata included in
every Responses API turn metadata payload, including parent and subagent
requests.
- Limit the map to 16 entries, ASCII identifier keys of at most 64 bytes, and
values of at most 128 bytes. Reject reserved Codex metadata keys and ignore
this setting in project-local configuration.
- Give configured product metadata precedence over app-server client metadata
while keeping it out of metadata sent to external MCP servers.
## Testing
- Cover reserved-key validation, metadata precedence, MCP isolation, and
propagation to parent and subagent Responses API requests.
GitOrigin-RevId: a7be798294fde25145ab375a468321bb4e4a49f1
## What changed
- Add the effective permission profile as `sandbox_mode` in turn metadata for regular, prewarm, compaction, and detached memory requests.
- Reserve `sandbox_mode` so client-provided metadata cannot override the computed value.
## Testing
- Cover metadata headers and request bodies for read-only and danger-full-access modes.
GitOrigin-RevId: 13c690cc99bc2691023f281ca527af049bb1286f
## What changed
- Stop adding `code_mode_tool_names` to Responses Lite turn metadata.
- Keep `code_mode_tool_names` reserved so client metadata cannot reintroduce the removed, unbounded inventory.
- Use the opt-in `tool_namespaces_info` metadata, including each function's `code_mode_name`, when authoritative tool details are requested.
## Testing
- Update Responses Lite and code-mode tests to verify the opt-in namespace metadata and normalized code-mode names.
GitOrigin-RevId: cbfb9af984de71c7cc175d0cd47ae799a5275309
## What changed
- Add opt-in `tool_namespaces_info` metadata for Responses Lite turns when
`tool_registry.turn_metadata_includes_tool_info` is enabled.
- Describe each model-visible function's namespace, direct and deferred
exposure, Code Mode name, and harness or MCP ownership.
- Reject visible namespaces shared by different owners when strict collision
checking and tool inventory metadata are enabled.
- Keep tool inventories out of compatibility headers and metadata sent to MCP
servers.
## Testing
- Cover opt-in behavior, MCP exposure details, namespace ownership collisions,
reserved metadata handling, and Responses Lite request serialization.
GitOrigin-RevId: 6a6965d2ba98e29444fdfbb4ccec6aafcf0391e6
## What changed
- Store synchronization primitives directly in `TurnMetadataState` instead of
wrapping each field in its own `Arc`.
- Require an `Arc<TurnMetadataState>` when spawning Git enrichment so the
background task retains the complete state.
- Update Git enrichment tests to use the shared state container.
GitOrigin-RevId: 745ca6504c0a6533cb7726d045905472e51726df
## 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
## What changed
- Add `code_mode_tool_names` to Responses Lite turn metadata, mapping each normalized code-mode identifier to its structured `ToolName`.
- Reserve the metadata key against client overrides and omit it from metadata exposed to external MCP servers.
- Keep non-Lite requests and the legacy top-level client metadata unchanged.
## Testing
- Cover HTTP and WebSocket Responses Lite requests, including switching from a non-Lite model.
- Verify reserved-key handling and external MCP metadata filtering.
GitOrigin-RevId: b678afba13d57a91e26f5895aa37238fbb4cb276
## Why
Startup prewarms and Guardian review sessions do not need workspace Git metadata. Collecting it for those requests performs redundant work, while user turns still need a fresh view of the repository.
## What changed
- Add a per-session Git enrichment policy.
- Skip enrichment for startup prewarm, preview, and Guardian review turns.
- Keep fresh enrichment enabled for regular sessions and one-shot delegated turns.
## Testing
- Cover prewarm and Guardian requests omitting workspace metadata while subsequent user turns observe repository changes.
- Cover concurrent repositories and worktrees retaining distinct metadata.
- Verify concurrent enrichment is coalesced and canceled enrichment can be retried.
GitOrigin-RevId: 4a68615288bb568c75f2e487d9c0776e3e80f191
## What changed
- Remove the `spawn_agents_on_csv` and `report_agent_job_result` tools and their agent-job runtime and state models.
- Drop the legacy `agent_jobs` and `agent_job_items` tables during state database migration.
- Keep `features.enable_fanout` and `agents.job_max_runtime_seconds` accepted as no-op compatibility settings while omitting them from the generated configuration schema.
## Testing
- Verify upgrades remove both legacy agent-job tables.
- Verify the removed feature and configuration keys still parse without taking effect.
GitOrigin-RevId: 8cc3337da78c67162229f02f40a747f503542646
## Description
Restore `thread_source` in `x-codex-turn-metadata`.
Inadvertently removed `thread_source` from `x-codex-turn-metadata` in
https://github.com/openai/codex/pull/27122 - didn't realize it was a
top-level thread app-server API field, not passed in
`responsesapi_client_metadata`.
This also reserves the key so `responsesapi_client_metadata` cannot
override it.
## What
Introduce a `CodexResponsesMetadata` struct that defines all the core
metadata we send to Responses API. Example fields are `thread_id`,
`turn_id`, `window_id`, etc.
Going forward, `client_metadata["x-codex-turn-metadata"]` will be the
canonical way Codex sends metadata to Responses API across both HTTP and
websocket transports.
For now, we continue to emit the existing top-level HTTP headers and
top-level `client_metadata` fields from the same
`CodexResponsesMetadata` struct for compatibility reasons.
Also, app-server clients who specify additional
`responsesapi_client_metadata` via `turn/start` and `turn/steer` will
have those fields merged into
`client_metadata["x-codex-turn-metadata"]`, but cannot override the
reserved fields that core uses (i.e. the fields in
`CodexResponsesMetadata`).
## Why
Responses API request instrumentation is the source of truth for
downstream Codex analytics that join requests by Codex IDs such as
session, thread, turn, and context window. Before this change, those
values were assembled through several request-specific paths: HTTP
request bodies, websocket handshake headers, websocket `response.create`
payloads, compaction requests, and the rich `x-codex-turn-metadata`
envelope all had their own wiring.
That made metadata propagation easy to drift across API-key/direct
Responses API requests, ChatGPT-auth/proxied requests, websocket
requests, and compaction requests. It also made additions like
`window_id` error-prone because a field could be added to one transport
projection but missed in another.
## What changed
- Added `CodexResponsesMetadata` as the core-owned snapshot for Codex
metadata sent to ResponsesAPI.
- Render `client_metadata["x-codex-turn-metadata"]`, flat
`client_metadata` projections, and direct compatibility headers from
that same snapshot.
- Include the known Codex-owned fields in the turn metadata blob,
including installation/session/thread/turn/window IDs, request kind,
lineage, sandbox/workspace metadata, timing, and compaction details.
- Treat app-server `responsesapi_client_metadata` as enrichment for the
Codex turn metadata blob while preventing those extras from overriding
Codex-owned fields.
- Use the same metadata path for normal turns, websocket prewarm, local
compaction, remote v1 compaction, and remote v2 compaction.
- Keep websocket connection-only preconnect metadata separate so
handshakes carry compatibility identity headers without inventing a fake
turn metadata blob.
## Verification
- `cargo check -p codex-core`
- `just fix -p codex-core`
## Summary
- carry `workspace_kind` from Responses API client metadata into the
turn resolved analytics fact
- serialize the optional value on `codex_turn_event`
- cover both the turn metadata source and turn event serialization
The `workspace_kind` tells us whether a thread had a project attached vs
projectless. this is an indicator for who is adopting Codex for
knowledge work outside of coding
## Testing
- `env UV_CACHE_DIR=/private/tmp/uv-cache
/private/tmp/cargo-tools/bin/just fmt`
- `env PATH=/private/tmp/cargo-tools/bin:$PATH
CARGO_HOME=/private/tmp/cargo-home UV_CACHE_DIR=/private/tmp/uv-cache
/private/tmp/cargo-tools/bin/just test -p codex-analytics`
- `env PATH=/private/tmp/cargo-tools/bin:$PATH
CARGO_HOME=/private/tmp/cargo-home UV_CACHE_DIR=/private/tmp/uv-cache
/private/tmp/cargo-tools/bin/just test -p codex-core turn_metadata`
Paired with openai/openai#970661, which keeps forwarding the same
metadata key through Responses API headers.
## Why
This PR
https://github.com/openai/codex/pull/24161#discussion_r3325692763
revealed a subagent data modeling issue, where we overloaded
`forked_from_id` to also mean `parent_thread_id`. That's incorrect since
guardian and review subagents can be a subagent and NOT fork the main
thread's history.
The solution here is to explicitly store a new `parent_thread_id` on
`SessionMeta`, alongside `forked_from_id` which already exists. While
we're at it, also expose it in the app-server protocol on the `Thread`
object.
A thread->subagent relationship and a fork of thread history are
orthogonal concepts.
## What Changed
- Added top-level `parent_thread_id` persistence on `SessionMeta` and
runtime/session plumbing through `SessionConfiguredEvent`,
`CodexSpawnArgs`, `SessionConfiguration`, `ThreadConfigSnapshot`,
`TurnContext`, and `ModelClient`.
- Made turn metadata, request headers, analytics, and subagent-start
events read the separate runtime/top-level parent field instead of
deriving general parent lineage from `SessionSource` or
`forked_from_thread_id`.
- Passed parent lineage separately at delegated subagent, review,
guardian, agent-job, and multi-agent spawn construction sites;
copied-history fork lineage remains derived only from `InitialHistory`.
- Persisted and exposed parent lineage through rollout/thread-store
projections and app-server v2 `Thread.parentThreadId`.
- Updated app-server README text and regenerated app-server schema
fixtures for the additive `parentThreadId` response field.
## Why
We recently added `forked_from_thread_id` which lets us trace where a
thread's _context_ comes from, but we also want to understand subagent
lineage (e.g. which parent thread spawned this subagent? what kind of
subagent is it?) which is orthogonal.
This PR adds `parent_thread_id` and `subagent_kind` to the
`x-codex-turn-metadata` header sent to ResponsesAPI.
## What changed
- Adds `parent_thread_id` and `subagent_kind` to core-owned
`x-codex-turn-metadata`.
- Restores persisted `SessionSource` and `ThreadSource` from resumed
session metadata so cold-resumed subagent threads keep their lineage on
later Responses API requests.
- Centralizes parent-thread extraction on `SessionSource` /
`SubAgentSource` and reuses it in the Responses client, analytics, agent
control, and state parsing paths.
- Extends reserved-key, git-enrichment, thread-spawn, and app-server v2
metadata coverage for the new lineage fields.
## Verification
- Not run locally per request.
- Added focused coverage in `core/src/turn_metadata_tests.rs` and
`app-server/tests/suite/v2/client_metadata.rs`.
## Summary
- Add `request_kind` values for foreground turn, startup prewarm,
compaction, and detached memory model requests.
- Attach compaction dispatch metadata to local Responses, legacy
`/v1/responses/compact`, and remote v2 compact requests.
- Add the existing logical context-window identifier as `window_id` on
turn-owned model request metadata.
- Keep identity fields optional for detached memory requests, while
still emitting `request_kind="memory"` in non-git/no-sandbox workspaces.
## Root Cause
`x-codex-turn-metadata` has more than one producer. Foreground turns and
compaction requests own a real turn and should carry that turn identity.
Detached memory stage-one requests do not own a foreground turn, so
absent identity fields are valid rather than missing data. Startup
websocket prewarm is also a model request, but it has `generate=false`
and must not be counted as a foreground turn.
`thread_source` or session source identifies where a thread came from
(for example review, guardian, or another subagent). `request_kind`
identifies what the current outbound model request is doing (`turn`,
`prewarm`, `compaction`, or `memory`). A review or guardian thread can
issue either a normal turn request or a compaction request, so source
cannot replace request kind.
## Behavior / Impact
- Ordinary foreground requests send `request_kind="turn"`, their real
identity fields, and `window_id="<thread_id>:<window_generation>"`.
- Startup websocket warmup requests send `request_kind="prewarm"` so
they are not counted as foreground turns.
- Compaction requests send `request_kind="compaction"`, their real
owning turn identity, the existing `window_id`, and
`compaction.{trigger,reason,implementation,phase,strategy}`.
- Detached memory stage-one requests send `request_kind="memory"`
without `session_id`, `thread_id`, `turn_id`, or `window_id`; when no
workspace metadata exists, the kind-only header is still emitted.
- `session_id`, `thread_id`, `turn_id`, and `window_id` remain optional
in the header schema because detached memory requests do not own a
foreground turn or context window.
- `window_id` is not a new ID system: it is copied from the already-sent
`x-codex-window-id` / WS client metadata value at model-request dispatch
time.
- Existing `x-codex-window-id` HTTP/WS emission, value format,
generation advancement, resume behavior, and fork reset behavior are
unchanged.
- `request_kind`, `window_id`, and upstream turn-owned identity fields
remain schema-owned; input `responsesapi_client_metadata` cannot replace
their canonical values.
- No table, DAG, export, app-server API, or MCP `_meta` schema changes
are included.
A compaction attempt stopped by a pre-compact hook issues no model
request and therefore has no request header; its outcome remains in
analytics events. Status, error, duration, and token deltas also remain
analytics fields rather than request-header fields.
Future detached-memory attribution using a real initiating turn ID as
`trigger_turn_id` is intentionally not part of this PR.
## Sync With Main
- Final pushed head `716342e79` is rebased onto `origin/main@0d37db4b2`.
- The metadata conflict came from upstream `#24160`, which added
`forked_from_thread_id` on the same `turn_metadata` surface. Resolution
preserves that field and its protection from client metadata override
alongside this PR's request-kind, compaction, and window-id fields.
- While resolving the overlapping commits, I removed an accidental
recursive model-request overlay and a duplicate detached-memory header
builder before completing the rebase.
## Latency / User Experience Boundary
- Foreground turns perform no new filesystem, git, or network work. New
fields are inserted into metadata already serialized for outgoing
requests.
- Compaction issues the same model/HTTP requests with the same prompt,
model, service tier, and sampling settings; only metadata bytes change.
- Startup prewarm already sent metadata; it is now correctly classified
as `prewarm`.
- Non-git detached memory now sends a small kind-only metadata header
rather than no header.
- This client diff adds no user-visible latency mechanism beyond
negligible serialization and header bytes on already-existing requests.
## Validation
On conflict-resolved head `1d35c2cfb` based on `origin/main@487521733`:
- `just fmt` (passed)
- `just fix -p codex-core` (passed)
- `git diff --check origin/main...HEAD` (passed)
- `just test -p codex-core -E 'test(turn_metadata) |
test(websocket_first_turn_uses_startup_prewarm_and_create) |
test(responses_stream_includes_turn_metadata_header_for_git_workspace_e2e)
|
test(responses_websocket_forwards_turn_metadata_on_initial_and_incremental_create)
| test(remote_compact_v2_retries_failures_with_stream_retry_budget) |
test(window_id_advances_after_compact_persists_on_resume_and_resets_on_fork)'`
(`23 passed`; `bench-smoke` passed)
- `just test -p codex-app-server -E
'test(turn_start_forwards_client_metadata_to_responses_request_v2) |
test(turn_start_forwards_client_metadata_to_responses_websocket_request_body_v2)
| test(auto_compaction_remote_emits_started_and_completed_items)'` (`3
passed`; `bench-smoke` passed)
- `just test -p codex-memories-write` (`29 passed`; `bench-smoke`
passed)
## Why
When Codex calls responsesapi, we currently send `session_id`,
`thread_id`, and `turn_id` among other things as
`client_metadata["x-codex-turn-metadata"]`. This PR adds
`forked_from_thread_id` which helps explain the "lineage" of a forked
thread.
## What's changed
- Track the immediate history source copied into a forked thread through
thread/session creation, including subagent and review turn metadata
paths.
- Include `forked_from_thread_id` in Codex turn metadata while
preventing turn-scoped Responses API client metadata from overwriting
Codex-owned lineage fields.
- Add coverage for fork lineage in turn metadata and the app-server
Responses API request path.
## Why
Sandbox telemetry tags should be derived from the active permission
profile, not from a legacy `SandboxPolicy`, so the tagging code stays
aligned with the permissions migration and does not preserve a
policy-shaped production helper only for tests.
## What Changed
- Removed the production `sandbox_tag(&SandboxPolicy, ...)` helper.
- Updated sandbox tag tests to construct the relevant
`PermissionProfile` values directly.
- Kept the platform-specific sandbox tag behavior under the existing
`permission_profile_sandbox_tag` path.
## How To Review
The production change is in `codex-rs/core/src/sandbox_tags.rs`. Most of
the diff is test cleanup that replaces legacy policy setup with
permission profiles, so review the expected tag assertions rather than
the old helper mechanics.
## Verification
- `cargo test -p codex-core sandbox_tag`
---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/22791).
* #22795
* #22792
* __->__ #22791
## Why
- Similar change as https://github.com/openai/codex/pull/21219
- Without change: MCP tool calls receive
`_meta["x-codex-turn-metadata"]` with various key values.
- Issue: MCP servers currently do not know if user input was requested
during the turn (Ex: Model decides to prompt the user for approval
mid-turn before making a possibly risky tool call). MCP servers may want
to know this when tracking latency metrics because these instances are
inflated.
## What Changed
- With change: MCP turn metadata now includes
`user_input_requested_during_turn` when a model-visible
`request_user_input` call happened earlier in the turn, propagated in
`_meta["x-codex-turn-metadata"]`.
- `mark_turn_user_input_requested()` is called when user input is
requested through either MCP elicitation (`mcp.rs`) or the
`request_user_input` tool (`mod.rs`).
- MCP tool call `_meta` is now built immediately before execution
(`mcp_tool_call.rs`) so user input requested earlier in the same turn,
including within the same tool call via elicitation, is reflected in the
metadata.
- Normal `/responses` turn metadata headers are unchanged.
## Verification
- `codex-rs/core/src/session/mcp_tests.rs`
- `codex-rs/core/src/tools/handlers/request_user_input_tests.rs`
- `codex-rs/core/src/turn_metadata_tests.rs`
- `codex-rs/core/tests/suite/search_tool.rs`
## Why
MCP tool calls already include `session_id` in `x-codex-turn-metadata`,
but descendant threads intentionally share that value with the root
thread. Consumers that need to correlate work at the concrete thread
level also need the current `thread_id`.
## What changed
- add `thread_id` to `x-codex-turn-metadata` while preserving
`session_id` as the shared session identity
- thread the two identities separately through normal turns and spawned
review threads
- add regression coverage for resumed sessions, reserved metadata
fields, and deferred MCP tool calls
## Verification
- added focused coverage in `core/src/session/tests.rs`,
`core/src/turn_metadata_tests.rs`, and `core/tests/suite/search_tool.rs`
## Summary
- make `thread_source` an explicit optional thread-level field on
`thread/start`, `thread/fork`, and returned thread payloads
- persist `thread_source` in rollout/session metadata so resumed live
threads retain the original value
- replace the old best-effort `session_source` -> `thread_source`
mapping with an explicit caller-supplied analytics classification
## Why
Before this change, analytics `thread_source` was populated by a
best-effort mapping from `session_source`. `session_source` describes
the runtime/client surface, not the actual thread-level origin, so that
projection was not accurate enough to distinguish cases such as `user`,
`subagent`, `memory_consolidation`, and future thread origins reliably.
Making `thread_source` explicit keeps one thread-level analytics field
while letting callers provide the real classification directly instead
of recovering it indirectly from `session_source`.
## Impact
For new analytics events, `thread_source` now reflects the explicit
thread-level classification supplied by the caller rather than an
inferred value derived from `session_source`. Existing protocol fields
remain optional; callers that omit `threadSource` now produce `null`
instead of a best-effort inferred value.
## Validation
- `just write-app-server-schema`
- `cargo test -p codex-analytics -p codex-core -p
codex-app-server-protocol --no-run`
- `cargo test -p codex-app-server-protocol
generated_ts_optional_nullable_fields_only_in_params`
- `cargo test -p codex-analytics
thread_initialized_event_serializes_expected_shape`
- `cargo test -p codex-core
resume_stopped_thread_from_rollout_preserves_thread_source`
## Why
- Similar change as https://github.com/openai/codex/pull/19473.
- Without change: MCP tool calls receive
`_meta["x-codex-turn-metadata"]` with `session_id`, `turn_id`, and
`turn_started_at_unix_ms`.
- Issue: MCP servers may want the model and reasoning effort to better
understand tool-call behavior and latency relative to turn start.
## What Changed
- With change: MCP turn metadata now includes `model` and
`reasoning_effort`, propagated in `_meta["x-codex-turn-metadata"]`.
- Normal `/responses` turn metadata headers are unchanged.
## Verification
- `codex-rs/core/src/mcp_tool_call_tests.rs`
- `codex-rs/core/src/turn_metadata_tests.rs`
- `codex-rs/core/tests/suite/search_tool.rs`
## Why
`x-codex-turn-metadata` is sent as an HTTP/WebSocket header, but Codex
was serializing the metadata JSON with raw UTF-8 string contents. When a
workspace path contains non-ASCII characters, common HTTP stacks can
reject or corrupt that header before the request reaches the provider.
Fixes#17468. Also addresses the duplicate WebSocket report in #19581.
## What changed
- Added `codex_utils_string::to_ascii_json_string`, a shared helper that
serializes JSON normally while escaping non-ASCII string content as
`\uXXXX`.
- Switched turn metadata header serialization, including merged
Responses API client metadata, to use the ASCII-safe JSON helper.
- Added coverage for non-ASCII workspace paths and non-ASCII client
metadata while preserving the same parsed JSON values.
## Verification
- `cargo test -p codex-utils-string`
- `cargo test -p codex-core turn_metadata`
- `just bazel-lock-check`
## Why
- Without change: MCP tool calls receive
`_meta["x-codex-turn-metadata"]` with `session_id` and `turn_id`.
- Issue: MCP servers may want the turn start timestamp to measure
internal latency relative to turn start.
## What Changed
- With change: turn metadata now includes `turn_started_at_unix_ms`,
which is propagated to MCP tool calls in
`_meta["x-codex-turn-metadata"]`.
## Verification
- `codex-rs/core/src/mcp_tool_call_tests.rs`
- `codex-rs/core/src/turn_metadata_tests.rs`
- `codex-rs/core/src/turn_timing_tests.rs`
- `codex-rs/core/tests/responses_headers.rs`
- `codex-rs/core/tests/suite/search_tool.rs`
## Why
This supersedes #19391. During stack repair, GitHub marked #19391 as
merged into a temporary stack branch rather than into `main`, so the
runtime-config change needed a fresh PR.
`PermissionProfile` is now the canonical permissions shape after #19231
because it can distinguish `Managed`, `Disabled`, and `External`
enforcement while also carrying filesystem rules that legacy
`SandboxPolicy` cannot represent cleanly. Core config and session state
still needed to accept profile-backed permissions without forcing every
profile through the strict legacy bridge, which rejected valid runtime
profiles such as direct write roots.
The unrelated CI/test hardening that previously rode along with this PR
has been split into #19683 so this PR stays focused on the permissions
model migration.
## What Changed
- Adds `Permissions.permission_profile` and
`SessionConfiguration.permission_profile` as constrained runtime state,
while keeping `sandbox_policy` as a legacy compatibility projection.
- Introduces profile setters that keep `PermissionProfile`, split
filesystem/network policies, and legacy `SandboxPolicy` projections
synchronized.
- Uses a compatibility projection for requirement checks and legacy
consumers instead of rejecting profiles that cannot round-trip through
`SandboxPolicy` exactly.
- Updates config loading, config overrides, session updates, turn
context plumbing, prompt permission text, sandbox tags, and exec request
construction to carry profile-backed runtime permissions.
- Preserves configured deny-read entries and `glob_scan_max_depth` when
command/session profiles are narrowed.
- Adds `PermissionProfile::read_only()` and
`PermissionProfile::workspace_write()` presets that match legacy
defaults.
## Verification
- `cargo test -p codex-core direct_write_roots`
- `cargo test -p codex-core runtime_roots_to_legacy_projection`
- `cargo test -p codex-app-server
requested_permissions_trust_project_uses_permission_profile_intent`
---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/openai/codex/pull/19606).
* #19395
* #19394
* #19393
* #19392
* __->__ #19606