hooks-mechanization

Follow the 7-step playbook: identify the rule's observable signal, pick the matching lifecycle event (e.g., PreToolUse for pre-execution checks), choose a handler type, adapt the Node.js skeleton script, register it in settings.json, test with piped JSON input, then retire the original rule after the hook proves stable.

Command hooks run shell scripts for deterministic checks like regex matching. Prompt hooks send the input to an LLM for semantic judgment returning {ok: bool}. Agent hooks spawn a subagent with Read/Grep/Glob tools for cross-file verification, and are the slowest and most expensive option.

A Stop hook that always exits with code 2 forces Claude to continue forever. The hook must check the stop_hook_active field in stdin and exit 0 when it is true, allowing Claude to stop after the first intervention.

JSON parsing fails when stdout contains non-JSON text, typically from shell profile welcome messages or console.log debug statements. Use bash --noprofile --norc, send debug output only to stderr via console.error, and remember exit code 2 ignores JSON entirely.

No. Claude Code snapshots hooks at session start, so edits to settings.json do not hot-apply. Run /clear to start a new session or restart the CLI, then verify registration with the /hooks command.

Use async only for side effects like logging, telemetry, or cache warming, since async hooks cannot block actions or inject context. Any hook that must influence Claude's behavior, such as blocking a dangerous command, must run synchronously.