claude-code-hooks — Claude Code skill: hooks and setup
This skill writes, tests, registers, and debugs Claude Code hooks. Use it when a recurring rule must become an actual gate on tool calls.
MIT 333 installs ★ 1,540 updated 2026-11-22
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a claude-codeWhat claude-code-hooks does
claude-code-hooks helps build controls around Claude Code tool calls with PreToolUse, PostToolUse, SessionStart, and Stop. It covers JSON events sent through stdin and the exit codes that determine what happens next. PreToolUse can reject a call, PostToolUse can supply fresh context after execution, and Stop can keep the model working.
The skill also guides hook registration, testing, and troubleshooting, including matcher behavior. A PreToolUse hook blocks with exit code 2, while stderr carries the reason shown to the model. A prose rule in CLAUDE.md is advisory, so an irreversible action guarded only by that rule has a weaker control.
SessionStart checks should return exit code 0. A nonzero result cannot stop the session, but it produces a hook error notice on every startup.
What it helps with
- block a dangerous tool call
- intercept an action before execution
- inject context after a tool runs
- debug a hook that fires incorrectly
- verify Claude Code hook registration
Example prompts for the agent
- Write a
PreToolUsehook that blocks file deletion and tells the model which safer action to take. - Debug my hook that fails to stop
Bash, including itsmatcherand exit code. - Add a
PostToolUsehook that gives the model the currentgit HEADafter a commit.
How to install claude-code-hooks
1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a claude-code2Manually: put the files in place
~/.claude/skills/claude-code-hooks/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/claude-code-hooks/
1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a codex2Manually: put the files in place
.agents/skills/claude-code-hooks/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a cursor2Manually: put the files in place
.cursor/skills/claude-code-hooks/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install daymade/claude-code-skills daymade-claude-code/claude-code-hooks/SKILL.md2Manually: put the files in place
.github/skills/claude-code-hooks/SKILL.md1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a gemini-cli2Platform CLI
gemini skills install https://github.com/daymade/claude-code-skills --path daymade-claude-code/claude-code-hooksManually: put the files in place
.devin/skills/claude-code-hooks/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about claude-code-hooks
How do I install claude-code-hooks in Claude Code?
Run npx skills add daymade/claude-code-skills --skill claude-code-hooks -a claude-code, then check ~/.claude/skills/claude-code-hooks/SKILL.md.
What does claude-code-hooks do?
It helps create, test, register, and debug Claude Code hooks. The skill turns a rule that keeps being ignored into a mechanical check around an action.
Which hook can block a tool call?
Use PreToolUse: exit code 2 rejects the call, and stderr gives the model the reason plus an acceptable alternative. PostToolUse runs too late to undo the tool.
Source text
SKILL.md · MIT
---
name: claude-code-hooks
description: >-
Writes, tests, registers and debugs Claude Code hooks (PreToolUse, PostToolUse, SessionStart,
Stop) that turn a rule the model keeps breaking into a hard gate. Use when the user wants to block
or intercept a tool call, add a guard rail, fix a misfiring hook, or says 拦截 / 守卫 / 钩子 — including
"make it stop doing X".
---
# Claude Code Hooks
Claude Code fires **hooks** at tool-call boundaries. A hook is a shell command
that receives a JSON event on stdin and, for blocking hooks, decides via its
**exit code** whether the tool call proceeds. This is the only mechanism that
*structurally* stops a behavior — a prose rule in CLAUDE.md is a suggestion the
completion drive can override; a hook is a wall.
## When a hook is the right tool (and when it isn't)
Write a hook when **a rule keeps getting violated even though it's already
written down**. The tell: you added the prose rule, it read clearly, and the
behavior recurred anyway — because at the moment of action, attention is 100%
on "get the thing done" and the reminder loses. That recurrence is the signal
to move the rule from prose (advisory) to a hook (enforced). Governance rule of
thumb: *Tier-0 irreversible action + only prose, no hook → it should be a hook.*
(**Tier-0** here = an action whose damage cannot be undone from inside the session:
destroying uncommitted work, pushing secrets to a remote, deleting files, publishing
something outward. The test is reversibility, not severity.)
Do **not** reach for a hook when: the rule has never actually recurred (don't
pre-build guards for hypothetical mistakes — cost with no proven benefit), or
the "rule" is a judgment call with no mechanical signature (a hook can only
match tokens/patterns; it can't judge whether a design is good).
If the symptom is “it keeps reviewing / waiting / retrying,” do not assume the
answer is another hook. First complete the **Loop Contract** in rule 7 and read
[pitfall #36](references/hook_pitfalls.md#36-a-self-applied-review-rule-can-loop-without-any-hook).
The loop may be created entirely by an agent repeatedly applying a prose rule.
For an existing hook's usefulness, duplicate behavior or cost, follow the
[read-only effect and cost audit](references/effect-and-cost-audit.md) before
consolidating or retiring it. Keep configured handlers, observed processes,
in-process rules and measured wall time separate; missing correlation stays unknown.
## Hook types and what the exit code means
| Type | Fires | Exit 0 | Exit 2 | Other |
|---|---|---|---|---|
| **PreToolUse** | before a tool runs | normal permission flow unless JSON supplies allow/deny/ask | **block** the call even when JSON says `allow`; read valid JSON fields (v2.1.214+). JSON blocking reason or stderr → model | without schema-valid JSON, another nonzero exit is a non-blocking error and the call proceeds; with valid JSON, the supported fields decide and that status is ignored. Use exit 0 for structured control. Follow the [official exit-code contract](https://code.claude.com/docs/en/hooks#exit-code-output) |
| **PostToolUse** | after a tool ran | quiet **unless it prints a `hookSpecificOutput` JSON on stdout — that is how context injection works, and it happens at exit 0** | feedback to the model (can't un-run the tool) | — |
| **SessionStart** | session begins | proceed | **cannot block** — stderr shows the user a hook-error notice, Claude never sees it, the session starts anyway | **exit 0 anyway**: not because a non-zero would block (it can't), but because anything non-zero puts a `<hook> hook error` in the user's transcript on every single session start. Takes a `matcher` on *how the session started* — `startup`, `resume`, `clear`, `compact`, `fork` |
| **Stop** (+ `SubagentStop`) | the model is about to finish responding | let it stop | **block the stop** — forces the model to keep going (stderr → fed back as the reason) | loop safety: the hook checks `stop_hook_active` (necessary, **not** sufficient — rule 7). The harness's consecutive-block ceiling (default 8) is **not** a general backstop — its counter resets on any continuation that executed tools, so it never arrives for a hook whose remediation involves tool calls, which is most of them (#27). Carry your own bound. All Stop hooks for an event run **in parallel** — one block round can carry several hooks' feedback |
- **PreToolUse** is the workhorse for stopping a *tool call* — the types in this
table are the ones this file teaches, not the complete set of blockable events, and
the **official** hooks reference (docs.claude.com / code.claude.com, not the
`references/` files in this bundle — those cover only the types above) now
lists many more blockable events, including `UserPromptSubmit`, `PreCompact`,
`TeammateIdle`, and task and config events. If what you need to gate is not a tool
call, look there before forcing it onto PreToolUse.
`matcher` selects the tool (`Bash`, `Agent`, `WebFetch`, …) — **and how it is
matched depends on the characters you use**: a matcher containing only letters,
digits, `_`, `-`, spaces, `,` and `|` is compared as an **exact string** (or a
`|`/`,`-separated list of exact strings); anything else is treated as an
**unanchored JavaScript regex**. Both directions bite silently — `Edit.*` also
matches `NotebookEdit` (anchor it `^Edit$`), while `mcp__memory` matches **nothing**
because it is all exact-match characters and no tool is named exactly that (you
want `mcp__memory__.*`). Matching is case-sensitive. Exit 2 blocks and
the hook's **stderr** becomes the message the model sees — so put the *why* and
the *correct alternative* there, not just "blocked".
- **PostToolUse** can't undo, but it can **inject authoritative context** so a
later hallucination can't stand (e.g. re-read the real git HEAD after a commit
and surface it — the model can't "believe it committed" against injected truth).
- **SessionStart** is for **bounded deployment and liveness probes of the guard rails themselves** —
silent when healthy, warn on breakage, always exit 0. Note *why*: it is not that
a non-zero exit would block the session (it cannot), but that it would print a
hook-error notice at every session start until someone fixes it — a check that
cries wolf on startup is a check people learn to scroll past. Run the full
regression battery after edits in the build/commit check, not at session start.
Invoke only owner-declared bounded offline liveness modes at startup; missing
modes leave logic unknown/incomplete, without falling back to `--selftest`
(build order step 4; pitfall #50).
- **`set -euo pipefail` vs `set -uo pipefail` — pick by contract, and know there
are two ways to keep an always-exit-0 contract.** A hook that may block
(PreToolUse) wants `-e`: an unexpected failure aborting the script is
survivable, because the caller treats a non-0/2 exit as "proceed". A hook whose
contract is **ALWAYS exit 0** (PostToolUse injectors, SessionStart checks) has
two honest shapes: (a) **drop `-e`** and `||`-guard every risky command —
with `-e` on, one `grep` that legitimately finds nothing kills the hook
mid-way and the CLI surfaces a bare `Failed with non-blocking status code`
(pitfall #8, Pattern E's shape); or (b) **keep `-e` and add `trap 'exit 0' ERR`**
so any failure still converts to exit 0 while `-e` keeps guarding the plumbing
(`git-commit-headcheck`'s production shape, Pattern D). Either is correct;
what you cannot do is `-e` alone with no trap and no `||`-guards. Rule of
thumb: **`-e` for hooks that decide; for hooks that report, drop `-e` or trap
it** (pitfall #8).
- **Stop is the odd one out, and the one most often reached for by mistake**:
it's the *only* hook type that can react to what the model **itself just
generated** (its own reply text). Every other hook type — including
`UserPromptSubmit`, which sounds like a plausible place to police "what gets
said" — only ever sees the **user's** input; it structurally cannot see the
model's own *current-turn* output (that claim holds — this is still the
right reason to route such a rule to Stop). That guarantee, however, does
not extend to proving the `.prompt` field always originated from a
keystroke: a background task-notification's own report text can populate
it too, and so can a teammate's or another session's message — no field in
the stdin JSON marks the difference, only the wrapper tag the text opens
with — #30. A rule like "the model must not invent a shorthand name
for something it hasn't verified" belongs on Stop; put it on
`UserPromptSubmit` instead and it will (a) never once catch what it was
built for, since that text never flows through that event, and (b)
false-block the user's own unrelated typing whenever it happens to contain
the trigger pattern. This is a category mistake, not a tuning problem — no
amount of regex refinement on the wrong event fixes it. Full contract
(`last_assistant_message` vs `transcript_path`, the anti-loop check) in
Pattern E in [references/hook_patterns.md](references/hook_patterns.md).
- **Stop has two block channels with identical loop protections — pick by
intent, and make the first (only) block carry everything.** `decision:
"block"` + `reason`, or plain exit 2 + stderr, shows as a hook *error* — for
hard gates ("this must not stand"). `hookSpecificOutput.additionalContext`
shows as neutral "Stop hook feedback" with no error notification — for
coaching and reminders the model should weigh, not gates. Both count toward
the same consecutive-block ceiling from the table above, so the choice is
tone, not safety. What that means for message design: a blocked retry
round (`stop_hook_active: true`) is let through **with whatever violations
remain** — so a Stop guard gets exactly **one** informed bite. (The ceiling
reinforces this only when your remediation is "rewrite the reply"; if it
involves tool calls the counter resets and the ceiling never lands — #27.
Either way the one-bite conclusion holds, because it rests on the latch, not
on the ceiling.) Report *all* findings in that
one block (a guard that prints only the first loses the rest permanently —
pitfall #17), and write the message as an escape manual naming the exact
acceptable fix, not a verdict — the model converges in one round or it burns
the cap guessing. v2.1.145+ inputs `background_tasks` / `session_crons` let a
blocking hook tell "the session is done" from "the session is merely paused
waiting for background work" — blocking a pause forces pointless
continuations and wastes the same cap.
Full runnable skeletons: [references/hook_patterns.md](references/hook_patterns.md).
## The skeleton (PreToolUse Bash guard)
```bash
#!/usr/bin/env bash
set -euo pipefail
IFS= read -rd '' INPUT || true # builtin; NOT $(cat) — see below
# 0-fork fast path: a builtin `case` on the raw JSON, BEFORE paying for python3.
# Your guard runs on EVERY matching tool call, so the irrelevant path is the one
# that has to be cheap. Keep this filter BROADER than what you actually block and
# never flag-level — it answers "is this even about X", nothing finer (#22).
case "$INPUT" in *TRIGGER*) ;; *) exit 0 ;; esac
TOOL=$(printf '%s' "$INPUT" | python3 -c "import sys,json;print(json.load(sys.stdin).get('tool_name',''))" 2>/dev/null||echo "")
[ "$TOOL" != "Bash" ] && exit 0 # only guard the tool you mean to
CMD=$(printf '%s' "$INPUT" | python3 -c "import sys,json;print(json.load(sys.stdin).get('tool_input',{}).get('command',''))" 2>/dev/null||echo "")
[ -z "$CMD" ] && exit 0
printf '%s' "$CMD" | grep -qw 'TRIGGER' || exit 0 # precise relevance check
# ... precise detection here ...
if <command actually does the banned thing>; then
echo "BLOCKED: ... WHY ... USE INSTEAD: ..." >&2 # stderr = the guidance shown
exit 2
fi
exit 0
```
**Why the first two lines are not stylistic.** `INPUT=$(cat)` plus each
`printf … | python3 -c …` costs forks **on every call this hook matches, including
the ones it has nothing to say about**. A fleet of ~13 Bash-matcher hooks × parallel
sessions × sub-second tool cadence turned that into a sustained 40–200 forks/sec of
pure guard overhead and put Gatekeeper at the top of an all-day CPU ranking with no
runaway process anywhere — the fleet was fine; the *irrelevant path's* per-call cost
was the bug (#22, with the per-guard conversion recipe and its measured floor).
Check these caveats before copying the `case` line — the first one is the
difference between a fast path and a bypass:
- **A coarse filter must be a SUPERSET of what you block, and a raw substring test
is not one.** `TRIG''GER -x` runs `TRIGGER` — bash splices the quotes away before
execution — but the raw event text contains no `TRIGGER` substring, so a bare
`case "$INPUT" in *TRIGGER*)` exits 0 and the guard never sees it. **Measured**:
drop this exact line into the shipped Pattern A and `TRIG''GER -x` flips from
exit 2 to exit 0, a full bypass — while `scripts/test_hook.sh` still reports
21 pass / 0 fail, because no row carries a spliced trigger. Pattern A already
carries the fix and the reason ("de-splice — strip quotes and backslashes — and
check again; a false negative is a full bypass"); a coarse filter placed *before*
that de-splice makes it unreachable. Two safe shapes, in order of preference:
**filter on something the splice cannot touch** — a JSON key or a tool name
(`case "$INPUT" in *'"tool_name":"Bash"'*)`), since quote-splicing lives in the
*command* text and cannot rewrite the event's own structure; or **de-splice
inside the filter** before testing (strip `"`, `'` and `\` from a copy of the
input, then match). Prefer the first: it needs no escaping gymnastics, and a
filter whose own quoting you have to get right is a filter you can get wrong
silently. The skeleton above is safe
as written only because its own detection is likewise a plain word match; the
moment the guard below the filter is smarter than the filter, the filter decides.
- **This skeleton is fail-open on irrelevance** (`grep -qw … || exit 0`), so a
coarse filter in front of it changes cost, not semantics. **A fail-closed guard is
different**: a bare substring filter silently converts its contract from
block-unknown to allow-unknown (measured — `'not json'` sailed straight through the
first cut of that fix), and a `*tool_name*` marker alone re-opens the same hole from
the other side. Read #22's gate requirements *before* fitting a fast path to a guard
that is supposed to block on malformed input.
- **There is a cheaper layer above the script.** A hook handler can carry an
`if` field in its registration — permission-rule syntax such as `"Bash(git *)"` —
and the hook command **does not run at all** when it doesn't match: zero forks,
because zero processes. It is best-effort by design (the docs say it fails *open*,
running your hook anyway, when the Bash command can't be parsed), so treat it as a
cost optimization and **never as the gate** — the in-script check still decides.
Check its limits: it holds exactly one rule (no `&&`/`||`), it is only evaluated
on tool events, and a hook that sets `if` on a non-tool event **never runs at all**.
## Rules that separate a working guard from a session-poisoning one
Not style preferences — each is a specific failure we shipped and traced back.
### 1. Match at the **token level with shlex**, never awk-split the raw string
A guard that **false-blocks a healthy command is worse than one that misses** —
a guard people must bypass gets bypassed reflexively, and then it protects
nothing (the core discipline: *误杀健康输入比漏报更糟*). The recurring cause of
false-blocks is matching on the raw command string.
- **Wrong**: `awk '{gsub(/&&|\|\||;|\|/,"\n")}'` to split into segments — awk
doesn't understand shell quoting, so `grep -E "a|TRIGGER|b"` gets split at the
`|` *inside the quoted regex*, `TRIGGER` becomes a phantom command, and the
guard blocks a plain grep. (Shipped 2026-07-21; the guard's very first real use
was a false-block on my own grep.)
- **Right**: tokenize the whole command with the **`shlex.shlex` class**, not the
`shlex.split()` function — `split()` only treats `| ; & < >` as separators when
they are space-separated, so `ls|TRIGGER x` tokenizes to `['ls|TRIGGER', 'x']` and
your command-position check never sees `TRIGGER` at all (measured; the class with
`punctuation_chars=True` yields `['ls', '|', 'TRIGGER', 'x']`). Copy a shipped
walker verbatim rather than reaching for the one-liner — but **copy the one that
passes `scripts/test_hook.sh`**, which is **Pattern A's**. The
[walker section](references/hook_patterns.md#the-shlex-command-position-walker) is
a *compact* form and says so: it omits the per-wrapper valued-flag tables, so it
misses a target riding a **valued-flag wrapper** — measured, it returns "not in
command position" for `timeout 5 TRIGGER`, `sudo -u root TRIGGER` and
`nice -n 10 TRIGGER`, while Pattern A's version catches all three. (Bare
`sudo TRIGGER` is fine in both — it is the wrapper's *own* flag taking an argument
that the compact table doesn't know to skip.) Only one of those shapes is in the
shipped harness, so the run you actually see is **20 pass / 1 fail on
`wrapper-timeout`** against 21/0 for Pattern A's; the other two fail silently
because no row covers them. A quoted
`"a|TRIGGER|b"` stays **one token**, so a regex argument is never mistaken for
a command. Then check whether your target is in a **command position**
(token[0], or right after a `;`/`&&`/`||`/`|` separator, skipping `VAR=val`
env-assignment prefixes). Command-position walker in
[references/hook_patterns.md](references/hook_patterns.md).
- Corollary: `echo "…TRIGGER…"`, `grep TRIGGER`, `# TRIGGER`, `man TRIGGER` must
all pass. Your test set MUST include these mention-not-execute cases.
- **Corollary — exempt `git` write segments before they reach the walker.** A
commit message is arbitrary data, and the whole message text reaches your
command-position walk as pseudo-command-text — `git commit -F - <<EOF` with a
body quoting `foo|TRIGGER` lands `TRIGGER` in command position, and the guard
blocks its own fix commit (pitfall #7 is exactly this, shipped). Any Bash guard
that inspects command strings must skip segments whose head is `git` +
`commit`/`rebase`/`tag`/`am`/`cherry-pick` — and do it at the whole-command
level, before any line splitting (Pattern A shows the order; the production
version is `lib-git-commit-detect`'s adjacency check).
- **Corollary — the walker is two-stage for a reason.** `whitespace_split=True`
treats newlines as ordinary whitespace, so a multiline block
(`cd /x\ngit add\nTRIGGER -y`) collapses into one segment headed by `cd` and
the trigger is never in command position — replayed trigger rate 0 on real
transcripts (pitfall #11). Split into lines **shell-aware** first (quote state
and backslash continuations honored, so quoted multiline strings don't
fragment), then shlex-walk each line — both Pattern A and the walker section
ship that splitter (`split_shell_lines`, production-proven in qlmanage-guard).
What even it cannot parse is a heredoc body (not quote syntax); when to accept
that residual is #11's call.
- **But shlex isn't a silver bullet, and *what* you detect changes whether
fail-open is safe.** `shlex.split()` itself throws `ValueError` on an unbalanced
quote — a multi-line `git commit -m "…` message with a `#` or an unclosed quote
is the classic trigger. The `except ValueError: cmd.split()` fallback then
*allows*, which is right when you're detecting a **banned modifier** (does this
carry `--no-verify`? — missing it errs safe, Rule 1's direction), but
**dangerous when you're detecting whether the command IS your target at all**
(is this a `git commit`? — a ValueError there means the guard never recognises
the commit and silently doesn't fire; a real cross-domain commit shipped with no
confirmation dialog this way). For the *is-this-the-command* decision, prefer a
narrow **regex** (`git` and `commit` as separate words, any flag tokens between)
that's immune to multi-line-quote breakage; reserve the shlex walker for the
*command-position / modifier* checks where fail-open is the safe direction.
(The boundary: regex when the predicate is "is this a specific common command
at all" — `git commit`, `git push` — whose own message/arguments are what breaks
tokenizing; walker when the predicate is "is a *banned* command or modifier in
command position" — there the banned thing is rare and a ValueError fail-open
errs safe, Rule 1's direction.)
### 2. Test with **bash -n + a real JSON event, end-to-end, BEFORE registering**
**A corrupted or wrong-logic PreToolUse hook poisons the *entire* session** —
every later Bash call gets truncated / duplicated / falsely-failed / looks
hallucinated-executed, and you'll blame "the environment" when it's the hook you
just installed. (2026-07-05: a `[^;&|]` regex broke in one edit, `;&` became a
bash case-fallthrough token, poisoned half a session until `bash -n` found it.)
"My tests passed at deploy" isn't enough — the file can corrupt in a *later* edit.
Gate before registering ANY hook:
```bash
bash -n hook.sh # syntax
printf '%s' '{"tool_name":"Bash","tool_input":{"command":"<trigger case>"}}' | ./hook.sh; echo "exit=$?" # want 2
printf '%s' '{"tool_name":"Bash","tool_input":{"command":"<healthy lookalike>"}}'| ./hook.sh; echo "exit=$?" # want 0
```
Run the end-to-end case in the **verbatim form the registration will use** —
if settings.json will say `$HOME/.claude/hooks/x.sh`, execute exactly that string.
Any interpreter-explicit form (`bash hook.sh`, `python3 hook.py`, and a hook's own
`--selftest` that re-invokes itself through `bash`) bypasses the exec bit, so it
structurally cannot catch a dead-on-arrival registration. Symptom index: a
repeating non-blocking `PreToolUse hook error: … Permission denied` after install
means a bare-path-registered hook lost its exec bit — **the gate has been dead
since install**; a green selftest is not evidence against this, because the
selftest never exercised the registered form.
Bundle the harness: [scripts/test_hook.sh](scripts/test_hook.sh) runs a whole
table of trigger/allow cases. **Self-block gotcha:** once the hook is live in the
session you cannot test it by putting the trigger string in your *own* Bash
command — the live hook blocks your test command. Put the cases in a **script
file** and run `bash test_hook.sh`; the outer command doesn't contain the
trigger, so it isn't self-blocked.
**Once a hook has caused one real incident (a false-block or a silent miss),
solo re-reading the code is not enough** — a same-day rewrite of a Stop-hook
guard was itself re-broken twice by the author while fixing the first bug (a
quote inside a Python comment, invisible on re-read, only surfaced by running
the actual failing JSON case). The escalation is a multi-lens agent-team
review where every finding must be reproduced by *executing* a real payload
against the live script, not by reading the code and agreeing — this is the
general Counter Review methodology
(skill-creator's `skill-development-methodology` reference, Phase 6), applied to
a hook instead of a skill. In one such pass, 3 lenses (matching
logic / shell-embedding safety / event-contract robustness) surfaced 13
confirmed, independently-reproduced bugs and 1 finding whose own cited
evidence turned out to be a hallucinated doc quote — caught only because the
verifier was required to curl the raw source and grep for the exact string
rather than trust the citation.
### 3. Installer-owned source, installation and recovery
Keep the entrypoint and its rule modules in version-controlled source. Use the
owning installer's current entry map for installation and recovery; a rule module
does not need its own link or registration. When that installer uses symlinks,
the layout is:
```
~/scripts/claude-hooks/<name>.sh # SSOT (this setup: a private git repo)
~/.claude/hooks/<name>.sh # symlink → SSOT
```
After a reinstall, restore only the entries the current installer declares active;
do not reconstruct registrations from old filenames or reinstall retired aliases.
Preserve independent rule state and authorization writers when migrating entries.
Verify the consumed entrypoint, modules and effective settings, then exercise a
real matching event in a fresh native session. A dangling link can silently disarm
a guard; use bounded deployment/liveness checks (rule 4; Pattern C in
[references/hook_patterns.md](references/hook_patterns.md)).
### 4. Registration is per-profile — converge ALL profiles, release via a HUMAN gate
- **There are two registration surfaces, and the health check probably only
watches one.** Besides the profile settings below, a repo's own
`.claude/settings.json` (and `settings.local.json`) registers hooks for
sessions in that repo. Those live outside `~/.claude/hooks/`, so a guard-rail
check that walks that directory covers none of them — syntax, path,
`--selftest`, nothing. Two silent failures shipped in one such file and
survived two months under a SessionStart health check built to prevent
exactly that (#38, #39). Register project hooks by **absolute** path — a
relative one resolves against the session cwd and breaks the first time
someone starts `claude` from a subdirectory — and extend the health check to
walk up from the event's cwd for project settings.
- A hook in `~/.claude/hooks/` protects **nothing** if the *active profile's*
`settings.json` doesn't call it. Multi-profile users ran with zero guards until
every profile was converged. Use the owning installer to update the **main** profile's settings
(`~/.claude/settings.json` in this setup; the Registration section of
[references/hook_patterns.md](references/hook_patterns.md) has the exact jsonc
shape). Update an existing engine's matcher only when its coverage changes;
preserve each rule's narrower internal selector. In this
setup the converger is registered as a SessionStart hook **without arguments**
(`sync-profile-settings.py`, owned by the `claude-switch-models-setup` skill),
so the next profile to start a session carries the registration into every
profile. `--all` is the explicit convergence mode; run it when immediate
profile synchronization is needed, without treating that write as activation proof.
A SessionStart health check verifies each profile's effective registrations
through their owner; use text searches only to locate candidates. For new or changed registrations, verify a real matching event
and debug evidence in a fresh native session. Claim current-session hot reload
only after observing that session invoke the changed registration; a successful
settings write or startup health line alone is insufficient. The current
[ConfigChange contract](https://code.claude.com/docs/en/hooks#configchange)
allows settings changes to be applied to a running session; it does not prove
this particular registration has fired.
- **Cover every active agent host on the machine, not just one.** A guard enforced
only in Claude Code (or Claude Code + Codex) still leaves unguarded hosts such as
Antigravity (`~/.gemini/config/hooks.json`, which reads camelCase `toolCall` JSON
on stdin and expects `{"decision":"allow"|"deny"}` on stdout) wide open to the
same failure. Keep one SSOT classifier behind thin per-host adapters instead of
duplicating detection logic, note that already-running sessions may not hot-reload
newly added hook files, and verify interception in a fresh process of each target
host (for Antigravity, a fresh `agy -p` run).
- **If the guard needs a release valve, make it a *human* gate, not an env var.**
A static `GUARD_OK=1` escape hatch is no gate — the model can set the env var
itself. Use a native macOS dialog (`osascript` — the model can't click);
refuse/cancel/timeout = hard NO; log every prompt/bypass to an audit file.
Pattern in [references/hook_patterns.md](references/hook_patterns.md).
- ⚠️ **`/dev/tty` is not a second channel — the docs say hooks cannot open it.**
This file used to prescribe a typed `YES` on `/dev/tty` alongside the dialog.
The official reference is explicit: hooks "run in their own session **without a
controlling terminal**", and "the hook process and any child processes **can't
open `/dev/tty`**" (`terminalSequence` is the documented replacement for writing
to it). So a "two-channel" gate built that way is one channel plus dead code,
and on a box with no GUI session the gate can never be approved by anyone.
Consistent with local observation, though read the boundary carefully: in one
setup's shared audit log — 1,801 entries, several guards writing to it, three of
which implement a tty channel — **360 lines carry a channel tag (236 dialog
confirmations, 124 declines or timeouts) and not one line of any kind names the
tty channel.** That means the tty branch was never *entered*, which on macOS is
what you would predict anyway, because the dialog answers first and short-
circuits it. So the log shows nothing here ever depended on tty; it is the
documentation, not this measurement, that establishes tty cannot work at all.
Keep the dialog; if you need a non-macOS gate,
you need a channel this file does not yet have a verified answer for.
- ⚠️ **A human gate that outlives the hook timeout fails OPEN.** Hook `command`
timeout defaults to 600s (30s on `UserPromptSubmit`), and a timed-out hook
**does not block the tool call** — so an unanswered dialog...
© daymade · MIT · daymade/claude-code-skills