feat: repeat-tool guard — break the loop before the budget runs out

[saucam]

Why

An unattended dispatch worker wedged on Read(same file) or Bash(same failing command) burns its entire tool budget and reports failure with no diagnosis. The budget caps the damage; nothing currently catches the cause while the turn can still recover.

What

The first advisory guard. It watches each agent's tool stream, counts runs of consecutive calls to the same tool with identical canonicalised arguments, and at 3 / 5 / 8 in a row injects an escalating reminder to re-read the last result and either change approach or conclude.

Advisory only — it never appears in the tool list, never vetoes a call, never rewrites arguments, and never delays anything. Anything that needs to stop a call stays with the approval flow or the autonomous budget.

src/daemon/guard/repeat-tool.ts   312  pure: no I/O, no clock, no daemon imports
src/daemon/guard/index.ts          21  barrel + the "observe, never block" contract
src/daemon/session.ts             +89  4 wiring points
src/config.ts                     +56  GuardSchema + 2 env overrides

Prior art

DeepSeek Harness's dsh-repeat-tool-reminder, analysed in the new docs/prior-art-deepseek-harness.md (§3.7 / §4.3). Two divergences, both forced by codeoid being a control plane rather than a harness:

• Chains key per emitting agent (sdkAgentId). dsh has one agent per loop; we get interleaved tool_start events from parallel subagents, which under one shared chain would reset forever and never fire.
• Case-insensitive patterns, because the same logical tool is TodoWrite on Claude and todo_write elsewhere — one default exclude list has to cover both.

Design notes worth reviewing

Injection uses later priority, which merges into the running turn without starting a fresh query — so a reminder costs no extra turn. This is the analog of dsh's agent.inject().

The advisory also goes to the accumulator, not just the run. It is model-visible, so canonical history has to carry it or a cross-backend fork would replay a conversation the model never had.

Invalid thresholds fail loud in the guard constructor rather than silently reverting to defaults — a guard that never fires because of a typo is worse than no guard. Session construction catches that and starts without the guard; an advisory plugin is never a reason to refuse a session.

Chains reset on any inbound message — owner, background-task digest, or dispatch task. The guard only claims "N identical calls with nothing else happening", and a new message is something else happening.

guard is optional on CodeoidConfig (like hooks) so the 11 existing hand-built config fixtures still typecheck. The Zod schema still defaults it, so anything through loadConfig has it populated.

Also included

Starts the Model Experience / KV Cache effect doc convention (prior-art §4.9): any feature that changes what the model sees states what reaches it and whether it invalidates the prompt prefix. The guard's FEATURES.md entry is the first adopter.

Testing

28 new tests. Full suite 2338 pass / 0 fail across 155 files; typecheck and biome clean.

Worth noting: I first wrote the chain-key separator as a literal NUL byte. It typechecked, it linted, and all tests passed — src/tests/source-hygiene.test.ts was the only thing that caught it, exactly as its docblock predicts. Fixed to the six-character escape, with a test pinning why NUL is the right separator (a tool named Read {"x":1} can't forge a collision with Read + {x:1}).

Not included

dsh also ships a per-tool timeout guard. It doesn't port: dsh arms a deadline on exec.signal inside its own tools/execute pipeline because it owns tool execution. We don't — the backend runs the tool and we observe tool_start/tool_complete, so we can't abort one in-flight tool, only interrupt the whole turn (which turnStallTimeoutMs already does). Closed as not-applicable at this integration boundary rather than deferred.

🤖 Generated with Claude Code