From 4da39dbea7a829435ea0e8b614ed0c9f3311abeb Mon Sep 17 00:00:00 2001
From: iceweasel-oai <iceweasel@openai.com>
Date: Tue, 14 Jul 2026 20:33:32 +0000
Subject: [PATCH] Clarify exec yield timing on Windows (#33150)

## Why

The generic `yield_time_ms` description does not explain the Windows-specific
initial wait behavior or when callers should choose a shorter value.

## What changed

- Describe `yield_time_ms` on Windows as the maximum wait before a running
  command returns a session ID, while commands that finish sooner still return
  immediately.
- Recommend the 10-second default for ordinary commands and shorter waits for
  intentionally long-lived or interactive processes.
- Keep the existing parameter description on other platforms.

## Testing

- Update the expected `exec_command` tool schema for both platform variants.

GitOrigin-RevId: 32f90b3a56604fcf1734cc81ba7ab2f0bec41643
---
 codex-rs/core/src/tools/handlers/shell_spec.rs       | 9 ++++++---
 codex-rs/core/src/tools/handlers/shell_spec_tests.rs | 9 ++++++---
 2 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/codex-rs/core/src/tools/handlers/shell_spec.rs b/codex-rs/core/src/tools/handlers/shell_spec.rs
index 3fb563b8d9..69a7946523 100644
--- a/codex-rs/core/src/tools/handlers/shell_spec.rs
+++ b/codex-rs/core/src/tools/handlers/shell_spec.rs
@@ -23,6 +23,11 @@ pub(crate) fn create_exec_command_tool_with_environment_id(
     include_environment_id: bool,
     include_shell_parameter: bool,
 ) -> ToolSpec {
+    let yield_time_ms_description = if cfg!(windows) {
+        "Maximum time to wait before returning a session ID for a still-running command. Commands that finish sooner return immediately. For ordinary commands, omit this parameter to use the 10000 ms default. Set a shorter value only when intentionally starting a long-lived or interactive process and you want a session ID promptly."
+    } else {
+        "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms."
+    };
     let mut properties = BTreeMap::from([
         (
             "cmd".to_string(),
@@ -44,9 +49,7 @@ pub(crate) fn create_exec_command_tool_with_environment_id(
         ),
         (
             "yield_time_ms".to_string(),
-            JsonSchema::number(Some(
-                "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.".to_string(),
-            )),
+            JsonSchema::number(Some(yield_time_ms_description.to_string())),
         ),
         (
             "max_output_tokens".to_string(),
diff --git a/codex-rs/core/src/tools/handlers/shell_spec_tests.rs b/codex-rs/core/src/tools/handlers/shell_spec_tests.rs
index b7bbfa54a1..cb73d45421 100644
--- a/codex-rs/core/src/tools/handlers/shell_spec_tests.rs
+++ b/codex-rs/core/src/tools/handlers/shell_spec_tests.rs
@@ -29,6 +29,11 @@ fn exec_command_tool_matches_expected_spec() {
         "Runs a command in a PTY, returning output or a session ID for ongoing interaction."
             .to_string()
     };
+    let yield_time_ms_description = if cfg!(windows) {
+        "Maximum time to wait before returning a session ID for a still-running command. Commands that finish sooner return immediately. For ordinary commands, omit this parameter to use the 10000 ms default. Set a shorter value only when intentionally starting a long-lived or interactive process and you want a session ID promptly."
+    } else {
+        "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms."
+    };
 
     let mut properties = BTreeMap::from([
         (
@@ -57,9 +62,7 @@ fn exec_command_tool_matches_expected_spec() {
         ),
         (
             "yield_time_ms".to_string(),
-            JsonSchema::number(Some(
-                    "Wait before yielding output. Defaults to 10000 ms; effective range is 250-30000 ms.".to_string(),
-                )),
+            JsonSchema::number(Some(yield_time_ms_description.to_string())),
         ),
         (
             "max_output_tokens".to_string(),