From 9f71dcbf577c2f87048c97c9b533817313b93955 Mon Sep 17 00:00:00 2001
From: Dylan <dylan.hurd@openai.com>
Date: Thu, 21 Aug 2025 19:58:07 -0700
Subject: [PATCH] [shell_tool] Small updates to ensure shell consistency
 (#2571)

## Summary
Small update to hopefully improve some shell edge cases, and make the
function clearer to the model what is going on. Keeping `timeout` as an
alias means that calls with the previous name will still work.

## Test Plan
- [x] Tested locally, model still works
---
 codex-rs/core/src/models.rs       |  6 ++----
 codex-rs/core/src/openai_tools.rs | 14 +++++++++-----
 2 files changed, 11 insertions(+), 9 deletions(-)

diff --git a/codex-rs/core/src/models.rs b/codex-rs/core/src/models.rs
index f6323e27..0c509ee2 100644
--- a/codex-rs/core/src/models.rs
+++ b/codex-rs/core/src/models.rs
@@ -197,10 +197,8 @@ pub struct ShellToolCallParams {
     pub command: Vec<String>,
     pub workdir: Option<String>,
 
-    /// This is the maximum time in seconds that the command is allowed to run.
-    #[serde(rename = "timeout")]
-    // The wire format uses `timeout`, which has ambiguous units, so we use
-    // `timeout_ms` as the field name so it is clear in code.
+    /// This is the maximum time in milliseconds that the command is allowed to run.
+    #[serde(alias = "timeout")]
     pub timeout_ms: Option<u64>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub with_escalated_permissions: Option<bool>,
diff --git a/codex-rs/core/src/openai_tools.rs b/codex-rs/core/src/openai_tools.rs
index dd5eb125..f02c7847 100644
--- a/codex-rs/core/src/openai_tools.rs
+++ b/codex-rs/core/src/openai_tools.rs
@@ -115,16 +115,20 @@ fn create_shell_tool() -> OpenAiTool {
         "command".to_string(),
         JsonSchema::Array {
             items: Box::new(JsonSchema::String { description: None }),
-            description: None,
+            description: Some("The command to execute".to_string()),
         },
     );
     properties.insert(
         "workdir".to_string(),
-        JsonSchema::String { description: None },
+        JsonSchema::String {
+            description: Some("The working directory to execute the command in".to_string()),
+        },
     );
     properties.insert(
-        "timeout".to_string(),
-        JsonSchema::Number { description: None },
+        "timeout_ms".to_string(),
+        JsonSchema::Number {
+            description: Some("The timeout for the command in milliseconds".to_string()),
+        },
     );
 
     OpenAiTool::Function(ResponsesApiTool {
@@ -155,7 +159,7 @@ fn create_shell_tool_for_sandbox(sandbox_policy: &SandboxPolicy) -> OpenAiTool {
         },
     );
     properties.insert(
-        "timeout".to_string(),
+        "timeout_ms".to_string(),
         JsonSchema::Number {
             description: Some("The timeout for the command in milliseconds".to_string()),
         },