Feature: Add simplified sandbox_path option for workspace isolation

[jsham042]

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:

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:

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