Sandbox mode: files created by background agents via Bash don't persist to real filesystem

Description

When running Claude Code in /sandbox mode, files created by background agents (spawned via the Agent tool) using Bash commands (cp, cat >, echo >, etc.) are written to a sandbox overlay and are not visible on the user's real filesystem. The files appear to exist from the agent's Bash perspective (ls, cat, stat all work), but they don't exist on the actual disk.

Steps to Reproduce

1. Enable sandbox mode (/sandbox)
2. Spawn a background agent via the Agent tool
3. Have the agent create a file using Bash (e.g., echo "content" > /path/to/file.md)
4. Agent reports success, file is visible via ls from agent's Bash
5. Check from the user's terminal — file does not exist

Expected Behavior

Files created by agents in sandbox mode should persist to the real filesystem, same as files created by the main conversation's Bash commands.

Actual Behavior

Files are trapped in a per-agent sandbox overlay that is destroyed when the agent terminates. The content is permanently lost.

Workaround

Instruct agents to use the Write tool instead of Bash for all file creation. The Write tool bypasses the sandbox and writes to the real filesystem. This is fragile because:

• It's easy to forget
• Agents may use cp or mv which also don't persist
• The failure is silent — everything appears to work until the user checks their filesystem

Impact

In a session involving many agents producing output files (e.g., documentation generation), all agent-written files can be silently lost, requiring complete re-generation. In our case, ~210KB of architecture documentation across 7 files was lost and had to be re-written.

Environment

• Claude Code CLI with /sandbox enabled
• Linux (WSL2)
• Agents spawned via Agent tool with run_in_background: true

🤖 Generated with Claude Code