audit-hooks

name	audit-hooks
description	Audit Claude Code hooks for safety and correctness. Use when reviewing hook health, checking hook safety, validating hooks, or after adding/modifying hooks.
disable-model-invocation	true
allowed-tools	Read, Grep, Glob, Bash

Hook Audit

Goal: verify that every Claude Code hook registered in .claude/settings.json is safe — advisory hooks can never hang or block a session, validators actually block what they exist to block, and no hook fails silently. Check each hook against the rules in BEST_PRACTICES.md and report PASS/WARN/FAIL per hook. Read-only: findings only, fixes are applied by a human.

Repo Context Probe

If .claude/skill-context/audit-hooks.md exists, read it and honor its declarations; otherwise use the generic defaults described below.

The context file is where a repo declares its validator inventory (hooks that must NOT have || true), its error-logging convention, and its hook log path. Generic defaults: validators are identified by a validate_* script name on PreToolUse/PostToolUse with a matcher; the error log is logs/hooks.log; the logging helper is log_hook_error() if the repo has one.

Audit Procedure

Step 1: Parse settings.json

Read .claude/settings.json and extract every hook entry. For each hook, record:

• Event type (UserPromptSubmit, PreToolUse, PostToolUse, Stop)
• Matcher (empty string = all, or specific tool name)
• Command string
• Timeout value
• Whether || true is present

Step 2: Classify hooks

| Classification | Criteria | || true required? | |---------------|----------|-------------------| | Validator | PreToolUse/PostToolUse + matcher + named validate_*.py | NO — must NOT have || true | | Advisory | Any hook whose purpose is logging/tracking/enrichment | YES — must have || true | | Stop | Any hook on Stop events | YES — must have || true |

Step 3: Check each hook against rules

For EACH hook command, check:

Settings-level checks:

• || true correctness (Rules 1-3 from BEST_PRACTICES.md)
• Timeout appropriateness (Rule 9: 5s simple, 10s git, 15s API)
• Matcher specificity (empty matcher on PreToolUse fires on every tool call — WARN if timeout > 5s)

Python script checks (for hooks targeting .py files):

• Has try/except + error logging at __main__ level (Rule 4)
• No bare sys.exit(1) in advisory hooks
• No top-level imports of known-heavy modules: anthropic, openai, pandas, numpy, httpx, pydantic (Rule 8)

Bash script checks (for hooks targeting .sh files):

• Uses set +e, not set -e (Rule 5)
• No bare exec without error handling (Rule 6)
• Prefers venv binaries over system PATH (Rule 7)
• Has error logging to the hook log

Step 4: Deployment readiness

• Every script path referenced in settings.json exists
• Python scripts are importable (no syntax errors)
• Shell scripts are executable (chmod +x)
• The error-logging helper is importable from where the repo declares it lives

Step 5: Check the hook log

If the hook log (default logs/hooks.log) exists, scan for recent errors (last 24h). Report:

• Total error count
• Unique hook names that errored
• Most frequent error message

Report Format

Output findings as a structured table:

## Hook Audit Report

### Summary
- Total hooks: N
- PASS: N | WARN: N | FAIL: N

### Findings

| Hook | Event | Type | Finding | Severity |
|------|-------|------|---------|----------|
| stop.py | Stop | Advisory | Has || true, has log_hook_error() | PASS |
| validate_commit_message.py | PreToolUse | Validator | No || true (correct) | PASS |
| calendar_prompt_hook.sh | UserPromptSubmit | Advisory | Missing || true | FAIL |

### Recommendations
[List specific fixes for FAIL and WARN items]

Severity Levels

• FAIL: Rule violation that can cause session hangs, silent failures, or security issues
• WARN: Suboptimal pattern that should be improved but is not immediately dangerous
• PASS: Hook follows all applicable best practices