ADR-704: A tool-name trigger lane¶
Summary¶
- Decided: a way can fire when Claude Code calls a named tool. The frontmatter field
tool_name:is a regex matched against the hook payload'stool_name, case-insensitively like every trigger regex (ADR-157). The fieldtool_event:says when: a list of literal hook event names,[PreToolUse]by default,[PostToolUse]after the tool returns,[PreToolUse, PostToolUse]on either. A failed call (PostToolUseFailure) fires only a way that lists it. The lane is served byways hook toolthrough the adapterhooks/ways/check-tool.sh, which the settings template wires on PreToolUse and PostToolUse forEnterPlanMode|ExitPlanMode|Workflow. - Trades away: dynamic coverage. A
tool_name:regex reaches only the tools the shipped matcher names, andtool_event:only the events it wires. A way that names another tool stays silent until the template adds it; lint warns and names the wired set. - One-way? No. The lane is additive. Removing the template entries switches it off, and a way that also carries other triggers keeps them.
- Inversion: between a matcher on every tool call (
.*), which spawns the binary for each call, and no tool lane, where moments such as an approved plan or a launched Workflow have no trigger at all.
Context¶
The existing tool lanes key on what a tool touches: commands: matches the Bash command and files: matches the Edit or Write path. Some moments in a session are tool calls with nothing to match but the name. A plan is approved when ExitPlanMode returns. A Workflow starts when the Workflow tool is called. A way written for those moments had no trigger. The workaround was a postcheck (ADR-135) that tests tool_name and exits 0, plus a wider PostToolUse matcher. That puts a match rule in a script that the frontmatter cannot show.
The motivating case is a planning loop run through plan mode and Workflows: the prompt is the specification, the approved plan is a prediction, and the Workflow is the evaluation. Guidance for each step belongs at the moment the step starts.
What Claude Code delivers, per the hooks reference (fetched 2026-10-21) and a probe:
- PreToolUse and PostToolUse match on any tool name. The reference names
ExitPlanModeexplicitly. For it,tool_inputcarriesplanandplanFilePath, and the PostToolUsetool_responsecarriesplanandfilePath. PostToolUse fires only when the user approves the plan. EnterPlanModeis a tool, so hooks fire on it by the general rule. Toggling plan mode with Shift+Tab is not a tool call and fires no hook.WorkflowPreToolUse and PostToolUse both fire. The Workflow runs in the background, so PostToolUse fires at launch, not at completion (probe, 2026-10-21).- Neither plan-mode tool is available under
claude -p, so their firing is unverified in-p. It rests on the reference. - PreToolUse
additionalContextin thehookSpecificOutputenvelope reaches the model (#528).
Decision¶
- Fields.
tool_name:is a regex on the tool name, and it is fire-bearing, so the way needsrefire:. The field takes the name of the payload key it matches.tool_event:is a one-line list of hook event names, written as Claude Code names them, and defaults to[PreToolUse]. Names are compared exactly. Lint accepts the five events Claude Code filters by tool name:PreToolUse,PostToolUse,PostToolUseFailure,PermissionRequest,PermissionDenied. Any other name is an error, an empty list is an error, andtool_event:withouttool_name:is a warning. - Matching.
scan::toolmirrorsscan::file. It appliesscope:andwhen:(includingwhen: file_exists, which the way schema now lists), checks the event against the way'stool_event:, matches the regex, orders the hits, and shows each way on channeltool. The envelope'shookEventNameis the real event. The default list leaves outPostToolUseFailure, because a match there would stamp the way and hold it back from the retry that succeeds (ADR-188 item 2). A way that lists it accepts that cost. - Wiring.
hooks/ways/check-tool.shis a two-line adapter overways hook tool(ADR-504 ยง11). The settings template adds one PreToolUse entry and one PostToolUse entry with matcherEnterPlanMode|ExitPlanMode|Workflow. Each is its own entry, so existing entries keep their matchers. Extending the lane to a new tool is a one-line change to both matchers. Extending it to another event is one more entry. - Refire. The lane uses the same refire curve as every other lane (ADR-126). A second call inside the window is held back. A call far past it fires again, so a loop that approves a plan each round gets the way each round.
- What is wired is declared, and lint checks against it. The way schema (
frontmatter-schema.yaml) lists the wired tools undertool_name.wiredand the wired events undertool_event.wired, and a unit test holds both equal to thecheck-tool.shentries in the shippedsettings.json. Lint warns when atool_name:regex matches none of the wired tools, and whentool_event:lists an event that is not wired, and names the wired set in the warning. The warning applies to user and project ways too: they cannot widen the shipped matcher, so a way that names an unwired tool would otherwise lint clean and never fire. tool_event:belongs to the tool-call lane, not to this field. Every tool hook names its event, and a way on any tool surface may need to say which one.tool_event:is defined for the lane: the literal event names, the default, and the lint rules above. A later field on the same lane, such as a matcher ontool_input, reuses it rather than adding its own phase field. A type-keyed tool-call lane, which the rewrite of ADR-188 is drafting, builds ontool_name:andtool_event:as defined here.
Consequences¶
Positive¶
- A way can carry guidance for the moment a plan is approved or a Workflow launches, and its frontmatter shows the trigger.
- The lane reuses the scan, show and envelope code of the file lane, so budget, scope,
when:and refire behave the same.
Negative¶
- Two matchers in the template must name the tools a way may target. A way that names an unwired tool never fires. Lint warns, but a user or project author can only ask for the template to change.
- The schema's
wiredlists repeat whatsettings.jsonsays. The unit test catches a template edit that skips the schema.
Neutral¶
- The field reads only the tool name. Matching on
tool_input(for example the plan text) is left for a later decision. - The common hook input carries
permission_mode("plan" in plan mode). A gate on it would let a way fire only while planning. It is not part of this decision.
Alternatives Considered¶
- Matcher
.*on PreToolUse and PostToolUse. Rejected: it spawns the binary on every tool call to serve a handful of ways. - A postcheck per way. Works today without engine changes, but hides the trigger in a script and runs a process per way.
- Field names
tools:andtool_phase: pre|post|both. The first draft of this decision used them. Rejected before release.tools:already means the tools an agent may use in agent definitions (agents/*.md), so a reader moving between the two would confuse them.tool_name:is Claude Code's own payload key, so the field says what it matches.tool_phase:mapped three words onto two events and had no word for the other three events Claude Code filters by tool name; a list of literal event names covers all five with no translation table. Once user and project ways carry a field, renaming it is a contract change, so the names were settled before the lane shipped. - Field names
tool_names:oron_tools:. They avoid the agent-definition clash, but neither names the payload key it matches. - Fire on
PostToolUseFailureby default. Rejected for the reason in ADR-188 item 2. A way may still list it.
Follow-ups¶
- A
when: permission_mode:gate. - Matching
tool_inputfields, withtool_event:as defined here. - A type-keyed tool-call lane in the rewrite of ADR-188, built on
tool_name:andtool_event:.
Note, 2026-10-22: ADR-188's rewrite¶
Appended; nothing above is changed.
- This record cites "ADR-188 item 2" for why
PostToolUseFailureis out of the defaulttool_event:, as does the doc comment onscan::tool(tools/ways-cli/src/cmd/scan/mod.rs:1084on main at 7fd6c0de). In ADR-188's rewrite the reason sits in item 2'stool_event:bullet, so the citation still finds it; item 8 states the rule this record decided: out of the default, accepted when a way lists it. - ADR-188 builds its type-keyed lane on
tool_name:andtool_event:as defined here and amends one part of item 1: lint also acceptsUserPromptExpansion, the event a typed/nameskill arrives on, and the defaulttool_event:becomes[PreToolUse, UserPromptExpansion]. Event names stay literal and compared exactly.