[Feature request] Guard against re-issuing identical tool calls across turns (cross-turn tool-call loop guard)

[msoukhomlinov]

Summary

An agent can fall into a silent, unbounded loop: issuing the exact same tool call (same tool, same arguments) every turn, reading the result, concluding "let me try a different approach," and then issuing the same call again, repeating dozens of times until a human aborts. This was reported and reproduced in #1326 (closed): 3 loops, 52 identical iterations (e.g. 23× a grep, 20× a zodToJsonSchema script, 9× a sed read), with no harness layer detecting or interrupting it.

I'm bringing this to Discussions per the new contribution process in CONTRIBUTING.md (Issue queue → maintainer work queue; public feedback starts here). I searched existing Discussions and found none on this topic, so this is not a duplicate. There is already maintainer-level interest and a concrete design sketch on the issue thread (see BILLKISHORE's comment on #1326), which I've built on and grounded against current main.

The idea is a cross-turn tool-call loop guard: a bounded, in-memory detector that notices when the same (toolName, inputHash) pair recurs on N consecutive turns and injects a single, non-blocking advisory message so the model is nudged to change approach, while still letting a legitimately repetitive call (e.g. a poll loop waiting on a build) continue.

Why this needs a harness-level guard (not just a model fix)

• The failure is model-agnostic and reproducible across providers. Even Claude Code still ships open reports of the same bug, e.g. the same grep called 30-50× (claude-code#59318), 10+ identical Reads on one file (#53578), an identical failing Edit retried repeatedly (#29944). A deterministic harness counter is the reliable layer.
• On main today there is no guard of any kind: I verified packages/agent and packages/ai contain no max-turn/max-tool-call limit and no repetition detector. Related [stack 8/8] fix(runtime): bound transcript and autonomous recovery #1165 (degenerate text repetition + dropping duplicate tool results during transcript repair) is closed and not merged, and targets a different phenomenon anyway; it would be complementary, not redundant.
• The cost is real: dozens of inference calls burned, transcript polluted with 50+ identical call/result pairs, and in autonomous mode the loop can run unbounded.

Proposed design (grounded in current main, commit 97b994c)

• Hook point: the shared agent loop runLoop in packages/agent/src/agent-loop.ts (lines 307-461). Per turn, tool calls are extracted at line 358 (message.content.filter(c => c.type === "toolCall")) and executed at line 363. The guard records the turn's (toolName, inputHash) pairs there, and delivers the advisory via the loop's existing pendingMessages injection block (lines 337-345), the same mechanism already used for steering messages, before the next streamAssistantResponse at line 348.
• Detector is a pure function in a new packages/agent/src/tool-loop-guard.ts: detectToolCallLoop(ring, threshold) over a bounded ring buffer of (toolName, inputHash) entries. It fires only when the same pair appears on N consecutive turns, not N-1, not when the input differs by a byte, not on alternating calls, and is disabled at threshold <= 0. This matches the design constraints already agreed on the issue thread and keeps it trivially unit-testable.
• inputHash is canonicalized (recursively sorted JSON keys) so harmless key-ordering/metadata churn doesn't cause a false "different input"; a known false-negative risk in gemini-cli's verbatim-args hashing, which we avoid. A genuine content change still resets the run.
• Intervention is warn-and-continue: inject exactly one advisory system-role message and let the turn proceed (no abort, no auto-compact). Then reset the counter so a legitimate repeated call can't trigger a message every turn. This is the friendlier, prior-validated default (oh-my-pi does this; gemini-cli's ask-the-user gate was reported as a pipeline breaker in scripts).
• Config: an optional toolLoopGuard field on AgentLoopConfig (following the existing camelCase optional-field convention), default threshold 5 (industry consensus), default enabled, with a clean disable (threshold 0 / disabled: true) and an optional PI_AGENT_TOOL_LOOP_THRESHOLD env override following the repo's PI_* env-var convention.
• Exempt/polling tools: a small exempt allowlist so keep-alive/poll/status tools that legitimately repeat aren't flagged (prevents the "legit poll loop" false positive discussed on the issue).

Prior art that validates this approach

• oh-my-pi ships ToolCallLoopGuard (can1357/oh-my-pi), default threshold 5, canonicalized args hash, hidden system redirect that lets the turn continue, the closest match to the design above. Its origin issue #3971 notes "threshold 3 is too aggressive for bash/read"; its extreme case #6315 (11k identical sends from a budget-aborted subagent) shows an advisory alone has a ceiling when a model ignores steering.
• gemini-cli has LoopDetectionService (fires on 5 consecutive identical calls / repeating cycles), but it stops and asks the user, a documented pipeline breaker (#19953), and still has open false-positive issues (#18551).
• Claude Code interjects on repetition but the built-in guard is late/narrow/model-dependent, as the open issues above show.

These independently converged on the same signal (identical tool call repeated N times, N≈5) and on "nudge, then continue" as the least-disruptive intervention, which is exactly what this proposes.

Scope (v1) and limitations

• v1 compares (toolName, inputHash) only, with no output comparison and no ratio heuristic. Comparing outputs is expensive and brings its own failure modes; a short, truncated result summary in the advisory gives the model steering context without making outputs part of the detection signal.
• The advisory is non-blocking. That has a ceiling: if the model ignores it, an escalation (hard stop or park after K more turns of no progress) can be added later. It is not part of this first PR, but prior art (#6315) shows an ignored advisory is not enough at the extreme.
• Alternating cycles (edit→build→edit→build) are out of scope here; v1 covers identical consecutive calls.

Files I'd touch if invited

• packages/agent/src/tool-loop-guard.ts (new): contains ToolLoopEntry, pure detectToolCallLoop, advisory builder
• packages/agent/src/agent-loop.ts: wire the ring into runLoop + advisory injection/reset
• packages/agent/src/types.ts: add optional toolLoopGuard to AgentLoopConfig
• packages/agent/src/agent.ts: createLoopConfig default (5) / env / disable resolution
• packages/agent/test/tool-loop-guard.test.ts: pure-function unit tests
• packages/agent/test/agent-loop.test.ts: one integration test for advisory injection (matching the existing multi-turn test style)

Offer

Happy to draft a PR implementing this, following the development guide, adding the tests, and describing validation. I will wait for a maintainer invitation before opening anything, per the current contribution policy, and am happy to adjust threshold defaults, naming, or scope to fit the roadmap.

For the maintainers:

1. Does this fit the roadmap? Standalone guard, or fold it into any in-flight loop hardening?
2. Is default threshold 5 and on-by-default acceptable, or prefer opt-in initially?
3. Any preference on naming / config shape (toolLoopGuard, env var)?
4. Is the v1 advisory-first scope acceptable, with escalation as a follow-up?

No credentials, keys, prompts, or other sensitive info included.

[msoukhomlinov]

@kevinjosethomas Following up on #1326, which you closed when Prime Agent moved to the discussion-first process. I've brought it here per the new CONTRIBUTING.md guidance (searched first, no duplicate) with a proposed design and an offer to draft a PR. Would be glad to hear if this fits the roadmap.