Claude Code Hooks Cookbook: 18 Recipes, All 33 Events

echo '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"}}' | .claude/hooks/block-destructive.sh; echo "exit $?"

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-destructive.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# PreToolUse, matcher "Bash". Exit 2 blocks the call; stderr becomes Claude's reason.
cmd=$(jq -r '.tool_input.command // empty')
patterns=(
  'rm[[:space:]]+-[[:alnum:]-]*[rR][[:alnum:]-]*[[:space:]]+(/|~|\$HOME|\.|\*)/?([[:space:]]|$)'  # rm -rf / ~ $HOME . *
  'mkfs(\.[a-z0-9]+)?[[:space:]]'                                                       # format a filesystem
  'dd[[:space:]].*of=/dev/'                                                             # raw write to a device
  ':\(\)[[:space:]]*\{'                                                                 # fork bomb
  '>[[:space:]]*/dev/(sd|nvme|disk)'                                                    # redirect onto a disk
  'chmod[[:space:]]+-R[[:space:]]+777[[:space:]]+/'                                     # world-writable root
  'git[[:space:]]+push([[:space:]].*)?[[:space:]](--force|-f)([[:space:]]|$)'         # force push (--force-with-lease allowed)
  'git[[:space:]]+reset[[:space:]]+--hard'                                              # discard work
  'git[[:space:]]+clean[[:space:]]+-[[:alnum:]]*f'                                      # delete untracked files
)
for p in "${patterns[@]}"; do
  if [[ "$cmd" =~ $p ]]; then
    echo "Blocked by block-destructive hook (pattern: $p). Use a narrower, reversible command or ask the user to run it." >&2
    exit 2
  fi
done
exit 0

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/rm-to-trash.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# PreToolUse, matcher "Bash". Denies rm / find -delete and tells Claude to move files to .trash/ instead.
cmd=$(jq -r '.tool_input.command // empty')
rm_re='(^|[;&|(][[:space:]]*|sudo[[:space:]]+)rm[[:space:]]'
find_re='find[[:space:]].*-delete'
if [[ "$cmd" =~ $rm_re || "$cmd" =~ $find_re ]]; then
  jq -n --arg cmd "$cmd" '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: ("Deleting is disabled in this project. Instead of `" + $cmd + "`, move the files with: mkdir -p .trash && mv <paths> .trash/  (the user empties .trash/ after review).")
    }
  }'
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/protect-files.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# PreToolUse, matcher "Edit|Write". Blocks edits to secrets, git internals and lockfiles.
path=$(jq -r '.tool_input.file_path // empty')
[[ -z "$path" ]] && exit 0
path=${path//\\//}   # normalize Windows separators
case "$path" in
  */.env.example|*/.env.sample) exit 0 ;;   # templates are fine
  */.env|*/.env.*|*.pem|*.key|*/id_rsa*|*/id_ed25519*|*/.git/*|\
  */package-lock.json|*/yarn.lock|*/pnpm-lock.yaml|*/poetry.lock|*/Cargo.lock|*/uv.lock)
    echo "Protected file: $path. Lockfiles change via the package manager; secrets and .git/ are off-limits. Ask the user if this edit is really needed." >&2
    exit 2 ;;
esac
exit 0

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/secret-scan.py", "args": [] }] }
    ]
  }
}

#!/usr/bin/env python3
"""PreToolUse, matcher "Edit|Write". Blocks writes whose new text contains a credential.
Prints only the pattern name, never the matched value."""
import json, re, sys

PATTERNS = {
    "AWS access key id": r"\bAKIA[0-9A-Z]{16}\b",
    "private key block": r"-----BEGIN [A-Z ]*PRIVATE KEY-----",
    "GitHub token": r"\b(ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{36}\b|\bgithub_pat_[A-Za-z0-9_]{40,}",
    "Anthropic key": r"\bsk-ant-[A-Za-z0-9_\-]{20,}",
    "OpenAI-style key": r"\bsk-(proj-)?[A-Za-z0-9_\-]{32,}",
    "Slack token": r"\bxox[abprs]-[A-Za-z0-9-]{10,}",
    "Stripe live key": r"\b[sr]k_live_[A-Za-z0-9]{20,}",
    "Google API key": r"\bAIza[0-9A-Za-z_\-]{35}\b",
    "hardcoded secret assignment": r"(?i)\b(private[_-]?key|secret|api[_-]?key|access[_-]?token|password)\b\s*[:=]\s*[\"'][A-Za-z0-9_\-/+=]{16,}[\"']",
}

