check-hook

name	check-hook
description	Audits Claude Code hooks configuration for event coverage, script safety, async and blocking contradictions, Stop hook loop risks, rule overlap, and idempotency. Use when the user wants to "audit hooks", "review hooks", or "are my hooks safe".
allowed-tools	Read, Write, Edit, Bash, Grep, Glob
argument-hint	[settings.json path]
user-invocable	true
references	["../../_shared/references/brief-best-practices.md","../../_shared/references/hook-best-practices.md","references/check-async-blocking-coherence.md","references/check-attack-surface.md","references/check-brief-presence-and-content.md","references/check-claude-md-overlap.md","references/check-command-path-expansion.md","references/check-destructive-operations.md","references/check-event-matcher-fit.md","references/check-exit-code-contract.md","references/check-idempotency.md","references/check-injection-safety.md","references/check-jq-handling.md","references/check-json-output-contract.md","references/check-latency.md","references/check-primitive-routing-coverage.md","references/check-shell-hygiene.md","references/check-static-analysis.md","references/check-stdin-consumption.md","references/check-stop-loop-guard.md","references/platform-limitations.md"]
license	MIT

Check Hook

Audit a project's Claude Code hooks configuration against the rubric in hook-best-practices.md. Read-only until the opt-in Repair Loop.

This skill follows the check-skill pattern. It is a pure-judgment skill — no Tier-1 detection scripts of its own; the 18 rules live as references/check-*.md files read inline by the primary agent during Tier-2. Tier-3 (cross-entity collision) does not apply (single configuration scope per audit).

When to use

Also fires when the user phrases the request as:

• "check hooks"
• "check my hooks"
• "what quality gates are missing"

Workflow

1. Scope → 2. Tier-2 Judgment → 3. Platform Scope → 4. Report → 5. Opt-In Repair Loop.

1. Scope

If $ARGUMENTS is non-empty, read the settings file at that path. Otherwise, read from both default locations (use whichever exist):

• .claude/settings.json
• .claude/settings.local.json

If neither exists, or neither has a hooks: key, the first finding is:

No hooks configured (warn) — PreToolUse hooks provide deterministic enforcement CLAUDE.md instructions cannot guarantee.

The check-primitive-routing-coverage rule (Tier-2 below) will also fire if CLAUDE.md carries advisory rules that should be hooks.

2. Tier-2 Judgment

Evaluate each configured hook against the 18 judgment rules in references/check-*.md. Read each rule body once, then evaluate every hook against it as a unified rubric pass.

The 18 dimensions:

