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:

| The user wants to… | Event | Can it block? | |---|---|---| | Stop the agent from doing something (read a secret, edit a protected path, run a destructive command) | PreToolUse ⭐ | Yes — block the tool before it runs | | React after an action (auto-format an edited file, log a command, inject context) | PostToolUse | No — the tool already ran; observe / format / inject only | | Guarantee work isn't "done" until a check passes (don't stop until tests/lint/types are green) | Stop (or SubagentStop) | Yes — block the stop and send the agent back to work | | Gate or scan the user's prompt before the model sees it | UserPromptSubmit | Yes — block the prompt; can also inject context | | Load context every time a session starts | SessionStart | No — inject context only | | Get notified when the agent needs you / finishes | Notification (or Stop) | No — side-effect only (desktop/Slack/sound) | | Snapshot state before context compaction | PreCompact | No |

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

5. Wire it into settings.json

Edit .claude/settings.json (create it if absent). Merge into any existing hooks block — never clobber other events or other hooks on the same event. Shape:

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Edit|Write|Read|Bash",
        "hooks": [ { "type": "command", "command": "uv run .claude/hooks/pre_tool_use.py" } ] }
    ]
  }
}

6. Prove it yourself, then explain and warn

Run the hook before you hand it over. Feed it a sample event on stdin and check the exit code — do not ship a hook you have only read. A hook that always blocks, or never blocks, looks identical to a working one until it fires at the wrong moment.

# should ALLOW (exit 0)
echo '{"session_id":"t","cwd":"","hook_event_name":"Stop","stop_hook_active":false}' | uv run .claude/hooks/stop.py; echo "exit=$?"

• For a command-running hook (tests/lint/types), this is mandatory and you must check both directions:

it exits 0 while the command passes, and exits 2 once it genuinely fails. If it exits 2 in both states, the command is not resolving — re-read the warning in step 4 about sys.executable.

• For a blocking guard, feed it one payload that should be blocked and one that should pass.
• If a check comes back wrong, fix the script and re-run before reporting success.

Then:

• Tell the user what you built, in plain words: which event, what it guarantees, and the one line they'd

change to adjust it.

• Give them a way to prove it in the agent: for a blocking hook, an action that should be blocked ("ask me

to read the env file — watch it refuse"); for an observe hook, where the output lands (the log, the notification).

• Report what you verified, and say plainly if you could not verify something.
• Security note (always say this): a hook runs arbitrary code automatically, with your credentials, on every

matching event. Review hooks like you review CI config; only run hooks you trust. (Same caution as MCP servers.)

Quality checks

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

Notes

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: coleam00
• Source: coleam00/skills
• License: MIT

Install and usage instructions live in the source repository linked above.