Pre = guarantee/gate. Post = react/log. If the user's goal is "make sure X never happens" or "don't finish until Y," it's a blocking hook (PreToolUse / Stop / UserPromptSubmit). If it's "do Z when W happens," it's an observe/react hook (PostToolUse / SessionStart / Notification).

• Hooks reference: https://code.claude.com/docs/en/hooks
• Hooks guide (examples): https://code.claude.com/docs/en/hooks-guide

WebFetch

• Input: Claude Code passes a JSON object on stdin — always includes

  session_id

  ,

  cwd

  ,

  hook_event_name

  ; event-specific fields like

  tool_name

  +

  tool_input

  (tool events),

  prompt

  (UserPromptSubmit),

  source

  (SessionStart).
• Output / control:

  • exit 0

    — allow / success. For

    UserPromptSubmit

    and

    SessionStart

    , anything printed to stdout is injected into the agent's context.

  • exit 2

    — block. The action is prevented and whatever you print to stderr is fed back to the agent as the reason, so it adapts. (Only blocking-capable events honor this — see the table.)
  • any other exit code — non-blocking error; shown to the user, execution continues.
  • Advanced (optional): instead of exit codes, print a JSON object on stdout — e.g.

    {"decision":"block", "reason":"…"}

    (Stop), or

    {"hookSpecificOutput":{"hookEventName":"PreToolUse", "permissionDecision":"deny","permissionDecisionReason":"…"}}

    . Prefer the simple exit-code form unless the user needs to modify input/output or inject context with

    additionalContext

    . Confirm field names against the fetched docs.

$ARGUMENTS

• What should happen or be prevented, and when (before/after an action, at finish, at session start)?
• How precisely should it match? ("any

  .env

  file", "the

  migrations/

  folder", "

  rm -rf

  ", "my test command exits non-zero"). Get the concrete file paths / commands / patterns — the guarantee is only as good as what it matches, so don't guess. If the ask is vague, propose a concrete interpretation and confirm.

• Default to a

  uv

  single-file Python script at

  .claude/hooks/<event_snake_case>.py

  (matches the pack's tooling). Use another language only if the user asks.
• Read the JSON from stdin, do the check, and:
  • to block: print a clear reason to

    stderr

    and

    sys.exit(2)

    ;
  • to allow:

    sys.exit(0)

    (optionally print context to stdout for the injecting events).
• Fail open. Wrap the body so any unexpected error exits

  0

  (a broken hook must never brick the user's session). The only intentional non-zero exit is the deliberate

  exit 2

  block.
• Keep it lean and readable — the user will want to tweak the matched paths/commands later.
• If a hook already exists for that event, extend it rather than overwrite (add your check; keep theirs).

• Stop

  /

  SubagentStop

  only: check

  stop_hook_active

  first and

  sys.exit(0)

  when it is true. Without that guard the hook blocks the stop, the agent works, tries to stop again, is blocked again — a loop.

⚠️ Running a project command from a hook (read this before writing one)

The hook itself runs under

uv run

, in an isolated ephemeral environment. Its interpreter is NOT the project's interpreter and does NOT have the project's dependencies. So:

• NEVER rebuild the command with

  sys.executable

  or a bare

  ["python", "-m", "pytest", ...]

  list. That runs the hook's throwaway python, which has no pytest, no project packages, nothing. The command fails with

  No module named …

  every single time — so a "don't finish until tests pass" hook blocks on green as readily as on red, and reports a nonsense reason. It looks like it works. It does not.
• DO run the user's command verbatim, as a shell string, in the project directory — with uv's ephemeral venv stripped from the environment.

  shell=True

  alone is not enough:

  uv run

  puts its throwaway interpreter first on

  PATH

  and sets

  VIRTUAL_ENV

  , so even a shell command resolves

  python

  to the wrong one. Copy this helper as-is:
  python

  TEST_COMMAND = "python -m pytest -q"   # exactly what the user typed; the one line they'll edit
  
  def _project_env() -> dict:
      """os.environ minus uv's ephemeral venv, so the project's own tools resolve."""
      env = os.environ.copy()
      venv = env.pop("VIRTUAL_ENV", None)
      if venv:
          drop = {os.path.join(venv, "Scripts"), os.path.join(venv, "bin")}
          env["PATH"] = os.pathsep.join(
              p for p in env.get("PATH", "").split(os.pathsep) if p not in drop
          )
      return env
  
  result = subprocess.run(
      TEST_COMMAND, shell=True, capture_output=True, text=True,
      cwd=hook_input.get("cwd"),          # the project root Claude Code passes in
      env=_project_env(),
  )

  Put the command in a single named constant at the top of the file so the user can edit one obvious line.
• If the command must run from a subdirectory (a monorepo, or a project whose test config lives deeper — e.g.

  app/backend/

  ), ask for that, and pass it:

  cwd=Path(hook_input["cwd"]) / "app/backend"

  . Getting this wrong produces a hook that always blocks, which the user will read as "hooks are broken."

• ✅ The behavior maps to the right event, and a blocking goal uses a blocking-capable event (PreToolUse / Stop / UserPromptSubmit) — not PostToolUse.
• ✅ The matcher is scoped to what the user actually meant (not firing on everything by accident).
• ✅ The script fails open — any error exits 0; the only

  exit 2

  is the intended block, with a clear stderr reason.
• ✅ Any project command runs verbatim via

  shell=True

  in the project

  cwd

  — never rebuilt with

  sys.executable

  or a bare

  python

  (the hook's own interpreter has none of the project's dependencies).
• ✅ A

  Stop

  /

  SubagentStop

  hook honors

  stop_hook_active

  so it cannot loop.
• ✅

  settings.json

  was merged, not overwritten; existing hooks still present.
• ✅ You ran the hook and confirmed it exits 0 when it should allow and 2 when it should block — not just read it.
• ✅ The user got a plain-English explanation + a test + the security note.

• Hooks are the deterministic floor of the AI Layer — use them for the non-negotiables (secrets, protected paths, "don't finish until green"), not for things a rule or skill handles well enough.
• A blocking hook's coverage is only as good as its matcher — it guarantees the hook runs, but you decide what it catches. Be honest with the user about the edges (e.g. a

  .env

  matcher won't catch a base64'd read).
• Keep hooks fast — they run on the matched event every time. Heavy work belongs in an async hook or a skill.