manage-hooks

Protocol Overview

Hooks are event-driven automation for Claude Code. They execute shell commands or LLM prompts in response to:

• Tool Events: Before (PreToolUse) or after (PostToolUse) tool execution
• Session Events: SessionStart, SessionEnd, PreCompact
• User Events: UserPromptSubmit, PermissionRequest
• Agent Events: Stop, SubagentStart, SubagentStop
• System Events: Notification

Hooks operate within an event hierarchy: events trigger matchers (tool patterns) which execute hooks (commands or prompts). Hooks can block actions, modify tool inputs, inject context, or observe and log operations.

Available Resources

Workflows

Three workflows exist for hook lifecycle management:

• Create (workflows/create.md) - Creating new hooks from templates
• Edit (workflows/edit.md) - Modifying existing hook configurations
• Audit (workflows/audit.md) - Security validation and testing

Templates and Assets

Python Templates (assets/templates/)

• base-hook.py - Core template with path validation, error handling, and security patterns
• blocking-hook.py - Template for PreToolUse/Stop hooks that can approve/block actions
• observer-hook.py - Template for PostToolUse/SessionStart hooks that observe/report
• hooks-json.md - Complete guide to hooks.json configuration structure

Utilities (assets/scripts/)

• path-validator.py - Reusable utility for validating file paths and preventing traversal attacks
• hook-tester.py - Automated validation tool supporting all 11 hook event types

Usage: Import or copy these into .claude/hooks/scripts/ for use in hook configurations.

Example: File Protection Hook

.claude/hooks/
├── hooks.json              # Hook configuration
└── scripts/
    └── protect-files.py    # Hook script

Configuration:

{
  "description": "File protection and security checks",
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/.claude/hooks/scripts/protect-files.py"
          }
        ]
      }
    ]
  }
}

Hook Event Types

Supported Events (11 total)

Event	Fires	Can Block?	Matcher Required?
PreToolUse	Before tool execution	Yes	Yes
PostToolUse	After tool execution	No	Yes
UserPromptSubmit	User submits a prompt	Yes	No
PermissionRequest	Permission dialog shown	Yes	No
Stop	Claude attempts to stop	Yes	No
SubagentStart	Subagent starts	No	No
SubagentStop	Subagent attempts to stop	Yes	No
SessionStart	Session begins	No	No
SessionEnd	Session ends	No	No
PreCompact	Before context compaction	Yes	No
Notification	Claude sends notifications	No	No

See references/hook-types.md for complete event documentation including input/output schemas and use cases.

Hook Types

Command Hook

Type: Executes a shell command

Configuration:

{
  "type": "command",
  "command": "/path/to/script.sh",
  "timeout": 30000
}

Use cases: Simple validation, logging, external tools, notifications

Input: JSON via stdin Output: JSON via stdout (optional)

Prompt Hook

Type: LLM evaluates a prompt

Configuration:

{
  "type": "prompt",
  "prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
}

Use cases: Complex decision logic, natural language validation, context-aware checks, reasoning

Input: Prompt with $ARGUMENTS placeholder Output: JSON with decision and reason

Matchers

Matchers filter which tools trigger the hook:

{
  "matcher": "Bash",             // Exact match
  "matcher": "Write|Edit",      // Multiple tools (regex OR)
  "matcher": "mcp__.*",         // All MCP tools
  "matcher": "mcp__memory__.*"   // Specific MCP server
}

Optional for: UserPromptSubmit, PermissionRequest, Stop, SubagentStart, SubagentStop, SessionStart, SessionEnd, PreCompact, Notification

Input/Output Protocol

Input Format: JSON via stdin

{
  "session_id": "string",
  "transcript_path": "path",
  "cwd": "path",
  "permission_mode": "default|plan|acceptEdits|dontAsk|bypassPermissions",
  "hook_event_name": "EventName",
  "event_specific_data": "varies"
}

Output Format: JSON via stdout (blocking hooks)

{
  "decision": "approve" | "block",
  "reason": "explanation",
  "continue": true,
  "systemMessage": "warning"
}

See references/input-output-schemas.md for complete schemas per event type.

Environment Variables

Available in hook commands:

• $CLAUDE_PROJECT_DIR - Project root directory
• ${CLAUDE_PLUGIN_ROOT} - Plugin directory (plugin hooks only)
• $ARGUMENTS - Hook input JSON (prompt hooks only)

Pattern Catalog

Desktop Notification

{
  "hooks": {
    "Notification": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

Block Destructive Commands

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
          }
        ]
      }
    ]
  }
}

Auto-format Code

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write $CLAUDE_PROJECT_DIR",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

Session Context Injection

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
          }
        ]
      }
    ]
  }
}

Debug Protocol

Command: claude --debug

Shows hook execution details, command output, and matching information.

Reference Documentation

Hook Types: references/hook-types.md

• Complete list of hook events
• When each event fires
• Input/output schemas for each event
• Blocking vs non-blocking behavior

Command vs Prompt: references/command-vs-prompt.md

• Decision tree: which type to use
• Command hook patterns and examples
• Prompt hook patterns and examples
• Performance considerations

Matchers: references/matchers.md

• Regex patterns for tool matching
• MCP tool matching patterns
• Multiple tool matching
• Debugging matcher issues

Input/Output Schemas: references/input-output-schemas.md

• Complete schema for each hook type
• Field descriptions and types
• Hook-specific output fields
• Example JSON for each event

Working Examples: references/examples.md

• Desktop notifications
• Command validation
• Auto-formatting workflows
• Logging and audit trails
• Stop logic patterns
• Session context injection

Hook Examples Reference: references/hook-examples.md

• Complete hooks.json structure guide
• File protection hook example
• Hook script patterns and best practices
• Template usage examples

Troubleshooting: references/troubleshooting.md

• Hooks not triggering
• Command execution failures
• Prompt hook issues
• Permission problems
• Timeout handling
• Debug workflow