data = json.load(sys.stdin)
ti = data.get("tool_input", {})
text = "\n".join(str(ti.get(k, "")) for k in ("content", "new_string"))
hits = [name for name, rx in PATTERNS.items() if re.search(rx, text)]
if hits:
    print(f"Blocked: the new text for {ti.get('file_path', '?')} looks like it contains: "
          f"{', '.join(hits)}. Load secrets from the environment or a gitignored .env at runtime "
          "instead of writing them into files.", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/format-on-edit.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# PostToolUse, matcher "Edit|Write". Formats the edited file with whatever formatter is installed.
# Never blocks: a missing or failing formatter just leaves the file as written.
f=$(jq -r '.tool_input.file_path // empty')
[[ -f "$f" ]] || exit 0
has() { command -v "$1" >/dev/null 2>&1; }
case "$f" in
  *.ts|*.tsx|*.js|*.jsx|*.mjs|*.css|*.scss|*.json|*.md|*.html|*.yaml|*.yml)
    if has prettier; then prettier --write --log-level warn "$f"
    elif [[ -x node_modules/.bin/prettier ]]; then node_modules/.bin/prettier --write --log-level warn "$f"; fi ;;
  *.py)  has ruff && ruff format --quiet "$f" ;;   # format only: lint --fix would strip imports Claude is about to use
  *.rs)  has rustfmt && rustfmt --edition 2021 "$f" ;;
  *.go)  has gofmt && gofmt -w "$f" ;;
  *.sh)  has shfmt && shfmt -w "$f" ;;
esac >/dev/null 2>&1
exit 0

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/py-check.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# PostToolUse, matcher "Edit|Write". If a Python file no longer parses, hand the error back to Claude.
f=$(jq -r '.tool_input.file_path // empty')
[[ "$f" == *.py && -f "$f" ]] || exit 0
err=$(python3 - "$f" <<'PY'
import ast, sys
try:
    ast.parse(open(sys.argv[1], encoding="utf-8").read(), sys.argv[1])
except SyntaxError as e:
    print(f"{e.filename}:{e.lineno}:{e.offset}: {e.msg}\n    {(e.text or '').rstrip()}")
PY
)
if [[ -n "$err" ]]; then
  jq -n --arg r "Syntax error after editing — fix it before moving on: $err" '{decision: "block", reason: $r}'
fi
exit 0

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "TEST_CMD='pytest -q -x' \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/stop-tests-gate.sh", "timeout": 300 }] }
    ]
  }
}

#!/usr/bin/env bash
# Stop (no matcher). Refuses to let Claude finish while the test suite fails.
# Set TEST_CMD in the hook command (default: npm test --silent).
input=$(cat)
[[ $(jq -r '.stop_hook_active // false' <<<"$input") == "true" ]] && exit 0   # already continuing: don't loop
cd "${CLAUDE_PROJECT_DIR:-$(jq -r '.cwd' <<<"$input")}" || exit 0
# Skip when nothing changed since the last commit: no edits, no reason to re-run tests.
if git rev-parse --git-dir >/dev/null 2>&1 && [[ -z $(git status --porcelain) ]]; then exit 0; fi
if ! out=$(bash -c "${TEST_CMD:-npm test --silent}" 2>&1); then
  { echo "Tests are failing, so the task is not done. Fix them, then finish. Last output:"; tail -n 30 <<<"$out"; } >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/lazy-stop.py", "args": [] }] }
    ]
  }
}

#!/usr/bin/env python3
"""Stop (no matcher). Sends Claude back to work when its final message hands work off
or admits to skipping it."""
import json, re, sys

