Workspace Isolation Plugin

The Workspace Isolation plugin gives each conversation an isolated sandbox using Linux bubblewrap (bwrap) and overlay filesystems. Agents can freely modify files, run shell commands, and perform git workflows without affecting other conversations or the base repository.

Overview

1. Each conversation gets a copy-on-write overlay: the base repository is read-only, and all writes go to a per-session upper layer
2. All tool operations (shell, file read/write) run inside the bwrap sandbox
3. Subagent changes are automatically integrated back into the parent agent's sandbox via VCS-aware diffing
4. Stable base snapshots decouple active sessions from ingestion pulls
5. AI-based merge resolution handles conflicts when subagent changes overlap with the parent's work

Requirements

• Linux (not supported on macOS or Windows)
• bubblewrap with overlay support: apt install bubblewrap (may need rebuild from source for --overlay-src)
• User namespaces enabled (AppArmor may need a bwrap profile)

If enabled but unavailable, all tool operations fail with a clear error. The system never silently falls back to direct execution.

Configuration

plugins:
  workspace_isolation:
    enabled: true
    workspace_ttl: 86400          # Cleanup stale workspaces after N seconds (default: 24h)
    persistent_home: true         # Persistent $HOME shared across all agents (default: true)

    # Sandbox hardening
    sandbox:
      unshare_net: true           # Isolate network namespace (default)
      unshare_uts: true           # Isolate hostname
      unshare_cgroup: true        # Isolate cgroups
      hostname: "sandbox"         # Hostname inside sandbox
      new_session: true           # New session ID (setsid)
      clearenv: true              # Clear environment variables
      allowed_env_vars:           # Env vars to pass through when clearenv is true
        - HOME
        - PATH
        - LANG

    # Subagent change integration
    integration:
      enabled: true               # Enable VCS-aware diff integration (default: true)
      auto_commit: true           # Auto-commit uncommitted subagent changes (default: true)
      ai_merge: true              # Use AI for conflict resolution (default: true)

    # Stable base snapshots
    snapshots:
      enabled: true               # Snapshot repos_dir per session (default: true)
      shared: true                # Share snapshots across sessions at same commit (default: true)

Subagent Change Integration

When workspace isolation is active, each subagent gets its own sandbox. Without integration, subagent modifications would be stranded in an isolated overlay layer. The integration system propagates changes back automatically.

How it works

1. Feature branch creation -- When a subagent starts in a VCS repo, the system creates a feature branch (codumentor/dev/<subagent_id>) inside the subagent's sandbox
2. Auto-commit -- When the subagent completes, any uncommitted changes are committed to the feature branch
3. Diff generation -- The system generates a diff (git diff base...HEAD or svn diff) inside the subagent's sandbox
4. Diff application -- The diff is applied to the parent's sandbox (git apply --3way or patch)
5. Conflict resolution -- If the apply conflicts, the AI merge resolver attempts automatic resolution

The diff travels as a string in memory between sandboxes. No shared filesystem access is needed.

VCS support

VCS	Branch	Diff	Apply	Conflict detection
Git	git checkout -b	git diff base...HEAD	git apply --3way	Yes (3-way merge)
SVN	records base revision	svn diff -r base	patch -p0	Yes (patch rejects)
None	N/A	N/A	Copy upper_dir files	No (last writer wins)

AI merge resolution

When git apply --3way fails with conflicts, the system:

1. Parses conflicting file paths from git's stderr
2. Reads three versions of each file: base (common ancestor), ours (parent's), theirs (subagent's)
3. Sends each conflict to an LLM with a focused merge prompt
4. Writes the resolved content to the parent's sandbox

Disable with integration.ai_merge: false to report conflicts without automatic resolution.

Stable Base Snapshots

The overlay base layer (repos_dir) can change when the ingestion system pulls new content. Snapshots freeze the base at session start.

Snapshot strategies

VCS	Method	Cost
Git	git worktree add --detach	Near-zero (shares object store)
SVN	svn export -r REV	Full copy at pinned revision
None	cp -rl (hardlink copy)	Near-zero disk, instant

Sharing

Sessions starting at the same commit reuse the same snapshot directory. Reference counting tracks active sessions. Orphaned snapshots are cleaned up after the workspace TTL expires.

Disable sharing with snapshots.shared: false.

Files

File	Purpose
plugins/workspace_isolation/plugin.py	Plugin entry point, context hook, workspace lifecycle
plugins/workspace_isolation/strategies.py	IsolatedExecutionStrategy, FailedExecutionStrategy, SandboxPolicy
plugins/workspace_isolation/home_layout.py	Host-side HOME directory management (prepare, auth file copy)
plugins/workspace_isolation/sandbox_env.py	Sandbox-side HOME/env semantics (HOME path, baseline env)
plugins/workspace_isolation/vcs.py	VCS adapters (Git, SVN), feature branch and auto-commit
plugins/workspace_isolation/integrator.py	Diff generation, application, conflict detection
plugins/workspace_isolation/merge_resolver.py	AI-based three-way merge resolution
plugins/workspace_isolation/snapshots.py	Stable base snapshot management
tools/subagent_runner.py	Wires auto-commit and integration into subagent lifecycle

Testing

# All workspace isolation tests
python -m unittest tests/test_workspace_isolation_plugin.py tests/test_vcs_integration.py tests/test_integrator.py tests/test_integrator_integration.py tests/test_snapshots.py tests/test_merge_resolver.py -v