Summary

• Problem: generic repeated tool calls only warned even when the same calls kept returning identical no-progress outcomes.
• Why it matters: agents could keep spending model/tool cycles after a loop warning instead of stopping at the configured critical threshold.
• What changed: generic repeat detection now escalates identical tool+args+outcome loops to a critical block at criticalThreshold; docs and tests describe the no-progress requirement.
• What did NOT change (scope boundary): repeated calls with changing outcomes still warn instead of hard-blocking; the global circuit breaker remains a fallback.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #
• Related #
• This PR fixes a bug or regression

Real behavior proof (required for external PRs)

• Behavior or issue addressed: generic same-tool/same-args loops now stop when repeated calls also return identical outcomes.
• Real environment tested: local OpenClaw source checkout on macOS with Node/pnpm.
• Exact steps or command run after this patch: pnpm test src/agents/pi-tools.before-tool-call.e2e.test.ts
• Evidence after fix (screenshot, recording, terminal capture, console output, redacted runtime log, linked artifact, or copied live output): test output reported 42 passing tests, including the generic repeat escalation coverage.
• Observed result after fix: generic repeat diagnostics escalate from warning at 10 calls to critical block at 20 identical no-progress outcomes.
• What was not tested: live provider behavior against a real model.
• Before evidence (optional but encouraged): prior test coverage expected generic repeats to remain warn-only until the global circuit breaker.

Root Cause (if applicable)

• Root cause: the generic repeat detector only emitted warnings for repeated tool+args patterns and did not apply criticalThreshold to repeated no-progress outcomes.
• Missing detection / guardrail: generic loops had no critical no-progress stop before the global circuit breaker.
• Contributing context (if known): specialized poll and ping-pong detectors already had critical paths, but generic repeats did not.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/agents/tool-loop-detection.test.ts, src/agents/pi-tools.before-tool-call.e2e.test.ts
• Scenario the test should lock in: same tool, same args, and identical outcomes escalate from warning to critical at criticalThreshold; changing outcomes remain warnings.
• Why this is the smallest reliable guardrail: it exercises the detector directly and through the before-tool-call wrapper without invoking a live model.
• Existing test that already covers this (if any): N/A

User-visible / Behavior Changes

Agents with tools.loopDetection.enabled now abort generic repeated no-progress tool loops at criticalThreshold instead of waiting for the global circuit breaker.

Diagram (if applicable)

Before:
same tool + same args + same outcome -> warning -> warning until global circuit breaker

After:
same tool + same args -> warning
same tool + same args + same outcome -> critical block at threshold

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) Yes
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation: the tool loop guard can now block repeated generic no-progress tool calls sooner. It only blocks after identical outcomes, while changing outcomes remain allowed.

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local Node/pnpm source checkout
• Model/provider: N/A
• Integration/channel (if any): N/A
• Relevant config (redacted): tools.loopDetection.enabled: true

Steps

1. Enable loop detection.
2. Repeat a generic tool call with identical arguments and identical outcomes until criticalThreshold.
3. Repeat a generic tool call with identical arguments but changing outcomes.

Expected

• Identical no-progress outcomes are blocked at criticalThreshold.
• Changing outcomes are not hard-blocked by the generic detector.

Actual

• Matches expected.

Evidence

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: generic repeat warning, generic repeat critical block, run-id isolation, exec outcome normalization, changed-scope gate.
• Edge cases checked: changing exec output remains warning-only; global circuit breaker still works when generic repeat is disabled.
• What you did not verify: live model/provider run.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps: N/A

Risks and Mitigations

• Risk: legitimate repeated generic calls with identical outcomes may stop earlier than before.
  • Mitigation: the guard requires identical outcomes, preserves warning-only behavior for changing results, and remains controlled by tools.loopDetection.enabled and criticalThreshold.