Hooks Builder

Hooks Builder

A comprehensive guide for creating Claude Code hooks — event-driven automation that monitors and controls Claude's actions.

Quick Reference

The 10 Hook Events

Exit Code Semantics

Configuration Locations

~/.claude/settings.json          → Personal hooks (all projects)
.claude/settings.json            → Project hooks (team, committed)
.claude/settings.local.json      → Local overrides (not committed)

Essential Environment Variables

Key Commands

/hooks              # View active hooks
claude --debug      # Enable debug logging
chmod +x script.sh  # Make script executable

6-Phase Workflow

Phase 1: Requirements Gathering

Use AskUserQuestion to clarify:

1. What event should trigger this hook?

   • Tool execution (Pre/Post/Permission) → PreToolUse, PostToolUse, PermissionRequest
   • User input → UserPromptSubmit
   • Response completion → Stop, SubagentStop
   • Session lifecycle → SessionStart, SessionEnd
   • Context management → PreCompact
   • Notifications → Notification

2. What should happen when triggered?

   • Observe only (logging, metrics)
   • Block/allow based on conditions
   • Modify inputs before execution
   • Add context to prompts
   • Force continuation

3. Should it block, modify, or just observe?

   • Observer: PostToolUse, Notification, SessionEnd (can't block)
   • Gatekeeper: PreToolUse, PermissionRequest, UserPromptSubmit (can block)
   • Transformer: PreToolUse with updatedInput (can modify)
   • Controller: Stop, SubagentStop (can force continue)

4. What are the security implications?

   • Will it handle untrusted input?
   • Could it expose sensitive data?
   • Does it need to access external systems?

Phase 2: Event Selection

Match event to use case:

Determine if matchers are needed:

• Specific tools? → Use matcher: "Write|Edit"
• All tools? → Use "*" or omit matcher
• MCP tools? → Use mcp__server__tool pattern
• Bash commands? → Use Bash(git:*) pattern

Phase 3: Matcher Design

Matcher Pattern Syntax:

// Exact match (case-sensitive!)
"matcher": "Write"

// OR pattern
"matcher": "Write|Edit"

// Prefix match
"matcher": "Notebook.*"

// Contains match
"matcher": ".*Read.*"

// All tools
"matcher": "*"

// MCP tools
"matcher": "mcp__memory__.*"

// Bash sub-patterns
"matcher": "Bash(git:*)"

Common Matcher Patterns:

Phase 4: Implementation

Choose implementation approach:

1. Inline command (simple, no external file):

   {
     "type": "command",
     "command": "echo \"$(date) | $tool_name\" >> ~/.claude/audit.log"
   }
   

2. External script (complex logic, reusable):

   {
     "type": "command",
     "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/validate.sh"
   }
   

3. Prompt-based (LLM evaluation, intelligent decisions):

   {
     "type": "prompt",
     "prompt": "Analyze if all tasks are complete: $ARGUMENTS",
     "timeout": 30
   }
   

Script Template (Bash):

#!/bin/bash
set -euo pipefail

# Read JSON input from stdin
input=$(cat)

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

# Your logic here
if [[ "$file_path" == *".env"* ]]; then
    echo "BLOCKED: Cannot modify .env files" >&2
    exit 2
fi

# Success - output decision
echo '{"decision": "approve"}'
exit 0

Script Template (Python):

#!/usr/bin/env python3
import sys
import json

# Read JSON input from stdin
data = json.load(sys.stdin)

# Extract fields
tool_name = data.get('tool_name', '')
tool_input = data.get('tool_input', {})
file_path = tool_input.get('file_path', '')

# Your logic here
if '.env' in file_path:
    print("BLOCKED: Cannot modify .env files", file=sys.stderr)
    sys.exit(2)

# Success - output decision
output = {"decision": "approve"}
print(json.dumps(output))
sys.exit(0)

Phase 5: Security Hardening

CRITICAL: Hooks execute shell commands with YOUR permissions.

Security Checklist:

• All variables quoted: "$VAR" not $VAR
• JSON parsed with jq or json.load (not grep/sed)
• Paths validated (no .., normalized)
• No sensitive data in logs/output
• No sudo or privilege escalation
• Script tested manually first
• Project hooks audited before running
• Timeout set appropriately
• Error handling for all failure modes

Secure Patterns:

# UNSAFE - injection risk
rm $file_path

# SAFE - quoted, prevents flag injection
rm -- "$file_path"

# UNSAFE - parsing risk
cat "$input" | grep "field"

# SAFE - proper JSON parsing
echo "$input" | jq -r '.field'

Defense in Depth:

1. Input validation (parse JSON properly)
2. Path sanitization (normalize, check boundaries)
3. Output sanitization (no sensitive data)
4. Fail-safe defaults (block on error, not allow)
5. Timeout protection (prevent infinite loops)

Phase 6: Testing

Step 1: Manual Script Testing

# Create mock input
cat > /tmp/mock-input.json << 'EOF'
{
  "session_id": "test-123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "test content"
  }
}
EOF

