[hooks] add non-streaming (non-stdin style) shell-only PreToolUse support (#15211)

- add `PreToolUse` hook for bash-like tool execution only at first
- block shell execution before dispatch with deny-only hook behavior
- introduces common.rs matcher framework for matching when hooks are run

example run:

```
› run three parallel echo commands, and the second one should echo "[block-pre-tool-use]" as a test


• Running the three echo commands in parallel now and I’ll report the output directly.

• Running PreToolUse hook: name for demo pre tool use hook

• Running PreToolUse hook: name for demo pre tool use hook

• Running PreToolUse hook: name for demo pre tool use hook

PreToolUse hook (completed)
  warning: wizard-tower PreToolUse demo inspected Bash: echo "first parallel echo"
  
PreToolUse hook (blocked)
  warning: wizard-tower PreToolUse demo blocked a Bash command on purpose.
  feedback: PreToolUse demo blocked the command. Remove [block-pre-tool-use] to continue.

PreToolUse hook (completed)
  warning: wizard-tower PreToolUse demo inspected Bash: echo "third parallel echo"

• Ran echo "first parallel echo"
  └ first parallel echo

• Ran echo "third parallel echo"
  └ third parallel echo

• Three little waves went out in parallel.

  1. printed first parallel echo
  2. was blocked before execution because it contained the exact test string [block-pre-tool-use]
  3. printed third parallel echo

  There was also an unrelated macOS defaults warning around the successful commands, but the echoes
  themselves worked fine. If you want, I can rerun the second one with a slightly modified string so
  it passes cleanly.
```

codex-rs/core/src/hook_runtime.rs

@@ -1,6 +1,8 @@
 use std::future::Future;
 use std::sync::Arc;
 
+use codex_hooks::PreToolUseOutcome;
+use codex_hooks::PreToolUseRequest;
 use codex_hooks::SessionStartOutcome;
 use codex_hooks::UserPromptSubmitOutcome;
 use codex_hooks::UserPromptSubmitRequest;
@@ -109,6 +111,36 @@ pub(crate) async fn run_pending_session_start_hooks(
     .await
 }
 
+pub(crate) async fn run_pre_tool_use_hooks(
+    sess: &Arc<Session>,
+    turn_context: &Arc<TurnContext>,
+    tool_use_id: String,
+    command: String,
+) -> Option<String> {
+    let request = PreToolUseRequest {
+        session_id: sess.conversation_id,
+        turn_id: turn_context.sub_id.clone(),
+        cwd: turn_context.cwd.clone(),
+        transcript_path: sess.hook_transcript_path().await,
+        model: turn_context.model_info.slug.clone(),
+        permission_mode: hook_permission_mode(turn_context),
+        tool_name: "Bash".to_string(),
+        tool_use_id,
+        command,
+    };
+    let preview_runs = sess.hooks().preview_pre_tool_use(&request);
+    emit_hook_started_events(sess, turn_context, preview_runs).await;
+
+    let PreToolUseOutcome {
+        hook_events,
+        should_block,
+        block_reason,
+    } = sess.hooks().run_pre_tool_use(request).await;
+    emit_hook_completed_events(sess, turn_context, hook_events).await;
+
+    if should_block { block_reason } else { None }
+}
+
 pub(crate) async fn run_user_prompt_submit_hooks(
     sess: &Arc<Session>,
     turn_context: &Arc<TurnContext>,

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

@@ -5,6 +5,7 @@ use std::time::Instant;
 
 use crate::client_common::tools::ToolSpec;
 use crate::function_tool::FunctionCallError;
+use crate::hook_runtime::run_pre_tool_use_hooks;
 use crate::memories::usage::emit_metric_for_tool_read;
 use crate::protocol::SandboxPolicy;
 use crate::sandbox_tags::sandbox_tag;
@@ -20,7 +21,10 @@ use codex_hooks::HookToolInput;
 use codex_hooks::HookToolInputLocalShell;
 use codex_hooks::HookToolKind;
 use codex_protocol::models::ResponseInputItem;
+use codex_protocol::models::ShellCommandToolCallParams;
+use codex_protocol::models::ShellToolCallParams;
 use codex_utils_readiness::Readiness;
+use serde::Deserialize;
 use tracing::warn;
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
@@ -243,6 +247,20 @@ impl ToolRegistry {
             return Err(FunctionCallError::Fatal(message));
         }
 
+        if let Some(command) = pre_tool_use_command(tool_name.as_ref(), &invocation.payload)
+            && let Some(reason) = run_pre_tool_use_hooks(
+                &invocation.session,
+                &invocation.turn,
+                invocation.call_id.clone(),
+                command.clone(),
+            )
+            .await
+        {
+            return Err(FunctionCallError::RespondToModel(format!(
+                "Bash command blocked by hook: {reason}. Command: {command}"
+            )));
+        }
+
         let is_mutating = handler.is_mutating(&invocation).await;
         let response_cell = tokio::sync::Mutex::new(None);
         let invocation_for_tool = invocation.clone();
@@ -413,6 +431,35 @@ fn sandbox_policy_tag(policy: &SandboxPolicy) -> &'static str {
     }
 }
 
