openclaw/docs/plugins/codex-harness
Ayaan Zaidi 3a3eed8695
refactor(agents): replace tool-loop detectors with an arguments-only repeat guard (#199591)
## Problem

The tool-loop guard was 12 files and about 1,700 lines. It hashed tool outcomes, had name checks for single tools (exec, message, wait, memory_search, computer, progress_card, write, process), and had four separate detectors plus a post-compaction guard. Rolling detection was opt-in, so most installs did not use it.

One part was always on: after 3 identical failing calls, the next identical call ended the turn. The model got no chance to answer, and the user got a stop message in place of an answer.

## Fix

One guard in `packages/agent-core/src/tool-repeat-guard.ts` (105 lines), used by the agent loop:

- It compares each tool call with the call before it. It compares the tool name and the canonical arguments only. It never compares outcomes.
- 3rd identical call in a row: the call runs, and a redirect note is added to its result. The note names the tool and tells the model to change its approach.
- 20th identical call in a row: the call does not run. The turn ends with the typed reason `tool_repeat_limit` and this message: `OpenClaw stopped this turn: the model called <tool> with the same arguments 20 times in a row. Send a new message to continue.`
- Tools declare `repeatable` themselves and skip the check: Code Mode `wait`, `process` poll/log/list, `agents_wait`, `sessions_yield`, `subagents` list/wait, `computer` screenshot/wait. The declaration is plain data (`true` or `{ actions: [...] }`), so it crosses the worker wire.
- Worker turns (cloud and node workers) run the same guard over all their tools. The Gateway resolves `tools.loopDetection.enabled` (agent over global) into the worker tool-surface policy as `toolRepeatGuard`, and each tool definition carries its `repeatable` exemption. Two optional fields are added to the closed worker tool-surface schema (`definition.repeatable`, `policy.toolRepeatGuard`); worker bundles are build-bound to the Gateway.
- Calls to an unknown tool are keyed by name.
- New user input resets the streak.

Removed: outcome hashing, per-tool checks, argument churn, ping-pong, the rolling history, batch admission and recovery state, the post-compaction guard, the "3 identical failures" hard stop and its error code. Repeated identical failing calls now get the same note and cap as any other repeat.

Config:

- `tools.loopDetection.enabled` stays. `false` turns the guard off. Unset or `true` keeps it on. This also folds the rolling detection that was opt-in into the one default rule.
- The Codex `appServer.loopDetectionPreToolUseRelay` key is retired. `openclaw doctor --fix` removes it.
- The `tool.loop` diagnostic event stays, with `detector: "tool_repeat"`.

## User impact

- A model that repeats a failing call now gets a note and can still answer, instead of the turn ending after 3 failures.
- A model stuck on one call is stopped after 20 identical calls with a clear message, on local and worker turns alike.
- `tools.loopDetection.enabled: false` still turns the guard off. Existing configs keep loading; `openclaw doctor --fix` removes the retired keys.

## Proof

| Check | Tier | Base (`5d5ca9d2`) | Head (`ecb05477`) |
|---|---|---|---|
| Unit: note at 3rd identical call, stop at 20th with `tool_repeat_limit`, repeatable tools skip, unknown tool keyed by name, guard off when disabled (`tool-repeat-guard.test.ts`) | vitest-source | n/a (new) | 10/10 pass |
| Regression: 4 identical failing calls, then the model answers | vitest-source | **fails**: turn ends after 3 failures, no answer | pass |
| Real Gateway, mock model repeats one failing read (`tool-loop-global-breaker`, step 1) | dist-nodts | **fails**: Gateway logs `OpenClaw stopped this turn: the same read call failed 3 times`, run ends in error with no answer | pass: note on 3rd read, model recovers with its final answer |
| Real Gateway, mock model ignores the note (step 2) | dist-nodts | n/a | pass: exactly 20 reads, 20th not run, user sees the `tool_repeat_limit` message |
| Regression: worker turn with loop detection on, `progress_card` called 3 times with `{"markdown":"Still working"}` gets the redirect note on the 3rd result; with `tools.loopDetection.enabled: false` it gets none (`worker.runtime.test.ts`, real worker runtime + fake Gateway) | vitest-source | **fails** on `a3f26f46` (worker forced `enabled: false`) | pass |
| Gateway policy: `toolRepeatGuard: false` only when loop detection is off; agent setting overrides global (`prepared-tool-surface.test.ts`) | vitest-source | n/a (new) | pass |
| Upgrade: config written by latest stable `2026.11.3` (`tools.loopDetection.enabled`, Codex `appServer.loopDetectionPreToolUseRelay` + `requestTimeoutMs`) plus the old sub-keys (`windowSize`, `historySize`, `warningThreshold`, `criticalThreshold`, `globalCircuitBreakerThreshold`, `detectors`, `postCompactionGuard`, which stable already rejects, as left by older releases); stable Gateway runs turn 1 on a mock model; head `openclaw doctor --fix`; head Gateway starts and runs turns 2 and 3 on the same session (fresh HOME, throwaway ports) | source CLI | | pass: doctor removes every retired key and keeps `enabled` and `requestTimeoutMs`; head Gateway starts on the migrated config; turn 2 answers; turn 3's provider request contains turn 1's reply, so the session survives |
| `packages/agent-core` | vitest-source | | 29 files, 343 tests pass |
| 51 touched unit test files + 2 before-tool-call e2e files | vitest-source | | pass |
| `pnpm check:test-types`, `pnpm tsgo:scripts`, `tsgo:core`, `tsgo:extensions` | type | | pass |
| Full build with declarations + packed tarball check | full | | pass; guard in package, old symbols absent |
| `rg` for every removed symbol across `src/ scripts/ test/ extensions/ packages/` | static | | 0 hits |

## Net lines

`209 files changed, 1275 insertions(+), 9989 deletions(-)` (net -8,714)

- Source: +815 / -3,585 (net -2,770; includes the regenerated `predicates.js` validator)
- Tests: +391 / -6,198 (net -5,807)
- Docs: +69 / -206 (net -137)

Co-authored-by: Ayaan Zaidi <hi@obviy.us>
2026-11-16 10:29:21 +05:30
..
app-server.md docs: add a complete split-storage setup example (#184900) 2026-10-28 12:05:40 -07:00
commands.md docs: clarify Codex pre-turn tool verification (#189974) 2026-11-01 10:29:29 +08:00
config-fields.md fix: make Daybreak independent of retiring model aliases (#177812) 2026-10-26 05:17:07 +08:00
configuration.md fix(codex): refresh inherited workspace instructions on the next turn (#191439) 2026-11-03 04:32:02 +08:00
native-features.md fix(codex): keep native tool declarations stable on completion turns (#183286) 2026-10-24 23:54:33 -07:00
placement.md
routing.md
runtime-behavior.md fix(codex): apply plugin input rewrites to native tools (#189887) 2026-11-03 12:55:03 +08:00
troubleshooting.md refactor(agents): replace tool-loop detectors with an arguments-only repeat guard (#199591) 2026-11-16 10:29:21 +05:30