hooks-reference

Hooks Reference Skill

This skill provides comprehensive guidance for implementing Claude Code hooks - event handlers that automate validation, context loading, and workflow enforcement.

Hook Events Overview

Event	When Triggered	Use Cases
PreToolUse	Before tool executes	Validate, block, modify
PostToolUse	After tool completes	Audit, react, verify
PermissionRequest	Permission dialog shown	Auto-allow, auto-deny
Stop	Claude finishes	Force continue, verify
SubagentStop	Subagent finishes	Verify task complete
SessionStart	Session begins	Load context, setup
SessionEnd	Session ends	Cleanup, save state
UserPromptSubmit	Prompt submitted	Validate, add context
PreCompact	Before compaction	Preserve info
Notification	Notification sent	Alert, log

hooks.json Structure

Basic structure:

{
  "description": "What these hooks do",
  "hooks": {
    "EventName": [
      {
        "matcher": "Pattern",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/handler.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Matcher Patterns

For tool events (PreToolUse, PostToolUse, PermissionRequest):

• "Write" - Match exact tool name
• "Write|Edit" - Match multiple tools (regex)
• "Notebook.*" - Regex pattern
• "*" or "" - Match all tools

For SessionStart:

• "startup" - Initial startup
• "resume" - From --resume, --continue, /resume
• "clear" - From /clear
• "compact" - From auto/manual compact

For Notification:

• "permission_prompt" - Permission requests
• "idle_prompt" - Claude waiting for input

Hook Types

Command Hooks (type: "command")

Execute a bash script:

{
  "type": "command",
  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
  "timeout": 30
}

Prompt Hooks (type: "prompt")

LLM-based evaluation (Stop, SubagentStop only):

{
  "type": "prompt",
  "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete.",
  "timeout": 30
}