feat(agent-sdk): per-session sandbox workspaces (Pattern C)

[cognect]

Pattern C — per-session sandbox workspaces for the Agent SDK harness

Contains the harness's bypassPermissions default for untrusted work: each
interactive session (and each headless run) can get its own isolated microVM
sandbox as a disposable workspace. Feature-gated (agent-sdk-harness/sandbox)
and off unless spec.workspace.enabled.

What it does

• Stages the .claude/ projection into the sandbox (write_file) instead
  of the host filesystem — necessary because a SandboxHandle has no
  host-visible mount, so the host claude CLI can't cd into it.
• Routes the agent's work into the sandbox: injects an in-process
  run_in_sandbox tool bound to the session's sandbox and disables host
  Bash/Write/Edit (true containment).
• Discards (default) or snapshots the workspace to the warm pool on
  close; warm starts fork from the SnapshotPool.

The shared-registry seam (no Arc serialized across PyO3)

One SandboxClient is passed to the harness; the Rust side holds the same
Arc<SandboxHarness>, and the Python run_in_sandbox tool closes over the same
client — so the per-session sandbox the harness creates is the exact one the
tool execs into. The session's SandboxId rides the normal config round-trip
(config.sandbox_workspace_id); SandboxClient.attach(id) binds the tool.

Changes

• agent-sdk-core: AgentSdkConfig.sandbox_workspace_id (plain, optional data).
• agent-sdk-harness: new sandbox feature; workspace module
  (SandboxWorkspaceConfig / WorkspaceDisposition / SessionWorkspace /
  WorkspaceRegistry); render_projection refactor (pure renderer reused by
  the host-fs materialize and the new stage_into_sandbox sink);
  acquire_workspace / release_workspace / apply_containment wired into
  run / start_session / stop_session.
• py-bindings: SandboxClient.attach() + harness_arc();
  from_python_backend(sandbox=…); harness built with features=["sandbox"].
• python: _make_run_in_sandbox factory; sandbox= plumbed through
  ClaudeAgentSDKBackend / _build_options / agent_sdk_backend / harness.
• umbrella: agent-sdk-sandbox forwarder feature.
• docs / CHANGELOG / README: Pattern C section + cross-links.

Tests

• cargo test -p atomr-agents-agent-sdk-harness --features sandbox — 19 pass
  (11 new, MockBackend, network-free): acquire+stage, exec routing, containment
  flags, discard, snapshot, warm reuse, disabled path, enabled-no-client, two
  quotas, headless discard, projection parity.
• cargo test -p atomr-agents-agent-sdk-harness — 9 pass (base parity, no
  feature compiled).
• cargo build --workspace, cargo check -p atomr-agents-py-bindings,
  cargo build -p atomr-agents --features agent-sdk-sandbox — all build.
• Python smoke (mock backend) verifies the shared-registry attach + exec path
  and harness construction with a workspace-enabled spec.

Pattern B (whole claude CLI inside the VM via a SandboxAgentSdkBackend) and
a host-side credential proxy are noted as future roadmap.

🤖 Generated with Claude Code