File	Dimension	Severity
check-event-matcher-fit.md	Event-matcher fit (right event, canonical casing, matcher syntax)	fail
check-exit-code-contract.md	Exit code contract (exit 2 for blocks; explicit Python handlers)	fail
check-stdin-consumption.md	Stdin consumption (INPUT=$(cat); executable bit)	warn
check-json-output-contract.md	JSON output contract (exit-0 only; hookEventName; <10 KB)	warn
check-async-blocking-coherence.md	Async-blocking coherence (no async: true + exit 2)	fail
check-command-path-expansion.md	Command path expansion ($CLAUDE_PROJECT_DIR, never $HOME/~)	warn
check-stop-loop-guard.md	Stop-loop guard (re-entry guard for blocking Stop / SubagentStop)	fail
check-destructive-operations.md	Destructive operations (no rm -rf, git reset --hard, git push --force)	fail
check-injection-safety.md	Injection safety (no eval on payload; quoted expansions)	fail/warn
check-jq-handling.md	jq handling (availability, field paths, cross-platform)	fail/warn
check-shell-hygiene.md	Shell hygiene (set -Eeuo pipefail, output routing, [[)	warn
check-attack-surface.md	Attack surface (CVE-2025-59536-aware placement)	warn
check-latency.md	Latency (under 1s synchronous; no recursive claude invocation)	fail/warn
check-idempotency.md	Idempotency (running twice produces same outcome)	warn
check-static-analysis.md	Static analysis (ShellCheck and shfmt integration)	warn
check-claude-md-overlap.md	CLAUDE.md overlap (surface for user; never auto-resolve)	warn
check-brief-presence-and-content.md	Brief presence + content (5 H2 sections; specific So-what)	warn
check-primitive-routing-coverage.md	CLAUDE.md → hook conversion candidates	warn

Evaluator policy: see check-skill-pattern.md §Evaluator policy. Read all 18 rule files first, then evaluate each hook in turn against the unified rubric.

Skill-specific severity floor exceptions. The default WARN floor is overridden for the 7 rules documented as fail: event-matcher-fit, exit-code-contract, async-blocking-coherence, stop-loop-guard, destructive-operations, injection-safety, jq-handling (Copilot field-path mismatch), and latency (recursive claude invocation).

For each finding, capture: dimension name, offending hook / command / file, specific issue, severity. The finding's recommended_changes copies through from the rule body's How to apply section + example.

3. Platform Scope

These checks target Claude Code (settings.json / settings.local.json). If the project's hooks may run on additional platforms beyond Claude Code, read platform-limitations.md and append platform-specific findings as a separate report section.

4. Report

Present findings as a summary count plus a table, severity-sorted (fail → warn → inapplicable):

N issues across M hooks (X fail, Y warn)

event          | hook command          | dimension                 | finding
---------------+-----------------------+---------------------------+---------------------------
PostToolUse    | .claude/hooks/gate.sh | event-matcher-fit         | PostToolUse cannot block; use PreToolUse
Stop           | .claude/hooks/stop.sh | stop-loop-guard           | No re-entry guard — infinite loop risk
PostToolUse    | lint-after-write.sh   | async-blocking-coherence  | async:true + exit 2 — never blocks

If Platform Scope added findings, append:

**Cross-platform limitations:** [list per platform]

If no issues: "Hooks look well-configured."

5. Opt-In Repair Loop

Ask exactly once:

"Apply fixes? Enter y (all), n (skip), or comma-separated numbers."

For each selected finding, route per the recipe in recommended_changes (the rule body's How to apply section + code example). Most fixes fall into three buckets:

• Direct edit — add INPUT=$(cat), fix matcher casing, swap $HOME for $CLAUDE_PROJECT_DIR, add set -Eeuo pipefail. Show diff; write on confirmation.
• Routed to another skill — substantive rewrites (event must change; new hook needed for primitive-routing-coverage finding) → recommend /build:build-hook. Pair-level integrity issues → recommend /build:check-skill-pair hook.
• Requires user judgment — claude-md-overlap (keep both vs. drop one), attack-surface placement decisions, intentional advisory rules from primitive-routing-coverage.

Show the diff before writing. Terminate when the user selects no further findings, enters n, or confirms done.

Anti-Pattern Guards

1. Treating rule overlap as always wrong. CLAUDE.md + hook duplication can be intentional belt-and-suspenders; flag for user decision, do not auto-remove.
2. Skipping check-primitive-routing-coverage when no hooks exist. Absence of hooks is itself a coverage gap worth surfacing — the rule fires regardless of the configured-hook count.
3. Reading settings outside the project. Only .claude/settings.json and .claude/settings.local.json under the current project root, unless the user passes an explicit path.
4. Bulk-applying fixes. Per-finding confirmation required. Some findings (CLAUDE.md overlap, blocking-before-warn graduation) are intentional mid-deployment states.
5. Re-evaluating Tier-2 rules across multiple passes. Each judgment dimension is one finding maximum per hook; resist the urge to re-score against the same rule for "another angle".
6. Suppressing the inapplicable case. When a rule does not apply (e.g., stop-loop-guard against a PreToolUse hook), return inapplicable silently — do not pad the report with "N/A" rows.
7. Embellishing rule body wording in the report. Each rule's How to apply + example is canonical guidance. Copy it through for recommended_changes; do not paraphrase or expand.

Key Instructions

• Read-only until the Repair Loop; no writes without per-finding confirmation.
• The check-primitive-routing-coverage rule fires whether or not hooks are configured — absence of hooks against a CLAUDE.md carrying convertible rules is the coverage gap it surfaces.
• stop-loop-guard findings are fail, not warn — unguarded blocking Stop hooks require a session kill to recover.
• 18 judgment dimensions evaluated per hook; a dimension that does not apply (e.g., a rule about Python hooks against a bash hook) returns inapplicable silently.
• Recovery: outside the Repair Loop this skill modifies nothing; any edits it produces can be reverted with git diff / git checkout.

Handoff

Chainable to: /build:build-hook (create a new hook or substantially rewrite one flagged by the audit); /build:check-skill-pair hook (audit pair-level integrity).