ADR-705: Claude Code's tool surface and hook events, surveyed as tool types for trigger lanes and session sensing¶
What this record is¶
A survey taken on 2026-10-22 of the tools Claude Code offers the model and the hook events it sends, read for two uses: which tool calls ways could trigger on, and which session events an attend sensor could observe. It decides nothing. ADR-188, ADR-706 and ADR-415 cite it.
Sources:
- the installed Claude Code 2.1.308 binary, read with
strings; - the tool-input declarations Claude Code writes beside a loaded mod,
BuiltinToolInputsinclaude-code-tools/index.d.tsunder the plugin cache, 73 tools, written 2026-10-20; - the hook payload declarations in the sibling
claude-code/index.d.ts, written by 2.1.304 (theHookInputunion, andBaseHookInput); - the hooks and permissions references at code.claude.com/docs/en/hooks and code.claude.com/docs/en/permissions.
A statement marked inferred was not read directly from one of these.
Where tools come from¶
| Source | Names | Notes |
|---|---|---|
| Built-in | a canonical name such as Bash or Agent |
73 in this build's declarations. The binary names more, among them Glob, Grep, PowerShell, SubagentHandback, a structured-output tool and nine self_hosted_runner_* tools. |
| Deferred built-ins | the same names | 46 tool definitions in the binary are deferred: the model loads their schema through ToolSearch. Hooks key on the call, so deferral does not change which hooks fire (inferred). |
| MCP servers | mcp__<server>__<tool>; plugin servers mcp__plugin_<plugin>_<server>__<tool>; claude.ai connectors mcp__claude_ai_<server>__<tool> |
Arguments follow each server's own schema. No argument field is common to all of them. |
| Mod-registered tools | MCP names, such as mcp__attend__attend_send |
They fall in the MCP class and need the mods preview flag, which is off by default. |
Some tools exist only under a mode, role, surface or platform: ExitPlanMode in plan mode, SubagentHandback in a subagent (inferred), team tools in a team, claude.ai and Cowork tools on those surfaces, PowerShell on Windows. Glob and Grep are named in the binary but absent from this build's tool set; search runs through Bash on this install (inferred). Neither plan-mode tool is offered under claude -p.
Legacy names. Matchers and permission rules resolve old names through a legacyToolNames table in the binary: Task to Agent, KillShell and KillBash to TaskStop, ListPeers to ListAgents, Brief to SendUserMessage, and others. A shipped matcher naming Task therefore still reaches Agent. Payloads carry the canonical name (inferred).
Claude Code already groups its tools¶
Permission rules are written Tool or Tool(specifier), and the specifier targets one primary field per tool: command for Bash and PowerShell, file_path for Read, Edit and Write, path for Grep and Glob, notebook_path for NotebookEdit, and the URL's domain for WebFetch. Rules also group tools into families: an Edit rule covers every file-editing tool, and a Read rule covers Grep and Glob on a best-effort basis. The hook if field uses the same syntax on the five tool events and is evaluated before the hook process is spawned. A settings file rejects an mcp__ rule with a parenthesised specifier.
Grouping the tool set along those families gives these types. Value is rated H (high), M (medium), L (low) or N (noise), for ways and for attend.
| Type | Tools | Primary field | Ways | attend |
|---|---|---|---|---|
| shell | Bash, PowerShell | command |
H: 23 way files carry commands: (on main at 7fd6c0de) |
L; a finished background shell is M, seen through Stop |
| file-modify | Edit, Write, NotebookEdit, MultiEdit (legacy) | file_path, notebook_path |
H: 30 way files carry files: (on main at 7fd6c0de); NotebookEdit is not wired |
N; the git sensor covers it |
| file-read | Read, Glob, Grep, LSP | file_path, path, filePath (LSP is camelCase) |
M; the most frequent tool, so the spawn cost is highest | N |
| web | WebFetch, WebSearch | url; WebSearch has query and no URL |
M: the moment untrusted content enters | N |
| delegation | Agent, Workflow | subagent_type; Workflow name |
H: the task lane exists | H: subagent and workflow start and finish |
| plan/mode | EnterPlanMode, ExitPlanMode, ProposeGoal, EnterWorktree, ExitWorktree | none useful; the tool name | H at ExitPlanMode, after approval | H: plan approved, goal set, worktree entered |
| task/state | TaskCreate, TaskUpdate, TaskGet, TaskList, TaskStop, TodoWrite | subject, status |
M | M; the TaskCreated and TaskCompleted events carry the same state with less noise |
| scheduling | CronCreate and its siblings, ScheduleWakeup, Monitor, RemoteTrigger | the tool name; Monitor also takes a command |
M | H: the session will wake on its own |
| messaging | SendMessage, ListAgents, SendUserMessage, PushNotification, mcp__attend__* |
to |
L | M |
| user-interaction | AskUserQuestion, EndConversation | the tool name | M | H: the agent is waiting on its human |
| skill | Skill | skill (the skill's name) |
H: the operator works through skills; a typed /name takes another route (below) |
L |
| extension | ToolSearch, the plugin and connector search tools | query |
N | L |
| publish | Artifact and its siblings, PublishPlugin, SendFeedback | action, url |
H: an outward step | M |
| memory | memory_list, memory_read, memory_write | path |
M | L |
| MCP (class) | mcp__<server>__<tool> |
the name; no common argument field | H per server, such as a mail or chat server's send posture | M: an audit of external writes |
| output, runner ops | ReportFindings, structured output, self_hosted_runner_* |
none | N | N |
The current ways lanes on this grid¶
| Lane | Type and field | Event | Adapter |
|---|---|---|---|
commands: |
shell, command; Bash only |
PreToolUse | check-bash-pre.sh, ways hook command |
files: |
file-modify, file_path; Edit and Write, NotebookEdit missed |
PreToolUse | check-file-pre.sh, ways hook file |
| postcheck | Edit, Write, Bash, Task; any predicate over the payload | PostToolUse, PostToolUseFailure | check-post.sh, ways hook post-tool |
| task lane | delegation; semantic match on the prompt | PreToolUse on Task, delivered at SubagentStart | check-task-pre.sh |
tool_name: (ADR-704, on main) |
the wired tools (EnterPlanMode, ExitPlanMode, Workflow); the name only | the events a way's tool_event: lists; PreToolUse and PostToolUse are wired |
check-tool.sh, ways hook tool |
commands: and files: each name one type and match a regex against that type's primary field. The tool_name: lane matches the name alone. Its scan mirrors the file lane's hit loop (ADR-704 item 2).
Hook events beyond tool calls¶
Every event carries session_id, transcript_path, cwd, permission_mode, effort, and agent_id with agent_type inside a subagent. Comparing permission_mode across consecutive events recovers a plan-mode switch made with Shift+Tab, which fires no hook (inferred, not probed).
| Event and key fields | Known gaps | Ways | attend |
|---|---|---|---|
| PermissionRequest (tool_name, tool_input) | none known | L | H: waiting on approval |
| PermissionDenied (tool_name, reason) | auto mode only | M | M |
| SubagentStart, SubagentStop (agent_id, agent_type, agent_transcript_path, last_assistant_message) | none known | SubagentStart wired | H |
| Stop (last_assistant_message, background_tasks with id, type, status and name; session_crons) | not on a user interrupt | wired | H: comparing background_tasks between Stops shows workflows, shells and monitors finishing |
| StopFailure (error, error_details) | none known | L | H |
| TaskCreated, TaskCompleted, TeammateIdle | none known | TaskCreated wired | H |
| PreCompact, PostCompact (trigger, compact_summary) | none known | M | H: the context sensor's ground truth |
| PreModelSwitch, PostModelSwitch (from_model, to_model, source, context_tokens) | 30 s timeout | M | H: the window size changed |
| SessionStart (source), SessionEnd (reason) | SessionEnd shares a 1.5 s budget | SessionStart wired | M |
| UserPromptSubmit (prompt, source) | none known | wired | L |
| UserPromptExpansion (expansion_type, command_name, command_args, command_source, prompt) | fires for a typed command only (below) | not wired | L |
| Notification (notification_type: permission_prompt, idle_prompt) | none known | L | H |
| CwdChanged, WorktreeCreate, WorktreeRemove | none known | L | M |
| ConfigChange, InstructionsLoaded, FileChanged | InstructionsLoaded skips direct AGENTS.md reads | M (#493) | L |
| MessageDisplay, PostToolBatch, DirectoryAdded, Setup, Elicitation | MessageDisplay fires on every streamed chunk; PostToolBatch on every step | N | N |
Two routes into a skill¶
A skill reaches the model by one of two routes, and they fire different hooks.
- The model calls the Skill tool. The input is
{ skill, args? }(BuiltinToolInputs.Skill, read). PreToolUse and PostToolUse fire withtool_name: Skilllike any tool call (hooks reference, read). - The operator types
/name. No tool call is made. The hooks reference says so directly: a PreToolUse hook matching the Skill tool fires only when Claude calls the tool, typing/skillnamebypasses PreToolUse, and UserPromptExpansion fires on that direct path (read). Its payload carriesexpansion_type(slash_commandfor skills and custom commands,mcp_promptfor MCP prompts),command_name,command_args, an optionalcommand_sourceand the typedprompt(read in the reference, in theUserPromptExpansionHookInputdeclaration, and in the 2.1.308 binary's payload schema). The binary's matcher function returnscommand_namefor this event (read), and the binary's prompt-command expander calls the event's runner withslash_command, the command's name, its arguments and its source (read). UserPromptExpansion output may block the expansion or addadditionalContext, which Claude Code places alongside the expanded prompt (reference, read; not yet observed in this project's transcripts). - What UserPromptSubmit sees on the typed route. The line as typed, such as
/deploy staging, not the expanded skill text (reference, read). A UserPromptSubmit hook that blocks it stops the command from running, so UserPromptSubmit runs before the expansion (reference, read). - The transcript of a typed skill. A session in this project where the operator typed
/attendrecords a user entry carrying<command-message>attend</command-message>and<command-name>/attend</command-name>, then the expanded text, and the model's next action is an ordinary tool call; no Skilltool_useappears (read from the session transcript). - Not verified: whether a Skill tool call also fires UserPromptExpansion. The reference describes the event as covering user-typed commands only (inferred from its wording).
Gaps on tool calls themselves: EndConversation fires neither PreToolUse nor PostToolUse (hooks reference, read: "on every tool call inside the agentic loop: PreToolUse and PostToolUse, except EndConversation calls, which skip both"). PostToolUseFailure does not fire for a call rejected before it runs. Workflow's PostToolUse fires at launch, with status: async_launched, not at completion.
What a hook entry costs¶
- Every entry in the shipped
settings.jsonreaches every user through the three-way merge, which adds entries per event and leaves the user's own entries in place. - Each entry spawns one process per matching event. With no
timeoutset, Claude Code's default is 600 seconds, and a hung synchronous hook blocks the tool or the turn until then. - An entry with
async: truenever blocks. It suits an event that only feeds a sensor. - SessionEnd hooks share a 1.5 second budget.
- A per-handler
ifstops a spawn before it happens, but holds one rule per handler and is best effort, so it can only narrow a matcher.
Where attend could observe the session¶
attend's sensors are polled (Sensor::poll in sensor-trait), and hooks push one process per event. Three routes join them:
- The ways hooks already receive every payload they are wired for (#846). They could write each event to a file that a sensor reads on its poll. attend already reads ways state this way: its context and disclosure sensors call
ways context --json. - The attend mod registers in-process
session.*andturn.completehandlers, andtool.callhandlers scoped to its own five MCP tools (attend_listen,attend_send,attend_reply,attend_join,attend_peers;plugins/attend/hooks/register.tsx, lines 877-1067 on main). It sees other tool calls only if new handlers are registered, and it runs only with the mods preview flag on. - A hook could call
attenditself, one more process per event. The hooks today invoke one binary and add no logic (attend-drain-stop.sh).