coderifts 3.1.0 → 3.2.0

package/README.md

@@ -138,6 +138,53 @@ After upgrading the `coderifts` CLI, re-run `coderifts hook install` so the
 installed hook matches the package (already-installed hooks are not
 auto-updated).
 
+### Claude Code PreToolUse (`coderifts claude-hook`) — ID824
+
+Tool-call-time gate for **Claude Code**: blocks contract-touching `Write` /
+`Edit` / `MultiEdit` when authorize preflight returns **BLOCK/STOP**.
+
+**Exit map (Claude Code semantics — fixed):**
+
+| Exit | Meaning |
+|------|---------|
+| **2** | **BLOCK** — tool call cancelled; stderr is shown to the model |
+| **0** | Allow, or soft-skip (no key / wrong file / parse gap / API down) |
+| **1** | **Never used for deny** — Claude treats exit 1 as non-blocking (action proceeds) |
+
+Push-time equivalent (git exit **1** on BLOCK): `coderifts hook install`.
+
+**Install path:** `npm i -g coderifts` then set key + spec (same as the git hook):
+
+```bash
+git config coderifts.apiKey 'cr_live_…'          # or: coderifts login / CODERIFTS_API_KEY
+git config coderifts.specPath api/openapi.yaml   # default if omitted
+```
+
+**Recipe — project** (`.claude/settings.json`) **or user** (`~/.claude/settings.json`):
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "coderifts claude-hook",
+            "timeout": 60
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+- **Project** `.claude/settings.json` — shared with the repo (commit if the team wants the gate).
+- **User** `~/.claude/settings.json` — personal; applies to all projects on this machine.
+- Matcher is case-sensitive tool names/regex. Exit-2 blocking is **Claude Code** semantics; the same decision discipline at push-time is the git pre-push hook above.
+
 ### Agent host files (`coderifts agent-setup`)
 
 Writes the six CodeRifts agent-host rule files into the current repo (or `--out <dir>`):

package/bin/coderifts.js

@@ -109,6 +109,7 @@ program
   .option('--branch <name>', 'Branch to protect (default: repo default branch)')
   .option('--repo <owner/repo>', 'Override owner/repo (default: git remote origin)')
   .option('--apply', 'Apply the protection change (default: print the exact gh command only)')
+  .option('--enforce-admins', 'Set enforce_admins:true on create (default: false — admins can bypass; gate reports admin_bypass_open)')
   .option('--json', 'Machine-readable JSON result')
   .action(async (options) => {
     const { runSetupRequiredCheck } = require('../src/commands/setup-required-check');
@@ -201,6 +202,48 @@ program
     }
   });
 
