Claude Code hooks for safety

Claude Code hooks are shell commands (or HTTP endpoints, MCP tool calls, model prompts, or subagents) that Claude Code runs at fixed points in a session, handing each one the event as JSON. For safety, three events matter. PreToolUse runs before a tool call and can deny it. PostToolUse runs after a call succeeds; it can’t undo anything, but it can record what the call proved. Stop runs when Claude finishes responding and can send it back to work. A command hook is code outside the model: write it as a fixed rule and it gives the same answer every time, but it can only judge what it is shown.

The three Claude Code hooks that do safety work

Every command hook speaks the same protocol: the event arrives on stdin, and the hook answers with an exit code and, optionally, JSON on stdout. Two details decide whether a guard actually guards (both straight from the hooks reference):

• Exit 2 blocks. Exit 1 does not. Without valid JSON on stdout, Claude Code treats exit 1 as a non-blocking error and runs the tool anyway. A policy hook that fails with the usual Unix error code is a hook that allows.
• A hook that fails is not a hook that denies. A mistyped script path, a hook that can’t start, or a PreToolUse hook that hits its timeout all end the same way: the call continues through the normal permission flow. Watch the first run of any guard you add.

A real PreToolUse deny, byte for byte

This is what Bulkhead’s PreToolUse handler printed when the agent in our scripted demo session tried git push --force origin main: real engine output, from the session the home page prints.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "⛔ Bulkhead blocked this action.\nGuard: blocked-commands\nRule: force-push-protected-branch\nWhy: Force-push to a protected branch (main/master) — refusing.\nThis is a deterministic policy check that runs outside the model and cannot be overridden by reasoning.\nTo proceed, a human must change bulkhead.yaml or perform this action manually."
  },
  "systemMessage": "🛡 Bulkhead blocked: git push --force origin main — force-push to a protected branch (ledger #7)"
}

⛔ Bulkhead blocked this action.
Guard: blocked-commands
Rule: force-push-protected-branch
Why: Force-push to a protected branch (main/master) — refusing.
This is a deterministic policy check that runs outside the model and cannot be overridden by reasoning.
To proceed, a human must change bulkhead.yaml or perform this action manually.

Three fields do the work. permissionDecision: "deny" stops the call; when hooks disagree, deny beats defer, ask and allow. permissionDecisionReason goes to Claude, not to you, and says the check is deterministic so the agent doesn’t argue with it. systemMessage is the one line you see, because a reason only Claude reads makes every block invisible to the human.

When Bulkhead has no objection it returns no permission decision (only {"suppressOutput":true}). It never returns "allow", which would skip the permission prompt and override your own settings; silence leaves Claude Code’s normal permission flow in charge.

Stop uses a different shape: a top-level decision: "block" and a reason Claude has to act on. Here is the completion check refusing a false “All tests pass” (reason cut at the evidence line):

{
  "decision": "block",
  "reason": "⛔ Bulkhead completion check failed.\nYou stated \"All tests pass\" but the evidence ledger disagrees — the latest relevant evidence is: test_failed: npm test (exit 1) …",
  "systemMessage": "🛡 Bulkhead: agent said \"All tests pass\" but the latest `npm test` exited 1 — sent back to work (ledger #8)"
}

Claude Code caps this: after 8 consecutive Stop blocks it ends the turn anyway, and the stop_hook_active input flag tells a hook it is already in a retry (docs). Bulkhead records the verdict on a retry and doesn’t block twice, so a completion check can’t trap a session.

Eight guards to copy

Each is a snippet of bulkhead.yaml, the file npx @bulkheadtools/cli init writes and you own. Your rules add to the built-ins; deleting a built-in line doesn’t switch it off. Patterns are case-insensitive regexes over the whole Bash command. We ran every snippet through the 0.2.0 engine before publishing it.

# 01 · paths the agent may never write
protected_paths:
  deny:
    - "infra/**"
    - "secrets/**"
    - "**/*.pem"

blocked_commands:
  # 02 · no production deploys from the agent
  - pattern: '\b(?:vercel|netlify)\b[^\n;&|]*\s--prod\b'
    message: "Production deploy (a human runs this one)"
  # 03 · no package publishing (dry runs pass)
  - pattern: '\b(?:npm|pnpm|yarn)\s+publish\b(?![^\n;&|]*--dry-run)'
    message: "Package publish"
  # 04 · hands off the production cluster
  - pattern: '\bkubectl\b[^\n;&|]*--context[= ]\S*prod'
    message: "kubectl against a production context"

# 05 · a hard dollar cap
budget:
  session_usd: 5
  daily_usd: 20

# 06 · freeze a loop
loop:
  max_repeats: 8
  window_seconds: 300

# 07 · refuse a false "done"
verify:
  mode: block
  block_on_missing: false

# 08 · ask before it leaves the machine
risky:
  mode: ask
  min_level: high

Without Bulkhead: a minimal plain hook

If you would rather own a dozen lines of shell, here is guard 2 as a standalone PreToolUse hook. It needs jq, and it exits 2, not 1.

#!/usr/bin/env bash
# Minimal PreToolUse guard. No Bulkhead; needs jq.
# Claude Code sends the tool call as JSON on stdin.
cmd=$(jq -r '.tool_input.command // empty')

if printf '%s' "$cmd" | grep -Eq '(vercel|netlify)[^;&|]*--prod'; then
  echo "Blocked: production deploys are run by a human, not the agent." >&2
  exit 2   # 2 blocks the call; stderr is the reason Claude reads
fi

exit 0     # no opinion: the normal permission flow decides

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/deny-prod-deploy.sh"
          }
        ]
      }
    ]
  }
}

Make it executable, then feed it a fake tool call before you trust it:

chmod +x .claude/hooks/deny-prod-deploy.sh
echo '{"tool_input":{"command":"vercel --prod"}}' | .claude/hooks/deny-prod-deploy.sh
echo $?   # 2 means blocked

What hooks can’t see

A hook judges only the tool call it is handed. Everything below gets past a command-string rule, ours included. The last column is what covers it.

The first four are pinned as known misses in Bulkhead’s open corpus, next to its 26 denials and 15 ordinary commands let through, so you can see where the line is: run the proof. The layer that covers them is in sandbox vs guardrails. Then install the hooks:

npx @bulkheadtools/cli init

init writes bulkhead.yaml and merges PreToolUse, PostToolUse and Stop entries into .claude/settings.json, each with a 10-second timeout. It works in Manual, acceptEdits and auto mode; auto mode vs deterministic hooks shows how the layers stack.

Questions