Shell
How Workspace Shell executes sandbox and host commands
Shell is a Workspace capability, not a Power. It owns its Sandbox Provider, the isolated Workspace Sandbox, and reusable Shell Sessions.
What it does
- Executes commands in the Workspace Sandbox by default
- Keeps installed tools and HOME state across Chat Sessions
- Captures stdout, stderr, and exit codes
- Supports timeouts and cancellation
Long-running work and completion notifications
Use Shell's exec action for short commands and session_start for long-running or interactive processes. With auto_notify_on_exit: true, command completion automatically reports success, failure, or an explicit stop to the original Session. No polling is needed, and each completion is handled once.
Notifications are processed at execution checkpoints, without a guarantee of immediately interrupting model requests or synchronous tools. If the original execution has stopped, closed, or been replaced, results remain saved and late notifications do not wake it again. Use auto_notify_on_exit: false for long-lived services. After restart, only delivery of saved completion results is restored. Original processes that cannot be taken over are reported as interrupted or unknown; commands are not automatically rerun.
See Shell and Sandbox for calls and lifecycle details.
Safety
Shell has only two targets: sandbox and host. Sandbox execution is the default and cannot see arbitrary host paths. Host execution requires an explicit reason and host approval; Sandbox failures never fall back to the host.
Use cases
- Running build scripts
- File system operations
- Querying system state
- Executing project-specific tools
Continue with: