Hooks

A matcher narrows which occurrences of an event a hook’s commands run for. Tool events (PreToolUse, PostToolUse, …​) match on tool name — a plain name, a |-separated alternation, or (as soon as the value contains any other character) an unanchored JavaScript regular expression, e.g. Bash, Edit|Write, mcpgithub.. "", an empty matcher, or omitting it runs the hook on every occurrence of the event. A separate if field, available only on the tool events, filters further using permission-rule syntax such as Bash(git ), so a hook can target only git subcommands within a broader Bash matcher; because that filtering is best-effort (it can’t always tell which subcommands a shell string runs), it narrows *when the hook runs, not a hard security boundary — use permission rules for that.

Every hook receives one JSON object on stdin. Fields common to every event include session_id, transcript_path, cwd, permission_mode and hook_event_name; each event adds its own fields on top. A PreToolUse hook for a Bash call, for example, receives:

A Stop hook additionally receives stop_hook_active (true when this turn is already continuing because of an earlier Stop-hook block) and last_assistant_message; a SessionStart hook receives source (the same value the matcher filters on).

A hook script controls the outcome in one of two ways, and the reference recommends choosing one approach per hook: exit codes alone, or exit 0 plus a JSON object on stdout. If a hook mixes them, exit 2 still blocks and Claude Code still reads the JSON fields:

For finer control than block/allow, exit 0 and print a JSON object to stdout instead. The exact field names differ by event, verified against the reference's per-event sections:

A malformed or unparseable JSON payload on stdout is reported as a non-blocking error rather than silently ignored, so a hook that builds its output with jq (rather than raw string concatenation) avoids a stray unescaped quote breaking the whole decision.

Reformat whatever file Claude just edited or wrote, using the file path from tool_input.file_path:

No separate script is needed here — the command itself reads tool_input.file_path from stdin via jq and pipes it to Prettier. See Claude Code — Automate actions with hooks (Auto-format code after edits).

A PreToolUse hook on Bash inspects tool_input.command and exits 2 with a reason on stderr for a destructive pattern, which Claude Code both blocks and hands back to Claude as feedback:

This is a best-effort net, not the enforcement boundary: a pattern match on the command string misses the same command written another way. A rule that must hold regardless of phrasing belongs in a deny rule in permission settings, which Claude Code evaluates whatever a PreToolUse hook returns and which blocks in every permission mode, bypassPermissions included. See Claude Code — Hooks reference (PreToolUse).

A Stop hook re-runs the project’s test command every time Claude is about to finish, and blocks the stop until it passes — reading stop_hook_active first so a test that can never pass doesn’t loop forever:

Claude Code overrides a Stop hook’s block after eight consecutive continuations on the same turn even without the stop_hook_active check, so a hook that ignores the field still can’t loop forever — checking it just means the loop ends on the first re-entry instead of the eighth (the cap itself can be raised with the CLAUDE_CODE_STOP_HOOK_BLOCK_CAP environment variable). This is the same mechanism Testing & Debugging with AI introduces as the deterministic version of "tests as the assistant’s success criterion" for an unattended run; the script here also reads stop_hook_active explicitly rather than relying only on the eight-continuation cap. See Claude Code — Hooks reference (Stop).

A SessionStart hook with the compact matcher re-states project conventions right after a context compaction would otherwise have let them fade, by writing plain text to stdout:

With no matcher, the same hook fires on every SessionStart reason (startup, resume, clear, compact, fork), which is the right choice for context that should always be present rather than only after compaction. For static context that needs no script, both the hooks guide and the hooks reference recommend CLAUDE.md instead: it loads without running anything and is the standard place for unchanging project conventions. See Claude Code — Automate actions with hooks (Re-inject context after compaction) and Claude Code — Hooks reference (SessionStart).

Check Security (the detect-secrets-backed skill this account already ships) maintains a .secrets.baseline of already-triaged findings. A PreToolUse hook can then check every git commit Claude attempts against that baseline, instead of relying on Claude to invoke the skill first. It uses detect-secrets-hook, the detect-secrets entry point that exits non-zero only for secrets not in the baseline, on the files currently staged:

The if field narrows the hook to Bash calls with a git commit subcommand (best effort, as the matcher section above explains). The settings in these recipes set "args": [] so the script path runs in exec form, with no shell to mis-split a ${CLAUDE_PROJECT_DIR} that contains spaces — the form the reference recommends for any hook that uses a path placeholder:

The hook and the skill share the same tool and the same baseline. The skill is the interactive, triaged workflow: it rescans the repository, updates .secrets.baseline and reports only new findings. The hook is the net that catches a commit attempted without running the skill first. The two are complementary, and neither replaces the other. The hook only sees what is already staged when the tool call starts, so a single command such as git add . && git commit slips past it; a real pre-commit git hook closes that gap for every commit, not just Claude’s. See Claude Code — Hooks reference (the if field) and detect-secrets for detect-secrets-hook.