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_filefor reading specific filessearch_filesfor finding files by patternmcp_android_phone_*tools for Android-specific operationsmcp_android_phone_screenshotto 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
terminalcommand, 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 fallbackor 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 -dorfindrather thanlswhich may return empty on permission issues
Related Pitfalls
- 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