Context

Tool execution requires safety boundaries proportional to risk. The MVP uses a subprocess sandbox for file system and git tools — lighter weight than Docker but sufficient for workspace isolation. This implements the SandboxBackend protocol with a subprocess-based backend.

Note: Docker/WASM/Firecracker sandboxing for code execution is a separate M7 issue (#50).

Acceptance Criteria

SandboxBackend Protocol

• SandboxBackend protocol defined (execute, cleanup, health_check)
• Protocol is pluggable — new backends can be registered via config

Subprocess Sandbox Backend

• Tools execute in subprocess with restricted environment
• Workspace boundary enforcement — agents cannot escape their assigned directory
• Path validation: prevent directory traversal (../ attacks)
• Configurable resource limits: timeout per execution, memory cap
• Environment variable filtering (no secrets leakage to subprocess)
• Stdout/stderr capture and structured result return
• Cleanup after execution

Integration with Tool System

• ToolInvoker routes file/git tools through the subprocess sandbox
• Sandbox backend selection configurable per tool category
• Sandbox failures surface as ToolError (not raw subprocess errors)

Testing

• Unit tests for SandboxBackend protocol
• Unit tests for subprocess sandbox with path traversal attempts
• Integration test: tool execution through sandbox with workspace boundaries

Dependencies

• Design and implement basic tool system (registry, invocation, results) #15 — Tool system (done)
• Implement built-in tools: file system operations #18 — File system tools
• Git tools issue (sibling M3 issue)

Design Spec Reference

• §11.1.2 — Sandbox Backends (Subprocess row)
• §15.3 — tools/sandbox/ directory structure
• §15.5 — Engineering Conventions (sandboxing row)