PreToolUse hooks don't block in headless (-p) mode or with allowedTools wildcard

[synman]

Description

PreToolUse hooks that exit with code 2 (deny) do not block tool execution in two scenarios:

1. Headless mode (-p / --print): Hooks fire (confirmed via file evidence logging) but the tool executes anyway. The exit-2 denial arrives after execution.

2. allowedTools: ["*"]: The hook pipeline is skipped entirely — hooks never fire. This makes it impossible to pre-approve all tools while still running enforcement hooks.

Expected Behavior

• In -p mode: PreToolUse hooks should run synchronously before tool execution. Exit 2 should prevent the tool from running, and the {"reason":"..."} should be fed back to the agent so it can choose an alternative.
• With allowedTools: ["*"]: Hooks should still fire. allowedTools should skip the user permission prompt, not the hook pipeline.

Actual Behavior

• In -p mode: Tool executes before hook denial arrives (async race condition)
• With allowedTools: ["*"]: Hooks are never called at all

Reproduction

Setup

// settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "/tmp/test-block.sh",
            "timeout": 5
          }
        ]
      }
    ]
  },
  "allowedTools": ["*"]
}

# /tmp/test-block.sh
#!/usr/bin/env bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // ""')
echo "HOOK FIRED" >> /tmp/hook-evidence.log
echo "{\"reason\":\"Blocked: use MCP tool instead of $COMMAND\"}" >&2
exit 2

Test 1: allowedTools wildcard

rm -f /tmp/hook-evidence.log
claude -p "run: echo hello"
cat /tmp/hook-evidence.log  # → file does not exist (hook never fired)

Test 2: headless mode (without allowedTools wildcard)

// settings.json — change allowedTools to exclude Bash
{ "allowedTools": ["Read", "Edit", "Write", "Glob", "Grep"] }

rm -f /tmp/hook-evidence.log
claude -p "run: echo hello"
cat /tmp/hook-evidence.log  # → "HOOK FIRED" (hook ran, but tool still executed)

Use Case

We run a governance framework (isaac) with PreToolUse:Bash hooks that enforce MCP-first tool usage — when an agent tries git status via Bash, the hook blocks it and directs the agent to use a fork-free MCP tool (git_status via dulwich). This is critical for preventing fork exhaustion (kern.maxprocperuid limit).

The current behavior makes it impossible to:

• Pre-approve all tools (allowedTools: ["*"]) while keeping hook enforcement
• Run headless sessions (-p) with hook enforcement

We need allowedTools to control user prompts and hooks to control agent behavior — independently.

Environment

• Claude Code: v2.1.79
• OS: macOS 15.5 (Apple Silicon)
• Related: [BUG] PreToolUse hooks don't block command execution in bypass mode #20946 (hooks async in bypass mode), [BUG] PreToolUse hook exit code 2 causes Claude to stop instead of acting on error feedback #24327 (exit 2 causes stop instead of feedback)

🤖 Generated with Claude Code

[github-actions]

Found 3 possible duplicate issues:

1. PreToolUse hooks and --allowedTools not enforced in headless -p mode #33343
2. [BUG] hooks don't run in headless mode #20063
3. PreToolUse/PostToolUse hooks don't fire in non-interactive -p mode #30143

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[synman]

Would be really cool to see this fixed... Even if a dupe

[yurukusa]

This is an important finding for anyone relying on hooks for safety in CI/automation pipelines.

Workaround for headless mode:

Since exit 2 is ignored in -p mode, you can make the hook's block physical instead of relying on the exit code:

#!/bin/bash
# In headless mode, chmod the file or kill the dangerous process
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if echo "$CMD" | grep -qE 'rm\s+-rf|git\s+reset\s+--hard'; then
    # Physical block: create a lock file that the command will fail on
    # Or: rename the target to prevent deletion
    echo "BLOCKED (headless mode defense)" >&2

    # For rm -rf: make target immutable
    TARGET=$(echo "$CMD" | grep -oP 'rm\s+-rf\s+\K\S+')
    [ -n "$TARGET" ] && [ -e "$TARGET" ] && chmod 000 "$TARGET" 2>/dev/null

    exit 2  # Still try exit 2, but also use physical block
fi
exit 0

cc-safe-setup's destructive-guard uses exit 2 which works in interactive mode but not -p mode per this bug. I'll add a note to the README about this limitation.

For CI pipelines: consider using --dangerously-skip-permissions with hooks rather than -p mode, if hooks need to enforce safety.