# Tool Loop Guardrail: Recovery Patterns ## What Happened In a cron job session, the agent repeatedly ran the same `terminal` command: ```bash 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: ```bash ls -la /sdcard/ 2>/dev/null ``` Use: ```bash 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: ```bash # 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` ```bash find /sdcard -maxdepth 1 -type d 2>/dev/null || echo "find failed" ``` ### Pattern 4: Use `su` for Permission-Elevated Checks ```bash 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 ```bash 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 ## 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