Restricting Agent Filesystem Access to Preview Sandboxes

Most configurations for AI coding agents grant direct filesystem write privileges. The model receives a prompt, calls a file-modification tool, and mutates the working tree on disk.

When that output contains broken syntax, circular dependencies, or incompatible licenses, the working directory is instantly polluted. Language servers choke, local file watchers trigger rebuilds on invalid code, and developers waste cycles resetting Git state or prompting the agent to clean up its own mistakes.

The failure is structural: granting direct write access eliminates the control point between an agent's intent to modify a file and the physical write operation. Effective agent governance requires moving file mutations behind a preview-only layer.

The Cost of Ambient Write Access

When an agent executes an unfiltered write_file or apply_patch call, verification occurs too late. The toolchain treats the mutation as human authoring:

[Agent] ---> (write_file tool) ---> [Local Working Tree] ---> [Broken State]
                                              |
                                              v
                                   [Language Server / Watcher Fails]

This model assumes the generator can be trusted to produce valid syntax and uphold repository invariants on the first pass. It cannot.

Even if you run automated tests after the write, the blast radius is already uncontained. Filesystem hooks fire, temporary build artifacts are generated from invalid states, and other concurrent agents or human developers see a dirty tree. If the agent enters an error loop, it spends context tokens attempting to parse its own malformed edits out of the repository.

The Preview Sandbox Pattern

The correct posture is to separate the proposal from the mutation. An agent should never write directly to a working tree. It should write to an ephemeral staging layer that acts as a build gate.

In a preview-only architecture, the agent interface changes:

1. Emit Intent: The agent submits a proposed diff or full file replacement to a virtual buffer via its MCP server or tool integration.
2. Execute Invariant Checks: The harness applies the diff against the baseline in memory or in an isolated scratch directory. It executes static verification: AST parsing, type checking, schema enforcement, and license validation.
3. Return Diagnostics on Failure: If an invariant fails, the error diagnostics return directly to the agent's context window. The local working tree remains untouched.
4. Gated Application: Only when the build gate returns a clean pass does the harness write the change to the actual workspace.

[Agent] ---> (propose_diff) ---> [Preview Sandbox]
                                        |
                            [Run Static Invariant Checks]
                                        |
                        +---------------+---------------+
                        |                               |
                     [Pass]                          [Fail]
                        |                               |
             [Commit to Working Tree]         [Return Diagnostics to Agent]
                                              (Working Tree Untouched)

This approach shifts validation from post-commit cleanup to pre-write verification. It is the core mechanism behind governing code agents at the build-intent gate. The agent can attempt complex refactors, hit type errors, and iterate against machine-readable diagnostics without dirtying the developer's local state.

How SHPBL Implements the Build Gate

SHPBL uses this preview-first posture across all access methods: the MCP server, the HTTP API, the typed SDK (@shpbl/sdk), and the offline file edition.

When an agent requests software capability, every write must clear the Build Intent gate. The agent registers its intent, and the harness resolves the invariants and licensing in code—not through a model's runtime evaluation. Previews cost nothing; verification is computed rather than generated.

The harness executes the artifact and records an explicit verdict (CERTIFIED, PROVISIONAL, INCONCLUSIVE, or FAILED) before any file hits your repository. Because our library is model-independent and verified against published checksums, the artifact that passes the gate has zero runtime hallucination surface.

What to Configure on Monday

You can enforce this pattern in your existing development setup without overhauling your stack:

1. Revoke direct write tools: Remove raw write_to_file or edit_file tools from your agent configuration.
2. Expose a patch-validation tool: Provide the agent with an MCP tool that accepts a diff, writes it to a temporary directory mirroring the target file, and runs a fast syntax and type check (tsc --noEmit, cargo check, or ruff).
3. Gate the write on zero-exit status: Configure the tool to apply the diff to the real repository path only if the validator returns exit code 0. Otherwise, return stdout/stderr directly to the model.

Keep the agent's scratch space distinct from your working tree. When tools require code to pass invariants before touching the disk, broken agent edits stop interrupting your build.