What a breaking-change verdict should tell an AI agent

Most API diff tools answer one question: what changed. For a human skimming a pull request, that is often enough. For an AI agent calling that API at runtime, it is not even close.

When an agent depends on an API and the contract shifts under it, the failure is silent. The tests were green. The diff was reviewed. Then, mid-task, a call returns a 404, or a field that used to be a number comes back a string, and the agent has no idea why. The diff told a human what changed. Nobody told the agent what it meant, or what to do about it.

A verdict an agent can act on has to answer six questions, not one:

1. Is it safe for me to call this?
2. How dangerous is the change?
3. What exactly broke?
4. What does that mean for consumers like me?
5. How do I work around it?
6. What does it cost?

This is the contract CodeRifts returns on every /diff. Here is what each question looks like in the real response.

Is it safe? How dangerous?

The verdict leads the payload, so a streaming or truncating agent gets it first:

{
  "decision": "BLOCK",
  "safe_for_agent": false,
  "risk_score": 60,
  "breaking_changes": 4
}

safe_for_agent is the single boolean an agent gates on. decision is one of ALLOW, WARN, REQUIRE_APPROVAL, BLOCK.

What broke, and what does it mean?

This is the part a plain diff skips. CodeRifts names each pattern and spells out the consequence:

{
  "name": "AUTH_SCHEME_REMOVAL",
  "severity": "CRITICAL",
  "consequence": "All consumers using this auth method will be rejected."
}

AUTH_SCHEME_REMOVAL is what changed. "All consumers using this auth method will be rejected" is what it means. The agent does not have to infer the blast radius. It is told.

How do I work around it?

A BLOCK with no path forward is just an obstacle. Every breaking change comes with a non-breaking migration:

{
  "change": "type_changed",
  "field": "total",
  "suggestion": "Instead of changing the type of total, keep the old type and add a new field (e.g. total_v2) with the new type. Deprecate the old field after consumers migrate.",
  "effort": "medium"
}

What does it cost?

Two layers. Security findings flag the most dangerous class explicitly:

{
  "severity": "critical",
  "finding": "Auth scheme removed",
  "details": "Auth scheme 'oauth2' removed"
}

And token_cost_impact reports the per-call token and dollar delta of the change, so a cost-sensitive agent can weigh it in economic terms, not just risk.

And how do I depend on this natively?

Every verdict ships its own integration path:

{
  "mcp_config": { "url": "https://app.coderifts.com/mcp", "transport": "streamable-http" },
  "registry": "io.github.coderifts/api-governance",
  "manifest": "https://coderifts.com/mcp.json"
}

The whole response is machine-readable and front-loaded by design. An agent reads safe_for_agent; if it needs more, the consequence, the fix, and the cost are all right there, in a fixed shape it can parse without scraping prose.

That is the difference between a diff and a verdict. A diff tells you what changed. A verdict tells an agent whether to proceed.