How Agents Use the Decision Spec

Normative contract: Decision Spec v2 — preflight_mode required; analyze is informational only; authorize is operation-bound and may mint a receipt. This page is sample integration code only; do not treat it as a second protocol definition.

Reading a verdict is not preventing a call. For fail-closed tool-table wrapping, use Agents quickstart (@coderifts/agent-guard).

Which mode?

Act (merge / deploy / tool_call): preflight_mode: "authorize" + context.operation. Branch on execution_action; verify chain_receipt before gates act.

Assess risk only: preflight_mode: "analyze". Branch on analysis_outcome / may_execute (always false). No decision / execution_action / safe_for_agent on analyze.

Mode-less request → HTTP 400. Legacy pin: decision_spec_version: "1.0" until 2026-09-07 (deprecated).

Python (authorize — act on the result)

import requests

def authorize_change(artifacts: list, operation: str = "merge") -> dict:
    r = requests.post(
        "https://app.coderifts.com/api/v1/preflight",
        headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
        json={
            "preflight_mode": "authorize",
            "context": {"operation": operation},
            "artifacts": artifacts,  # [{id, type, before, after}, ...]
        },
        timeout=60,
    )
    r.raise_for_status()
    data = r.json()
    # Authorize only: branch on execution_action; decision explains why.
    action = data.get("execution_action")
    if action != "CONTINUE":
        raise RuntimeError(
            f"CodeRifts halted: execution_action={action!r} (decision={data.get('decision')})"
        )
    # Downstream: verify data.get("chain_receipt") conjunctively before merge/deploy.
    return data

Node.js (authorize)

async function authorizeChange(artifacts, operation = 'merge') {
  const res = await fetch('https://app.coderifts.com/api/v1/preflight', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.CODERIFTS_API_KEY}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      preflight_mode: 'authorize',
      context: { operation },
      artifacts,
    }),
  });
  if (!res.ok) throw new Error(`preflight HTTP ${res.status}`);
  const data = await res.json();
  if (data.execution_action !== 'CONTINUE') {
    throw new Error(
      `CodeRifts halted: execution_action=${JSON.stringify(data.execution_action)} (decision=${data.decision})`
    );
  }
  return data; // hand chain_receipt to gates
}

Go (authorize)

// POST /api/v1/preflight with preflight_mode=authorize and context.operation.
// Branch on execution_action == "CONTINUE" only; unknown values fail closed.
// Full field list: https://coderifts.com/decision-spec/

Analyze (risk only — not permission)

payload = {
  "preflight_mode": "analyze",
  "artifacts": artifacts,
}
# Response has analysis_outcome, may_execute:false, authorization_effect:NONE, receipt_kind:NONE
# Omits decision, execution_action, safe_for_agent — do not invent them.
# Branch on analysis_outcome / may_execute for logging; never treat as green light to act.

Quick reference (authorize)

Branch on execution_action; use decision as explanation. Full table and analyze branch: Decision Spec v2.

execution_action	Agent action
`STOP`	Do not proceed. Remediate, then re-preflight authorize.
`REQUEST_APPROVAL`	Pause for human sign-off.
`CONTINUE_WITH_MONITORING`	Only if a monitoring sink is wired.
`CONTINUE`	Proceed subject to receipt verification at gates.
unrecognised	Fail closed — not permission.

Schemas

GET https://coderifts.com/schemas/preflight-response.v2.consumer.json
GET https://coderifts.com/decision-spec/   # prose + examples