ADR-188: One tool-call lane keyed by tool type, and a Bash surface that is parsed, described and judged¶
Summary¶
- Decided: ways match tool calls in one lane. The tool catalog (ADR-706) resolves each call's tool to an abstract type and the value of that type's primary field, and one hit loop matches ways against it. Each type with a field has one frontmatter key whose value is a regex over that field:
commands:(shell),files:(file-modify),reads:(file-read),urls:(web),agents:(delegation),skills:(skills),mcp:(MCP tools). A skill has two ways in, andskills:catches both: the model's Skill tool call on PreToolUse, and the operator's typed/nameon UserPromptExpansion, which bypasses PreToolUse.tool_name:matches the tool name for types with no useful field, andtool_event:lists the hook events a way fires on; both are ADR-704's fields, and this record widenstool_event:'s default to PreToolUse and UserPromptExpansion. Existingcommands:andfiles:ways keep working unchanged and now also reach PowerShell and NotebookEdit. One adapter,check-tool.sh, serves every tool event and absorbs the Bash, file and post-tool adapters. The shell, file-modify, delegation, web, skill and plan-mode types are wired by default; file-read and MCP are not. The semantic lane on the Bash surface is rebuilt, not retired: each call is parsed into its ordered segments,commands:regexes run per segment and fire at once, and a matcher on the call's verbs and description proposes candidate ways that the relevance judge (ADR-196) reads against the described call. The judge is the session's engine, resolved once per session fromgate.engine(ADR-708): the ways agent on its API key, or Claude Code internal, a ways mod module on the session's own signed-in account. Only that engine runs, with no per-job fallback. The command never waits for the judge; approved ways arrive through ADR-606's deferred pipeline at the agent's next tool call or prompt. The pieces are separate components with one-way dependencies. This replaces this record's first draft, which moved tool-lane ways to PostToolUse on the belief that PreToolUse context never reaches the model; that belief was wrong. - Trades away: act-time delivery for meaning-based Bash guidance, which arrives after the command runs. A judge request on about half of Bash calls: about a tenth of a cent each on a key engine, or the session account's usage under Claude Code internal. A network dependency for that part of the lane. About a fifth of the judged injections were still off topic in the study. The lane waits on ADR-606's deferred pipeline, which is unbuilt. Each newly wired tool costs one process per call per wired event, and ways on file reads and MCP calls stay silent until a user wires them.
- One-way? No, not yet. The adapter, the wiring and the Bash pipeline can each be reversed in a session. The key names (
reads:,urls:,agents:,skills:,mcp:) and the widenedtool_event:default become a contract with users' own ways at the first release that ships them. - Probes: Confident (semantic): Bash commands keep pulling in guidance by meaning, from what the command does and its description rather than from the surrounding conversation, with the judge deciding; the patterns authors wrote still fire before the command, and the judged guidance arrives just after it. Not confident (cost): about half of Bash calls send a judge request at about a tenth of a cent each, roughly $8 over the 8,000 Bash calls of the 2.7 days measured. Is that spend acceptable for this lane?
- Inversion: at one end, a key or a lane per Claude Code tool (
Bash:,Edit:,Task:), coupled to every tool name and rename. At the other, one generictool:key in Claude Code's permission-rule syntax. The decision keys on the type, which is narrower than a tool and wider than a name. On the Bash surface it sits between injecting every embedding match at act time, as today, and matching only authored regexes: meaning-based candidates are kept, and a judge decides which reach the model.
Context¶
What the first draft decided, and why it no longer holds¶
The first draft of this record (2026-09-19) rested on issue #528's measurement: 3,132 PreToolUse hook outputs carrying a way, none delivered, against PostToolUse outputs delivered 144 of 145. It moved every tool-lane match to PostToolUse inside check-post.sh, made PreToolUse a refusal-only surface (ADR-181's guards), and named the condition for undoing that: a measured hook_additional_context row paired with a PreToolUse output.
That condition was met ten days later. The undelivered output was this project's emit shape, a top-level decision and additionalContext that Claude Code drops silently. Once the scans emitted the hookSpecificOutput envelope, #528 was closed with PreToolUse delivery verified on ways-v1.22.0: in a fresh session running git commit, three ways arrived as PreToolUse context and the model quoted them. The code has emitted that envelope on PreToolUse since (scan/mod.rs:861 and :1033, docstring of emit_hook_context at 1575-1578). The move to PostToolUse and the refusal-only rule therefore have no reason left, and PreToolUse is once again where act-time guidance lands. ADR-704, now on main, relies on that delivery and cites this record as precedent; this rewrite removes the contradiction with the first draft.
Two findings of the first draft still hold and are carried below: a fire is recorded when it is delivered, and a failed call fires nothing by default. Its third, retiring the semantic Bash lane, was measured and replaced (below).
The tool lanes as they stand¶
Five lanes match tool calls on main, each with its own adapter, request type and scan function (ADR-705):
commands:matches the Bash command on PreToolUse (check-bash-pre.sh), andpattern:matches the call's description there too;files:matches the Edit or Write path on PreToolUse (check-file-pre.sh);- postchecks run per-way scripts on PostToolUse and PostToolUseFailure (
check-post.sh); - the task lane scores the delegation prompt semantically and delivers at SubagentStart (
check-task-pre.sh); - ADR-704's
tool_name:lane matches the tool name, on the events a way'stool_event:lists, throughcheck-tool.shwired on PreToolUse and PostToolUse for EnterPlanMode, ExitPlanMode and Workflow; its scan mirrors the file lane's hit loop.
ADR-704 defines tool_event: for the whole tool-call lane and names the type-keyed lane of this record as its follow-up.
commands: and files: are already type keys. Each names one kind of tool and matches a regex against that kind's primary field. Claude Code groups its own tools the same way: a permission rule's specifier targets one primary field per tool, and rule families cover several tools at once (ADR-705). The lanes do not follow those families. PowerShell never reaches commands:, NotebookEdit never reaches files:, and nothing matches a file read's path, a fetched URL, a subagent's type or an MCP tool. Each gap closed so far has added a lane.
The operator asked to take the contributor's tool lane, survey what else can be sensed, and build an attend sensor "in addition to ways triggers", and chose one frontmatter key per type over a single permission-rule key. Asked about plan approval, the moment ADR-704 was built for, the operator answered "I don't really use plan mode" and "instead, we use our own skills". Skills reach Claude Code by two routes: the model calls the Skill tool, or the operator types /name. The typed route makes no tool call; Claude Code expands the skill into the prompt and fires UserPromptExpansion, not PreToolUse (ADR-705). ADR-706 decides the catalog that maps Claude Code's tool names to types. This record decides the lane that uses it.
The semantic Bash lane, measured¶
The semantic lane on the Bash surface (ADR-155 §4) embeds the assistant's prose since the last human turn, the command and its description, and injects every way that clears the calibrated threshold, unjudged. ADR-196 §1 applies the relevance gate to every way the matcher selected semantically, but the code calls the gate only on the prompt lane (scan/mod.rs:402), so today's Bash lane departs from §1; item 3c brings it under the gate. Since #528's fix its output reaches the model. ADR-707 measured it over 2.7 days and 8,016 Bash calls:
- It made 5,705 of 7,034 way fires (81%). About 3% were on topic and 77% off topic, and no score threshold separates the two.
- The matched text is mostly prose, not the command, and a subagent's call is matched against its lead's prose, because the lookbehind reads the main transcript for every caller (
lookbehind.rs:31). - A Bash call is several tools: a mean of 3.1 operative segments per call, and most calls with an action segment also carry reads. The
commands:regex runs on the raw string, so a pattern anchored at^ghmissesghaftergit push &&. - Matching on the call's verbs and its description, with narration and arguments removed, was on topic in 7.6% of its fires (36 of 473) on 200 uniformly drawn calls. None of 160 sampled fires of today's surface on those calls was graded on topic, though today's surface also fires at least 9 of those 36 on-topic pairs, so its rate is above zero. The verbs-plus-description matcher found 52 on-topic fires on calls where nothing semantic had fired. About three-quarters of its on-topic fires were regex-shaped, ways a repaired or new
commands:regex could reach; beyond those, meaning added about 4 intent-shaped on-topic fires per 100 calls. - The relevance judge reading an ordered description of the call (its description, then the call's segments in order, one
;,&&or newline unit per line with pipes inline, each segment with a tldr-pages description) passed 0.175 on-topic and 0.14 off-topic injections per call for those candidates. Today's surface, scanned fresh on the same calls, fires about 6 ways per call (1,201 fires) with on-topic fires between about 0.045 and 0.14 per call. Both are fresh scans; refire would lower both. Adding narration to the judge's input brought the off-topic passes back. - A judge request took 1.4 s at the median and 5.9 s at p95, so a synchronous judge would hold most Bash calls that carry candidates.
The draft's retirement would have removed the off-topic volume and the on-topic guidance with it. The operator read retirement as "a regression in capability", suspected that "each 'bash tool' is actually a whole universe of specific tools, sometimes in pipes", and set the flow: parse the call in order, match to the ways corpus, present the findings to the judge with the tldr explanations in order, and let the judge decide. The study's margin for meaning over repaired regexes is narrow, about 4 intent-shaped on-topic fires per 100 calls; the rebuild rests on the operator's direction and on the whole of ADR-707, which shows the judged lane at a small fraction of today's off-topic volume. They chose to run the judge alongside the command and deliver through the deferred pipeline ADR-606 decided, and asked that the concerns stay separated rather than grow into a matcher monolith.
The judge itself came late to this project because it needed a separate API key to manage; only once its value justified that key was the gate built (ADR-196). Claude Code's mod API can run a completion on the session's own account, which removes that cost wherever mods load, and ADR-708 adds it as a selectable engine.
Decision¶
-
One lane, keyed by tool type. Every tool event a ways hook receives goes through one path. The catalog (ADR-706) resolves the payload's
tool_name, legacy aliases included, to a type and the value of the type's abstract field. One hit loop then appliesscope:andwhen:, matches each way's keys, orders the hits, applies refire (ADR-126) and the context budget, and emits the bodies in thehookSpecificOutputenvelope for the payload's real event. ADR-704'sscan::tooland the separate command and file scans collapse into this loop, keeping their channel names in the events log. -
Frontmatter keys. Each regex compiles case-insensitively (ADR-157).
| Key | Type | Abstract field | Tools today, through the catalog |
|---|---|---|---|
commands: |
shell | command, matched per operative segment (item 3) |
Bash, PowerShell |
files: |
file-modify | path |
Edit, Write, NotebookEdit, MultiEdit (legacy) |
reads: |
file-read | path |
Read, Glob, Grep, LSP |
urls: |
web | url |
WebFetch |
agents: |
delegation | agent |
Agent's subagent type, Workflow's name |
skills: |
skill | skill |
the Skill tool's skill; a typed /name, through UserPromptExpansion's command_name |
mcp: |
mcp | tool |
any mcp__ tool, matched as server__tool |
skills:is a regex over the skill's name. The catalog maps both routes into the skill type (ADR-706 item 2): a Skill tool call by itsskillfield, and a UserPromptExpansion payload whoseexpansion_typeisslash_commandby itscommand_name. The typed route also covers custom commands, which Claude Code expands the same way. A typed/namearrives at the prompt lane as the line the operator typed, and the lane never sees the expanded skill text there;skills:is the trigger for the skill itself. Under the defaulttool_event:(below) askills:way fires on both routes, since UserPromptExpansion fires before the skill's text reaches the model as PreToolUse does before a tool runs.PostToolUsefires only on the tool route; the typed route has no after-event. Whether the tool route also fires UserPromptExpansion is not verified; if it does, refire (ADR-126) holds the second fire, and the build checks which events one model-invoked skill produces.tool_name:is ADR-704's field: a regex over the canonical tool name. It serves the types with no useful field (plan-mode, scheduling, user-interaction, publish and the rest) and tools the catalog does not map.tool_nameis also the payload key and the session event record's field (ADR-415).tool_event:is ADR-704's lane-wide field: literal hook event names, compared exactly, applying to every key above. Lint accepts the five events Claude Code filters by tool name (ADR-704 item 1). This record amends ADR-704 in two places: lint also acceptsUserPromptExpansion, the event a typed/nameskill arrives on, and the default becomes[PreToolUse, UserPromptExpansion]. A UserPromptExpansion payload resolves only to the skill type, so the wider default changes nothing for the other keys. A way that writestool_event:lists exactly the events it wants;[PreToolUse]alone reaches only the Skill tool route.- The default leaves out
PostToolUseFailure: a match on a failed call would stamp the way and hold it back from the retry that succeeds. A way that lists it accepts that cost (ADR-704 item 2).PermissionRequestandPermissionDeniedare accepted names but not wired by default, so lint warns on them as ADR-704 item 5 does for any unwired event. - A way's keys are independent triggers: any one that matches fires the way, as
pattern:andcommands:do today.pattern:keeps matching the shell type's description field. -
.check.mdchecks keep their scoring on the shell and file-modify types. -
The Bash surface is parsed, described and judged. This replaces the semantic lane ADR-155 §4 added and supersedes that section, declared in frontmatter on both records.
a. Parse. The command describer (item 4) splits each call into ordered segments. Each segment carries the connector before it (;, &&, ||, a pipe, &, a newline, a subshell or a command substitution), a role (navigation, filter or operative), its program, subcommand and flags, and a class (publish, version-control write, service, package, build and test, file write, version-control read, search, read and inspect, other). Heredoc bodies are dropped. Each commands: regex runs against each operative segment's own text, not the raw command, so a pattern anchored at the start matches after a connector, and one segment's arguments cannot satisfy a pattern meant for another program. Regex fires go out at once on PreToolUse with no judge, as authored triggers do today. Bash-derived write targets (#525) come from the same segments (item 10).
Note (2026-10-22), item 3a, as built. Each
commands:regex is matched against an operative segment's text and against the same segment's text from its program word, with leading assignments and wrappers (sudo,env,timeout,nohupand the rest of the describer's wrapper table) stripped, so^ghmatchesGH_TOKEN=x gh pr createandtimeout 580 gh pr checks. A navigation program reached through a wrapper is operative:sudo -n trueis a segment\bsudo\bcan match. A way fires once however many segments match, and.check.mdchecks use the same rule. The rule was chosen over three others on 8,016 recorded Bash calls and the corpus's 23commands:patterns (~/scratch/session-2026-10-22-toollane/per-segment-rules.md). Against the raw command (4,333 fires), operative segments only fired 4,443 (740 gained, 630 lost), this rule 4,457 (754 gained, 630 lost), and operative plus filter segments 4,475 (754 gained, 612 lost). The gains are anchored patterns matching after a connector; the losses are nearly all text no command runs: heredoc bodies,echoandgreparguments,cdpaths, path assignments and loop word lists. The 18 fires that filter segments recover are allgreparguments, so filters stay unmatched. Not recovered: a command held in a variable and run through it (R="docker run …"; $R make test, 13 calls, container-safety), and commands insidesh -candevalstrings or a heredoc fed to a shell (ssh host 'bash -s' <<'EOF', 2 calls, bounded-execution). Issue #1143 tracks parsing those strings as nested commands.
b. Candidates. The matcher scores ways against a text built from the call's operative verbs (program, subcommand and flags per operative segment, with arguments and paths dropped) and the Bash tool's description field, through the calibrated fire rule (ADR-156). Ways that clear it are candidates, not injections. No narration enters the matched text. The alternative recorded here is the tldr-text surface: the description, then each segment's tldr description in order, joined by its connector in words. Before this record is accepted, the two are compared on a fresh held-out set of uniformly drawn Bash calls under ADR-707's blind protocol, and the one with more on-topic injections per call, at no more off-topic injections per call, ships. If their intervals overlap, verbs plus description ships, since it needs no tldr text at match time and measured better on every column.
c. Judge. The candidates go to the relevance gate (ADR-196). On this lane the gate judges every candidate, in requests of at most the profile's max_candidates (8) each. That departs from the prompt lane, which judges the first max_candidates in the matcher's order and passes the rest unjudged (max_candidates in tools/ways-agent-core/src/profile.rs): unjudged candidates here were 66% off topic, and nothing on this lane waits on the request. ADR-707's arm E judged the same way, which is where its 0.57 requests per Bash call come from. The judge reads the block ADR-707 measured: About to run: <description>, then one line per unit the call splits into at ;, &&, a newline, a loop body or a subshell, in order. Segments joined by a pipe or || stay on one line with the symbol itself (git log (…) | grep (…) | head (…)). Each segment reads program subcommand (description): an operative segment carries its described example or authored entry (ADR-706 item 7), a filter its tldr summary, and either may carry none. Navigation segments are dropped. Narration is left out of the judge's input as well as the matcher's. Only ways the judge passes at the gate's threshold are delivered. A judge error, a missing API key or a run past ADR-606's 60 s bound delivers nothing from this lane and is logged; the regex fires of part a are unaffected.
The judge is the session's engine, resolved once per session from gate.engine, one interface for every lane the gate covers (ADR-708): a job holding the candidates and the ordered block goes in, and a verdict per candidate comes out into ADR-606's deferred store, where one collector delivers it.
- A key engine (anthropic, openrouter). The adapter starts the ways agent's request detached, on its own API key (ADR-196, ADR-502), as the prompt lane's gate runs today.
- Claude Code internal (claude-code). A ways module loaded into Claude Code as a mod claims the job and judges it through $.model.complete on the session's own signed-in account, with no separate key or bill. It answers in strict JSON validated against the record_judgements schema; an invalid reply is a judge error and delivers nothing (ADR-708 item 4). The module is a ways component, not part of the attend mod.
Only the session's engine judges. With a key engine selected the mod module stands down even when loaded, and when the session resolves to claude-code the ways agent sends no provider request. With claude-code selected and no mod loaded, the session resolves to a configured key engine, anthropic then openrouter, and keeps it for the session. No job falls back from one engine to the other, so no candidate is judged twice. A session left with no engine, no mod and no key, delivers nothing on this lane and logs that a key path should be configured. $.model.fork, which would give the judge the session's transcript, is not used, for the reason in ADR-708's alternatives: narration brought off-topic passes back in ADR-707.
Note, 2026-10-22: the shared parser and job store. ADR-708's prompt-lane handoff moves the parse and the validation of a claude-code reply to the hook side, in judge::parse_reply, and leaves the mod module to carry the request and the reply's text and usage. This lane's judge reuses that parser and the job store that handoff builds, so an invalid reply is still invalid_reply and delivers nothing. The rules above are unchanged.
d. Timing. The command never waits for the judge. At PreToolUse the adapter emits the regex fires, writes the candidates and the ordered block as a deferred job in the calling agent's deferred directory (ADR-606 §1), hands the job to the selected engine (part c), and returns. The verdict is delivered through ADR-606's deferred pipeline: the collector picks it up at the same agent's next PostToolUse or UserPromptSubmit and injects each approved way once under ADR-606's header, naming the way, the Bash lane and the segment that matched, and the age. ADR-606's relevance budget applies unchanged; a verdict collected past it becomes ADR-606's one-line pointer to the result file. A subagent's verdict is collected by that subagent, and its budget is time alone. ADR-606 is accepted and unbuilt: the engine has no macro_defer handling, result store or collector. This lane is the pipeline's second consumer, so the build of the store and the collector serves both: the collector reads results by kind, a macro's output or a judge's verdict, from the same per-agent directory and under the same budget.
e. Lookbehind. Any lookbehind reads the calling agent's own transcript: a subagent's own file for a subagent, the main transcript for the main agent. Today lookbehind::intent reads the main transcript for every caller (lookbehind.rs:31). The fix applies to the check-scoring embed pass, which keeps the lookbehind (ADR-160 stage 1) and runs only when a check in scope declares description and vocabulary and no regex matched it. The Bash lane's matcher and judge use no lookbehind.
- Components and their dependencies. The lane is built from separate components. Each depends only on the ones it names, no component calls back into one that calls it, and each is tested on its own inputs.
| Component | Owns | Depends on | Knows nothing of |
|---|---|---|---|
Hook adapter (check-tool.sh, ways hook tool) |
reading the payload, writing the session event record (ADR-415), calling the components below in order, emitting the envelope | the catalog, the describer, the matcher, the judge gate, ADR-606's store | how any of them work |
| Tool catalog (ADR-706) | tool names to types and fields; command entries and their descriptions | nothing; it is data | ways, hooks, embeddings |
| Command describer | parsing a command string into ordered, described segments | the catalog's command data | ways, embeddings, the judge, hook events; its own crate |
| Edge index builder | precomputed edges from command entries to candidate ways, at corpus build | the catalog, the corpus | hooks; optional for verbs plus description, which embeds the description per call, and needed by a description-free matcher |
| Matcher | scoring ways against abstract signals (type, field value, segment verbs, description) | the corpus, the edge index | Claude Code's names, hook events, the judge |
| Judge gate (ADR-196, ADR-708) | yes or no per candidate against the ordered block, by the one engine gate.engine selects: the ways agent on its key, or Claude Code internal in a ways mod module |
the deferred job and result store; the selected engine | how candidates were found |
| Lint and reach reports | ways author lint, ways status, the reach and delivered-versus-emitted counts in ways introspect |
logged results, the catalog, the describer | nothing calls them |
The figure shows the flow and the dependencies.
-
One adapter.
hooks/ways/check-tool.shoverways hook toolis the one tool-call adapter for ways. It readshook_event_name. On PreToolUse it runs the lane, and for the shell type writes the judge job of item 3 and hands it to the enginegate.engineselects. On UserPromptExpansion it runs the lane for the skill type and emits in that event's envelope, whoseadditionalContextClaude Code adds alongside the expanded prompt. On PostToolUse it runs the lane, then the postchecks (ADR-123) and ADR-606's collector, and prints one envelope. On PostToolUseFailure it runs the postchecks only.check-bash-pre.sh,check-file-pre.shandcheck-post.shfold into it. These stay as they are:check-task-pre.sh, whose semantic match on the delegation prompt is a different matcher from a field regex; the guardstrip-session-link-pre.sh(ADR-181);mark-tasks-active.sh;check-queued.sh(ADR-161);issues-pull.sh;check-pull.sh. The prompt lane's hook runs ADR-606's collector on UserPromptSubmit. -
Default wiring and its cost. The adapter's matchers are generated from the catalog's wired set (ADR-706 item 2), one entry each on PreToolUse, PostToolUse and PostToolUseFailure, plus one UserPromptExpansion entry with an empty matcher, since skill names are not known in advance. Every entry reaches every user through the settings merge (ADR-500), and each wired tool costs one process per call per event.
| Type | Wired by default | Cost against today |
|---|---|---|
| shell | yes | none for Bash: two adapters on Pre and Post become one each. Judge requests on calls with candidates, about half of them, 0.57 requests per Bash call in ADR-707 with every candidate judged: account usage on the mod path, about $0.001 per Bash call on the key path. PowerShell adds two per call, on Windows. |
| file-modify | yes | none for Edit and Write. NotebookEdit adds two per call. |
| delegation | yes | Agent gains one on Pre beside check-task-pre.sh; its Post spawn exists. Workflow: none, ADR-704 already wires it on both events. |
| web | WebFetch, yes | two per fetch |
| plan-mode | EnterPlanMode, ExitPlanMode, yes | none: ADR-704 already wires both on PreToolUse and PostToolUse |
| skill | yes: Skill on PreToolUse and PostToolUse, and UserPromptExpansion with an empty matcher | two per Skill call; one per typed slash command, which the operator types by hand |
| publish | the outward publish tools, by name | two per call; rare |
| file-read | no | the most frequent tool; two per Read, Glob or Grep |
| mcp | no | servers differ per user |
| the rest | no | reachable through tool_name: once wired |
The adapter entries keep the explicit timeout of 10 seconds that ADR-704's entries already set, so a hung binary holds a tool call for at most that long rather than Claude Code's 600-second default; the detached judge does not count against it. A per-handler if may narrow a spawn for a shipped way, as an optimisation and never as the trigger. Until a ways setting wires a type, a user wires file-read or MCP with a matcher entry in their own settings.
-
A fire is recorded when it is delivered. A lane records the fire, stamps engagement (ADR-123) and logs
way_firedwhen the body is emitted on an event measured to deliver; PreToolUse and PostToolUse in thehookSpecificOutputenvelope both are. A lane that separates match from delivery stamps when it drains: a judged Bash way is recorded when the collector delivers it, not when the judge passes it, and a verdict that becomes a pointer records no fire. The task stash drained at SubagentStart is checked against this rule as part of the build. This keeps the defect the first draft found from recurring: a fire nobody read stamped the way and muted the prompt lane. -
A failed call fires only a way that lists it. The default
tool_event:leaves outPostToolUseFailure, for the reason in item 2'stool_event:bullet, and a way that lists it accepts that its fire on a failed call stamps the way and holds it back from the retry (ADR-704 item 2). The postchecks keep running on PostToolUseFailure (item 5).PermissionRequestandPermissionDeniedare unwired by default; the session event record observes them (ADR-415). -
Lint.
ways author lintvalidates the keys against the schema, rejects atool_event:value outside ADR-704's five andUserPromptExpansion, warns ontool_event:with no tool key, warns on a key whose type is unwired by default and names how to wire it, and warns on atool_name:regex that matches no catalogued tool (ADR-706 item 6). -
ADR-704 is this lane's name-only case, and Bash-derived write targets feed
files:. ADR-704, on main, definestool_name:,tool_event:, the adaptercheck-tool.shoverways hook tool, the wired lists in the schema and the lint against them. This lane keeps all of them and amends only the accepted event names and the default oftool_event:(item 2). A write target the describer derives from a segment (sed -i,tee, a redirect; #525) is matched by the file-modify key on the same hook, with channelbash-write. -
Implementation items.
- The hit loop and catalog lookup in one
scanfunction, withways hook toolreading the event. - The command describer as its own crate, with tests on command strings alone.
- The matcher on verbs plus description, the semantic branch of today's command scan removed, and lazy embedding for checks.
- ADR-606's deferred result store and collector, built once for macros and judge verdicts.
- The lookbehind fix of item 3e.
- The settings template generated from the catalog, with a test that compares them.
- The schema entries for the new keys, and the lint rules in item 9.
- A delivered-versus-emitted count in
ways introspect, so a lane that emits and never delivers is visible within days. - The held-out comparison of item 3b, recorded under
observablebefore acceptance. - The acceptance observation: one interactive session in which a
commands:way, anagents:way and askills:way fire throughcheck-tool.sh, the last both on a typed/nameand on a Skill tool call, each paired with ahook_additional_contextrow, and a judged Bash way arrives at the next hook under the deferred header.
- The hit loop and catalog lookup in one
Consequences¶
Positive¶
- A new kind of tool trigger is a key and a catalog entry, not a lane.
commands:reaches PowerShell andfiles:reaches NotebookEdit with no edit to a way, and an anchoredcommands:regex matches after a connector.- Ways can fire on what a subagent launch, a web fetch, a skill or a plan approval carries, at act time.
- On the measured calls, scanned fresh, the judged Bash lane passes 0.175 on-topic and 0.14 off-topic injections per call, where today's surface fires about 6 ways per call with on-topic fires between about 0.045 and 0.14 per call; refire would lower both. Ways with no
commands:field, such as the delivery parent or testing evaluation, are still reached by meaning. - The command and the regex fires never wait on the judge.
- The describer, the matcher, the judge gate and the reports are tested and replaced separately. The describer knows nothing of ways, so a later matcher or another consumer can reuse it.
- Building ADR-606's store and collector once serves its deferred macros and this lane.
Negative¶
- Meaning-based Bash guidance arrives after the command it was about, at the agent's next hook. A heads-up written for the moment before a command lands after it; authored
commands:regexes still fire before. - The lane needs network and an engine for the session. With
claude-codeselected and no mod loaded it runs on a configured key, paying the provider. With no engine at all it delivers no meaning-based Bash guidance until a key path is configured, though its regex fires are unaffected. - On a key engine the judge is API spend, about $0.001 per Bash call, about $8 over the 8,016 calls of the measured 2.7 days. Under Claude Code internal it is the session account's usage, about 0.57 judge requests per Bash call in ADR-707, each of about 1,160 input and 117 output tokens; on a subscription that draws on the plan's limits.
- Under Claude Code internal the judge answers in JSON text rather than a forced tool call, so ADR-707's numbers hold there only once ADR-708's agreement observable is recorded. That engine also rests on a preview API.
- About 21% of the judged injections in the study were still off topic, and every grade behind that figure came from a Claude model.
- The judge sends
temperature: 0. The claude-api skill bundled with Claude Code 2.1.308 (claude-api/shared/api-version-migration.md, "Migrating to API version 2026-10-21", change 1) returns 400 fortemperature,top_pandtop_kon API version2026-10-21. The judge sends2023-06-01(tools/ways-agent/src/net.rs:275), where nothing changes; the first bump ofANTHROPIC_VERSIONdrops the parameter, and verdict stability at the default temperature is unmeasured (#1130). - The lane cannot ship before ADR-606's store and collector exist.
- The parser is heuristic and the tldr data misreads some invocations; a wrong description reaches the judge.
- Each newly wired tool adds a process per call per event. A way on an unwired type lints with a warning and stays silent; a user who wants
reads:must wire Read, and pays its frequency. - Five new frontmatter keys to learn, beside ADR-704's
tool_name:andtool_event:.tool_name:remains coupled to Claude Code's names.
Neutral¶
- ADR-155 §4 is superseded by item 3; the rest of ADR-155 stands.
- The task lane keeps its own adapter and semantic match.
agents:sits beside it on the same tool. - PostToolUse remains the place for postchecks, the queued-message lane (ADR-161) and ADR-606's collector. PreToolUse carries guidance again, as well as guards.
- Events logged on
semantic:bash:*before the build stay in the log and read as delivered from 2026-09-29 on. - ADR-707's graded sets can seed the calibration of the matcher and the judge's threshold on this lane.
Alternatives Considered¶
- Keep this record's first draft: move tool-lane matching to PostToolUse. Rejected. Its reason, that PreToolUse context is never delivered, was this project's emit shape, and #528 closed with PreToolUse delivery verified. Moving to PostToolUse would turn act-time guidance into after-the-fact guidance for no gain.
- Reject this record and accept ADR-704 as a separate lane. The cheapest path. Rejected as the end state: a lane per gap means a scan, a request type, an adapter and a phase concept per lane, and the field-matching gaps (PowerShell, NotebookEdit, reads, URLs, agent types, MCP) stay open. ADR-704's mechanism is kept as the name-only case.
- A single
tool:key in permission-rule syntax (Bash(git *),Edit(**/*.rs)). It is Claude Code's own syntax and matches the hookiffield. Not chosen: the operator picked one key per type. It would also name harness tools in every way and use globs where the 43 way files on main that carry acommands:orfiles:regex use regexes (23commands:and 30files:keys, 10 files carrying both, 4 of them checks). - A key per tool (
bash:,edit:,notebook_edit:). Rejected: every tool rename or new family member becomes a way edit, which is the coupling ADR-706 exists to remove. - Retire the semantic Bash lane, and repair the
commands:regexes it misses. The measurement's first recommendation, and this record's earlier text. Cheap, and it removes about 1,600 off-topic injections a day. Rejected by the operator, who read it as a regression in capability. The measured margin is narrow: about three-quarters of the rebuilt matcher's on-topic fires are regex-shaped, and once thecommands:regexes are repaired, meaning adds about 4 intent-shaped on-topic fires per 100 calls (ADR-707). The rebuild rests on the operator's direction and the whole of ADR-707 rather than on that margin. - Keep the lane as it is, or raise its threshold. Rejected: about 3% on topic, and precision is flat across score bands; a threshold of 0.7 keeps 2 of 7 on-topic fires at the same off-topic share.
- Repair today's surface per ADR-191 (lookbehind, chunking, winner confirmation). Rejected: the narration the lookbehind brings in is the main source of off-topic matches, and a judge given narration passed more off-topic ways.
- The tldr-text matcher. Recorded as the alternative in item 3b and decided on the held-out set before acceptance. It measured lower than verbs plus description on every column, inside overlapping intervals.
- Judge synchronously at PreToolUse. Act-time delivery for judged ways. Rejected: a judge request took 1.4 s at the median and 5.9 s at p95, and the prompt lane's 2,000 ms deadline would fail 9–29% of requests open across the study's arms and sets (19% for arm E), delivering unjudged candidates.
- Inject the candidates unjudged. Rejected: unjudged verbs-plus-description candidates were 66% off topic.
- The mod judges whenever it is loaded, with the key as a fallback for unclaimed jobs. This record's previous draft. Rejected: one candidate could reach two judges and be paid for twice, and loading a mod would change who pays. ADR-708 makes the engine one explicit setting.
- Describe commands with
man,whatisor an installed tldr client at run time. Rejected: their presence and content vary by host, and the operator ruled out depending on a package installed on the machine. The tldr data ships as corpus data instead (ADR-706). - Precompute embeddings of every tldr example at corpus build. About 29 MB at f16, and only a matcher without the description escapes per-call embedding. Kept as the optional edge index for such a matcher.
- Wire every tool (
.*) so any way works without wiring. Rejected: one process per tool call per event, Read included, to serve a handful of ways. - Fire on PostToolUseFailure by default. Rejected for the reason in item 2; a way may list it, as ADR-704 allows.
- Reject
PostToolUseFailure,PermissionRequestandPermissionDeniedin lint. This record's earlier text. Replaced by ADR-704's rule, on main, which accepts all five events and leaves the failure event out of the default. - Match
UserPromptExpansionthrough an alias rule (PreToolUsecovering both skill routes). Rejected: ADR-704 compares event names exactly, and an alias would maketool_event:mean something other than the events it lists. - A separate hook command for the lane on PostToolUse beside
check-post.sh. Rejected: a second process per call where one already reads the same payload and prints the envelope.