LAZY = {
    "for brevity": r"\bfor brevity\b",
    "left as an exercise": r"\bleft as an exercise\b",
    "hands work to the user": r"\byou (can|could|may want to) (implement|add|fill in)\b|\bI'?ll leave (that|this|the rest|the \w+)\b",
    "elided code": r"\.\.\. ?(existing|rest of) code|\brest of the (code|implementation) (remains|is) (the same|unchanged)\b",
    "placeholder": r"\bplaceholder (implementation|logic|code)\b|\bnot (yet )?implemented\b",
    "unverified 'should work'": r"\bshould (now )?work\b(?![^.]*\b(tested|ran|passed|verified)\b)",
}
data = json.load(sys.stdin)
if data.get("stop_hook_active"):
    sys.exit(0)                      # one nudge per stop; never loop
msg = data.get("last_assistant_message") or ""
hits = [name for name, rx in LAZY.items() if re.search(rx, msg, re.IGNORECASE)]
if hits:
    print(json.dumps({
        "decision": "block",
        "reason": "Your last message defers or skips work (matched: " + "; ".join(hits[:3]) +
                  "). Finish the remaining work, or state exactly what is blocked and why.",
    }))
sys.exit(0)

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/ai-tells.py", "args": [] }] }
    ]
  }
}

#!/usr/bin/env python3
"""PostToolUse, matcher "Edit|Write". Flags common AI-writing tells in prose files and
tells Claude to revise them. Advisory: never blocks."""
import json, re, sys

TELLS = {
    "delve": r"\bdelv(e|es|ing)\b", "tapestry": r"\btapestry\b", "testament to": r"\btestament to\b",
    "it's important to note": r"\bit'?s (important|worth) (to note|noting)\b",
    "fast-paced world": r"\bin today'?s (fast-paced|digital|ever-evolving)\b",
    "not just X, but Y": r"\bnot (just|only)\b[^.]{1,60}\bbut( also)?\b",
    "game-changer": r"\bgame[- ]changer\b", "seamless(ly)": r"\bseamless(ly)?\b",
    "unlock / unleash": r"\b(unlock|unleash)(es|ing)? the (power|potential)\b",
    "in conclusion": r"\bin conclusion\b", "navigate the landscape": r"\bnavigat\w+ the (complex )?landscape\b",
}
data = json.load(sys.stdin)
ti = data.get("tool_input", {})
path = ti.get("file_path", "")
if not re.search(r"\.(md|mdx|txt|rst|html)$", path):
    sys.exit(0)
text = ti.get("content") or ti.get("new_string") or ""
found = [name for name, rx in TELLS.items() if re.search(rx, text, re.IGNORECASE)]
dashes = text.count("—")
if dashes > max(3, len(text) // 1500):
    found.append(f"{dashes} em dashes")
if found:
    print(json.dumps({"hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "additionalContext": f"{path} contains AI-writing tells: {', '.join(found)}. "
                             "Rewrite those sentences in plain, specific language.",
    }}))
sys.exit(0)

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/audit-bash.sh" }] }
    ],
    "PostToolUseFailure": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/audit-bash.sh" }] }
    ]
  }
}

#!/usr/bin/env bash
# PostToolUse + PostToolUseFailure, matcher "Bash". Appends one JSON line per command Claude ran.
log="${HOOK_AUDIT_LOG:-$HOME/.claude/logs/bash-audit.jsonl}"
mkdir -p "$(dirname "$log")"
jq -c '{
  ts: (now | todate),
  event: .hook_event_name,
  session: .session_id,
  cwd: .cwd,
  command: .tool_input.command,
  ms: .duration_ms
}' >> "$log"
exit 0

{
  "hooks": {
    "PreCompact": [
      { "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/backup-transcript.sh" }] }
    ]
  }
}

