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()
    # Branch on execution_action (proceed); decision explains why.
    action, decision = data.get("execution_action"), data.get("decision")
    # CONTINUE_WITH_MONITORING requires @coderifts/agent-guard monitoringSinkWired:true
    # (plus a real monitor callback); this example has no sink — proceed only on CONTINUE.
    if action != "CONTINUE":
        return False, f"CodeRifts aborted: execution_action={action!r} (decision={decision})"
    if not data["safe_for_agent"]:
        return False, f"Unsafe: {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();
  // Branch on execution_action (proceed); decision explains why.
  const action = data.execution_action;
  const decision = data.decision;
  // CONTINUE_WITH_MONITORING requires @coderifts/agent-guard monitoringSinkWired:true
  // (plus a real monitor callback); this example has no sink — proceed only on CONTINUE.
  if (action !== 'CONTINUE') {
    throw new Error(`CodeRifts aborted: execution_action=${JSON.stringify(action)} (decision=${decision})`);
  }
  if (!data.safe_for_agent) {
    const reason = `${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 data map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&data)
    // Branch on execution_action (proceed); decision explains why.
    action, _ := data["execution_action"].(string)
    decision, _ := data["decision"].(string)
    // CONTINUE_WITH_MONITORING requires @coderifts/agent-guard monitoringSinkWired:true
    // (plus a real monitor callback); this example has no sink — proceed only on CONTINUE.
    if action != "CONTINUE" {
        return false, fmt.Sprintf("CodeRifts aborted: execution_action=%q (decision=%s)", action, decision), nil
    }
    if safeForAgent, ok := data["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()
    # Branch on execution_action (proceed); decision explains why.
    action, decision = check.get("execution_action"), check.get("decision")
    # CONTINUE_WITH_MONITORING requires @coderifts/agent-guard monitoringSinkWired:true
    # (plus a real monitor callback); this example has no sink — proceed only on CONTINUE.
    if action != "CONTINUE":
        return {"error": f"CodeRifts aborted: execution_action={action!r} (decision={decision})", "risk": check.get("risk_score")}
    if not check.get("safe_for_agent"):
        return {"error": f"CodeRifts {decision}: not safe_for_agent", "risk": check.get("risk_score")}
    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

Branch on execution_action (the proceed signal); use decision as the explanation.

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

Machine-Readable Schema

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

GET https://coderifts.com/decision-spec/v1.0.json

Use this to validate CodeRifts responses in your own systems.