Merge 3a46c41cd9 into sapling-pr-archive-bolinfest

.github/workflows/issue-deduplicator.yml

@@ -55,8 +55,9 @@ jobs:
             - `codex-existing-issues.json`: JSON array of recent issues (each element includes number, title, body, createdAt).
 
             Instructions:
-            - Load both files as JSON and review their contents carefully. The codex-existing-issues.json file is large, ensure you explore all of it.
             - Compare the current issue against the existing issues to find up to five that appear to describe the same underlying problem or request.
+            - Focus on the underlying intent and context of each issue—such as reported symptoms, feature requests, reproduction steps, or error messages—rather than relying solely on string similarity or synthetic metrics.
+            - After your analysis, validate your results in 1-2 lines explaining your decision to return the selected matches.
             - When unsure, prefer returning fewer matches.
             - Include at most five numbers.
 
@@ -69,9 +70,10 @@ jobs:
                   "items": {
                     "type": "string"
                   }
-                }
+                },
+                "reason": { "type": "string" }
               },
-              "required": ["issues"],
+              "required": ["issues", "reason"],
               "additionalProperties": false
             }
 

codex-rs/core/gpt_5_codex_prompt.md

@@ -10,12 +10,14 @@ You are Codex, based on GPT-5. You are running as a coding agent in the Codex CL
 
 - Default to ASCII when editing or creating files. Only introduce non-ASCII or other Unicode characters when there is a clear justification and the file already uses them.
 - Add succinct code comments that explain what is going on if code is not self-explanatory. You should not add comments like "Assigns the value to the variable", but a brief comment might be useful ahead of a complex code block that the user would otherwise have to spend time parsing out. Usage of these comments should be rare.
+- Try to use apply_patch for single file edits, but it is fine to explore other options to make the edit if it does not work well. Do not use apply_patch for changes that are auto-generated (i.e. generating package.json or running a lint or format command like gofmt) or when scripting is more efficient (such as search and replacing a string across a codebase).
 - You may be in a dirty git worktree.
     * NEVER revert existing changes you did not make unless explicitly requested, since these changes were made by the user.
     * If asked to make a commit or code edits and there are unrelated changes to your work or changes that you didn't make in those files, don't revert those changes.
     * If the changes are in files you've touched recently, you should read carefully and understand how you can work with the changes rather than reverting them.
     * If the changes are in unrelated files, just ignore them and don't revert them.
 - While you are working, you might notice unexpected changes that you didn't make. If this happens, STOP IMMEDIATELY and ask the user how they would like to proceed.
+- **NEVER** use destructive commands like `git reset --hard` or `git checkout --` unless specifically requested or approved by the user.
 
 ## Plan tool
 

codex-rs/core/src/client.rs

