Kjell Tore Guttormsen
624f5edabc
The knowledge base was frozen at ~v2.1.111, describing an Opus-4.7 world after CC shipped Opus 4.8 and Fable 5. Refreshed three agent-facing knowledge files; every fact re-verified against the official changelog (~/.claude/cache/changelog.md, CC 2.1.181) on 2026-06-18. - feature-evolution.md: new Opus-4.8-era rows above the v2.1.111 freeze -- Opus 4.8 default + /effort xhigh (2.1.154), Fable 5 Mythos-class (2.1.170), post-session hook (2.1.169), MessageDisplay (2.1.152), /simplify -> /code-review (2.1.147), /config key=value (2.1.181). - hook-events-reference.md: 26 -> 28 events (+MessageDisplay, +post-session); documented Stop/SubagentStop additionalContext output field. - claude-code-capabilities.md: 2026-06 model/effort lineup table; bundled skills /simplify -> /code-review; documented /config key=value. - cc-2.1.x-changelog-delta.md: marked SUPERSEDED by the gap-matrix. Verification caught two version errors in STATE/matrix, corrected to the changelog: - Stop/SubagentStop additionalContext is 2.1.163, not 2.1.165 (2.1.165 was "Bug fixes" only; matrix row 109 already said 2.1.163). - settings `agent` field introduced 2.0.59; 2.1.157 = honored for dispatched `claude agents` sessions, not the introduction. New tests/knowledge/knowledge-staleness.test.mjs (8 tests) encodes the verified facts as a re-freeze guard (RED before edits, GREEN after). Full suite: 850/850 green (+8). self-audit PASS, A(100)/A(97).
124 lines
8.3 KiB
Markdown
124 lines
8.3 KiB
Markdown
# Hook Events Reference
|
||
|
||
> All 28 hook events as of June 2026. Source: code.claude.com/docs/en/hooks.md
|
||
> Verified 2026-04-19 against research/03-claude-code-changes-config-surfaces.md — no new hook events introduced in v2.1.83–v2.1.111. Sandbox + managed-only flags (2026-04) operate at the settings layer, not as new hook events.
|
||
> Re-verified 2026-06-18 against the official changelog (window v2.1.114–v2.1.181): added `MessageDisplay` (v2.1.152) and `post-session` (v2.1.169), bringing the count from 26 to 28.
|
||
|
||
---
|
||
|
||
## Event Table
|
||
|
||
| Event | Trigger | Blocking? | Matcher Support | Common Use Cases |
|
||
|-------|---------|-----------|-----------------|------------------|
|
||
| `SessionStart` | Session begins or resumes | No | `startup`, `resume`, `clear`, `compact` | Inject git branch/env into context; show session state; load external context |
|
||
| `InstructionsLoaded` | CLAUDE.md / .claude/rules files are loaded | No | `session_start`, `nested_traversal`, `path_glob_match`, `include`, `compact` | Debug which instruction files loaded; log instruction sources; validate rule sets |
|
||
| `UserPromptSubmit` | User submits a prompt | Yes | No matcher | Validate prompt length; inject context; block disallowed prompt patterns; add mandatory context |
|
||
| `PreToolUse` | Before any tool executes | Yes | Tool name (e.g., `Bash`, `Write`, `mcp__.*`) | Security validation; confirm destructive ops; log tool calls; rate limiting |
|
||
| `PermissionRequest` | Permission dialog appears | Yes | Tool name | Auto-approve known-safe patterns; add approval context; integrate with approval workflows |
|
||
| `PermissionDenied` | Auto mode denies a tool call | No (info only) | Tool name | Log denied operations; alert on unexpected denials; track permission patterns |
|
||
| `PostToolUse` | Tool completes successfully | No | Tool name | Auto-format after Write/Edit; run linting; update docs; log completions |
|
||
| `PostToolUseFailure` | Tool ends in error | No | Tool name | Log failures; send alerts; trigger retry logic; update error tracking |
|
||
| `SubagentStart` | Subagent is spawned | No | Agent type (name) | Log agent invocations; inject agent-specific context; record spawn times |
|
||
| `SubagentStop` | Subagent finishes | Yes | Agent type (name) | Quality gates (exit 2 to reject); validate agent output; run post-agent checks |
|
||
| `TaskCreated` | A task is created in the task list | Yes | No matcher | Validate task format; enforce naming conventions; block disallowed task types |
|
||
| `TaskCompleted` | A task is marked complete | Yes | No matcher | Verify completion criteria; run acceptance checks; require sign-off |
|
||
| `Stop` | Claude finishes a response turn | Yes | No matcher | Session summaries; commit prompts; send desktop notifications; log turn metadata |
|
||
| `StopFailure` | Turn ends in an API error | No | Error type | Alert on API errors; retry logic; log error context |
|
||
| `TeammateIdle` | An agent team member has no tasks | Yes | No matcher | Assign next task (exit 2 to keep working); log team status; rebalance work |
|
||
| `Notification` | A notification is sent (permission prompt, idle, auth) | No | `permission_prompt`, `idle_prompt`, `auth_success`, `elicitation_dialog` | Desktop notifications; Slack/webhook alerts; mobile push; audio cues |
|
||
| `MessageDisplay` | Assistant message text is about to be displayed (v2.1.152) | Yes (transforms) | No matcher | Transform or hide assistant output before it reaches the terminal — redact secrets, rewrite text |
|
||
| `ConfigChange` | A config file changes on disk | Yes | `user_settings`, `project_settings`, `local_settings`, `policy_settings`, `skills` | Validate config changes; block invalid edits; reload dependent processes |
|
||
| `CwdChanged` | Working directory changes | No | No matcher | Inject new directory context; update env vars via `$CLAUDE_ENV_FILE`; log navigation |
|
||
| `FileChanged` | A watched file changes | No | Filename pattern | Auto-reload when config changes; trigger builds on source change; sync state |
|
||
| `WorktreeCreate` | A git worktree is being created | Yes (path return) | No matcher | Custom worktree path via stdout; non-git VCS support; worktree naming conventions |
|
||
| `WorktreeRemove` | A git worktree is removed | No | No matcher | Cleanup resources; log worktree lifecycle; update team state |
|
||
| `PreCompact` | Before context compaction | No | `manual`, `auto` | Save current state; checkpoint important context; log pre-compact state |
|
||
| `PostCompact` | After context compaction | No | `manual`, `auto` | Reinject critical context; validate compaction; log post-compact state |
|
||
| `Elicitation` | An MCP server requests user input | Yes | MCP server name | Control which servers can request input; log elicitations; pre-fill responses |
|
||
| `ElicitationResult` | User responds to MCP elicitation | Yes | MCP server name | Validate responses; log user input; transform before sending to MCP |
|
||
| `SessionEnd` | Session terminates | No | `clear`, `resume`, `logout`, `prompt_input_exit`, `other` | Final session summary; save state; cleanup temp files; send end-of-session report |
|
||
| `post-session` | Session has ended, before the workspace is deleted (v2.1.169) | No | No matcher | Snapshot uncommitted work; export logs; cleanup (self-hosted runner). Kebab-case, distinct from `SessionEnd`. |
|
||
|
||
---
|
||
|
||
## Hook Handler Types
|
||
|
||
| Type | Description | Use When |
|
||
|------|-------------|----------|
|
||
| `command` | Shell command (bash/powershell) | Fast scripts, file checks, security validation |
|
||
| `http` | HTTP POST to endpoint | Remote logging, webhooks, approval systems |
|
||
| `prompt` | LLM evaluation (yes/no decision) | Semantic validation that needs language understanding |
|
||
| `agent` | Full subagent with tools | Complex validation requiring file reads or multi-step logic |
|
||
|
||
---
|
||
|
||
## Handler Configuration Fields
|
||
|
||
| Field | Type | Description |
|
||
|-------|------|-------------|
|
||
| `type` | string | `command`, `http`, `prompt`, `agent` |
|
||
| `command` | string | Shell command (type: command only) |
|
||
| `url` | string | HTTP endpoint (type: http only) |
|
||
| `prompt` | string | LLM prompt (type: prompt only) |
|
||
| `if` | string | Conditional expression — only fires when true (e.g., `Bash(rm *)`) |
|
||
| `timeout` | number | Milliseconds before hook is killed (default: varies) |
|
||
| `statusMessage` | string | Message shown in UI while hook runs |
|
||
| `async` | bool | `true` = fire and forget, don't wait for result |
|
||
| `shell` | string | `"bash"` or `"powershell"` |
|
||
|
||
---
|
||
|
||
## Exit Code Semantics
|
||
|
||
| Exit Code | Blocking Event | Non-Blocking Event |
|
||
|-----------|---------------|---------------------|
|
||
| `0` | Proceed; JSON on stdout is parsed | Success; JSON on stdout parsed |
|
||
| `2` | **Block** — stderr shown to Claude as error | Non-blocking; treated as informational |
|
||
| other | Non-blocking; stderr in verbose log only | Non-blocking; stderr in verbose log only |
|
||
|
||
---
|
||
|
||
## Blocking Event Output Fields
|
||
|
||
**PreToolUse** (exit 0):
|
||
- `permissionDecision`: `"allow"` / `"deny"` / `"ask"` / `"defer"`
|
||
- `updatedInput`: modified tool input
|
||
- `additionalContext`: string appended to Claude's context
|
||
|
||
**PermissionRequest** (exit 0):
|
||
- `decision.behavior`: `"allow"` / `"deny"`
|
||
- `updatedInput`: modified input
|
||
- `updatedPermissions`: modified permission set
|
||
|
||
**WorktreeCreate** (exit 0):
|
||
- stdout: path string OR `hookSpecificOutput.worktreePath`
|
||
|
||
**SessionStart** (exit 0):
|
||
- `additionalContext`: string injected into context
|
||
- Or: write env vars to `$CLAUDE_ENV_FILE`
|
||
|
||
**Stop / SubagentStop** (exit 0, since v2.1.163):
|
||
- `hookSpecificOutput.additionalContext`: feedback string that keeps the turn going without being treated as a hook error
|
||
|
||
---
|
||
|
||
## Environment Variables Available in Hooks
|
||
|
||
| Variable | Available In | Description |
|
||
|----------|-------------|-------------|
|
||
| `$CLAUDE_PROJECT_DIR` | All hooks | Absolute path to project root |
|
||
| `${CLAUDE_PLUGIN_ROOT}` | Plugin hooks | Plugin installation directory |
|
||
| `${CLAUDE_PLUGIN_DATA}` | Plugin hooks | Plugin persistent data directory |
|
||
| `$CLAUDE_ENV_FILE` | SessionStart, CwdChanged, FileChanged | Path to write env var exports |
|
||
| `$CLAUDE_CODE_REMOTE` | All hooks | `"true"` when running in web sessions |
|
||
|
||
---
|
||
|
||
## MCP Tool Matcher Patterns
|
||
|
||
| Pattern | Matches |
|
||
|---------|---------|
|
||
| `mcp__memory__.*` | All tools from the `memory` server |
|
||
| `mcp__.*__write.*` | Any tool named `write*` from any server |
|
||
| `mcp__filesystem__read_file` | Specific tool on specific server |
|
||
| `mcp__.*` | All MCP tools from all servers |
|