anthropics / anthropics/claude-agent-sdk-python

Feature: Add simplified sandbox_path option for workspace isolation

Open
#457 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.