Feature request: improve agent looping detection

[pshickeydev]

A common frustration I have with the agentic paradigm is an agent trying the same unsuccessful approach to a problem. Crush already detects loops, but this doesn't catch more subtle cases like a UI fix not working which doesn't surface an error code. I'm not super clear on a great solution to this problem and want to open a discussion for other input. I had Kimi K3 investigate to kick things off and this may be possible to some extent with user defined hooks. I'll include that below for reference.

---

Loop-Detection Investigation & Plan

What already exists

Crush already has one loop detector, added in af86738e (fix #2130/#2214):

• internal/agent/loop_detection.go — hasRepeatedToolCalls(steps, windowSize=10, maxRepeats=5) hashes each step's tool interactions (tool name + input + output, SHA-256) and returns true when any identical signature appears >5 times within the last 10 steps.
• Wired as a fantasy StopCondition at internal/agent/agent.go:1058-1060. When it fires, the stream simply ends; the last assistant message gets FinishReasonToolUse → treated as end-of-turn. There is no user-visible signal that a loop was detected — the turn just stops, indistinguishable from the agent finishing.

Why it misses the frustrating scenarios

The current detector is exact-match only. The common stuck cases escape it:

1. Subtle-input drift: editing the same file with slightly different content each attempt (edit with tweaked old_string) produces a different signature every time. Same for bash retries with reordered flags.
2. Output variance: the output is part of the hash. A failed UI fix verified by a screenshot, a build with different error line numbers, or a test run with varying output never repeats its signature.
3. A→B→A→B cycles: alternating between two approaches (fix CSS → screenshot → tweak → screenshot) means neither signature exceeds 5-in-10.
4. Semantic repetition: "same approach" is often only visible at the intent level (same file, same goal), not at the string level.

Intervention points available

Point	Location	What it can do
StopWhen conditions	agent.go:1036-1061	See full []fantasy.StepResult history (calls, inputs, outputs); stop the turn. Cheap, deterministic.
OnStepFinish	agent.go:983	Fires per step; can inspect and record state (e.g. per-session tracker).
PrepareStep	agent.go:808-879	Can inject messages into prepared.Messages before each model call — e.g. a system nudge "you've attempted X 3 times, change approach" — instead of hard-stopping.
hookedTool.Run	hooked_tool.go:54-100	Sees every tool call + result; can deny/halt/inject context. Runs before permission checks.
User hooks	internal/hooks/ (only EventPreToolUse exists)	Users could already write their own detector today via a PreToolUse hook that tracks state externally.
FinishReason + UI banner	internal/message/content.go:36-48	New reason (e.g. loop_detected) would let the TUI show why the turn stopped.

Proposed design (layered)

1. Extend detection beyond exact-match

Replace/augment loop_detection.go with escalating signature levels:

• (a) name+input+output (current): exact repeat detection.
• (b) name+input only: catches output variance, e.g. repeated failed builds or screenshot-verify loops.
• (c) name+target-file only: catches edit-drift on one file.
• Cycle detection: detect period-2/period-3 patterns (A→B→A→B) over name+target signatures within the window, not just single-signature counts.
• Same-target counter: N consecutive steps mutating the same file path without a successful test/build between them is a strong "stuck on UI fix" signal.

Coarser signatures get lower thresholds to compensate for higher false-positive risk.

2. Escalating response instead of binary stop

Via PrepareStep message injection:

• Soft threshold (e.g. 3 repeats): inject a system message telling the model it's repeating itself and must change strategy. Keeps the agent autonomous while breaking the pattern — addresses the "no error code" case where a hard stop loses work.
• Hard threshold (current behavior, tuned): stop the turn.

3. Surface it to the user

• Add FinishReasonLoopDetected (or use AddFinish with a message) and render a banner in the TUI, so a stopped turn explains itself. Currently the stop is silent.

4. Configurability

Both config formats, deep-merged through the same pipeline.

crush.json (existing format, unchanged schema path):

{
  "options": {
    "loop_detection": {
      "enabled": true,
      "window_size": 10,
      "max_repeats": 5,
      "soft_nudge_threshold": 3,
      "detect_cycles": true
    }
  }
}

crushrc (Bash format, via the option builtin in internal/shellconfig/options.go):

option loop-detection true
option loop-detection-window-size 10
option loop-detection-max-repeats 5
option loop-detection-soft-nudge-threshold 3
option loop-detection-cycles true

Implementation follows the existing shellconfig patterns:

• Add LoopDetection *LoopDetectionConfig json:"loop_detection,omitempty"`` to the options struct in internal/config/config.go (with jsonschema descriptions so it appears in the JSON schema), keeping `enabled` as a positive user-facing key mapped to a negatively-stored field only if the config convention requires it (see `disable_metrics` vs `metrics` at `internal/shellconfig/options.go:22-24`).
• Register the five kebab-case keys in optionSpecs (internal/shellconfig/options.go:180): loop-detection and loop-detection-cycles as optBool; loop-detection-window-size, loop-detection-max-repeats, and loop-detection-soft-nudge-threshold need a new optInt kind (the spec table currently has only string/bool/list at options.go:155-159) so values are validated and stored as numbers, not strings.
• Each key writes into a nested loop_detection map under options, the way attribution-* keys write into a nested map via childMap (options.go:87-107) — either via a child field on optionSpec or as special cases in handleOption.
• No changes needed in the loader: shell configs and JSON configs are discovered together and deep-merged by the same pipeline, so JSON users are unaffected and crushrc users get the new keys for free once the builder emits them.
• Tests: extend internal/shellconfig/options_test.go cases for each new key (including bool default-to-true shorthand and int validation errors), mirroring the existing table tests.

5. Optional: PostToolUse hook event

Today only EventPreToolUse exists, which can't see tool outcomes. A PostToolUse event would let users implement their own detection with full call+result context.

Suggested starting point

The highest-value, lowest-risk change is (3) surfacing the existing detector plus (2) the soft-nudge injection via PrepareStep — both reuse existing mechanisms with no new infrastructure. Level-(b)/(c) signatures and cycle detection are incremental extensions to the well-tested hasRepeatedToolCalls.