К основному содержанию
скилл CX Codex

claude-code-hooks — скилл для Claude Code: что делает и установка

Скилл claude-code-hooks помогает писать, тестировать, регистрировать и отлаживать хуки Claude Code. Он пригодится, когда правило нужно превратить в блокировку вызова инструмента.

MIT 333 установок ★ 1 540 обновлён 2026-11-22

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add daymade/claude-code-skills --skill claude-code-hooks -a claude-code
Открыть на GitHub

Что делает claude-code-hooks

claude-code-hooks разбирает хуки на границах вызовов инструментов: PreToolUse, PostToolUse, SessionStart и Stop. Он помогает выбрать тип хука, принять событие в формате JSON через stdin и задать поведение через код завершения. PreToolUse может остановить вызов, PostToolUse — добавить контекст после выполнения, а Stop — не дать модели завершить ответ.

Скилл также помогает регистрировать и проверять хуки, искать причины сбоев и учитывать правила matcher. Для блокировки PreToolUse используется код выхода 2, а сообщение в stderr становится объяснением для модели. Правило в CLAUDE.md остаётся подсказкой, поэтому для необратимого действия без хука защита слабее.

В SessionStart проверка должна завершаться кодом 0: ненулевой результат не остановит сессию, но покажет ошибку при каждом запуске.

Какие задачи решает

  • заблокировать опасный вызов инструмента
  • перехватить действие перед запуском
  • добавить контекст после выполнения команды
  • найти причину срабатывания хука
  • проверить регистрацию хуков Claude Code

Примеры запросов агенту

  • Напиши PreToolUse-хук, который блокирует удаление файлов и объясняет модели безопасную альтернативу.
  • Проверь, почему мой хук не останавливает вызов Bash, и исправь matcher и код выхода.
  • Добавь PostToolUse-хук, который передаёт модели актуальное состояние git HEAD после коммита.

Как установить claude-code-hooks

1Через Skills CLI (Vercel)

npx skills add daymade/claude-code-skills --skill claude-code-hooks -a claude-code

2Вручную: положить файлы

~/.claude/skills/claude-code-hooks/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/claude-code-hooks/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о claude-code-hooks

Как установить claude-code-hooks в Claude Code?

Выполните npx skills add daymade/claude-code-skills --skill claude-code-hooks -a claude-code, затем проверьте файл ~/.claude/skills/claude-code-hooks/SKILL.md.

Что делает claude-code-hooks?

Скилл создаёт, тестирует, регистрирует и отлаживает хуки Claude Code. Он помогает превращать повторяющееся нарушение правила в механическую проверку вызова.

Какой хук блокирует вызов инструмента?

Для этого нужен PreToolUse: код выхода 2 блокирует вызов, а текст в stderr передаёт модели причину и допустимую альтернативу. PostToolUse уже не может отменить выполненный инструмент.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
sage xoai Плагин sage для Claude Code сначала уточняет задачу, затем помогает пройти этапы разработки и проверки. Хуки блокируют некоторые действия, пока не выполнены заданные условия. ★ 31звёзд репо agentdevx mirajmahmudul57 MCP-сервер agentdevx для Claude Code подключает API, хранит учётные данные в зашифрованном хранилище и применяет политики OPA. Управляет вызовами внешних сервисов. CX Codex +1 10 461установок Wax Seal degenlegion-com MCP-сервер Wax Seal проверяет криптографические личности, подписи документов и токены согласования для рискованных действий ИИ-агента. CX Codex +1 303установок agent-plugin-eval fabricioctelles Скилл agent-plugin-eval для Claude Code проверяет Agent Plugins по спецификации, выставляет оценку и сравнивает два репозитория. Задача — ревью перед выпуском. CX Codex +1 ★ 141звёзд репо loop-constraints Cobus Greyling Скилл loop-constraints загружает правила проекта до начала работы и проверяет их перед изменениями, тестами, отправкой и слиянием кода. CX Codex +1 ★ 11 819звёзд репо akf HMAKT99 MCP-сервер akf с 10 инструментами формата Agent Knowledge Format: агент проверяет, можно ли строить на файле, и ставит метку доверия после проверки. CX Codex +1 ★ 22звёзд репо

Из того же набора102

Весь набор →
git-safety-net Скилл git-safety-net для Claude Code находит и сохраняет локальные коммиты, незакоммиченные файлы и ветки перед очисткой репозитория. Защищает от потери кода при слияниях и удалении воркдеревьев. CX Codex +1 362установок photo-to-scanned-pdf Скилл photo-to-scanned-pdf превращает снимки документов со смартфона или цифровые файлы в чистые сканы PDF формата A4 с выравниванием и осветлением фона. CX Codex +1 358установок local-conversation-history Скилл local-conversation-history для Claude Code направляет запросы к нужному читателю истории диалогов. Он различает поиск сказанного и продолжение прежней работы. CX Codex +1 346установок continue-codex-work Скилл continue-codex-work для Claude Code перехватывает прерванную сессию Codex по её Session ID. Включается, когда процесс завис, сжался или требует передачи задач новому агенту. CX Codex +1 344установок docx-creator Скилл docx-creator для Claude Code создаёт DOCX из Markdown и помогает экспортировать документы Word/WPS в PDF с проверкой результата. Обрабатывает договоры и документы со сложной вёрсткой. CX Codex +1 323установок macos-watchdog Скилл macos-watchdog для Claude Code проектирует и проверяет watchdog-задачи в launchd. Он подключается к запросам о LaunchAgent, LaunchDaemon, расписании или повторных уведомлениях. CX Codex +1 240установок read-claude-code-history Скилл read-claude-code-history для Claude Code ищет и экспортирует историю локальных сессий. Он помогает найти исходные сообщения, контекст разговора и сведения о командах и вызовах инструментов. CX Codex +1 223установок read-codex-history Скилл read-codex-history для Codex, Claude Code, Cursor, GitHub Copilot и Gemini CLI, который читает, ищет и экспортирует локальную историю сессий OpenAI Codex без возобновления работы. CX Codex +1 221установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой