Merge branch 'main' into etraut/tui-status-regression

.bazelrc

@@ -124,7 +124,6 @@ build:argument-comment-lint --@rules_rust//rust/toolchain/channel=nightly
 common:ci-windows --config=ci-bazel
 common:ci-windows --build_metadata=TAG_os=windows
 common:ci-windows --repo_contents_cache=D:/a/.cache/bazel-repo-contents-cache
-common:ci-windows --repository_cache=D:/a/.cache/bazel-repo-cache
 
 # We prefer to run the build actions entirely remotely so we can dial up the concurrency.
 # We have platform-specific tests, so we want to execute the tests on all platforms using the strongest sandboxing available on each platform.

.github/actions/setup-bazel-ci/action.yml

@@ -9,9 +9,9 @@ inputs:
     required: false
     default: "false"
 outputs:
-  cache-hit:
-    description: Whether the Bazel repository cache key was restored exactly.
-    value: ${{ steps.cache_bazel_repository_restore.outputs.cache-hit }}
+  repository-cache-path:
+    description: Filesystem path used for the Bazel repository cache.
+    value: ${{ steps.configure_bazel_repository_cache.outputs.repository-cache-path }}
 
 runs:
   using: composite
@@ -41,17 +41,16 @@ runs:
     - name: Set up Bazel
       uses: bazelbuild/setup-bazelisk@v3
 
-    # Restore bazel repository cache so we don't have to redownload all the external dependencies
-    # on every CI run.
-    - name: Restore bazel repository cache
-      id: cache_bazel_repository_restore
-      uses: actions/cache/restore@v5
-      with:
-        path: |
-          ~/.cache/bazel-repo-cache
-        key: bazel-cache-${{ inputs.target }}-${{ hashFiles('MODULE.bazel', 'codex-rs/Cargo.lock', 'codex-rs/Cargo.toml') }}
-        restore-keys: |
-          bazel-cache-${{ inputs.target }}
+    - name: Configure Bazel repository cache
+      id: configure_bazel_repository_cache
+      shell: pwsh
+      run: |
+        # Keep the repository cache under HOME on all runners. Windows `D:\a`
+        # cache paths match `.bazelrc`, but `actions/cache/restore` currently
+        # returns HTTP 400 for that path in the Windows clippy job.
+        $repositoryCachePath = Join-Path $HOME '.cache/bazel-repo-cache'
+        "repository-cache-path=$repositoryCachePath" | Out-File -FilePath $env:GITHUB_OUTPUT -Encoding utf8 -Append
+        "BAZEL_REPOSITORY_CACHE=$repositoryCachePath" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 
     - name: Configure Bazel output root (Windows)
       if: runner.os == 'Windows'
@@ -65,10 +64,6 @@ runs:
         $repoContentsCache = Join-Path $env:RUNNER_TEMP "bazel-repo-contents-cache-$env:GITHUB_RUN_ID-$env:GITHUB_JOB"
         "BAZEL_OUTPUT_USER_ROOT=$bazelOutputUserRoot" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
         "BAZEL_REPO_CONTENTS_CACHE=$repoContentsCache" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
-        if (-not $hasDDrive) {
-          $repositoryCache = Join-Path $env:USERPROFILE '.cache\bazel-repo-cache'
-          "BAZEL_REPOSITORY_CACHE=$repositoryCache" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
-        }
 
     - name: Expose MSVC SDK environment (Windows)
       if: runner.os == 'Windows'

.github/workflows/bazel.yml

@@ -58,6 +58,20 @@ jobs:
           target: ${{ matrix.target }}
           install-test-prereqs: "true"
 
+      # Restore the Bazel repository cache explicitly so external dependencies
+      # do not need to be re-downloaded on every CI run. Keep restore failures
+      # non-fatal so transient cache-service errors degrade to a cold build
+      # instead of failing the job.
+      - name: Restore bazel repository cache
+        id: cache_bazel_repository_restore
+        continue-on-error: true
+        uses: actions/cache/restore@v5
+        with:
+          path: ${{ steps.setup_bazel.outputs.repository-cache-path }}
+          key: bazel-cache-${{ matrix.target }}-${{ hashFiles('MODULE.bazel', 'codex-rs/Cargo.lock', 'codex-rs/Cargo.toml') }}
+          restore-keys: |
+            bazel-cache-${{ matrix.target }}
+
       - name: Check MODULE.bazel.lock is up to date
         if: matrix.os == 'ubuntu-24.04' && matrix.target == 'x86_64-unknown-linux-gnu'
         shell: bash
@@ -112,12 +126,11 @@ jobs:
       # Save bazel repository cache explicitly; make non-fatal so cache uploading
       # never fails the overall job. Only save when key wasn't hit.
       - name: Save bazel repository cache
-        if: always() && !cancelled() && steps.setup_bazel.outputs.cache-hit != 'true'
+        if: always() && !cancelled() && steps.cache_bazel_repository_restore.outputs.cache-hit != 'true'
         continue-on-error: true
         uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
         with:
-          path: |
-            ~/.cache/bazel-repo-cache
+          path: ${{ steps.setup_bazel.outputs.repository-cache-path }}
           key: bazel-cache-${{ matrix.target }}-${{ hashFiles('MODULE.bazel', 'codex-rs/Cargo.lock', 'codex-rs/Cargo.toml') }}
 
   clippy:
@@ -148,6 +161,20 @@ jobs:
         with:
           target: ${{ matrix.target }}
 
+      # Restore the Bazel repository cache explicitly so external dependencies
+      # do not need to be re-downloaded on every CI run. Keep restore failures
+      # non-fatal so transient cache-service errors degrade to a cold build
+      # instead of failing the job.
+      - name: Restore bazel repository cache
+        id: cache_bazel_repository_restore
+        continue-on-error: true
+        uses: actions/cache/restore@v5
+        with:
+          path: ${{ steps.setup_bazel.outputs.repository-cache-path }}
+          key: bazel-cache-${{ matrix.target }}-${{ hashFiles('MODULE.bazel', 'codex-rs/Cargo.lock', 'codex-rs/Cargo.toml') }}
+          restore-keys: |
+            bazel-cache-${{ matrix.target }}
+
       - name: Set up Bazel execution logs
         shell: bash
         run: |
@@ -159,6 +186,18 @@ jobs:
           BUILDBUDDY_API_KEY: ${{ secrets.BUILDBUDDY_API_KEY }}
         shell: bash
         run: |
+          bazel_clippy_args=(
+            --config=clippy
+            --build_metadata=COMMIT_SHA=${GITHUB_SHA}
+            --build_metadata=TAG_job=clippy
+          )
+          if [[ "${RUNNER_OS}" == "Windows" ]]; then
+            # Some explicit targets pulled in through //codex-rs/... are
+            # intentionally incompatible with `//:local_windows`, but the lint
+            # aspect still traverses their compatible Rust deps.
+            bazel_clippy_args+=(--skip_incompatible_explicit_targets)
+          fi
+
           bazel_target_lines="$(./scripts/list-bazel-clippy-targets.sh)"
           bazel_targets=()
           while IFS= read -r target; do
@@ -168,9 +207,7 @@ jobs:
           ./.github/scripts/run-bazel-ci.sh \
             -- \
             build \
-            --config=clippy \
-            --build_metadata=COMMIT_SHA=${GITHUB_SHA} \
-            --build_metadata=TAG_job=clippy \
+            "${bazel_clippy_args[@]}" \
             -- \
             "${bazel_targets[@]}"
 
@@ -186,10 +223,9 @@ jobs:
       # Save bazel repository cache explicitly; make non-fatal so cache uploading
       # never fails the overall job. Only save when key wasn't hit.
       - name: Save bazel repository cache
-        if: always() && !cancelled() && steps.setup_bazel.outputs.cache-hit != 'true'
+        if: always() && !cancelled() && steps.cache_bazel_repository_restore.outputs.cache-hit != 'true'
         continue-on-error: true
         uses: actions/cache/save@668228422ae6a00e4ad889ee87cd7109ec5666a7 # v5
         with:
-          path: |
-            ~/.cache/bazel-repo-cache
+          path: ${{ steps.setup_bazel.outputs.repository-cache-path }}
           key: bazel-cache-${{ matrix.target }}-${{ hashFiles('MODULE.bazel', 'codex-rs/Cargo.lock', 'codex-rs/Cargo.toml') }}

.github/workflows/rust-release.yml

@@ -584,14 +584,11 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
         with:
-          node-version: 22
+          # Node 24 bundles npm >= 11.5.1, which trusted publishing requires.
+          node-version: 24
           registry-url: "https://registry.npmjs.org"
           scope: "@openai"
 
-      # Trusted publishing requires npm CLI version 11.5.1 or later.
-      - name: Update npm
-        run: npm install -g npm@latest
-
       - name: Download npm tarballs from release
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

codex-rs/Cargo.lock

@@ -2552,6 +2552,7 @@ dependencies = [
  "codex-process-hardening",
  "ctor 0.6.3",
  "libc",
+ "pretty_assertions",
  "reqwest",
  "serde",
  "serde_json",

codex-rs/core/config.schema.json

@@ -524,6 +524,9 @@
         "include_apps_instructions": {
           "type": "boolean"
         },
+        "include_environment_context": {
+          "type": "boolean"
+        },
         "include_permissions_instructions": {
           "type": "boolean"
         },
@@ -2278,6 +2281,10 @@
       "description": "Whether to inject the `<apps_instructions>` developer block.",
       "type": "boolean"
     },
+    "include_environment_context": {
+      "description": "Whether to inject the `<environment_context>` user block.",
+      "type": "boolean"
+    },
     "include_permissions_instructions": {
       "description": "Whether to inject the `<permissions instructions>` developer block.",
       "type": "boolean"
@@ -2641,4 +2648,4 @@
   },
   "title": "ConfigToml",
   "type": "object"
-}
+}

codex-rs/core/src/client.rs

@@ -28,6 +28,7 @@ use std::sync::Arc;
 use std::sync::Mutex as StdMutex;
 use std::sync::OnceLock;
 use std::sync::atomic::AtomicBool;
+use std::sync::atomic::AtomicU64;
 use std::sync::atomic::Ordering;
 
 use codex_api::CompactClient as ApiCompactClient;
@@ -119,6 +120,9 @@ use codex_response_debug_context::telemetry_transport_error_message;
 pub const OPENAI_BETA_HEADER: &str = "OpenAI-Beta";
 pub const X_CODEX_TURN_STATE_HEADER: &str = "x-codex-turn-state";
 pub const X_CODEX_TURN_METADATA_HEADER: &str = "x-codex-turn-metadata";
