​

Tool-loop detection

​

Why this exists

• Detect repetitive sequences that do not make progress.
• Detect high-frequency no-result loops (same tool, same inputs, repeated errors).
• Detect specific repeated-call patterns for known polling tools.

​

Configuration block

{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            warningThreshold: 8,
            criticalThreshold: 16,
          },
        },
      },
    ],
  },
}

​

Field behavior

• enabled: Master switch. false means no loop detection is performed.
• historySize: number of recent tool calls kept for analysis.
• warningThreshold: threshold before classifying a pattern as warning-only.
• criticalThreshold: threshold for blocking repetitive loop patterns.
• globalCircuitBreakerThreshold: global no-progress breaker threshold.
• detectors.genericRepeat: detects repeated same-tool + same-params patterns.
• detectors.knownPollNoProgress: detects known polling-like patterns with no state change.
• detectors.pingPong: detects alternating ping-pong patterns.

​

Recommended setup

• Start with enabled: true, defaults unchanged.
• Keep thresholds ordered as warningThreshold < criticalThreshold < globalCircuitBreakerThreshold.
• If false positives occur:
  • raise warningThreshold and/or criticalThreshold
  • (optionally) raise globalCircuitBreakerThreshold
  • disable only the detector causing issues
  • reduce historySize for less strict historical context

​

Logs and expected behavior

• Prefer warning and temporary suppression first.
• Escalate only when repeated evidence accumulates.

​

Notes

• tools.loopDetection is merged with agent-level overrides.
• Per-agent config fully overrides or extends global values.
• If no config exists, guardrails stay off.