Policy-Driven Build Intent Gates for Multi-Agent Environments

Multi-agent environments fail at the filesystem boundary.

When you give three agents write access to a repository, they collide. An orchestrator instructs Agent A to write database migrations and Agent B to implement an API handler. Agent B encounters a typing mismatch, edits tsconfig.json to relax compiler checks, and commits. Agent A regenerates schema definitions against the altered compiler settings. By the time a developer opens the pull request, the repository state is a tangle of mutual compromises.

Prompting agents to "only edit files inside /src/handlers" is advisory. System prompts degrade under long context windows, and tools like sub-agent delegation strip parent instructions. Practical agent governance requires placing a physical boundary between the agent deciding to modify code and the bytes touching the filesystem.

That boundary is a policy-driven code write gate.

The Anatomy of a Build Intent Policy

A build intent policy is a machine-readable specification of what an agent may propose. It runs outside the agent's context, evaluating proposed changes against static repository invariants before granting write execution.

A standard policy enforces four constraints:

1. Path Boundaries: Strict globs defining allowable read and write targets for a specific agent role.
2. Immutable Files: Configuration, CI workflows, and package lockfiles locked against automated mutation.
3. Dependency Controls: Restrictions on introducing new external packages or modifying dependency versions.
4. Interface Contracts: Invariants asserting that public exports or schema types cannot be removed without explicit human elevation.

A minimal build intent policy defines these constraints directly:

{
  "role": "feature-worker",
  "allowed_paths": ["src/features/billing/**", "tests/billing/**"],
  "denied_paths": ["src/core/**", "package.json", "tsconfig.json"],
  "max_changed_files": 5,
  "forbidden_tokens": ["any", "ts-ignore", "process.env"]
}

This file lives in the repository root or a central configuration store. It is evaluated by your tooling, not passed as context to the model. The model does not need to understand the policy; it only receives the terminal output if it attempts a violation.

Enforcing the Gate Inside an MCP Server

In a modern workflow, agents interact with repositories through the Model Context Protocol (MCP). Exposing raw filesystem primitives like write_file or run_terminal_command directly to the model bypasses your control plane.

Instead, route all file modifications through a specialized MCP server tool that acts as the gate.

Agent Action ──> MCP Tool Call ──> Policy Evaluator ──> [ Allow: Write Disk ]
                                                    └──> [ Reject: Return Error ]

When an agent requests a file mutation, the MCP server does not write immediately. It executes a three-phase check:

1. Intent Registration: The server reads the target path, the proposed diff, and the active session ID.
2. Policy Evaluation: The engine checks the diff against the active policy. It parses the AST to detect forbidden tokens and evaluates the target path against the glob rules.
3. Terminal Decision: If the check passes, the tool applies the mutation to a scratch space or target branch. If it fails, the server rejects the call and returns the exact invariant violation back to the model.

// MCP Tool Handler for write_code_intent
export async function handleWriteIntent(params: WriteIntentParams): Promise<ToolResult> {
  const policy = await loadPolicyForSession(params.sessionId);
  const evaluation = evaluateIntent(params.targetPath, params.diff, policy);

  if (!evaluation.valid) {
    return {
      isError: true,
      content: [
        {
          type: "text",
          text: `Build Intent Rejected: ${evaluation.violations.join(", ")}. Write aborted.`
        }
      ]
    };
  }

  await applyFileMutation(params.targetPath, params.diff);
  return {
    content: [{ type: "text", text: `Successfully wrote ${params.targetPath}` }]
  };
}

By separating agent proposals from repository mutations, the repository remains clean. If an agent tries to modify tsconfig.json, the tool returns a failure immediately. The agent can adjust its strategy within its allowed bounds, but it cannot force the mutation.

What Static Policies Cannot Catch

A build intent policy is a static boundary, not a semantic guarantee.

It easily prevents path traversal, dependency tampering, and forbidden syntax. It cannot determine whether an algorithm is correct, whether a database query performs poorly, or whether business logic is subtly flawed. Those guarantees require isolated test execution and formal harness verification after the write occurs.

Do not overload the policy engine with dynamic integration checks. Keep the gate fast, deterministic, and focused strictly on repository safety and scope isolation.

What to Do on Monday

To stop ungoverned agent writes in your current setup:

1. Audit your tool layer: Inspect the tools registered on your MCP server. Identify any tool that provides unrestricted file write or bash execution access to code agents.
2. Implement a write wrapper: Replace raw write_file tools with a gated write handler that accepts the target path and patch.
3. Define a default deny list: Start simple. Block writes to package.json, lockfiles, CI pipelines, and base configuration files.

Enforce the boundary at the protocol level, and let the model operate safely within the box you define.