[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);
+}

codex-rs/core/tests/suite/hooks.rs

@@ -174,6 +174,69 @@ if payload.get("prompt") == {blocked_prompt_json}:
     Ok(())
 }
 
+fn write_pre_tool_use_hook(
+    home: &Path,
+    matcher: Option<&str>,
+    mode: &str,
+    reason: &str,
+) -> Result<()> {
+    let script_path = home.join("pre_tool_use_hook.py");
+    let log_path = home.join("pre_tool_use_hook_log.jsonl");
+    let mode_json = serde_json::to_string(mode).context("serialize pre tool use mode")?;
+    let reason_json = serde_json::to_string(reason).context("serialize pre tool use reason")?;
+    let script = format!(
+        r#"import json
+from pathlib import Path
+import sys
+
+log_path = Path(r"{log_path}")
+mode = {mode_json}
+reason = {reason_json}
+
+payload = json.load(sys.stdin)
+
+with log_path.open("a", encoding="utf-8") as handle:
+    handle.write(json.dumps(payload) + "\n")
+
+if mode == "json_deny":
+    print(json.dumps({{
+        "hookSpecificOutput": {{
+            "hookEventName": "PreToolUse",
+            "permissionDecision": "deny",
+            "permissionDecisionReason": reason
+        }}
+    }}))
+elif mode == "exit_2":
+    sys.stderr.write(reason + "\n")
+    raise SystemExit(2)
+"#,
+        log_path = log_path.display(),
+        mode_json = mode_json,
+        reason_json = reason_json,
+    );
+
+    let mut group = serde_json::json!({
+        "hooks": [{
+            "type": "command",
+            "command": format!("python3 {}", script_path.display()),
+            "statusMessage": "running pre tool use hook",
+        }]
+    });
+    if let Some(matcher) = matcher {
+        group["matcher"] = Value::String(matcher.to_string());
+    }
+
+    let hooks = serde_json::json!({
+        "hooks": {
+            "PreToolUse": [group]
+        }
+    });
+
+    fs::write(&script_path, script).context("write pre tool use hook script")?;
+    fs::write(home.join("hooks.json"), hooks.to_string()).context("write hooks.json")?;
+    Ok(())
+}
+
 fn write_session_start_hook_recording_transcript(home: &Path) -> Result<()> {
     let script_path = home.join("session_start_hook.py");
     let log_path = home.join("session_start_hook_log.jsonl");
@@ -253,6 +316,15 @@ fn read_stop_hook_inputs(home: &Path) -> Result<Vec<serde_json::Value>> {
         .collect()
 }
 
+fn read_pre_tool_use_hook_inputs(home: &Path) -> Result<Vec<serde_json::Value>> {
+    fs::read_to_string(home.join("pre_tool_use_hook_log.jsonl"))
+        .context("read pre tool use hook log")?
+        .lines()
+        .filter(|line| !line.trim().is_empty())
+        .map(|line| serde_json::from_str(line).context("parse pre tool use hook log line"))
+        .collect()
+}
+
 fn read_session_start_hook_inputs(home: &Path) -> Result<Vec<serde_json::Value>> {
     fs::read_to_string(home.join("session_start_hook_log.jsonl"))
         .context("read session start hook log")?
@@ -849,3 +921,357 @@ async fn blocked_queued_prompt_does_not_strand_earlier_accepted_prompt() -> Resu
     server.shutdown().await;
     Ok(())
 }
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn pre_tool_use_blocks_shell_command_before_execution() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let call_id = "pretooluse-shell-command";
+    let marker = std::env::temp_dir().join("pretooluse-shell-command-marker");
+    let command = format!("printf blocked > {}", marker.display());
+    let args = serde_json::json!({ "command": command });
+    let responses = mount_sse_sequence(
+        &server,
+        vec![
+            sse(vec![
+                ev_response_created("resp-1"),
+                core_test_support::responses::ev_function_call(
+                    call_id,
+                    "shell_command",
+                    &serde_json::to_string(&args)?,
+                ),
+                ev_completed("resp-1"),
+            ]),
+            sse(vec![
+                ev_response_created("resp-2"),
+                ev_assistant_message("msg-1", "hook blocked it"),
+                ev_completed("resp-2"),
+            ]),
+        ],
+    )
+    .await;
+
+    let mut builder = test_codex()
+        .with_pre_build_hook(|home| {
+            if let Err(error) =
+                write_pre_tool_use_hook(home, Some("^Bash$"), "json_deny", "blocked by pre hook")
+            {
+                panic!("failed to write pre tool use hook test fixture: {error}");
+            }
+        })
+        .with_config(|config| {
+            config
+                .features
+                .enable(Feature::CodexHooks)
+                .expect("test config should allow feature update");
+        });
+    let test = builder.build(&server).await?;
+
+    if marker.exists() {
+        fs::remove_file(&marker).context("remove leftover pre tool use marker")?;
+    }
+
+    test.submit_turn_with_policy(
+        "run the blocked shell command",
+        codex_protocol::protocol::SandboxPolicy::DangerFullAccess,
+    )
+    .await?;
+
+    let requests = responses.requests();
+    assert_eq!(requests.len(), 2);
+    let output_item = requests[1].function_call_output(call_id);
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("shell command output string");
+    assert!(
+        output.contains("Bash command blocked by hook: blocked by pre hook"),
+        "blocked tool output should surface the hook reason",
+    );
+    assert!(
+        output.contains(&format!("Command: {command}")),
+        "blocked tool output should surface the blocked command",
+    );
+    assert!(
+        !marker.exists(),
+        "blocked command should not create marker file"
+    );
+
+    let hook_inputs = read_pre_tool_use_hook_inputs(test.codex_home_path())?;
+    assert_eq!(hook_inputs.len(), 1);
+    assert_eq!(hook_inputs[0]["hook_event_name"], "PreToolUse");
+    assert_eq!(hook_inputs[0]["tool_name"], "Bash");
+    assert_eq!(hook_inputs[0]["tool_use_id"], call_id);
+    assert_eq!(hook_inputs[0]["tool_input"]["command"], command);
+    let transcript_path = hook_inputs[0]["transcript_path"]
+        .as_str()
+        .expect("pre tool use hook transcript_path");
+    assert!(
+        !transcript_path.is_empty(),
+        "pre tool use hook should receive a non-empty transcript_path",
+    );
+    assert!(
+        Path::new(transcript_path).exists(),
+        "pre tool use hook transcript_path should be materialized on disk",
+    );
+    assert!(
+        hook_inputs[0]["turn_id"]
+            .as_str()
+            .is_some_and(|turn_id| !turn_id.is_empty())
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn pre_tool_use_blocks_local_shell_before_execution() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let call_id = "pretooluse-local-shell";
+    let marker = std::env::temp_dir().join("pretooluse-local-shell-marker");
+    let command = vec![
+        "/bin/sh".to_string(),
+        "-c".to_string(),
+        format!("printf blocked > {}", marker.display()),
+    ];
+    let responses = mount_sse_sequence(
+        &server,
+        vec![
+            sse(vec![
+                ev_response_created("resp-1"),
+                core_test_support::responses::ev_local_shell_call(
+                    call_id,
+                    "completed",
+                    command.iter().map(String::as_str).collect(),
+                ),
+                ev_completed("resp-1"),
+            ]),
+            sse(vec![
+                ev_response_created("resp-2"),
+                ev_assistant_message("msg-1", "local shell blocked"),
+                ev_completed("resp-2"),
+            ]),
+        ],
+    )
+    .await;
+
+    let mut builder = test_codex()
+        .with_pre_build_hook(|home| {
+            if let Err(error) =
+                write_pre_tool_use_hook(home, Some("^Bash$"), "json_deny", "blocked local shell")
+            {
+                panic!("failed to write pre tool use hook test fixture: {error}");
+            }
+        })
+        .with_config(|config| {
+            config
+                .features
+                .enable(Feature::CodexHooks)
+                .expect("test config should allow feature update");
+        });
+    let test = builder.build(&server).await?;
+
+    if marker.exists() {
+        fs::remove_file(&marker).context("remove leftover local shell marker")?;
+    }
+
+    test.submit_turn("run the blocked local shell command")
+        .await?;
+
+    let requests = responses.requests();
+    assert_eq!(requests.len(), 2);
+    let output_item = requests[1].function_call_output(call_id);
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("local shell output string");
+    assert!(
+        output.contains("Bash command blocked by hook: blocked local shell"),
+        "blocked local shell output should surface the hook reason",
+    );
+    assert!(
+        output.contains(&format!(
+            "Command: {}",
+            codex_shell_command::parse_command::shlex_join(&command)
+        )),
+        "blocked local shell output should surface the blocked command",
+    );
+    assert!(
+        !marker.exists(),
+        "blocked local shell command should not execute"
+    );
+
+    let hook_inputs = read_pre_tool_use_hook_inputs(test.codex_home_path())?;
+    assert_eq!(hook_inputs.len(), 1);
+    assert_eq!(
+        hook_inputs[0]["tool_input"]["command"],
+        codex_shell_command::parse_command::shlex_join(&command),
+    );
+    assert!(
+        hook_inputs[0]["turn_id"]
+            .as_str()
+            .is_some_and(|turn_id| !turn_id.is_empty())
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn pre_tool_use_blocks_exec_command_before_execution() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let call_id = "pretooluse-exec-command";
+    let marker = std::env::temp_dir().join("pretooluse-exec-command-marker");
+    let command = format!("printf blocked > {}", marker.display());
+    let args = serde_json::json!({ "cmd": command });
+    let responses = mount_sse_sequence(
+        &server,
+        vec![
+            sse(vec![
+                ev_response_created("resp-1"),
+                core_test_support::responses::ev_function_call(
+                    call_id,
+                    "exec_command",
+                    &serde_json::to_string(&args)?,
+                ),
+                ev_completed("resp-1"),
+            ]),
+            sse(vec![
+                ev_response_created("resp-2"),
+                ev_assistant_message("msg-1", "exec command blocked"),
+                ev_completed("resp-2"),
+            ]),
+        ],
+    )
+    .await;
+
+    let mut builder = test_codex()
+        .with_pre_build_hook(|home| {
+            if let Err(error) =
+                write_pre_tool_use_hook(home, Some("^Bash$"), "exit_2", "blocked exec command")
+            {
+                panic!("failed to write pre tool use hook test fixture: {error}");
+            }
+        })
+        .with_config(|config| {
+            config.use_experimental_unified_exec_tool = true;
+            config
+                .features
+                .enable(Feature::CodexHooks)
+                .expect("test config should allow feature update");
+            config
+                .features
+                .enable(Feature::UnifiedExec)
+                .expect("test config should allow feature update");
+        });
+    let test = builder.build(&server).await?;
+
+    if marker.exists() {
+        fs::remove_file(&marker).context("remove leftover exec marker")?;
+    }
+
+    test.submit_turn("run the blocked exec command").await?;
+
+    let requests = responses.requests();
+    assert_eq!(requests.len(), 2);
+    let output_item = requests[1].function_call_output(call_id);
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("exec command output string");
+    assert!(
+        output.contains("Bash command blocked by hook: blocked exec command"),
+        "blocked exec command output should surface the hook reason",
+    );
+    assert!(
+        output.contains(&format!("Command: {command}")),
+        "blocked exec command output should surface the blocked command",
+    );
+    assert!(!marker.exists(), "blocked exec command should not execute");
+
+    let hook_inputs = read_pre_tool_use_hook_inputs(test.codex_home_path())?;
+    assert_eq!(hook_inputs.len(), 1);
+    assert_eq!(hook_inputs[0]["tool_use_id"], call_id);
+    assert_eq!(hook_inputs[0]["tool_input"]["command"], command);
+    assert!(
+        hook_inputs[0]["turn_id"]
+            .as_str()
+            .is_some_and(|turn_id| !turn_id.is_empty())
+    );
+
+    Ok(())
+}
+
+#[tokio::test(flavor = "multi_thread", worker_threads = 2)]
+async fn pre_tool_use_does_not_fire_for_non_shell_tools() -> Result<()> {
+    skip_if_no_network!(Ok(()));
+
+    let server = start_mock_server().await;
+    let call_id = "pretooluse-update-plan";
+    let args = serde_json::json!({
+        "plan": [{
+            "step": "watch the tide",
+            "status": "pending",
+        }]
+    });
+    let responses = mount_sse_sequence(
+        &server,
+        vec![
+            sse(vec![
+                ev_response_created("resp-1"),
+                core_test_support::responses::ev_function_call(
+                    call_id,
+                    "update_plan",
+                    &serde_json::to_string(&args)?,
+                ),
+                ev_completed("resp-1"),
+            ]),
+            sse(vec![
+                ev_response_created("resp-2"),
+                ev_assistant_message("msg-1", "plan updated"),
+                ev_completed("resp-2"),
+            ]),
+        ],
+    )
+    .await;
+
+    let mut builder = test_codex()
+        .with_pre_build_hook(|home| {
+            if let Err(error) = write_pre_tool_use_hook(home, None, "json_deny", "should not fire")
+            {
+                panic!("failed to write pre tool use hook test fixture: {error}");
+            }
+        })
+        .with_config(|config| {
+            config
+                .features
+                .enable(Feature::CodexHooks)
+                .expect("test config should allow feature update");
+        });
+    let test = builder.build(&server).await?;
+
+    test.submit_turn("update the plan").await?;
+
+    let requests = responses.requests();
+    assert_eq!(requests.len(), 2);
+    let output_item = requests[1].function_call_output(call_id);
+    let output = output_item
+        .get("output")
+        .and_then(Value::as_str)
+        .expect("update plan output string");
+    assert!(
+        !output.contains("should not fire"),
+        "non-shell tool output should not be blocked by PreToolUse",
+    );
+
+    let hook_log_path = test.codex_home_path().join("pre_tool_use_hook_log.jsonl");
+    assert!(
+        !hook_log_path.exists(),
+        "non-shell tools should not trigger pre tool use hooks",
+    );
+
+    Ok(())
+}

codex-rs/core/tests/suite/otel.rs

@@ -973,6 +973,7 @@ async fn handle_response_item_records_tool_result_for_local_shell_call() {
                 .features
                 .disable(Feature::GhostCommit)
                 .expect("test config should allow feature update");
+            config.permissions.approval_policy = Constrained::allow_any(AskForApproval::Never);
         })
         .build(&server)
         .await
@@ -989,7 +990,7 @@ async fn handle_response_item_records_tool_result_for_local_shell_call() {
         .await
         .unwrap();
 
-    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TokenCount(_))).await;
+    wait_for_event(&codex, |ev| matches!(ev, EventMsg::TurnComplete(_))).await;
 
     logs_assert(|lines: &[&str]| {
         let line = lines