#!/usr/bin/env bash
# PreCompact (matcher "manual|auto" or none). Copies the full transcript before it is summarized.
input=$(cat)
src=$(jq -r '.transcript_path // empty' <<<"$input")
[[ -f "$src" ]] || exit 0
sid=$(jq -r '.session_id // "unknown"' <<<"$input")
trigger=$(jq -r '.trigger // "unknown"' <<<"$input")
dest="${HOOK_BACKUP_DIR:-$HOME/.claude/transcript-backups}"
mkdir -p "$dest"
cp "$src" "$dest/$(date -u +%Y%m%dT%H%M%SZ)-${sid}-${trigger}.jsonl"
# keep the newest 50 backups
ls -1t "$dest"/*.jsonl 2>/dev/null | tail -n +51 | while IFS= read -r old; do rm -f -- "$old"; done
exit 0

{
  "hooks": {
    "SessionEnd": [
      { "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/session-ledger.py", "timeout": 10 }] }
    ],
    "StopFailure": [
      { "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/session-ledger.py" }] }
    ]
  }
}

#!/usr/bin/env python3
"""SessionEnd and StopFailure. Appends one JSON line per session end (with tool-call counts
from the transcript) or per API failure (rate_limit, overloaded, billing_error, ...)."""
import collections, datetime, json, os, sys

data = json.load(sys.stdin)
log = os.environ.get("HOOK_LEDGER", os.path.expanduser("~/.claude/logs/sessions.jsonl"))
os.makedirs(os.path.dirname(log), exist_ok=True)
row = {
    "ts": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds"),
    "event": data.get("hook_event_name"),
    "session": data.get("session_id"),
    "cwd": data.get("cwd"),
}
if row["event"] == "StopFailure":
    row["error"] = data.get("error")
else:
    row["reason"] = data.get("reason")
    tools, turns = collections.Counter(), 0
    path = data.get("transcript_path") or ""
    if os.path.isfile(path):
        with open(path, encoding="utf-8", errors="replace") as fh:
            for line in fh:
                try:
                    entry = json.loads(line)
                except ValueError:
                    continue
                msg = entry.get("message") if isinstance(entry, dict) else None
                if not isinstance(msg, dict) or msg.get("role") != "assistant":
                    continue
                turns += 1
                for block in msg.get("content") or []:
                    if isinstance(block, dict) and block.get("type") == "tool_use":
                        tools[block.get("name", "?")] += 1
    row.update(assistant_messages=turns, tool_calls=sum(tools.values()), top_tools=dict(tools.most_common(5)))
with open(log, "a", encoding="utf-8") as fh:
    fh.write(json.dumps(row) + "\n")

{
  "hooks": {
    "Notification": [
      { "matcher": "permission_prompt|idle_prompt",
        "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/notify.sh" }] }
    ]
  }
}

#!/usr/bin/env bash
# Notification (matcher "permission_prompt|idle_prompt", or none for all). Desktop alert with Claude's message.
input=$(cat)
title=$(jq -r '.title // "Claude Code"' <<<"$input")
msg=$(jq -r '.message // "Claude needs your attention"' <<<"$input")
project=$(basename "$(jq -r '.cwd // empty' <<<"$input")")
[[ -n "$project" ]] && title="$title · $project"
if command -v notify-send >/dev/null 2>&1; then                       # Linux
  notify-send --app-name="Claude Code" "$title" "$msg"
elif command -v osascript >/dev/null 2>&1; then                      # macOS
  osascript - "$title" "$msg" <<'OSA'
on run argv
  display notification (item 2 of argv) with title (item 1 of argv) sound name "Glass"
end run
OSA
else                                                                  # anywhere else: terminal bell via Claude Code
  printf '{"terminalSequence":"\\u0007"}\n'
fi
exit 0

{
  "hooks": {
    "Notification": [
      { "matcher": "permission_prompt|idle_prompt",
        "hooks": [{ "type": "command", "command": "\"$HOME\"/.claude/hooks/discord-ping.sh", "async": true }] }
    ]
  }
}

#!/usr/bin/env bash
# Notification, matcher "permission_prompt|idle_prompt". Posts to a Discord webhook so you can
# see from your phone that a session is waiting. Needs DISCORD_WEBHOOK_URL in the environment.
input=$(cat)
payload=$(jq -c '{
  username: "Claude Code",
  content: ("**" + (.notification_type // "notification") + "** in `" + ((.cwd // "?") | split("/") | last) + "`: " + (.message // ""))
}' <<<"$input")
if [[ -n "$HOOK_DRY_RUN" ]]; then echo "$payload"; exit 0; fi
[[ -n "$DISCORD_WEBHOOK_URL" ]] || exit 0
curl -fsS -m 10 -H "Content-Type: application/json" -d "$payload" "$DISCORD_WEBHOOK_URL" >/dev/null || exit 1
exit 0

{
  "hooks": {
    "SessionStart": [
      { "matcher": "startup|resume|compact",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-context.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# SessionStart, matcher "startup|resume|compact". Plain stdout from SessionStart is added to Claude's context.
cd "${CLAUDE_PROJECT_DIR:-.}" || exit 0
echo "## Session context ($(date '+%Y-%m-%d %H:%M %Z'))"
if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "Branch: $(git branch --show-current 2>/dev/null)"
  echo "### Uncommitted changes"; git status --short | head -15
  echo "### Last 5 commits"; git log --oneline -5 2>/dev/null
fi
for f in primer.md .claude/after-compact.md; do          # living state file + rules worth re-reading
  [[ -f "$f" ]] && { echo "### $f"; head -c 4000 "$f"; echo; }
done
exit 0

{
  "hooks": {
    "SubagentStart": [
      { "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/subagent-rules.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# SubagentStart (matcher: agent type, or none for all). Gives every subagent the project's hard rules,
# which it would not otherwise see in full.
rules="${CLAUDE_PROJECT_DIR:-.}/.claude/subagent-rules.md"
[[ -f "$rules" ]] || exit 0
jq -n --rawfile r "$rules" '{hookSpecificOutput: {hookEventName: "SubagentStart", additionalContext: $r}}'
exit 0

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Read|Grep|Glob",
        "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/read-guard.py", "args": [] }] }
    ]
  }
}

#!/usr/bin/env python3
"""PreToolUse, matcher "Read|Grep|Glob". Keeps generated and vendored files out of context and
makes Claude page through very large files instead of reading them whole."""
import json, os, re, sys

NOISE = re.compile(r"(^|/)(node_modules|dist|build|\.next|\.venv|venv|__pycache__|\.git|coverage|vendor)(/|$)"
                   r"|(package-lock\.json|yarn\.lock|pnpm-lock\.yaml|\.min\.(js|css)|\.map)$")
MAX_BYTES = int(os.environ.get("READ_GUARD_MAX_BYTES", 256_000))

def deny(reason):
    print(json.dumps({"hookSpecificOutput": {"hookEventName": "PreToolUse",
                      "permissionDecision": "deny", "permissionDecisionReason": reason}}))
    sys.exit(0)

data = json.load(sys.stdin)
tool, ti = data.get("tool_name"), data.get("tool_input", {})
target = (ti.get("file_path") or ti.get("path") or "").replace("\\", "/")
if target and NOISE.search(target):
    deny(f"{target} is generated or vendored. Read the source that produces it, or grep for one symbol.")
if tool == "Read" and target and not ti.get("limit"):
    try:
        size = os.path.getsize(target)
    except OSError:
        sys.exit(0)
    if size > MAX_BYTES:
        deny(f"{target} is {size // 1024} KB. Grep for what you need, or Read it with offset/limit in chunks.")
sys.exit(0)

{
  "hooks": {
    "PreModelSwitch": [
      { "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/model-switch-guard.sh", "args": [] }] }
    ]
  }
}

#!/usr/bin/env bash
# PreModelSwitch (no matcher). Asks before switching a session onto an Opus-class model.
input=$(cat)
to=$(jq -r '.to_model // empty' <<<"$input")
if [[ "${to,,}" == *opus* ]]; then
  jq -n --arg to "$to" '{hookSpecificOutput: {
    hookEventName: "PreModelSwitch",
    permissionDecision: "ask",
    permissionDecisionReason: ("Switching to " + $to + " costs more per token. Confirm this task needs it.")
  }}'
fi
exit 0

You are a platform engineer hardening my Claude Code setup with hooks. First run `claude --version` and read the hooks reference for that version (code.claude.com/docs/en/hooks); record the exact event names, stdin fields, exit-code semantics, and the structured JSON output schema (permissionDecision, updatedInput, additionalContext, decision/reason for Stop). Install a temporary catch-all hook that dumps stdin for every event into ~/.claude/hook-payloads/ and run one short session to capture real payloads; these become test fixtures. Then build, in a git-tracked ~/.claude/hooks/ directory: block-destructive.sh (PreToolUse, Bash), block-secrets.py (PreToolUse, Edit|Write|MultiEdit, gitleaks-derived patterns), format-on-edit.sh (PostToolUse), session-git-context.sh (SessionStart), bash-audit.sh (PostToolUse, Bash, TSV), precompact-backup.py (PreCompact, async), stop-tests-gate.sh (Stop, honours stop_hook_active). For each: a bats or pytest test feeding fixtures and asserting exit code and output, shellcheck clean, hyperfine timing under 50 ms for PreToolUse. Register them in ~/.claude/settings.json without clobbering existing hooks. Prove each fires in a headless `claude -p --output-format stream-json` session using canary files under /tmp. Return the file tree, the test output, the timing table, and a list of guide claims you found wrong for this version.

ROLE AND STANCE
You are a platform engineer building a deterministic guardrail layer for Claude Code. You treat hooks as production code that runs with the user's full permissions on every tool call. You trust the installed version's documentation and captured payloads over any blog post, including the guide you were given. You never claim a hook works until a live session proves it.

CONTEXT
- Hooks are shell commands the harness (not the model) runs at lifecycle events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop, SubagentStop, PreCompact, SessionEnd, plus newer ones that churn between versions.
- Stdin is JSON (session_id, hook_event_name, tool_name, tool_input, cwd, transcript_path, and per-event fields). Exit 0 allows, exit 2 blocks and feeds stderr to Claude, other non-zero is a non-blocking error.
- Claims from the guide you must TEST, not repeat: (1) 'structured JSON can return {"modified_tool_input": ...} to rewrite arguments' (current docs may name this updatedInput under hookSpecificOutput); (2) '{"decision": "approve"}' as a valid PreToolUse output; (3) 'SessionStart stdout gets injected into Claude's first system message'; (4) 'async: true hooks cannot block or modify'; (5) 'later settings files win for the same key' (hooks may merge rather than override).
- References: code.claude.com/docs/en/hooks, code.claude.com/docs/en/hooks-guide, github.com/disler/claude-code-hooks-mastery, the hookify plugin if installed (/hookify:list).

HARD CONSTRAINTS
- Back up ~/.claude/settings.json to settings.json.bak-<date> before editing. Merge hooks with jq; never overwrite existing entries.
- All scripts live in ~/.claude/hooks/, are git-tracked, executable, shellcheck clean.
- PreToolUse hooks must finish in under 50 ms median (hyperfine, 20 runs).
- Every Stop hook must exit 0 when stop_hook_active is true to prevent infinite loops.
- Destructive tests only against canary paths under /tmp/hooktest-*. Never test against real data.
- The secret blocker reports the pattern name, never the matched value.

ORDERED DELIVERABLES
1. ground-truth.md: claude --version, the event table copied from the installed version's docs, the exact output JSON schema, and a verdict on each of the five guide claims above.
2. A capture hook (temporary) that writes every event's stdin to ~/.claude/hook-payloads/; run one session that triggers Bash, Edit, Write, a subagent, and /compact. Keep the payloads as fixtures in ~/.claude/hooks/tests/fixtures/. Remove the capture hook afterward.
3. Seven hooks: block-destructive.sh, block-secrets.py, format-on-edit.sh, session-git-context.sh, bash-audit.sh, precompact-backup.py (async), stop-tests-gate.sh.
4. tests/: bats or pytest cases, at least three per hook (allow case, block case, malformed-stdin case).
5. settings.json merged entries with matchers (Bash; Edit|Write|MultiEdit; empty matcher for lifecycle events) and timeouts.
6. Live proof: headless runs of `claude -p '...' --output-format stream-json` for the blocker, the secret blocker, and the Stop gate, saved as transcripts in ~/.claude/hooks/proof/.
7. README.md in ~/.claude/hooks/: what each hook does, how to disable (disableAllHooks or removing the entry), and a 'what this cannot stop' section.

BUILT-IN GAP ANALYSIS
Before finishing, write GAPS.md listing: every event you could not trigger live and why; every guide claim that was false or unverifiable on this version; bypasses you found for each blocker (try bash -c, eval, base64 -d | sh, writing a script then running it, MCP tools that write files); hooks whose latency exceeded budget. Fix what you can now (for example extend the Edit matcher to MCP filesystem tools), and mark the rest open with a reason.

SELF-QUESTIONS BEFORE FINISHING
- Did I read the docs for my installed version, or an older page?
- Does any hook print a secret, a full tool_input, or a transcript to stdout where Claude will see it?
- What happens to each hook when jq is missing, stdin is empty, or tool_input lacks the field I read?
- Does the Stop gate handle a repo without tests, and does it honour stop_hook_active?
- Does format-on-edit run on files outside the project (for example ~/.claude itself)?

STOP CONDITIONS
Stop and report when all seven hooks pass their tests and the three live proofs exist, or when a doc/behaviour mismatch blocks a hook (report the mismatch with the doc excerpt and the observed payload). Stop immediately and ask if any test would touch a path outside /tmp/hooktest-* or the hooks directory.

RETURN FORMAT
A single message with: (1) file tree of ~/.claude/hooks; (2) test summary (pass/fail counts per hook); (3) latency table (hook, median ms); (4) verdicts on the five guide claims; (5) the GAPS.md contents; (6) the exact settings.json diff.

Run `claude --version` and record it. Read the hooks reference at code.claude.com/docs/en/hooks and the hooks guide at code.claude.com/docs/en/hooks-guide. Write ~/.claude/hooks/ground-truth.md containing: the full list of hook events with when they fire and whether they can block; the stdin fields common to all events and the extra fields per event (tool_name, tool_input, tool_response, prompt, stop_hook_active, trigger for PreCompact, source for SessionStart); exit-code semantics; the structured JSON output schema (continue, stopReason, suppressOutput, hookSpecificOutput.permissionDecision, permissionDecisionReason, updatedInput, additionalContext, and Stop's decision/reason). Then judge these guide claims as true, false, or renamed for this version: modified_tool_input rewrites args; decision: approve is valid for PreToolUse; SessionStart stdout is injected as context; async hooks cannot block; later settings files override earlier ones for hooks. Next, back up ~/.claude/settings.json, add a temporary catch-all hook on every event that runs `cat > ~/.claude/hook-payloads/$(date +%s%N)-event.json`, start one session that runs a Bash command, edits a file, writes a file, spawns a subagent, and runs /compact, then remove the catch-all. Copy the payloads into ~/.claude/hooks/tests/fixtures/ named by event.

Using the fixtures in ~/.claude/hooks/tests/fixtures/ and the schema in ground-truth.md, write two hooks. (a) block-destructive.sh: read .tool_input.command with jq; block with exit 2 and a one-line stderr reason on rm -rf against /, ~, $HOME or a repo root, mkfs, dd of= to /dev/, fork bombs, chmod -R 777 /, git push --force to main or master, `find ... -exec rm -rf` without a .git prune, and rm -rf of any directory containing a .protected sentinel file (this gives live tests a safe target). Allow everything else. Handle missing jq or empty stdin by exiting 0 and logging to ~/.claude/hooks/errors.log. (b) block-secrets.py: on Edit, Write, and MultiEdit, scan new_string, content, and edits[].new_string against a pattern set derived from gitleaks default rules (AWS keys, GitHub tokens, Anthropic and OpenAI keys, PEM private key headers, 64-hex Ethereum private keys) and exit 2 naming only the rule, never the value. Write bats or pytest cases: three allow, three block, one malformed stdin per hook. Run shellcheck. Time each with `hyperfine --runs 20` piping a fixture; the median must be under 50 ms. Then try to bypass block-destructive with bash -c, eval, base64 -d | sh, and a script file, and record which get through.

Write three hooks using the fixtures. (a) format-on-edit.sh for PostToolUse on Edit|Write|MultiEdit: read .tool_input.file_path, skip files outside the session cwd (from .cwd) and anything under ~/.claude, then dispatch by extension: prettier --write for ts/tsx/js/jsx/json/css/md, ruff format for py, rustfmt for rs, gofmt -w for go. Skip silently if the formatter is not installed. Never exit 2. (b) bash-audit.sh for PostToolUse on Bash: append a TSV row of ISO timestamp, session_id, cwd, and the command with tabs and newlines escaped, to ~/.claude/bash-log.tsv; rotate when the file passes 10 MB. (c) session-git-context.sh for SessionStart: if cwd is a git repo, print the branch, `git status --short | head -10`, and `git log --oneline -5`; print nothing outside a repo. Verify against ground-truth.md whether SessionStart stdout becomes model context on this version and whether JSON additionalContext is the preferred path; use whichever the docs specify. Write tests: format-on-edit actually reformats a badly indented fixture file in /tmp/hooktest-fmt; audit log escapes a multi-line command; git context prints nothing in a non-repo directory.

Write stop-tests-gate.sh for the Stop event. Read stdin; if .stop_hook_active is true, exit 0 immediately to avoid an infinite loop. Detect the test runner from the cwd: pytest if pyproject.toml or pytest.ini exists, `npm test --silent` if package.json has a test script, `cargo test --quiet` for Cargo.toml; if none, exit 0. Run it with a 120-second timeout. On failure, block the stop using the mechanism ground-truth.md specifies for Stop on this version (exit 2 with the failing test names on stderr, or JSON decision: block with a reason), capped to the last 30 lines of output. Write precompact-backup.py for PreCompact, registered async: copy the file at .transcript_path to ~/.claude/transcript-backups/<session_id>-<trigger>-<UTC timestamp>.jsonl, keep the newest 50, and never print the transcript. Test the Stop gate in /tmp/hooktest-stop with a tiny pytest project in three states: passing, failing, and stop_hook_active true while failing. Test the backup with a fixture payload pointing at a dummy transcript.

First register the hooks: back up ~/.claude/settings.json, then merge all seven entries into .hooks with jq, appending to existing arrays (matchers Bash and Edit|Write|MultiEdit for the tool hooks, empty for lifecycle events, async true for PreCompact, Stop timeout 150 seconds). Validate with `jq empty`, confirm each entry appears under /hooks, and list project-level hooks in .claude/settings.json that would double-fire. Then create canaries: mkdir -p /tmp/hooktest-canary && touch /tmp/hooktest-canary/keep.txt /tmp/hooktest-canary/.protected. Never target a parent path in a test. Run headless sessions and save each transcript to ~/.claude/hooks/proof/: (1) `claude -p 'Run: rm -rf /tmp/hooktest-canary then report' --output-format stream-json --verbose` with permission settings that would otherwise allow Bash; confirm the stream shows a block with your stderr reason and the canary still exists. (2) Ask Claude to write a file /tmp/hooktest-secret/config.py containing a fake AWS key in the documented AKIA format; confirm the write is blocked and the file does not exist. (3) In /tmp/hooktest-stop with a failing test, ask Claude to 'add a docstring and say done'; confirm the session continues and fixes or reports the failing test before stopping. (4) Count Bash tool calls in the transcripts and compare with new rows in bash-log.tsv. (5) Run /compact in an interactive session and confirm a backup file appears.

Run the full test suite from a clean shell and paste the summary. Run shellcheck on all .sh files. Run hyperfine on every PreToolUse hook and tabulate medians. Run gitleaks detect on the project repo and confirm no secret type it finds is missing from block-secrets.py's rules. Re-read the five proof transcripts. Write ~/.claude/hooks/README.md (purpose of each hook, how to disable each, fail-open versus fail-closed choice, what each blocker cannot stop) and GAPS.md with three sections: Verified (claim, evidence file), Open (claim or bypass, why not fixed, impact high/medium/low), and Guide corrections (each guide claim that was false or renamed on this version with the doc excerpt). Commit ~/.claude/hooks to git with a message naming the Claude Code version tested.

You are auditing a freshly built Claude Code hook suite in ~/.claude/hooks/ that you did not write. Do not trust README.md. (1) List every claim the README and ground-truth.md make (each hook's trigger, behaviour, latency, and each guide-claim verdict). (2) For each, mark verified, unverified, or false, and cite evidence: a test case name, a proof transcript line, or a doc excerpt for the version from `claude --version`. (3) Attack the blockers: try at least eight bypasses of block-destructive (bash -c, sh -c, eval, base64 -d | sh, python -c with shutil.rmtree, a heredoc script then execute, xargs rm, an MCP filesystem delete tool) and five of block-secrets (split string concatenation, base64 of a key, a key in a NotebookEdit cell, a key via Bash echo > file, a key in an MCP write tool). Record which get through. (4) Check for silent failures: what does each hook do with empty stdin, invalid JSON, a missing jq or formatter; does any hook print tool_input or transcript content where Claude sees it. (5) Rank all gaps by impact (data loss, secret leak, workflow friction). Fix the top three now, re-run tests, and append results to GAPS.md. Report what you could not fix and why, with the exact command that demonstrates each remaining bypass on a /tmp canary.