Skip to content

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, and skills: catches both: the model's Skill tool call on PreToolUse, and the operator's typed /name on UserPromptExpansion, which bypasses PreToolUse. tool_name: matches the tool name for types with no useful field, and tool_event: lists the hook events a way fires on; both are ADR-704's fields, and this record widens tool_event:'s default to PreToolUse and UserPromptExpansion. Existing commands: and files: 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 from gate.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 widened tool_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 generic tool: 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), and pattern: 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's tool_event: lists, through check-tool.sh wired 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 ^gh misses gh after git 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

  1. 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 applies scope: and when:, matches each way's keys, orders the hits, applies refire (ADR-126) and the context budget, and emits the bodies in the hookSpecificOutput envelope for the payload's real event. ADR-704's scan::tool and the separate command and file scans collapse into this loop, keeping their channel names in the events log.

  2. 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 its skill field, and a UserPromptExpansion payload whose expansion_type is slash_command by its command_name. The typed route also covers custom commands, which Claude Code expands the same way. A typed /name arrives 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 default tool_event: (below) a skills: way fires on both routes, since UserPromptExpansion fires before the skill's text reaches the model as PreToolUse does before a tool runs. PostToolUse fires 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_name is 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 accepts UserPromptExpansion, the event a typed /name skill 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 writes tool_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). PermissionRequest and PermissionDenied are 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: and commands: do today. pattern: keeps matching the shell type's description field.
  • .check.md checks 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, nohup and the rest of the describer's wrapper table) stripped, so ^gh matches GH_TOKEN=x gh pr create and timeout 580 gh pr checks. A navigation program reached through a wrapper is operative: sudo -n true is a segment \bsudo\b can match. A way fires once however many segments match, and .check.md checks use the same rule. The rule was chosen over three others on 8,016 recorded Bash calls and the corpus's 23 commands: 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, echo and grep arguments, cd paths, path assignments and loop word lists. The 18 fires that filter segments recover are all grep arguments, 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 inside sh -c and eval strings 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.

  1. 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.

The tool-call lane. At corpus build, tldr-pages data, authored entries and user overrides form the tool catalog's command data, and the way corpus with that data feeds the optional edge index. At a Bash call's PreToolUse, the hook adapter writes the event record and passes the command and description to the command describer, which returns ordered segments with roles, classes and descriptions. Per-segment commands: regexes fire at once in the hook's envelope. The matcher turns operative verbs plus the description into candidate ways, which the judge gate reads against the ordered described block in a detached run, by the session's one engine, resolved once per session from the gate.engine setting: the ways agent on its own API key, or Claude Code internal, a ways mod module calling $.model.complete on the session's own account; with Claude Code internal selected and no mod loaded, the session uses a configured key engine instead, and no job falls back between engines. The verdict lands in the deferred result store, and the collector delivers approved ways at the agent's next PostToolUse or UserPromptSubmit with ADR-606's header, or a one-line pointer past the relevance budget. Lint and reach reports read the logged results.

  1. One adapter. hooks/ways/check-tool.sh over ways hook tool is the one tool-call adapter for ways. It reads hook_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 engine gate.engine selects. On UserPromptExpansion it runs the lane for the skill type and emits in that event's envelope, whose additionalContext Claude 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.sh and check-post.sh fold 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 guard strip-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.

  2. 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.

  1. A fire is recorded when it is delivered. A lane records the fire, stamps engagement (ADR-123) and logs way_fired when the body is emitted on an event measured to deliver; PreToolUse and PostToolUse in the hookSpecificOutput envelope 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.

  2. A failed call fires only a way that lists it. The default tool_event: leaves out PostToolUseFailure, for the reason in item 2's tool_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). PermissionRequest and PermissionDenied are unwired by default; the session event record observes them (ADR-415).

  3. Lint. ways author lint validates the keys against the schema, rejects a tool_event: value outside ADR-704's five and UserPromptExpansion, warns on tool_event: with no tool key, warns on a key whose type is unwired by default and names how to wire it, and warns on a tool_name: regex that matches no catalogued tool (ADR-706 item 6).

  4. ADR-704 is this lane's name-only case, and Bash-derived write targets feed files:. ADR-704, on main, defines tool_name:, tool_event:, the adapter check-tool.sh over ways 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 of tool_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 channel bash-write.

  5. Implementation items.

    • The hit loop and catalog lookup in one scan function, with ways hook tool reading 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 observable before acceptance.
    • The acceptance observation: one interactive session in which a commands: way, an agents: way and a skills: way fire through check-tool.sh, the last both on a typed /name and on a Skill tool call, each paired with a hook_additional_context row, and a judged Bash way arrives at the next hook under the deferred header.

Consequences

Positive

  • A new kind of tool trigger is a key and a catalog entry, not a lane.
  • commands: reaches PowerShell and files: reaches NotebookEdit with no edit to a way, and an anchored commands: 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-code selected 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 for temperature, top_p and top_k on API version 2026-10-21. The judge sends 2023-06-01 (tools/ways-agent/src/net.rs:275), where nothing changes; the first bump of ANTHROPIC_VERSION drops 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: and tool_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 hook if field. 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 a commands: or files: regex use regexes (23 commands: and 30 files: 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 the commands: 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, whatis or 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, PermissionRequest and PermissionDenied in 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 UserPromptExpansion through an alias rule (PreToolUse covering both skill routes). Rejected: ADR-704 compares event names exactly, and an alias would make tool_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.