CodeRifts Decision Spec

Decision Object (Public Layer)

Every CodeRifts analysis returns a Decision Object. The public fields are stable, versioned, and free to consume without authentication.

{
  "coderifts_version": "1.0",
  "decision": "BLOCK",
  "risk_score": 87,
  "safe_for_agent": false,
  "breaking_changes": 3,
  "patterns": [
    "AUTH_SCOPE_REDUCTION",
    "FIELD_REMOVED",
    "ENDPOINT_REMOVED"
  ],
  "requires_migration": true,
  "timestamp": "2026-03-18T10:00:00Z"
}

Field Definitions

Decision Values

safe_for_agent Flag

safe_for_agent: false is set when any of the following agent-breaking patterns are detected:

• • Tool schema drift (TOOL_CALLING_SCHEMA_DRIFT)
• • Tool result shape change (TOOL_RESULT_SHAPE_DRIFT)
• • Agent protocol change (AGENT_PROTOCOL_DRIFT)
• • Workflow chain break (WORKFLOW_CHAIN_BREAK)
• • Auth delegation change (AUTH_DELEGATION_DRIFT)
• • Shared state schema change (SHARED_STATE_SCHEMA_DRIFT)

Pattern Registry (v1.0)

Patterns are named identifiers for categories of breaking changes. They are stable across spec versions.

Contract Patterns

Agent Patterns

Behavioral Patterns

Extended Decision Object (Authenticated)

With an API key, the full decision object is returned including blast radius, migration plan, compliance index, and workflow simulation:

{
  "coderifts_version": "1.0",
  "decision": "BLOCK",
  "risk_score": 87,
  "safe_for_agent": false,
  "breaking_changes": 3,
  "patterns": ["AUTH_SCOPE_REDUCTION", "FIELD_REMOVED"],
  "requires_migration": true,
  "timestamp": "2026-03-18T10:00:00Z",

  "extended": {
    "omega_api": 87.3,
    "reflex_triggers": [
      { "rule": "endpoint_removed ∧ public_api", "decision": "BLOCK" }
    ],
    "blast_radius": {
      "affected_consumers": 4,
      "estimated_cost": "$12,000–$45,000",
      "migration_effort_days": 8
    },
    "migration_plan": "Restore removed field as deprecated with x-sunset date. Notify consumers via POST /api/v1/scar/create.",
    "compliance_index": "F",
    "workflow_simulation": {
      "simulation_result": "WORKFLOW_BROKEN",
      "first_failure_step": 2
    }
  }
}

How Agents Should Use This Spec

Step 1: Preflight Check Before Tool Call

POST https://app.coderifts.com/api/v1/agent/preflight
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "tools_before": [ /* previous tool schemas */ ],
  "tools_after": [ /* current tool schemas */ ]
}

Step 2: Parse the Decision

const { decision, safe_for_agent, patterns } = response;

if (!safe_for_agent || decision === "BLOCK") {
  throw new Error(`API change blocks agent execution. Patterns: ${patterns.join(", ")}`);
}

if (decision === "REQUIRE_APPROVAL") {
  await requestHumanApproval(response);
  return;
}

// ALLOW or WARN — proceed
await callAPI();

Step 3: Handle BLOCK Gracefully

if (decision === "BLOCK") {
  // 1. Log the block with full decision object
  // 2. Notify the team
  // 3. Do not retry — human review required
  // 4. Check extended.migration_plan for remediation steps
}

Integration Examples

LangChain

from langchain.tools import tool

@tool
def safe_api_call(endpoint: str, payload: dict):
    """Call an API endpoint with CodeRifts governance check."""
    preflight = coderifts.preflight_check(
        tools_before=get_cached_schema(endpoint),
        tools_after=get_current_schema(endpoint)
    )

    if not preflight["safe_for_agent"]:
        return {"error": f"Blocked by CodeRifts. Decision: {preflight['decision']}"}

    return call_endpoint(endpoint, payload)

AutoGen

import autogen

def coderifts_preflight_hook(agent, message):
    result = coderifts.preflight_check(message["tool_schemas"])
    if result["decision"] == "BLOCK":
        raise ValueError(f"CodeRifts BLOCK: {result['patterns']}")
    return message

agent = autogen.AssistantAgent(
    name="SafeAgent",
    pre_message_hooks=[coderifts_preflight_hook]
)

Claude / MCP

{
  "mcpServers": {
    "coderifts": {
      "url": "https://coderifts.com/mcp.json",
      "headers": { "x-api-key": "YOUR_API_KEY" }
    }
  }
}

Claude will automatically run coderifts.preflight_check before tool invocations.

Auto-Discovery

Agents can discover CodeRifts governance endpoints automatically:

GET https://coderifts.com/.well-known/coderifts.json

Returns the full manifest including available tools, endpoints, and this spec URL.

Versioning Policy

• • This is v1.0. The public layer fields (decision, risk_score, safe_for_agent, breaking_changes, patterns, requires_migration) are stable and will not change in v1.x.
• • New fields may be added in minor versions (v1.1, v1.2) without breaking existing consumers.
• • Breaking changes to the spec format will only occur in major versions (v2.0) with 6 months notice.

Changelog

Links

• API Reference
• MCP Manifest
• Well-Known Discovery
• Agent Frameworks Integration
• GitHub