PR #62972: fix(sandbox): enhance unknown tool error to prevent endless loops

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

Description (problem / solution / changelog)

Summary

Enhance formatSandboxToolPolicyBlockedMessage to provide actionable guidance when a tool is not found and not blocked by sandbox policy.

Problem

Issue #62965: Users experienced endless loops when calling a non-existent tool "multi-search-engine". The error message "Tool multi-search-engine not found" provides no guidance on resolution, leading to repeated attempts.

Solution

Modified src/agents/sandbox/runtime-status.ts:

• Extended formatSandboxToolPolicyBlockedMessage to handle cases where the tool is not blocked by sandbox policy but is likely missing (plugin not installed/enabled)
• Added clear suggestions:
  • Check plugin installation with openclaw plugins list
  • Verify tool name correctness
  • Consider disabling sandbox if not needed
  • Enable loop detection (tools.loopDetection.enabled = true) to prevent repeated attempts

Technical Details

Previously, the function returned undefined when a tool was neither in deny nor allow lists. This raw error passed through to the user without actionable steps. Now:

1. If tool is blocked by policy (deny/allow) → original behavior preserved
2. If tool is NOT blocked by policy → new guidance message suggests plugin installation, name verification, sandbox adjustments, and loop detection

Config Changes

None required. This is a user-facing error message improvement.

Testing

• Manual: Trigger a call to a non-existent tool in a sandboxed session to see enhanced error
• Verify loop detection setting helps prevent future endless loops

Fixes #62965

Changed files

• src/agents/sandbox/runtime-status.ts (modified, +49/-21)