hook-audit

Comprehensive audit of Claude Code hooks for correctness, safety, and performance. Use when reviewing, validating, or debugging hooks, checking JSON stdin handling, verifying exit codes (0=allow, 2=block), analyzing error handling, fixing hook failures, ensuring safe degradation, optimizing performance, or validating settings.json registration. Also triggers when user asks about hook best practices, wants to create a new hook, or needs help with hook configuration.

⭐5stars🔀1forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive auditing framework for Claude Code hooks, ensuring they adhere to best practices for security, performance, and reliability. It automates the validation of JSON input handling, exit code semantics (0 for allow, 2 for block), and error recovery patterns to prevent hooks from inadvertently blocking user workflows or compromising system stability.

Use Cases

  • Security & Safety Auditing: Automatically verify that hooks correctly implement exit code logic to prevent unauthorized operations while ensuring the agent doesn't get stuck on internal errors.
  • Performance Optimization: Identify slow-running PreToolUse hooks that may degrade the user experience and provide recommendations for caching or moving logic to PostToolUse.
  • Robust Error Handling: Validate that hooks include proper try/except blocks and graceful degradation so that missing dependencies or malformed JSON don't interrupt the main session.
  • Configuration & Registration: Ensure hooks are correctly registered in settings.json with appropriate matchers and timeouts, preventing common configuration pitfalls during setup.
  • Hook Development & Best Practices: Guide developers in creating new hooks by providing standardized templates for Python and Bash, ensuring consistent patterns across the codebase.
namehook-audit
descriptionComprehensive audit of Claude Code hooks for correctness, safety, and performance. Use when reviewing, validating, or debugging hooks, checking JSON stdin handling, verifying exit codes (0=allow, 2=block), analyzing error handling, fixing hook failures, ensuring safe degradation, optimizing performance, or validating settings.json registration. Also triggers when user asks about hook best practices, wants to create a new hook, or needs help with hook configuration.
allowed-tools[Read, Grep, Glob, Bash]
modelhaiku
tags[audit, hooks, validation, security]

Reference Files

Advanced hook patterns and best practices:


Hook Audit

Performs comprehensive security and quality audits of Claude Code hooks, ensuring correct JSON handling, exit code semantics, error handling, and performance.

Quick Start

Audit a single hook:

User: "Audit my validate-config.py hook"
Assistant: [Reads hook file, checks patterns, generates report]

Audit all hooks:

User: "Check all my hooks for best practices"
Assistant: [Finds all hooks, analyzes each, generates consolidated report]

Fix specific issues:

User: "My hook is blocking on errors"
Assistant: [Analyzes error handling, suggests fixes]

Hook Audit Checklist

Use this checklist to audit any Claude Code hook:

