PR #63023: fix(agents): break repeated unknown-tool loops

• Repository: openclaw/openclaw
• Author: GaosCode
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63023

Description (problem / solution / changelog)

Fixes #62971

Summary

Fixes a runaway tool-loop case where the model keeps retrying the same missing tool name after receiving a tool not found / unknown tool error.

Current generic tool-loop protection is not enough for this case:

• tools.loopDetection is disabled by default
• even when enabled, generic-repeat warnings start at 10 and blocking only happens much later
• unknown/missing tools are not recoverable by retrying, so the session can burn tokens until the user manually resets it

This PR adds a narrow, dedicated breaker for repeated unknown-tool failures.

Problem

When the model calls a tool name that does not exist, the current turn can get stuck in a retry loop:

1. model calls a missing tool
2. tool execution returns an error like Tool <name> not found
3. model retries the same missing tool
4. loop continues until manual user intervention (/reset, /new, etc.)

Root cause

The repo already has generic tool-loop detection, but it is not sufficient for this failure mode:

• it is opt-in (tools.loopDetection.enabled)
• generic repeated calls are warn-only for a long time
• the existing detectors are tuned for repeated no-progress tool usage, not for immediately fatal missing-tool retries

So repeated unknown-tool failures were being treated like ordinary tool errors instead of a fast-stop condition.

Changes

• add a dedicated unknown_tool_repeat detector
• classify repeated unknown tool / tool not found outcomes in tool-call history
• block the tool call once the same missing tool has already failed twice consecutively with the same arguments
• keep the existing generic loop-detection defaults unchanged
• emit the usual diagnostic tool.loop event/log for this dedicated breaker

Scope boundary

This PR does not:

• change the global default for tools.loopDetection
• retune generic repeat / poll / ping-pong thresholds
• change normal recoverable tool-error handling
• affect successful or progressing tool calls

It only adds a fast-stop path for repeated missing-tool retries.

Reproduction

Minimal local repro before this fix:

const tool = wrapToolWithBeforeToolCallHook(
  {
    name: "some_non_existent_tool",
    execute: async () => {
      throw new Error("Tool some_non_existent_tool not found");
    },
  },
  {
    agentId: "main",
    sessionKey: "repro:unknown-tool-loop",
    loopDetection: { enabled: false },
  },
);

Before this fix:

attempt 1: throws Tool some_non_existent_tool not found
attempt 2: throws Tool some_non_existent_tool not found
attempt 3+: same error continues, no automatic stop

After this fix:

attempt 1: original missing-tool error
attempt 2: original missing-tool error
attempt 3: blocked with a critical breaker message telling the model to stop retrying and ask for correction / installation

Validation

Tests:

pnpm test src/agents/tool-loop-detection.test.ts src/agents/pi-tools.before-tool-call.e2e.test.ts

Build:

pnpm build

Manual repro after patch:

• repeated the same missing-tool call with loopDetection.enabled=false
• confirmed the third identical attempt is blocked by the dedicated breaker
• confirmed diagnostic logging emits detector=unknown_tool_repeat Observed repro output after patch:

attempt 1: threw -> Error: Tool some_non_existent_tool not found
attempt 2: threw -> Error: Tool some_non_existent_tool not found
attempt 3: threw -> Error: CRITICAL: some_non_existent_tool is not an available tool and has already failed 2 consecutive times. Stop retrying this tool call and ask the user to correct the tool name or install the missing tool.

Files

• src/agents/tool-loop-detection.ts
• src/agents/pi-tools.before-tool-call.ts
• src/agents/pi-tools.before-tool-call.runtime.ts
• src/logging/diagnostic-session-state.ts
• src/logging/diagnostic.ts
• src/infra/diagnostic-events.ts
• src/agents/tool-loop-detection.test.ts
• src/agents/pi-tools.before-tool-call.e2e.test.ts

AI Assistance

Made with Codex

Changed files

