Fallback File Ops

Fallback File Operations

Purpose

When execute_code_sandbox or shell_agent fail with 'unknown error' on filesystem operations, fall back to run_shell with explicit mkdir and file write commands. This hybrid approach is more reliable for creating complex project structures.

When to Apply

• execute_code_sandbox returns 'unknown error' on file/directory creation
• shell_agent fails to write files or create nested directories
• You need to create complex project structures with multiple levels

Procedure

Step 1: Detect Tool Failure

Monitor for these failure patterns:

• Error message contains "unknown error"
• File operations silently fail (file not created)
• Directory creation returns success but directory doesn't exist

Step 2: Switch to run_shell

When failures occur, immediately switch to run_shell for filesystem operations:

# Create directory structure explicitly
run_shell: mkdir -p /path/to/nested/directory

# Write files using shell redirection or echo
run_shell: echo "content" > /path/to/file.txt

# Or use cat with heredoc for multi-line files
run_shell: cat > /path/to/file.txt  src/components/Button.tsx
run_shell: echo "// Utility file" > src/utils/helpers.ts

Best Practices

1. Be explicit: Always use full paths or confirm working directory
2. Create parent directories: Use mkdir -p for nested structures
3. Verify before proceeding: Check files exist before dependent operations
4. Log tool switches: Note when you fall back to run_shell for debugging
5. Batch operations: Group related file operations in consecutive run_shell calls

Common Pitfalls

• Don't assume filesystem state after tool failure
• Don't mix tools for the same file operation (pick one and stick with it)
• Don't skip verification steps when using fallback

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: HKUDS
• Source: HKUDS/OpenSpace
• License: MIT

Install and usage instructions live in the source repository linked above.