From afa8cb9c4c34826bd1647403f99494830ab6e1cb Mon Sep 17 00:00:00 2001
From: Abhinav Vedmala <abhinav@openai.com>
Date: Wed, 6 May 2026 11:42:20 -0700
Subject: [PATCH] Document hook input inversions

---
 codex-rs/core/src/tools/handlers/apply_patch.rs  | 3 +++
 codex-rs/core/src/tools/handlers/mcp.rs          | 3 +++
 codex-rs/core/src/tools/handlers/shell.rs        | 2 ++
 codex-rs/core/src/tools/handlers/unified_exec.rs | 2 ++
 4 files changed, 10 insertions(+)

diff --git a/codex-rs/core/src/tools/handlers/apply_patch.rs b/codex-rs/core/src/tools/handlers/apply_patch.rs
index 37e663c553..1dc06780ae 100644
--- a/codex-rs/core/src/tools/handlers/apply_patch.rs
+++ b/codex-rs/core/src/tools/handlers/apply_patch.rs
@@ -325,6 +325,9 @@ impl ToolHandler for ApplyPatchHandler {
         })
     }
 
+    // Hooks expose apply_patch through the stable `{ "command": ... }` shape,
+    // while the underlying tool stores the patch as either the function
+    // argument `input` or freeform custom-tool input.
     fn with_updated_hook_input(
         &self,
         mut invocation: ToolInvocation,
diff --git a/codex-rs/core/src/tools/handlers/mcp.rs b/codex-rs/core/src/tools/handlers/mcp.rs
index d00d6e6b0f..7397f5a45b 100644
--- a/codex-rs/core/src/tools/handlers/mcp.rs
+++ b/codex-rs/core/src/tools/handlers/mcp.rs
@@ -48,6 +48,9 @@ impl ToolHandler for McpHandler {
         })
     }
 
+    // MCP hooks expose the full arguments object, so rewrites replace the
+    // serialized raw argument payload wholesale rather than patching one
+    // handler-owned field.
     fn with_updated_hook_input(
         &self,
         mut invocation: ToolInvocation,
diff --git a/codex-rs/core/src/tools/handlers/shell.rs b/codex-rs/core/src/tools/handlers/shell.rs
index 8524fa7713..45365dfbfd 100644
--- a/codex-rs/core/src/tools/handlers/shell.rs
+++ b/codex-rs/core/src/tools/handlers/shell.rs
@@ -379,6 +379,8 @@ impl ToolHandler for LocalShellHandler {
         })
     }
 
+    // Hooks see a joined shell command string, but local_shell stores argv.
+    // Split on the way back in to invert the hook-facing representation.
     fn with_updated_hook_input(
         &self,
         mut invocation: ToolInvocation,
diff --git a/codex-rs/core/src/tools/handlers/unified_exec.rs b/codex-rs/core/src/tools/handlers/unified_exec.rs
index 2c19c6b6c7..1f56841425 100644
--- a/codex-rs/core/src/tools/handlers/unified_exec.rs
+++ b/codex-rs/core/src/tools/handlers/unified_exec.rs
@@ -164,6 +164,8 @@ impl ToolHandler for ExecCommandHandler {
             })
     }
 
+    // Hooks normalize Bash-like tools to `{ "command": ... }`, while the
+    // exec_command wire schema still names the field `cmd`.
     fn with_updated_hook_input(
         &self,
         mut invocation: ToolInvocation,