feat: add configurable tool loop detection

docs/tools/index.md

@@ -224,6 +224,35 @@ Notes:
 - `log` supports line-based `offset`/`limit` (omit `offset` to grab the last N lines).
 - `process` is scoped per agent; sessions from other agents are not visible.
 
+### `loop-detection` (tool-call loop guardrails)
+
+OpenClaw tracks recent tool-call history and blocks or warns when it detects repetitive no-progress loops.
+Enable with `tools.loopDetection.enabled: true` (default is `false`).
+
+```json5
+{
+  tools: {
+    loopDetection: {
+      enabled: true,
+      warningThreshold: 10,
+      criticalThreshold: 20,
+      globalCircuitBreakerThreshold: 30,
+      historySize: 30,
+      detectors: {
+        genericRepeat: true,
+        knownPollNoProgress: true,
+        pingPong: true,
+      },
+    },
+  },
+}
+```
+
+- `genericRepeat`: repeated same tool + same params call pattern.
+- `knownPollNoProgress`: repeating poll-like tools with identical outputs.
+- `pingPong`: alternating `A/B/A/B` no-progress patterns.
+- Per-agent override: `agents.list[].tools.loopDetection`.
+
 ### `web_search`
 
 Search the web using Brave Search API.

docs/tools/loop-detection.md

@@ -0,0 +1,98 @@
+---
+title: "Tool-loop detection"
+description: "Configure optional guardrails for preventing repetitive or stalled tool-call loops"
+read_when:
+  - A user reports agents getting stuck repeating tool calls
+  - You need to tune repetitive-call protection
+  - You are editing agent tool/runtime policies
+---
+
+# Tool-loop detection
+
+OpenClaw 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.
+
+## 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, OpenClaw 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.