Before an Agent's .proto Edit Silently Breaks Binary Compatibility: Gating Wire Compat with buf breaking

Making buf breaking the Gatekeeper for Wire Compatibility

Buf's buf breaking compares the changed schema against the previous one and detects breaking changes. Narrow the category to WIRE and you allow source cleanup and renames while rejecting only changes that break byte-level compatibility.

Place a buf.yaml at the repository root.

# buf.yaml
version: v2
modules:
  - path: proto
breaking:
  use:
    - WIRE            # audit binary compatibility only (allow naming/formatting)
  ignore_unstable_packages: true
lint:
  use:
    - STANDARD

Choosing WIRE is the point. The FILE category treats even field renames as breaking, which is too strict when you only want to protect wire compatibility. To leave the agent room to reformat while defending only semantic compatibility, WIRE is exactly right.

Use the main branch as the comparison baseline.

# compare the changed proto against main's proto
buf breaking --against '.git#branch=main,subdir=.'

On a breaking change, buf prints the file, line, and violated rule and exits non-zero. A type change on a numbered field surfaces a FIELD_SAME_TYPE-style violation, for example, and a change to what a number means surfaces the specific rule.

Deleting a Field Comes Paired With reserved

buf breaking is powerful, but it only compares against the "previous state." Free a number now and reuse it in a later change, and each step alone can look non-breaking. So we seal the number at deletion time.

When asking an agent to delete, instruct it to replace with reserved rather than remove. Here is Before and After.

// Before: the risky shape the agent "tidied" into
message UserProfile {
  string display_name = 1;
  string avatar_url = 2;
  // deleted legacy_score(3) and put a new nickname at 3
  string nickname = 3;
}

// After: reserve the number and old name so it is never reused
message UserProfile {
  string display_name = 1;
  string avatar_url = 2;
  string nickname = 4;          // use the next free number
 
  reserved 3;                   // seal the number legacy_score used
  reserved "legacy_score";      // reserve the old field name too
}

Once reserved is declared, the moment an agent later tries to use number 3, compilation itself fails. It stops right there, without waiting for human review. In indie development, this "stops mechanically at an early stage" is what I appreciate most. A pipeline that ran overnight and caused trouble by morning is far worse than one that turns red on the spot.

Stopping It in Front of a Human With a pre-push Hook

Catching it only in CI means a broken change already reached the remote once. Stopping it at the moment of the push gives faster feedback. Layering agent operation and a manual hook in two stages follows the same idea as the two-stage gate design of Antigravity CLI Hooks and git pre-push.

Here is the script for .git/hooks/pre-push.

#!/usr/bin/env bash
# .git/hooks/pre-push — verify proto wire compatibility before pushing
set -euo pipefail
 
# pass immediately if no proto changes (do not slow down unrelated pushes)
if git diff --quiet origin/main -- 'proto/**/*.proto'; then
  echo "no proto changes — skipping wire compat check"
  exit 0
fi
 
echo "proto changes detected — running buf breaking"
if ! buf breaking --against '.git#branch=main,subdir=.'; then
  echo ""
  echo "Blocked: found a change that breaks wire compatibility."
  echo "  Check for field-number reuse or type changes."
  echo "  Delete fields by replacing them with 'reserved'."
  exit 1
fi
 
echo "wire compatibility OK"

The aim of this hook is not to slow the agent down. Pushes that never touched proto pass through, and the gate only rises when proto was touched. You pay the cost only for the one thing worth protecting.

Kill Field-Number Reuse by Machine

buf and reserved cover most of it, but explicitly confirming per commit whether "a deleted number is registered in reserved" adds confidence. Here is a small script that directly detects the case where an agent forgot the reserved declaration.

# check_reserved.py — confirm deleted numbers are registered in reserved
import re
import subprocess
import sys
 
def field_numbers(proto_text: str) -> set[int]:
    # collect numbers from field definitions like "name = 12;"
    nums = set()
    for line in proto_text.splitlines():
        m = re.search(r"=\s*(\d+)\s*;", line)
        if m and "reserved" not in line:
            nums.add(int(m.group(1)))
    return nums
 
def reserved_numbers(proto_text: str) -> set[int]:
    nums = set()
    for m in re.finditer(r"reserved\s+([0-9,\s]+);", proto_text):
        for token in m.group(1).split(","):
            token = token.strip()
            if token.isdigit():
                nums.add(int(token))
    return nums
 
def read_main(path: str) -> str:
    return subprocess.run(
        ["git", "show", f"origin/main:{path}"],
        capture_output=True, text=True,
    ).stdout
 
def main(paths: list[str]) -> int:
    failed = False
    for path in paths:
        old = read_main(path)
        if not old:
            continue  # new file, nothing to compare
        with open(path, encoding="utf-8") as f:
            new = f.read()
        removed = field_numbers(old) - field_numbers(new)
        unreserved = removed - reserved_numbers(new)
        if unreserved:
            print(f"Blocked {path}: deleted numbers {sorted(unreserved)} are not reserved")
            failed = True
    return 1 if failed else 0
 
if __name__ == "__main__":
    sys.exit(main(sys.argv[1:]))

It is a deliberately blunt regex implementation and does not strictly distinguish nested messages. Even so, it catches the most common gap, "deleted a number but forgot to seal it," with no external dependencies. buf breaking handles structural compatibility while this script handles number hygiene, a double layer.

How Much to Delegate to the Agent

None of this machinery is about distrusting the agent. The opposite: it is the foundation that lets me delegate with peace of mind.

My boundary is this. Adding fields, tidying comments, unifying naming, reorganizing package structure, I hand over directly. None of these break wire compatibility. On the other hand, deleting fields, changing numbers, changing types, all pass through the three layers of reserved, buf breaking, and the number check. Even if the agent proposes it, it cannot be pushed unless it clears the gate.

Since adopting this design, my hesitation around proto changes has dropped. Because I know the machine stops the breaking operations, I can hand off formatting without a second thought. Separating what to delegate from what to verify is, in the end, what lets me use the agent more deeply. On the question of how to hand over write access, it also connects to the production design of Permission Boundary for safely granting write access to an Antigravity Agent.

Wrapping Up

As a next step, drop a buf.yaml into your own proto repository, set breaking.use to WIRE, and run buf breaking --against '.git#branch=main,subdir=.' once by hand. You will immediately see whether the diff between your current main and working branch is safe from the wire's point of view. From there, extend into the hook and check script, and your unease about handing proto to an agent moves over to the side of the tooling.

How do you defend the plain, fragile territory of schema compatibility by machine? I am still polishing my own workflow, and I would be glad to keep learning alongside you.