Hook Patterns

Production-tested patterns for Claude Code hooks (1.0.40+).

Hook Roles (Beyond Just Validation)

Event Reference

Exit Codes

JSON Response (Advanced)

{
  "decision": "approve|block",
  "reason": "Shown to user/Claude",
  "continue": true,
  "suppressOutput": false
}

Quick Registration

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "script.sh", "timeout": 5 }]
    }]
  }
}

Pattern Selection

Orchestration Patterns (NEW)

Hook-based skill/agent activation with reliability stats:

See orchestration-templates.md for templates.

Debugging

Common issues and solutions in debugging-guide.md.

Quick checklist:

• Hook executable? (chmod +x)
• Using INPUT=$(cat) to read stdin?
• Using exit 2 for blocking (not exit 1)?
• Debug to stderr (>&2), output to stdout?
• New session after settings.json change?

Common Mistakes

• Missing nested hooks array
• Missing "type": "command"
• Using exit 1 instead of exit 2 for blocking
• Object matcher (not supported) - use script parsing instead