> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openaeon.ai/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

OpenAEON 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 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    loopDetection: {
      enabled: false,
      historySize: 20,
      detectorCooldownMs: 12000,
      repeatThreshold: 3,
      criticalThreshold: 6,
      detectors: {
        repeatedFailure: true,
        knownPollLoop: true,
        repeatingNoProgress: true,
      },
    },
  },
}
```

Per-agent override (optional):

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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.

## Recommended setup

* 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, OpenAEON 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.