---

name: hook-creator description: Create native Claude Code hooks in ~/.claude/hooks/. Use when adding event-triggered automation (PreToolUse, PostToolUse, Stop, etc.).

Hook Creator (Tier 3 - Full Reference)

Persona: Defensive programmer creating fail-safe hooks - prioritizes silent failure over breaking workflows.

Create native Claude Code hooks - Python scripts that run before/after tool calls.

Note: Core workflow is in instructions.md. This file contains detailed templates, context fields, and registration details.

Hook Types

Event	When It Runs	Common Uses
PreToolUse	Before tool executes	Block, warn, suggest alternatives
PostToolUse	After tool completes	Cache results, chain to other tools, log
UserPromptSubmit	When user sends message	Context monitoring, input validation
Stop	When Claude stops	Session persistence, uncommitted reminders

Critical: Output Format

All hooks must return JSON with hookSpecificOutput:

# PreToolUse - approve/deny/block
result = {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "approve",  # or "deny", "block"
        "permissionDecisionReason": "Message shown to Claude"
    }
}

# PostToolUse - informational message
result = {
    "hookSpecificOutput": {
        "hookEventName": "PostToolUse",
        "message": "Message shown to Claude"
    }
}

# UserPromptSubmit - same as PreToolUse format
result = {
    "hookSpecificOutput": {
        "hookEventName": "UserPromptSubmit",
        "permissionDecision": "approve",
        "permissionDecisionReason": "Message if not approved"
    }
}

WRONG formats (will cause errors):

# BAD - old format
{"decision": "approve", "message": "..."}

# BAD - missing hookSpecificOutput wrapper
{"permissionDecision": "approve", "permissionDecisionReason": "..."}

Context Fields Available

Field	Available In	Contains
tool_name	Pre/Post	Tool name: "Bash", "Edit", "Task", etc.
tool_input	Pre/Post	Tool parameters (dict)
tool_result	PostToolUse only	Tool output (dict or str)
cwd	All	Current working directory
session_id	All	Session identifier

Detect Pre vs Post:

if "tool_result" in ctx:
    # PostToolUse
else:
    # PreToolUse

Hook Template

#!/usr/bin/env python3
"""
{Description of what this hook does}.

{Event} hook for {Tool} tool.
"""
import json
import sys

def main():
    try:
        ctx = json.load(sys.stdin)
    except json.JSONDecodeError:
        sys.exit(0)  # Silent failure

    tool_name = ctx.get("tool_name", "")
    tool_input = ctx.get("tool_input", {})

    # Early exit if not our target tool
    if tool_name != "TargetTool":
        sys.exit(0)

    # Your logic here
    should_warn = False  # Replace with actual check

    if should_warn:
        result = {
            "hookSpecificOutput": {
                "hookEventName": "PreToolUse",
                "permissionDecision": "approve",
                "permissionDecisionReason": "Warning message here"
            }
        }
        print(json.dumps(result))

    sys.exit(0)

if __name__ == "__main__":
    main()

Settings.json Configuration

Add hook to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "$HOME/.claude/hooks/my_hook.py",
            "timeout": 1,
            "once": true
          }
        ]
      }
    ]
  }
}

Hook options:

• type: "command" (required)
• command: Path to hook script (required)
• timeout: Max execution time in seconds (default: 30)
• once: If true, hook runs only once per session (NEW)

Matcher patterns:

• Single tool: "Bash"
• Multiple tools: "Bash|Edit|Write"
• All tools: "*" or omit matcher

PreToolUse Middleware Pattern (NEW)

Hooks can now return updatedInput with ask permission to modify tool input while still requesting user consent:

result = {
    "hookSpecificOutput": {
        "hookEventName": "PreToolUse",
        "permissionDecision": "ask",  # Request user consent
        "permissionDecisionReason": "Modified input - please confirm",
        "updatedInput": {
            "command": "safer_command_here"
        }
    }
}

Permission Decisions

Decision	Effect
approve	Allow tool, show message
deny	Block tool, show reason
block	Hard block (same as deny)
ask	Request user consent (can include updatedInput)
(no output)	Silent approval

Should NOT Attempt

