Enforcing Pre-Commit Schema Contracts on Agent Code Writes

Give an agent a tool that writes to disk, and by Wednesday it has modified four configuration files, renamed two exported interfaces, and opened a 600-line pull request.

The pull request looks clean on the surface. The tests pass because the agent updated the test assertions to match its new, broken output. The diff is too large for thorough human inspection on a busy afternoon, so the structural drift slips into main.

This failure mode comes from a fundamental architectural mistake: treating an agent like a human developer who sits behind a git commit interface. When you rely on downstream code review automation or human PR review to catch invalid agent mutations, you have already lost the control point. Verification belongs at the write boundary itself.

The failure of PR-level verification

Most teams deploying AI coding agents follow an identical pattern. The model is given shell access or a file-system write tool. It reads the workspace, formulates a plan, mutates files across three directories, commits, and opens a pull request.

At that point, review is an autopsy.

Human reviewers are notoriously bad at catching subtle structural degradation in high-volume diffs. When a model re-orders fields in an internal event schema, introduces a circular dependency, or adds an unauthorized dependency to package.json, it buries those changes inside hundreds of lines of mechanical refactoring.

If you catch the error at the PR stage, the agent's work loop is already complete. You either reject the entire branch—wasting the compute and the context window—or you pull the branch down and spend thirty minutes repairing the agent's hallucinations manually.

Effective agent governance requires moving the enforcement mechanism upstream. An agent should never write directly to a source tree or commit to a branch without its proposed mutation passing through a deterministic build gate that validates the operation against a strict schema contract.

Structuring the write transaction

A write gate sits between the agent's output buffer and the file system. In practice, this means removing raw file-writing capabilities (like arbitrary bash execution or unrestricted write_to_file tools) and replacing them with bounded mutation endpoints.

When the agent decides to modify code, it does not emit raw text to disk. It submits a structured mutation payload to an enforcement engine:

{
  "target": "services/billing/charge.ts",
  "operation": "modify_symbol",
  "symbol": "processPayment",
  "invariants": {
    "preserves_signature": true,
    "max_cyclomatic_complexity": 8,
    "forbidden_imports": ["stripe-internal-v1"]
  },
  "patch": "..."
}

Before this patch touches a file or generates a git commit, the write gate evaluates the proposal against explicit schema contracts:

1. AST Schema Invariants: Does the replacement AST preserve the public type contract of the existing symbol?
2. Boundary Rules: Does the new implementation import modules outside its designated domain layer?
3. Configuration Schema: If the target is a declarative configuration file, does the resulting document parse against the canonical schema without unknown keys?

If the mutation violates any of these rules, the gate halts the operation. The file system is never modified, no git ref is created, and the branch remains pristine.

Fast rejection and error payloads

The value of a pre-commit schema contract is not merely preventing invalid code from landing in main. It is providing immediate, deterministic feedback to the agent while its execution context is still warm.

When a write gate rejects a mutation, it should return a precise, structured failure state rather than a generic error string. If an agent tries to append an unvalidated key to a schema, the gate returns the exact contract violation:

{
  "status": "REJECTED",
  "gate": "SCHEMA_VALIDATION_FAILED",
  "path": "config/routes.json",
  "error": "Property 'timeout_ms' is not permitted in RouteConfigV2. Allowed properties: ['path', 'handler', 'auth_required']."
}

This short-circuits the hallucination loop. The agent does not spend ten iterations writing code, running a test suite, failing a downstream CI step, and guessing why a integration test flapped. It receives a deterministic boundary failure at the exact point of mutation.

The hardest part of this posture is resisting the urge to let the agent "just write the file and run the linter later." Linters running in CI are advisory; a write gate is authoritative. You can inspect how deterministic gates enforce terminal boundaries over tool interfaces at /mcp-access.

What to implement Monday

You do not need to re-architect your entire deployment pipeline to start gating agent mutations. Start with the most common point of silent failure:

1. Strip raw file write access: Remove unbounded write tools from your agent's execution environment. Replace them with a dedicated tool that takes explicit file targets and patches.
2. Validate schemas in-memory: In the tool implementation, apply the patch to an in-memory representation of the target file before writing to disk.
3. Run AST/schema checks before disk flush: Parse the resulting buffer. If it's TypeScript, run the compiler API to verify interface integrity. If it's JSON/YAML, validate against your JSON Schema.
4. Fail closed: If validation fails, return the parser error directly to the model. Do not touch the file. Do not stage the commit.

When agents are constrained to valid mutations at the gate, your PR review process returns to evaluating logic and intent, rather than policing basic structural sanity.