+#[derive(Deserialize)]
+struct PreToolUseExecCommandArgs {
+    cmd: String,
+}
+
+fn pre_tool_use_command(tool_name: &str, payload: &ToolPayload) -> Option<String> {
+    match (tool_name, payload) {
+        ("shell" | "container.exec", ToolPayload::Function { arguments }) => {
+            serde_json::from_str::<ShellToolCallParams>(arguments)
+                .ok()
+                .map(|params| codex_shell_command::parse_command::shlex_join(&params.command))
+        }
+        ("local_shell", ToolPayload::LocalShell { params }) => Some(
+            codex_shell_command::parse_command::shlex_join(&params.command),
+        ),
+        ("shell_command", ToolPayload::Function { arguments }) => {
+            serde_json::from_str::<ShellCommandToolCallParams>(arguments)
+                .ok()
+                .map(|params| params.command)
+        }
+        ("exec_command", ToolPayload::Function { arguments }) => {
+            serde_json::from_str::<PreToolUseExecCommandArgs>(arguments)
+                .ok()
+                .map(|params| params.cmd)
+        }
+        _ => None,
+    }
+}
+
 // Hooks use a separate wire-facing input type so hook payload JSON stays stable
 // and decoupled from core's internal tool runtime representation.
 impl From<&ToolPayload> for HookToolInput {

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

@@ -1,6 +1,8 @@
 use super::*;
 use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolPayload;
 use async_trait::async_trait;
+use codex_protocol::models::ShellToolCallParams;
 use pretty_assertions::assert_eq;
 
 struct TestHandler;
@@ -48,3 +50,63 @@ fn handler_looks_up_namespaced_aliases_explicitly() {
             .is_some_and(|handler| Arc::ptr_eq(handler, &namespaced_handler))
     );
 }
+
+#[test]
+fn pre_tool_use_command_uses_raw_shell_command_input() {
+    let payload = ToolPayload::Function {
+        arguments: serde_json::json!({ "command": "printf shell command" }).to_string(),
+    };
+
+    assert_eq!(
+        pre_tool_use_command("shell_command", &payload),
+        Some("printf shell command".to_string())
+    );
+}
+
+#[test]
+fn pre_tool_use_command_shell_joins_vector_input() {
+    let payload = ToolPayload::LocalShell {
+        params: ShellToolCallParams {
+            command: vec![
+                "bash".to_string(),
+                "-lc".to_string(),
+                "printf hi".to_string(),
+            ],
+            workdir: None,
+            timeout_ms: None,
+            sandbox_permissions: None,
+            prefix_rule: None,
+            additional_permissions: None,
+            justification: None,
+        },
+    };
+
+    assert_eq!(
+        pre_tool_use_command("local_shell", &payload),
+        Some("bash -lc 'printf hi'".to_string())
+    );
+}
+
+#[test]
+fn pre_tool_use_command_uses_raw_exec_command_input() {
+    let payload = ToolPayload::Function {
+        arguments: serde_json::json!({ "cmd": "printf exec command" }).to_string(),
+    };
+
+    assert_eq!(
+        pre_tool_use_command("exec_command", &payload),
+        Some("printf exec command".to_string())
+    );
+}
+
+#[test]
+fn pre_tool_use_command_skips_non_shell_tools() {
+    let payload = ToolPayload::Function {
+        arguments: serde_json::json!({
+            "plan": [{ "step": "watch the tide", "status": "pending" }]
+        })
+        .to_string(),
+    };
+
+    assert_eq!(pre_tool_use_command("update_plan", &payload), None);
+}