pi-anti-doom-loop

Stop agent doom loops in pi before they burn tokens.

Cheap models sometimes get stuck repeating the same cheap tool call — grep the same file, re-run the same failing command — with no progress. Each iteration is so cheap nobody notices until the bill mounts. This extension watches every tool call and blocks the loop at the source.

Install

pi install npm:pi-anti-doom-loop

What it detects

Blocks hand the model an instructive reason ("change your approach, use a different tool, or ask the user"). If the model ignores the block and re-issues the exact same call, the turn is aborted.

Escalation (text loops): steer → abort → bounded resume

The first text-loop detection steers the agent mid-run (injects guidance, lets it continue). If it persists, the run is aborted and one fresh- resume directive is queued so work continues with a new approach. If it still loops after that, the run aborts for real and control returns to you — the auto-resume budget is capped per session (a new prompt does not restore it) so a truly stuck model can't cycle forever. Detection counters reset on every user prompt, so a task legitimately repeated later in the same session is never a false positive.

Every state machine behind this behaviour — states, invariants, and the transitions the code allows — is documented in docs/state-machines.md.

Configuration

Environment variables, read at session/prompt start:

When the agent needs to repeat anyway

Some repeats are correct. Polling a job, waiting on a deploy to go green, or re-running one flaky step all mean calling the same thing again — and the reason lives in the agent's head, not in the arguments. Blocking those just forces a workaround.

So a repeat block is overridable by the agent itself, through a loop_ack tool registered by this extension:

1. A repeat block names it, in the block reason: "If this repeat is intentional … call loop_ack and say why."
2. The agent calls loop_ack with the reason.
3. The call it just got blocked on is cleared from the window — and so is the whole near-identical cluster behind the block, so a retry whose args drifted (the head, a sleep wrapper) is not instantly re-blocked — and the retry runs.

It acts on the last block, so the agent never re-sends the arguments — the detector already has them.

It is deliberately narrow:

• Only repeat blocks. A block caused by repeated failures cannot be acknowledged. There the evidence is already in the transcript, and waving it through would remove the guard that stops blind retries.
• Not a repeat that is also failing. If the tool has failed since its last success, the block is a blind retry, and the hint is not offered at all. An acknowledgement never erases failure evidence, so a command that starts failing re-blocks.
• Bounded per tool. One tool can be acknowledged twice per prompt, not more — otherwise "ack, retry, blocked, ack" becomes the loop it was meant to allow. Scoped to the tool rather than the exact call, because a drifting loop changes its arguments on every retry and would otherwise get a fresh allowance each time.
• Reset with everything else on the next user prompt.

Prefer this over the disable switches when only one call is in question.

Turning it off

Loosest to strictest — pick the scope you need:

Pi deep-merges the two settings.json files with the project winning per key, so a project can disable what global enables (and vice versa) without either file repeating the other. Only an explicit false disables: a missing key, a malformed value, or a non-boolean leaves detection on, because a typo must never silently turn off loop detection. The project scope only applies to a trusted project — pi does not read .pi/settings.json otherwise.

Edit either file during a session and the change lands on the next prompt; no restart needed.

Command

• /loopcheck — show thresholds, counters (steers/aborts this session), suspend state, the current window contents (most-repeated recent calls and texts), repeated-argument token count, and the fail-rate/time-window/exclude config when enabled
• /loopcheck reset — clear counters
• /loopcheck suspend — pause detection until the next prompt (escape hatch for intentional repetition)
• /loopcheck resume — re-enable detection early

Codemode (pi ≥ 0.99): nested script calls

pi's codemode tool lets the model run a JavaScript script that calls other tools via tools.<name>(args) — a script can loop hundreds of calls inside ONE top-level tool call, which per-call detection never sees as a streak. Since pi 0.99, those nested calls still flow through the tool_call/ tool_result events tagged with parentToolCallId — and this extension tracks them:

