hooks-reference

# Claude Code Hooks Reference

Hooks are user-defined shell commands that execute at various points in Claude Code's lifecycle, providing deterministic control over behavior.

## Quick Reference: Hook Events

| Event | When | Input | Can Control |
|-------|------|-------|-------------|
| `PreToolUse` | Before tool runs | Tool name, inputs | Block/modify tool |
| `PostToolUse` | After tool succeeds | Tool name, result | Feedback to Claude |
| `PostToolUseFailure` | After tool fails | Tool name, error | Error handling |
| `PermissionRequest` | Permission dialog shown | Details | Allow/deny |
| `UserPromptSubmit` | User submits prompt | User input | Modify prompt |
| `Notification` | Notification sent | Message | Custom notifications |
| `Stop` | Claude stops | Reason | Continue/stop |
| `SubagentStop` | Subagent completes | Result | Subagent behavior |
| `PreCompact` | Before compaction | Context | Modify context |
| `SessionStart` | Session begins | Session info | Env setup |
| `SessionEnd` | Session ends | Stats | Cleanup |

## Hook Configuration Location

```
~/.claude/settings.json          # User-level (all projects)
.claude/settings.json            # Project-level (team shared)
.claude/settings.local.json      # Project-local (gitignored)
```

## Basic Hook Structure

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "your-script.sh"
          }
        ]
      }
    ]
  }
}
```

## Matcher Patterns

| Pattern | Matches |
|---------|---------|
| `*` | All tools |
| `Bash` | Bash tool only |
| `Write\|Edit` | Write or Edit tools |
| `Read.*` | Read and any Read variants |

## Hook Types

### Command Hook
```json
{
  "type": "command",
  "command": "jq '.tool_input' >> /tmp/log.txt"
}
```

### Prompt Hook
```json
{
  "type": "prompt",
  "prompt": "Review the output: $ARGUMENTS"
}
```

### Agent Hook
```json
{
  "type": "agent",
  "prompt": "Verify the c