How Agents Use the Decision Spec

Python

import requests

def should_call_api(spec_url: str) -> tuple[bool, str]:
    r = requests.get(
        "https://app.coderifts.com/api/v1/public/preflight",
        params={"url": spec_url}
    )
    data = r.json()
    if data["decision"] == "BLOCK":
        return False, f"Blocked. Risk: {data['risk_score']}/100"
    if data["decision"] == "REQUIRE_APPROVAL":
        # surface to your approval flow; do not auto-proceed
        return False, f"Needs approval: {data['decision']}"
    if not data["safe_for_agent"]:
        return False, f"Unsafe: {data['decision']}"
    return True, "Safe to call"

Node.js

async function shouldCallAPI(specUrl) {
  const res = await fetch(
    `https://app.coderifts.com/api/v1/public/preflight?url=${encodeURIComponent(specUrl)}`
  );
  const data = await res.json();
  if (data.decision === 'BLOCK') {
    throw new Error(`CodeRifts BLOCK: risk ${data.risk_score}/100`);
  }
  if (data.decision === 'REQUIRE_APPROVAL') {
    // surface to your approval flow; do not auto-proceed
    return requestHumanApproval(data);
  }
  if (!data.safe_for_agent) {
    const reason = `${data.decision}: ${data.patterns?.map(p => p.pattern).join(', ')}`;
    throw new Error(`CodeRifts: ${reason}`);
  }
}

Go

func ShouldCallAPI(specURL string) (bool, string, error) {
    resp, err := http.Get(
        "https://app.coderifts.com/api/v1/public/preflight?url=" + url.QueryEscape(specURL),
    )
    if err != nil {
        return false, "", err
    }
    defer resp.Body.Close()
    var decision map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&decision)
    if decision["decision"] == "BLOCK" {
        return false, fmt.Sprintf("Blocked. Risk: %v/100", decision["risk_score"]), nil
    }
    if decision["decision"] == "REQUIRE_APPROVAL" {
        // surface to your approval flow; do not auto-proceed
        return false, "Needs approval", nil
    }
    if safeForAgent, ok := decision["safe_for_agent"].(bool); ok && !safeForAgent {
        return false, "Not safe for agents", nil
    }
    return true, "Safe to call", nil
}

LangChain Integration

from langchain.tools import tool
import requests

@tool
def governed_api_call(spec_url: str, endpoint: str, payload: dict):
    """Call an API endpoint with CodeRifts governance check."""
    check = requests.get(
        "https://app.coderifts.com/api/v1/public/preflight",
        params={"url": spec_url}
    ).json()
    if not check["safe_for_agent"]:
        return {"error": f"CodeRifts BLOCK: {check['decision']}", "risk": check["risk_score"]}
    # Proceed with the actual API call
    return requests.post(endpoint, json=payload).json()

Reading from PR Comments

CodeRifts posts a machine-readable JSON block in every PR comment. AI agents (Grok, Claude, Copilot) can extract it directly:

# The JSON block is embedded in every PR comment as:
# <!-- coderifts-agent-data -->
# {"coderifts_version":"1.0","decision":"BLOCK",...}
# <!-- /coderifts-agent-data -->

import re, json

def extract_coderifts_decision(pr_comment: str) -> dict:
    match = re.search(
        r'<!-- coderifts-agent-data -->\n(.*?)\n<!-- /coderifts-agent-data -->',
        pr_comment, re.DOTALL
    )
    if match:
        return json.loads(match.group(1))
    return None

Auto-Discovery

Agents can discover CodeRifts automatically from any API that publishes a manifest:

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

This returns the full manifest including preflight endpoint, spec version, and available tools.

Decision Reference

decision	safe_for_agent	Agent Action
BLOCK	false	Do not call. Human review required.
REQUIRE_APPROVAL	false	Pause. Wait for human sign-off.
WARN	true	Proceed with monitoring.
ALLOW	true	Proceed; apply your own runtime checks.

Machine-Readable Schema

The full JSON Schema for the Decision Spec is available at:

GET https://app.coderifts.com/api/v1/decision-spec/schema

Use this to validate CodeRifts responses in your own systems.