tool-loop-guardrail.md 3.41 KB

Tool Loop Guardrail: Recovery Patterns

What Happened

In a cron job session, the agent repeatedly ran the same terminal command:

ls -la /sdcard/ 2>/dev/null; echo "---"; ls -la /storage/ 2>/dev/null; echo "---"; ls -la /storage/emulated/ 2>/dev/null

This command consistently returned empty results (exit code 0 but no output). The agent ran it 5 times with identical arguments, triggering the tool-loop guardrail:

Blocked terminal: the same tool call failed 5 times with identical arguments.
Stop retrying it unchanged; change strategy or explain the blocker.

After the 5th failure, the terminal tool was blocked for the remainder of the session, preventing any further file operations.

Root Cause

The /sdcard/ directory was a symlink to /storage/self/primary which was itself a symlink, but the actual mount points were not accessible from the Termux environment without proper permissions. The command was not "failing" in the traditional sense (exit code was 0), but it was producing no useful output. The agent kept retrying the same command hoping for different results.

Why This Matters for VisualAgent Backends

When building or debugging VisualAgent backends, you often need to check directory existence and permissions. If your first check returns empty/unexpected results, you must change strategy rather than repeating the same check.

Recovery Patterns

Pattern 1: Add Fallback Output

Instead of:

ls -la /sdcard/ 2>/dev/null

Use:

ls -la /sdcard/ 2>/dev/null || echo "FALLBACK: /sdcard not accessible"

This ensures you get SOME output even on failure, and the command signature changes if it fails vs succeeds.

Pattern 2: Try Alternative Paths

If /sdcard/ fails, try the actual FUSE mount point:

# Check where /sdcard actually points
readlink -f /sdcard
# Check mount points
mount | grep -i sdcard
# Try the actual emulated storage path
ls -la /storage/emulated/0/ 2>/dev/null || echo "emulated/0 not accessible"

Pattern 3: Use find Instead of ls

find /sdcard -maxdepth 1 -type d 2>/dev/null || echo "find failed"

Pattern 4: Use su for Permission-Elevated Checks

su -c "ls -la /sdcard/" 2>/dev/null || echo "su ls failed"

Pattern 5: Switch to a Different Tool

If terminal is blocked or returning empty results, try:

  • read_file for reading specific files
  • search_files for finding files by pattern
  • mcp_android_phone_* tools for Android-specific operations
  • mcp_android_phone_screenshot to verify the device state visually

Pattern 6: Check Environment Variables

echo "EXTERNAL_STORAGE=$EXTERNAL_STORAGE"
echo "ANDROID_DATA=$ANDROID_DATA"
echo "HOME=$HOME"

Prevention Checklist

  • [ ] Before retrying a terminal command, ask: "Did I change the command or just repeat it?"
  • [ ] If a command returns empty/unexpected results 2 times, change strategy on the 3rd attempt
  • [ ] Always include || echo fallback or similar for commands that might fail silently
  • [ ] Keep a mental counter: same command + same args + same failure = guardrail trigger
  • [ ] When checking directory existence, use test -d or find rather than ls which may return empty on permission issues
  • Pitfall #12 in android-ui-automation/SKILL.md: Avoid redundant polling loops
  • Pitfall #30: FUSE filesystem hides files across UID boundaries
  • Pitfall #32: Use /data/local/tmp/ for Android automation