Critical Requirements

  • Shebang Line: Correct interpreter (#!/usr/bin/env python3 or #!/usr/bin/env bash)
  • JSON stdin Handling: Safe parsing with try/except and .get() methods
  • Exit Codes: Correct semantics (0=allow, 2=block, never 1)
  • Error Handling: Exit 0 on hook errors (never block on hook failures)
  • Settings.json Registration: Hook is registered with correct matcher and timeout

High Priority

  • Timeout: Configured appropriately for hook type (PreToolUse <500ms, PostToolUse <2s)
  • File Type Validation: Checks file type before processing
  • Error Messages: Clear messages to stderr
  • Performance: Executes within reasonable time

Medium Priority

  • Naming Convention: Uses kebab-case naming
  • Documentation: Header comments explain purpose and usage
  • Pattern Consistency: Follows existing hook patterns
  • Security: No security vulnerabilities or unsafe operations

Audit Workflow

Step 1: Identify Hook Type

Determine the hook type from settings.json registration:

  • PreToolUse: Runs before tool execution, can block operations
  • PostToolUse: Runs after successful tool execution
  • Notification: Runs on specific events (Idle, etc.)
  • SessionStart: Runs once at session start

Hook type determines performance requirements and exit code handling.

Step 2: Read Hook File and Check Syntax

Read the hook file and verify basic syntax:

# For Python hooks
python3 -m py_compile hook-file.py

# For Bash hooks
bash -n hook-file.sh

Check for:

  • Correct shebang line
  • Executable permissions
  • Valid syntax

Step 3: Verify JSON Handling Pattern

For hooks that receive JSON stdin (PreToolUse, PostToolUse), verify safe parsing:

Python Pattern:

try:
    data = json.load(sys.stdin)
    file_path = data.get("tool_input", {}).get("file_path", "")
    content = data.get("tool_input", {}).get("content", "")
except Exception as e:
    print(f"Error: {e}", file=sys.stderr)
    sys.exit(0)  # Don't block on parsing errors

Bash Pattern:

# Read stdin to variable
stdin_data=$(cat)

# Parse specific fields with jq
file_path=$(echo "$stdin_data" | jq -r '.tool_input.file_path // empty')

Critical: Use .get() with defaults, never direct key access.

Step 4: Check Exit Code Usage

Verify exit codes follow correct semantics:

  • Exit 0: Allow operation (or hook encountered error)
  • Exit 2: Block operation (validation failed)
  • Never Exit 1: Reserved, don't use

Pattern to Check:

# Good: Block on validation failure
if errors:
    print(f"Validation errors:", file=sys.stderr)
    sys.exit(2)

# Good: Allow on hook error
except Exception as e:
    print(f"Hook error: {e}", file=sys.stderr)
    sys.exit(0)  # Don't block user

# Bad: Exit 1 or non-zero on errors
sys.exit(1)  # ✗ Wrong, use 0 or 2

For details on exit code patterns, see exit-codes.md.

Step 5: Review Error Handling

Check that hooks degrade gracefully:

  1. Dependency Check: Missing dependencies exit 0 (don't block)
  2. Try/Except: All operations wrapped in try/except
  3. Error Exit: Exceptions exit 0, not 1 or other codes
  4. Clear Messages: Errors printed to stderr with context

Example Pattern:

try:
    import yaml
except ImportError:
    print("Warning: PyYAML not installed, skipping", file=sys.stderr)
    sys.exit(0)  # Don't block user

try:
    # Hook logic here
    ...
except Exception as e:
    print(f"Error in hook: {e}", file=sys.stderr)
    sys.exit(0)  # Don't block user

For error handling patterns, see error-patterns.md.

Step 6: Validate settings.json Registration

Check that the hook is properly registered:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "command": "python3 ~/.claude/hooks/validate-config.py",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

Verify:

  • Hook file exists at specified path
  • Matcher pattern is correct for intended triggers
  • Timeout is appropriate for hook type
  • Hook type (PreToolUse/PostToolUse/etc.) matches purpose

Step 7: Generate Report

Create a structured audit report following the output format below.

Hook Type Reference

PreToolUse Hooks

Purpose: Validate operations before execution Can Block: Yes (exit 2 to block) Performance Target: <500ms (blocks user interaction) JSON stdin: Tool name and input parameters

Example Matchers:

  • Edit|Write - Validate before file modifications
  • Bash - Validate before bash commands
  • .* - All tools (use cautiously)

Common Uses:

  • File content validation (YAML, config files)
  • Security checks (prevent writing secrets)
  • Policy enforcement

PostToolUse Hooks

Purpose: Process results after successful execution Can Block: No (exit code ignored, operation already completed) Performance Target: <2s (runs after operation) JSON stdin: Tool name, input, and output

Common Uses:

  • Auto-formatting (gofmt, prettier)
  • Logging operations
  • Side effects (notifications, metrics)

Notification Hooks

Purpose: React to events Can Block: No Performance Target: <100ms (quick notifications) JSON stdin: Event-specific data

Common Uses:

  • Desktop notifications (Idle event)
  • Metrics tracking
  • Alert systems

SessionStart Hooks

Purpose: Initialize session state Can Block: No Performance Target: <5s (one-time initialization) JSON stdin: Session metadata

Common Uses:

  • Load git repository context
  • Set environment variables
  • Initialize session state

Common Issues

Missing try/except

Problem: Hook crashes on errors, blocks user

# ✗ Bad: No error handling
data = json.load(sys.stdin)
file_path = data["tool_input"]["file_path"]

Fix: Wrap in try/except, exit 0 on errors

# ✓ Good: Safe error handling
try:
    data = json.load(sys.stdin)
    file_path = data.get("tool_input", {}).get("file_path", "")
except Exception as e:
    print(f"Error: {e}", file=sys.stderr)
    sys.exit(0)

Wrong Exit Codes

Problem: Using exit 1 instead of 0 or 2

# ✗ Bad: Exit 1
if error:
    sys.exit(1)

Fix: Use exit 2 to block, exit 0 to allow

# ✓ Good: Correct exit codes
if validation_failed:
    sys.exit(2)  # Block operation

if hook_error:
    sys.exit(0)  # Don't block user

Blocking on Hook Errors

Problem: Hook exits non-zero on internal errors, blocks user

# ✗ Bad: Blocks user on missing dependency
import yaml  # Crashes if not installed

Fix: Check dependencies, exit 0 on errors

# ✓ Good: Graceful degradation
try:
    import yaml
except ImportError:
    print("Warning: PyYAML not installed", file=sys.stderr)
    sys.exit(0)

Slow Performance

Problem: PreToolUse hook takes >1s, blocks user

Fix: Optimize or move to PostToolUse

  • Cache expensive operations
  • Use faster parsing (regex instead of full AST)
  • Move non-critical checks to PostToolUse

For performance optimization, see performance.md.

Report Format

Generate audit reports in this standardized structure:

# Hook Audit Report: {hook-name}

**Hook**: {name}
**Type**: PreToolUse | PostToolUse | Notification | SessionStart
**File**: {path}
**Audited**: {YYYY-MM-DD HH:MM}

## Summary

{1-2 sentence overview of hook and audit results}

## Compliance Status

**Overall**: PASS | NEEDS WORK | FAIL

- **Shebang Line**: ✓/✗
- **JSON Handling**: ✓/✗
- **Exit Codes**: ✓/✗
- **Error Handling**: ✓/✗
- **Performance**: ✓/✗
- **Registration**: ✓/✗

## Critical Issues

{List of critical failures that must be fixed}

### {Issue Title}

- **Severity**: CRITICAL
- **Location**: {file}:{line}
- **Issue**: {description}
- **Fix**: {specific remediation}

## High Priority Issues

{List of important improvements}

### {Issue Title}

- **Severity**: HIGH
- **Location**: {file}:{line}
- **Issue**: {description}
- **Fix**: {specific remediation}

## Medium Priority Issues

{List of best practice violations}

### {Issue Title}

- **Severity**: MEDIUM
- **Location**: {file}:{line}
- **Issue**: {description}
- **Fix**: {specific remediation}

## Recommendations

1. **Critical**: {must-fix items for safety/correctness}
2. **Important**: {should-fix items for reliability}
3. **Nice-to-Have**: {polish items for maintainability}

## Next Steps

{Specific actions to improve hook quality and safety}

Integration

With Other Auditors

  • claude-code-evaluator: General correctness and clarity
  • claude-code-test-runner: Functional testing
  • audit-coordinator: Orchestrates multiple auditors

With Hook Validation

The validate-config.py hook validates YAML frontmatter in agents/skills. The hook-audit validates hooks themselves - a meta-validation.

Examples

For detailed examples of good and bad hook patterns, including before/after refactoring, see examples.md.

Quick Examples:

Good Hook (validate-config.py):

  • ✓ Safe JSON parsing with try/except
  • ✓ Correct exit codes (0 on error, 2 to block)
  • ✓ Dependency checking (PyYAML)
  • ✓ Clear error messages
  • ✓ File type validation

Simple Hook (log-git-commands.sh):

  • ✓ Basic bash pattern
  • ✓ Safe jq parsing
  • ✓ Always exits 0 (informational)
  • ✓ Clear purpose

For complete examples and anti-patterns, see the references above.