Tool-loop detection

Mayros can keep agents from getting stuck in repeated tool-call patterns. The guard is disabled by default.

Enable it only where needed, because it can block legitimate repeated calls with strict settings.

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

Global defaults:

json5
{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 20,
      detectorCooldownMs: 12000,
      repeatThreshold: 3,
      criticalThreshold: 6,
      detectors: {
        repeatedFailure: true,
        knownPollLoop: true,
        repeatingNoProgress: true,
      },
    },
  },
}

Per-agent override (optional):

json5
{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            repeatThreshold: 2,
            criticalThreshold: 5,
          },
        },
      },
    ],
  },
}

Field behavior

  • enabled: Master switch. false means no loop detection is performed.
  • historySize: number of recent tool calls kept for analysis.
  • detectorCooldownMs: time window used by the no-progress detector.
  • repeatThreshold: minimum repeats before warning/blocking starts.
  • criticalThreshold: stronger threshold that can trigger stricter handling.
  • detectors.repeatedFailure: detects repeated failed attempts on the same call path.
  • detectors.knownPollLoop: detects known polling-like loops.
  • detectors.repeatingNoProgress: detects high-frequency repeated calls without state change.
  • Start with enabled: true, defaults unchanged.
  • If false positives occur:
    • raise repeatThreshold and/or criticalThreshold
    • disable only the detector causing issues
    • reduce historySize for less strict historical context

Logs and expected behavior

When a loop is detected, Mayros reports a loop event and blocks or dampens the next tool-cycle depending on severity. This protects users from runaway token spend and lockups while preserving normal tool access.

  • 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.