+pub const X_CODEX_PARENT_THREAD_ID_HEADER: &str = "x-codex-parent-thread-id";
+pub const X_CODEX_WINDOW_ID_HEADER: &str = "x-codex-window-id";
+pub const X_OPENAI_SUBAGENT_HEADER: &str = "x-openai-subagent";
 pub const X_RESPONSESAPI_INCLUDE_TIMING_METRICS_HEADER: &str =
     "x-responsesapi-include-timing-metrics";
 const RESPONSES_WEBSOCKETS_V2_BETA_HEADER_VALUE: &str = "responses_websockets=2026-02-06";
@@ -137,6 +141,7 @@ pub(crate) const WEBSOCKET_CONNECT_TIMEOUT: Duration =
 struct ModelClientState {
     auth_manager: Option<Arc<AuthManager>>,
     conversation_id: ThreadId,
+    window_generation: AtomicU64,
     provider: ModelProviderInfo,
     auth_env_telemetry: AuthEnvTelemetry,
     session_source: SessionSource,
@@ -274,6 +279,7 @@ impl ModelClient {
             state: Arc::new(ModelClientState {
                 auth_manager,
                 conversation_id,
+                window_generation: AtomicU64::new(0),
                 provider,
                 auth_env_telemetry,
                 session_source,
@@ -303,6 +309,24 @@ impl ModelClient {
         self.state.auth_manager.clone()
     }
 
+    pub(crate) fn set_window_generation(&self, window_generation: u64) {
+        self.state
+            .window_generation
+            .store(window_generation, Ordering::Relaxed);
+        self.store_cached_websocket_session(WebsocketSession::default());
+    }
+
+    pub(crate) fn advance_window_generation(&self) {
+        self.state.window_generation.fetch_add(1, Ordering::Relaxed);
+        self.store_cached_websocket_session(WebsocketSession::default());
+    }
+
+    fn current_window_id(&self) -> String {
+        let conversation_id = self.state.conversation_id;
+        let window_generation = self.state.window_generation.load(Ordering::Relaxed);
+        format!("{conversation_id}:{window_generation}")
+    }
+
     fn take_cached_websocket_session(&self) -> WebsocketSession {
         let mut cached_websocket_session = self
             .state
@@ -401,7 +425,7 @@ impl ModelClient {
             text,
         };
 
-        let mut extra_headers = self.build_subagent_headers();
+        let mut extra_headers = self.build_responses_identity_headers();
         extra_headers.extend(build_conversation_headers(Some(
             self.state.conversation_id.to_string(),
         )));
@@ -461,21 +485,56 @@ impl ModelClient {
 
     fn build_subagent_headers(&self) -> ApiHeaderMap {
         let mut extra_headers = ApiHeaderMap::new();
-        if let SessionSource::SubAgent(sub) = &self.state.session_source {
-            let subagent = match sub {
-                SubAgentSource::Review => "review".to_string(),
-                SubAgentSource::Compact => "compact".to_string(),
-                SubAgentSource::MemoryConsolidation => "memory_consolidation".to_string(),
-                SubAgentSource::ThreadSpawn { .. } => "collab_spawn".to_string(),
-                SubAgentSource::Other(label) => label.clone(),
-            };
-            if let Ok(val) = HeaderValue::from_str(&subagent) {
-                extra_headers.insert("x-openai-subagent", val);
-            }
+        if let Some(subagent) = subagent_header_value(&self.state.session_source)
+            && let Ok(val) = HeaderValue::from_str(&subagent)
+        {
+            extra_headers.insert(X_OPENAI_SUBAGENT_HEADER, val);
         }
         extra_headers
     }
 
+    fn build_responses_identity_headers(&self) -> ApiHeaderMap {
+        let mut extra_headers = self.build_subagent_headers();
+        if let Some(parent_thread_id) = parent_thread_id_header_value(&self.state.session_source)
+            && let Ok(val) = HeaderValue::from_str(&parent_thread_id)
+        {
+            extra_headers.insert(X_CODEX_PARENT_THREAD_ID_HEADER, val);
+        }
+        if let Ok(val) = HeaderValue::from_str(&self.current_window_id()) {
+            extra_headers.insert(X_CODEX_WINDOW_ID_HEADER, val);
+        }
+        extra_headers
+    }
+
+    fn build_ws_client_metadata(
+        &self,
+        turn_metadata_header: Option<&str>,
+    ) -> HashMap<String, String> {
+        let mut client_metadata = HashMap::new();
+        client_metadata.insert(
+            X_CODEX_WINDOW_ID_HEADER.to_string(),
+            self.current_window_id(),
+        );
+        if let Some(subagent) = subagent_header_value(&self.state.session_source) {
+            client_metadata.insert(X_OPENAI_SUBAGENT_HEADER.to_string(), subagent);
+        }
+        if let Some(parent_thread_id) = parent_thread_id_header_value(&self.state.session_source) {
+            client_metadata.insert(
+                X_CODEX_PARENT_THREAD_ID_HEADER.to_string(),
+                parent_thread_id,
+            );
+        }
+        if let Some(turn_metadata_header) = parse_turn_metadata_header(turn_metadata_header)
+            && let Ok(turn_metadata) = turn_metadata_header.to_str()
+        {
+            client_metadata.insert(
+                X_CODEX_TURN_METADATA_HEADER.to_string(),
+                turn_metadata.to_string(),
+            );
+        }
+        client_metadata
+    }
+
     /// Builds request telemetry for unary API calls (e.g., Compact endpoint).
     fn build_request_telemetry(
         session_telemetry: &SessionTelemetry,
@@ -655,6 +714,7 @@ impl ModelClient {
             headers.insert("x-client-request-id", header_value);
         }
         headers.extend(build_conversation_headers(Some(conversation_id)));
+        headers.extend(self.build_responses_identity_headers());
         headers.insert(
             OPENAI_BETA_HEADER,
             HeaderValue::from_static(RESPONSES_WEBSOCKETS_V2_BETA_HEADER_VALUE),
@@ -678,7 +738,7 @@ impl Drop for ModelClientSession {
 }
 
 impl ModelClientSession {
-    fn reset_websocket_session(&mut self) {
+    pub(crate) fn reset_websocket_session(&mut self) {
         self.websocket_session.connection = None;
         self.websocket_session.last_request = None;
         self.websocket_session.last_response_rx = None;
@@ -769,11 +829,15 @@ impl ModelClientSession {
         ApiResponsesOptions {
             conversation_id: Some(conversation_id),
             session_source: Some(self.client.state.session_source.clone()),
-            extra_headers: build_responses_headers(
-                self.client.state.beta_features_header.as_deref(),
-                Some(&self.turn_state),
-                turn_metadata_header.as_ref(),
-            ),
+            extra_headers: {
+                let mut headers = build_responses_headers(
+                    self.client.state.beta_features_header.as_deref(),
+                    Some(&self.turn_state),
+                    turn_metadata_header.as_ref(),
+                );
+                headers.extend(self.client.build_responses_identity_headers());
+                headers
+            },
             compression,
             turn_state: Some(Arc::clone(&self.turn_state)),
         }
@@ -1137,7 +1201,7 @@ impl ModelClientSession {
             )?;
             let mut ws_payload = ResponseCreateWsRequest {
                 client_metadata: response_create_client_metadata(
-                    build_ws_client_metadata(turn_metadata_header),
+                    Some(self.client.build_ws_client_metadata(turn_metadata_header)),
                     request_trace.as_ref(),
                 ),
                 ..ResponseCreateWsRequest::from(&request)
@@ -1370,14 +1434,6 @@ fn parse_turn_metadata_header(turn_metadata_header: Option<&str>) -> Option<Head
     turn_metadata_header.and_then(|value| HeaderValue::from_str(value).ok())
 }
 
-fn build_ws_client_metadata(turn_metadata_header: Option<&str>) -> Option<HashMap<String, String>> {
-    let turn_metadata_header = parse_turn_metadata_header(turn_metadata_header)?;
-    let turn_metadata = turn_metadata_header.to_str().ok()?.to_string();
-    let mut client_metadata = HashMap::new();
-    client_metadata.insert(X_CODEX_TURN_METADATA_HEADER.to_string(), turn_metadata);
-    Some(client_metadata)
-}
-
 /// Builds the extra headers attached to Responses API requests.
 ///
 /// These headers implement Codex-specific conventions:
@@ -1409,6 +1465,34 @@ fn build_responses_headers(
     headers
 }
 
+fn subagent_header_value(session_source: &SessionSource) -> Option<String> {
+    let SessionSource::SubAgent(subagent_source) = session_source else {
+        return None;
+    };
+    match subagent_source {
+        SubAgentSource::Review => Some("review".to_string()),
+        SubAgentSource::Compact => Some("compact".to_string()),
+        SubAgentSource::MemoryConsolidation => Some("memory_consolidation".to_string()),
+        SubAgentSource::ThreadSpawn { .. } => Some("collab_spawn".to_string()),
+        SubAgentSource::Other(label) => Some(label.clone()),
+    }
+}
+
+fn parent_thread_id_header_value(session_source: &SessionSource) -> Option<String> {
+    match session_source {
+        SessionSource::SubAgent(SubAgentSource::ThreadSpawn {
+            parent_thread_id, ..
+        }) => Some(parent_thread_id.to_string()),
+        SessionSource::Cli
+        | SessionSource::VSCode
+        | SessionSource::Exec
+        | SessionSource::Mcp
+        | SessionSource::Custom(_)
+        | SessionSource::SubAgent(_)
+        | SessionSource::Unknown => None,
+    }
+}
+
 fn map_response_stream<S>(
     api_stream: S,
     session_telemetry: SessionTelemetry,

codex-rs/core/src/client_tests.rs

@@ -2,6 +2,10 @@ use super::AuthRequestTelemetryContext;
 use super::ModelClient;
 use super::PendingUnauthorizedRetry;
 use super::UnauthorizedRecoveryExecution;
+use super::X_CODEX_PARENT_THREAD_ID_HEADER;
+use super::X_CODEX_TURN_METADATA_HEADER;
+use super::X_CODEX_WINDOW_ID_HEADER;
+use super::X_OPENAI_SUBAGENT_HEADER;
 use codex_api::api_bridge::CoreAuthProvider;
 use codex_app_server_protocol::AuthMode;
 use codex_model_provider_info::WireApi;
@@ -80,11 +84,49 @@ fn build_subagent_headers_sets_other_subagent_label() {
     )));
     let headers = client.build_subagent_headers();
     let value = headers
-        .get("x-openai-subagent")
+        .get(X_OPENAI_SUBAGENT_HEADER)
         .and_then(|value| value.to_str().ok());
     assert_eq!(value, Some("memory_consolidation"));
 }
 
+#[test]
+fn build_ws_client_metadata_includes_window_lineage_and_turn_metadata() {
+    let parent_thread_id = ThreadId::new();
+    let client = test_model_client(SessionSource::SubAgent(SubAgentSource::ThreadSpawn {
+        parent_thread_id,
+        depth: 2,
+        agent_path: None,
+        agent_nickname: None,
+        agent_role: None,
+    }));
+
+    client.advance_window_generation();
+
+    let client_metadata = client.build_ws_client_metadata(Some(r#"{"turn_id":"turn-123"}"#));
+    let conversation_id = client.state.conversation_id;
+    assert_eq!(
+        client_metadata,
+        std::collections::HashMap::from([
+            (
+                X_CODEX_WINDOW_ID_HEADER.to_string(),
+                format!("{conversation_id}:1"),
+            ),
+            (
+                X_OPENAI_SUBAGENT_HEADER.to_string(),
+                "collab_spawn".to_string(),
+            ),
+            (
+                X_CODEX_PARENT_THREAD_ID_HEADER.to_string(),
+                parent_thread_id.to_string(),
+            ),
+            (
+                X_CODEX_TURN_METADATA_HEADER.to_string(),
+                r#"{"turn_id":"turn-123"}"#.to_string(),
+            ),
+        ])
+    );
+}
+
 #[tokio::test]
 async fn summarize_memories_returns_empty_for_empty_input() {
     let client = test_model_client(SessionSource::Cli);

codex-rs/core/src/codex.rs

@@ -332,6 +332,7 @@ use codex_protocol::config_types::ServiceTier;
 use codex_protocol::config_types::WindowsSandboxLevel;
 use codex_protocol::models::ContentItem;
 use codex_protocol::models::DeveloperInstructions;
+use codex_protocol::models::MessagePhase;
 use codex_protocol::models::ResponseInputItem;
 use codex_protocol::models::ResponseItem;
 use codex_protocol::openai_models::ReasoningEffort as ReasoningEffortConfig;
@@ -1530,6 +1531,17 @@ impl Session {
                 ),
             ),
         };
+        let window_generation = match &initial_history {
+            InitialHistory::Resumed(resumed_history) => u64::try_from(
+                resumed_history
+                    .history
+                    .iter()
+                    .filter(|item| matches!(item, RolloutItem::Compacted(_)))
+                    .count(),
+            )
+            .unwrap_or(u64::MAX),
+            InitialHistory::New | InitialHistory::Forked(_) => 0,
+        };
         let state_builder = match &initial_history {
             InitialHistory::Resumed(resumed) => metadata::builder_from_items(
                 resumed.history.as_slice(),
@@ -1919,6 +1931,9 @@ impl Session {
             ),
             environment: environment_manager.current().await?,
         };
+        services
+            .model_client
+            .set_window_generation(window_generation);
         let js_repl = Arc::new(JsReplHandle::with_node_path(
             config.js_repl_node_path.clone(),
             config.js_repl_node_module_dirs.clone(),
@@ -3513,6 +3528,7 @@ impl Session {
             self.persist_rollout_items(&[RolloutItem::TurnContext(turn_context_item)])
                 .await;
         }
+        self.services.model_client.advance_window_generation();
     }
 
     async fn persist_rollout_response_items(&self, items: &[ResponseItem]) {
@@ -3688,16 +3704,18 @@ impl Session {
                 .serialize_to_text(),
             );
         }
-        let subagents = self
-            .services
-            .agent_control
-            .format_environment_context_subagents(self.conversation_id)
-            .await;
-        contextual_user_sections.push(
-            EnvironmentContext::from_turn_context(turn_context, shell.as_ref())
-                .with_subagents(subagents)
-                .serialize_to_xml(),
-        );
+        if turn_context.config.include_environment_context {
+            let subagents = self
+                .services
+                .agent_control
+                .format_environment_context_subagents(self.conversation_id)
+                .await;
+            contextual_user_sections.push(
+                EnvironmentContext::from_turn_context(turn_context, shell.as_ref())
+                    .with_subagents(subagents)
+                    .serialize_to_xml(),
+            );
+        }
 
         let mut items = Vec::with_capacity(3);
         if let Some(developer_message) =
@@ -5730,16 +5748,20 @@ pub(crate) async fn run_turn(
 
     let model_info = turn_context.model_info.clone();
     let auto_compact_limit = model_info.auto_compact_token_limit().unwrap_or(i64::MAX);
+    let mut prewarmed_client_session = prewarmed_client_session;
     // TODO(ccunningham): Pre-turn compaction runs before context updates and the
     // new user message are recorded. Estimate pending incoming items (context
     // diffs/full reinjection + user input) and trigger compaction preemptively
     // when they would push the thread over the compaction threshold.
-    if run_pre_sampling_compact(&sess, &turn_context)
-        .await
-        .is_err()
-    {
-        error!("Failed to run pre-sampling compact");
-        return None;
+    let pre_sampling_compacted = match run_pre_sampling_compact(&sess, &turn_context).await {
+        Ok(pre_sampling_compacted) => pre_sampling_compacted,
+        Err(_) => {
+            error!("Failed to run pre-sampling compact");
+            return None;
+        }
+    };
+    if pre_sampling_compacted && let Some(mut client_session) = prewarmed_client_session.take() {
+        client_session.reset_websocket_session();
     }
 
     let skills_outcome = Some(turn_context.turn_skills.outcome.as_ref());
@@ -6052,6 +6074,7 @@ pub(crate) async fn run_turn(
                     {
                         return None;
                     }
+                    client_session.reset_websocket_session();
                     continue;
                 }
 
@@ -6212,9 +6235,9 @@ pub(crate) async fn run_turn(
 async fn run_pre_sampling_compact(
     sess: &Arc<Session>,
     turn_context: &Arc<TurnContext>,
-) -> CodexResult<()> {
+) -> CodexResult<bool> {
     let total_usage_tokens_before_compaction = sess.get_total_token_usage().await;
-    maybe_run_previous_model_inline_compact(
+    let mut pre_sampling_compacted = maybe_run_previous_model_inline_compact(
         sess,
         turn_context,
         total_usage_tokens_before_compaction,
@@ -6228,8 +6251,9 @@ async fn run_pre_sampling_compact(
     // Compact if the total usage tokens are greater than the auto compact limit
     if total_usage_tokens >= auto_compact_limit {
         run_auto_compact(sess, turn_context, InitialContextInjection::DoNotInject).await?;
+        pre_sampling_compacted = true;
     }
-    Ok(())
+    Ok(pre_sampling_compacted)
 }
 
 /// Runs pre-sampling compaction against the previous model when switching to a smaller
@@ -7424,6 +7448,25 @@ async fn try_run_sampling_request(
                     cancellation_token: cancellation_token.child_token(),
                 };
 
+                let preempt_for_mailbox_mail = match &item {
+                    ResponseItem::Message { role, phase, .. } => {
+                        role == "assistant" && matches!(phase, Some(MessagePhase::Commentary))
+                    }
+                    ResponseItem::Reasoning { .. } => true,
+                    ResponseItem::LocalShellCall { .. }
+                    | ResponseItem::FunctionCall { .. }
+                    | ResponseItem::ToolSearchCall { .. }
+                    | ResponseItem::FunctionCallOutput { .. }
+                    | ResponseItem::CustomToolCall { .. }
+                    | ResponseItem::CustomToolCallOutput { .. }
+                    | ResponseItem::ToolSearchOutput { .. }
+                    | ResponseItem::WebSearchCall { .. }
+                    | ResponseItem::ImageGenerationCall { .. }
+                    | ResponseItem::GhostSnapshot { .. }
+                    | ResponseItem::Compaction { .. }
+                    | ResponseItem::Other => false,
+                };
+
                 let output_result = handle_output_item_done(&mut ctx, item, previously_active_item)
                     .instrument(handle_responses)
                     .await?;
@@ -7434,6 +7477,13 @@ async fn try_run_sampling_request(
                     last_agent_message = Some(agent_message);
                 }
                 needs_follow_up |= output_result.needs_follow_up;
+                // todo: remove before stabilizing multi-agent v2
+                if preempt_for_mailbox_mail && sess.mailbox_rx.lock().await.has_pending() {
+                    break Ok(SamplingRequestResult {
+                        needs_follow_up: true,
+                        last_agent_message,
+                    });
+                }
             }
             ResponseEvent::OutputItemAdded(item) => {
                 if let Some(turn_item) = handle_non_tool_response_item(

codex-rs/core/src/codex_tests.rs

@@ -283,6 +283,23 @@ fn developer_input_texts(items: &[ResponseItem]) -> Vec<&str> {
         .collect()
 }
 
+fn user_input_texts(items: &[ResponseItem]) -> Vec<&str> {
+    items
+        .iter()
+        .filter_map(|item| match item {
+            ResponseItem::Message { role, content, .. } if role == "user" => {
+                Some(content.as_slice())
+            }
+            _ => None,
+        })
+        .flat_map(|content| content.iter())
+        .filter_map(|item| match item {
+            ContentItem::InputText { text } => Some(text.as_str()),
+            _ => None,
+        })
+        .collect()
+}
+
 fn test_tool_runtime(session: Arc<Session>, turn_context: Arc<TurnContext>) -> ToolCallRuntime {
     let router = Arc::new(ToolRouter::from_config(
         &turn_context.tools_config,
@@ -3774,17 +3791,9 @@ async fn build_settings_update_items_emits_environment_item_for_network_changes(
         .build_settings_update_items(Some(&reference_context_item), &current_context)
         .await;
 
-    let environment_update = update_items
-        .iter()
-        .find_map(|item| match item {
-            ResponseItem::Message { role, content, .. } if role == "user" => {
-                let [ContentItem::InputText { text }] = content.as_slice() else {
-                    return None;
-                };
-                text.contains("<environment_context>").then_some(text)
-            }
-            _ => None,
-        })
+    let environment_update = user_input_texts(&update_items)
+        .into_iter()
+        .find(|text| text.contains("<environment_context>"))
         .expect("environment update item should be emitted");
     assert!(environment_update.contains("<network enabled=\"true\">"));
     assert!(environment_update.contains("<allowed>api.example.com</allowed>"));
@@ -3809,22 +3818,43 @@ async fn build_settings_update_items_emits_environment_item_for_time_changes() {
         .build_settings_update_items(Some(&reference_context_item), &current_context)
         .await;
 
-    let environment_update = update_items
-        .iter()
-        .find_map(|item| match item {
-            ResponseItem::Message { role, content, .. } if role == "user" => {
-                let [ContentItem::InputText { text }] = content.as_slice() else {
-                    return None;
-                };
-                text.contains("<environment_context>").then_some(text)
-            }
-            _ => None,
-        })
+    let environment_update = user_input_texts(&update_items)
+        .into_iter()
+        .find(|text| text.contains("<environment_context>"))
         .expect("environment update item should be emitted");
     assert!(environment_update.contains("<current_date>2026-02-27</current_date>"));
     assert!(environment_update.contains("<timezone>Europe/Berlin</timezone>"));
 }
 
+#[tokio::test]
+async fn build_settings_update_items_omits_environment_item_when_disabled() {
+    let (session, previous_context) = make_session_and_context().await;
+    let previous_context = Arc::new(previous_context);
+    let mut current_context = previous_context
+        .with_model(
+            previous_context.model_info.slug.clone(),
+            &session.services.models_manager,
+        )
+        .await;
+    let mut config = (*current_context.config).clone();
+    config.include_environment_context = false;
+    current_context.config = Arc::new(config);
+    current_context.current_date = Some("2026-02-27".to_string());
+
+    let reference_context_item = previous_context.to_turn_context_item();
+    let update_items = session
+        .build_settings_update_items(Some(&reference_context_item), &current_context)
+        .await;
+
+    let user_texts = user_input_texts(&update_items);
+    assert!(
+        !user_texts
+            .iter()
+            .any(|text| text.contains("<environment_context>")),
+        "did not expect environment context updates when disabled, got {user_texts:?}"
+    );
+}
+
 #[tokio::test]
 async fn build_settings_update_items_emits_realtime_start_when_session_becomes_live() {
     let (session, previous_context) = make_session_and_context().await;

codex-rs/core/src/compact.rs

@@ -220,6 +220,7 @@ async fn run_compact_task_inner(
     };
     sess.replace_compacted_history(new_history, reference_context_item, compacted_item)
         .await;
+    client_session.reset_websocket_session();
     sess.recompute_token_usage(&turn_context).await;
 
     sess.emit_turn_item_completed(&turn_context, compaction_item)

codex-rs/core/src/config/config_tests.rs

@@ -4495,6 +4495,7 @@ fn test_precedence_fixture_with_o3_profile() -> std::io::Result<()> {
             guardian_developer_instructions: None,
             include_permissions_instructions: true,
             include_apps_instructions: true,
+            include_environment_context: true,
             compact_prompt: None,
             commit_attribution: None,
             forced_chatgpt_workspace_id: None,
@@ -4639,6 +4640,7 @@ fn test_precedence_fixture_with_gpt3_profile() -> std::io::Result<()> {
         guardian_developer_instructions: None,
         include_permissions_instructions: true,
         include_apps_instructions: true,
+        include_environment_context: true,
         compact_prompt: None,
         commit_attribution: None,
         forced_chatgpt_workspace_id: None,
@@ -4781,6 +4783,7 @@ fn test_precedence_fixture_with_zdr_profile() -> std::io::Result<()> {
         guardian_developer_instructions: None,
         include_permissions_instructions: true,
         include_apps_instructions: true,
+        include_environment_context: true,
         compact_prompt: None,
         commit_attribution: None,
         forced_chatgpt_workspace_id: None,
@@ -4909,6 +4912,7 @@ fn test_precedence_fixture_with_gpt5_profile() -> std::io::Result<()> {
         guardian_developer_instructions: None,
         include_permissions_instructions: true,
         include_apps_instructions: true,
+        include_environment_context: true,
         compact_prompt: None,
         commit_attribution: None,
         forced_chatgpt_workspace_id: None,
@@ -5799,10 +5803,12 @@ async fn prompt_instruction_blocks_can_be_disabled_from_config_and_profiles() ->
         codex_home.path().join(CONFIG_TOML_FILE),
         r#"include_permissions_instructions = false
 include_apps_instructions = false
+include_environment_context = false
 profile = "chatty"
 
 [profiles.chatty]
 include_permissions_instructions = true
+include_environment_context = true
 "#,
     )?;
 
@@ -5814,6 +5820,7 @@ include_permissions_instructions = true
 
     assert!(config.include_permissions_instructions);
     assert!(!config.include_apps_instructions);
+    assert!(config.include_environment_context);
     Ok(())
 }
 

codex-rs/core/src/config/mod.rs

@@ -286,6 +286,9 @@ pub struct Config {
     /// Whether to inject the `<apps_instructions>` developer block.
     pub include_apps_instructions: bool,
 
+    /// Whether to inject the `<environment_context>` user block.
+    pub include_environment_context: bool,
+
     /// Compact prompt override.
     pub compact_prompt: Option<String>,
 
@@ -1195,6 +1198,9 @@ pub struct ConfigToml {
     /// Whether to inject the `<apps_instructions>` developer block.
     pub include_apps_instructions: Option<bool>,
 
+    /// Whether to inject the `<environment_context>` user block.
+    pub include_environment_context: Option<bool>,
+
     /// Optional path to a file containing model instructions that will override
     /// the built-in instructions for the selected model. Users are STRONGLY
     /// DISCOURAGED from using this field, as deviating from the instructions
@@ -2472,6 +2478,10 @@ impl Config {
             .include_apps_instructions
             .or(cfg.include_apps_instructions)
             .unwrap_or(true);
+        let include_environment_context = config_profile
+            .include_environment_context
+            .or(cfg.include_environment_context)
+            .unwrap_or(true);
         let guardian_developer_instructions = guardian_developer_instructions_from_requirements(
             config_layer_stack.requirements_toml(),
         );
@@ -2640,6 +2650,7 @@ impl Config {
             commit_attribution,
             include_permissions_instructions,
             include_apps_instructions,
+            include_environment_context,
             // The config.toml omits "_mode" because it's a config file. However, "_mode"
             // is important in code to differentiate the mode from the store implementation.
             cli_auth_credentials_store_mode: cfg.cli_auth_credentials_store.unwrap_or_default(),

codex-rs/core/src/config/profile.rs

@@ -51,6 +51,7 @@ pub struct ConfigProfile {
     pub include_apply_patch_tool: Option<bool>,
     pub include_permissions_instructions: Option<bool>,
     pub include_apps_instructions: Option<bool>,
+    pub include_environment_context: Option<bool>,
     pub experimental_use_unified_exec_tool: Option<bool>,
     pub experimental_use_freeform_apply_patch: Option<bool>,
     pub tools_view_image: Option<bool>,

codex-rs/core/src/context_manager/updates.rs

@@ -16,6 +16,10 @@ fn build_environment_update_item(
     next: &TurnContext,
     shell: &Shell,
 ) -> Option<ResponseItem> {
+    if !next.config.include_environment_context {
+        return None;
+    }
+
     let prev = previous?;
     let prev_context = EnvironmentContext::from_turn_context_item(prev, shell);
     let next_context = EnvironmentContext::from_turn_context(next, shell);

codex-rs/core/src/tools/handlers/multi_agents_v2/spawn.rs

@@ -6,11 +6,16 @@ use crate::agent::next_thread_spawn_depth;
 use crate::agent::role::DEFAULT_ROLE_NAME;
 use crate::agent::role::apply_role_to_config;
 use codex_protocol::AgentPath;
+use codex_protocol::models::DeveloperInstructions;
 use codex_protocol::protocol::InterAgentCommunication;
 use codex_protocol::protocol::Op;
 
 pub(crate) struct Handler;
 
+pub(crate) const SPAWN_AGENT_DEVELOPER_INSTRUCTIONS: &str = r#"<spawned_agent_context>
+You are a newly spawned agent in a team of agents collaborating to complete a task. You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents. You are responsible for returning the response to your assigned task in the final channel. When you give your response, the contents of your response in the final channel will be immediately delivered back to your parent agent. The prior conversation history was forked from your parent agent. Treat the next user message as your assigned task, and use the forked history only as background context.
+</spawned_agent_context>"#;
+
 impl ToolHandler for Handler {
     type Output = SpawnAgentResult;
 
@@ -78,6 +83,17 @@ impl ToolHandler for Handler {
             .map_err(FunctionCallError::RespondToModel)?;
         apply_spawn_agent_runtime_overrides(&mut config, turn.as_ref())?;
         apply_spawn_agent_overrides(&mut config, child_depth);
+        config.developer_instructions = Some(
+            if let Some(existing_instructions) = config.developer_instructions.take() {
+                DeveloperInstructions::new(existing_instructions)
+                    .concat(DeveloperInstructions::new(
+                        SPAWN_AGENT_DEVELOPER_INSTRUCTIONS,
+                    ))
+                    .into_text()
+            } else {
+                DeveloperInstructions::new(SPAWN_AGENT_DEVELOPER_INSTRUCTIONS).into_text()
+            },
+        );
 
         let spawn_source = thread_spawn_source(
             session.conversation_id,

codex-rs/core/tests/responses_headers.rs

@@ -129,10 +129,16 @@ async fn responses_stream_includes_subagent_header_on_review() {
     }
 
     let request = request_recorder.single_request();
+    let expected_window_id = format!("{conversation_id}:0");
     assert_eq!(
         request.header("x-openai-subagent").as_deref(),
         Some("review")
     );
+    assert_eq!(
+        request.header("x-codex-window-id").as_deref(),
+        Some(expected_window_id.as_str())
+    );
+    assert_eq!(request.header("x-codex-parent-thread-id"), None);
     assert_eq!(request.header("x-codex-sandbox"), None);
 }
 

codex-rs/core/tests/suite/client.rs

@@ -195,23 +195,28 @@ mv tokens.next tokens.txt
 
         #[cfg(windows)]
         let (command, args) = {
-            let script_path = tempdir.path().join("print-token.ps1");
+            let script_path = tempdir.path().join("print-token.cmd");
             std::fs::write(
                 &script_path,
-                r#"$lines = @(Get-Content -Path tokens.txt)
-if ($lines.Count -eq 0) { exit 1 }
-Write-Output $lines[0]
-$lines | Select-Object -Skip 1 | Set-Content -Path tokens.txt
+                r#"@echo off
+setlocal EnableExtensions DisableDelayedExpansion
+
+set "first_line="
+<tokens.txt set /p first_line=
+if not defined first_line exit /b 1
+
+echo(%first_line%
+more +1 tokens.txt > tokens.next
+move /y tokens.next tokens.txt >nul
 "#,
             )?;
             (
-                "powershell.exe".to_string(),
+                "cmd.exe".to_string(),
                 vec![
-                    "-NoProfile".to_string(),
-                    "-ExecutionPolicy".to_string(),
-                    "Bypass".to_string(),
-                    "-File".to_string(),
-                    ".\\print-token.ps1".to_string(),
+                    "/D".to_string(),
+                    "/Q".to_string(),
+                    "/C".to_string(),
+                    ".\\print-token.cmd".to_string(),
                 ],
             )
         };
@@ -227,7 +232,8 @@ $lines | Select-Object -Skip 1 | Set-Content -Path tokens.txt
         ModelProviderAuthInfo {
             command: self.command.clone(),
             args: self.args.clone(),
-            timeout_ms: non_zero_u64(/*value*/ 1_000),
+            // Match the provider-auth default to avoid brittle shell-startup timing in CI.
+            timeout_ms: non_zero_u64(/*value*/ 5_000),
             refresh_interval_ms: 60_000,
             cwd: match codex_utils_absolute_path::AbsolutePathBuf::try_from(self.tempdir.path()) {
                 Ok(cwd) => cwd,
@@ -1339,6 +1345,45 @@ async fn omits_apps_guidance_when_configured_off() {
     );
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn omits_environment_context_when_configured_off() {
+    let server = MockServer::start().await;
+    let resp_mock = mount_sse_once(
+        &server,
+        sse(vec![ev_response_created("resp1"), ev_completed("resp1")]),
+    )
+    .await;
+
+    let mut builder = test_codex().with_config(|config| {
+        config.include_environment_context = false;
+    });
+    let codex = builder
+        .build(&server)
+        .await
+        .expect("create new conversation")
+        .codex;
+
+    codex
+        .submit(Op::UserInput {
+            items: vec![UserInput::Text {
+                text: "hello".into(),
+                text_elements: Vec::new(),
+            }],
+            final_output_json_schema: None,
+        })
+        .await
+        .unwrap();
+
+    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TurnComplete(_))).await;
+
+    let request = resp_mock.single_request();
+    assert!(
+        !message_input_text_contains(&request, "user", "<environment_context>"),
+        "did not expect environment context when include_environment_context = false, got {:?}",
+        request.body_json()["input"]
+    );
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn skills_append_to_developer_message() {
     skip_if_no_network!();

codex-rs/core/tests/suite/mod.rs

@@ -154,3 +154,4 @@ mod user_shell_cmd;
 mod view_image;
 mod web_search;
 mod websocket_fallback;
+mod window_headers;

codex-rs/core/tests/suite/pending_input.rs

@@ -1,17 +1,31 @@
+use std::sync::Arc;
+
+use codex_core::CodexThread;
+use codex_protocol::AgentPath;
+use codex_protocol::items::TurnItem;
 use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::InterAgentCommunication;
 use codex_protocol::protocol::Op;
 use codex_protocol::user_input::UserInput;
+use core_test_support::context_snapshot;
+use core_test_support::context_snapshot::ContextSnapshotOptions;
 use core_test_support::responses;
 use core_test_support::responses::ev_completed;
+use core_test_support::responses::ev_function_call;
 use core_test_support::responses::ev_message_item_added;
 use core_test_support::responses::ev_output_text_delta;
+use core_test_support::responses::ev_reasoning_item;
+use core_test_support::responses::ev_reasoning_item_added;
 use core_test_support::responses::ev_response_created;
 use core_test_support::streaming_sse::StreamingSseChunk;
+use core_test_support::streaming_sse::StreamingSseServer;
 use core_test_support::streaming_sse::start_streaming_sse_server;
 use core_test_support::test_codex::test_codex;
 use core_test_support::wait_for_event;
 use pretty_assertions::assert_eq;
 use serde_json::Value;
+use serde_json::from_slice;
+use serde_json::json;
 use tokio::sync::oneshot;
 
 fn ev_message_item_done(id: &str, text: &str) -> Value {
@@ -44,6 +58,115 @@ fn message_input_texts(body: &Value, role: &str) -> Vec<String> {
         .collect()
 }
 
+fn chunk(event: Value) -> StreamingSseChunk {
+    StreamingSseChunk {
+        gate: None,
+        body: responses::sse(vec![event]),
+    }
+}
+
+fn gated_chunk(gate: oneshot::Receiver<()>, events: Vec<Value>) -> StreamingSseChunk {
+    StreamingSseChunk {
+        gate: Some(gate),
+        body: responses::sse(events),
+    }
+}
+
+fn response_completed_chunks(response_id: &str) -> Vec<StreamingSseChunk> {
+    vec![
+        chunk(ev_response_created(response_id)),
+        chunk(ev_completed(response_id)),
+    ]
+}
+
+async fn build_codex(server: &StreamingSseServer) -> Arc<CodexThread> {
+    test_codex()
+        .with_model("gpt-5.1")
+        .build_with_streaming_server(server)
+        .await
+        .unwrap_or_else(|err| panic!("build streaming Codex test session: {err}"))
+        .codex
+}
+
+async fn submit_user_input(codex: &CodexThread, text: &str) {
+    codex
+        .submit(Op::UserInput {
+            items: vec![UserInput::Text {
+                text: text.to_string(),
+                text_elements: Vec::new(),
+            }],
+            final_output_json_schema: None,
+        })
+        .await
+        .unwrap_or_else(|err| panic!("submit user input: {err}"));
+}
+
+async fn submit_queue_only_agent_mail(codex: &CodexThread, text: &str) {
+    codex
+        .submit(Op::InterAgentCommunication {
+            communication: InterAgentCommunication::new(
+                AgentPath::try_from("/root/worker")
+                    .unwrap_or_else(|err| panic!("worker path should parse: {err}")),
+                AgentPath::root(),
+                Vec::new(),
+                text.to_string(),
+                /*trigger_turn*/ false,
+            ),
+        })
+        .await
+        .unwrap_or_else(|err| panic!("submit queue-only agent mail: {err}"));
+}
+
+async fn wait_for_reasoning_item_started(codex: &CodexThread) {
+    wait_for_event(codex, |event| {
+        matches!(
+            event,
+            EventMsg::ItemStarted(item_started)
+                if matches!(&item_started.item, TurnItem::Reasoning(_))
+        )
+    })
+    .await;
+}
+
+async fn wait_for_agent_message(codex: &CodexThread, text: &str) {
+    let final_message = wait_for_event(
+        codex,
+        |event| matches!(event, EventMsg::AgentMessage(message) if message.message == text),
+    )
+    .await;
+    assert!(matches!(final_message, EventMsg::AgentMessage(_)));
+}
+
+async fn wait_for_turn_complete(codex: &CodexThread) {
+    wait_for_event(codex, |event| matches!(event, EventMsg::TurnComplete(_))).await;
+}
+
+fn assert_two_responses_input_snapshot(snapshot_name: &str, requests: &[Vec<u8>]) {
+    assert_eq!(requests.len(), 2);
+    let options = ContextSnapshotOptions::default().strip_capability_instructions();
+    let first: Value =
+        from_slice(&requests[0]).unwrap_or_else(|err| panic!("parse first request: {err}"));
+    let second: Value =
+        from_slice(&requests[1]).unwrap_or_else(|err| panic!("parse second request: {err}"));
+    let first_items = first["input"]
+        .as_array()
+        .unwrap_or_else(|| panic!("first request input"))
+        .clone();
+    let second_items = second["input"]
+        .as_array()
+        .unwrap_or_else(|| panic!("second request input"))
+        .clone();
+    let snapshot = context_snapshot::format_labeled_items_snapshot(
+        "/responses POST bodies (input only, redacted like other suite snapshots)",
+        &[
+            ("First request", first_items.as_slice()),
+            ("Second request", second_items.as_slice()),
+        ],
+        &options,
+    );
+    insta::assert_snapshot!(snapshot_name, snapshot);
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 #[ignore = "TODO(aibrahim): flaky"]
 async fn injected_user_input_triggers_follow_up_request_with_deltas() {
@@ -144,3 +267,162 @@ async fn injected_user_input_triggers_follow_up_request_with_deltas() {
 
     server.shutdown().await;
 }
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn queued_inter_agent_mail_triggers_follow_up_after_reasoning_item() {
+    let (gate_reasoning_done_tx, gate_reasoning_done_rx) = oneshot::channel();
+
+    let first_chunks = vec![
+        chunk(ev_response_created("resp-1")),
+        chunk(ev_reasoning_item_added("reason-1", &["thinking"])),
+        gated_chunk(
+            gate_reasoning_done_rx,
+            vec![
+                ev_reasoning_item("reason-1", &["thinking"], &[]),
+                ev_function_call(
+                    "call-stale",
+                    "shell",
+                    r#"{"command":"echo stale tool call"}"#,
+                ),
+                ev_message_item_added("msg-stale", ""),
+                ev_output_text_delta("stale final"),
+                ev_message_item_done("msg-stale", "stale final"),
+                ev_completed("resp-1"),
+            ],
+        ),
+    ];
+
+    let (server, _completions) =
+        start_streaming_sse_server(vec![first_chunks, response_completed_chunks("resp-2")]).await;
+
+    let codex = build_codex(&server).await;
+
+    submit_user_input(&codex, "first prompt").await;
+
+    wait_for_reasoning_item_started(&codex).await;
+
+    submit_queue_only_agent_mail(&codex, "queued child update").await;
+
+    let _ = gate_reasoning_done_tx.send(());
+
+    wait_for_turn_complete(&codex).await;
+
+    let requests = server.requests().await;
+    assert_two_responses_input_snapshot("pending_input_queued_mail_after_reasoning", &requests);
+
+    server.shutdown().await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn queued_inter_agent_mail_triggers_follow_up_after_commentary_message_item() {
+    let (gate_message_done_tx, gate_message_done_rx) = oneshot::channel();
+
+    let first_chunks = vec![
+        chunk(ev_response_created("resp-1")),
+        chunk(ev_message_item_added("msg-1", "")),
+        gated_chunk(
+            gate_message_done_rx,
+            vec![
+                ev_output_text_delta("first answer"),
+                json!({
+                    "type": "response.output_item.done",
+                    "item": {
+                        "type": "message",
+                        "role": "assistant",
+                        "id": "msg-1",
+                        "content": [{"type": "output_text", "text": "first answer"}],
+                        "phase": "commentary",
+                    }
+                }),
+                ev_function_call(
+                    "call-stale",
+                    "shell",
+                    r#"{"command":"echo stale tool call"}"#,
+                ),
+                ev_message_item_added("msg-stale", ""),
+                ev_output_text_delta("stale final"),
+                ev_message_item_done("msg-stale", "stale final"),
+                ev_completed("resp-1"),
+            ],
+        ),
+    ];
+
+    let (server, _completions) =
+        start_streaming_sse_server(vec![first_chunks, response_completed_chunks("resp-2")]).await;
+
+    let codex = build_codex(&server).await;
+
+    submit_user_input(&codex, "first prompt").await;
+
+    wait_for_event(&codex, |event| {
+        matches!(
+            event,
+            EventMsg::ItemStarted(item_started)
+                if matches!(&item_started.item, TurnItem::AgentMessage(_))
+        )
+    })
+    .await;
+
+    submit_queue_only_agent_mail(&codex, "queued child update").await;
+
+    let _ = gate_message_done_tx.send(());
+
+    wait_for_agent_message(&codex, "first answer").await;
+
+    wait_for_turn_complete(&codex).await;
+
+    let requests = server.requests().await;
+    assert_two_responses_input_snapshot("pending_input_queued_mail_after_commentary", &requests);
+
+    server.shutdown().await;
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn user_input_does_not_preempt_after_reasoning_item() {
+    let (gate_reasoning_done_tx, gate_reasoning_done_rx) = oneshot::channel();
+
+    let first_chunks = vec![
+        chunk(ev_response_created("resp-1")),
+        chunk(ev_reasoning_item_added("reason-1", &["thinking"])),
+        gated_chunk(
+            gate_reasoning_done_rx,
+            vec![
+                ev_reasoning_item("reason-1", &["thinking"], &[]),
+                ev_function_call(
+                    "call-preserved",
+                    "shell",
+                    r#"{"command":"echo preserved tool call"}"#,
+                ),
+                ev_message_item_added("msg-1", ""),
+                ev_output_text_delta("first answer"),
+                ev_message_item_done("msg-1", "first answer"),
+                ev_completed("resp-1"),
+            ],
+        ),
+    ];
+
+    let (server, _completions) =
+        start_streaming_sse_server(vec![first_chunks, response_completed_chunks("resp-2")]).await;
+
+    let codex = build_codex(&server).await;
+
+    submit_user_input(&codex, "first prompt").await;
+
+    wait_for_reasoning_item_started(&codex).await;
+
+    submit_user_input(&codex, "second prompt").await;
+
+    let _ = gate_reasoning_done_tx.send(());
+
+    wait_for_agent_message(&codex, "first answer").await;
+
+    wait_for_turn_complete(&codex).await;
+
+    let requests = server.requests().await;
+    assert_two_responses_input_snapshot(
+        "pending_input_user_input_no_preempt_after_reasoning",
+        &requests,
+    );
+
+    server.shutdown().await;
+}

codex-rs/core/tests/suite/snapshots/all__suite__pending_input__pending_input_queued_mail_after_commentary.snap

@@ -0,0 +1,17 @@
+---
+source: core/tests/suite/pending_input.rs
+expression: snapshot
+---
+Scenario: /responses POST bodies (input only, redacted like other suite snapshots)
+
+## First request
+00:message/developer:<PERMISSIONS_INSTRUCTIONS>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:first prompt
+
+## Second request
+00:message/developer:<PERMISSIONS_INSTRUCTIONS>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:first prompt
+03:message/assistant:first answer
+04:message/assistant:{"author":"/root/worker","recipient":"/root","other_recipients":[],"content":"queued child update","trigger_turn":false}

codex-rs/core/tests/suite/snapshots/all__suite__pending_input__pending_input_queued_mail_after_reasoning.snap

@@ -0,0 +1,17 @@
+---
+source: core/tests/suite/pending_input.rs
+expression: snapshot
+---
+Scenario: /responses POST bodies (input only, redacted like other suite snapshots)
+
+## First request
+00:message/developer:<PERMISSIONS_INSTRUCTIONS>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:first prompt
+
+## Second request
+00:message/developer:<PERMISSIONS_INSTRUCTIONS>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:first prompt
+03:reasoning:summary=thinking:encrypted=true
+04:message/assistant:{"author":"/root/worker","recipient":"/root","other_recipients":[],"content":"queued child update","trigger_turn":false}

codex-rs/core/tests/suite/snapshots/all__suite__pending_input__pending_input_user_input_no_preempt_after_reasoning.snap

@@ -0,0 +1,20 @@
+---
+source: core/tests/suite/pending_input.rs
+expression: snapshot
+---
+Scenario: /responses POST bodies (input only, redacted like other suite snapshots)
+
+## First request
+00:message/developer:<PERMISSIONS_INSTRUCTIONS>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:first prompt
+
+## Second request
+00:message/developer:<PERMISSIONS_INSTRUCTIONS>
+01:message/user:<ENVIRONMENT_CONTEXT:cwd=<CWD>>
+02:message/user:first prompt
+03:reasoning:summary=thinking:encrypted=true
+04:function_call/shell
+05:message/assistant:first answer
+06:function_call_output:failed to parse function arguments: invalid type: string "echo preserved tool call", expected a sequence at line 1 column 37
+07:message/user:second prompt

codex-rs/core/tests/suite/subagent_notifications.rs

@@ -35,6 +35,7 @@ const REQUESTED_MODEL: &str = "gpt-5.1";
 const REQUESTED_REASONING_EFFORT: ReasoningEffort = ReasoningEffort::Low;
 const ROLE_MODEL: &str = "gpt-5.1-codex-max";
 const ROLE_REASONING_EFFORT: ReasoningEffort = ReasoningEffort::High;
+const SPAWNED_AGENT_DEVELOPER_INSTRUCTIONS: &str = "You are a newly spawned agent in a team of agents collaborating to complete a task. You can spawn sub-agents to handle subtasks, and those sub-agents can spawn their own sub-agents. You are responsible for returning the response to your assigned task in the final channel. When you give your response, the contents of your response in the final channel will be immediately delivered back to your parent agent. The prior conversation history was forked from your parent agent. Treat the next user message as your assigned task, and use the forked history only as background context.";
 
 fn body_contains(req: &wiremock::Request, text: &str) -> bool {
     let is_zstd = req
@@ -413,6 +414,99 @@ async fn spawn_agent_requested_model_and_reasoning_override_inherited_settings_w
     Ok(())
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn spawned_multi_agent_v2_child_receives_xml_tagged_developer_context() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let spawn_args = serde_json::to_string(&json!({
+        "message": CHILD_PROMPT,
+        "task_name": "worker",
+    }))?;
+    mount_sse_once_match(
+        &server,
+        |req: &wiremock::Request| body_contains(req, TURN_1_PROMPT),
+        sse(vec![
+            ev_response_created("resp-turn1-1"),
+            ev_function_call(SPAWN_CALL_ID, "spawn_agent", &spawn_args),
+            ev_completed("resp-turn1-1"),
+        ]),
+    )
+    .await;
+
+    let _child_request_log = mount_sse_once_match(
+        &server,
+        |req: &wiremock::Request| {
+            body_contains(req, CHILD_PROMPT) && !body_contains(req, SPAWN_CALL_ID)
+        },
+        sse(vec![
+            ev_response_created("resp-child-1"),
+            ev_completed("resp-child-1"),
+        ]),
+    )
+    .await;
+
+    let _turn1_followup = mount_sse_once_match(
+        &server,
+        |req: &wiremock::Request| body_contains(req, SPAWN_CALL_ID),
+        sse(vec![
+            ev_response_created("resp-turn1-2"),
+            ev_assistant_message("msg-turn1-2", "parent done"),
+            ev_completed("resp-turn1-2"),
+        ]),
+    )
+    .await;
+
+    let mut builder = test_codex().with_config(|config| {
+        config
+            .features
+            .enable(Feature::Collab)
+            .expect("test config should allow feature update");
+        config
+            .features
+            .enable(Feature::MultiAgentV2)
+            .expect("test config should allow feature update");
+        config.developer_instructions = Some("Parent developer instructions.".to_string());
+    });
+    let test = builder.build(&server).await?;
+
+    test.submit_turn(TURN_1_PROMPT).await?;
+
+    let deadline = Instant::now() + Duration::from_secs(2);
+    let child_request = loop {
+        if let Some(request) = server
+            .received_requests()
+            .await
+            .unwrap_or_default()
+            .into_iter()
+            .find(|request| {
+                body_contains(request, CHILD_PROMPT)
+                    && body_contains(request, "<spawned_agent_context>")
+                    && body_contains(request, SPAWNED_AGENT_DEVELOPER_INSTRUCTIONS)
+                    && !body_contains(request, SPAWN_CALL_ID)
+            })
+        {
+            break request;
+        }
+        if Instant::now() >= deadline {
+            anyhow::bail!("timed out waiting for spawned child request with developer context");
+        }
+        sleep(Duration::from_millis(10)).await;
+    };
+    assert!(body_contains(
+        &child_request,
+        "Parent developer instructions."
+    ));
+    assert!(body_contains(&child_request, "<spawned_agent_context>"));
+    assert!(body_contains(
+        &child_request,
+        SPAWNED_AGENT_DEVELOPER_INSTRUCTIONS
+    ));
+    assert!(body_contains(&child_request, CHILD_PROMPT));
+
+    Ok(())
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn spawn_agent_role_overrides_requested_model_and_reasoning_settings() -> Result<()> {
     skip_if_no_network!(Ok(()));

codex-rs/core/tests/suite/window_headers.rs

@@ -0,0 +1,146 @@
+#![allow(clippy::expect_used)]
+
+use super::compact::COMPACT_WARNING_MESSAGE;
+use anyhow::Result;
+use codex_core::CodexThread;
+use codex_core::compact::SUMMARIZATION_PROMPT;
+use codex_protocol::protocol::EventMsg;
+use codex_protocol::protocol::Op;
+use codex_protocol::protocol::WarningEvent;
+use codex_protocol::user_input::UserInput;
+use core_test_support::responses::ResponsesRequest;
+use core_test_support::responses::ev_assistant_message;
+use core_test_support::responses::ev_completed;
+use core_test_support::responses::mount_sse_sequence;
+use core_test_support::responses::sse;
+use core_test_support::responses::start_mock_server;
+use core_test_support::skip_if_no_network;
+use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
+use pretty_assertions::assert_eq;
+use std::sync::Arc;
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn window_id_advances_after_compact_persists_on_resume_and_resets_on_fork() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let request_log = mount_sse_sequence(
+        &server,
+        vec![
+            sse(vec![
+                ev_assistant_message("msg-1", "first reply"),
+                ev_completed("resp-1"),
+            ]),
+            sse(vec![
+                ev_assistant_message("msg-2", "summary"),
+                ev_completed("resp-2"),
+            ]),
+            sse(vec![ev_completed("resp-3")]),
+            sse(vec![ev_completed("resp-4")]),
+            sse(vec![ev_completed("resp-5")]),
+        ],
+    )
+    .await;
+
+    let mut builder = test_codex().with_config(|config| {
+        config.model_provider.name = "Non-OpenAI Model provider".to_string();
+        config.compact_prompt = Some(SUMMARIZATION_PROMPT.to_string());
+    });
+    let initial = builder.build(&server).await?;
+    let initial_thread = Arc::clone(&initial.codex);
+    let rollout_path = initial
+        .session_configured
+        .rollout_path
+        .clone()
+        .expect("rollout path");
+
+    submit_user_turn(&initial_thread, "before compact").await?;
+    submit_compact_turn(&initial_thread).await?;
+    submit_user_turn(&initial_thread, "after compact").await?;
+    shutdown_thread(&initial_thread).await?;
+
+    let resumed = builder
+        .resume(&server, initial.home.clone(), rollout_path.clone())
+        .await?;
+    submit_user_turn(&resumed.codex, "after resume").await?;
+    shutdown_thread(&resumed.codex).await?;
+
+    let forked = resumed
+        .thread_manager
+        .fork_thread(
+            /*snapshot*/ 0usize,
+            resumed.config.clone(),
+            rollout_path,
+            /*persist_extended_history*/ false,
+            /*parent_trace*/ None,
+        )
+        .await?;
+    submit_user_turn(&forked.thread, "after fork").await?;
+    shutdown_thread(&forked.thread).await?;
+
+    let requests = request_log.requests();
+    assert_eq!(requests.len(), 5, "expected five model requests");
+
+    let (initial_thread_id, first_generation) = window_id_parts(&requests[0]);
+    let (compact_thread_id, compact_generation) = window_id_parts(&requests[1]);
+    let (after_compact_thread_id, after_compact_generation) = window_id_parts(&requests[2]);
+    let (after_resume_thread_id, after_resume_generation) = window_id_parts(&requests[3]);
+    let (after_fork_thread_id, after_fork_generation) = window_id_parts(&requests[4]);
+
+    assert_eq!(first_generation, 0);
+    assert_eq!(compact_thread_id, initial_thread_id);
+    assert_eq!(compact_generation, 0);
+    assert_eq!(after_compact_thread_id, initial_thread_id);
+    assert_eq!(after_compact_generation, 1);
+    assert_eq!(after_resume_thread_id, initial_thread_id);
+    assert_eq!(after_resume_generation, 1);
+    assert_ne!(after_fork_thread_id, initial_thread_id);
+    assert_eq!(after_fork_generation, 0);
+
+    Ok(())
+}
+
+async fn submit_user_turn(codex: &Arc<CodexThread>, text: &str) -> Result<()> {
+    codex
+        .submit(Op::UserInput {
+            items: vec![UserInput::Text {
+                text: text.to_string(),
+                text_elements: Vec::new(),
+            }],
+            final_output_json_schema: None,
+        })
+        .await?;
+    wait_for_event(codex, |event| matches!(event, EventMsg::TurnComplete(_))).await;
+    Ok(())
+}
+
+async fn submit_compact_turn(codex: &Arc<CodexThread>) -> Result<()> {
+    codex.submit(Op::Compact).await?;
+    let warning_event = wait_for_event(codex, |event| matches!(event, EventMsg::Warning(_))).await;
+    let EventMsg::Warning(WarningEvent { message }) = warning_event else {
+        panic!("expected warning event after compact");
+    };
+    assert_eq!(message, COMPACT_WARNING_MESSAGE);
+    wait_for_event(codex, |event| matches!(event, EventMsg::TurnComplete(_))).await;
+    Ok(())
+}
+
+async fn shutdown_thread(codex: &Arc<CodexThread>) -> Result<()> {
+    codex.submit(Op::Shutdown).await?;
+    wait_for_event(codex, |event| matches!(event, EventMsg::ShutdownComplete)).await;
+    Ok(())
+}
+
+fn window_id_parts(request: &ResponsesRequest) -> (String, u64) {
+    let window_id = request
+        .header("x-codex-window-id")
+        .expect("missing x-codex-window-id header");
+    let (thread_id, generation) = window_id
+        .rsplit_once(':')
+        .unwrap_or_else(|| panic!("invalid window id header: {window_id}"));
+    let generation = generation
+        .parse::<u64>()
+        .unwrap_or_else(|err| panic!("invalid window generation in {window_id}: {err}"));
+    (thread_id.to_string(), generation)
+}

codex-rs/linux-sandbox/build.rs

@@ -9,6 +9,7 @@ fn main() {
     println!("cargo:rerun-if-env-changed=PKG_CONFIG_ALLOW_CROSS");
     println!("cargo:rerun-if-env-changed=PKG_CONFIG_PATH");
     println!("cargo:rerun-if-env-changed=PKG_CONFIG_SYSROOT_DIR");
+    println!("cargo:rerun-if-env-changed=CODEX_SKIP_VENDORED_BWRAP");
 
     // Rebuild if the vendored bwrap sources change.
     let manifest_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap_or_default());
@@ -31,7 +32,7 @@ fn main() {
     );
 
     let target_os = env::var("CARGO_CFG_TARGET_OS").unwrap_or_default();
-    if target_os != "linux" {
+    if target_os != "linux" || env::var_os("CODEX_SKIP_VENDORED_BWRAP").is_some() {
         return;
     }
 

codex-rs/responses-api-proxy/Cargo.toml

@@ -26,3 +26,6 @@ serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 tiny_http = { workspace = true }
 zeroize = { workspace = true }
+
+[dev-dependencies]
+pretty_assertions = { workspace = true }

codex-rs/responses-api-proxy/README.md

@@ -35,18 +35,20 @@ curl --fail --silent --show-error "${PROXY_BASE_URL}/shutdown"
 - Listens on the provided port or an ephemeral port if `--port` is not specified.
 - Accepts exactly `POST /v1/responses` (no query string). The request body is forwarded to `https://api.openai.com/v1/responses` with `Authorization: Bearer <key>` set. All original request headers (except any incoming `Authorization`) are forwarded upstream, with `Host` overridden to `api.openai.com`. For other requests, it responds with `403`.
 - Optionally writes a single-line JSON file with server info, currently `{ "port": <u16>, "pid": <u32> }`.
+- Optionally writes request/response JSON dumps to a directory. Each accepted request gets a pair of files that share a sequence/timestamp prefix, for example `000001-1846179912345-request.json` and `000001-1846179912345-response.json`. Header values are dumped in full except `Authorization` and any header whose name includes `cookie`, which are redacted. Bodies are written as parsed JSON when possible, otherwise as UTF-8 text.
 - Optional `--http-shutdown` enables `GET /shutdown` to terminate the process with exit code `0`. This allows one user (e.g., `root`) to start the proxy and another unprivileged user on the host to shut it down.
 
 ## CLI
 
 ```
-codex-responses-api-proxy [--port <PORT>] [--server-info <FILE>] [--http-shutdown] [--upstream-url <URL>]
+codex-responses-api-proxy [--port <PORT>] [--server-info <FILE>] [--http-shutdown] [--upstream-url <URL>] [--dump-dir <DIR>]
 ```
 
 - `--port <PORT>`: Port to bind on `127.0.0.1`. If omitted, an ephemeral port is chosen.
 - `--server-info <FILE>`: If set, the proxy writes a single line of JSON with `{ "port": <PORT>, "pid": <PID> }` once listening.
 - `--http-shutdown`: If set, enables `GET /shutdown` to exit the process with code `0`.
 - `--upstream-url <URL>`: Absolute URL to forward requests to. Defaults to `https://api.openai.com/v1/responses`.
+- `--dump-dir <DIR>`: If set, writes one request JSON file and one response JSON file per accepted proxy call under this directory. Filenames use a shared sequence/timestamp prefix so each pair is easy to correlate.
 - Authentication is fixed to `Authorization: Bearer <key>` to match the Codex CLI expectations.
 
 For Azure, for example (ensure your deployment accepts `Authorization: Bearer <key>`):

codex-rs/responses-api-proxy/src/dump.rs

@@ -0,0 +1,360 @@
+use std::fs;
+use std::io;
+use std::io::Read;
+use std::path::PathBuf;
+use std::sync::atomic::AtomicU64;
+use std::sync::atomic::Ordering;
+use std::time::SystemTime;
+use std::time::UNIX_EPOCH;
+
+use reqwest::header::HeaderMap;
+use serde::Serialize;
+use serde_json::Value;
+use tiny_http::Header;
+use tiny_http::Method;
+
+const AUTHORIZATION_HEADER_NAME: &str = "authorization";
+const REDACTED_HEADER_VALUE: &str = "[REDACTED]";
+
+pub(crate) struct ExchangeDumper {
+    dump_dir: PathBuf,
+    next_sequence: AtomicU64,
+}
+
+impl ExchangeDumper {
+    pub(crate) fn new(dump_dir: PathBuf) -> io::Result<Self> {
+        fs::create_dir_all(&dump_dir)?;
+
+        Ok(Self {
+            dump_dir,
+            next_sequence: AtomicU64::new(1),
+        })
+    }
+
+    pub(crate) fn dump_request(
+        &self,
+        method: &Method,
+        url: &str,
+        headers: &[Header],
+        body: &[u8],
+    ) -> io::Result<ExchangeDump> {
+        let sequence = self.next_sequence.fetch_add(1, Ordering::Relaxed);
+        let timestamp_ms = SystemTime::now()
+            .duration_since(UNIX_EPOCH)
+            .map_or(0, |duration| duration.as_millis());
+        let prefix = format!("{sequence:06}-{timestamp_ms}");
+
+        let request_path = self.dump_dir.join(format!("{prefix}-request.json"));
+        let response_path = self.dump_dir.join(format!("{prefix}-response.json"));
+
+        let request_dump = RequestDump {
+            method: method.as_str().to_string(),
+            url: url.to_string(),
+            headers: headers.iter().map(HeaderDump::from).collect(),
+            body: dump_body(body),
+        };
+
+        write_json_dump(&request_path, &request_dump)?;
+
+        Ok(ExchangeDump { response_path })
+    }
+}
+
+pub(crate) struct ExchangeDump {
+    response_path: PathBuf,
+}
+
+impl ExchangeDump {
+    pub(crate) fn tee_response_body<R: Read>(
+        self,
+        status: u16,
+        headers: &HeaderMap,
+        response_body: R,
+    ) -> ResponseBodyDump<R> {
+        ResponseBodyDump {
+            response_body,
+            response_path: self.response_path,
+            status,
+            headers: headers.iter().map(HeaderDump::from).collect(),
+            body: Vec::new(),
+            dump_written: false,
+        }
+    }
+}
+
+pub(crate) struct ResponseBodyDump<R> {
+    response_body: R,
+    response_path: PathBuf,
+    status: u16,
+    headers: Vec<HeaderDump>,
+    body: Vec<u8>,
+    dump_written: bool,
+}
+
+impl<R> ResponseBodyDump<R> {
+    fn write_dump_if_needed(&mut self) {
+        if self.dump_written {
+            return;
+        }
+
+        self.dump_written = true;
+
+        let response_dump = ResponseDump {
+            status: self.status,
+            headers: std::mem::take(&mut self.headers),
+            body: dump_body(&self.body),
+        };
+
+        if let Err(err) = write_json_dump(&self.response_path, &response_dump) {
+            eprintln!(
+                "responses-api-proxy failed to write {}: {err}",
+                self.response_path.display()
+            );
+        }
+    }
+}
+
+impl<R: Read> Read for ResponseBodyDump<R> {
+    fn read(&mut self, buf: &mut [u8]) -> io::Result<usize> {
+        let bytes_read = self.response_body.read(buf)?;
+        if bytes_read == 0 {
+            self.write_dump_if_needed();
+            return Ok(0);
+        }
+
+        self.body.extend_from_slice(&buf[..bytes_read]);
+        Ok(bytes_read)
+    }
+}
+
+impl<R> Drop for ResponseBodyDump<R> {
+    fn drop(&mut self) {
+        self.write_dump_if_needed();
+    }
+}
+
+#[derive(Serialize)]
+struct RequestDump {
+    method: String,
+    url: String,
+    headers: Vec<HeaderDump>,
+    body: Value,
+}
+
+#[derive(Serialize)]
+struct ResponseDump {
+    status: u16,
+    headers: Vec<HeaderDump>,
+    body: Value,
+}
+
+#[derive(Debug, Serialize)]
+struct HeaderDump {
+    name: String,
+    value: String,
+}
+
+impl From<&Header> for HeaderDump {
+    fn from(header: &Header) -> Self {
+        let name = header.field.as_str().to_string();
+        let value = if should_redact_header(&name) {
+            REDACTED_HEADER_VALUE.to_string()
+        } else {
+            header.value.as_str().to_string()
+        };
+
+        Self { name, value }
+    }
+}
+
+impl From<(&reqwest::header::HeaderName, &reqwest::header::HeaderValue)> for HeaderDump {
+    fn from(header: (&reqwest::header::HeaderName, &reqwest::header::HeaderValue)) -> Self {
+        let name = header.0.as_str();
+        let value = if should_redact_header(name) {
+            REDACTED_HEADER_VALUE.to_string()
+        } else {
+            String::from_utf8_lossy(header.1.as_bytes()).into_owned()
+        };
+
+        Self {
+            name: name.to_string(),
+            value,
+        }
+    }
+}
+
+fn should_redact_header(name: &str) -> bool {
+    name.eq_ignore_ascii_case(AUTHORIZATION_HEADER_NAME)
+        || name.to_ascii_lowercase().contains("cookie")
+}
+
+fn dump_body(body: &[u8]) -> Value {
+    serde_json::from_slice(body)
+        .unwrap_or_else(|_| Value::String(String::from_utf8_lossy(body).into_owned()))
+}
+
+fn write_json_dump(path: &PathBuf, dump: &impl Serialize) -> io::Result<()> {
+    let mut bytes = serde_json::to_vec_pretty(dump)
+        .map_err(|err| io::Error::new(io::ErrorKind::InvalidData, err))?;
+    bytes.push(b'\n');
+    fs::write(path, bytes)
+}
+
+#[cfg(test)]
+mod tests {
+    use std::fs;
+    use std::io::Cursor;
+    use std::io::Read;
+    use std::sync::atomic::AtomicU64;
+    use std::sync::atomic::Ordering;
+
+    use pretty_assertions::assert_eq;
+    use reqwest::header::AUTHORIZATION;
+    use reqwest::header::CONTENT_TYPE;
+    use reqwest::header::HeaderMap;
+    use reqwest::header::HeaderValue;
+    use serde_json::json;
+    use tiny_http::Header;
+    use tiny_http::Method;
+
+    use super::ExchangeDumper;
+
+    static NEXT_TEST_DIR: AtomicU64 = AtomicU64::new(0);
+
+    #[test]
+    fn dump_request_writes_redacted_headers_and_json_body() {
+        let dump_dir = test_dump_dir();
+        let dumper = ExchangeDumper::new(dump_dir.clone()).expect("create dumper");
+        let headers = vec![
+            Header::from_bytes(&b"Authorization"[..], &b"Bearer secret"[..])
+                .expect("authorization header"),
+            Header::from_bytes(&b"Cookie"[..], &b"user-session=secret"[..]).expect("cookie header"),
+            Header::from_bytes(&b"Content-Type"[..], &b"application/json"[..])
+                .expect("content-type header"),
+        ];
+
+        let exchange_dump = dumper
+            .dump_request(
+                &Method::Post,
+                "/v1/responses",
+                &headers,
+                br#"{"model":"gpt-5.4"}"#,
+            )
+            .expect("dump request");
+
+        let request_dump = fs::read_to_string(dump_file_with_suffix(&dump_dir, "-request.json"))
+            .expect("read request dump");
+
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&request_dump).expect("parse request dump"),
+            json!({
+                "method": "POST",
+                "url": "/v1/responses",
+                "headers": [
+                    {
+                        "name": "Authorization",
+                        "value": "[REDACTED]"
+                    },
+                    {
+                        "name": "Cookie",
+                        "value": "[REDACTED]"
+                    },
+                    {
+                        "name": "Content-Type",
+                        "value": "application/json"
+                    }
+                ],
+                "body": {
+                    "model": "gpt-5.4"
+                }
+            })
+        );
+        assert!(
+            exchange_dump
+                .response_path
+                .file_name()
+                .expect("response dump file name")
+                .to_string_lossy()
+                .ends_with("-response.json")
+        );
+
+        fs::remove_dir_all(dump_dir).expect("remove test dump dir");
+    }
+
+    #[test]
+    fn response_body_dump_streams_body_and_writes_response_file() {
+        let dump_dir = test_dump_dir();
+        let dumper = ExchangeDumper::new(dump_dir.clone()).expect("create dumper");
+        let exchange_dump = dumper
+            .dump_request(&Method::Post, "/v1/responses", &[], b"{}")
+            .expect("dump request");
+
+        let mut headers = HeaderMap::new();
+        headers.insert(CONTENT_TYPE, HeaderValue::from_static("text/event-stream"));
+        headers.insert(AUTHORIZATION, HeaderValue::from_static("Bearer secret"));
+        headers.insert(
+            "set-cookie",
+            HeaderValue::from_static("user-session=secret"),
+        );
+
+        let mut response_body = String::new();
+        exchange_dump
+            .tee_response_body(
+                /*status*/ 200,
+                &headers,
+                Cursor::new(b"data: hello\n\n".to_vec()),
+            )
+            .read_to_string(&mut response_body)
+            .expect("read response body");
+
+        let response_dump = fs::read_to_string(dump_file_with_suffix(&dump_dir, "-response.json"))
+            .expect("read response dump");
+
+        assert_eq!(response_body, "data: hello\n\n");
+        assert_eq!(
+            serde_json::from_str::<serde_json::Value>(&response_dump).expect("parse response dump"),
+            json!({
+                "status": 200,
+                "headers": [
+                    {
+                        "name": "content-type",
+                        "value": "text/event-stream"
+                    },
+                    {
+                        "name": "authorization",
+                        "value": "[REDACTED]"
+                    },
+                    {
+                        "name": "set-cookie",
+                        "value": "[REDACTED]"
+                    }
+                ],
+                "body": "data: hello\n\n"
+            })
+        );
+
+        fs::remove_dir_all(dump_dir).expect("remove test dump dir");
+    }
+
+    fn test_dump_dir() -> std::path::PathBuf {
+        let test_id = NEXT_TEST_DIR.fetch_add(1, Ordering::Relaxed);
+        let dump_dir = std::env::temp_dir().join(format!(
+            "codex-responses-api-proxy-dump-test-{}-{test_id}",
+            std::process::id()
+        ));
+        fs::create_dir_all(&dump_dir).expect("create test dump dir");
+        dump_dir
+    }
+
+    fn dump_file_with_suffix(dump_dir: &std::path::Path, suffix: &str) -> std::path::PathBuf {
+        let mut matches = fs::read_dir(dump_dir)
+            .expect("read dump dir")
+            .map(|entry| entry.expect("read dump entry").path())
+            .filter(|path| path.to_string_lossy().ends_with(suffix))
+            .collect::<Vec<_>>();
+        matches.sort();
+
+        assert_eq!(matches.len(), 1);
+        matches.pop().expect("single dump file")
+    }
+}

codex-rs/responses-api-proxy/src/lib.rs

@@ -1,5 +1,6 @@
 use std::fs::File;
 use std::fs::{self};
+use std::io::Read;
 use std::io::Write;
 use std::net::SocketAddr;
 use std::net::TcpListener;
@@ -27,7 +28,9 @@ use tiny_http::Response;
 use tiny_http::Server;
 use tiny_http::StatusCode;
 
+mod dump;
 mod read_api_key;
+use dump::ExchangeDumper;
 use read_api_key::read_auth_header_from_stdin;
 
 /// CLI arguments for the proxy.
@@ -49,6 +52,10 @@ pub struct Args {
     /// Absolute URL the proxy should forward requests to (defaults to OpenAI).
     #[arg(long, default_value = "https://api.openai.com/v1/responses")]
     pub upstream_url: String,
+
+    /// Directory where request/response dumps should be written as JSON.
+    #[arg(long, value_name = "DIR")]
+    pub dump_dir: Option<PathBuf>,
 }
 
 #[derive(Serialize)]
@@ -79,6 +86,12 @@ pub fn run_main(args: Args) -> Result<()> {
         upstream_url,
         host_header,
     });
+    let dump_dir = args
+        .dump_dir
+        .map(ExchangeDumper::new)
+        .transpose()
+        .context("creating --dump-dir")?
+        .map(Arc::new);
 
     let (listener, bound_addr) = bind_listener(args.port)?;
     if let Some(path) = args.server_info.as_ref() {
@@ -100,13 +113,20 @@ pub fn run_main(args: Args) -> Result<()> {
     for request in server.incoming_requests() {
         let client = client.clone();
         let forward_config = forward_config.clone();
+        let dump_dir = dump_dir.clone();
         std::thread::spawn(move || {
             if http_shutdown && request.method() == &Method::Get && request.url() == "/shutdown" {
                 let _ = request.respond(Response::new_empty(StatusCode(200)));
                 std::process::exit(0);
             }
 
-            if let Err(e) = forward_request(&client, auth_header, &forward_config, request) {
+            if let Err(e) = forward_request(
+                &client,
+                auth_header,
+                &forward_config,
+                dump_dir.as_deref(),
+                request,
+            ) {
                 eprintln!("forwarding error: {e}");
             }
         });
@@ -144,6 +164,7 @@ fn forward_request(
     client: &Client,
     auth_header: &'static str,
     config: &ForwardConfig,
+    dump_dir: Option<&ExchangeDumper>,
     mut req: Request,
 ) -> Result<()> {
     // Only allow POST /v1/responses exactly, no query string.
@@ -159,8 +180,18 @@ fn forward_request(
 
     // Read request body
     let mut body = Vec::new();
-    let mut reader = req.as_reader();
-    std::io::Read::read_to_end(&mut reader, &mut body)?;
+    let reader = req.as_reader();
+    reader.read_to_end(&mut body)?;
+
+    let exchange_dump = dump_dir.and_then(|dump_dir| {
+        dump_dir
+            .dump_request(&method, &url_path, req.headers(), &body)
+            .map_err(|err| {
+                eprintln!("responses-api-proxy failed to dump request: {err}");
+                err
+            })
+            .ok()
+    });
 
     // Build headers for upstream, forwarding everything from the incoming
     // request except Authorization (we replace it below).
@@ -224,10 +255,17 @@ fn forward_request(
         }
     });
 
+    let response_body: Box<dyn Read + Send> = if let Some(exchange_dump) = exchange_dump {
+        let headers = upstream_resp.headers().clone();
+        Box::new(exchange_dump.tee_response_body(status.as_u16(), &headers, upstream_resp))
+    } else {
+        Box::new(upstream_resp)
+    };
+
     let response = Response::new(
         StatusCode(status.as_u16()),
         response_headers,
-        upstream_resp,
+        response_body,
         content_length,
         None,
     );