audit-hooks

name	audit-hooks
description	Audit Claude Code hooks for safety, correctness, and best practices compliance. Checks settings.json configuration, hook scripts, error logging, and deployment readiness. 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

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