In DeepSeek Harness workflows, agents can fall into loops where they repeatedly invoke the same tool and continue receiving identical results, wasting steps and tokens. The dsh-loop-guard plugin uses a result-aware mechanism to intervene when the run length of consecutive calls reaches a threshold, issuing an advisory notification or directly rejecting subsequent identical calls.

Core Features

The plugin provides result-aware loop detection for DeepSeek Harness, with three core features:

  1. Result-Aware Tracking
    The plugin tracks the run length of consecutive tool calls that have the same tool name, sorted parameters, and result content. Only fully identical “tool name + parameters + result” combinations count toward the loop counter, so legitimate state polling or file rereads do not trigger false positives.

  2. Soft and Hard Blocking Stages
    * Soft Stage (Advisory): When the run length reaches softThreshold (default 4), the plugin injects an advisory notification informing the model that the current call has been repeated, and warning that it will be rejected once the hard threshold is triggered.
    * Hard Stage (Hard Stop): When the run length reaches hardThreshold (default 8), the plugin explicitly rejects the next identical tool call and includes corrective feedback. The model must change its behavior to clear the block.

  3. User Intervention Reset
    When source.kind === 'user', the chain is reset. This means repeated calls across user messages are not treated as a loop, ensuring that operations can continue after manual user intervention.

Installation and Enablement

Use the official installation command to add the plugin to the specified profile:

dsh plugin --profile <name> add github:erdholion/dsh-loop-guard

You can also install from a local checkout directory:

dsh plugin --profile <name> add ./dsh-loop-guard

Configuration

Add the plugin definition to the DSH configuration file. Note that invalid configuration will cause an error when the plugin loads:

- id: loop-guard
  name: dsh-loop-guard
  config:
    softThreshold: 4     # 0 禁用提示，默认 4
    hardThreshold: 8     # 0 禁用拒绝，必须大于软阈值，默认 8
    resultHashChars: 4000 # 参与哈希的结果序列前缀长度

Typical Usage and Scenarios

This plugin is especially useful in scenarios involving uncertain return values or state changes:

  • Legitimate Polling: Polling calls with different results are allowed (for example, job status checks). As long as the result changes, the loop count does not increase, and the behavior is not misclassified as a dead loop.
  • State Recovery: Re-reading with different results is allowed (for example, reading a file again after editing).
  • Combined Use: It can be used together with the official @deepseek-ai/dsh-repeat-tool-reminder. The reminder plugin provides early warnings for identical parameters, while the loop-guard plugin enforces hard rejection for identical results.

Notes

  • Configuration Constraints: The hard threshold must be strictly greater than the soft threshold; otherwise, plugin loading will fail.
  • Blocking Behavior: A rejection triggered in the hard stage is a normal error result and is returned to the model along with corrective feedback. This is especially important for frontends that treat provider 4xx errors as fatal.
  • Notification Source: Notifications injected by the plugin originate from the plugin itself and do not trigger a chain reset.

Through its result-aware mechanism, the plugin effectively prevents agents from getting stuck in repetitive, non-informative call loops, improving resource utilization efficiency.