@@ -63,7 +63,6 @@ struct ErrorResponse {
 #[derive(Debug, Deserialize)]
 struct Error {
     r#type: Option<String>,
-    #[allow(dead_code)]
     code: Option<String>,
     message: Option<String>,
 
@@ -228,7 +227,7 @@ impl ModelClient {
             input: &input_with_instructions,
             tools: &tools_json,
             tool_choice: "auto",
-            parallel_tool_calls: false,
+            parallel_tool_calls: prompt.parallel_tool_calls,
             reasoning,
             store: azure_workaround,
             stream: true,
@@ -794,9 +793,13 @@ async fn process_sse<S>(
                     if let Some(error) = error {
                         match serde_json::from_value::<Error>(error.clone()) {
                             Ok(error) => {
-                                let delay = try_parse_retry_after(&error);
-                                let message = error.message.unwrap_or_default();
-                                response_error = Some(CodexErr::Stream(message, delay));
+                                if is_context_window_error(&error) {
+                                    response_error = Some(CodexErr::ContextWindowExceeded);
+                                } else {
+                                    let delay = try_parse_retry_after(&error);
+                                    let message = error.message.clone().unwrap_or_default();
+                                    response_error = Some(CodexErr::Stream(message, delay));
+                                }
                             }
                             Err(e) => {
                                 let error = format!("failed to parse ErrorResponse: {e}");
@@ -922,6 +925,10 @@ fn try_parse_retry_after(err: &Error) -> Option<Duration> {
     None
 }
 
+fn is_context_window_error(error: &Error) -> bool {
+    error.code.as_deref() == Some("context_length_exceeded")
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -1179,6 +1186,74 @@ mod tests {
         }
     }
 
+    #[tokio::test]
+    async fn context_window_error_is_fatal() {
+        let raw_error = r#"{"type":"response.failed","sequence_number":3,"response":{"id":"resp_5c66275b97b9baef1ed95550adb3b7ec13b17aafd1d2f11b","object":"response","created_at":1759510079,"status":"failed","background":false,"error":{"code":"context_length_exceeded","message":"Your input exceeds the context window of this model. Please adjust your input and try again."},"usage":null,"user":null,"metadata":{}}}"#;
+
+        let sse1 = format!("event: response.failed\ndata: {raw_error}\n\n");
+        let provider = ModelProviderInfo {
+            name: "test".to_string(),
+            base_url: Some("https://test.com".to_string()),
+            env_key: Some("TEST_API_KEY".to_string()),
+            env_key_instructions: None,
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: None,
+            env_http_headers: None,
+            request_max_retries: Some(0),
+            stream_max_retries: Some(0),
+            stream_idle_timeout_ms: Some(1000),
+            requires_openai_auth: false,
+        };
+
+        let otel_event_manager = otel_event_manager();
+
+        let events = collect_events(&[sse1.as_bytes()], provider, otel_event_manager).await;
+
+        assert_eq!(events.len(), 1);
+
+        match &events[0] {
+            Err(err @ CodexErr::ContextWindowExceeded) => {
+                assert_eq!(err.to_string(), CodexErr::ContextWindowExceeded.to_string());
+            }
+            other => panic!("unexpected context window event: {other:?}"),
+        }
+    }
+
+    #[tokio::test]
+    async fn context_window_error_with_newline_is_fatal() {
+        let raw_error = r#"{"type":"response.failed","sequence_number":4,"response":{"id":"resp_fatal_newline","object":"response","created_at":1759510080,"status":"failed","background":false,"error":{"code":"context_length_exceeded","message":"Your input exceeds the context window of this model. Please adjust your input and try\nagain."},"usage":null,"user":null,"metadata":{}}}"#;
+
+        let sse1 = format!("event: response.failed\ndata: {raw_error}\n\n");
+        let provider = ModelProviderInfo {
+            name: "test".to_string(),
+            base_url: Some("https://test.com".to_string()),
+            env_key: Some("TEST_API_KEY".to_string()),
+            env_key_instructions: None,
+            wire_api: WireApi::Responses,
+            query_params: None,
+            http_headers: None,
+            env_http_headers: None,
+            request_max_retries: Some(0),
+            stream_max_retries: Some(0),
+            stream_idle_timeout_ms: Some(1000),
+            requires_openai_auth: false,
+        };
+
+        let otel_event_manager = otel_event_manager();
+
+        let events = collect_events(&[sse1.as_bytes()], provider, otel_event_manager).await;
+
+        assert_eq!(events.len(), 1);
+
+        match &events[0] {
+            Err(err @ CodexErr::ContextWindowExceeded) => {
+                assert_eq!(err.to_string(), CodexErr::ContextWindowExceeded.to_string());
+            }
+            other => panic!("unexpected context window event: {other:?}"),
+        }
+    }
+
     // ────────────────────────────
     // Table-driven test from `main`
     // ────────────────────────────

codex-rs/core/src/client_common.rs

@@ -9,9 +9,11 @@ use codex_protocol::config_types::ReasoningSummary as ReasoningSummaryConfig;
 use codex_protocol::config_types::Verbosity as VerbosityConfig;
 use codex_protocol::models::ResponseItem;
 use futures::Stream;
+use serde::Deserialize;
 use serde::Serialize;
 use serde_json::Value;
 use std::borrow::Cow;
+use std::collections::HashSet;
 use std::ops::Deref;
 use std::pin::Pin;
 use std::task::Context;
@@ -31,6 +33,9 @@ pub struct Prompt {
     /// external MCP servers.
     pub(crate) tools: Vec<ToolSpec>,
 
+    /// Whether parallel tool calls are permitted for this prompt.
+    pub(crate) parallel_tool_calls: bool,
+
     /// Optional override for the built-in BASE_INSTRUCTIONS.
     pub base_instructions_override: Option<String>,
 
@@ -64,10 +69,114 @@ impl Prompt {
     }
 
     pub(crate) fn get_formatted_input(&self) -> Vec<ResponseItem> {
-        self.input.clone()
+        let mut input = self.input.clone();
+
+        // when using the *Freeform* apply_patch tool specifically, tool outputs
+        // should be structured text, not json. Do NOT reserialize when using
+        // the Function tool - note that this differs from the check above for
+        // instructions. We declare the result as a named variable for clarity.
+        let is_freeform_apply_patch_tool_present = self.tools.iter().any(|tool| match tool {
+            ToolSpec::Freeform(f) => f.name == "apply_patch",
+            _ => false,
+        });
+        if is_freeform_apply_patch_tool_present {
+            reserialize_shell_outputs(&mut input);
+        }
+
+        input
     }
 }
 
+fn reserialize_shell_outputs(items: &mut [ResponseItem]) {
+    let mut shell_call_ids: HashSet<String> = HashSet::new();
+
+    items.iter_mut().for_each(|item| match item {
+        ResponseItem::LocalShellCall { call_id, id, .. } => {
+            if let Some(identifier) = call_id.clone().or_else(|| id.clone()) {
+                shell_call_ids.insert(identifier);
+            }
+        }
+        ResponseItem::CustomToolCall {
+            id: _,
+            status: _,
+            call_id,
+            name,
+            input: _,
+        } => {
+            if name == "apply_patch" {
+                shell_call_ids.insert(call_id.clone());
+            }
+        }
+        ResponseItem::CustomToolCallOutput { call_id, output } => {
+            if shell_call_ids.remove(call_id)
+                && let Some(structured) = parse_structured_shell_output(output)
+            {
+                *output = structured
+            }
+        }
+        ResponseItem::FunctionCall { name, call_id, .. }
+            if is_shell_tool_name(name) || name == "apply_patch" =>
+        {
+            shell_call_ids.insert(call_id.clone());
+        }
+        ResponseItem::FunctionCallOutput { call_id, output } => {
+            if shell_call_ids.remove(call_id)
+                && let Some(structured) = parse_structured_shell_output(&output.content)
+            {
+                output.content = structured
+            }
+        }
+        _ => {}
+    })
+}
+
+fn is_shell_tool_name(name: &str) -> bool {
+    matches!(name, "shell" | "container.exec")
+}
+
+#[derive(Deserialize)]
+struct ExecOutputJson {
+    output: String,
+    metadata: ExecOutputMetadataJson,
+}
+
+#[derive(Deserialize)]
+struct ExecOutputMetadataJson {
+    exit_code: i32,
+    duration_seconds: f32,
+}
+
+fn parse_structured_shell_output(raw: &str) -> Option<String> {
+    let parsed: ExecOutputJson = serde_json::from_str(raw).ok()?;
+    Some(build_structured_output(&parsed))
+}
+
+fn build_structured_output(parsed: &ExecOutputJson) -> String {
+    let mut sections = Vec::new();
+    sections.push(format!("Exit code: {}", parsed.metadata.exit_code));
+    sections.push(format!(
+        "Wall time: {} seconds",
+        parsed.metadata.duration_seconds
+    ));
+
+    if let Some(total_lines) = extract_total_output_lines(&parsed.output) {
+        sections.push(format!("Total output lines: {total_lines}"));
+    }
+
+    sections.push("Output:".to_string());
+    sections.push(parsed.output.clone());
+
+    sections.join("\n")
+}
+
+fn extract_total_output_lines(output: &str) -> Option<u32> {
+    let marker_start = output.find("[... omitted ")?;
+    let marker = &output[marker_start..];
+    let (_, after_of) = marker.split_once(" of ")?;
+    let (total_segment, _) = after_of.split_once(' ')?;
+    total_segment.parse::<u32>().ok()
+}
+
 #[derive(Debug)]
 pub enum ResponseEvent {
     Created,
@@ -182,6 +291,17 @@ pub(crate) mod tools {
         Freeform(FreeformTool),
     }
 
+    impl ToolSpec {
+        pub(crate) fn name(&self) -> &str {
+            match self {
+                ToolSpec::Function(tool) => tool.name.as_str(),
+                ToolSpec::LocalShell {} => "local_shell",
+                ToolSpec::WebSearch {} => "web_search",
+                ToolSpec::Freeform(tool) => tool.name.as_str(),
+            }
+        }
+    }
+
     #[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
     pub struct FreeformTool {
         pub(crate) name: String,
@@ -327,7 +447,7 @@ mod tests {
             input: &input,
             tools: &tools,
             tool_choice: "auto",
-            parallel_tool_calls: false,
+            parallel_tool_calls: true,
             reasoning: None,
             store: false,
             stream: true,
@@ -368,7 +488,7 @@ mod tests {
             input: &input,
             tools: &tools,
             tool_choice: "auto",
-            parallel_tool_calls: false,
+            parallel_tool_calls: true,
             reasoning: None,
             store: false,
             stream: true,
@@ -404,7 +524,7 @@ mod tests {
             input: &input,
             tools: &tools,
             tool_choice: "auto",
-            parallel_tool_calls: false,
+            parallel_tool_calls: true,
             reasoning: None,
             store: false,
             stream: true,

codex-rs/core/src/codex.rs

@@ -100,7 +100,9 @@ use crate::tasks::CompactTask;
 use crate::tasks::RegularTask;
 use crate::tasks::ReviewTask;
 use crate::tools::ToolRouter;
+use crate::tools::context::SharedTurnDiffTracker;
 use crate::tools::format_exec_output_str;
+use crate::tools::parallel::ToolCallRuntime;
 use crate::turn_diff_tracker::TurnDiffTracker;
 use crate::unified_exec::UnifiedExecSessionManager;
 use crate::user_instructions::UserInstructions;
@@ -782,6 +784,17 @@ impl Session {
         self.send_event(event).await;
     }
 
+    async fn set_total_tokens_full(&self, sub_id: &str, turn_context: &TurnContext) {
+        let context_window = turn_context.client.get_model_context_window();
+        if let Some(context_window) = context_window {
+            {
+                let mut state = self.state.lock().await;
+                state.set_token_usage_full(context_window);
+            }
+            self.send_token_count_event(sub_id).await;
+        }
+    }
+
     /// Record a user input item to conversation history and also persist a
     /// corresponding UserMessage EventMsg to rollout.
     async fn record_input_and_rollout_usermsg(&self, response_input: &ResponseInputItem) {
@@ -807,7 +820,7 @@ impl Session {
 
     async fn on_exec_command_begin(
         &self,
-        turn_diff_tracker: &mut TurnDiffTracker,
+        turn_diff_tracker: SharedTurnDiffTracker,
         exec_command_context: ExecCommandContext,
     ) {
         let ExecCommandContext {
@@ -823,7 +836,10 @@ impl Session {
                 user_explicitly_approved_this_action,
                 changes,
             }) => {
-                turn_diff_tracker.on_patch_begin(&changes);
+                {
+                    let mut tracker = turn_diff_tracker.lock().await;
+                    tracker.on_patch_begin(&changes);
+                }
 
                 EventMsg::PatchApplyBegin(PatchApplyBeginEvent {
                     call_id,
@@ -850,7 +866,7 @@ impl Session {
 
     async fn on_exec_command_end(
         &self,
-        turn_diff_tracker: &mut TurnDiffTracker,
+        turn_diff_tracker: SharedTurnDiffTracker,
         sub_id: &str,
         call_id: &str,
         output: &ExecToolCallOutput,
@@ -898,7 +914,10 @@ impl Session {
         // If this is an apply_patch, after we emit the end patch, emit a second event
         // with the full turn diff if there is one.
         if is_apply_patch {
-            let unified_diff = turn_diff_tracker.get_unified_diff();
+            let unified_diff = {
+                let mut tracker = turn_diff_tracker.lock().await;
+                tracker.get_unified_diff()
+            };
             if let Ok(Some(unified_diff)) = unified_diff {
                 let msg = EventMsg::TurnDiff(TurnDiffEvent { unified_diff });
                 let event = Event {
@@ -915,7 +934,7 @@ impl Session {
     /// Returns the output of the exec tool call.
     pub(crate) async fn run_exec_with_events(
         &self,
-        turn_diff_tracker: &mut TurnDiffTracker,
+        turn_diff_tracker: SharedTurnDiffTracker,
         prepared: PreparedExec,
         approval_policy: AskForApproval,
     ) -> Result<ExecToolCallOutput, ExecError> {
@@ -924,7 +943,7 @@ impl Session {
         let sub_id = context.sub_id.clone();
         let call_id = context.call_id.clone();
 
-        self.on_exec_command_begin(turn_diff_tracker, context.clone())
+        self.on_exec_command_begin(turn_diff_tracker.clone(), context.clone())
             .await;
 
         let result = self
@@ -1633,7 +1652,7 @@ pub(crate) async fn run_task(
     let mut last_agent_message: Option<String> = None;
     // Although from the perspective of codex.rs, TurnDiffTracker has the lifecycle of a Task which contains
     // many turns, from the perspective of the user, it is a single turn.
-    let mut turn_diff_tracker = TurnDiffTracker::new();
+    let turn_diff_tracker = Arc::new(tokio::sync::Mutex::new(TurnDiffTracker::new()));
     let mut auto_compact_recently_attempted = false;
 
     loop {
@@ -1681,9 +1700,9 @@ pub(crate) async fn run_task(
             })
             .collect();
         match run_turn(
-            &sess,
-            turn_context.as_ref(),
-            &mut turn_diff_tracker,
+            Arc::clone(&sess),
+            Arc::clone(&turn_context),
+            Arc::clone(&turn_diff_tracker),
             sub_id.clone(),
             turn_input,
         )
@@ -1906,18 +1925,27 @@ fn parse_review_output_event(text: &str) -> ReviewOutputEvent {
 }
 
 async fn run_turn(
-    sess: &Session,
-    turn_context: &TurnContext,
-    turn_diff_tracker: &mut TurnDiffTracker,
+    sess: Arc<Session>,
+    turn_context: Arc<TurnContext>,
+    turn_diff_tracker: SharedTurnDiffTracker,
     sub_id: String,
     input: Vec<ResponseItem>,
 ) -> CodexResult<TurnRunResult> {
     let mcp_tools = sess.services.mcp_connection_manager.list_all_tools();
-    let router = ToolRouter::from_config(&turn_context.tools_config, Some(mcp_tools));
+    let router = Arc::new(ToolRouter::from_config(
+        &turn_context.tools_config,
+        Some(mcp_tools),
+    ));
 
+    let model_supports_parallel = turn_context
+        .client
+        .get_model_family()
+        .supports_parallel_tool_calls;
+    let parallel_tool_calls = model_supports_parallel;
     let prompt = Prompt {
         input,
-        tools: router.specs().to_vec(),
+        tools: router.specs(),
+        parallel_tool_calls,
         base_instructions_override: turn_context.base_instructions.clone(),
         output_schema: turn_context.final_output_json_schema.clone(),
     };
@@ -1925,10 +1953,10 @@ async fn run_turn(
     let mut retries = 0;
     loop {
         match try_run_turn(
-            &router,
-            sess,
-            turn_context,
-            turn_diff_tracker,
+            Arc::clone(&router),
+            Arc::clone(&sess),
+            Arc::clone(&turn_context),
+            Arc::clone(&turn_diff_tracker),
             &sub_id,
             &prompt,
         )
@@ -1938,6 +1966,10 @@ async fn run_turn(
             Err(CodexErr::Interrupted) => return Err(CodexErr::Interrupted),
             Err(CodexErr::EnvVar(var)) => return Err(CodexErr::EnvVar(var)),
             Err(e @ CodexErr::Fatal(_)) => return Err(e),
+            Err(e @ CodexErr::ContextWindowExceeded) => {
+                sess.set_total_tokens_full(&sub_id, &turn_context).await;
+                return Err(e);
+            }
             Err(CodexErr::UsageLimitReached(e)) => {
                 let rate_limits = e.rate_limits.clone();
                 if let Some(rate_limits) = rate_limits {
@@ -1984,9 +2016,9 @@ async fn run_turn(
 /// "handled" such that it produces a `ResponseInputItem` that needs to be
 /// sent back to the model on the next turn.
 #[derive(Debug)]
-struct ProcessedResponseItem {
-    item: ResponseItem,
-    response: Option<ResponseInputItem>,
+pub(crate) struct ProcessedResponseItem {
+    pub(crate) item: ResponseItem,
+    pub(crate) response: Option<ResponseInputItem>,
 }
 
 #[derive(Debug)]
@@ -1996,10 +2028,10 @@ struct TurnRunResult {
 }
 
 async fn try_run_turn(
-    router: &crate::tools::ToolRouter,
-    sess: &Session,
-    turn_context: &TurnContext,
-    turn_diff_tracker: &mut TurnDiffTracker,
+    router: Arc<ToolRouter>,
+    sess: Arc<Session>,
+    turn_context: Arc<TurnContext>,
+    turn_diff_tracker: SharedTurnDiffTracker,
     sub_id: &str,
     prompt: &Prompt,
 ) -> CodexResult<TurnRunResult> {
@@ -2070,24 +2102,34 @@ async fn try_run_turn(
     let mut stream = turn_context.client.clone().stream(&prompt).await?;
 
     let mut output = Vec::new();
+    let mut tool_runtime = ToolCallRuntime::new(
+        Arc::clone(&router),
+        Arc::clone(&sess),
+        Arc::clone(&turn_context),
+        Arc::clone(&turn_diff_tracker),
+        sub_id.to_string(),
+    );
 
     loop {
         // Poll the next item from the model stream. We must inspect *both* Ok and Err
         // cases so that transient stream failures (e.g., dropped SSE connection before
         // `response.completed`) bubble up and trigger the caller's retry logic.
         let event = stream.next().await;
-        let Some(event) = event else {
-            // Channel closed without yielding a final Completed event or explicit error.
-            // Treat as a disconnected stream so the caller can retry.
-            return Err(CodexErr::Stream(
-                "stream closed before response.completed".into(),
-                None,
-            ));
+        let event = match event {
+            Some(event) => event,
+            None => {
+                tool_runtime.abort_all();
+                return Err(CodexErr::Stream(
+                    "stream closed before response.completed".into(),
+                    None,
+                ));
+            }
         };
 
         let event = match event {
             Ok(ev) => ev,
             Err(e) => {
+                tool_runtime.abort_all();
                 // Propagate the underlying stream error to the caller (run_turn), which
                 // will apply the configured `stream_max_retries` policy.
                 return Err(e);
@@ -2097,16 +2139,66 @@ async fn try_run_turn(
         match event {
             ResponseEvent::Created => {}
             ResponseEvent::OutputItemDone(item) => {
-                let response = handle_response_item(
-                    router,
-                    sess,
-                    turn_context,
-                    turn_diff_tracker,
-                    sub_id,
-                    item.clone(),
-                )
-                .await?;
-                output.push(ProcessedResponseItem { item, response });
+                match ToolRouter::build_tool_call(sess.as_ref(), item.clone()) {
+                    Ok(Some(call)) => {
+                        let payload_preview = call.payload.log_payload().into_owned();
+                        tracing::info!("ToolCall: {} {}", call.tool_name, payload_preview);
+                        let index = output.len();
+                        output.push(ProcessedResponseItem {
+                            item,
+                            response: None,
+                        });
+                        tool_runtime
+                            .handle_tool_call(call, index, output.as_mut_slice())
+                            .await?;
+                    }
+                    Ok(None) => {
+                        let response = handle_non_tool_response_item(
+                            Arc::clone(&sess),
+                            Arc::clone(&turn_context),
+                            sub_id,
+                            item.clone(),
+                        )
+                        .await?;
+                        output.push(ProcessedResponseItem { item, response });
+                    }
+                    Err(FunctionCallError::MissingLocalShellCallId) => {
+                        let msg = "LocalShellCall without call_id or id";
+                        turn_context
+                            .client
+                            .get_otel_event_manager()
+                            .log_tool_failed("local_shell", msg);
+                        error!(msg);
+
+                        let response = ResponseInputItem::FunctionCallOutput {
+                            call_id: String::new(),
+                            output: FunctionCallOutputPayload {
+                                content: msg.to_string(),
+                                success: None,
+                            },
+                        };
+                        output.push(ProcessedResponseItem {
+                            item,
+                            response: Some(response),
+                        });
+                    }
+                    Err(FunctionCallError::RespondToModel(message)) => {
+                        let response = ResponseInputItem::FunctionCallOutput {
+                            call_id: String::new(),
+                            output: FunctionCallOutputPayload {
+                                content: message,
+                                success: None,
+                            },
+                        };
+                        output.push(ProcessedResponseItem {
+                            item,
+                            response: Some(response),
+                        });
+                    }
+                    Err(FunctionCallError::Fatal(message)) => {
+                        return Err(CodexErr::Fatal(message));
+                    }
+                }
             }
             ResponseEvent::WebSearchCallBegin { call_id } => {
                 let _ = sess
@@ -2126,10 +2218,15 @@ async fn try_run_turn(
                 response_id: _,
                 token_usage,
             } => {
-                sess.update_token_usage_info(sub_id, turn_context, token_usage.as_ref())
+                sess.update_token_usage_info(sub_id, turn_context.as_ref(), token_usage.as_ref())
                     .await;
 
-                let unified_diff = turn_diff_tracker.get_unified_diff();
+                tool_runtime.resolve_pending(output.as_mut_slice()).await?;
+
+                let unified_diff = {
+                    let mut tracker = turn_diff_tracker.lock().await;
+                    tracker.get_unified_diff()
+                };
                 if let Ok(Some(unified_diff)) = unified_diff {
                     let msg = EventMsg::TurnDiff(TurnDiffEvent { unified_diff });
                     let event = Event {
@@ -2188,88 +2285,40 @@ async fn try_run_turn(
     }
 }
 
-async fn handle_response_item(
-    router: &crate::tools::ToolRouter,
-    sess: &Session,
-    turn_context: &TurnContext,
-    turn_diff_tracker: &mut TurnDiffTracker,
+async fn handle_non_tool_response_item(
+    sess: Arc<Session>,
+    turn_context: Arc<TurnContext>,
     sub_id: &str,
     item: ResponseItem,
 ) -> CodexResult<Option<ResponseInputItem>> {
     debug!(?item, "Output item");
 
-    match ToolRouter::build_tool_call(sess, item.clone()) {
-        Ok(Some(call)) => {
-            let payload_preview = call.payload.log_payload().into_owned();
-            tracing::info!("ToolCall: {} {}", call.tool_name, payload_preview);
-            match router
-                .dispatch_tool_call(sess, turn_context, turn_diff_tracker, sub_id, call)
-                .await
-            {
-                Ok(response) => Ok(Some(response)),
-                Err(FunctionCallError::Fatal(message)) => Err(CodexErr::Fatal(message)),
-                Err(other) => unreachable!("non-fatal tool error returned: {other:?}"),
+    match &item {
+        ResponseItem::Message { .. }
+        | ResponseItem::Reasoning { .. }
+        | ResponseItem::WebSearchCall { .. } => {
+            let msgs = match &item {
+                ResponseItem::Message { .. } if turn_context.is_review_mode => {
+                    trace!("suppressing assistant Message in review mode");
+                    Vec::new()
+                }
+                _ => map_response_item_to_event_messages(&item, sess.show_raw_agent_reasoning()),
+            };
+            for msg in msgs {
+                let event = Event {
+                    id: sub_id.to_string(),
+                    msg,
+                };
+                sess.send_event(event).await;
             }
         }
-        Ok(None) => {
-            match &item {
-                ResponseItem::Message { .. }
-                | ResponseItem::Reasoning { .. }
-                | ResponseItem::WebSearchCall { .. } => {
-                    let msgs = match &item {
-                        ResponseItem::Message { .. } if turn_context.is_review_mode => {
-                            trace!("suppressing assistant Message in review mode");
-                            Vec::new()
-                        }
-                        _ => map_response_item_to_event_messages(
-                            &item,
-                            sess.show_raw_agent_reasoning(),
-                        ),
-                    };
-                    for msg in msgs {
-                        let event = Event {
-                            id: sub_id.to_string(),
-                            msg,
-                        };
-                        sess.send_event(event).await;
-                    }
-                }
-                ResponseItem::FunctionCallOutput { .. }
-                | ResponseItem::CustomToolCallOutput { .. } => {
-                    debug!("unexpected tool output from stream");
-                }
-                _ => {}
-            }
-
-            Ok(None)
+        ResponseItem::FunctionCallOutput { .. } | ResponseItem::CustomToolCallOutput { .. } => {
+            debug!("unexpected tool output from stream");
         }
-        Err(FunctionCallError::MissingLocalShellCallId) => {
-            let msg = "LocalShellCall without call_id or id";
-            turn_context
-                .client
-                .get_otel_event_manager()
-                .log_tool_failed("local_shell", msg);
-            error!(msg);
-
-            Ok(Some(ResponseInputItem::FunctionCallOutput {
-                call_id: String::new(),
-                output: FunctionCallOutputPayload {
-                    content: msg.to_string(),
-                    success: None,
-                },
-            }))
-        }
-        Err(FunctionCallError::RespondToModel(msg)) => {
-            Ok(Some(ResponseInputItem::FunctionCallOutput {
-                call_id: String::new(),
-                output: FunctionCallOutputPayload {
-                    content: msg,
-                    success: None,
-                },
-            }))
-        }
-        Err(FunctionCallError::Fatal(message)) => Err(CodexErr::Fatal(message)),
+        _ => {}
     }
+
+    Ok(None)
 }
 
 pub(super) fn get_last_assistant_message_from_turn(responses: &[ResponseItem]) -> Option<String> {
@@ -2505,13 +2554,19 @@ mod tests {
 
         let out = format_exec_output_str(&exec);
 
+        // Strip truncation header if present for subsequent assertions
+        let body = out
+            .strip_prefix("Total output lines: ")
+            .and_then(|rest| rest.split_once("\n\n").map(|x| x.1))
+            .unwrap_or(out.as_str());
+
         // Expect elision marker with correct counts
         let omitted = 400 - MODEL_FORMAT_MAX_LINES; // 144
         let marker = format!("\n[... omitted {omitted} of 400 lines ...]\n\n");
         assert!(out.contains(&marker), "missing marker: {out}");
 
         // Validate head and tail
-        let parts: Vec<&str> = out.split(&marker).collect();
+        let parts: Vec<&str> = body.split(&marker).collect();
         assert_eq!(parts.len(), 2, "expected one marker split");
         let head = parts[0];
         let tail = parts[1];
@@ -2547,14 +2602,19 @@ mod tests {
         };
 
         let out = format_exec_output_str(&exec);
-        assert!(out.len() <= MODEL_FORMAT_MAX_BYTES, "exceeds byte budget");
+        // Keep strict budget on the truncated body (excluding header)
+        let body = out
+            .strip_prefix("Total output lines: ")
+            .and_then(|rest| rest.split_once("\n\n").map(|x| x.1))
+            .unwrap_or(out.as_str());
+        assert!(body.len() <= MODEL_FORMAT_MAX_BYTES, "exceeds byte budget");
         assert!(out.contains("omitted"), "should contain elision marker");
 
         // Ensure head and tail are drawn from the original
-        assert!(full.starts_with(out.chars().take(8).collect::<String>().as_str()));
+        assert!(full.starts_with(body.chars().take(8).collect::<String>().as_str()));
         assert!(
             full.ends_with(
-                out.chars()
+                body.chars()
                     .rev()
                     .take(8)
                     .collect::<String>()
@@ -2901,13 +2961,10 @@ mod tests {
     #[tokio::test]
     async fn fatal_tool_error_stops_turn_and_reports_error() {
         let (session, turn_context, _rx) = make_session_and_context_with_rx();
-        let session_ref = session.as_ref();
-        let turn_context_ref = turn_context.as_ref();
         let router = ToolRouter::from_config(
-            &turn_context_ref.tools_config,
-            Some(session_ref.services.mcp_connection_manager.list_all_tools()),
+            &turn_context.tools_config,
+            Some(session.services.mcp_connection_manager.list_all_tools()),
         );
-        let mut tracker = TurnDiffTracker::new();
         let item = ResponseItem::CustomToolCall {
             id: None,
             status: None,
@@ -2916,22 +2973,26 @@ mod tests {
             input: "{}".to_string(),
         };
 
-        let err = handle_response_item(
-            &router,
-            session_ref,
-            turn_context_ref,
-            &mut tracker,
-            "sub-id",
-            item,
-        )
-        .await
-        .expect_err("expected fatal error");
+        let call = ToolRouter::build_tool_call(session.as_ref(), item.clone())
+            .expect("build tool call")
+            .expect("tool call present");
+        let tracker = Arc::new(tokio::sync::Mutex::new(TurnDiffTracker::new()));
+        let err = router
+            .dispatch_tool_call(
+                Arc::clone(&session),
+                Arc::clone(&turn_context),
+                tracker,
+                "sub-id".to_string(),
+                call,
+            )
+            .await
+            .expect_err("expected fatal error");
 
         match err {
-            CodexErr::Fatal(message) => {
+            FunctionCallError::Fatal(message) => {
                 assert_eq!(message, "tool shell invoked with incompatible payload");
             }
-            other => panic!("expected CodexErr::Fatal, got {other:?}"),
+            other => panic!("expected FunctionCallError::Fatal, got {other:?}"),
         }
     }
 
@@ -3045,9 +3106,11 @@ mod tests {
         use crate::turn_diff_tracker::TurnDiffTracker;
         use std::collections::HashMap;
 
-        let (session, mut turn_context) = make_session_and_context();
+        let (session, mut turn_context_raw) = make_session_and_context();
         // Ensure policy is NOT OnRequest so the early rejection path triggers
-        turn_context.approval_policy = AskForApproval::OnFailure;
+        turn_context_raw.approval_policy = AskForApproval::OnFailure;
+        let session = Arc::new(session);
+        let mut turn_context = Arc::new(turn_context_raw);
 
         let params = ExecParams {
             command: if cfg!(windows) {
@@ -3075,7 +3138,7 @@ mod tests {
             ..params.clone()
         };
 
-        let mut turn_diff_tracker = TurnDiffTracker::new();
+        let turn_diff_tracker = Arc::new(tokio::sync::Mutex::new(TurnDiffTracker::new()));
 
         let tool_name = "shell";
         let sub_id = "test-sub".to_string();
@@ -3084,9 +3147,9 @@ mod tests {
         let resp = handle_container_exec_with_params(
             tool_name,
             params,
-            &session,
-            &turn_context,
-            &mut turn_diff_tracker,
+            Arc::clone(&session),
+            Arc::clone(&turn_context),
+            Arc::clone(&turn_diff_tracker),
             sub_id,
             call_id,
         )
@@ -3105,14 +3168,16 @@ mod tests {
 
         // Now retry the same command WITHOUT escalated permissions; should succeed.
         // Force DangerFullAccess to avoid platform sandbox dependencies in tests.
-        turn_context.sandbox_policy = SandboxPolicy::DangerFullAccess;
+        Arc::get_mut(&mut turn_context)
+            .expect("unique turn context Arc")
+            .sandbox_policy = SandboxPolicy::DangerFullAccess;
 
         let resp2 = handle_container_exec_with_params(
             tool_name,
             params2,
-            &session,
-            &turn_context,
-            &mut turn_diff_tracker,
+            Arc::clone(&session),
+            Arc::clone(&turn_context),
+            Arc::clone(&turn_diff_tracker),
             "test-sub".to_string(),
             "test-call-2".to_string(),
         )

codex-rs/core/src/codex/compact.rs

@@ -103,6 +103,18 @@ async fn run_compact_task_inner(
             Err(CodexErr::Interrupted) => {
                 return;
             }
+            Err(e @ CodexErr::ContextWindowExceeded) => {
+                sess.set_total_tokens_full(&sub_id, turn_context.as_ref())
+                    .await;
+                let event = Event {
+                    id: sub_id.clone(),
+                    msg: EventMsg::Error(ErrorEvent {
+                        message: e.to_string(),
+                    }),
+                };
+                sess.send_event(event).await;
+                return;
+            }
             Err(e) => {
                 if retries < max_retries {
                     retries += 1;

codex-rs/core/src/config.rs

@@ -209,6 +209,9 @@ pub struct Config {
     /// The active profile name used to derive this `Config` (if any).
     pub active_profile: Option<String>,
 
+    /// Tracks whether the Windows onboarding screen has been acknowledged.
+    pub windows_wsl_setup_acknowledged: bool,
+
     /// When true, disables burst-paste detection for typed input entirely.
     /// All characters are inserted as they are received, and no buffering
     /// or placeholder replacement will occur for fast keypress bursts.
@@ -471,6 +474,29 @@ pub fn set_project_trusted(codex_home: &Path, project_path: &Path) -> anyhow::Re
     Ok(())
 }
 
+/// Persist the acknowledgement flag for the Windows onboarding screen.
+pub fn set_windows_wsl_setup_acknowledged(
+    codex_home: &Path,
+    acknowledged: bool,
+) -> anyhow::Result<()> {
+    let config_path = codex_home.join(CONFIG_TOML_FILE);
+    let mut doc = match std::fs::read_to_string(config_path.clone()) {
+        Ok(s) => s.parse::<DocumentMut>()?,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => DocumentMut::new(),
+        Err(e) => return Err(e.into()),
+    };
+
+    doc["windows_wsl_setup_acknowledged"] = toml_edit::value(acknowledged);
+
+    std::fs::create_dir_all(codex_home)?;
+
+    let tmp_file = NamedTempFile::new_in(codex_home)?;
+    std::fs::write(tmp_file.path(), doc.to_string())?;
+    tmp_file.persist(config_path)?;
+
+    Ok(())
+}
+
 fn ensure_profile_table<'a>(
     doc: &'a mut DocumentMut,
     profile_name: &str,
@@ -724,6 +750,7 @@ pub struct ConfigToml {
     pub experimental_use_exec_command_tool: Option<bool>,
     pub experimental_use_unified_exec_tool: Option<bool>,
     pub experimental_use_rmcp_client: Option<bool>,
+    pub experimental_use_freeform_apply_patch: Option<bool>,
 
     pub projects: Option<HashMap<String, ProjectConfig>>,
 
@@ -737,6 +764,9 @@ pub struct ConfigToml {
 
     /// OTEL configuration.
     pub otel: Option<crate::config_types::OtelConfigToml>,
+
+    /// Tracks whether the Windows onboarding screen has been acknowledged.
+    pub windows_wsl_setup_acknowledged: Option<bool>,
 }
 
 impl From<ConfigToml> for UserSavedConfig {
@@ -1082,7 +1112,9 @@ impl Config {
                 .or(cfg.chatgpt_base_url)
                 .unwrap_or("https://chatgpt.com/backend-api/".to_string()),
             include_plan_tool: include_plan_tool.unwrap_or(false),
-            include_apply_patch_tool: include_apply_patch_tool.unwrap_or(false),
+            include_apply_patch_tool: include_apply_patch_tool
+                .or(cfg.experimental_use_freeform_apply_patch)
+                .unwrap_or(false),
             tools_web_search_request,
             use_experimental_streamable_shell_tool: cfg
                 .experimental_use_exec_command_tool
@@ -1093,6 +1125,7 @@ impl Config {
             use_experimental_use_rmcp_client: cfg.experimental_use_rmcp_client.unwrap_or(false),
             include_view_image_tool,
             active_profile: active_profile_name,
+            windows_wsl_setup_acknowledged: cfg.windows_wsl_setup_acknowledged.unwrap_or(false),
             disable_paste_burst: cfg.disable_paste_burst.unwrap_or(false),
             tui_notifications: cfg
                 .tui
@@ -1885,6 +1918,7 @@ model_verbosity = "high"
                 use_experimental_use_rmcp_client: false,
                 include_view_image_tool: true,
                 active_profile: Some("o3".to_string()),
+                windows_wsl_setup_acknowledged: false,
                 disable_paste_burst: false,
                 tui_notifications: Default::default(),
                 otel: OtelConfig::default(),
@@ -1946,6 +1980,7 @@ model_verbosity = "high"
             use_experimental_use_rmcp_client: false,
             include_view_image_tool: true,
             active_profile: Some("gpt3".to_string()),
+            windows_wsl_setup_acknowledged: false,
             disable_paste_burst: false,
             tui_notifications: Default::default(),
             otel: OtelConfig::default(),
@@ -2022,6 +2057,7 @@ model_verbosity = "high"
             use_experimental_use_rmcp_client: false,
             include_view_image_tool: true,
             active_profile: Some("zdr".to_string()),
+            windows_wsl_setup_acknowledged: false,
             disable_paste_burst: false,
             tui_notifications: Default::default(),
             otel: OtelConfig::default(),
@@ -2084,6 +2120,7 @@ model_verbosity = "high"
             use_experimental_use_rmcp_client: false,
             include_view_image_tool: true,
             active_profile: Some("gpt5".to_string()),
+            windows_wsl_setup_acknowledged: false,
             disable_paste_burst: false,
             tui_notifications: Default::default(),
             otel: OtelConfig::default(),

codex-rs/core/src/conversation_manager.rs

@@ -236,7 +236,7 @@ mod tests {
 
     #[test]
     fn drops_from_last_user_only() {
-        let items = vec![
+        let items = [
             user_msg("u1"),
             assistant_msg("a1"),
             assistant_msg("a2"),

codex-rs/core/src/error.rs

@@ -55,6 +55,11 @@ pub enum CodexErr {
     #[error("stream disconnected before completion: {0}")]
     Stream(String, Option<Duration>),
 
+    #[error(
+        "Codex ran out of room in the model's context window. Start a new conversation or clear earlier history before retrying."
+    )]
+    ContextWindowExceeded,
+
     #[error("no conversation with id: {0}")]
     ConversationNotFound(ConversationId),
 

codex-rs/core/src/model_family.rs

@@ -35,6 +35,10 @@ pub struct ModelFamily {
     // See https://platform.openai.com/docs/guides/tools-local-shell
     pub uses_local_shell_tool: bool,
 
+    /// Whether this model supports parallel tool calls when using the
+    /// Responses API.
+    pub supports_parallel_tool_calls: bool,
+
     /// Present if the model performs better when `apply_patch` is provided as
     /// a tool call instead of just a bash command
     pub apply_patch_tool_type: Option<ApplyPatchToolType>,
@@ -58,6 +62,7 @@ macro_rules! model_family {
             supports_reasoning_summaries: false,
             reasoning_summary_format: ReasoningSummaryFormat::None,
             uses_local_shell_tool: false,
+            supports_parallel_tool_calls: false,
             apply_patch_tool_type: None,
             base_instructions: BASE_INSTRUCTIONS.to_string(),
             experimental_supported_tools: Vec::new(),
@@ -72,7 +77,11 @@ macro_rules! model_family {
 
 /// Returns a `ModelFamily` for the given model slug, or `None` if the slug
 /// does not match any known model family.
-pub fn find_family_for_model(slug: &str) -> Option<ModelFamily> {
+pub fn find_family_for_model(mut slug: &str) -> Option<ModelFamily> {
+    // TODO(jif) clean once we have proper feature flags
+    if matches!(std::env::var("CODEX_EXPERIMENTAL").as_deref(), Ok("1")) {
+        slug = "codex-experimental";
+    }
     if slug.starts_with("o3") {
         model_family!(
             slug, "o3",
@@ -103,13 +112,39 @@ pub fn find_family_for_model(slug: &str) -> Option<ModelFamily> {
         model_family!(slug, "gpt-4o", needs_special_apply_patch_instructions: true)
     } else if slug.starts_with("gpt-3.5") {
         model_family!(slug, "gpt-3.5", needs_special_apply_patch_instructions: true)
-    } else if slug.starts_with("codex-") || slug.starts_with("gpt-5-codex") {
+    } else if slug.starts_with("test-gpt-5-codex") {
         model_family!(
             slug, slug,
             supports_reasoning_summaries: true,
             reasoning_summary_format: ReasoningSummaryFormat::Experimental,
             base_instructions: GPT_5_CODEX_INSTRUCTIONS.to_string(),
+            experimental_supported_tools: vec![
+                "read_file".to_string(),
+                "test_sync_tool".to_string()
+            ],
+            supports_parallel_tool_calls: true,
+        )
+
+    // Internal models.
+    } else if slug.starts_with("codex-") {
+        model_family!(
+            slug, slug,
+            supports_reasoning_summaries: true,
+            reasoning_summary_format: ReasoningSummaryFormat::Experimental,
+            base_instructions: GPT_5_CODEX_INSTRUCTIONS.to_string(),
+            apply_patch_tool_type: Some(ApplyPatchToolType::Freeform),
             experimental_supported_tools: vec!["read_file".to_string()],
+            supports_parallel_tool_calls: true,
+        )
+
+    // Production models.
+    } else if slug.starts_with("gpt-5-codex") {
+        model_family!(
+            slug, slug,
+            supports_reasoning_summaries: true,
+            reasoning_summary_format: ReasoningSummaryFormat::Experimental,
+            base_instructions: GPT_5_CODEX_INSTRUCTIONS.to_string(),
+            apply_patch_tool_type: Some(ApplyPatchToolType::Freeform),
         )
     } else if slug.starts_with("gpt-5") {
         model_family!(
@@ -130,6 +165,7 @@ pub fn derive_default_model_family(model: &str) -> ModelFamily {
         supports_reasoning_summaries: false,
         reasoning_summary_format: ReasoningSummaryFormat::None,
         uses_local_shell_tool: false,
+        supports_parallel_tool_calls: false,
         apply_patch_tool_type: None,
         base_instructions: BASE_INSTRUCTIONS.to_string(),
         experimental_supported_tools: Vec::new(),

codex-rs/core/src/state/session.rs

@@ -64,5 +64,14 @@ impl SessionState {
         (self.token_info.clone(), self.latest_rate_limits.clone())
     }
 
+    pub(crate) fn set_token_usage_full(&mut self, context_window: u64) {
+        match &mut self.token_info {
+            Some(info) => info.fill_to_context_window(context_window),
+            None => {
+                self.token_info = Some(TokenUsageInfo::full_context_window(context_window));
+            }
+        }
+    }
+
     // Pending input/approval moved to TurnState.
 }

codex-rs/core/src/tools/context.rs

@@ -14,12 +14,17 @@ use mcp_types::CallToolResult;
 use std::borrow::Cow;
 use std::collections::HashMap;
 use std::path::PathBuf;
+use std::sync::Arc;
+use tokio::sync::Mutex;
 
-pub struct ToolInvocation<'a> {
-    pub session: &'a Session,
-    pub turn: &'a TurnContext,
-    pub tracker: &'a mut TurnDiffTracker,
-    pub sub_id: &'a str,
+pub type SharedTurnDiffTracker = Arc<Mutex<TurnDiffTracker>>;
+
+#[derive(Clone)]
+pub struct ToolInvocation {
+    pub session: Arc<Session>,
+    pub turn: Arc<TurnContext>,
+    pub tracker: SharedTurnDiffTracker,
+    pub sub_id: String,
     pub call_id: String,
     pub tool_name: String,
     pub payload: ToolPayload,

codex-rs/core/src/tools/handlers/apply_patch.rs

@@ -1,5 +1,6 @@
 use std::collections::BTreeMap;
 use std::collections::HashMap;
+use std::sync::Arc;
 
 use crate::client_common::tools::FreeformTool;
 use crate::client_common::tools::FreeformToolFormat;
@@ -36,10 +37,7 @@ impl ToolHandler for ApplyPatchHandler {
         )
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session,
             turn,
@@ -79,10 +77,10 @@ impl ToolHandler for ApplyPatchHandler {
         let content = handle_container_exec_with_params(
             tool_name.as_str(),
             exec_params,
-            session,
-            turn,
-            tracker,
-            sub_id.to_string(),
+            Arc::clone(&session),
+            Arc::clone(&turn),
+            Arc::clone(&tracker),
+            sub_id.clone(),
             call_id.clone(),
         )
         .await?;
@@ -106,7 +104,7 @@ pub enum ApplyPatchToolType {
 pub(crate) fn create_apply_patch_freeform_tool() -> ToolSpec {
     ToolSpec::Freeform(FreeformTool {
         name: "apply_patch".to_string(),
-        description: "Use the `apply_patch` tool to edit files".to_string(),
+        description: "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.".to_string(),
         format: FreeformToolFormat {
             r#type: "grammar".to_string(),
             syntax: "lark".to_string(),

codex-rs/core/src/tools/handlers/exec_stream.rs

@@ -19,10 +19,7 @@ impl ToolHandler for ExecStreamHandler {
         ToolKind::Function
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session,
             tool_name,

codex-rs/core/src/tools/handlers/mcp.rs

@@ -16,10 +16,7 @@ impl ToolHandler for McpHandler {
         ToolKind::Mcp
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session,
             sub_id,
@@ -45,8 +42,8 @@ impl ToolHandler for McpHandler {
         let arguments_str = raw_arguments;
 
         let response = handle_mcp_tool_call(
-            session,
-            sub_id,
+            session.as_ref(),
+            &sub_id,
             call_id.clone(),
             server,
             tool,

codex-rs/core/src/tools/handlers/mod.rs

@@ -4,6 +4,7 @@ mod mcp;
 mod plan;
 mod read_file;
 mod shell;
+mod test_sync;
 mod unified_exec;
 mod view_image;
 
@@ -15,5 +16,6 @@ pub use mcp::McpHandler;
 pub use plan::PlanHandler;
 pub use read_file::ReadFileHandler;
 pub use shell::ShellHandler;
+pub use test_sync::TestSyncHandler;
 pub use unified_exec::UnifiedExecHandler;
 pub use view_image::ViewImageHandler;

codex-rs/core/src/tools/handlers/plan.rs

@@ -65,10 +65,7 @@ impl ToolHandler for PlanHandler {
         ToolKind::Function
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session,
             sub_id,
@@ -86,7 +83,8 @@ impl ToolHandler for PlanHandler {
             }
         };
 
-        let content = handle_update_plan(session, arguments, sub_id.to_string(), call_id).await?;
+        let content =
+            handle_update_plan(session.as_ref(), arguments, sub_id.clone(), call_id).await?;
 
         Ok(ToolOutput::Function {
             content,

codex-rs/core/src/tools/handlers/read_file.rs

@@ -42,10 +42,7 @@ impl ToolHandler for ReadFileHandler {
         ToolKind::Function
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation { payload, .. } = invocation;
 
         let arguments = match payload {

codex-rs/core/src/tools/handlers/shell.rs

@@ -1,5 +1,6 @@
 use async_trait::async_trait;
 use codex_protocol::models::ShellToolCallParams;
+use std::sync::Arc;
 
 use crate::codex::TurnContext;
 use crate::exec::ExecParams;
@@ -40,10 +41,7 @@ impl ToolHandler for ShellHandler {
         )
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session,
             turn,
@@ -62,14 +60,14 @@ impl ToolHandler for ShellHandler {
                             "failed to parse function arguments: {e:?}"
                         ))
                     })?;
-                let exec_params = Self::to_exec_params(params, turn);
+                let exec_params = Self::to_exec_params(params, turn.as_ref());
                 let content = handle_container_exec_with_params(
                     tool_name.as_str(),
                     exec_params,
-                    session,
-                    turn,
-                    tracker,
-                    sub_id.to_string(),
+                    Arc::clone(&session),
+                    Arc::clone(&turn),
+                    Arc::clone(&tracker),
+                    sub_id.clone(),
                     call_id.clone(),
                 )
                 .await?;
@@ -79,14 +77,14 @@ impl ToolHandler for ShellHandler {
                 })
             }
             ToolPayload::LocalShell { params } => {
-                let exec_params = Self::to_exec_params(params, turn);
+                let exec_params = Self::to_exec_params(params, turn.as_ref());
                 let content = handle_container_exec_with_params(
                     tool_name.as_str(),
                     exec_params,
-                    session,
-                    turn,
-                    tracker,
-                    sub_id.to_string(),
+                    Arc::clone(&session),
+                    Arc::clone(&turn),
+                    Arc::clone(&tracker),
+                    sub_id.clone(),
                     call_id.clone(),
                 )
                 .await?;

codex-rs/core/src/tools/handlers/test_sync.rs

@@ -0,0 +1,158 @@
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::sync::Arc;
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use serde::Deserialize;
+use tokio::sync::Barrier;
+use tokio::time::sleep;
+
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct TestSyncHandler;
+
+const DEFAULT_TIMEOUT_MS: u64 = 1_000;
+
+static BARRIERS: OnceLock<tokio::sync::Mutex<HashMap<String, BarrierState>>> = OnceLock::new();
+
+struct BarrierState {
+    barrier: Arc<Barrier>,
+    participants: usize,
+}
+
+#[derive(Debug, Deserialize)]
+struct BarrierArgs {
+    id: String,
+    participants: usize,
+    #[serde(default = "default_timeout_ms")]
+    timeout_ms: u64,
+}
+
+#[derive(Debug, Deserialize)]
+struct TestSyncArgs {
+    #[serde(default)]
+    sleep_before_ms: Option<u64>,
+    #[serde(default)]
+    sleep_after_ms: Option<u64>,
+    #[serde(default)]
+    barrier: Option<BarrierArgs>,
+}
+
+fn default_timeout_ms() -> u64 {
+    DEFAULT_TIMEOUT_MS
+}
+
+fn barrier_map() -> &'static tokio::sync::Mutex<HashMap<String, BarrierState>> {
+    BARRIERS.get_or_init(|| tokio::sync::Mutex::new(HashMap::new()))
+}
+
+#[async_trait]
+impl ToolHandler for TestSyncHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation { payload, .. } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "test_sync_tool handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let args: TestSyncArgs = serde_json::from_str(&arguments).map_err(|err| {
+            FunctionCallError::RespondToModel(format!(
+                "failed to parse function arguments: {err:?}"
+            ))
+        })?;
+
+        if let Some(delay) = args.sleep_before_ms
+            && delay > 0
+        {
+            sleep(Duration::from_millis(delay)).await;
+        }
+
+        if let Some(barrier) = args.barrier {
+            wait_on_barrier(barrier).await?;
+        }
+
+        if let Some(delay) = args.sleep_after_ms
+            && delay > 0
+        {
+            sleep(Duration::from_millis(delay)).await;
+        }
+
+        Ok(ToolOutput::Function {
+            content: "ok".to_string(),
+            success: Some(true),
+        })
+    }
+}
+
+async fn wait_on_barrier(args: BarrierArgs) -> Result<(), FunctionCallError> {
+    if args.participants == 0 {
+        return Err(FunctionCallError::RespondToModel(
+            "barrier participants must be greater than zero".to_string(),
+        ));
+    }
+
+    if args.timeout_ms == 0 {
+        return Err(FunctionCallError::RespondToModel(
+            "barrier timeout must be greater than zero".to_string(),
+        ));
+    }
+
+    let barrier_id = args.id.clone();
+    let barrier = {
+        let mut map = barrier_map().lock().await;
+        match map.entry(barrier_id.clone()) {
+            Entry::Occupied(entry) => {
+                let state = entry.get();
+                if state.participants != args.participants {
+                    let existing = state.participants;
+                    return Err(FunctionCallError::RespondToModel(format!(
+                        "barrier {barrier_id} already registered with {existing} participants"
+                    )));
+                }
+                state.barrier.clone()
+            }
+            Entry::Vacant(entry) => {
+                let barrier = Arc::new(Barrier::new(args.participants));
+                entry.insert(BarrierState {
+                    barrier: barrier.clone(),
+                    participants: args.participants,
+                });
+                barrier
+            }
+        }
+    };
+
+    let timeout = Duration::from_millis(args.timeout_ms);
+    let wait_result = tokio::time::timeout(timeout, barrier.wait())
+        .await
+        .map_err(|_| {
+            FunctionCallError::RespondToModel("test_sync_tool barrier wait timed out".to_string())
+        })?;
+
+    if wait_result.is_leader() {
+        let mut map = barrier_map().lock().await;
+        if let Some(state) = map.get(&barrier_id)
+            && Arc::ptr_eq(&state.barrier, &barrier)
+        {
+            map.remove(&barrier_id);
+        }
+    }
+
+    Ok(())
+}

codex-rs/core/src/tools/handlers/unified_exec.rs

@@ -33,10 +33,7 @@ impl ToolHandler for UnifiedExecHandler {
         )
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session, payload, ..
         } = invocation;

codex-rs/core/src/tools/handlers/view_image.rs

@@ -26,10 +26,7 @@ impl ToolHandler for ViewImageHandler {
         ToolKind::Function
     }
 
-    async fn handle(
-        &self,
-        invocation: ToolInvocation<'_>,
-    ) -> Result<ToolOutput, FunctionCallError> {
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
         let ToolInvocation {
             session,
             turn,

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

@@ -1,5 +1,6 @@
 pub mod context;
 pub(crate) mod handlers;
+pub mod parallel;
 pub mod registry;
 pub mod router;
 pub mod spec;
@@ -21,7 +22,7 @@ use crate::executor::linkers::PreparedExec;
 use crate::function_tool::FunctionCallError;
 use crate::tools::context::ApplyPatchCommandContext;
 use crate::tools::context::ExecCommandContext;
-use crate::turn_diff_tracker::TurnDiffTracker;
+use crate::tools::context::SharedTurnDiffTracker;
 use codex_apply_patch::MaybeApplyPatchVerified;
 use codex_apply_patch::maybe_parse_apply_patch_verified;
 use codex_protocol::protocol::AskForApproval;
@@ -29,6 +30,7 @@ use codex_utils_string::take_bytes_at_char_boundary;
 use codex_utils_string::take_last_bytes_at_char_boundary;
 pub use router::ToolRouter;
 use serde::Serialize;
+use std::sync::Arc;
 use tracing::trace;
 
 // Model-formatting limits: clients get full streams; only content sent to the model is truncated.
@@ -48,9 +50,9 @@ pub(crate) const TELEMETRY_PREVIEW_TRUNCATION_NOTICE: &str =
 pub(crate) async fn handle_container_exec_with_params(
     tool_name: &str,
     params: ExecParams,
-    sess: &Session,
-    turn_context: &TurnContext,
-    turn_diff_tracker: &mut TurnDiffTracker,
+    sess: Arc<Session>,
+    turn_context: Arc<TurnContext>,
+    turn_diff_tracker: SharedTurnDiffTracker,
     sub_id: String,
     call_id: String,
 ) -> Result<String, FunctionCallError> {
@@ -68,7 +70,15 @@ pub(crate) async fn handle_container_exec_with_params(
     // check if this was a patch, and apply it if so
     let apply_patch_exec = match maybe_parse_apply_patch_verified(&params.command, &params.cwd) {
         MaybeApplyPatchVerified::Body(changes) => {
-            match apply_patch::apply_patch(sess, turn_context, &sub_id, &call_id, changes).await {
+            match apply_patch::apply_patch(
+                sess.as_ref(),
+                turn_context.as_ref(),
+                &sub_id,
+                &call_id,
+                changes,
+            )
+            .await
+            {
                 InternalApplyPatchInvocation::Output(item) => return item,
                 InternalApplyPatchInvocation::DelegateToExec(apply_patch_exec) => {
                     Some(apply_patch_exec)
@@ -139,12 +149,13 @@ pub(crate) async fn handle_container_exec_with_params(
 
     let output_result = sess
         .run_exec_with_events(
-            turn_diff_tracker,
+            turn_diff_tracker.clone(),
             prepared_exec,
             turn_context.approval_policy,
         )
         .await;
 
+    // always make sure to truncate the output if its length isn't controlled.
     match output_result {
         Ok(output) => {
             let ExecToolCallOutput { exit_code, .. } = &output;
@@ -155,13 +166,16 @@ pub(crate) async fn handle_container_exec_with_params(
                 Err(FunctionCallError::RespondToModel(content))
             }
         }
-        Err(ExecError::Function(err)) => Err(err),
+        Err(ExecError::Function(err)) => Err(truncate_function_error(err)),
         Err(ExecError::Codex(CodexErr::Sandbox(SandboxErr::Timeout { output }))) => Err(
             FunctionCallError::RespondToModel(format_exec_output_apply_patch(&output)),
         ),
-        Err(ExecError::Codex(err)) => Err(FunctionCallError::RespondToModel(format!(
-            "execution error: {err:?}"
-        ))),
+        Err(ExecError::Codex(err)) => {
+            let message = format!("execution error: {err:?}");
+            Err(FunctionCallError::RespondToModel(format_exec_output(
+                &message,
+            )))
+        }
     }
 }
 
@@ -206,26 +220,42 @@ pub fn format_exec_output_str(exec_output: &ExecToolCallOutput) -> String {
         aggregated_output, ..
     } = exec_output;
 
-    // Head+tail truncation for the model: show the beginning and end with an elision.
-    // Clients still receive full streams; only this formatted summary is capped.
-
-    let mut s = &aggregated_output.text;
-    let prefixed_str: String;
+    let content = aggregated_output.text.as_str();
 
     if exec_output.timed_out {
-        prefixed_str = format!(
-            "command timed out after {} milliseconds\n",
+        let prefixed = format!(
+            "command timed out after {} milliseconds\n{content}",
             exec_output.duration.as_millis()
-        ) + s;
-        s = &prefixed_str;
+        );
+        return format_exec_output(&prefixed);
     }
 
-    let total_lines = s.lines().count();
-    if s.len() <= MODEL_FORMAT_MAX_BYTES && total_lines <= MODEL_FORMAT_MAX_LINES {
-        return s.to_string();
-    }
+    format_exec_output(content)
+}
 
-    let segments: Vec<&str> = s.split_inclusive('\n').collect();
+fn truncate_function_error(err: FunctionCallError) -> FunctionCallError {
+    match err {
+        FunctionCallError::RespondToModel(msg) => {
+            FunctionCallError::RespondToModel(format_exec_output(&msg))
+        }
+        FunctionCallError::Fatal(msg) => FunctionCallError::Fatal(format_exec_output(&msg)),
+        other => other,
+    }
+}
+
+fn format_exec_output(content: &str) -> String {
+    // Head+tail truncation for the model: show the beginning and end with an elision.
+    // Clients still receive full streams; only this formatted summary is capped.
+    let total_lines = content.lines().count();
+    if content.len() <= MODEL_FORMAT_MAX_BYTES && total_lines <= MODEL_FORMAT_MAX_LINES {
+        return content.to_string();
+    }
+    let output = truncate_formatted_exec_output(content, total_lines);
+    format!("Total output lines: {total_lines}\n\n{output}")
+}
+
+fn truncate_formatted_exec_output(content: &str, total_lines: usize) -> String {
+    let segments: Vec<&str> = content.split_inclusive('\n').collect();
     let head_take = MODEL_FORMAT_HEAD_LINES.min(segments.len());
     let tail_take = MODEL_FORMAT_TAIL_LINES.min(segments.len().saturating_sub(head_take));
     let omitted = segments.len().saturating_sub(head_take + tail_take);
@@ -236,9 +266,9 @@ pub fn format_exec_output_str(exec_output: &ExecToolCallOutput) -> String {
         .map(|segment| segment.len())
         .sum();
     let tail_slice_start: usize = if tail_take == 0 {
-        s.len()
+        content.len()
     } else {
-        s.len()
+        content.len()
             - segments
                 .iter()
                 .rev()
@@ -260,9 +290,9 @@ pub fn format_exec_output_str(exec_output: &ExecToolCallOutput) -> String {
         head_budget = MODEL_FORMAT_MAX_BYTES.saturating_sub(marker.len());
     }
 
-    let head_slice = &s[..head_slice_end];
+    let head_slice = &content[..head_slice_end];
     let head_part = take_bytes_at_char_boundary(head_slice, head_budget);
-    let mut result = String::with_capacity(MODEL_FORMAT_MAX_BYTES.min(s.len()));
+    let mut result = String::with_capacity(MODEL_FORMAT_MAX_BYTES.min(content.len()));
 
     result.push_str(head_part);
     result.push_str(&marker);
@@ -272,9 +302,86 @@ pub fn format_exec_output_str(exec_output: &ExecToolCallOutput) -> String {
         return result;
     }
 
-    let tail_slice = &s[tail_slice_start..];
+    let tail_slice = &content[tail_slice_start..];
     let tail_part = take_last_bytes_at_char_boundary(tail_slice, remaining);
     result.push_str(tail_part);
 
     result
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use regex_lite::Regex;
+
+    fn assert_truncated_message_matches(message: &str, line: &str, total_lines: usize) {
+        let pattern = truncated_message_pattern(line, total_lines);
+        let regex = Regex::new(&pattern).unwrap_or_else(|err| {
+            panic!("failed to compile regex {pattern}: {err}");
+        });
+        let captures = regex
+            .captures(message)
+            .unwrap_or_else(|| panic!("message failed to match pattern {pattern}: {message}"));
+        let body = captures
+            .name("body")
+            .expect("missing body capture")
+            .as_str();
+        assert!(
+            body.len() <= MODEL_FORMAT_MAX_BYTES,
+            "body exceeds byte limit: {} bytes",
+            body.len()
+        );
+    }
+
+    fn truncated_message_pattern(line: &str, total_lines: usize) -> String {
+        let head_take = MODEL_FORMAT_HEAD_LINES.min(total_lines);
+        let tail_take = MODEL_FORMAT_TAIL_LINES.min(total_lines.saturating_sub(head_take));
+        let omitted = total_lines.saturating_sub(head_take + tail_take);
+        let escaped_line = regex_lite::escape(line);
+        format!(
+            r"(?s)^Total output lines: {total_lines}\n\n(?P<body>{escaped_line}.*\n\[\.{{3}} omitted {omitted} of {total_lines} lines \.{{3}}]\n\n.*)$",
+        )
+    }
+
+    #[test]
+    fn truncate_formatted_exec_output_truncates_large_error() {
+        let line = "very long execution error line that should trigger truncation\n";
+        let large_error = line.repeat(2_500); // way beyond both byte and line limits
+
+        let truncated = format_exec_output(&large_error);
+
+        let total_lines = large_error.lines().count();
+        assert_truncated_message_matches(&truncated, line, total_lines);
+        assert_ne!(truncated, large_error);
+    }
+
+    #[test]
+    fn truncate_function_error_trims_respond_to_model() {
+        let line = "respond-to-model error that should be truncated\n";
+        let huge = line.repeat(3_000);
+        let total_lines = huge.lines().count();
+
+        let err = truncate_function_error(FunctionCallError::RespondToModel(huge));
+        match err {
+            FunctionCallError::RespondToModel(message) => {
+                assert_truncated_message_matches(&message, line, total_lines);
+            }
+            other => panic!("unexpected error variant: {other:?}"),
+        }
+    }
+
+    #[test]
+    fn truncate_function_error_trims_fatal() {
+        let line = "fatal error output that should be truncated\n";
+        let huge = line.repeat(3_000);
+        let total_lines = huge.lines().count();
+
+        let err = truncate_function_error(FunctionCallError::Fatal(huge));
+        match err {
+            FunctionCallError::Fatal(message) => {
+                assert_truncated_message_matches(&message, line, total_lines);
+            }
+            other => panic!("unexpected error variant: {other:?}"),
+        }
+    }
+}

codex-rs/core/src/tools/parallel.rs

@@ -0,0 +1,137 @@
+use std::sync::Arc;
+
+use tokio::task::JoinHandle;
+
+use crate::codex::Session;
+use crate::codex::TurnContext;
+use crate::error::CodexErr;
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::SharedTurnDiffTracker;
+use crate::tools::router::ToolCall;
+use crate::tools::router::ToolRouter;
+use codex_protocol::models::ResponseInputItem;
+
+use crate::codex::ProcessedResponseItem;
+
+struct PendingToolCall {
+    index: usize,
+    handle: JoinHandle<Result<ResponseInputItem, FunctionCallError>>,
+}
+
+pub(crate) struct ToolCallRuntime {
+    router: Arc<ToolRouter>,
+    session: Arc<Session>,
+    turn_context: Arc<TurnContext>,
+    tracker: SharedTurnDiffTracker,
+    sub_id: String,
+    pending_calls: Vec<PendingToolCall>,
+}
+
+impl ToolCallRuntime {
+    pub(crate) fn new(
+        router: Arc<ToolRouter>,
+        session: Arc<Session>,
+        turn_context: Arc<TurnContext>,
+        tracker: SharedTurnDiffTracker,
+        sub_id: String,
+    ) -> Self {
+        Self {
+            router,
+            session,
+            turn_context,
+            tracker,
+            sub_id,
+            pending_calls: Vec::new(),
+        }
+    }
+
+    pub(crate) async fn handle_tool_call(
+        &mut self,
+        call: ToolCall,
+        output_index: usize,
+        output: &mut [ProcessedResponseItem],
+    ) -> Result<(), CodexErr> {
+        let supports_parallel = self.router.tool_supports_parallel(&call.tool_name);
+        if supports_parallel {
+            self.spawn_parallel(call, output_index);
+        } else {
+            self.resolve_pending(output).await?;
+            let response = self.dispatch_serial(call).await?;
+            let slot = output.get_mut(output_index).ok_or_else(|| {
+                CodexErr::Fatal(format!("tool output index {output_index} out of bounds"))
+            })?;
+            slot.response = Some(response);
+        }
+
+        Ok(())
+    }
+
+    pub(crate) fn abort_all(&mut self) {
+        while let Some(pending) = self.pending_calls.pop() {
+            pending.handle.abort();
+        }
+    }
+
+    pub(crate) async fn resolve_pending(
+        &mut self,
+        output: &mut [ProcessedResponseItem],
+    ) -> Result<(), CodexErr> {
+        while let Some(PendingToolCall { index, handle }) = self.pending_calls.pop() {
+            match handle.await {
+                Ok(Ok(response)) => {
+                    if let Some(slot) = output.get_mut(index) {
+                        slot.response = Some(response);
+                    }
+                }
+                Ok(Err(FunctionCallError::Fatal(message))) => {
+                    self.abort_all();
+                    return Err(CodexErr::Fatal(message));
+                }
+                Ok(Err(other)) => {
+                    self.abort_all();
+                    return Err(CodexErr::Fatal(other.to_string()));
+                }
+                Err(join_err) => {
+                    self.abort_all();
+                    return Err(CodexErr::Fatal(format!(
+                        "tool task failed to join: {join_err}"
+                    )));
+                }
+            }
+        }
+
+        Ok(())
+    }
+
+    fn spawn_parallel(&mut self, call: ToolCall, index: usize) {
+        let router = Arc::clone(&self.router);
+        let session = Arc::clone(&self.session);
+        let turn = Arc::clone(&self.turn_context);
+        let tracker = Arc::clone(&self.tracker);
+        let sub_id = self.sub_id.clone();
+        let handle = tokio::spawn(async move {
+            router
+                .dispatch_tool_call(session, turn, tracker, sub_id, call)
+                .await
+        });
+        self.pending_calls.push(PendingToolCall { index, handle });
+    }
+
+    async fn dispatch_serial(&self, call: ToolCall) -> Result<ResponseInputItem, CodexErr> {
+        match self
+            .router
+            .dispatch_tool_call(
+                Arc::clone(&self.session),
+                Arc::clone(&self.turn_context),
+                Arc::clone(&self.tracker),
+                self.sub_id.clone(),
+                call,
+            )
+            .await
+        {
+            Ok(response) => Ok(response),
+            Err(FunctionCallError::Fatal(message)) => Err(CodexErr::Fatal(message)),
+            Err(other) => Err(CodexErr::Fatal(other.to_string())),
+        }
+    }
+}

codex-rs/core/src/tools/registry.rs

@@ -32,8 +32,7 @@ pub trait ToolHandler: Send + Sync {
         )
     }
 
-    async fn handle(&self, invocation: ToolInvocation<'_>)
-    -> Result<ToolOutput, FunctionCallError>;
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError>;
 }
 
 pub struct ToolRegistry {
@@ -57,9 +56,9 @@ impl ToolRegistry {
     //     }
     // }
 
-    pub async fn dispatch<'a>(
+    pub async fn dispatch(
         &self,
-        invocation: ToolInvocation<'a>,
+        invocation: ToolInvocation,
     ) -> Result<ResponseInputItem, FunctionCallError> {
         let tool_name = invocation.tool_name.clone();
         let call_id_owned = invocation.call_id.clone();
@@ -137,9 +136,24 @@ impl ToolRegistry {
     }
 }
 
+#[derive(Debug, Clone)]
+pub struct ConfiguredToolSpec {
+    pub spec: ToolSpec,
+    pub supports_parallel_tool_calls: bool,
+}
+
+impl ConfiguredToolSpec {
+    pub fn new(spec: ToolSpec, supports_parallel_tool_calls: bool) -> Self {
+        Self {
+            spec,
+            supports_parallel_tool_calls,
+        }
+    }
+}
+
 pub struct ToolRegistryBuilder {
     handlers: HashMap<String, Arc<dyn ToolHandler>>,
-    specs: Vec<ToolSpec>,
+    specs: Vec<ConfiguredToolSpec>,
 }
 
 impl ToolRegistryBuilder {
@@ -151,7 +165,16 @@ impl ToolRegistryBuilder {
     }
 
     pub fn push_spec(&mut self, spec: ToolSpec) {
-        self.specs.push(spec);
+        self.push_spec_with_parallel_support(spec, false);
+    }
+
+    pub fn push_spec_with_parallel_support(
+        &mut self,
+        spec: ToolSpec,
+        supports_parallel_tool_calls: bool,
+    ) {
+        self.specs
+            .push(ConfiguredToolSpec::new(spec, supports_parallel_tool_calls));
     }
 
     pub fn register_handler(&mut self, name: impl Into<String>, handler: Arc<dyn ToolHandler>) {
@@ -183,7 +206,7 @@ impl ToolRegistryBuilder {
     //     }
     // }
 
-    pub fn build(self) -> (Vec<ToolSpec>, ToolRegistry) {
+    pub fn build(self) -> (Vec<ConfiguredToolSpec>, ToolRegistry) {
         let registry = ToolRegistry::new(self.handlers);
         (self.specs, registry)
     }

codex-rs/core/src/tools/router.rs

@@ -1,15 +1,17 @@
 use std::collections::HashMap;
+use std::sync::Arc;
 
 use crate::client_common::tools::ToolSpec;
 use crate::codex::Session;
 use crate::codex::TurnContext;
 use crate::function_tool::FunctionCallError;
+use crate::tools::context::SharedTurnDiffTracker;
 use crate::tools::context::ToolInvocation;
 use crate::tools::context::ToolPayload;
+use crate::tools::registry::ConfiguredToolSpec;
 use crate::tools::registry::ToolRegistry;
 use crate::tools::spec::ToolsConfig;
 use crate::tools::spec::build_specs;
-use crate::turn_diff_tracker::TurnDiffTracker;
 use codex_protocol::models::LocalShellAction;
 use codex_protocol::models::ResponseInputItem;
 use codex_protocol::models::ResponseItem;
@@ -24,7 +26,7 @@ pub struct ToolCall {
 
 pub struct ToolRouter {
     registry: ToolRegistry,
-    specs: Vec<ToolSpec>,
+    specs: Vec<ConfiguredToolSpec>,
 }
 
 impl ToolRouter {
@@ -34,11 +36,22 @@ impl ToolRouter {
     ) -> Self {
         let builder = build_specs(config, mcp_tools);
         let (specs, registry) = builder.build();
+
         Self { registry, specs }
     }
 
-    pub fn specs(&self) -> &[ToolSpec] {
-        &self.specs
+    pub fn specs(&self) -> Vec<ToolSpec> {
+        self.specs
+            .iter()
+            .map(|config| config.spec.clone())
+            .collect()
+    }
+
+    pub fn tool_supports_parallel(&self, tool_name: &str) -> bool {
+        self.specs
+            .iter()
+            .filter(|config| config.supports_parallel_tool_calls)
+            .any(|config| config.spec.name() == tool_name)
     }
 
     pub fn build_tool_call(
@@ -118,10 +131,10 @@ impl ToolRouter {
 
     pub async fn dispatch_tool_call(
         &self,
-        session: &Session,
-        turn: &TurnContext,
-        tracker: &mut TurnDiffTracker,
-        sub_id: &str,
+        session: Arc<Session>,
+        turn: Arc<TurnContext>,
+        tracker: SharedTurnDiffTracker,
+        sub_id: String,
         call: ToolCall,
     ) -> Result<ResponseInputItem, FunctionCallError> {
         let ToolCall {

codex-rs/core/src/tools/spec.rs

@@ -258,6 +258,68 @@ fn create_view_image_tool() -> ToolSpec {
     })
 }
 
+fn create_test_sync_tool() -> ToolSpec {
+    let mut properties = BTreeMap::new();
+    properties.insert(
+        "sleep_before_ms".to_string(),
+        JsonSchema::Number {
+            description: Some("Optional delay in milliseconds before any other action".to_string()),
+        },
+    );
+    properties.insert(
+        "sleep_after_ms".to_string(),
+        JsonSchema::Number {
+            description: Some(
+                "Optional delay in milliseconds after completing the barrier".to_string(),
+            ),
+        },
+    );
+
+    let mut barrier_properties = BTreeMap::new();
+    barrier_properties.insert(
+        "id".to_string(),
+        JsonSchema::String {
+            description: Some(
+                "Identifier shared by concurrent calls that should rendezvous".to_string(),
+            ),
+        },
+    );
+    barrier_properties.insert(
+        "participants".to_string(),
+        JsonSchema::Number {
+            description: Some(
+                "Number of tool calls that must arrive before the barrier opens".to_string(),
+            ),
+        },
+    );
+    barrier_properties.insert(
+        "timeout_ms".to_string(),
+        JsonSchema::Number {
+            description: Some("Maximum time in milliseconds to wait at the barrier".to_string()),
+        },
+    );
+
+    properties.insert(
+        "barrier".to_string(),
+        JsonSchema::Object {
+            properties: barrier_properties,
+            required: Some(vec!["id".to_string(), "participants".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+    );
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "test_sync_tool".to_string(),
+        description: "Internal synchronization helper used by Codex integration tests.".to_string(),
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: None,
+            additional_properties: Some(false.into()),
+        },
+    })
+}
+
 fn create_read_file_tool() -> ToolSpec {
     let mut properties = BTreeMap::new();
     properties.insert(
@@ -507,6 +569,7 @@ pub(crate) fn build_specs(
     use crate::tools::handlers::PlanHandler;
     use crate::tools::handlers::ReadFileHandler;
     use crate::tools::handlers::ShellHandler;
+    use crate::tools::handlers::TestSyncHandler;
     use crate::tools::handlers::UnifiedExecHandler;
     use crate::tools::handlers::ViewImageHandler;
     use std::sync::Arc;
@@ -573,16 +636,26 @@ pub(crate) fn build_specs(
         .any(|tool| tool == "read_file")
     {
         let read_file_handler = Arc::new(ReadFileHandler);
-        builder.push_spec(create_read_file_tool());
+        builder.push_spec_with_parallel_support(create_read_file_tool(), true);
         builder.register_handler("read_file", read_file_handler);
     }
 
+    if config
+        .experimental_supported_tools
+        .iter()
+        .any(|tool| tool == "test_sync_tool")
+    {
+        let test_sync_handler = Arc::new(TestSyncHandler);
+        builder.push_spec_with_parallel_support(create_test_sync_tool(), true);
+        builder.register_handler("test_sync_tool", test_sync_handler);
+    }
+
     if config.web_search_request {
         builder.push_spec(ToolSpec::WebSearch {});
     }
 
     if config.include_view_image_tool {
-        builder.push_spec(create_view_image_tool());
+        builder.push_spec_with_parallel_support(create_view_image_tool(), true);
         builder.register_handler("view_image", view_image_handler);
     }
 
@@ -610,20 +683,25 @@ pub(crate) fn build_specs(
 mod tests {
     use crate::client_common::tools::FreeformTool;
     use crate::model_family::find_family_for_model;
+    use crate::tools::registry::ConfiguredToolSpec;
     use mcp_types::ToolInputSchema;
     use pretty_assertions::assert_eq;
 
     use super::*;
 
-    fn assert_eq_tool_names(tools: &[ToolSpec], expected_names: &[&str]) {
+    fn tool_name(tool: &ToolSpec) -> &str {
+        match tool {
+            ToolSpec::Function(ResponsesApiTool { name, .. }) => name,
+            ToolSpec::LocalShell {} => "local_shell",
+            ToolSpec::WebSearch {} => "web_search",
+            ToolSpec::Freeform(FreeformTool { name, .. }) => name,
+        }
+    }
+
+    fn assert_eq_tool_names(tools: &[ConfiguredToolSpec], expected_names: &[&str]) {
         let tool_names = tools
             .iter()
-            .map(|tool| match tool {
-                ToolSpec::Function(ResponsesApiTool { name, .. }) => name,
-                ToolSpec::LocalShell {} => "local_shell",
-                ToolSpec::WebSearch {} => "web_search",
-                ToolSpec::Freeform(FreeformTool { name, .. }) => name,
-            })
+            .map(|tool| tool_name(&tool.spec))
             .collect::<Vec<_>>();
 
         assert_eq!(
@@ -639,6 +717,16 @@ mod tests {
         }
     }
 
+    fn find_tool<'a>(
+        tools: &'a [ConfiguredToolSpec],
+        expected_name: &str,
+    ) -> &'a ConfiguredToolSpec {
+        tools
+            .iter()
+            .find(|tool| tool_name(&tool.spec) == expected_name)
+            .unwrap_or_else(|| panic!("expected tool {expected_name}"))
+    }
+
     #[test]
     fn test_build_specs() {
         let model_family = find_family_for_model("codex-mini-latest")
@@ -681,9 +769,10 @@ mod tests {
     }
 
     #[test]
-    fn test_build_specs_includes_beta_read_file_tool() {
+    #[ignore]
+    fn test_parallel_support_flags() {
         let model_family = find_family_for_model("gpt-5-codex")
-            .expect("gpt-5-codex should be a valid model family");
+            .expect("codex-mini-latest should be a valid model family");
         let config = ToolsConfig::new(&ToolsConfigParams {
             model_family: &model_family,
             include_plan_tool: false,
@@ -693,9 +782,37 @@ mod tests {
             include_view_image_tool: false,
             experimental_unified_exec_tool: true,
         });
-        let (tools, _) = build_specs(&config, Some(HashMap::new())).build();
+        let (tools, _) = build_specs(&config, None).build();
 
-        assert_eq_tool_names(&tools, &["unified_exec", "read_file"]);
+        assert!(!find_tool(&tools, "unified_exec").supports_parallel_tool_calls);
+        assert!(find_tool(&tools, "read_file").supports_parallel_tool_calls);
+    }
+
+    #[test]
+    fn test_test_model_family_includes_sync_tool() {
+        let model_family = find_family_for_model("test-gpt-5-codex")
+            .expect("test-gpt-5-codex should be a valid model family");
+        let config = ToolsConfig::new(&ToolsConfigParams {
+            model_family: &model_family,
+            include_plan_tool: false,
+            include_apply_patch_tool: false,
+            include_web_search_request: false,
+            use_streamable_shell_tool: false,
+            include_view_image_tool: false,
+            experimental_unified_exec_tool: false,
+        });
+        let (tools, _) = build_specs(&config, None).build();
+
+        assert!(
+            tools
+                .iter()
+                .any(|tool| tool_name(&tool.spec) == "test_sync_tool")
+        );
+        assert!(
+            tools
+                .iter()
+                .any(|tool| tool_name(&tool.spec) == "read_file")
+        );
     }
 
     #[test]
@@ -760,7 +877,7 @@ mod tests {
         );
 
         assert_eq!(
-            tools[3],
+            tools[3].spec,
             ToolSpec::Function(ResponsesApiTool {
                 name: "test_server/do_something_cool".to_string(),
                 parameters: JsonSchema::Object {
@@ -921,7 +1038,7 @@ mod tests {
             &tools,
             &[
                 "unified_exec",
-                "read_file",
+                "apply_patch",
                 "web_search",
                 "view_image",
                 "dash/search",
@@ -929,7 +1046,7 @@ mod tests {
         );
 
         assert_eq!(
-            tools[4],
+            tools[4].spec,
             ToolSpec::Function(ResponsesApiTool {
                 name: "dash/search".to_string(),
                 parameters: JsonSchema::Object {
@@ -988,14 +1105,14 @@ mod tests {
             &tools,
             &[
                 "unified_exec",
-                "read_file",
+                "apply_patch",
                 "web_search",
                 "view_image",
                 "dash/paginate",
             ],
         );
         assert_eq!(
-            tools[4],
+            tools[4].spec,
             ToolSpec::Function(ResponsesApiTool {
                 name: "dash/paginate".to_string(),
                 parameters: JsonSchema::Object {
@@ -1019,7 +1136,7 @@ mod tests {
         let config = ToolsConfig::new(&ToolsConfigParams {
             model_family: &model_family,
             include_plan_tool: false,
-            include_apply_patch_tool: false,
+            include_apply_patch_tool: true,
             include_web_search_request: true,
             use_streamable_shell_tool: false,
             include_view_image_tool: true,
@@ -1052,14 +1169,14 @@ mod tests {
             &tools,
             &[
                 "unified_exec",
-                "read_file",
+                "apply_patch",
                 "web_search",
                 "view_image",
                 "dash/tags",
             ],
         );
         assert_eq!(
-            tools[4],
+            tools[4].spec,
             ToolSpec::Function(ResponsesApiTool {
                 name: "dash/tags".to_string(),
                 parameters: JsonSchema::Object {
@@ -1119,14 +1236,14 @@ mod tests {
             &tools,
             &[
                 "unified_exec",
-                "read_file",
+                "apply_patch",
                 "web_search",
                 "view_image",
                 "dash/value",
             ],
         );
         assert_eq!(
-            tools[4],
+            tools[4].spec,
             ToolSpec::Function(ResponsesApiTool {
                 name: "dash/value".to_string(),
                 parameters: JsonSchema::Object {
@@ -1223,7 +1340,7 @@ mod tests {
             &tools,
             &[
                 "unified_exec",
-                "read_file",
+                "apply_patch",
                 "web_search",
                 "view_image",
                 "test_server/do_something_cool",
@@ -1231,7 +1348,7 @@ mod tests {
         );
 
         assert_eq!(
-            tools[4],
+            tools[4].spec,
             ToolSpec::Function(ResponsesApiTool {
                 name: "test_server/do_something_cool".to_string(),
                 parameters: JsonSchema::Object {

codex-rs/core/tests/common/responses.rs

@@ -135,6 +135,16 @@ pub fn ev_apply_patch_function_call(call_id: &str, patch: &str) -> Value {
     })
 }
 
+pub fn sse_failed(id: &str, code: &str, message: &str) -> String {
+    sse(vec![serde_json::json!({
+        "type": "response.failed",
+        "response": {
+            "id": id,
+            "error": {"code": code, "message": message}
+        }
+    })])
+}
+
 pub fn sse_response(body: String) -> ResponseTemplate {
     ResponseTemplate::new(200)
         .insert_header("content-type", "text/event-stream")

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

@@ -3,14 +3,14 @@ use std::time::Duration;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::InputItem;
 use codex_core::protocol::Op;
+use core_test_support::responses::ev_completed;
 use core_test_support::responses::ev_function_call;
-use core_test_support::responses::mount_sse_once_match;
+use core_test_support::responses::mount_sse_once;
 use core_test_support::responses::sse;
 use core_test_support::responses::start_mock_server;
 use core_test_support::test_codex::test_codex;
 use core_test_support::wait_for_event_with_timeout;
 use serde_json::json;
-use wiremock::matchers::body_string_contains;
 
 /// Integration test: spawn a long‑running shell tool via a mocked Responses SSE
 /// function call, then interrupt the session and expect TurnAborted.
@@ -27,10 +27,13 @@ async fn interrupt_long_running_tool_emits_turn_aborted() {
         "timeout_ms": 60_000
     })
     .to_string();
-    let body = sse(vec![ev_function_call("call_sleep", "shell", &args)]);
+    let body = sse(vec![
+        ev_function_call("call_sleep", "shell", &args),
+        ev_completed("done"),
+    ]);
 
     let server = start_mock_server().await;
-    mount_sse_once_match(&server, body_string_contains("start sleep"), body).await;
+    mount_sse_once(&server, body).await;
 
     let codex = test_codex().build(&server).await.unwrap().codex;
 

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

@@ -14,6 +14,8 @@ use codex_core::ResponseEvent;
 use codex_core::ResponseItem;
 use codex_core::WireApi;
 use codex_core::built_in_model_providers;
+use codex_core::error::CodexErr;
+use codex_core::model_family::find_family_for_model;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::InputItem;
 use codex_core::protocol::Op;
@@ -26,8 +28,10 @@ use core_test_support::load_default_config_for_test;
 use core_test_support::load_sse_fixture_with_id;
 use core_test_support::responses;
 use core_test_support::skip_if_no_network;
+use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
 use core_test_support::wait_for_event;
+use core_test_support::wait_for_event_with_timeout;
 use futures::StreamExt;
 use serde_json::json;
 use std::io::Write;
@@ -37,6 +41,7 @@ use uuid::Uuid;
 use wiremock::Mock;
 use wiremock::MockServer;
 use wiremock::ResponseTemplate;
+use wiremock::matchers::body_string_contains;
 use wiremock::matchers::header_regex;
 use wiremock::matchers::method;
 use wiremock::matchers::path;
@@ -996,6 +1001,100 @@ async fn usage_limit_error_emits_rate_limit_event() -> anyhow::Result<()> {
     Ok(())
 }
 
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn context_window_error_sets_total_tokens_to_model_window() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+    let server = MockServer::start().await;
+
+    responses::mount_sse_once_match(
+        &server,
+        body_string_contains("trigger context window"),
+        responses::sse_failed(
+            "resp_context_window",
+            "context_length_exceeded",
+            "Your input exceeds the context window of this model. Please adjust your input and try again.",
+        ),
+    )
+    .await;
+
+    responses::mount_sse_once_match(
+        &server,
+        body_string_contains("seed turn"),
+        sse_completed("resp_seed"),
+    )
+    .await;
+
+    let TestCodex { codex, .. } = test_codex()
+        .with_config(|config| {
+            config.model = "gpt-5".to_string();
+            config.model_family = find_family_for_model("gpt-5").expect("known gpt-5 model family");
+            config.model_context_window = Some(272_000);
+        })
+        .build(&server)
+        .await?;
+
+    codex
+        .submit(Op::UserInput {
+            items: vec![InputItem::Text {
+                text: "seed turn".into(),
+            }],
+        })
+        .await?;
+
+    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
+
+    codex
+        .submit(Op::UserInput {
+            items: vec![InputItem::Text {
+                text: "trigger context window".into(),
+            }],
+        })
+        .await?;
+
+    use std::time::Duration;
+
+    let token_event = wait_for_event_with_timeout(
+        &codex,
+        |event| {
+            matches!(
+                event,
+                EventMsg::TokenCount(payload)
+                    if payload.info.as_ref().is_some_and(|info| {
+                        info.model_context_window == Some(info.total_token_usage.total_tokens)
+                            && info.total_token_usage.total_tokens > 0
+                    })
+            )
+        },
+        Duration::from_secs(5),
+    )
+    .await;
+
+    let EventMsg::TokenCount(token_payload) = token_event else {
+        unreachable!("wait_for_event_with_timeout returned unexpected event");
+    };
+
+    let info = token_payload
+        .info
+        .expect("token usage info present when context window is exceeded");
+
+    assert_eq!(info.model_context_window, Some(272_000));
+    assert_eq!(info.total_token_usage.total_tokens, 272_000);
+
+    let error_event = wait_for_event(&codex, |ev| matches!(ev, EventMsg::Error(_))).await;
+    let expected_context_window_message = CodexErr::ContextWindowExceeded.to_string();
+    assert!(
+        matches!(
+            error_event,
+            EventMsg::Error(ref err) if err.message == expected_context_window_message
+        ),
+        "expected context window error; got {error_event:?}"
+    );
+
+    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
+
+    Ok(())
+}
+
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
 async fn azure_overrides_assign_properties_used_for_responses_url() {
     skip_if_no_network!();

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

@@ -20,9 +20,11 @@ mod review;
 mod rmcp_client;
 mod rollout_list_find;
 mod seatbelt;
+mod shell_serialization;
 mod stream_error_allows_next_turn;
 mod stream_no_completed;
 mod tool_harness;
+mod tool_parallelism;
 mod tools;
 mod unified_exec;
 mod user_notification;

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

@@ -125,7 +125,7 @@ async fn model_selects_expected_tools() {
     let gpt5_codex_tools = collect_tool_identifiers_for_model("gpt-5-codex").await;
     assert_eq!(
         gpt5_codex_tools,
-        vec!["shell".to_string(), "read_file".to_string()],
-        "gpt-5-codex should expose the beta read_file tool",
+        vec!["shell".to_string(), "apply_patch".to_string(),],
+        "gpt-5-codex should expose the apply_patch tool",
     );
 }

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

@@ -180,16 +180,16 @@ async fn prompt_tools_are_consistent_across_requests() {
 
     let cwd = TempDir::new().unwrap();
     let codex_home = TempDir::new().unwrap();
+
     let mut config = load_default_config_for_test(&codex_home);
     config.cwd = cwd.path().to_path_buf();
     config.model_provider = model_provider;
     config.user_instructions = Some("be consistent and helpful".to_string());
-    config.include_apply_patch_tool = true;
     config.include_plan_tool = true;
 
     let conversation_manager =
         ConversationManager::with_auth(CodexAuth::from_api_key("Test API Key"));
-    let expected_instructions = config.model_family.base_instructions.clone();
+    let base_instructions = config.model_family.base_instructions.clone();
     let codex = conversation_manager
         .new_conversation(config)
         .await
@@ -222,19 +222,10 @@ async fn prompt_tools_are_consistent_across_requests() {
     // our internal implementation is responsible for keeping tools in sync
     // with the OpenAI schema, so we just verify the tool presence here
     let tools_by_model: HashMap<&'static str, Vec<&'static str>> = HashMap::from([
-        (
-            "gpt-5",
-            vec!["shell", "update_plan", "apply_patch", "view_image"],
-        ),
+        ("gpt-5", vec!["shell", "update_plan", "view_image"]),
         (
             "gpt-5-codex",
-            vec![
-                "shell",
-                "update_plan",
-                "apply_patch",
-                "read_file",
-                "view_image",
-            ],
+            vec!["shell", "update_plan", "apply_patch", "view_image"],
         ),
     ]);
     let expected_tools_names = tools_by_model
@@ -242,6 +233,17 @@ async fn prompt_tools_are_consistent_across_requests() {
         .unwrap_or_else(|| panic!("expected tools to be defined for model {OPENAI_DEFAULT_MODEL}"))
         .as_slice();
     let body0 = requests[0].body_json::<serde_json::Value>().unwrap();
+
+    let expected_instructions = if expected_tools_names.contains(&"apply_patch") {
+        base_instructions
+    } else {
+        [
+            base_instructions.clone(),
+            include_str!("../../../apply-patch/apply_patch_tool_instructions.md").to_string(),
+        ]
+        .join("\n")
+    };
+
     assert_eq!(
         body0["instructions"],
         serde_json::json!(expected_instructions),

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

@@ -21,6 +21,7 @@ use serde_json::Value;
 use wiremock::matchers::any;
 
 #[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+#[ignore = "disabled until we enable read_file tool"]
 async fn read_file_tool_returns_requested_lines() -> anyhow::Result<()> {
     skip_if_no_network!(Ok(()));
 

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

@@ -24,6 +24,7 @@ use core_test_support::load_default_config_for_test;
 use core_test_support::load_sse_fixture_with_id_from_str;
 use core_test_support::skip_if_no_network;
 use core_test_support::wait_for_event;
+use core_test_support::wait_for_event_with_timeout;
 use pretty_assertions::assert_eq;
 use std::path::PathBuf;
 use std::sync::Arc;
@@ -260,25 +261,28 @@ async fn review_does_not_emit_agent_message_on_structured_output() {
         .unwrap();
 
     // Drain events until TaskComplete; ensure none are AgentMessage.
-    use tokio::time::Duration;
-    use tokio::time::timeout;
     let mut saw_entered = false;
     let mut saw_exited = false;
-    loop {
-        let ev = timeout(Duration::from_secs(5), codex.next_event())
-            .await
-            .expect("timeout waiting for event")
-            .expect("stream ended unexpectedly");
-        match ev.msg {
-            EventMsg::TaskComplete(_) => break,
+    wait_for_event_with_timeout(
+        &codex,
+        |event| match event {
+            EventMsg::TaskComplete(_) => true,
             EventMsg::AgentMessage(_) => {
                 panic!("unexpected AgentMessage during review with structured output")
             }
-            EventMsg::EnteredReviewMode(_) => saw_entered = true,
-            EventMsg::ExitedReviewMode(_) => saw_exited = true,
-            _ => {}
-        }
-    }
+            EventMsg::EnteredReviewMode(_) => {
+                saw_entered = true;
+                false
+            }
+            EventMsg::ExitedReviewMode(_) => {
+                saw_exited = true;
+                false
+            }
+            _ => false,
+        },
+        tokio::time::Duration::from_secs(5),
+    )
+    .await;
     assert!(saw_entered && saw_exited, "missing review lifecycle events");
 
     server.verify().await;

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

@@ -0,0 +1,275 @@
+#![cfg(not(target_os = "windows"))]
+
+use anyhow::Result;
+use codex_core::model_family::find_family_for_model;
+use codex_core::protocol::AskForApproval;
+use codex_core::protocol::EventMsg;
+use codex_core::protocol::InputItem;
+use codex_core::protocol::Op;
+use codex_core::protocol::SandboxPolicy;
+use codex_protocol::config_types::ReasoningSummary;
+use core_test_support::responses::ev_assistant_message;
+use core_test_support::responses::ev_completed;
+use core_test_support::responses::ev_function_call;
+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::TestCodex;
+use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
+use serde_json::Value;
+use serde_json::json;
+
+async fn submit_turn(test: &TestCodex, prompt: &str, sandbox_policy: SandboxPolicy) -> Result<()> {
+    let session_model = test.session_configured.model.clone();
+
+    test.codex
+        .submit(Op::UserTurn {
+            items: vec![InputItem::Text {
+                text: prompt.into(),
+            }],
+            final_output_json_schema: None,
+            cwd: test.cwd.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy,
+            model: session_model,
+            effort: None,
+            summary: ReasoningSummary::Auto,
+        })
+        .await?;
+
+    wait_for_event(&test.codex, |event| {
+        matches!(event, EventMsg::TaskComplete(_))
+    })
+    .await;
+
+    Ok(())
+}
+
+fn request_bodies(requests: &[wiremock::Request]) -> Result<Vec<Value>> {
+    requests
+        .iter()
+        .map(|req| Ok(serde_json::from_slice::<Value>(&req.body)?))
+        .collect()
+}
+
+fn find_function_call_output<'a>(bodies: &'a [Value], call_id: &str) -> Option<&'a Value> {
+    for body in bodies {
+        if let Some(items) = body.get("input").and_then(Value::as_array) {
+            for item in items {
+                if item.get("type").and_then(Value::as_str) == Some("function_call_output")
+                    && item.get("call_id").and_then(Value::as_str) == Some(call_id)
+                {
+                    return Some(item);
+                }
+            }
+        }
+    }
+    None
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn shell_output_stays_json_without_freeform_apply_patch() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let mut builder = test_codex().with_config(|config| {
+        config.include_apply_patch_tool = false;
+        config.model = "gpt-5".to_string();
+        config.model_family = find_family_for_model("gpt-5").expect("gpt-5 is a model family");
+    });
+    let test = builder.build(&server).await?;
+
+    let call_id = "shell-json";
+    let args = json!({
+        "command": ["/bin/echo", "shell json"],
+        "timeout_ms": 1_000,
+    });
+    let responses = vec![
+        sse(vec![
+            json!({"type": "response.created", "response": {"id": "resp-1"}}),
+            ev_function_call(call_id, "shell", &serde_json::to_string(&args)?),
+            ev_completed("resp-1"),
+        ]),
+        sse(vec![
+            ev_assistant_message("msg-1", "done"),
+            ev_completed("resp-2"),
+        ]),
+    ];
+    mount_sse_sequence(&server, responses).await;
+
+    submit_turn(
+        &test,
+        "run the json shell command",
+        SandboxPolicy::DangerFullAccess,
+    )
+    .await?;
+
+    let requests = server
+        .received_requests()
+        .await
+        .expect("recorded requests present");
+    let bodies = request_bodies(&requests)?;
+    let output_item = find_function_call_output(&bodies, call_id).expect("shell output present");
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("shell output string");
+
+    let parsed: Value = serde_json::from_str(output)?;
+    assert_eq!(
+        parsed
+            .get("metadata")
+            .and_then(|metadata| metadata.get("exit_code"))
+            .and_then(Value::as_i64),
+        Some(0),
+        "expected zero exit code in unformatted JSON output",
+    );
+    let stdout = parsed
+        .get("output")
+        .and_then(Value::as_str)
+        .unwrap_or_default();
+    assert!(
+        stdout.contains("shell json"),
+        "expected stdout to include command output, got {stdout:?}"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn shell_output_is_structured_with_freeform_apply_patch() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let mut builder = test_codex().with_config(|config| {
+        config.include_apply_patch_tool = true;
+    });
+    let test = builder.build(&server).await?;
+
+    let call_id = "shell-structured";
+    let args = json!({
+        "command": ["/bin/echo", "freeform shell"],
+        "timeout_ms": 1_000,
+    });
+    let responses = vec![
+        sse(vec![
+            json!({"type": "response.created", "response": {"id": "resp-1"}}),
+            ev_function_call(call_id, "shell", &serde_json::to_string(&args)?),
+            ev_completed("resp-1"),
+        ]),
+        sse(vec![
+            ev_assistant_message("msg-1", "done"),
+            ev_completed("resp-2"),
+        ]),
+    ];
+    mount_sse_sequence(&server, responses).await;
+
+    submit_turn(
+        &test,
+        "run the structured shell command",
+        SandboxPolicy::DangerFullAccess,
+    )
+    .await?;
+
+    let requests = server
+        .received_requests()
+        .await
+        .expect("recorded requests present");
+    let bodies = request_bodies(&requests)?;
+    let output_item =
+        find_function_call_output(&bodies, call_id).expect("structured output present");
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("structured output string");
+
+    assert!(
+        serde_json::from_str::<Value>(output).is_err(),
+        "expected structured shell output to be plain text",
+    );
+    assert!(
+        output.starts_with("Exit code: 0\n"),
+        "expected exit code prefix, got {output:?}",
+    );
+    assert!(
+        output.contains("\nOutput:\n"),
+        "expected Output section, got {output:?}"
+    );
+    assert!(
+        output.contains("freeform shell"),
+        "expected stdout content, got {output:?}"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn shell_output_reserializes_truncated_content() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let mut builder = test_codex().with_config(|config| {
+        config.model = "gpt-5-codex".to_string();
+        config.model_family =
+            find_family_for_model("gpt-5-codex").expect("gpt-5 is a model family");
+    });
+    let test = builder.build(&server).await?;
+
+    let call_id = "shell-truncated";
+    let args = json!({
+        "command": ["/bin/sh", "-c", "seq 1 400"],
+        "timeout_ms": 1_000,
+    });
+    let responses = vec![
+        sse(vec![
+            json!({"type": "response.created", "response": {"id": "resp-1"}}),
+            ev_function_call(call_id, "shell", &serde_json::to_string(&args)?),
+            ev_completed("resp-1"),
+        ]),
+        sse(vec![
+            ev_assistant_message("msg-1", "done"),
+            ev_completed("resp-2"),
+        ]),
+    ];
+    mount_sse_sequence(&server, responses).await;
+
+    submit_turn(
+        &test,
+        "run the truncation shell command",
+        SandboxPolicy::DangerFullAccess,
+    )
+    .await?;
+
+    let requests = server
+        .received_requests()
+        .await
+        .expect("recorded requests present");
+    let bodies = request_bodies(&requests)?;
+    let output_item =
+        find_function_call_output(&bodies, call_id).expect("truncated output present");
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("truncated output string");
+
+    assert!(
+        serde_json::from_str::<Value>(output).is_err(),
+        "expected truncated shell output to be plain text",
+    );
+    assert!(
+        output.starts_with("Exit code: 0\n"),
+        "expected exit code prefix, got {output:?}",
+    );
+    assert!(
+        output.lines().any(|line| line == "Total output lines: 400"),
+        "expected total output lines marker, got {output:?}",
+    );
+    assert!(
+        output.contains("[... omitted"),
+        "expected truncated marker, got {output:?}",
+    );
+
+    Ok(())
+}

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

@@ -13,7 +13,7 @@ use core_test_support::load_sse_fixture_with_id;
 use core_test_support::skip_if_no_network;
 use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
-use tokio::time::timeout;
+use core_test_support::wait_for_event_with_timeout;
 use wiremock::Mock;
 use wiremock::MockServer;
 use wiremock::Request;
@@ -102,13 +102,10 @@ async fn retries_on_early_close() {
         .unwrap();
 
     // Wait until TaskComplete (should succeed after retry).
-    loop {
-        let ev = timeout(Duration::from_secs(10), codex.next_event())
-            .await
-            .unwrap()
-            .unwrap();
-        if matches!(ev.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event_with_timeout(
+        &codex,
+        |event| matches!(event, EventMsg::TaskComplete(_)),
+        Duration::from_secs(10),
+    )
+    .await;
 }

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

@@ -1,5 +1,6 @@
 #![cfg(not(target_os = "windows"))]
 
+use codex_core::model_family::find_family_for_model;
 use codex_core::protocol::AskForApproval;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::InputItem;
@@ -18,6 +19,7 @@ use core_test_support::responses::start_mock_server;
 use core_test_support::skip_if_no_network;
 use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
 use serde_json::Value;
 use serde_json::json;
 use wiremock::matchers::any;
@@ -53,7 +55,8 @@ async fn shell_tool_executes_command_and_streams_output() -> anyhow::Result<()>
     let server = start_mock_server().await;
 
     let mut builder = test_codex().with_config(|config| {
-        config.include_apply_patch_tool = true;
+        config.model = "gpt-5".to_string();
+        config.model_family = find_family_for_model("gpt-5").expect("gpt-5 is a valid model");
     });
     let TestCodex {
         codex,
@@ -97,12 +100,7 @@ async fn shell_tool_executes_command_and_streams_output() -> anyhow::Result<()>
         })
         .await?;
 
-    loop {
-        let event = codex.next_event().await.expect("event");
-        if matches!(event.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event(&codex, |event| matches!(event, EventMsg::TaskComplete(_))).await;
 
     let requests = server.received_requests().await.expect("recorded requests");
     assert!(!requests.is_empty(), "expected at least one POST request");
@@ -187,23 +185,21 @@ async fn update_plan_tool_emits_plan_update_event() -> anyhow::Result<()> {
         .await?;
 
     let mut saw_plan_update = false;
-
-    loop {
-        let event = codex.next_event().await.expect("event");
-        match event.msg {
-            EventMsg::PlanUpdate(update) => {
-                saw_plan_update = true;
-                assert_eq!(update.explanation.as_deref(), Some("Tool harness check"));
-                assert_eq!(update.plan.len(), 2);
-                assert_eq!(update.plan[0].step, "Inspect workspace");
-                assert!(matches!(update.plan[0].status, StepStatus::InProgress));
-                assert_eq!(update.plan[1].step, "Report results");
-                assert!(matches!(update.plan[1].status, StepStatus::Pending));
-            }
-            EventMsg::TaskComplete(_) => break,
-            _ => {}
+    wait_for_event(&codex, |event| match event {
+        EventMsg::PlanUpdate(update) => {
+            saw_plan_update = true;
+            assert_eq!(update.explanation.as_deref(), Some("Tool harness check"));
+            assert_eq!(update.plan.len(), 2);
+            assert_eq!(update.plan[0].step, "Inspect workspace");
+            assert!(matches!(update.plan[0].status, StepStatus::InProgress));
+            assert_eq!(update.plan[1].step, "Report results");
+            assert!(matches!(update.plan[1].status, StepStatus::Pending));
+            false
         }
-    }
+        EventMsg::TaskComplete(_) => true,
+        _ => false,
+    })
+    .await;
 
     assert!(saw_plan_update, "expected PlanUpdate event");
 
@@ -284,15 +280,15 @@ async fn update_plan_tool_rejects_malformed_payload() -> anyhow::Result<()> {
         .await?;
 
     let mut saw_plan_update = false;
-
-    loop {
-        let event = codex.next_event().await.expect("event");
-        match event.msg {
-            EventMsg::PlanUpdate(_) => saw_plan_update = true,
-            EventMsg::TaskComplete(_) => break,
-            _ => {}
+    wait_for_event(&codex, |event| match event {
+        EventMsg::PlanUpdate(_) => {
+            saw_plan_update = true;
+            false
         }
-    }
+        EventMsg::TaskComplete(_) => true,
+        _ => false,
+    })
+    .await;
 
     assert!(
         !saw_plan_update,
@@ -391,22 +387,21 @@ async fn apply_patch_tool_executes_and_emits_patch_events() -> anyhow::Result<()
 
     let mut saw_patch_begin = false;
     let mut patch_end_success = None;
-
-    loop {
-        let event = codex.next_event().await.expect("event");
-        match event.msg {
-            EventMsg::PatchApplyBegin(begin) => {
-                saw_patch_begin = true;
-                assert_eq!(begin.call_id, call_id);
-            }
-            EventMsg::PatchApplyEnd(end) => {
-                assert_eq!(end.call_id, call_id);
-                patch_end_success = Some(end.success);
-            }
-            EventMsg::TaskComplete(_) => break,
-            _ => {}
+    wait_for_event(&codex, |event| match event {
+        EventMsg::PatchApplyBegin(begin) => {
+            saw_patch_begin = true;
+            assert_eq!(begin.call_id, call_id);
+            false
         }
-    }
+        EventMsg::PatchApplyEnd(end) => {
+            assert_eq!(end.call_id, call_id);
+            patch_end_success = Some(end.success);
+            false
+        }
+        EventMsg::TaskComplete(_) => true,
+        _ => false,
+    })
+    .await;
 
     assert!(saw_patch_begin, "expected PatchApplyBegin event");
     let patch_end_success =
@@ -519,12 +514,7 @@ async fn apply_patch_reports_parse_diagnostics() -> anyhow::Result<()> {
         })
         .await?;
 
-    loop {
-        let event = codex.next_event().await.expect("event");
-        if matches!(event.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event(&codex, |event| matches!(event, EventMsg::TaskComplete(_))).await;
 
     let requests = server.received_requests().await.expect("recorded requests");
     assert!(!requests.is_empty(), "expected at least one POST request");

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

@@ -0,0 +1,178 @@
+#![cfg(not(target_os = "windows"))]
+#![allow(clippy::unwrap_used)]
+
+use std::time::Duration;
+use std::time::Instant;
+
+use codex_core::model_family::find_family_for_model;
+use codex_core::protocol::AskForApproval;
+use codex_core::protocol::EventMsg;
+use codex_core::protocol::InputItem;
+use codex_core::protocol::Op;
+use codex_core::protocol::SandboxPolicy;
+use codex_protocol::config_types::ReasoningSummary;
+use core_test_support::responses::ev_assistant_message;
+use core_test_support::responses::ev_completed;
+use core_test_support::responses::ev_function_call;
+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::TestCodex;
+use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
+use serde_json::json;
+
+async fn run_turn(test: &TestCodex, prompt: &str) -> anyhow::Result<()> {
+    let session_model = test.session_configured.model.clone();
+
+    test.codex
+        .submit(Op::UserTurn {
+            items: vec![InputItem::Text {
+                text: prompt.into(),
+            }],
+            final_output_json_schema: None,
+            cwd: test.cwd.path().to_path_buf(),
+            approval_policy: AskForApproval::Never,
+            sandbox_policy: SandboxPolicy::DangerFullAccess,
+            model: session_model,
+            effort: None,
+            summary: ReasoningSummary::Auto,
+        })
+        .await?;
+
+    wait_for_event(&test.codex, |ev| matches!(ev, EventMsg::TaskComplete(_))).await;
+
+    Ok(())
+}
+
+async fn run_turn_and_measure(test: &TestCodex, prompt: &str) -> anyhow::Result<Duration> {
+    let start = Instant::now();
+    run_turn(test, prompt).await?;
+    Ok(start.elapsed())
+}
+
+#[allow(clippy::expect_used)]
+async fn build_codex_with_test_tool(server: &wiremock::MockServer) -> anyhow::Result<TestCodex> {
+    let mut builder = test_codex().with_config(|config| {
+        config.model = "test-gpt-5-codex".to_string();
+        config.model_family =
+            find_family_for_model("test-gpt-5-codex").expect("test-gpt-5-codex model family");
+    });
+    builder.build(server).await
+}
+
+fn assert_parallel_duration(actual: Duration) {
+    assert!(
+        actual < Duration::from_millis(500),
+        "expected parallel execution to finish quickly, got {actual:?}"
+    );
+}
+
+fn assert_serial_duration(actual: Duration) {
+    assert!(
+        actual >= Duration::from_millis(500),
+        "expected serial execution to take longer, got {actual:?}"
+    );
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn read_file_tools_run_in_parallel() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let test = build_codex_with_test_tool(&server).await?;
+
+    let parallel_args = json!({
+        "sleep_after_ms": 300,
+        "barrier": {
+            "id": "parallel-test-sync",
+            "participants": 2,
+            "timeout_ms": 1_000,
+        }
+    })
+    .to_string();
+
+    let first_response = sse(vec![
+        json!({"type": "response.created", "response": {"id": "resp-1"}}),
+        ev_function_call("call-1", "test_sync_tool", &parallel_args),
+        ev_function_call("call-2", "test_sync_tool", &parallel_args),
+        ev_completed("resp-1"),
+    ]);
+    let second_response = sse(vec![
+        ev_assistant_message("msg-1", "done"),
+        ev_completed("resp-2"),
+    ]);
+    mount_sse_sequence(&server, vec![first_response, second_response]).await;
+
+    let duration = run_turn_and_measure(&test, "exercise sync tool").await?;
+    assert_parallel_duration(duration);
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn non_parallel_tools_run_serially() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let test = test_codex().build(&server).await?;
+
+    let shell_args = json!({
+        "command": ["/bin/sh", "-c", "sleep 0.3"],
+        "timeout_ms": 1_000,
+    });
+    let args_one = serde_json::to_string(&shell_args)?;
+    let args_two = serde_json::to_string(&shell_args)?;
+
+    let first_response = sse(vec![
+        json!({"type": "response.created", "response": {"id": "resp-1"}}),
+        ev_function_call("call-1", "shell", &args_one),
+        ev_function_call("call-2", "shell", &args_two),
+        ev_completed("resp-1"),
+    ]);
+    let second_response = sse(vec![
+        ev_assistant_message("msg-1", "done"),
+        ev_completed("resp-2"),
+    ]);
+    mount_sse_sequence(&server, vec![first_response, second_response]).await;
+
+    let duration = run_turn_and_measure(&test, "run shell twice").await?;
+    assert_serial_duration(duration);
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn mixed_tools_fall_back_to_serial() -> anyhow::Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let test = build_codex_with_test_tool(&server).await?;
+
+    let sync_args = json!({
+        "sleep_after_ms": 300
+    })
+    .to_string();
+    let shell_args = serde_json::to_string(&json!({
+        "command": ["/bin/sh", "-c", "sleep 0.3"],
+        "timeout_ms": 1_000,
+    }))?;
+
+    let first_response = sse(vec![
+        json!({"type": "response.created", "response": {"id": "resp-1"}}),
+        ev_function_call("call-1", "test_sync_tool", &sync_args),
+        ev_function_call("call-2", "shell", &shell_args),
+        ev_completed("resp-1"),
+    ]);
+    let second_response = sse(vec![
+        ev_assistant_message("msg-1", "done"),
+        ev_completed("resp-2"),
+    ]);
+    mount_sse_sequence(&server, vec![first_response, second_response]).await;
+
+    let duration = run_turn_and_measure(&test, "mix tools").await?;
+    assert_serial_duration(duration);
+
+    Ok(())
+}

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

@@ -2,6 +2,7 @@
 #![allow(clippy::unwrap_used, clippy::expect_used)]
 
 use anyhow::Result;
+use codex_core::model_family::find_family_for_model;
 use codex_core::protocol::AskForApproval;
 use codex_core::protocol::EventMsg;
 use codex_core::protocol::InputItem;
@@ -18,6 +19,7 @@ use core_test_support::responses::start_mock_server;
 use core_test_support::skip_if_no_network;
 use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
 use serde_json::Value;
 use serde_json::json;
 use wiremock::Request;
@@ -45,12 +47,10 @@ async fn submit_turn(
         })
         .await?;
 
-    loop {
-        let event = test.codex.next_event().await?;
-        if matches!(event.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event(&test.codex, |event| {
+        matches!(event, EventMsg::TaskComplete(_))
+    })
+    .await;
 
     Ok(())
 }
@@ -147,7 +147,10 @@ async fn shell_escalated_permissions_rejected_then_ok() -> Result<()> {
     skip_if_no_network!(Ok(()));
 
     let server = start_mock_server().await;
-    let mut builder = test_codex();
+    let mut builder = test_codex().with_config(|config| {
+        config.model = "gpt-5".to_string();
+        config.model_family = find_family_for_model("gpt-5").expect("gpt-5 is a valid model");
+    });
     let test = builder.build(&server).await?;
 
     let command = ["/bin/echo", "shell ok"];
@@ -375,7 +378,10 @@ async fn shell_timeout_includes_timeout_prefix_and_metadata() -> Result<()> {
     skip_if_no_network!(Ok(()));
 
     let server = start_mock_server().await;
-    let mut builder = test_codex();
+    let mut builder = test_codex().with_config(|config| {
+        config.model = "gpt-5".to_string();
+        config.model_family = find_family_for_model("gpt-5").expect("gpt-5 is a valid model");
+    });
     let test = builder.build(&server).await?;
 
     let call_id = "shell-timeout";
@@ -431,11 +437,11 @@ async fn shell_timeout_includes_timeout_prefix_and_metadata() -> Result<()> {
 
         let stdout = output_json["output"].as_str().unwrap_or_default();
         assert!(
-            stdout.starts_with("command timed out after "),
+            stdout.contains("command timed out after "),
             "expected timeout prefix, got {stdout:?}"
         );
-        let first_line = stdout.lines().next().unwrap_or_default();
-        let duration_ms = first_line
+        let third_line = stdout.lines().nth(2).unwrap_or_default();
+        let duration_ms = third_line
             .strip_prefix("command timed out after ")
             .and_then(|line| line.strip_suffix(" milliseconds"))
             .and_then(|value| value.parse::<u64>().ok())
@@ -458,3 +464,150 @@ async fn shell_timeout_includes_timeout_prefix_and_metadata() -> Result<()> {
 
     Ok(())
 }
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn shell_sandbox_denied_truncates_error_output() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let mut builder = test_codex();
+    let test = builder.build(&server).await?;
+
+    let call_id = "shell-denied";
+    let long_line = "this is a long stderr line that should trigger truncation 0123456789abcdefghijklmnopqrstuvwxyz";
+    let script = format!(
+        "for i in $(seq 1 500); do >&2 echo '{long_line}'; done; cat <<'EOF' > denied.txt\ncontent\nEOF",
+    );
+    let args = json!({
+        "command": ["/bin/sh", "-c", script],
+        "timeout_ms": 1_000,
+    });
+
+    let responses = vec![
+        sse(vec![
+            json!({"type": "response.created", "response": {"id": "resp-1"}}),
+            ev_function_call(call_id, "shell", &serde_json::to_string(&args)?),
+            ev_completed("resp-1"),
+        ]),
+        sse(vec![
+            ev_assistant_message("msg-1", "done"),
+            ev_completed("resp-2"),
+        ]),
+    ];
+    mount_sse_sequence(&server, responses).await;
+
+    submit_turn(
+        &test,
+        "attempt to write in read-only sandbox",
+        AskForApproval::Never,
+        SandboxPolicy::ReadOnly,
+    )
+    .await?;
+
+    let requests = server.received_requests().await.expect("recorded requests");
+    let bodies = request_bodies(&requests)?;
+    let function_outputs = collect_output_items(&bodies, "function_call_output");
+    let denied_item = function_outputs
+        .iter()
+        .find(|item| item.get("call_id").and_then(Value::as_str) == Some(call_id))
+        .expect("denied output present");
+
+    let output = denied_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("denied output string");
+
+    assert!(
+        output.contains("failed in sandbox: "),
+        "expected sandbox error prefix, got {output:?}"
+    );
+    assert!(
+        output.contains("[... omitted"),
+        "expected truncated marker, got {output:?}"
+    );
+    assert!(
+        output.contains(long_line),
+        "expected truncated stderr sample, got {output:?}"
+    );
+    // Linux distributions may surface sandbox write failures as different errno messages
+    // depending on the underlying mechanism (e.g., EPERM, EACCES, or EROFS). Accept a
+    // small set of common variants to keep this cross-platform.
+    let denial_markers = [
+        "Operation not permitted", // EPERM
+        "Permission denied",       // EACCES
+        "Read-only file system",   // EROFS
+    ];
+    assert!(
+        denial_markers.iter().any(|m| output.contains(m)),
+        "expected sandbox denial message, got {output:?}"
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn shell_spawn_failure_truncates_exec_error() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let mut builder = test_codex().with_config(|cfg| {
+        cfg.sandbox_policy = SandboxPolicy::DangerFullAccess;
+    });
+    let test = builder.build(&server).await?;
+
+    let call_id = "shell-spawn-failure";
+    let bogus_component = "missing-bin-".repeat(700);
+    let bogus_exe = test
+        .cwd
+        .path()
+        .join(bogus_component)
+        .to_string_lossy()
+        .into_owned();
+
+    let args = json!({
+        "command": [bogus_exe],
+        "timeout_ms": 1_000,
+    });
+
+    let responses = vec![
+        sse(vec![
+            json!({"type": "response.created", "response": {"id": "resp-1"}}),
+            ev_function_call(call_id, "shell", &serde_json::to_string(&args)?),
+            ev_completed("resp-1"),
+        ]),
+        sse(vec![
+            ev_assistant_message("msg-1", "done"),
+            ev_completed("resp-2"),
+        ]),
+    ];
+    mount_sse_sequence(&server, responses).await;
+
+    submit_turn(
+        &test,
+        "spawn a missing binary",
+        AskForApproval::Never,
+        SandboxPolicy::DangerFullAccess,
+    )
+    .await?;
+
+    let requests = server.received_requests().await.expect("recorded requests");
+    let bodies = request_bodies(&requests)?;
+    let function_outputs = collect_output_items(&bodies, "function_call_output");
+    let failure_item = function_outputs
+        .iter()
+        .find(|item| item.get("call_id").and_then(Value::as_str) == Some(call_id))
+        .expect("spawn failure output present");
+
+    let output = failure_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("spawn failure output string");
+
+    assert!(
+        output.contains("execution error:"),
+        "expected execution error prefix, got {output:?}"
+    );
+    assert!(output.len() <= 10 * 1024);
+
+    Ok(())
+}

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

@@ -19,6 +19,7 @@ use core_test_support::skip_if_no_network;
 use core_test_support::skip_if_sandbox;
 use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
 use serde_json::Value;
 
 fn extract_output_text(item: &Value) -> Option<&str> {
@@ -122,12 +123,7 @@ async fn unified_exec_reuses_session_via_stdin() -> Result<()> {
         })
         .await?;
 
-    loop {
-        let event = codex.next_event().await.expect("event");
-        if matches!(event.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event(&codex, |event| matches!(event, EventMsg::TaskComplete(_))).await;
 
     let requests = server.received_requests().await.expect("recorded requests");
     assert!(!requests.is_empty(), "expected at least one POST request");

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

@@ -17,6 +17,7 @@ use core_test_support::responses::start_mock_server;
 use core_test_support::skip_if_no_network;
 use core_test_support::test_codex::TestCodex;
 use core_test_support::test_codex::test_codex;
+use core_test_support::wait_for_event;
 use serde_json::Value;
 use wiremock::matchers::any;
 
@@ -121,16 +122,20 @@ async fn view_image_tool_attaches_local_image() -> anyhow::Result<()> {
         .await?;
 
     let mut tool_event = None;
-    loop {
-        let event = codex.next_event().await.expect("event");
-        match event.msg {
-            EventMsg::ViewImageToolCall(ev) => tool_event = Some(ev),
-            EventMsg::TaskComplete(_) => break,
-            _ => {}
+    wait_for_event(&codex, |event| match event {
+        EventMsg::ViewImageToolCall(_) => {
+            tool_event = Some(event.clone());
+            false
         }
-    }
+        EventMsg::TaskComplete(_) => true,
+        _ => false,
+    })
+    .await;
 
-    let tool_event = tool_event.expect("view image tool event emitted");
+    let tool_event = match tool_event.expect("view image tool event emitted") {
+        EventMsg::ViewImageToolCall(event) => event,
+        _ => unreachable!("stored event must be ViewImageToolCall"),
+    };
     assert_eq!(tool_event.call_id, call_id);
     assert_eq!(tool_event.path, abs_path);
 
@@ -229,12 +234,7 @@ async fn view_image_tool_errors_when_path_is_directory() -> anyhow::Result<()> {
         })
         .await?;
 
-    loop {
-        let event = codex.next_event().await.expect("event");
-        if matches!(event.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event(&codex, |event| matches!(event, EventMsg::TaskComplete(_))).await;
 
     let requests = server.received_requests().await.expect("recorded requests");
     assert!(
@@ -314,12 +314,7 @@ async fn view_image_tool_errors_when_file_missing() -> anyhow::Result<()> {
         })
         .await?;
 
-    loop {
-        let event = codex.next_event().await.expect("event");
-        if matches!(event.msg, EventMsg::TaskComplete(_)) {
-            break;
-        }
-    }
+    wait_for_event(&codex, |event| matches!(event, EventMsg::TaskComplete(_))).await;
 
     let requests = server.received_requests().await.expect("recorded requests");
     assert!(

codex-rs/exec/src/lib.rs

@@ -177,7 +177,7 @@ pub async fn run_main(cli: Cli, codex_linux_sandbox_exe: Option<PathBuf>) -> any
         codex_linux_sandbox_exe,
         base_instructions: None,
         include_plan_tool: Some(include_plan_tool),
-        include_apply_patch_tool: Some(true),
+        include_apply_patch_tool: None,
         include_view_image_tool: None,
         show_raw_agent_reasoning: oss.then_some(true),
         tools_web_search_request: None,

codex-rs/protocol/src/protocol.rs

@@ -590,6 +590,31 @@ impl TokenUsageInfo {
         self.total_token_usage.add_assign(last);
         self.last_token_usage = last.clone();
     }
+
+    pub fn fill_to_context_window(&mut self, context_window: u64) {
+        let previous_total = self.total_token_usage.total_tokens;
+        let delta = context_window.saturating_sub(previous_total);
+
+        self.model_context_window = Some(context_window);
+        self.total_token_usage = TokenUsage {
+            total_tokens: context_window,
+            ..TokenUsage::default()
+        };
+        self.last_token_usage = TokenUsage {
+            total_tokens: delta,
+            ..TokenUsage::default()
+        };
+    }
+
+    pub fn full_context_window(context_window: u64) -> Self {
+        let mut info = Self {
+            total_token_usage: TokenUsage::default(),
+            last_token_usage: TokenUsage::default(),
+            model_context_window: Some(context_window),
+        };
+        info.fill_to_context_window(context_window);
+        info
+    }
 }
 
 #[derive(Debug, Clone, Deserialize, Serialize, TS)]

codex-rs/tui/src/lib.rs

@@ -80,6 +80,7 @@ pub mod test_backend;
 mod updates;
 
 use crate::onboarding::TrustDirectorySelection;
+use crate::onboarding::WSL_INSTRUCTIONS;
 use crate::onboarding::onboarding_screen::OnboardingScreenArgs;
 use crate::onboarding::onboarding_screen::run_onboarding_app;
 use crate::tui::Tui;
@@ -87,6 +88,7 @@ pub use cli::Cli;
 pub use markdown_render::render_markdown_text;
 pub use public_widgets::composer_input::ComposerAction;
 pub use public_widgets::composer_input::ComposerInput;
+use std::io::Write as _;
 
 // (tests access modules directly within the crate)
 
@@ -364,11 +366,18 @@ async fn run_ratatui_app(
 
     let auth_manager = AuthManager::shared(config.codex_home.clone(), false);
     let login_status = get_login_status(&config);
-    let should_show_onboarding =
-        should_show_onboarding(login_status, &config, should_show_trust_screen);
+    let should_show_windows_wsl_screen =
+        cfg!(target_os = "windows") && !config.windows_wsl_setup_acknowledged;
+    let should_show_onboarding = should_show_onboarding(
+        login_status,
+        &config,
+        should_show_trust_screen,
+        should_show_windows_wsl_screen,
+    );
     if should_show_onboarding {
-        let directory_trust_decision = run_onboarding_app(
+        let onboarding_result = run_onboarding_app(
             OnboardingScreenArgs {
+                show_windows_wsl_screen: should_show_windows_wsl_screen,
                 show_login_screen: should_show_login_screen(login_status, &config),
                 show_trust_screen: should_show_trust_screen,
                 login_status,
@@ -378,7 +387,22 @@ async fn run_ratatui_app(
             &mut tui,
         )
         .await?;
-        if let Some(TrustDirectorySelection::Trust) = directory_trust_decision {
+        if onboarding_result.windows_install_selected {
+            restore();
+            session_log::log_session_end();
+            let _ = tui.terminal.clear();
+            if let Err(err) = writeln!(std::io::stdout(), "{WSL_INSTRUCTIONS}") {
+                tracing::error!("Failed to write WSL instructions: {err}");
+            }
+            return Ok(AppExitInfo {
+                token_usage: codex_core::protocol::TokenUsage::default(),
+                conversation_id: None,
+            });
+        }
+        if should_show_windows_wsl_screen {
+            config.windows_wsl_setup_acknowledged = true;
+        }
+        if let Some(TrustDirectorySelection::Trust) = onboarding_result.directory_trust_decision {
             config.approval_policy = AskForApproval::OnRequest;
             config.sandbox_policy = SandboxPolicy::new_workspace_write_policy();
         }
@@ -521,7 +545,12 @@ fn should_show_onboarding(
     login_status: LoginStatus,
     config: &Config,
     show_trust_screen: bool,
+    show_windows_wsl_screen: bool,
 ) -> bool {
+    if show_windows_wsl_screen {
+        return true;
+    }
+
     if show_trust_screen {
         return true;
     }

codex-rs/tui/src/onboarding/mod.rs

@@ -3,3 +3,6 @@ pub mod onboarding_screen;
 mod trust_directory;
 pub use trust_directory::TrustDirectorySelection;
 mod welcome;
+mod windows;
+
+pub(crate) use windows::WSL_INSTRUCTIONS;

codex-rs/tui/src/onboarding/onboarding_screen.rs

@@ -19,6 +19,7 @@ use crate::onboarding::auth::SignInState;
 use crate::onboarding::trust_directory::TrustDirectorySelection;
 use crate::onboarding::trust_directory::TrustDirectoryWidget;
 use crate::onboarding::welcome::WelcomeWidget;
+use crate::onboarding::windows::WindowsSetupWidget;
 use crate::tui::FrameRequester;
 use crate::tui::Tui;
 use crate::tui::TuiEvent;
@@ -28,6 +29,7 @@ use std::sync::RwLock;
 
 #[allow(clippy::large_enum_variant)]
 enum Step {
+    Windows(WindowsSetupWidget),
     Welcome(WelcomeWidget),
     Auth(AuthModeWidget),
     TrustDirectory(TrustDirectoryWidget),
@@ -38,6 +40,7 @@ pub(crate) trait KeyboardHandler {
     fn handle_paste(&mut self, _pasted: String) {}
 }
 
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
 pub(crate) enum StepState {
     Hidden,
     InProgress,
@@ -52,9 +55,11 @@ pub(crate) struct OnboardingScreen {
     request_frame: FrameRequester,
     steps: Vec<Step>,
     is_done: bool,
+    windows_install_selected: bool,
 }
 
 pub(crate) struct OnboardingScreenArgs {
+    pub show_windows_wsl_screen: bool,
     pub show_trust_screen: bool,
     pub show_login_screen: bool,
     pub login_status: LoginStatus,
@@ -62,9 +67,15 @@ pub(crate) struct OnboardingScreenArgs {
     pub config: Config,
 }
 
+pub(crate) struct OnboardingResult {
+    pub directory_trust_decision: Option<TrustDirectorySelection>,
+    pub windows_install_selected: bool,
+}
+
 impl OnboardingScreen {
     pub(crate) fn new(tui: &mut Tui, args: OnboardingScreenArgs) -> Self {
         let OnboardingScreenArgs {
+            show_windows_wsl_screen,
             show_trust_screen,
             show_login_screen,
             login_status,
@@ -73,10 +84,14 @@ impl OnboardingScreen {
         } = args;
         let cwd = config.cwd.clone();
         let codex_home = config.codex_home;
-        let mut steps: Vec<Step> = vec![Step::Welcome(WelcomeWidget::new(
+        let mut steps: Vec<Step> = Vec::new();
+        if show_windows_wsl_screen {
+            steps.push(Step::Windows(WindowsSetupWidget::new(codex_home.clone())));
+        }
+        steps.push(Step::Welcome(WelcomeWidget::new(
             !matches!(login_status, LoginStatus::NotAuthenticated),
             tui.frame_requester(),
-        ))];
+        )));
         if show_login_screen {
             steps.push(Step::Auth(AuthModeWidget {
                 request_frame: tui.frame_requester(),
@@ -110,6 +125,7 @@ impl OnboardingScreen {
             request_frame: tui.frame_requester(),
             steps,
             is_done: false,
+            windows_install_selected: false,
         }
     }
 
@@ -163,6 +179,10 @@ impl OnboardingScreen {
             })
             .flatten()
     }
+
+    pub fn windows_install_selected(&self) -> bool {
+        self.windows_install_selected
+    }
 }
 
 impl KeyboardHandler for OnboardingScreen {
@@ -200,6 +220,14 @@ impl KeyboardHandler for OnboardingScreen {
                 }
             }
         };
+        if self
+            .steps
+            .iter()
+            .any(|step| matches!(step, Step::Windows(widget) if widget.exit_requested()))
+        {
+            self.windows_install_selected = true;
+            self.is_done = true;
+        }
         self.request_frame.schedule_frame();
     }
 
@@ -281,6 +309,7 @@ impl WidgetRef for &OnboardingScreen {
 impl KeyboardHandler for Step {
     fn handle_key_event(&mut self, key_event: KeyEvent) {
         match self {
+            Step::Windows(widget) => widget.handle_key_event(key_event),
             Step::Welcome(widget) => widget.handle_key_event(key_event),
             Step::Auth(widget) => widget.handle_key_event(key_event),
             Step::TrustDirectory(widget) => widget.handle_key_event(key_event),
@@ -289,6 +318,7 @@ impl KeyboardHandler for Step {
 
     fn handle_paste(&mut self, pasted: String) {
         match self {
+            Step::Windows(_) => {}
             Step::Welcome(_) => {}
             Step::Auth(widget) => widget.handle_paste(pasted),
             Step::TrustDirectory(widget) => widget.handle_paste(pasted),
@@ -299,6 +329,7 @@ impl KeyboardHandler for Step {
 impl StepStateProvider for Step {
     fn get_step_state(&self) -> StepState {
         match self {
+            Step::Windows(w) => w.get_step_state(),
             Step::Welcome(w) => w.get_step_state(),
             Step::Auth(w) => w.get_step_state(),
             Step::TrustDirectory(w) => w.get_step_state(),
@@ -309,6 +340,9 @@ impl StepStateProvider for Step {
 impl WidgetRef for Step {
     fn render_ref(&self, area: Rect, buf: &mut Buffer) {
         match self {
+            Step::Windows(widget) => {
+                widget.render_ref(area, buf);
+            }
             Step::Welcome(widget) => {
                 widget.render_ref(area, buf);
             }
@@ -325,7 +359,7 @@ impl WidgetRef for Step {
 pub(crate) async fn run_onboarding_app(
     args: OnboardingScreenArgs,
     tui: &mut Tui,
-) -> Result<Option<crate::onboarding::TrustDirectorySelection>> {
+) -> Result<OnboardingResult> {
     use tokio_stream::StreamExt;
 
     let mut onboarding_screen = OnboardingScreen::new(tui, args);
@@ -386,5 +420,8 @@ pub(crate) async fn run_onboarding_app(
             }
         }
     }
-    Ok(onboarding_screen.directory_trust_decision())
+    Ok(OnboardingResult {
+        directory_trust_decision: onboarding_screen.directory_trust_decision(),
+        windows_install_selected: onboarding_screen.windows_install_selected(),
+    })
 }

codex-rs/tui/src/onboarding/trust_directory.rs

@@ -4,6 +4,7 @@ use codex_core::config::set_project_trusted;
 use codex_core::git_info::resolve_root_git_project_for_trust;
 use crossterm::event::KeyCode;
 use crossterm::event::KeyEvent;
+use crossterm::event::KeyEventKind;
 use ratatui::buffer::Buffer;
 use ratatui::layout::Rect;
 use ratatui::prelude::Widget;
@@ -109,6 +110,10 @@ impl WidgetRef for &TrustDirectoryWidget {
 
 impl KeyboardHandler for TrustDirectoryWidget {
     fn handle_key_event(&mut self, key_event: KeyEvent) {
+        if key_event.kind == KeyEventKind::Release {
+            return;
+        }
+
         match key_event.code {
             KeyCode::Up | KeyCode::Char('k') => {
                 self.highlighted = TrustDirectorySelection::Trust;
@@ -153,3 +158,37 @@ impl TrustDirectoryWidget {
         self.selection = Some(TrustDirectorySelection::DontTrust);
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crossterm::event::KeyCode;
+    use crossterm::event::KeyEvent;
+    use crossterm::event::KeyEventKind;
+    use crossterm::event::KeyModifiers;
+    use pretty_assertions::assert_eq;
+    use std::path::PathBuf;
+
+    #[test]
+    fn release_event_does_not_change_selection() {
+        let mut widget = TrustDirectoryWidget {
+            codex_home: PathBuf::from("."),
+            cwd: PathBuf::from("."),
+            is_git_repo: false,
+            selection: None,
+            highlighted: TrustDirectorySelection::DontTrust,
+            error: None,
+        };
+
+        let release = KeyEvent {
+            kind: KeyEventKind::Release,
+            ..KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE)
+        };
+        widget.handle_key_event(release);
+        assert_eq!(widget.selection, None);
+
+        let press = KeyEvent::new(KeyCode::Enter, KeyModifiers::NONE);
+        widget.handle_key_event(press);
+        assert_eq!(widget.selection, Some(TrustDirectorySelection::DontTrust));
+    }
+}

codex-rs/tui/src/onboarding/windows.rs

@@ -0,0 +1,190 @@
+use std::path::PathBuf;
+
+use codex_core::config::set_windows_wsl_setup_acknowledged;
+use crossterm::event::KeyCode;
+use crossterm::event::KeyEvent;
+use crossterm::event::KeyEventKind;
+use ratatui::buffer::Buffer;
+use ratatui::layout::Rect;
+use ratatui::prelude::Widget;
+use ratatui::style::Color;
+use ratatui::style::Stylize;
+use ratatui::text::Line;
+use ratatui::widgets::Paragraph;
+use ratatui::widgets::WidgetRef;
+use ratatui::widgets::Wrap;
+
+use crate::onboarding::onboarding_screen::KeyboardHandler;
+use crate::onboarding::onboarding_screen::StepStateProvider;
+
+use super::onboarding_screen::StepState;
+
+pub(crate) const WSL_INSTRUCTIONS: &str = r"Windows Subsystem for Linux (WSL2) is required to run Codex.
+
+To install WSL2:
+  1. Open PowerShell as Administrator and run: wsl --install
+  2. Restart your machine if prompted.
+  3. Launch the Ubuntu shortcut from the Start menu to complete setup.
+
+After installation, reopen Codex from a WSL shell.";
+
+pub(crate) struct WindowsSetupWidget {
+    pub codex_home: PathBuf,
+    pub selection: Option<WindowsSetupSelection>,
+    pub highlighted: WindowsSetupSelection,
+    pub error: Option<String>,
+    exit_requested: bool,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum WindowsSetupSelection {
+    Continue,
+    Install,
+}
+
+impl WindowsSetupWidget {
+    pub fn new(codex_home: PathBuf) -> Self {
+        Self {
+            codex_home,
+            selection: None,
+            highlighted: WindowsSetupSelection::Continue,
+            error: None,
+            exit_requested: false,
+        }
+    }
+
+    fn handle_continue(&mut self) {
+        self.highlighted = WindowsSetupSelection::Continue;
+        match set_windows_wsl_setup_acknowledged(&self.codex_home, true) {
+            Ok(()) => {
+                self.selection = Some(WindowsSetupSelection::Continue);
+                self.exit_requested = false;
+                self.error = None;
+            }
+            Err(err) => {
+                tracing::error!("Failed to persist Windows onboarding acknowledgement: {err:?}");
+                self.error = Some(format!("Failed to update config: {err}"));
+                self.selection = None;
+            }
+        }
+    }
+
+    fn handle_install(&mut self) {
+        self.highlighted = WindowsSetupSelection::Install;
+        self.selection = Some(WindowsSetupSelection::Install);
+        self.exit_requested = true;
+    }
+
+    pub fn exit_requested(&self) -> bool {
+        self.exit_requested
+    }
+}
+
+impl WidgetRef for &WindowsSetupWidget {
+    fn render_ref(&self, area: Rect, buf: &mut Buffer) {
+        let mut lines: Vec<Line> = vec![
+            Line::from(vec!["> ".into(), "Codex Windows Support".bold()]),
+            Line::from(""),
+            Line::from(
+                "  Codex support for Windows is in progress. Full support for Codex on Windows requires Windows Subsystem for Linux (WSL2).",
+            ),
+            Line::from(""),
+        ];
+
+        let create_option =
+            |idx: usize, option: WindowsSetupSelection, text: &str| -> Line<'static> {
+                if self.highlighted == option {
+                    Line::from(format!("> {}. {text}", idx + 1)).cyan()
+                } else {
+                    Line::from(format!("  {}. {}", idx + 1, text))
+                }
+            };
+
+        lines.push(create_option(
+            0,
+            WindowsSetupSelection::Continue,
+            "Continue anyway",
+        ));
+        lines.push(create_option(
+            1,
+            WindowsSetupSelection::Install,
+            "Exit and install Windows Subsystem for Linux (WSL2)",
+        ));
+        lines.push("".into());
+
+        if let Some(error) = &self.error {
+            lines.push(Line::from(format!("  {error}")).fg(Color::Red));
+            lines.push("".into());
+        }
+
+        lines.push(Line::from(vec!["  Press Enter to continue".dim()]));
+
+        Paragraph::new(lines)
+            .wrap(Wrap { trim: false })
+            .render(area, buf);
+    }
+}
+
+impl KeyboardHandler for WindowsSetupWidget {
+    fn handle_key_event(&mut self, key_event: KeyEvent) {
+        if key_event.kind == KeyEventKind::Release {
+            return;
+        }
+
+        match key_event.code {
+            KeyCode::Up | KeyCode::Char('k') => {
+                self.highlighted = WindowsSetupSelection::Continue;
+            }
+            KeyCode::Down | KeyCode::Char('j') => {
+                self.highlighted = WindowsSetupSelection::Install;
+            }
+            KeyCode::Char('1') => self.handle_continue(),
+            KeyCode::Char('2') => self.handle_install(),
+            KeyCode::Enter => match self.highlighted {
+                WindowsSetupSelection::Continue => self.handle_continue(),
+                WindowsSetupSelection::Install => self.handle_install(),
+            },
+            _ => {}
+        }
+    }
+}
+
+impl StepStateProvider for WindowsSetupWidget {
+    fn get_step_state(&self) -> StepState {
+        match self.selection {
+            Some(WindowsSetupSelection::Continue) => StepState::Hidden,
+            Some(WindowsSetupSelection::Install) => StepState::Complete,
+            None => StepState::InProgress,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::TempDir;
+
+    #[test]
+    fn windows_step_hidden_after_continue() {
+        let temp_dir = TempDir::new().expect("temp dir");
+        let mut widget = WindowsSetupWidget::new(temp_dir.path().to_path_buf());
+
+        assert_eq!(widget.get_step_state(), StepState::InProgress);
+
+        widget.handle_continue();
+
+        assert_eq!(widget.get_step_state(), StepState::Hidden);
+        assert!(!widget.exit_requested());
+    }
+
+    #[test]
+    fn windows_step_complete_after_install_selection() {
+        let temp_dir = TempDir::new().expect("temp dir");
+        let mut widget = WindowsSetupWidget::new(temp_dir.path().to_path_buf());
+
+        widget.handle_install();
+
+        assert_eq!(widget.get_step_state(), StepState::Complete);
+        assert!(widget.exit_requested());
+    }
+}

sdk/typescript/README.md

@@ -10,7 +10,7 @@ npm install @openai/codex-sdk
 
 ## Usage
 
-Call `startThread()` and `run()` to start a thead with Codex.
+Call `startThread()` and `run()` to start a thread with Codex.
 
 ```typescript
 import { Codex } from "@openai/codex-sdk";
@@ -32,17 +32,21 @@ console.log(result);
 
 ### Streaming
 
-The `await run()` method completes when a thread turn is complete and agent is prepared the final response.
+The `run()` method completes when a thread turn is complete and the agent has produced the final response.
 
-You can thread items while they are being produced by calling `await runStreamed()`.
+You can stream events while they are being produced by calling `runStreamed()` and iterating the returned generator.
 
 ```typescript
-const result = thread.runStreamed("Diagnose the test failure and propose a fix");
+const { events } = await thread.runStreamed("Diagnose the test failure and propose a fix");
+
+for await (const event of events) {
+  console.log(event);
+}
 ```
 
 ### Resuming a thread
 
-If you don't have the original `Thread` instance to continue the thread, you can resume a thread by calling `resumeThread()` and providing the thread.
+If you don't have the original `Thread` instance to continue the thread, you can resume by calling `resumeThread()` and providing the thread identifier.
 
 ```typescript
 const threadId = "...";
@@ -54,7 +58,7 @@ console.log(result);
 
 ### Working directory
 
-By default, Codex will run in the current working directory. You can change the working directory by passing the `workingDirectory` option to the when creating a thread.
+By default, Codex will run in the current working directory. You can change the working directory by passing the `workingDirectory` option when creating a thread.
 
 ```typescript
 const thread = codex.startThread({
@@ -62,7 +66,7 @@ const thread = codex.startThread({
 });
 ```
 
-To avoid unrecoverable errors, Codex requires the working directory to be a git repository. You can skip the git repository check by passing the `skipGitRepoCheck` option to the when creating a thread.
+To avoid unrecoverable errors, Codex requires the working directory to be a Git repository. You can skip the Git repository check by passing the `skipGitRepoCheck` option when creating a thread.
 
 ```typescript
 const thread = codex.startThread({

sdk/typescript/src/codexOptions.ts

@@ -2,5 +2,4 @@ export type CodexOptions = {
   codexPathOverride?: string;
   baseUrl?: string;
   apiKey?: string;
-  workingDirectory?: string;
 };

sdk/typescript/src/index.ts

@@ -30,4 +30,4 @@ export { Codex } from "./codex";
 
 export type { CodexOptions } from "./codexOptions";
 
-export type { ThreadOptions as TheadOptions, ApprovalMode, SandboxMode } from "./threadOptions";
+export type { ThreadOptions, ApprovalMode, SandboxMode } from "./threadOptions";

sdk/typescript/src/thread.ts

@@ -1,5 +1,5 @@
 import { CodexOptions } from "./codexOptions";
-import { ThreadEvent, Usage } from "./events";
+import { ThreadEvent, ThreadError, Usage } from "./events";
 import { CodexExec } from "./exec";
 import { ThreadItem } from "./items";
 import { ThreadOptions } from "./threadOptions";
@@ -87,6 +87,7 @@ export class Thread {
     const items: ThreadItem[] = [];
     let finalResponse: string = "";
     let usage: Usage | null = null;
+    let turnFailure: ThreadError | null = null;
     for await (const event of generator) {
       if (event.type === "item.completed") {
         if (event.item.type === "agent_message") {
@@ -95,8 +96,14 @@ export class Thread {
         items.push(event.item);
       } else if (event.type === "turn.completed") {
         usage = event.usage;
+      } else if (event.type === "turn.failed") {
+        turnFailure = event.error;
+        break;
       }
     }
+    if (turnFailure) {
+      throw new Error(turnFailure.message);
+    }
     return { items, finalResponse, usage };
   }
 }

sdk/typescript/tests/responsesProxy.ts

@@ -173,16 +173,19 @@ export function assistantMessage(text: string, itemId: string = DEFAULT_MESSAGE_
   };
 }
 
+export function responseFailed(errorMessage: string): SseEvent {
+  return {
+    type: "error",
+    error: { code: "rate_limit_exceeded", message: errorMessage },
+  };
+}
+
 export function responseCompleted(
   responseId: string = DEFAULT_RESPONSE_ID,
   usage: ResponseCompletedUsage = DEFAULT_COMPLETED_USAGE,
 ): SseEvent {
-  const inputDetails = usage.input_tokens_details
-    ? { ...usage.input_tokens_details }
-    : null;
-  const outputDetails = usage.output_tokens_details
-    ? { ...usage.output_tokens_details }
-    : null;
+  const inputDetails = usage.input_tokens_details ? { ...usage.input_tokens_details } : null;
+  const outputDetails = usage.output_tokens_details ? { ...usage.output_tokens_details } : null;
   return {
     type: "response.completed",
     response: {

sdk/typescript/tests/run.test.ts

@@ -12,6 +12,7 @@ import {
   responseCompleted,
   responseStarted,
   sse,
+  responseFailed,
   startResponsesTestProxy,
 } from "./responsesProxy";
 
@@ -287,6 +288,23 @@ describe("Codex", () => {
       await close();
     }
   });
+  it("throws ThreadRunError on turn failures", async () => {
+    const { url, close } = await startResponsesTestProxy({
+      statusCode: 200,
+      responseBodies: [
+        sse(responseStarted("response_1")),
+        sse(responseFailed("rate limit exceeded")),
+      ],
+    });
+
+    try {
+      const client = new Codex({ codexPathOverride: codexExecPath, baseUrl: url, apiKey: "test" });
+      const thread = client.startThread();
+      await expect(thread.run("fail")).rejects.toThrow("stream disconnected before completion:");
+    } finally {
+      await close();
+    }
+  }, 10000); // TODO(pakrym): remove timeout
 });
 function expectPair(args: string[] | undefined, pair: [string, string]) {
   if (!args) {