Hook Development Guide

This skill provides comprehensive guidance for creating Claude Code hooks. Hooks intercept events in the Claude Code lifecycle and can validate, modify, or block operations.

Hook Types

1. Command Hooks (Recommended)

Execute a script for deterministic checks. Best for pattern matching, validation, and blocking.

{
  "type": "command",
  "command": "${CLAUDE_PLUGIN_ROOT}/hooks/my-hook.py",
  "timeout": 10
}

2. Prompt Hooks

Use LLM reasoning for context-aware decisions. More expensive but can understand intent.

{
  "type": "prompt",
  "prompt": "Check if this operation is safe given the project context..."
}

3. Agent Hooks (v2.1.0+)

Leverage agent capabilities for complex workflows requiring multiple steps.

Hook Events

Configuration Structure

Plugin hooks.json Format

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/check-bash.py",
            "timeout": 10
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/format-on-save.py",
            "timeout": 30
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/init.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Matchers

• "Bash" - Match specific tool by name
• "Edit" - Match Edit tool
• "Read" - Match Read tool
• "*" - Match all tools/events
• Tool names are case-sensitive

Environment Variables

Critical: Always use ${CLAUDE_PLUGIN_ROOT} in hook commands for portability.

Writing Command Hooks (Python)

Basic Structure

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["cchooks"]
# ///
"""Hook description."""

from cchooks import PreToolUseContext, create_context

c = create_context()
assert isinstance(c, PreToolUseContext)

# Check if this is the right tool
if c.tool_name != "Bash":
    c.output.exit_success()

# Get tool input
command = c.tool_input.get("command", "")

# Your validation logic here
if is_dangerous(command):
    c.output.exit_block("Reason for blocking")

c.output.exit_success()

Context Types

• PreToolUseContext - Before tool execution
• PostToolUseContext - After tool execution
• Other contexts follow same pattern

Exit Methods

# Allow operation to proceed
c.output.exit_success()

# Block operation with message
c.output.exit_block("Descriptive reason for blocking")

# Modify tool input (PreToolUse only)
c.output.exit_modify({"command": modified_command})

Best Practices

Security

1. Quote all bash variables to prevent injection
2. Validate inputs before processing
3. Use safe patterns with allowlists before blocklists
4. Set reasonable timeouts to prevent hangs

Performance

1. Exit early when hook doesn't apply (if c.tool_name != "X": exit_success())
2. Use compiled regex for pattern matching
3. Keep hooks focused - one responsibility per hook

Patterns

Safe Patterns First

# Check safe patterns before blocking
SAFE_PATTERNS = [
    r"rm\s+-rf\s+/tmp/",
]

BLOCKED_PATTERNS = [
    (r"rm\s+-rf\s+", "rm -rf is destructive"),
]

for pattern in SAFE_PATTERNS:
    if re.search(pattern, command):
        c.output.exit_success()

for pattern, reason in BLOCKED_PATTERNS:
    if re.search(pattern, command):
        c.output.exit_block(reason)

Informative Block Messages

c.output.exit_block(
    f"BLOCKED: {reason}\n"
    f"Command: {command}\n"
    "If this operation is truly needed, ask the user for permission."
)

Templates

Ready-to-use templates are available:

• templates/pretooluse-bash.py - PreToolUse hook for Bash commands
• templates/pretooluse-read.py - PreToolUse hook for file reads
• templates/posttooluse-edit.py - PostToolUse hook for formatting
• templates/sessionstart.sh - SessionStart initialization

Copy and customize for your plugin:

cp ${CLAUDE_PLUGIN_ROOT}/skills/create-hook/templates/pretooluse-bash.py \
   your-plugin/hooks/your-hook.py

Creating a New Hook Plugin

1. Create Directory Structure

mkdir -p plugins/my-hook/.claude-plugin
mkdir -p plugins/my-hook/hooks

2. Create plugin.json

{
  "name": "my-hook",
  "version": "1.0.0",
  "description": "What this hook does"
}

3. Create hooks/hooks.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/my-hook.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

4. Create Hook Script

#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["cchooks"]
# ///
"""My hook description."""

from cchooks import PreToolUseContext, create_context

c = create_context()
assert isinstance(c, PreToolUseContext)

if c.tool_name != "Bash":
    c.output.exit_success()

command = c.tool_input.get("command", "")

# Add your logic here

c.output.exit_success()

5. Make Executable

chmod +x plugins/my-hook/hooks/my-hook.py

6. Validate

claude plugin validate .

Common Hook Patterns

Block Destructive Commands

See plugins/safety-guard/hooks/safety_guard_bash.py

Enforce Coding Standards

See plugins/conventional-commits/hooks/conventional_commits.py

Format on Save

See plugins/python-format/hooks/format_python.py

Protect Sensitive Files

See plugins/protect-env/hooks/protect_env.py

Debugging Hooks

Test Hook Directly

echo '{"tool_name": "Bash", "tool_input": {"command": "rm -rf /"}}' | \
  python plugins/my-hook/hooks/my-hook.py

Check Hook Output

Hooks should output JSON. Check stdout/stderr for errors.

Validate JSON

cat plugins/my-hook/hooks/hooks.json | jq .