Hooks Create

Create Hook: Turn an Idea Into a Working Claude Code Hook

What the user wants the hook to do: $ARGUMENTS

If that is filled in, treat it as the behavior spec and start from it. Don't re-ask what they already told you; only ask to pin down the gaps (the exact paths / commands / patterns, and whether it must block). If it is blank, start by asking what the hook should guarantee or do (Workflow step 1).

What a hook is (30-second intro)

A hook is deterministic code that fires automatically on a Claude Code lifecycle event - before a tool runs, after it runs, when the agent tries to finish, when a session starts, and so on. Unlike a skill or a subagent, the agent does not choose to invoke a hook - it fires whether the model "remembers" or not. That is the whole point: a rule asks the agent to behave; a hook guarantees it, at the tooling layer the model can't talk its way around.

The user brings the idea ("the agent should never read my .env"); this skill writes the code and wires it in. They don't need to know Python.

It's all composition - a hook is just a small script the harness runs at a defined moment, configured in .claude/settings.json. You're adding one more deterministic guarantee to the AI Layer.

The one thing to get right: which event, and can it block?

The behavior the user wants maps to one lifecycle event. Pick by when it should fire and whether it must stop something:

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).

Required reading (do this first)

The hook event list and the exact stdin/stdout contract evolve - don't rely on a snapshot. Before writing, fetch the current docs and confirm the event name, its input fields, and its control protocol:

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

Use WebFetch on these and verify against what you're about to write. If the fetch fails, proceed from the canonical events in the table above and say so in your report so the user can double-check.

The execution protocol (how a hook talks to Claude Code)

• 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.

Workflow

1. Understand the idea (start from $ARGUMENTS; ask only to fill gaps)

Start from what the user already described in $ARGUMENTS (the user may not be technical). Pin down two things in plain language, asking only for what is missing:

• 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.

2. Read the docs

Fetch the hooks reference/guide (above) and confirm the target event's name, stdin fields, and control protocol.

3. Pick the event (and matcher)

Use the table to choose the single event. Choose a matcher that scopes it tightly - for tool events, the tool name(s) (e.g. "Bash", "Edit|Write", "mcp__.*"); empty/"*" means every occurrence. Don't fire on everything if the goal is specific.

4. Write the hook script

• Default to a uv single-file Python script at .claude/hooks/<event_snake_case>.py - a uv run --script shebang plus inline # /// script metadata, so it needs no install and no project venv of its own. 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 AND the project's own venv put first. Both steps are required. shell=True alone is not enough: uv run puts its throwaway interpreter first on PATH and sets VIRTUAL_ENV. But removing uv's venv does not activate the project's - a hook is not the user's shell, so .venv was never on PATH to begin with, and python falls through to whatever global interpreter the machine has. That global one has a different (often broken) set of packages, so the hook exits 2 on a perfectly green suite and blames some unrelated module. Copy this helper as-is:

  TEST_COMMAND = "python -m pytest -q"   # exactly what the user typed; the one line they'll edit
  
  def _project_env(project_root: Path) -> dict:
      """os.environ with uv's ephemeral venv removed and the PROJECT's venv first."""
      env = os.environ.copy()
      ephemeral = env.pop("VIRTUAL_ENV", None)
      parts = env.get("PATH", "").split(os.pathsep)
      if ephemeral:                                    # 1. uv's throwaway venv, out
          drop = {os.path.join(ephemeral, "Scripts"), os.path.join(ephemeral, "bin")}
          parts = [p for p in parts if p not in drop]
      for candidate in (".venv", "venv"):              # 2. the project's own venv, first
          for bindir in ("Scripts", "bin"):
              venv_bin = project_root / candidate / bindir
              if venv_bin.is_dir():
                  env["VIRTUAL_ENV"] = str(project_root / candidate)
                  parts.insert(0, str(venv_bin))
                  env["PATH"] = os.pathsep.join(parts)
                  return env
      env["PATH"] = os.pathsep.join(parts)
      return env
  
  root = Path(hook_input["cwd"])          # the project root Claude Code passes in
  result = subprocess.run(
      TEST_COMMAND, shell=True, capture_output=True, text=True,
      cwd=str(root), env=_project_env(root),
  )

  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."