Audit Hooks

Hook Audit

Audits all Claude Code hooks registered in .claude/settings.json against the best practices defined in BEST_PRACTICES.md. Produces a structured report with PASS/WARN/FAIL dispositions per hook.

What this skill does

1. Parse .claude/settings.json and extract all hook entries
2. Classify each hook as advisory (has || true) or validator (no || true)
3. Run safety checks against BEST_PRACTICES.md rules
4. Inspect each hook script for code-level issues
5. Check deployment readiness
6. Output a structured findings report

This skill is read-only. It does NOT auto-fix anything. Review findings and fix manually.

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 + log_hook_error() 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)
• File exists and is syntactically valid Python

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 logs/hooks.log
• File exists and is executable

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)
• log_hook_error() is importable from hook_utils.constants

Step 5: Check logs/hooks.log

If 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