A Discovery and Attestation Protocol for AI Tool Contracts

An agent calls a tool against an assumed contract. When that contract drifts, a field rename, a removal, a response shape change, the agent either breaks or, worse, hallucinates around the gap and keeps going. A guard that diffs the new contract against the old one catches this before any tool code runs. But a guard is only as good as the baseline it diffs against, and to be usable inside tight agent loops it has to stay zero-config, fast, and deterministic.

So the real question is not whether you can diff a contract. It is how an agent gets a current, trustworthy contract to diff against, with zero per-call config, and verifies it cheaply on every call. This is a working sketch of a protocol for exactly that. It is intentionally open and implementation-agnostic.

Design goals

• Zero per-call config. The agent should not be handed specs by hand on every call.
• Deterministic. The same change always produces the same decision.
• Fast hot path. Steady-state cost inside a loop should approach zero.
• Decentralized. No central authority, no extra trust root to compromise.
• Verifiable. The agent can prove what it is trusting.

Three primitives

Contract by hash. The canonical contract (OpenAPI, GraphQL, gRPC, or AsyncAPI) lives in the repo and is identified by its content hash. The hash is both the pin and the cache key.

Verdict by hash. A guard produces a deterministic decision about a change and binds it to the content hash it concerns. The guard is a black box here. Any implementation that emits a deterministic, signable verdict fits the protocol; the quality of the guard is a separate concern from the shape of the protocol.

Git for provenance. Signed commits (GPG or SSH) anchor authenticity. The repo's immutable history becomes the transparency log: spec, verdicts, and signed attestations all live in one place.

Discovery and fetch flow

Each tool exposes its current contract at a predictable, well-known path. This is a small extension of the llms.txt pattern already in use, for example a /.well-known/contract endpoint that returns the contract, the signed commit SHA it came from, and the content hash.

Agent
  GET /.well-known/contract
    -> { contract, commit_sha, content_hash, attestation }
  verify  content_hash == hash(contract)      (integrity)
  verify  signature on the attestation        (verdict)
  verify  commit_sha is signed on main        (provenance)
  -> proceed, or block before the tool runs

The agent pulls lazily and caches by content hash. Two modes cover both ends of the lifecycle:

• Cold start, inline attestation. One fetch. The agent checks the signature and confirms the hash matches locally. Done.
• Steady state, separate attestation. The agent already holds the contract by hash, so a call becomes a tiny verdict revalidation. The verdict is small, deterministic, and bound only to the hash, so it caches and revalidates independently of the spec, with its own TTL and CDN behavior.

The two modes are the same artifact at different TTLs, not a fork in the design. The full contract re-fetches only when the hash actually changes. That collapses the loop-traffic cost, which is the whole reason the protocol has to look like this.

The trust model

A contract changes only through a pull request, and a guard inspects every pull request. So an under-declared breaking change never reaches HEAD in the first place. That removes the need for a central authority to vouch for contracts:

• Provenance is the signed commit.
• Integrity is the content hash.
• The verdict is a signed attestation bound to that hash.

The repo itself becomes the transparency log. No central service, no extra trust root.

"Git provenance plus that hash pin turns the repo itself into the transparency log. Contract changes, guard decisions, and signed attestations all live in the same immutable history. No central service, no extra trust root."

What ships today, and what is proposed

This sketch separates shipped behavior from the proposed layer on purpose.

Today. Git is the source of truth. A zero-config GitHub App diffs each pull request against the merge base and blocks breaking changes at PR time with a deterministic decision. An llms.txt is published at a known path, a .coderifts.yml policy file governs rules, and an inline x-coderifts extension lets a contract carry its own policy.

Proposed, and building toward. The /.well-known/contract discovery endpoint, signed verdict attestations bound to the content hash, and the agent-side lazy fetch with a hash-pinned cache.

Open questions

• Endpoint shape and revalidation: what the well-known payload carries, and how caches revalidate a verdict independently of the spec.
• Attestation signing and key distribution: reuse the commit-signing key, or a separate guard key with its own rotation.
• Multi-agent setups: how a fleet shares and revalidates verdicts without re-fetching contracts.

The protocol is intentionally open and guard-agnostic. The value sits in the quality of the guard, not in owning the format. The goal is to make the pattern easy enough that many agent developers adopt it, so we collectively build fewer brittle agent systems and safer defaults.

Try it

The PR-time guard ships today as a zero-config GitHub App. Open the demo PR to see a real block with the exact field that breaks, or install it on a repo.