sandbox.h File Reference

Filesystem-based sandbox isolation for delegations. More...

#include <atomic>
#include <filesystem>
#include <mutex>
#include <optional>
#include <string>
#include <vector>

Include dependency graph for sandbox.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	entropic::SandboxInfo
	Identifies one delegation's sandbox directory. More...
struct	entropic::SandboxResult
	Final artifact emitted by a finalized sandbox. More...
class	entropic::SandboxManager
	Create, finalize, and discard per-delegation filesystem sandboxes. More...
class	entropic::ScopedSandbox
	RAII directory swapper for sandbox-scoped tool execution. More...

Namespaces
namespace	entropic
	Activate model on GPU (WARM → ACTIVE).

Detailed Description

Filesystem-based sandbox isolation for delegations.

Replaces the v1.8.6–v2.1.4 git-worktree-based isolation (WorktreeManager) which corrupted user repo state (gh#29).

The sandbox lives at ~/.entropic/sandbox/<session-id>/, entirely outside the user's project directory. The engine NEVER manipulates the user's repo: no git checkout, no branches, no commits, no merges — that holds on every path, isolation on or off.

Opt-in (gh#160, v2.13.0)

This module runs only when delegation.isolation: sandbox is set. Under the default (none) a delegated child shares its parent's working directory and nothing here is constructed — no snapshot, no patch. That default is not a regression: from v2.1.5 to v2.12.2 the dir-swap callback had no production caller, so the snapshot was taken, never entered, and always diffed to zero bytes. gh#160 wires the swap and puts the cost behind the switch that buys it.

With isolation on, delegations run in isolated copies of the project tree and produce a portable unified-diff patch as their final artifact. The consumer (TUI/CLI/IDE plugin) is responsible for applying that patch — with the user's consent and authorship — back to the project. The snapshot source is the SESSION'S TOOL ROOT (AgentEngine::resolve_session_root), not the engine's own repo dir: gh#160's report was a consumer whose mcp.working_dir pointed at one repository while the sandbox snapshotted the host process's cwd.

Layout

~/.entropic/sandbox/<session-id>/
  base/                       Project snapshot at session start
  d-<delegation-id>/          Per-delegation sandbox (copy of base/
                              or of a prior delegation when chaining)
  pending/<delegation-id>.patch
                              Default-deny output when the consumer
                              registered no completion callback.

Invariant

Every filesystem write performed by this module must occur at a path under session_base_. The path_in_session_base() helper is the single chokepoint enforcing this; tests assert it directly.

Version

2.1.5

Definition in file sandbox.h.