• src/agents/pi-tools.before-tool-call.e2e.test.ts (modified, +39/-2)
• src/agents/tool-loop-detection.test.ts (modified, +112/-0)
• src/agents/tool-loop-detection.ts (modified, +103/-1)
• src/infra/diagnostic-events.ts (modified, +6/-1)
• src/logging/diagnostic-session-state.ts (modified, +2/-0)
• src/logging/diagnostic.ts (modified, +6/-1)

PR #63041: fix: detect and abort infinite loop when agent repeatedly calls non-existent tools

• Repository: openclaw/openclaw
• Author: yizhi94
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/63041

Description (problem / solution / changelog)

Summary

Fixes #62971

When the agent calls a tool that doesn't exist in the registered tool set, the pi-agent-core SDK returns an immediate error ("Tool X not found") and bypasses all beforeToolCall/afterToolCall hooks. This means OpenClaw's existing tool-loop-detection framework never sees these failures, causing the agent to retry the same non-existent tool indefinitely — burning tokens and never terminating.

This PR adds a dedicated unknown_tool detector that catches this specific failure mode and aborts the run after 3 consecutive unknown-tool errors.

Root Cause

The SDK's prepareToolCall() short-circuits for unknown tools: it returns an error result directly without invoking beforeToolCall or afterToolCall. The only OpenClaw code path that observes these errors is the tool_execution_end event handler (handleToolExecutionEnd).

Changes

Detection (tool-loop-detection.ts)

• Added "unknown_tool" to LoopDetectorKind
• Added isUnknownToolErrorText() to match SDK's "Tool X not found" error pattern
• Added getUnknownToolStreak() and detectUnknownToolLoop() with a critical threshold of 3 consecutive errors
• This detector is always active regardless of the main loop-detection enabled flag, since unknown-tool loops are always unrecoverable

Integration (pi-embedded-subscribe.handlers.tools.ts)

• In handleToolExecutionEnd, when isToolError is true: check if the error matches the unknown-tool pattern, record it in diagnostic session state, and run the detector
• If critical threshold is reached, set sessionState.unknownToolLoopDetected flag

Termination (attempt.ts)

• Added a streamFn wrapper that checks unknownToolLoopDetected before each LLM call
• If the flag is set, immediately aborts the run via runAbortController.abort() with a descriptive error

Type Extensions

• config/types.tools.ts: added unknownTool detector config and unknownToolCriticalThreshold
• logging/diagnostic-session-state.ts: added unknownTool flag on ToolCallRecord and unknownToolLoopDetected on SessionState
• logging/diagnostic.ts & infra/diagnostic-events.ts: added "unknown_tool" to detector kind union
• pi-tools.before-tool-call.runtime.ts: exported new detection functions for lazy loading

Test Plan

• Unit tests for isUnknownToolErrorText — matches SDK error format, rejects unrelated errors
• Unit tests for detectUnknownToolLoop — threshold detection, streak reset by normal calls, mixed unknown tools, custom threshold, independent of main enabled flag
• pnpm check (tsgo + oxlint) passes
• Existing tool-loop-detection tests remain green

Changed files

• src/agents/pi-embedded-runner/run/attempt.ts (modified, +40/-0)
• src/agents/pi-embedded-subscribe.handlers.tools.ts (modified, +67/-0)
• src/agents/pi-tools.before-tool-call.runtime.ts (modified, +4/-0)
• src/agents/tool-loop-detection.test.ts (modified, +127/-0)
• src/agents/tool-loop-detection.ts (modified, +78/-1)
• src/config/schema.base.generated.ts (modified, +16/-0)
• src/config/types.tools.ts (modified, +4/-0)
• src/config/zod-schema.agent-runtime.ts (modified, +2/-0)
• src/infra/diagnostic-events.ts (modified, +6/-1)
• src/logging/diagnostic-session-state.ts (modified, +6/-0)
• src/logging/diagnostic.ts (modified, +6/-1)