dsh-loop-guard
Result-aware stuck-loop guard for DeepSeek Harness: advisory nudges plus a monotonic hard stop.
Why
A stage that repeats the same tool call and keeps getting the same result is stuck — it burns steps (and tokens) without producing new information. This plugin ports a guard that ran for weeks in front of a multi-harness LLM gateway, where the two-stage design measurably turned aborted agentic runs into completed ones (the pattern follows OpenHands' StuckDetector lineage).
The key design decision is that only repeats with identical results count. Requiring result identity whitelists legitimate repeats for free, with no tool-name configuration:
- polling a job status that progresses → results differ → never triggers
- re-reading a file after an edit → result differs → never triggers
- retrying a flaky command that eventually behaves differently → never triggers
How it relates to @deepseek-ai/dsh-repeat-tool-reminder
The official base bundle already ships an advisory repeat detector. This plugin is complementary, not a replacement:
| repeat-tool-reminder (official) | dsh-loop-guard |
|---|
| Chain identity | tool name + arguments | tool name + arguments + result |
| Progressing poll loops | trigger reminders (unless excluded by pattern) | transparent, never trigger |
| Enforcement | never — advisory only, by design | denies further identical calls at the hard threshold |
| A model that ignores reminders | loops until the turn/budget dies | stopped, with corrective feedback it can act on |
Running both is fine: the reminder nudges early on argument-identical repeats; this guard only engages when the loop is provably sterile (identical results), and it is the only one of the two that can end it. The denial is a normal error result — the session survives and the model gets corrective feedback, which matters for frontends that treat provider-level 4xx errors as fatal.
Install
dsh plugin --profile <name> add github:erdholion/dsh-loop-guard
Or from a local checkout: dsh plugin --profile <name> add ./dsh-loop-guard.
Behavior
Per agent, the guard tracks the run length of consecutive tool calls with identical (name, canonically key-sorted arguments) and identical result content.
- Soft stage (run ≥
softThreshold, default 4): each further identical repeat injects a plugin-sourced notice after the tool result telling the model the calls are identical, that repeating will be denied at the hard threshold, and to act on what it already knows.
- Hard stage (run ≥
hardThreshold, default 8): a monotonic tool guard denies the next identical call with corrective feedback. Non-identical calls are unaffected; the chain freezes while denials repeat, so the guard stays engaged until the model changes its action.
- Reset: a genuine user interjection (
source.kind === 'user') resets the chain — repetition across a user message is not a loop. The guard's own injected notices are plugin-sourced and do not reset anything.
Config
- id: loop-guard
name: dsh-loop-guard
config:
softThreshold: 4 # 0 disables nudges
hardThreshold: 8 # 0 disables denial; must exceed softThreshold
resultHashChars: 4000 # serialized-result prefix that participates in the hash
Invalid config (non-integer, negative, hard ≤ soft) throws at plugin load — a misconfigured guard fails loud, never silently.
License
MIT
