Explain hook opt outs

codex-rs/core/src/tools/code_mode/wait_handler.rs

@@ -115,6 +115,10 @@ impl ToolExecutor<ToolInvocation> for CodeModeWaitHandler {
 
 impl CoreToolRuntime for CodeModeWaitHandler {
     fn pre_tool_use_payload(&self, _invocation: &ToolInvocation) -> Option<PreToolUsePayload> {
+        // Code-mode `wait` is runtime control for an existing code cell, not a
+        // standalone user action. Tool calls made from code mode still flow
+        // through normal dispatch, but hooks should not block or rewrite the
+        // wait loop itself.
         None
     }
 
@@ -123,6 +127,8 @@ impl CoreToolRuntime for CodeModeWaitHandler {
         _invocation: &ToolInvocation,
         _result: &dyn ToolOutput,
     ) -> Option<PostToolUsePayload> {
+        // The wait result feeds code-mode control flow, so do not let
+        // PostToolUse replace it with model-facing hook feedback.
         None
     }
 }

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

@@ -103,6 +103,9 @@ impl CoreToolRuntime for WriteStdinHandler {
     }
 
     fn pre_tool_use_payload(&self, _invocation: &ToolInvocation) -> Option<PreToolUsePayload> {
+        // `write_stdin` is transport for an existing exec session. Empty writes
+        // are background polls, and non-empty writes continue a command that
+        // already ran PreToolUse as Bash, so do not emit a second pre hook here.
         None
     }
 
@@ -111,6 +114,8 @@ impl CoreToolRuntime for WriteStdinHandler {
         invocation: &ToolInvocation,
         result: &dyn crate::tools::context::ToolOutput,
     ) -> Option<PostToolUsePayload> {
+        // A `write_stdin` poll can observe final completion for the original
+        // `exec_command`; emit that command's matching Bash PostToolUse.
         post_unified_exec_tool_use_payload(invocation, result)
     }
 }