adding-hooks

# Claude Code Hooks Configuration

## Quick Start

**First, ask the user where to add hooks**:
- `~/.claude/settings.json` - User-scoped (personal, all projects)
- `.claude/settings.json` - Project-scoped (shared via git)
- `.claude/settings.local.json` - Local project (not committed)
- Plugin `hooks/hooks.json` - Plugin-bundled hooks

## Basic Structure

```json
{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here",
            "timeout": 60
          }
        ]
      }
    ]
  }
}
```

## Hook Events

| Event | When | Common Use |
|-------|------|------------|
| `PreToolUse` | Before tool execution | Validation, blocking |
| `PostToolUse` | After tool completion | Formatting, logging |
| `PermissionRequest` | Permission dialog shown | Auto-approve/deny |
| `UserPromptSubmit` | User sends prompt | Context injection |
| `Stop` | Agent finishes | Task completion check |
| `SubagentStop` | Subagent finishes | Subagent validation |
| `SessionStart` | Session begins | Environment setup |
| `SessionEnd` | Session ends | Cleanup tasks |
| `Notification` | Notification sent | Alerts |
| `PreCompact` | Before compact | Custom summarization |

See [events.md](references/events.md) for detailed event documentation.

## Matchers

**For PreToolUse, PostToolUse, PermissionRequest**:
- Exact match: `"Write"` - matches Write tool only
- Regex: `"Edit|Write"` - matches Edit or Write
- All tools: `"*"` or `""` or omit matcher
- MCP tools: `"mcp__server__tool"` pattern

**Case-sensitive**: `Write` ≠ `write`

## Hook Types

### Command Hooks

```json
{
  "type": "command",
  "command": "\"$CLAUDE_PROJECT_DIR\"/scripts/check.sh",
  "timeout": 30
}
```

### Prompt Hooks (LLM evaluation)

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

Supported for: `Stop`, `SubagentSto