claude-code-hook-development

# Claude Code Hook Development

Create hooks that run shell commands on specific events to add guardrails, automations, and policy enforcement.

## Quick Reference

You MUST read the reference files for detailed schemas and examples:

- [Hook Events Reference](./references/hook-events.md) - All events with input/output schemas
- [Examples: Firewall](./references/examples/firewall.md) - Block dangerous commands
- [Examples: Quality Checks](./references/examples/quality-checks.md) - Lint/format after edits
- [Examples: Pre-Push Tests](./references/examples/pre-push-tests.md) - Run tests before git push

## Core Concepts

### Hook Types

1. **Command hooks** - Run bash scripts
2. **Prompt hooks** - Query LLM for context-aware decisions

### Exit Codes

| Code | Meaning | Behavior |
|------|---------|----------|
| 0 | Success | Action proceeds; stdout shown in verbose mode |
| 2 | Block | Action blocked; stderr fed to Claude |
| Other | Error | Non-blocking; stderr shown to user |

### File Locations

- Settings: `.claude/settings.json`
- Scripts: `.claude/hooks/` (mark executable)

## Settings Structure

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/my-script.sh",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
```

## Hook Events Summary

| Event | When | Can Block? |
|-------|------|------------|
| PreToolUse | Before tool executes | Yes (exit 2) |
| PostToolUse | After tool completes | Feedback only |
| PermissionRequest | User sees permission dialog | Yes |
| UserPromptSubmit | User submits prompt | Yes |
| Stop | Main agent finishes | Yes (continue) |
| SubagentStop | Subagent finishes | Yes (continue) |
| SessionStart | Session begins | Add context |
| SessionEnd | Session ends | Cleanup only |
| Notification | Notifications sent | No |
| PreCompact | Before compact | No |

## Common Matchers

For PreToolUse/PostT