This page is the canonical list of hook names, runtime event families, and externalized stream/control frames visible around tools, sessions, MCP, and agents. It keeps event lists out of broad narrative pages while preserving links to the implementation owners.
Scope and caveats
- Hook names are source-visible in the analyzed
cli.js bundle; exact input/output schemas are event-specific and may be extended by plugins or feature gates.
- This page distinguishes hooks from frames and protocol methods. They are all event-like, but they do not share one subscription mechanism.
- Treat
tengu_* strings as telemetry or feature-signal names unless adjacent code/doc text confirms a public event contract.
Source anchors
| Semantic alias | Source | Approximate location | String or symbol | Meaning |
|---|
| ToolHookEventList | cli.js | line ~185, byte 0x10b6b4 | PreToolUse | Hook event list begins. |
| SessionLifecycleHook | cli.js | line ~185, byte 0x10b73b | SessionEnd | Session lifecycle hook surface. |
| PreToolUseAuthorization | cli.js | line ~3553, byte 0x876552 | hookPermissionResult, PreToolUse | PreToolUse can participate in authorization and input mutation. |
| ToolExecutionBoundary | cli.js | line ~4202, byte 0x8a813a | function U85 | Permission/execution boundary that invokes tool decision paths. |
| SdkPermissionBridge | cli.js | line ~9564, byte 0xcc4a2a | createCanUseTool, permission_denied | SDK/bridge permission wrapper and denial frame. |
| SessionStateStreamFrame | cli.js | line ~2004, byte 0x518f8c | session_state_changed | Runtime/session state stream frame. |
| BridgeStateStreamFrame | cli.js | line ~19356, byte 0xdaf5aa | bridge_state | Remote bridge state stream frame. |
| McpToolsListMethod | cli.js | line ~95, byte 0x907a4 | tools/list | MCP method schema family. |
Hook names by family
| Family | Hook names | Trigger summary |
|---|
| Tool lifecycle | PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch | Before/after tool execution and tool batch completion. |
| Permission and elicitation | PermissionRequest, PermissionDenied, Elicitation, ElicitationResult | Permission prompts, denial feedback, and MCP-style elicitation completion. |
| Prompt/session lifecycle | UserPromptSubmit, UserPromptExpansion, SessionStart, SessionEnd, Setup | User input, context expansion, startup/setup, and shutdown. |
| Stop and compaction | Stop, StopFailure, PreCompact, PostCompact, InstructionsLoaded | Stop requests/failures, compaction boundaries, and instruction loading. |
| Agent/task lifecycle | SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle | Subagent/task start, completion, and background-agent idle state. |
| Config/worktree/file | ConfigChange, WorktreeCreate, WorktreeRemove, CwdChanged, FileChanged | Runtime configuration, working tree, CWD, and file-change boundaries. |
| Notification | Notification | External or internal notification delivery. |
Blocking versus observational hooks
| Hook type | Examples | Runtime effect |
|---|
| Authorization hooks | PreToolUse, PermissionRequest, PermissionDenied | Can affect whether a tool runs, whether approval is requested, whether retry feedback is returned, or whether input is updated. |
| Lifecycle hooks | SessionStart, SessionEnd, SubagentStart, SubagentStop, PreCompact, PostCompact | Run at major state transitions; may record or shape boundary behavior depending on event type. |
| Observational hooks | PostToolUse, PostToolUseFailure, PostToolBatch, TaskCompleted, Notification | Observe outcomes and emit side effects without being the primary approval gate. |
Externalized stream/control frames
These are not hook names. They are serialized frames used by headless, SDK, bridge, or remote consumers.
| Frame or subtype | Direction | Meaning |
|---|
session_state_changed | runtime → host/SDK | Session state changed, such as idle/running/requires-action. |
transcript_mirror | runtime → host/SDK/store | Local transcript record mirrored to an external consumer. |
bridge_state | runtime → remote host | Remote bridge connection/control state changed. |
control_request / control_response | runtime ↔ host | Request/response control-plane pair. |
permission_denied | runtime → host/SDK/model result surface | Tool was denied without an interactive approval path. |
can_use_tool | runtime → host | Ask-style permission control request. |
permission_response | host → runtime | Host reply to a permission/control decision. |
task_started, task_updated, task_progress, task_notification | runtime → host/model | Task/subagent state and progress frames. |
prompt_suggestion | runtime → host/SDK | Predicted next-prompt suggestion when enabled. |
rate_limit_event | provider/runtime → host/SDK | Rate-limit/quota state surfaced to clients. |
relevant_memories | memory subsystem → model/context | Memory recall output surfaced into a turn. |
elicitation_complete | MCP/runtime → host/SDK | MCP URL-mode elicitation completed. |
MCP protocol methods
These are JSON-RPC method names, not Claude Code hook events.
| Method family | Examples | Owner |
|---|
| Tools | tools/list, tools/call | MCP server/client runtime. |
| Resources | resources/list, resources/read, resources/templates/list | MCP resource runtime. |
| Prompts | prompts/list, prompts/get | MCP prompt runtime. |
| Tasks/cancel/progress | tasks/list, tasks/cancel, notifications/cancelled, progress notifications | MCP/task coordination. |
Interpretation rules
- Use hook for in-process extension points that can observe, block, mutate, or provide feedback.
- Use frame for serialized headless/SDK/remote messages.
- Use protocol method for MCP JSON-RPC method names.
- Use telemetry event for
tengu_* signal names; do not treat them as stable public hooks.
