anthropics / anthropics/claude-agent-sdk-python
Feature: Add simplified sandbox_path option for workspace isolation
- Dominant language
- Python
- Stars
- 8.1k
- Forks
- 1.3k
- Avg merge
- 2d 31m
- Merged PRs (30d)
- 1
Description
## Problem
Agents can access and modify files broadly by default, which is unexpected and potentially dangerous. While the SDK provides building blocks for file isolation (`SandboxSettings`, `can_use_tool` callbacks, permission rules), there is no simple way to restrict all file operations to a designated workspace.
### Current State
The SDK provides:
1. **`SandboxSettings`** - Controls bash command sandboxing, but documentation notes that filesystem restrictions come from permission rules, not sandbox settings
2. **`can_use_tool` callback** - Runtime permission control, but requires manual implementation
3. **`add_dirs`** - Extends allowed directories, but is additive rather than restrictive
### Limitations
- With `permission_mode="bypassPermissions"`, agents have broad filesystem access
- `can_use_tool` hooks for `Write`/`Edit` don't prevent `Bash` from modifying files via redirects (`echo > file`, `rm -rf`, etc.)
- `Read` tool can access any file on the system
- No concept of a "scratchpad" or isolated workspace
### Workaround
Implement custom `PreToolUse` hooks to validate file paths:
```python
def create_sandbox_validator(sandbox_path: Path) -> HookMatcher:
async def validate_file_path(hook_input, _tool_use_id, _context):
tool_input = hook_input.get("tool_input", {})
file_path = tool_input.get("file_path", "")
abs_path = str(Path(file_path).resolve())
if not abs_path.startswith(str(sandbox_path)):
return {"hookSpecificOutput": {"permissionDecision": "deny"}}
return {}
return HookMatcher(matcher="Write|Edit", hooks=[validate_file_path])
```
This is incomplete as it doesn't cover `Bash` file operations.
## Proposed Solution
Add a first-class `sandbox_path` option that restricts all file operations:
```python
ClaudeAgentOptions(
sandbox_path="/path/to/session/sandbox", # All file ops restricted here
allow_project_read=True, # Can read project files but not write
allow_project_write=False, # Must be explicit to write project files
)
```
This would:
- Restrict `Write`, `Edit`, `Read` tools to the sandbox by default
- Configure `SandboxSettings` to restrict bash file access
- Provide clear opt-in for project file access
- Make isolation the default for agent workspaces
## Alternatives Considered
1. **Better documentation of permission rules** - Helps but still requires complex configuration
2. **Pre-built hook utilities** - Partial solution, still manual
3. **Container-based isolation** - Heavier weight, not always practical
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.