A coding agent is asked to fix a bug while another agent reviews a different feature and a human continues normal development.
The team creates three branches. Problem solved?
Not necessarily.
A branch separates a line of source history. It does not automatically separate the working directory, running processes, package caches, test databases, network access, credentials, temporary artifacts, or promotion path. Those other boundaries determine whether agents can work independently and whether a result can be trusted.
A branch is a source-control boundary. An agent workspace is an operating boundary.
The difference matters even when only one agent is active. It becomes critical when work is concurrent, resumable, or allowed to make changes that a human will later review.
What a worktree does—and does not—isolate
Git’s worktree documentation describes multiple working trees attached to one repository, with separate working-tree metadata such as HEAD and index. That can make it possible to check out different branches at once without disturbing a current change.
But Git also documents shared repository state. Some references and repository configuration are shared across linked worktrees unless a team explicitly configures otherwise. A worktree therefore isolates important source-control state, not the full runtime environment of an agent.
That is a feature, not a defect. Git was not designed to be a complete agent sandbox.
The danger begins when a team assumes that a worktree guarantees all of the following:
- only one agent can change the files that matter;
- only one process can access the test environment;
- no tool can reach the host filesystem outside the repository;
- credentials and network identity are different;
- a passing test reflects the intended source snapshot;
- the result will be promoted only through the expected review path.
Those promises require a larger contract.
A proposed six-boundary workspace contract
Virillio Code Editorial proposes treating a coding-agent workspace as six separately declared boundaries. This is an editorial design model, not a Git, container, or agent-platform standard.
- Boundary: Source — Question it answers: Which code and initial state did the agent receive? — Typical evidence: Repository identity, immutable revision, initial diff, branch or detached state
- Boundary: Filesystem — Question it answers: Which paths may the agent read or modify? — Typical evidence: Workspace root, allowed output paths, excluded paths, mount policy
- Boundary: Process — Question it answers: Which local processes, ports, locks, and caches can interact with the work? — Typical evidence: Process namespace or isolation policy, port allocation, cache scope, cleanup state
- Boundary: Environment — Question it answers: Which runtime, dependencies, services, and network rules apply? — Typical evidence: Image or runtime version, dependency policy, fixtures, service endpoint class, resource limits
- Boundary: Identity — Question it answers: Which user, credentials, and authority apply to operations? — Typical evidence: Execution identity class, least-privilege policy, approved tool and permission scope
- Boundary: Promotion — Question it answers: How does a result become visible to the team or a target system? — Typical evidence: Diff, test evidence, review route, merge or deployment approval boundary
The contract does not need to be large. It needs to be explicit enough that a reviewer can tell what is isolated, what is shared, and what must never be assumed.
A filled workspace contract
For a coding agent assigned to fix ticket API-1842 in a fictional payments service, a concrete contract might read:
- Boundary: Source — Declared contract: Start from repository payments-api at commit 8f3c2d1 in a dedicated api-1842 checkout; record a clean initial diff; do not rebase during the run.
- Boundary: Filesystem — Declared contract: Allow read/write only under /workspace/payments-api and /workspace/evidence; mount the dependency cache read-only; do not mount a home directory, sibling repositories, or host credentials.
- Boundary: Process — Declared contract: Run in a task-specific container; reserve port 43117; use cache prefix run-742 and database schema agent_742; the runner owns cleanup.
- Boundary: Environment — Declared contract: Use the pinned CI image digest and lockfile; seed the named test fixture; deny outbound network access; cap execution with the task’s recorded time and resource budget.
- Boundary: Identity — Declared contract: Use a short-lived coding-agent identity that can edit the checkout and run tests but has no production credentials, merge permission, or deployment authority.
- Boundary: Promotion — Declared contract: Permit a patch and evidence bundle to be exported to a draft review; require a human reviewer to approve any merge; require a separate deployment workflow for release.
The identifiers are illustrative, but the declarations are testable. A reviewer can inspect the commit and initial diff, probe excluded paths, check the assigned port and database namespace, and confirm that the execution identity cannot merge or deploy.
1. Source boundary: freeze what the agent is changing
Source isolation starts with more than a branch name.
Record:
- repository identity and revision;
- initial working-tree state;
- branch, detached state, or task-specific checkout;
- included submodules, generated artifacts, and relevant configuration files;
- expected output path and whether unrelated changes are in scope.
This is the same discipline that makes coding-agent evaluations believable, but it is equally important in production workflows. If an agent resumes tomorrow from a different default branch, it may be solving a different problem even if the task text is unchanged.
Worktrees are often a good source boundary because they make a separate checkout visible. They are not a reason to skip recording the actual revision or the initial diff.
2. Filesystem boundary: expose only the paths the task needs
The filesystem is the agent’s practical world. A narrow source checkout is useful only if the rest of the path scope is equally deliberate.
Decide:
- which repository or directory is the workspace root;
- which paths are read-only;
- which paths may receive generated artifacts;
- whether temporary files are retained, exported, or discarded;
- whether host files are materialized, mounted, or unavailable;
- which paths are categorically excluded.
Docker’s bind-mount documentation is a useful warning here: a bind mount shares a host file or directory into a container and is writable by default. A process inside the container can therefore affect the host path. A container plus a broad bind mount may be operationally convenient, but it is not the same as a narrow workspace boundary.
The rule is simple:
A sandbox boundary is only as narrow as its mounts and path grants.
If a task only needs one repository and one output directory, the workspace should not quietly inherit a home directory, shared secrets location, or every sibling project.
3. Process boundary: prevent invisible interference
Two separate directories can still interfere through processes.
Examples include:
- a development server already listening on a shared port;
- a test runner using the same database or queue;
- a language server rewriting generated files;
- a package manager sharing a lock or cache with mutable behavior;
- a background process holding a file lock;
- a browser session or local emulator with one global state.
These conflicts are especially hard for agents because the model may not know another process exists. It sees a test failure, a timeout, or stale output and may infer the wrong cause.
The process boundary should state whether work happens:
- in the host process environment;
- in a dedicated container or virtual environment;
- in a managed sandbox session;
- through a remote or shared service with a task-specific namespace;
- with assigned ports, cache keys, and cleanup ownership.
You do not need maximal isolation for every lint fix. You do need enough isolation that the task’s claims remain credible.
4. Environment boundary: define more than the repository
The environment includes the parts of execution that source control does not version by itself:
- language and toolchain version;
- dependency installation and cache policy;
- operating-system and filesystem behavior;
- test fixtures and service stubs;
- network availability and allowed destinations;
- time, memory, concurrency, and retry limits.
OpenAI’s sandbox-agent guide makes this separation concrete: a manifest describes the desired fresh workspace, while a live sandbox session is the environment where commands run and files change. A later run may resume an existing session or start from saved workspace state, so a manifest is not automatically the complete description of every live environment.
That distinction is broadly useful. “We start from the same repo” does not establish “we ran in the same environment.”
For a coding agent, record enough of the execution envelope to explain why a test passed, failed, or could not run. If a test requires a shared integration service, say so. Do not let a green check imply an environment was isolated when it was not.
5. Identity boundary: separate access from location
An agent’s workspace and its authority are related but distinct.
The same repository checkout can be read-only for a reviewer, writable for a repair agent, and unavailable to a research agent. The same container can have broad or narrow credentials. The same tool can be allowed against a test system and forbidden against a production one.
An identity boundary should establish:
- the execution identity class;
- which tool categories are enabled;
- what permissions or approvals govern writes;
- whether credentials are available at all;
- the target scope for any networked or external action;
- the audit and retention policy for access records.
This is a least-privilege design concern, not a prompt-writing concern. Do not ask a model to remember that it lacks authority; make the tool and environment boundary enforce it.
A well-scoped coding agent has only the authority its task requires.
6. Promotion boundary: keep working state separate from delivered state
A code change is not ready merely because files changed in a workspace.
The promotion boundary explains how a task becomes an engineering artifact another person can trust:
- Promotion step: Patch prepared — Evidence needed: Changed paths, intended behavior, and scope check
- Promotion step: Verification complete — Evidence needed: Targeted tests, checks, or explicit unrun items
- Promotion step: Review ready — Evidence needed: Change evidence package and review route
- Promotion step: Merge candidate — Evidence needed: Branch or commit identity, approval status, conflict state
- Promotion step: External release candidate — Evidence needed: Explicit deployment or publication authority, rollback or recovery plan
This keeps an agent’s mutable work separate from a team’s accepted change. It also limits the damage of a mistaken assumption: a faulty local result can be caught at review instead of becoming a silent external effect.
The review handoff should reference the workspace contract where it matters. A reviewer should know whether a test ran in a clean environment, whether a source state was isolated, and whether a shared service or cache could affect the result.
Match isolation to task shape
Isolation is not an all-or-nothing checkbox. Choose the smallest boundary that keeps the task understandable and safe.
- Task shape: Read-only repository orientation — Appropriate starting boundary: Pinned revision and read-only file scope
- Task shape: Narrow single-agent fix — Appropriate starting boundary: Dedicated checkout or worktree plus bounded test and output scope
- Task shape: Parallel independent changes — Appropriate starting boundary: Separate source workspaces, explicit ownership, and non-shared mutable test state
- Task shape: Integration or migration investigation — Appropriate starting boundary: Isolated or namespaced service environment plus a clear cleanup plan
- Task shape: High-consequence or external change — Appropriate starting boundary: Narrow workspace, least-privilege identity, explicit approval, and evidence-rich promotion
The point is not to force every task into a container. It is to prevent a low-cost setup from making a high-confidence claim it cannot support.
Do not confuse resume with a fresh start
Long-running coding workflows introduce one more complication: a resumed workspace may be useful precisely because it contains partial work, downloaded dependencies, or a live process.
That state can be valuable. It can also be the source of ambiguity.
Record whether the agent:
- received a fresh workspace from a known source state;
- resumed a named prior workspace or serialized session;
- started from a saved snapshot;
- inherited files or processes from a previous task;
- is allowed to use those artifacts as evidence.
Fresh and resumed are both legitimate. The mistake is treating them as interchangeable.
OpenAI’s sandbox guidance makes this explicit: the fresh manifest, a live session, a serialized session state, and a saved snapshot are different ways to establish a workspace. That is a useful model for any coding-agent platform.
Test the workspace contract
The contract should be evaluated like any other product boundary.
- Test: Snapshot test — What it proves: Agent starts from the expected source state
- Test: Path-scope test — What it proves: Agent cannot read or write excluded locations
- Test: Concurrency test — What it proves: Parallel tasks do not collide through files, ports, or shared mutable fixtures
- Test: Resume test — What it proves: A resumed task identifies inherited state and remains reproducible enough to review
- Test: Credential test — What it proves: The agent lacks authority outside the task’s target scope
- Test: Promotion test — What it proves: A workspace change cannot skip required verification or human review
These tests complement a policy document by turning isolation from an intention into a property the team can observe.
Common anti-patterns
“Each agent has a branch, so they are isolated”
Branches separate source history. They do not automatically separate caches, processes, service state, credentials, or promotion authority.
Shared test environments with no ownership rule
Two agents can produce a misleading failure or a false pass by mutating the same fixture, database, queue, or emulator.
Containerized process with a broad writable host mount
Container isolation can be weakened or bypassed by the filesystem it is given. A writable mount may be appropriate, but it must be treated as shared authority.
Resuming a workspace without declaring it
An agent may be operating on a half-finished patch or stale generated artifact. Hiding that history makes later verification unreliable.
Treating merge as an implementation detail
Promotion is the boundary between experimental agent work and accepted engineering work. It deserves its own evidence and authorization.
A practical adoption path
- Classify your current coding-agent tasks by source, process, and external-effect risk.
- Create a small workspace contract for one task type.
- Pin source state and define explicit file and output scope.
- Decide whether tests use shared, namespaced, or isolated services.
- Separate the execution identity from the human reviewer’s identity.
- Require a promotion package with test evidence and residual risk.
- Run two similar tasks concurrently and inspect every shared boundary they reveal.
The result is not just fewer collisions. It is a coding-agent workflow where a human can understand what the agent was allowed to touch, what it actually touched, and why the final change is ready for review.
What we are learning building Virillio Code
Virillio Code’s workspace and session architecture remains in development, but the general lesson is clear: source, tools, permissions, and filesystem placement have different scopes and lifetimes. Coding-agent reliability improves when the workspace is an explicit contract rather than an accidental directory plus a branch.
The more autonomous the agent, the more important it becomes to separate a place where work can happen from the authority that lets work advance.
Sources and further reading
- git-worktree documentation — Linked worktrees provide multiple checkouts with a mix of per-worktree state such as HEAD and index alongside shared repository data.
- Bind mounts — Docker Docs — Bind mounts share host directories with containers and are writable by default, so processes inside the container can modify mounted host paths.
- Sandbox agent concepts — OpenAI Agents SDK — A fresh workspace manifest, a live sandbox session, saved session state, and snapshots are distinct ways of defining and carrying an agent workspace.
Editorial disclosure
This article was substantially researched, drafted, and revised with AI through the Virillio Code editorial workflow. Virillio Code publishes the final text under its editorial byline, and the supporting primary sources are linked above.