• Stricter in-script threshold — inside one script, the 2nd identical call blocks (top-level detection needs 3). A repeated call inside a script is never progress: the script can store its first result in a variable and reuse it. Near-identical args (sleep-wrapped polls, flag drift) count too.
• Error-retry rule — an identical retry of a call that already errored inside the same script blocks immediately with a "the identical call already failed inside this script" reason.
• Script-level isolation — nested traffic never enters the top-level window and vice versa, so script loops cannot hide from their own 2× rule and legitimate top-level repetition is never inflated by scripts.
• The information wall — a nested block reason reaches the script as a tool error, not the model (only the script's return value does). When a script swallows it anyway, the next assistant message gets a one-shot steer telling the model to call each tool once and reuse results — so the loop signal can never be silently eaten by a script that ignores tool errors.
• Cross-script escalation — counters are per-script (a new script starts clean), but re-issuing a signature blocked in an earlier script this prompt escalates and aborts the turn, mirroring top-level block-escalation.

Huge nested payloads (whole-file reads) are identity-capped (100 KB per call) and each script keeps only its most recent 100 calls, so memory stays bounded. /loopcheck reports nested: calls=N blocks=M.

Scripts are exempt from the top-level near-identical rule. Two different scripts share JS boilerplate (const, await, tools, return), so their shared-token score is ~0.7 — above the 0.55 near-identical bar. Sequential one-off scripts checking different hypotheses are normal exploration, not a loop, and the near-identical rule blocked them. They are therefore compared by exact identity only (the same script re-issued still blocks), while their real loop shape — repeated calls inside one script — stays covered by the nested 2× rule above. If a specific call is a deliberate repeat, the agent can clear it with loop_ack.

Token-cost awareness

The detector estimates the size of repeated argument text (~4 chars/token) and reports it as "~N tokens of repeated arguments." in tool-call block reasons. The cumulative count also appears in /loopcheck status.

It is deliberately not labelled "wasted": for an exploratory session, a repeat can be the productive move, and only the caller knows which. The figure sizes the repetition; it does not judge it.

How it works

Everything hooks into the tool_call / tool_result / message_end events; detection is a small sliding-window counter (see extensions/detector.ts) with per-session counters (steers/aborts) tracked in extensions/controller.ts. Works with any model — cheap models just trigger it more often.

Development

Requires Node 22.18+ and pnpm 12 (pinned via packageManager; the install uses pnpm's virtual store at node_modules/.pnpm).

pnpm install
pnpm test        # node --test: unit + fixture + fuzz + integration + e2e (incl. real-pi e2e)
pnpm run check   # pnpm test + tsc + oxlint --deny-warnings + oxfmt

E2E against real pi ≥ 0.99

tests/e2e/pi.test.ts downloads the real @earendil-works/pi-coding-agent@0.99.2 once (cached in the OS temp dir), then drives it headlessly: an in-process OpenAI-compatible fake LLM scripts the assistant turns, pi's RPC entry runs with THIS repo's extension loaded, and the assertions read the real RPC event stream. Verified scenarios:

• the extension loads into pi 0.99 and blocks a scripted identical-bash doom loop with the instructive block reason
• a real codemode worker executing a script that polls a file 5× inside ONE codemode call gets blocked by the nested 2× rule — the script fails with BLOCKED by anti-doom-loop — inside one codemode script…
• the recommended distinct Promise.allSettled batch completes untouched

Everything is offline (no API keys); if the npm registry is unreachable the real-pi tests skip cleanly instead of failing. Run just them with:

pnpm run e2e:pi

Test suite (Node built-in runner, no framework)

peerDependencies pins @earendil-works/pi-coding-agent at "*" on purpose — the pi packages docs require an unbounded range for pi-core packages (pi provides them at runtime). The extension loads .ts directly via jiti, so no build step ships; prepublishOnly runs the full quality gate before publish. When a call is blocked, escalation still works without recording it in the window: re-issuing the identical call increments a per-signature block counter and aborts the turn on the second block. Thresholds are clamped to a minimum of 2 so a bad config can never brick the agent.

Releasing

Publishing is handled by the GitHub Actions workflow .github/workflows/release.yml, guarded against version drift:

1. Add an npm Automation token as the NPM_TOKEN repo secret (Settings → Secrets and variables → Actions, or gh secret set NPM_TOKEN).
2. Bump version in package.json, commit, then tag and push:

git tag v0.0.1
git push origin v0.0.1

CI runs the quality gate with pnpm, then the version bump guard (pnpm run guard): it blocks publishing if the version is already on npm or the tag doesn't match package.json. After publishing, the workflow polls the registry until the new version is actually installable — npm scans new publishes before serving them, so publish succeeding is not the same as install working. After the first publish, the pi.dev gallery picks the package up automatically via the pi-package keyword.

License

MIT