Claude Code Hooks Mastery

Overview

Claude Code hooks are event-driven extensions that execute commands or LLM evaluations at specific lifecycle points. This skill provides guidance for creating production-ready hooks following the official protocol specification.

Core Concepts

Hook Types

Command Hooks: Execute bash scripts with JSON input via stdin

{
  "type": "command",
  "command": "python3 /path/to/script.py",
  "timeout": 60
}

Prompt-Based Hooks: Use LLM (Haiku) for intelligent evaluation

{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS",
  "timeout": 30
}

Hook Events

Configuration Structure

Hooks are configured in settings files (user, project, or local scope):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validator.py",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Creating Hooks

Step 1: Choose Hook Event

Identify which lifecycle point to hook into:

• Validation before action: PreToolUse, PermissionRequest
• Processing after action: PostToolUse
• Context enhancement: UserPromptSubmit, SessionStart
• Flow control: Stop, SubagentStop

Step 2: Write Hook Script

Input Protocol: Hooks receive JSON via stdin with these common fields:

{
  "session_id": "string",
  "transcript_path": "string",
  "cwd": "string",
  "permission_mode": "default|plan|acceptEdits|bypassPermissions",
  "hook_event_name": "EventName",
  // Event-specific fields...
}

Output Protocol: Respond via exit codes and stdout:

Exit Code 0 (Success):

• stdout: Plain text or JSON for structured control
• JSON enables advanced decisions

Exit Code 2 (Blocking):

• stderr: Error message fed to Claude
• Blocks the action (behavior varies by event)

Exit Code 1+ (Non-blocking):

• stderr: Logged to verbose mode
• Execution continues

Step 3: Configure Hook

Add to appropriate settings file:

• ~/.claude/settings.json

  - User-level

• .claude/settings.json

  - Project-level (team-shared)

• .claude/settings.local.json

  - Local (git-ignored)

Step 4: Test Hook

Enable debug mode to see hook execution:

claude --debug

Use verbose mode (Ctrl+O) during session to see hook output.

Common Patterns

Pattern 1: Validation Hook (PreToolUse)

Validate and potentially block tool calls:

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

# Read input
input_data = json.load(sys.stdin)

# Validate
if should_block(input_data):
    print("Validation failed: reason", file=sys.stderr)
    sys.exit(2)  # Block execution

# Allow with optional modification
output = {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "allow",
        "updatedInput": {
            "modified_field": "new_value"
        }
    }
}
print(json.dumps(output))
sys.exit(0)

Pattern 2: Context Enrichment (UserPromptSubmit)

Add context before Claude processes prompt:

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

input_data = json.load(sys.stdin)

# Add context (plain text stdout with exit 0)
context = f"Current time: {datetime.datetime.now()}\n"
context += f"Current directory: {input_data['cwd']}"
print(context)

sys.exit(0)

Pattern 3: Environment Setup (SessionStart)

Initialize environment variables and context:

#!/bin/bash

# Setup environment
source ~/.nvm/nvm.sh
nvm use 20

# Persist variables
if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

# Add context
echo "Environment initialized: Node $(node --version)"

exit 0

Pattern 4: Intelligent Decision (Stop Hook)

Use LLM for context-aware decisions:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Context: $ARGUMENTS\n\nDetermine if all tasks are complete. Check for:\n1. All user requests fulfilled\n2. No errors requiring fixes\n3. Tests passing\n\nRespond: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
          }
        ]
      }
    ]
  }
}

Matcher Patterns

Matchers determine when hooks execute (PreToolUse, PostToolUse, PermissionRequest, Notification, PreCompact, SessionStart):

Exact match:

"matcher": "Write"

"matcher": "Edit|Write"

"matcher": "*"

"matcher": ""

"matcher": "mcp__github__.*"

Environment Variables

Available in all hooks:

• CLAUDE_PROJECT_DIR

  - Project root directory

• CLAUDE_CODE_REMOTE

  -

  "true"

  if web environment

SessionStart hooks only:

• CLAUDE_ENV_FILE

  - File path for persisting environment variables

Plugin hooks only:

• CLAUDE_PLUGIN_ROOT

  - Plugin directory

Security Considerations

Input Validation: Always validate and sanitize inputs

if '..' in file_path or file_path.startswith('/'):
    print("Path traversal detected", file=sys.stderr)
    sys.exit(2)

Shell Safety: Quote all variables

command="$CLAUDE_PROJECT_DIR/script.sh"

Sensitive Files: Skip .env, .git/, keys, etc.

sensitive = ['.env', '.git/', 'id_rsa', '*.pem']
if any(p in file_path for p in sensitive):
    sys.exit(2)

Troubleshooting

Hook not executing:

• Check configuration with

  /hooks

  command
• Verify matcher pattern matches tool name
• Enable debug mode:

  claude --debug

Hook timing out:

• Increase timeout in configuration
• Default: 60s for command, 30s for prompt
• Individual timeout doesn't affect other hooks

JSON parsing errors:

• Validate JSON output with

  jq

• Check exit code is 0 for JSON processing
• Exit code 2 ignores stdout JSON

Permission denied:

• Make scripts executable:

  chmod +x script.sh

• Check file paths are absolute or use

  $CLAUDE_PROJECT_DIR

Quick Reference

Decision Control by Event

permissionDecision: "allow"

permissionDecision: "deny"

updatedInput: {}

behavior: "allow"

behavior: "deny"

updatedInput: {}

decision: "block"

decision: "block"

decision: "block"

Exit Code Behavior

Additional Resources

For detailed protocol specifications:

• references/protocol-specification.md

  - Complete protocol documentation

• references/event-reference.md

  - Detailed event specifications

For working examples:

• examples/pretooluse-validator/

  - Bash command validation

• examples/userprompt-enricher/

  - Context injection

• examples/sessionstart-setup/

  - Environment initialization

• examples/stop-evaluator/

  - Prompt-based decision making

For validation and testing:

• scripts/validate-hook-config.py

  - Validate hooks.json against schema

• scripts/test-hook-io.py

  - Test hook input/output locally

• scripts/generate-hook-template.sh

  - Generate hook boilerplate

For schema validation:

• assets/hooks-schema.json

  - JSON schema for hooks configuration