# Test script
cat /tmp/mock-input.json | ./my-hook.sh
echo "Exit code: $?"

Step 2: Edge Case Testing

• Empty inputs: {}
• Missing fields: {"tool_name": "Write"}
• Malicious inputs: {"tool_input": {"file_path": "; rm -rf /"}}
• Large inputs: 10KB+ content
• Unicode: paths with special characters

Step 3: Integration Testing

# Start Claude with debug mode
claude --debug

# Trigger the tool your hook targets
# Watch debug output for hook execution

Step 4: Verification

# Check hooks are registered
/hooks

# Watch hook execution
claude --debug 2>&1 | grep -i hook

Hook Patterns

Observer Pattern

Log without blocking — use PostToolUse or Notification.

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "echo \"$(date) | $tool_name\" >> ~/.claude/audit.log"
      }]
    }]
  }
}

Gatekeeper Pattern

Block dangerous actions — use PreToolUse or PermissionRequest.

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "python3 ~/.claude/hooks/file-protector.py"
      }]
    }]
  }
}

Transformer Pattern

Modify inputs before execution — use PreToolUse with updatedInput.

# In script, output:
output = {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow",
        "updatedInput": {
            "content": add_license_header(original_content)
        }
    }
}
print(json.dumps(output))

Orchestrator Pattern

Coordinate multiple events — combine SessionStart + PreToolUse + PostToolUse.

{
  "hooks": {
    "SessionStart": [{
      "matcher": "startup",
      "hooks": [{"type": "command", "command": "~/.claude/hooks/setup-env.sh"}]
    }],
    "PreToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "~/.claude/hooks/validate.sh"}]
    }],
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{"type": "command", "command": "~/.claude/hooks/format.sh"}]
    }]
  }
}

Common Pitfalls

1. Forgetting Exit Code 2 for Blocking

# WRONG - exit 1 doesn't block
echo "Error" >&2
exit 1

# RIGHT - exit 2 blocks Claude
echo "BLOCKED: reason" >&2
exit 2

2. Case Sensitivity in Matchers

// WRONG - won't match "Write" tool
"matcher": "write"

// RIGHT - case-sensitive match
"matcher": "Write"

3. Unquoted Variables (Injection Risk)

# WRONG - command injection vulnerability
rm $file_path

# RIGHT - properly quoted
rm -- "$file_path"

4. Missing Shebang in Scripts

# WRONG - no shebang, may fail
set -euo pipefail

# RIGHT - explicit interpreter
#!/bin/bash
set -euo pipefail

5. Not Making Scripts Executable

# Don't forget!
chmod +x ~/.claude/hooks/my-hook.sh

6. Forgetting to Quote Paths in JSON

// WRONG - spaces in path will break
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/script.sh"

// RIGHT - quoted path
"command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/script.sh"

7. No Error Handling

# WRONG - silent failures
input=$(cat)
tool=$(echo "$input" | jq -r '.tool_name')

# RIGHT - handle errors
input=$(cat) || { echo "Failed to read input" >&2; exit 1; }
tool=$(echo "$input" | jq -r '.tool_name') || { echo "Failed to parse JSON" >&2; exit 1; }

8. Logging Sensitive Data

# WRONG - may log secrets
echo "Processing: $input" >> /tmp/debug.log

# RIGHT - sanitize before logging
echo "Processing tool: $tool_name" >> /tmp/debug.log

When to Use Hooks

USE hooks for:

• Security enforcement (block dangerous operations)
• Code quality automation (format, lint on save)
• Compliance and auditing (log all actions)
• Environment setup (consistent configuration)
• Workflow automation (notifications, integrations)
• Input validation (prompt checking)
• Task completion verification

DON'T use hooks for:

• Adding new capabilities (use Skills)
• Delegating complex work (use Agents)
• User-invoked prompts (use Commands)
• Simple one-off tasks (just ask Claude)

Files in This Skill

Templates (Progressive Complexity)

• templates/basic-hook.md — Single event, inline command
• templates/with-scripts.md — External shell scripts
• templates/with-decisions.md — Permission control, input modification
• templates/with-prompts.md — LLM-based evaluation
• templates/production-hooks.md — Complete multi-event system

Examples (18 Complete Hooks)

• examples/security-hooks.md — Protection, validation, auditing
• examples/quality-hooks.md — Formatting, linting, testing
• examples/workflow-hooks.md — Setup, context, notifications

Reference

• reference/syntax-guide.md — Complete JSON schemas, all events
• reference/best-practices.md — Security, design, team deployment
• reference/troubleshooting.md — 10 common issues, testing methodology