+// ── outcome — POST /api/v1/outcomes (caller assertion; does not verify the deploy) ──
+program
+  .command('outcome <kind>')
+  .description(
+    'Report a post-hoc outcome for a decision_id (deploy_succeeded/deploy_failed/…). '
+    + 'Records the caller\'s assertion — does not verify the deploy itself.',
+  )
+  .option('--decision <decision_id>', 'Decision id from decision_result.decision_id (required)')
+  .option('--observed-at <iso>', 'When the outcome was observed (ISO-8601; default: now)')
+  .option('--details <json>', 'Optional JSON object/array bound to the outcome row')
+  .option('--json', 'Print the API response JSON to stdout')
+  .addHelpText('after', () => {
+    const { USAGE } = require('../src/commands/outcome');
+    return `\n${USAGE}\n`;
+  })
+  .action(async (kind, options) => {
+    const { runOutcome } = require('../src/commands/outcome');
+    const result = await runOutcome(kind, options);
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── claude-hook — Claude Code PreToolUse (exit 2 = BLOCK; never exit 1 for deny) ──
+program
+  .command('claude-hook')
+  .description(
+    'Claude Code PreToolUse gate: block contract-touching Write|Edit|MultiEdit on BLOCK/STOP '
+    + '(exit 2). Soft-allow when unconfigured/unparseable/API down.',
+  )
+  .addHelpText('after', () => {
+    const { USAGE } = require('../src/commands/claude-hook');
+    return `\n${USAGE}\n`;
+  })
+  .action(async () => {
+    const { runClaudeHook } = require('../src/commands/claude-hook');
+    const result = await runClaudeHook();
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
 // ── hook command group ──
 const hookCmd = program
   .command('hook')

package/dist/cli.js

@@ -3007,7 +3007,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "coderifts",
-      version: "3.1.0",
+      version: "3.2.0",
       description: "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
       author: "CodeRifts <hello@coderifts.com>",
       license: "MIT",
@@ -3045,7 +3045,7 @@ var require_package = __commonJS({
       },
       scripts: {
         build: "node scripts/copy-corpus.js && esbuild bin/coderifts.js --bundle --platform=node --target=node18 --outfile=dist/cli.js",
-        prepublishOnly: "npm run build",
+        prepublishOnly: "bash ../../scripts/freeze-gate.sh && npm run build",
         postinstall: "node scripts/postinstall.js",
         test: "node --test test/*.test.js"
       },
@@ -13553,11 +13553,33 @@ var require_cloud = __commonJS({
       const q = encodeURIComponent(String(repo || ""));
       return cloudRequest("GET", `/api/v1/lock?repo=${q}`, apiKey);
     }
+    function cloudPostOutcome(apiKey, body) {
+      return cloudRequest("POST", "/api/v1/outcomes", apiKey, body);
+    }
+    function cloudAuthorizePreflight(before, after, apiKey, ctx = {}) {
+      return cloudRequest("POST", "/api/v1/preflight", apiKey, {
+        preflight_mode: "authorize",
+        artifacts: [
+          {
+            id: "api",
+            type: "openapi",
+            before: String(before == null ? "" : before),
+            after: String(after == null ? "" : after)
+          }
+        ],
+        context: {
+          operation: ctx.operation || "merge",
+          environment: ctx.environment || "staging"
+        }
+      });
+    }
     module2.exports = {
       cloudDiff,
       cloudRequest,
       cloudGetEnforcementStatus,
       cloudGetLock,
+      cloudPostOutcome,
+      cloudAuthorizePreflight,
       API_BASE
     };
   }
@@ -69056,6 +69078,24 @@ var require_deploy_gate2 = __commonJS({
         return null;
       }
     }
+    function extractDecisionIdFromReceipt(receipt) {
+      if (!receipt || typeof receipt !== "object") return null;
+      if (typeof receipt.decision_id === "string" && receipt.decision_id.trim()) {
+        return receipt.decision_id.trim();
+      }
+      const nested = receipt.decision_result;
+      if (nested && typeof nested === "object" && typeof nested.decision_id === "string" && nested.decision_id.trim()) {
+        return nested.decision_id.trim();
+      }
+      return null;
+    }
+    function formatOutcomeReportHint(decisionId) {
+      const id = String(decisionId);
+      return [
+        "# report the deploy outcome after your deploy step:",
+        `coderifts outcome <deploy_succeeded|deploy_failed|rolled_back> --decision ${id}`
+      ].join("\n");
+    }
     function renderDeployGateTerminal(bind, enforce) {
       const g = bind.gate;
       const color = bind.deploy_check_status === "success" ? chalk.green : bind.deploy_check_status === "failure" ? chalk.red : chalk.yellow;
@@ -69085,10 +69125,23 @@ var require_deploy_gate2 = __commonJS({
       const observed = observeCDEnforcement({ enforce });
       const bind = deployBind({ environment, artifact_id: artifactId, receipt, observed_cd_enforcement: observed });
       const code = clampExit(bind.deploy_check_status, enforce);
+      const decisionId = extractDecisionIdFromReceipt(receipt);
       if (options.json) {
-        console.log(renderJson({ command: "deploy-gate", environment, artifact_id: artifactId, phase: enforce ? "enforcing" : "advisory", exit_code: code, ...bind }));
+        console.log(renderJson({
+          command: "deploy-gate",
+          environment,
+          artifact_id: artifactId,
+          phase: enforce ? "enforcing" : "advisory",
+          exit_code: code,
+          decision_id: decisionId,
+          ...bind
+        }));
       } else {
         console.log(renderDeployGateTerminal(bind, enforce));
+        if (decisionId) {
+          console.log(formatOutcomeReportHint(decisionId));
+          console.log("");
+        }
       }
       process.exit(code);
     }
@@ -69098,6 +69151,8 @@ var require_deploy_gate2 = __commonJS({
       observeCDEnforcement,
       clampExit,
       readReceiptFile,
+      extractDecisionIdFromReceipt,
+      formatOutcomeReportHint,
       renderDeployGateTerminal
     };
   }
@@ -95855,13 +95910,30 @@ var require_setup_required_check = __commonJS({
       if (!protection || typeof protection !== "object") return [];
       const rsc = protection.required_status_checks;
       if (!rsc || typeof rsc !== "object") return [];
-      if (Array.isArray(rsc.contexts) && rsc.contexts.length) {
-        return rsc.contexts.map((c) => String(c));
+      const raw = rsc.contexts || (Array.isArray(rsc.checks) ? rsc.checks.map((c) => c && c.context) : []);
+      if (!Array.isArray(raw)) return [];
+      return raw.map((c) => c == null ? "" : String(c)).filter(Boolean);
+    }
+    var HINT_403_PLAN_LIMIT = "private repo on a free plan: branch protection requires GitHub Pro or a public repo";
+    var HINT_403_PERMISSION = "administration:read (or repo admin) required to read branch protection \u2014 try: gh auth refresh -s repo";
+    var HINT_403_BOTH = "cannot distinguish cause from the response body \u2014 either (1) private repo on a free plan (branch protection needs GitHub Pro or a public repo) or (2) missing administration:read / repo admin (try: gh auth refresh -s repo)";
+    function github403EvidenceText(read) {
+      const parts = [];
+      const body = read && read.body;
+      if (body && typeof body === "object" && body.message != null) parts.push(String(body.message));
+      if (typeof body === "string" && body.trim()) parts.push(body);
+      if (read && read.errorMessage) parts.push(String(read.errorMessage));
+      return parts.join("\n");
+    }
+    function classify403Cause(read) {
+      const text = github403EvidenceText(read || {});
+      if (/Upgrade to GitHub Pro|make this repository public/i.test(text)) {
+        return { cause: "plan_limit", permission_hint: HINT_403_PLAN_LIMIT };
       }
-      if (Array.isArray(rsc.checks)) {
-        return rsc.checks.map((c) => c && c.context != null ? String(c.context) : "").filter(Boolean);
+      if (/Resource not accessible|insufficient.*scope|not have permission|Must have admin|Requires authentication|Bad credentials|admin(istration)?:?(read|write)?/i.test(text) && !/Upgrade to GitHub Pro/i.test(text)) {
+        return { cause: "permission", permission_hint: HINT_403_PERMISSION };
       }
-      return [];
+      return { cause: "unknown", permission_hint: HINT_403_BOTH };
     }
     function classifyObservation(read, contextName = CHECK_NAME) {
       const status = read && read.status != null ? Number(read.status) : null;
@@ -95875,13 +95947,15 @@ var require_setup_required_check = __commonJS({
         };
       }
       if (status === 403) {
+        const disc = classify403Cause(read);
         return {
           state: "UNKNOWN",
           context_is_required: false,
           required_contexts: [],
           protection: null,
           observation_error: "403",
-          permission_hint: "administration:read (or repo admin) required to read branch protection"
+          observation_cause: disc.cause,
+          permission_hint: disc.permission_hint
         };
       }
       if (status != null && status >= 400) {
@@ -96225,11 +96299,25 @@ var require_setup_required_check = __commonJS({
         if (!options.json) {
           logErr(chalk.red("Cannot observe branch protection (UNKNOWN)."));
           logErr(`  HTTP: ${obs.observation_error || "unknown"}`);
-          logErr(`  ${obs.permission_hint || "An admin with administration:read must run this command."}`);
-          logErr("  The CodeRifts App never writes protection; an admin must grant or run this.");
+          logErr(`  ${obs.permission_hint || HINT_403_BOTH}`);
+          if (obs.observation_cause === "plan_limit") {
+            logErr("  Not a missing-permission issue \u2014 the free-plan private-repo limit blocks classic protection reads.");
+          } else if (obs.observation_cause === "permission") {
+            logErr("  The CodeRifts App never writes protection; an admin must grant or run this.");
+          } else {
+            logErr("  The CodeRifts App never writes protection; fix plan limit or admin access, then re-run.");
+          }
         }
-        return finish(EXIT.PERMISSION, { ...basePayload, ok: false, code: "PERMISSION", observation_error: obs.observation_error });
+        return finish(EXIT.PERMISSION, {
+          ...basePayload,
+          ok: false,
+          code: "PERMISSION",
+          observation_error: obs.observation_error,
+          observation_cause: obs.observation_cause || null,
+          permission_hint: obs.permission_hint || null
+        });
       }
+      const enforceAdmins = options.enforceAdmins === true;
       let payload;
       if (obs.state === "ABSENT" || !obs.protection) {
         payload = {
@@ -96237,12 +96325,13 @@ var require_setup_required_check = __commonJS({
             strict: false,
             contexts: [CHECK_NAME]
           },
-          enforce_admins: false,
+          enforce_admins: enforceAdmins,
           required_pull_request_reviews: null,
           restrictions: null
         };
       } else {
         payload = buildProtectionUpdatePayload(obs.protection, CHECK_NAME);
+        if (enforceAdmins) payload.enforce_admins = true;
       }
       const cmdText = printApplyCommand(owner, repo, branch, payload);
       if (!options.apply) {
@@ -96251,6 +96340,11 @@ var require_setup_required_check = __commonJS({
           log(`  repo:   ${owner}/${repo}`);
           log(`  branch: ${branch}`);
           log("");
+          log("enforce_admins (admin bypass of the required check):");
+          log("  true: admins cannot bypass the contract gate (closes the admin_bypass_open residual)");
+          log("  false (default): admins can bypass; the gate reports admin_bypass_open");
+          log(`  this run: ${enforceAdmins ? "true (--enforce-admins)" : "false (default; pass --enforce-admins to set true)"}`);
+          log("");
           log("Dry-run (default). Exact command to add the required check with your credentials:");
           log("");
           log(cmdText);
@@ -96261,6 +96355,7 @@ var require_setup_required_check = __commonJS({
         return finish(EXIT.NEEDS_APPLY, {
           ...basePayload,
           code: "NEEDS_APPLY",
+          enforce_admins: enforceAdmins,
           apply_command: cmdText,
           apply_payload: payload
         });
@@ -96336,6 +96431,11 @@ var require_setup_required_check = __commonJS({
       EXIT,
       extractRequiredContexts,
       classifyObservation,
+      classify403Cause,
+      github403EvidenceText,
+      HINT_403_PLAN_LIMIT,
+      HINT_403_PERMISSION,
+      HINT_403_BOTH,
       buildProtectionUpdatePayload,
       detectRulesetRequiredCheck,
       parseGitHubRemote,
@@ -97541,6 +97641,437 @@ var require_lock = __commonJS({
   }
 });
 
+// src/commands/outcome.js
+var require_outcome = __commonJS({
+  "src/commands/outcome.js"(exports2, module2) {
+    "use strict";
+    var chalk = require_source();
+    var { getApiKey } = require_config();
+    var { cloudPostOutcome } = require_cloud();
+    if (process.env.NO_COLOR) chalk.level = 0;
+    var OUTCOME_KINDS = Object.freeze([
+      "deploy_succeeded",
+      "deploy_failed",
+      "rolled_back",
+      "consumer_break_reported",
+      "remediation_verified_working",
+      "false_positive_reported",
+      "other_reported"
+    ]);
+    var OUTCOME_KIND_SET = new Set(OUTCOME_KINDS);
+    var USAGE = [
+      "Usage: coderifts outcome <kind> --decision <decision_id> [--observed-at <ISO>] [--details <json>] [--json]",
+      "",
+      "Report a post-hoc observed outcome for a past decision_id to the CodeRifts cloud API.",
+      "This records the CALLER'S assertion (e.g. your deploy job knows success/failure) \u2014",
+      "the command does NOT itself verify that a deploy succeeded or failed.",
+      "",
+      "kind (required, closed set):",
+      `  ${OUTCOME_KINDS.join(", ")}`,
+      "",
+      "Requires a cloud API key (coderifts login or CODERIFTS_API_KEY).",
+      "POST /api/v1/outcomes \u2014 source is always reported (server-side); reporter is derived from the key."
+    ].join("\n");
+    function isValidOutcomeKind(kind) {
+      return typeof kind === "string" && OUTCOME_KIND_SET.has(kind);
+    }
+    function isValidObservedAt(iso) {
+      if (typeof iso !== "string" || !iso.trim()) return false;
+      const t = Date.parse(iso);
+      return Number.isFinite(t);
+    }
+    function parseDetails(raw) {
+      if (raw == null || raw === "") return { ok: true, details: null };
+      if (typeof raw !== "string") return { ok: false, error: "--details must be a JSON string" };
+      try {
+        const v = JSON.parse(raw);
+        if (v !== null && typeof v !== "object") {
+          return { ok: false, error: "--details must be a JSON object or array" };
+        }
+        return { ok: true, details: v };
+      } catch (e) {
+        return { ok: false, error: `--details is not valid JSON: ${e && e.message || "parse error"}` };
+      }
+    }
+    async function runOutcome(kind, options = {}, deps = {}) {
+      const getKey = deps.getApiKey || getApiKey;
+      const postOutcome = deps.cloudPostOutcome || cloudPostOutcome;
+      const log = deps.log || console.log;
+      const errLog = deps.errLog || console.error;
+      const nowIso = deps.nowIso || (() => (/* @__PURE__ */ new Date()).toISOString());
+      if (kind == null || String(kind).trim() === "") {
+        errLog(chalk.red("Error: missing outcome kind"));
+        errLog(USAGE);
+        return { exitCode: 1, error: "missing_kind" };
+      }
+      const outcomeKind = String(kind).trim();
+      if (!isValidOutcomeKind(outcomeKind)) {
+        errLog(chalk.red(`Error: invalid outcome kind '${outcomeKind}'`));
+        errLog(chalk.dim(`  Valid kinds: ${OUTCOME_KINDS.join(", ")}`));
+        return { exitCode: 1, error: "invalid_kind" };
+      }
+      const decisionId = options.decision != null ? String(options.decision).trim() : "";
+      if (!decisionId) {
+        errLog(chalk.red("Error: --decision <decision_id> is required"));
+        errLog(USAGE);
+        return { exitCode: 1, error: "missing_decision" };
+      }
+      let observedAt;
+      if (options.observedAt != null && String(options.observedAt).trim() !== "") {
+        observedAt = String(options.observedAt).trim();
+        if (!isValidObservedAt(observedAt)) {
+          errLog(chalk.red("Error: --observed-at must be a valid ISO-8601 timestamp"));
+          return { exitCode: 1, error: "invalid_observed_at" };
+        }
+      } else {
+        observedAt = nowIso();
+      }
+      const det = parseDetails(options.details);
+      if (!det.ok) {
+        errLog(chalk.red(`Error: ${det.error}`));
+        return { exitCode: 1, error: "invalid_details" };
+      }
+      const apiKey = getKey();
+      if (!apiKey) {
+        errLog(chalk.red("Error: no API key. Run `coderifts login` or set CODERIFTS_API_KEY."));
+        return { exitCode: 1, error: "missing_api_key" };
+      }
+      const body = {
+        decision_id: decisionId,
+        outcome_kind: outcomeKind,
+        observed_at: observedAt
+      };
+      if (det.details != null) body.details = det.details;
+      let response;
+      try {
+        response = await postOutcome(apiKey, body);
+      } catch (e) {
+        const msg = e && e.message ? String(e.message) : "request failed";
+        errLog(chalk.red(`Error: ${msg}`));
+        if (e && e.statusCode) errLog(chalk.dim(`  (HTTP ${e.statusCode})`));
+        if (e && e.code) errLog(chalk.dim(`  (${e.code})`));
+        return { exitCode: 1, error: msg, body };
+      }
+      if (options.json) {
+        log(JSON.stringify(response, null, 2));
+      } else {
+        const o = response && response.outcome ? response.outcome : response;
+        log(chalk.bold("CodeRifts outcome recorded"));
+        log(`  kind:        ${outcomeKind}`);
+        log(`  decision_id: ${decisionId}`);
+        log(`  observed_at: ${observedAt}`);
+        if (o && o.id) log(`  id:          ${o.id}`);
+        if (response && response.source) log(`  source:      ${response.source}`);
+        log(chalk.dim("  Caller assertion only \u2014 this command did not verify the deploy."));
+      }
+      return { exitCode: 0, response, body };
+    }
+    module2.exports = {
+      runOutcome,
+      isValidOutcomeKind,
+      isValidObservedAt,
+      parseDetails,
+      OUTCOME_KINDS,
+      USAGE
+    };
+  }
+});
+
+// src/commands/claude-hook.js
+var require_claude_hook = __commonJS({
+  "src/commands/claude-hook.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var { execSync } = require("child_process");
+    var { getApiKey } = require_config();
+    var { cloudAuthorizePreflight } = require_cloud();
+    var DEFAULT_SPEC_PATH = "api/openapi.yaml";
+    var CLOSED_ACTIONS = /* @__PURE__ */ new Set([
+      "CONTINUE",
+      "CONTINUE_WITH_MONITORING",
+      "REQUEST_APPROVAL",
+      "STOP"
+    ]);
+    var USAGE = [
+      "Usage: coderifts claude-hook",
+      "",
+      "Claude Code PreToolUse hook: gates Write|Edit|MultiEdit when they touch the",
+      "configured contract spec path. Reads JSON context from STDIN.",
+      "",
+      "Exit map (Claude Code semantics \u2014 get this exactly right):",
+      "  2  BLOCK \u2014 tool call cancelled (decision BLOCK/STOP or unrecognised execution_action)",
+      "  0  allow \u2014 or soft-skip (see soft contracts)",
+      "  1  NEVER used for security deny (Claude treats exit 1 as non-blocking; action proceeds)",
+      "",
+      "Soft contracts (exit 0 + one-line stderr note \u2014 do not brick the session):",
+      "  no API key (git config coderifts.apiKey / coderifts login / CODERIFTS_API_KEY)",
+      "  unparseable/unknown stdin shape",
+      "  file_path is not the configured spec path",
+      "  Edit/MultiEdit cannot be applied cleanly to disk content",
+      "  API unreachable / network error",
+      "",
+      "Spec path (same source as git pre-push hook):",
+      "  git config coderifts.specPath  (default: api/openapi.yaml)",
+      "",
+      "Baseline at PreToolUse: before = current file on disk (pre-edit state \u2014 the tool has",
+      "not written yet). after = proposed content from tool_input (Write: content; Edit/MultiEdit:",
+      "old\u2192new applied to disk content).",
+      "",
+      "Push-time equivalent: coderifts hook install (git exit 1 on BLOCK)."
+    ].join("\n");
+    function readGitConfig(key, deps = {}) {
+      const run = deps.execSync || execSync;
+      const cwd = deps.cwd || process.cwd();
+      try {
+        const v = run(`git config ${key}`, { encoding: "utf8", cwd, stdio: ["ignore", "pipe", "pipe"] });
+        const t = String(v || "").trim();
+        return t || null;
+      } catch {
+        return null;
+      }
+    }
+    function resolveApiKey(deps = {}) {
+      const getKey = deps.getApiKey || getApiKey;
+      const fromLogin = getKey();
+      if (fromLogin) return fromLogin;
+      const fromEnv = process.env.CODERIFTS_API_KEY && String(process.env.CODERIFTS_API_KEY).trim();
+      if (fromEnv) return fromEnv;
+      return readGitConfig("coderifts.apiKey", deps);
+    }
+    function resolveSpecPath(deps = {}) {
+      const fromGit = readGitConfig("coderifts.specPath", deps);
+      if (fromGit) return fromGit;
+      return DEFAULT_SPEC_PATH;
+    }
+    function parseStdinJson(raw) {
+      if (raw == null || String(raw).trim() === "") {
+        return { ok: false, reason: "empty stdin" };
+      }
+      let obj;
+      try {
+        obj = JSON.parse(String(raw));
+      } catch {
+        return { ok: false, reason: "stdin is not JSON" };
+      }
+      if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+        return { ok: false, reason: "stdin JSON is not an object" };
+      }
+      const toolName = obj.tool_name || obj.toolName || obj.name || null;
+      let toolInput = obj.tool_input || obj.toolInput || obj.input || null;
+      if (toolInput == null && obj.file_path) toolInput = obj;
+      if (!toolName || typeof toolName !== "string") {
+        return { ok: false, reason: "missing tool_name" };
+      }
+      if (!toolInput || typeof toolInput !== "object") {
+        return { ok: false, reason: "missing tool_input" };
+      }
+      return { ok: true, toolName: String(toolName), toolInput };
+    }
+    function isSpecPath(filePath, specPath) {
+      if (!filePath || !specPath) return false;
+      const fp = path.normalize(String(filePath).replace(/\\/g, "/"));
+      const sp = path.normalize(String(specPath).replace(/\\/g, "/"));
+      if (fp === sp) return true;
+      if (fp.endsWith("/" + sp) || fp.endsWith(sp)) return true;
+      const baseFp = path.basename(fp);
+      const baseSp = path.basename(sp);
+      if (baseFp === baseSp && (fp.endsWith(sp) || sp.endsWith(baseSp))) {
+        const tail = sp.split("/").filter(Boolean).join("/");
+        return fp.replace(/\\/g, "/").endsWith(tail);
+      }
+      return false;
+    }
+    function deriveAfterContent(toolName, toolInput, diskBefore) {
+      const name = String(toolName || "");
+      if (name === "Write" || name === "write") {
+        if (typeof toolInput.content !== "string") {
+          return { ok: false, reason: "Write tool_input.content missing or not a string" };
+        }
+        return { ok: true, after: toolInput.content };
+      }
+      if (name === "Edit" || name === "edit") {
+        const oldS = toolInput.old_string != null ? toolInput.old_string : toolInput.oldString;
+        const newS = toolInput.new_string != null ? toolInput.new_string : toolInput.newString;
+        if (typeof oldS !== "string" || typeof newS !== "string") {
+          return { ok: false, reason: "Edit tool_input.old_string/new_string missing" };
+        }
+        if (!diskBefore.includes(oldS)) {
+          return { ok: false, reason: "Edit old_string not found in disk content" };
+        }
+        return { ok: true, after: diskBefore.replace(oldS, newS) };
+      }
+      if (name === "MultiEdit" || name === "multi_edit" || name === "multiEdit") {
+        const edits = toolInput.edits || toolInput.Edits;
+        if (!Array.isArray(edits) || edits.length === 0) {
+          return { ok: false, reason: "MultiEdit tool_input.edits missing or empty" };
+        }
+        let cur = diskBefore;
+        for (let i = 0; i < edits.length; i++) {
+          const e = edits[i] || {};
+          const oldS = e.old_string != null ? e.old_string : e.oldString;
+          const newS = e.new_string != null ? e.new_string : e.newString;
+          if (typeof oldS !== "string" || typeof newS !== "string") {
+            return { ok: false, reason: `MultiEdit edits[${i}] missing old_string/new_string` };
+          }
+          if (!cur.includes(oldS)) {
+            return { ok: false, reason: `MultiEdit edits[${i}] old_string not found in content` };
+          }
+          cur = cur.replace(oldS, newS);
+        }
+        return { ok: true, after: cur };
+      }
+      return { ok: false, reason: `unsupported tool_name for content derive: ${name}` };
+    }
+    function mapDecisionSeverity(result) {
+      const d = result && typeof result === "object" ? result : {};
+      let ea = null;
+      const dr = d.decision_result;
+      if (dr && typeof dr === "object" && typeof dr.execution_action === "string") {
+        ea = dr.execution_action;
+      } else if (typeof d.execution_action === "string") {
+        ea = d.execution_action;
+      }
+      let severity;
+      if (ea != null && ea !== "") {
+        if (!CLOSED_ACTIONS.has(ea)) {
+          severity = "UNKNOWN";
+        } else if (ea === "CONTINUE" || ea === "CONTINUE_WITH_MONITORING") {
+          severity = "ALLOW";
+        } else if (ea === "STOP") {
+          severity = "BLOCK";
+        } else {
+          severity = "REQUIRE_APPROVAL";
+        }
+      } else {
+        const od = d.omega_decision || d.decision || "ALLOW";
+        if (od === "BLOCK") severity = "BLOCK";
+        else if (od === "REQUIRE_APPROVAL") severity = "REQUIRE_APPROVAL";
+        else if (od === "WARN") severity = "WARN";
+        else severity = "ALLOW";
+      }
+      const decision = dr && dr.decision || d.decision || d.omega_decision || null;
+      const decisionId = dr && dr.decision_id || d.decision_id || null;
+      return {
+        severity,
+        decision: decision != null ? String(decision) : null,
+        decisionId: decisionId != null ? String(decisionId) : null,
+        executionAction: ea
+      };
+    }
+    async function runClaudeHook(options = {}, deps = {}) {
+      const errLog = deps.errLog || ((m) => console.error(String(m)));
+      const readStdin = deps.readStdin || (() => {
+        try {
+          return fs.readFileSync(0, "utf8");
+        } catch {
+          return "";
+        }
+      });
+      const readFile = deps.readFile || ((p) => fs.readFileSync(p, "utf8"));
+      const exists = deps.exists || ((p) => fs.existsSync(p));
+      const authorize = deps.cloudAuthorizePreflight || cloudAuthorizePreflight;
+      const cwd = deps.cwd || process.cwd();
+      const apiKey = resolveApiKey({ ...deps, cwd });
+      if (!apiKey) {
+        errLog("CodeRifts claude-hook: no API key (coderifts login / CODERIFTS_API_KEY / git config coderifts.apiKey) \u2014 allowing");
+        return { exitCode: 0, reason: "missing_api_key" };
+      }
+      const raw = typeof options.stdin === "string" ? options.stdin : readStdin();
+      const parsed = parseStdinJson(raw);
+      if (!parsed.ok) {
+        errLog(`CodeRifts claude-hook: ${parsed.reason} \u2014 allowing (soft; never block on parse gap)`);
+        return { exitCode: 0, reason: "stdin_unparseable" };
+      }
+      const { toolName, toolInput } = parsed;
+      const filePath = toolInput.file_path || toolInput.filePath || toolInput.path;
+      if (!filePath || typeof filePath !== "string") {
+        errLog("CodeRifts claude-hook: tool_input.file_path missing \u2014 allowing (soft)");
+        return { exitCode: 0, reason: "missing_file_path" };
+      }
+      const specPath = resolveSpecPath({ ...deps, cwd });
+      if (!isSpecPath(filePath, specPath)) {
+        return { exitCode: 0, reason: "not_spec_path" };
+      }
+      const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
+      let diskBefore = "";
+      if (exists(absPath)) {
+        try {
+          diskBefore = readFile(absPath, "utf8");
+        } catch (e) {
+          errLog(`CodeRifts claude-hook: cannot read ${absPath} \u2014 allowing (soft)`);
+          return { exitCode: 0, reason: "disk_unreadable" };
+        }
+      }
+      const derived = deriveAfterContent(toolName, toolInput, diskBefore);
+      if (!derived.ok) {
+        errLog(`CodeRifts claude-hook: ${derived.reason} \u2014 allowing (soft; never guess edit apply)`);
+        return { exitCode: 0, reason: "edit_apply_failed" };
+      }
+      if (diskBefore === derived.after) {
+        return { exitCode: 0, reason: "identical" };
+      }
+      let result;
+      try {
+        result = await authorize(diskBefore, derived.after, apiKey, {
+          operation: "merge",
+          environment: "staging"
+        });
+      } catch (e) {
+        const msg = e && e.message ? String(e.message) : "request failed";
+        errLog(`CodeRifts claude-hook: API unreachable (${msg}) \u2014 allowing (soft; availability must not brick the editor)`);
+        return { exitCode: 0, reason: "api_unreachable" };
+      }
+      const mapped = mapDecisionSeverity(result);
+      const idPart = mapped.decisionId ? ` decision_id=${mapped.decisionId}` : "";
+      const decPart = mapped.decision ? ` decision=${mapped.decision}` : "";
+      const eaPart = mapped.executionAction ? ` execution_action=${mapped.executionAction}` : "";
+      if (mapped.severity === "BLOCK" || mapped.severity === "UNKNOWN") {
+        errLog(
+          `CodeRifts claude-hook: BLOCKED${decPart}${eaPart}${idPart}` + (mapped.severity === "UNKNOWN" ? " (unrecognised execution_action)" : "")
+        );
+        return {
+          exitCode: 2,
+          reason: mapped.severity === "UNKNOWN" ? "unknown_action" : "block",
+          severity: mapped.severity,
+          decision: mapped.decision,
+          decisionId: mapped.decisionId
+        };
+      }
+      if (mapped.severity === "REQUIRE_APPROVAL" || mapped.severity === "WARN") {
+        errLog(`CodeRifts claude-hook: WARNING ${mapped.severity}${decPart}${eaPart}${idPart}`);
+        return {
+          exitCode: 0,
+          reason: "warn",
+          severity: mapped.severity,
+          decision: mapped.decision,
+          decisionId: mapped.decisionId
+        };
+      }
+      return {
+        exitCode: 0,
+        reason: "allow",
+        severity: "ALLOW",
+        decision: mapped.decision,
+        decisionId: mapped.decisionId
+      };
+    }
+    module2.exports = {
+      runClaudeHook,
+      parseStdinJson,
+      isSpecPath,
+      deriveAfterContent,
+      mapDecisionSeverity,
+      resolveApiKey,
+      resolveSpecPath,
+      readGitConfig,
+      DEFAULT_SPEC_PATH,
+      CLOSED_ACTIONS,
+      USAGE
+    };
+  }
+});
+
 // corpus/vectors-mcp-fpfn.json
 var require_vectors_mcp_fpfn = __commonJS({
   "corpus/vectors-mcp-fpfn.json"(exports2, module2) {
@@ -99460,7 +99991,7 @@ program.command("login").description("Save your API key for cloud features").act
   const { login } = require_login();
   await login();
 });
-program.command("setup-required-check").description('Guide setup of required status check "CodeRifts / contract-gate" (uses gh, your credentials)').option("--branch <name>", "Branch to protect (default: repo default branch)").option("--repo <owner/repo>", "Override owner/repo (default: git remote origin)").option("--apply", "Apply the protection change (default: print the exact gh command only)").option("--json", "Machine-readable JSON result").action(async (options) => {
+program.command("setup-required-check").description('Guide setup of required status check "CodeRifts / contract-gate" (uses gh, your credentials)').option("--branch <name>", "Branch to protect (default: repo default branch)").option("--repo <owner/repo>", "Override owner/repo (default: git remote origin)").option("--apply", "Apply the protection change (default: print the exact gh command only)").option("--enforce-admins", "Set enforce_admins:true on create (default: false \u2014 admins can bypass; gate reports admin_bypass_open)").option("--json", "Machine-readable JSON result").action(async (options) => {
   const { runSetupRequiredCheck } = require_setup_required_check();
   const result = await runSetupRequiredCheck(options);
   if (result && typeof result.exitCode === "number") {
@@ -99506,6 +100037,34 @@ program.command("lock [repo]").description("Fetch the observed agent-contract lo
     process.exitCode = result.exitCode;
   }
 });
+program.command("outcome <kind>").description(
+  "Report a post-hoc outcome for a decision_id (deploy_succeeded/deploy_failed/\u2026). Records the caller's assertion \u2014 does not verify the deploy itself."
+).option("--decision <decision_id>", "Decision id from decision_result.decision_id (required)").option("--observed-at <iso>", "When the outcome was observed (ISO-8601; default: now)").option("--details <json>", "Optional JSON object/array bound to the outcome row").option("--json", "Print the API response JSON to stdout").addHelpText("after", () => {
+  const { USAGE } = require_outcome();
+  return `
+${USAGE}
+`;
+}).action(async (kind, options) => {
+  const { runOutcome } = require_outcome();
+  const result = await runOutcome(kind, options);
+  if (result && typeof result.exitCode === "number") {
+    process.exitCode = result.exitCode;
+  }
+});
+program.command("claude-hook").description(
+  "Claude Code PreToolUse gate: block contract-touching Write|Edit|MultiEdit on BLOCK/STOP (exit 2). Soft-allow when unconfigured/unparseable/API down."
+).addHelpText("after", () => {
+  const { USAGE } = require_claude_hook();
+  return `
+${USAGE}
+`;
+}).action(async () => {
+  const { runClaudeHook } = require_claude_hook();
+  const result = await runClaudeHook();
+  if (result && typeof result.exitCode === "number") {
+    process.exitCode = result.exitCode;
+  }
+});
 var hookCmd = program.command("hook").description("Manage the CodeRifts pre-push Git hook");
 hookCmd.command("install").description("Install the CodeRifts pre-push hook in the current Git repo").action(() => {
   const { install } = require_hook();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderifts",
-  "version": "3.1.0",
+  "version": "3.2.0",
   "description": "Detect breaking API changes from the command line. Works locally or with the CodeRifts cloud API.",
   "author": "CodeRifts <hello@coderifts.com>",
   "license": "MIT",
@@ -38,7 +38,7 @@
   },
   "scripts": {
     "build": "node scripts/copy-corpus.js && esbuild bin/coderifts.js --bundle --platform=node --target=node18 --outfile=dist/cli.js",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "bash ../../scripts/freeze-gate.sh && npm run build",
     "postinstall": "node scripts/postinstall.js",
     "test": "node --test test/*.test.js"
   },