# Claude Code Hooks

> Claude Code hooks system -- PreToolUse, PostToolUse, Stop, SessionStart, prompt hooks, command hooks, matchers, and production patterns for automation.

- Skill: `leolin990405/claude-code-hooks` (Agent Skill)
- Install (CLI): `npx get-skill add leolin990405/claude-code-hooks`
- Raw SKILL.md: https://api.skillmd.com/api/skills/leolin990405/claude-code-hooks/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: LeoLin990405 (https://skillmd.com/u/leolin990405)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/leolin990405/claude-code-hooks

---


# Claude Code Hooks

## Hook Events

| Event | Fires When | Can Control |
|-------|-----------|-------------|
| **PreToolUse** | Before tool execution | Allow/deny/modify tool calls |
| **PostToolUse** | After tool execution | Provide feedback to Claude |
| **PermissionRequest** | Permission dialog shown | Allow/deny |
| **UserPromptSubmit** | User submits prompt | Modify/block prompt |
| **Notification** | Claude sends notification | Custom handling |
| **Stop** | Claude finishes responding | Force continuation |
| **SubagentStop** | Subagent completes | Force continuation |
| **PreCompact** | Before compaction | Preserve info |
| **SessionStart** | Session begins | Load context, set env |
| **SessionEnd** | Session ends | Cleanup, logging |

## Hook Types

### Command Hook (deterministic)
```json
{"type": "command", "command": "bash /path/to/script.sh", "timeout": 60}
```

### Prompt Hook (LLM-driven)
```json
{"type": "prompt", "prompt": "Evaluate safety of: $TOOL_INPUT", "timeout": 30}
```

## Configuration (settings.json)

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "bash audit-command.sh"}]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{"type": "command", "command": "npx prettier --write $FILE_PATH"}]
      }
    ],
    "Stop": [
      {
        "matcher": "*",
        "hooks": [{"type": "prompt", "prompt": "Verify all requirements are met before stopping."}]
      }
    ],
    "SessionStart": [
      {
        "matcher": "*",
        "hooks": [{"type": "command", "command": "bash load-env.sh"}]
      }
    ]
  }
}
```

## Matchers

| Pattern | Matches |
|---------|---------|
| `"Write"` | Exact tool name |
| `"Read\|Write\|Edit"` | OR matching |
| `"*"` | All tools |
| `"mcp__.*"` | Regex for MCP tools |
| `"mcp__.*__delete.*"` | Regex with specificity |

Case-sensitive. First matching hook wins.

## Hook Input (JSON via stdin)

**Common fields**: `session_id`, `transcript_path`, `cwd`, `permission_mode`, `hook_event_name`

**PreToolUse/PostToolUse**: + `tool_name`, `tool_input`, `tool_result`

**UserPromptSubmit**: + `user_prompt`

**Stop/SubagentStop**: + `reason`

## Hook Output

### PreToolUse
```json
{
  "hookSpecificOutput": {
    "permissionDecision": "allow",
    "updatedInput": {"command": "sanitized-command"}
  },
  "systemMessage": "Command was sanitized for safety."
}
```

Decisions: `"allow"`, `"deny"`, `"ask"`

### Stop
```json
{
  "decision": "block",
  "reason": "Tests not yet run",
  "systemMessage": "Please run the test suite before completing."
}
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | Success (stdout added to transcript) |
| 1 | Non-blocking error (logged, continues) |
| 2 | Blocking error (stderr fed to Claude) |

## Environment Variables

`$CLAUDE_PROJECT_DIR`, `$CLAUDE_PLUGIN_ROOT`, `$CLAUDE_ENV_FILE` (SessionStart only)

## Production Patterns

### Auto-Format on Save
```json
{
  "PostToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{"type": "command", "command": "npx prettier --write \"$TOOL_INPUT_FILE_PATH\""}]
  }]
}
```

### File Protection
```json
{
  "PreToolUse": [{
    "matcher": "Edit|Write",
    "hooks": [{"type": "command", "command": "bash check-protected.sh"}]
  }]
}
```

### Audit Logging
```json
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [{"type": "command", "command": "echo \"$(date) $TOOL_INPUT\" >> ~/.claude/audit.log"}]
  }]
}
```

### Session Context Loading
```json
{
  "SessionStart": [{
    "matcher": "*",
    "hooks": [{"type": "command", "command": "echo 'export PROJECT_ENV=production' >> \"$CLAUDE_ENV_FILE\""}]
  }]
}
```

### Multi-Stage Validation
Combine command hook (fast check) + prompt hook (deep analysis):
```json
{
  "PreToolUse": [{
    "matcher": "Bash",
    "hooks": [
      {"type": "command", "command": "bash quick-check.sh", "timeout": 5},
      {"type": "prompt", "prompt": "Is this command safe? $TOOL_INPUT", "timeout": 30}
    ]
  }]
}
```

## Sources

- [Hooks Guide](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/hooks)
- [Hooks Reference](https://code.claude.com/docs/en/hooks)

