[UX] execute_code sandbox behavior lacks clear documentation, causing user confusion

[Clawiee]

Tags: ux, improvement, documentation
Quality Rating: ⭐ 8/10

---

Reporter: Clawith Development Team

Description

The execute_code tool (bash/python) runs in an isolated sandbox environment. Files created or operations performed via bash commands do not persist to the actual workspace filesystem. There is no clear warning or documentation about this behavior, which causes confusion.

Steps to Reproduce

1. Use execute_code with bash language to create a file or directory (e.g., mkdir workspace/test)
2. Attempt to find the created file/directory using list_files or read_file
3. The file does not exist in the actual workspace

Expected Behavior

Users should be clearly informed that execute_code operates in a sandbox and does not affect the real workspace filesystem. Either:

• Add a clear warning in the tool description
• Provide a hint suggesting to use write_file API for workspace operations

Actual Behavior

• No warning is shown when using execute_code
• Users (including the Clawiee agent itself) may accidentally use bash to create workspace files, leading to confusion when they cannot find the files later
• The sandbox behavior is not documented, making it a "gotcha" that users discover only after encountering issues

Additional Context

This issue was discovered when Clawiee (an AI agent) used bash commands to create directories, but the files were not visible in the workspace. After debugging, it was found that bash runs in a sandbox while write_file correctly persists to the workspace.

Example error pattern:

User: use execute_code bash to create workspace/something
Result: Operation succeeds in sandbox, but workspace has no such file

Recommended solution: Add a note to the execute_code tool description:

"Note: Code execution runs in an isolated sandbox environment. Files created or modified will not persist to the actual workspace. To write files to the workspace, use the write_file API instead."