create-hooks

<quick_start>

1. Choose hook event (when it fires) and hook type (command or prompt)
2. Create hooks config: .claude/hooks.json (project), ~/.claude/hooks.json (personal), or hooks/hooks.json (plugin)
3. Configure matcher pattern for which tools trigger the hook
4. Write hook command or prompt
5. Test with claude --debug </quick_start>

<essential_principles> Prompt-based hooks (recommended) use LLM reasoning for context-aware decisions. They handle complex logic, natural language validation, and edge cases without bash scripting.

Command hooks execute deterministic shell commands. Use them for fast checks, logging, file operations, external tool integrations, and notifications.

Choose prompt hooks unless you need: speed (command hooks are faster), determinism (exact same behavior every time), or external tool execution (formatters, linters). </essential_principles>

Event	When	Can Block?	Use For
PreToolUse	Before tool runs	Yes	Validation, modification, blocking
PostToolUse	After tool completes	No	Feedback, logging, formatting
UserPromptSubmit	User sends prompt	Yes	Context injection, prompt validation
Stop	Main agent stopping	Yes	Completeness verification
SubagentStop	Subagent stopping	Yes	Subagent task validation
SessionStart	Session begins	No	Context loading, env setup
SessionEnd	Session ends	No	Cleanup, state preservation
PreCompact	Before compaction	Yes	Preserve critical context
Notification	Claude needs input	No	Desktop notifications, alerts

See references/hook-types.md for detailed input/output schemas per event. </step_1_choose_event>

<step_2_configure_matcher> Matchers filter which tools trigger the hook:

"matcher": "Bash"                    // Exact match
"matcher": "Write|Edit"              // Multiple tools (regex OR)
"matcher": "Read|Write|Edit"         // All file operations
"matcher": "mcp__.*"                 // All MCP tools
"matcher": "mcp__plugin_asana_.*"    // Specific MCP server
"matcher": "mcp__.*__delete.*"       // All MCP delete tools
"matcher": "*"                       // Wildcard (all tools)

No matcher = fires for all tools. Matchers are case-sensitive and use regex syntax.

See references/matchers.md for comprehensive patterns. </step_2_configure_matcher>

<step_3_write_hook> Prompt hook (LLM-evaluated):

{
  "type": "prompt",
  "prompt": "Evaluate if this tool use is appropriate. Check for [criteria]. Return 'approve' or 'block' with reason.",
  "timeout": 30
}

Supported on: PreToolUse, Stop, SubagentStop, UserPromptSubmit

Command hook (shell execution):

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

Receives JSON via stdin, returns JSON via stdout.

Hook output for blocking events (PreToolUse):

{
  "hookSpecificOutput": {
    "permissionDecision": "allow|deny|ask",
    "updatedInput": {"field": "modified_value"}
  },
  "systemMessage": "Explanation for Claude"
}

Hook output for Stop/SubagentStop:

{
  "decision": "approve|block",
  "reason": "Explanation"
}

Exit codes: 0 = success (stdout in transcript), 2 = blocking error (stderr fed to Claude). </step_3_write_hook>

<step_4_assemble_config> Project/User hooks (.claude/hooks.json or ~/.claude/hooks.json):

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if this bash command is safe. Block destructive commands like rm -rf, git push --force, git reset --hard."
          }
        ]
      }
    ]
  }
}