• Complex logic that might timeout (keep under 1s)
• Side effects in PreToolUse hooks (only decide, don't act)
• Blocking without clear reason (frustrates workflow)
• Denying based on uncertain heuristics
• Network calls in hooks (too slow, may fail)
• Reading large files (use caching instead)

Failure Behavior

Always fail silently. A broken hook should never block work:

def main():
    try:
        ctx = json.load(sys.stdin)
        # ... your logic ...
    except Exception:
        pass  # Silent failure
    finally:
        sys.exit(0)  # Always exit 0

Never:

• Exit with non-zero codes
• Print error messages to stdout
• Let exceptions propagate

Escalation Triggers

Situation	Escalate To
Hook denies frequently	Rethink rule - consider skill or agent instead
Logic too complex for 1s timeout	agent-creator skill for subagent
Multiple hooks conflict	User to resolve priority/ordering
Requires human judgment	User clarification or manual intervention

Best Practices

1. Silent on success: Return nothing if no action needed
2. Timeout of 1s: Keep hooks fast, use 1-5s timeout max
3. Graceful errors: Catch all exceptions, exit 0 on failure
4. No side effects in Pre: PreToolUse should only decide, not act
5. Cache expensive ops: Use /tmp for caching

Examples

Block Dangerous Commands (PreToolUse)

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

DANGEROUS = [r"rm\s+-rf\s+/", r"chmod\s+777", r">\s*/dev/sd"]

try:
    ctx = json.load(sys.stdin)
    if ctx.get("tool_name") != "Bash":
        sys.exit(0)

    cmd = ctx.get("tool_input", {}).get("command", "")
    for pattern in DANGEROUS:
        if re.search(pattern, cmd):
            print(json.dumps({
                "hookSpecificOutput": {
                    "hookEventName": "PreToolUse",
                    "permissionDecision": "deny",
                    "permissionDecisionReason": f"Blocked dangerous command: {cmd[:50]}"
                }
            }))
            break
except Exception:
    pass
sys.exit(0)

Log Tool Usage (PostToolUse)

#!/usr/bin/env python3
import json, sys
from datetime import datetime
from pathlib import Path

try:
    ctx = json.load(sys.stdin)
    log = Path("/tmp/claude_tool_log.jsonl")
    entry = {
        "time": datetime.now().isoformat(),
        "tool": ctx.get("tool_name"),
        "success": "error" not in str(ctx.get("tool_result", "")).lower()
    }
    with open(log, "a") as f:
        f.write(json.dumps(entry) + "\n")
except Exception:
    pass
sys.exit(0)

Unified Pre/Post Hook

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

try:
    ctx = json.load(sys.stdin)
    tool_name = ctx.get("tool_name", "")

    if "tool_result" in ctx:
        # PostToolUse logic
        pass
    else:
        # PreToolUse logic
        pass
except Exception:
    pass
sys.exit(0)

Validation

Test hook before adding to settings:

echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' | python3 ~/.claude/hooks/my_hook.py

Verify syntax:

python3 -m py_compile ~/.claude/hooks/my_hook.py

Common Mistakes

Mistake	Fix
Wrong output format	Use hookSpecificOutput wrapper
Checking hook_type field	Check for tool_result instead
Using tool_response	Use tool_result
Exit code 1/2 on error	Always sys.exit(0)
Long timeouts	Keep under 5s, prefer 1s
Printing debug output	Only print JSON result
No exception handling	Wrap everything in try/except

Troubleshooting

Hook Not Triggered

# 1. Check hook is registered in settings.json
jq '.hooks' ~/.claude/settings.json

# 2. Verify matcher pattern matches tool
# "Bash" matches Bash tool, "Bash|Edit" matches both

# 3. Check hook is executable
ls -la ~/.claude/hooks/my_hook.py
chmod +x ~/.claude/hooks/my_hook.py

# 4. Test hook manually
echo '{"tool_name": "Bash", "tool_input": {"command": "ls"}}' | python3 ~/.claude/hooks/my_hook.py

Hook Not Producing Output

# 1. Verify JSON output format
echo '{"tool_name": "Bash", "tool_input": {"command": "rm -rf /"}}' | python3 ~/.claude/hooks/my_hook.py | jq .

# 2. Check for exceptions silently swallowed
# Add temporary logging:
import sys
sys.stderr.write(f"Debug: {variable}\n")

# 3. Verify hookSpecificOutput wrapper is present
# Must be: {"hookSpecificOutput": {...}}
# NOT: {"decision": ...} or {"permissionDecision": ...}

Hook Timing Out

# 1. Check current timeout in settings.json
jq '.hooks.PreToolUse[].hooks[].timeout' ~/.claude/settings.json

# 2. Profile hook execution time
time echo '{"tool_name": "Bash"}' | python3 ~/.claude/hooks/my_hook.py

# 3. Move slow operations to PostToolUse or async
# PreToolUse should complete in <100ms

Common Errors

Symptom	Cause	Fix
"Hook failed" in logs	Non-zero exit or exception	Add try/except, always exit(0)
No effect from hook	Wrong output format	Use hookSpecificOutput wrapper
Hook blocks everything	Matcher too broad	Use specific tool name
Permission denied	Script not executable	chmod +x hook.py
ModuleNotFoundError	Wrong Python env	Check shebang, use venv

Debugging Commands

# View hook execution logs
tail -100 ~/.claude/data/hook-events.jsonl | jq .

# Benchmark hook latency
~/.claude/scripts/diagnostics/hook-benchmark.sh my_hook.py

# Test all hooks
~/.claude/scripts/diagnostics/test-hooks.sh

# Check hook status
~/.claude/scripts/diagnostics/hook-cli.sh status my_hook

Related Skills

• skill-creator: Create skills that use hooks
• agent-creator: Create agents that complement hooks
• command-creator: Create commands that trigger hooks

When Blocked

If unable to create a working hook:

• Verify the hook event type exists
• Check if the use case is better suited for an agent
• Consider if a command/skill is more appropriate
• Simplify the logic to meet timeout constraints

Design Patterns

Do	Don't
Use dispatchers for PreToolUse/PostToolUse	Register hooks individually
Fail gracefully (hook_utils.py patterns)	Let errors crash
Target specific tools only	Watch all tools unnecessarily
Keep under 100ms latency	Block on slow operations
Log to hook-events.jsonl	Print to stdout