Nothing asserts a declared hook actually fires — an unfired hook is indistinguishable from a passing one #15997

Problem

Nothing asserts that a declared hook actually runs. Every hook guard we have checks what a hook
does once invoked; none checks that it is invoked at all. A hook that never fires and a hook
that fires and passes are indistinguishable from the outside — both produce silence.

That is not hypothetical. The open hook bugs cluster on exactly this shape:

A live instance of the same class, found this session outside the repo: a Claude Code
PreToolUse hook declared with matcher: "Bash(git commit)". The matcher field is a tool-name
pattern — permission-rule syntax belongs in the separate if field — so as a regex it wants the
literal string Bashgit commit and never matches the tool name Bash. The hook had been dead.

Verified by observation, not by reading the config: a git commit run in the main working
tree on Dev_new_gui — which that hook blocks with exit 1 and the message
Commits from the main working tree are blocked — was not blocked. Git answered
nothing to commit instead. A guard whose whole purpose is to stop commits outside a worktree
had been silently absent.

This repo's own .claude/settings.json declares six hooks. If one of them acquired the same
defect tomorrow, nothing would report it.

Scope

A liveness check for declared hooks: for each hook entry in .claude/settings.json, assert that
a matching tool call actually reaches it. The mechanism that matters is a sentinel — invoke
the matching shape and require positive evidence the hook ran, rather than inferring it from the
absence of a failure.

Explicitly a reach check, not a behaviour check: whether each hook's own logic is correct is
what the existing per-hook issues cover. Presence of the expected signal, never absence of an
error — an unfired hook and a passing hook look identical otherwise.

Acceptance criteria

• A test enumerates every hook entry in .claude/settings.json and asserts each is reachable by at least one matching tool call
• A hook whose matcher cannot match any tool name fails the test, naming the entry and the reason
• The test fails when a known-good hook entry is mutated to an unmatchable matcher (prove the check can fail)
• Reach is proven by a positive sentinel per hook, not by the absence of an error
• matcher vs if semantics are documented once, where hooks are declared, so the next author does not repeat the confusion
• Findings for hooks that are already dead are filed separately rather than fixed inline here

Blast radius

Test-only plus a doc line; no runtime or product code path. The risk is a flaky reach check
becoming noise, which the "prove the check can fail" criterion is there to bound.

Related

• core.hooksPath override silently disables every hook in a worktree #15961, bug(hooks): post-checkout rewrites itself mid-execution with cp, so the running shell resumes at a stale byte offset #15532, branch-switch hook denies git -C $VAR switch <branch> because it cannot resolve the variable #15446, bug(guards): the gitignore-shadow hook reads one section of .gitignore, so 44 tracked-but-ignored paths are invisible to it #15512 — hooks that stopped enforcing by different mechanisms
• fix(hooks): protect-files.sh ask() exits 2, so settings edits hard-fail instead of prompting #15369 and protect-files.sh hard-denies where it means to ask — ask() exits 2 #15956 appear to be the same bug filed twice (protect-files.sh ask() exits 2); worth deduplicating