> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wednesdayai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool-loop detection

> Configure optional guardrails for preventing repetitive or stalled tool-call loops

# Tool-loop detection

WednesdayAI can keep agents from getting stuck in repeated tool-call patterns.
Most of the guard is **disabled by default**; enable it only where needed, because strict settings can block legitimate repeated calls.

One detector, `sameErrorRepeat`, is **on by default**, as upstream OpenClaw's repeat guard is. It blocks a tool that keeps failing with the same error even when its arguments change. To turn it off, set `detectors.sameErrorRepeat: false`, or set `enabled: false` to turn off every detector.

## 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 theme={"dark"}
{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
        sameErrorRepeat: true,
      },
    },
  },
}
```

Per-agent override (optional):

```json5 theme={"dark"}
{
  agents: {
    list: [
      {
        id: "safe-runner",
        tools: {
          loopDetection: {
            enabled: true,
            warningThreshold: 5,
            criticalThreshold: 15,
          },
        },
      },
    ],
  },
}
```

### Field behavior

* `enabled`: Master switch for `genericRepeat`, `knownPollNoProgress`, `pingPong` and the global circuit breaker (default: false). When unset, only `sameErrorRepeat` runs. An explicit `false` turns every detector off.
* `historySize`: number of recent tool calls kept for analysis (default: 30).
* `warningThreshold`: warning threshold before a warning-only loop classification (default: 10). Must be lower than `criticalThreshold`.
* `criticalThreshold`: critical threshold for blocking repetitive loops (default: 20). Must be lower than `globalCircuitBreakerThreshold`.
* `globalCircuitBreakerThreshold`: global no-progress breaker threshold (default: 30).
* `detectors.genericRepeat`: warns when the same tool is called with the same arguments `warningThreshold` times.
* `detectors.knownPollNoProgress`: warns, then blocks, known polling tools whose output stops changing.
* `detectors.pingPong`: warns, then blocks, alternating `A/B/A/B` calls that make no progress.
* `detectors.sameErrorRepeat`: warns at `warningThreshold` and blocks at `criticalThreshold` when one tool fails with the same error that many times in the current run, even if its arguments change. Only failures still within the last `historySize` tool calls count, so the block lifts once other tool calls push them out of that window. A success of that tool resets the count, and a new run starts from zero.

## Recommended setup

* Start with `enabled: true`, defaults unchanged.
* If false positives occur:
  * raise `warningThreshold` 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, WednesdayAI 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, only `sameErrorRepeat` runs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.