Hook Development Guide

Create Claude Code hooks that intercept events in the lifecycle and can validate, modify, or block operations.

Hook Types

1. Command Hooks (recommended) -- Execute a script for deterministic checks
2. Prompt Hooks -- Use LLM reasoning for context-aware decisions
3. Agent Hooks (v2.1.0+) -- Leverage agent capabilities for complex workflows

Hook Events

Event	Trigger	Common Uses
PreToolUse	Before any tool executes	Block dangerous commands, validate inputs
PostToolUse	After tool completes	Format code, run linters, log results
SessionStart	When session begins	Check environment, load config
SessionEnd	When session ends	Cleanup, save state
Stop	When agent stops	Verify task completion
SubagentStop	When subagent stops	Validate subagent work
UserPromptSubmit	When user sends message	Process user input
PreCompact	Before context compression	Preserve critical info
Notification	System notifications	React to events
PermissionRequest	Permission dialogs (v2.1.0)	Custom permission handling

Configuration

hooks.json Format

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

Matchers: "Bash", "Edit", "Read" (case-sensitive tool names), or "*" for all.

Environment Variables

Variable	Description
CLAUDE_PLUGIN_ROOT	Plugin directory (always use for portable paths)
CLAUDE_PROJECT_DIR	Current project root
CLAUDE_ENV_FILE	Persist variables from SessionStart

Writing Command Hooks

Copy and customize a template from templates/:

Template	Purpose
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

cp ${CLAUDE_PLUGIN_ROOT}/skills/create-hook/templates/pretooluse-bash.py \
   plugins/my-hook/hooks/my-hook.py
chmod +x plugins/my-hook/hooks/my-hook.py

Essential Patterns

Always check safe patterns before blocking (allowlist-first):

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)

Exit methods:

• c.output.exit_success() -- allow operation
• c.output.exit_block("reason") -- block with message
• c.output.exit_modify({"command": modified}) -- modify input (PreToolUse only)

Early exit when hook doesn't apply:

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

Creating a New Hook Plugin

1. Create directory structure:

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

2. Create plugins/my-hook/.claude-plugin/plugin.json:

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

3. Create plugins/my-hook/hooks/hooks.json with event matchers (see Configuration above)

4. Copy and customize a template from this skill's templates/ directory

5. Validate: claude plugin validate .

Debugging

Test hooks directly by piping JSON input:

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

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

Reference Examples

Existing hooks in this repository:

• Block destructive commands: plugins/guards/security/safety-guard/
• Enforce commit format: plugins/guards/policy/conventional-commits/
• Format on save: plugins/guards/quality/python-format/
• Protect sensitive files: plugins/guards/security/protect-env/