Claude Code hooks, with the missing manual.

Ships as a ready-to-enable plugin, and every script also works standalone with a five-line settings.json entry. Plain Node, no dependencies, readable in one sitting.

You can tell Claude “never use npm here” in CLAUDE.md, and it will comply, usually. A hook removes the usually: it is a script the harness itself runs around every tool call, and when it says deny, the command does not execute. Instructions are advice; hooks are law.

The elegant part is what happens after a block. The hook’s reason is fed straight back into Claude’s context, so a good reason (“this repo uses pnpm, found pnpm-lock.yaml”) means the model immediately retries the right way. You are not fighting the agent; you are giving it guardrails it can read.

Register hooks in settings.json under the event name, with a matcher against the tool (exact name, regex, or *):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "node /path/to/danger-blocker.js" }
        ]
      }
    ]
  }
}

Every hook reads one JSON object on stdin and may answer with JSON on stdout. For PreToolUse, tool_input carries the exact arguments about to run, and your verdict goes back as a permissionDecision:

// stdin (what your script receives):
{
  "session_id": "abc123",
  "cwd": "/repo",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "npm install lodash" }
}

// stdout (how you block it):
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "This repo uses pnpm (found pnpm-lock.yaml).
      Re-run with pnpm so the lockfile stays consistent."
  }
}

Exit codes are the shorthand alternative: exit 0 processes your stdout, exit 2 blocks the action with stderr fed back to Claude, anything else is a non-blocking warning. Stop hooks use a top-level decision instead:

// A Stop hook that refuses to let the turn end with type errors:
{
  "decision": "block",
  "reason": "tsc --noEmit reports 3 errors after your changes.
    Fix them before finishing: src/auth.ts(42,7): error TS2339..."
}

One warning from production: a Stop hook that blocks must check the stop_hook_active flag on its input, or a persistent failure loops forever. The typecheck gate in this pack shows the guard.