coderifts 3.0.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');
@@ -169,6 +170,80 @@ program
     runAgentSetup(options, { exit: true });
   });
 
+// ── copilot-setup — emit GitHub Copilot MCP configs (VS Code + cloud agent + custom agent) ──
+// Single-source from CANONICAL_TOOL_NAMES; root keys: servers (VS Code) vs mcpServers (cloud).
+program
+  .command('copilot-setup')
+  .description('Write GitHub Copilot MCP configs (.vscode/mcp.json + cloud-agent paste JSON + docs)')
+  .option('--out <dir>', 'Target directory (default: current working directory)')
+  .option('--check', 'Exit 0 if on-disk files match embedded content; exit 1 on drift')
+  .option('--force', 'Overwrite existing files (default: skip collisions)')
+  .action((options) => {
+    const { runCopilotSetup } = require('../src/commands/copilot-setup');
+    runCopilotSetup(options, { exit: true });
+  });
+
+// ── lock — agent contract lockfile v1 (observed usage; ID847) ──
+// GET /api/v1/lock?repo= → write coderifts.lock. Observed-only; empty agents when none recorded.
+program
+  .command('lock [repo]')
+  .description('Fetch the observed agent-contract lockfile (coderifts.lock v1) for a repo')
+  .option('--repo <owner/repo>', 'Repository (owner/repo); also accepted as a positional argument')
+  .option('--out <path>', 'Output path (default: coderifts.lock in cwd)')
+  .option('--json', 'Print the lock document JSON to stdout (still writes --out)')
+  .action(async (repoPositional, options) => {
+    const { runLock } = require('../src/commands/lock');
+    const result = await runLock({
+      ...options,
+      repo: options.repo || repoPositional || null,
+    });
+    if (result && typeof result.exitCode === 'number') {
+      process.exitCode = result.exitCode;
+    }
+  });
+
+// ── 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.0.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"
       },
@@ -13549,10 +13549,37 @@ var require_cloud = __commonJS({
       const q = encodeURIComponent(String(repo || ""));
       return cloudRequest("GET", `/api/v1/enforcement-status?repo=${q}`, apiKey);
     }
+    function cloudGetLock(repo, apiKey) {
+      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
     };
   }
@@ -69051,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;
@@ -69080,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);
     }
@@ -69093,6 +69151,8 @@ var require_deploy_gate2 = __commonJS({
       observeCDEnforcement,
       clampExit,
       readReceiptFile,
+      extractDecisionIdFromReceipt,
+      formatOutcomeReportHint,
       renderDeployGateTerminal
     };
   }
@@ -95850,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;
@@ -95870,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) {
@@ -96220,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 = {
@@ -96232,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) {
@@ -96246,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);
@@ -96256,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
         });
@@ -96331,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,
@@ -97229,6 +97334,744 @@ ${USAGE}` };
   }
 });
 
+// src/copilot-mcp.embedded.js
+var require_copilot_mcp_embedded = __commonJS({
+  "src/copilot-mcp.embedded.js"(exports2, module2) {
+    "use strict";
+    var COPILOT_MCP_PATHS = Object.freeze([
+      ".vscode/mcp.json",
+      "copilot-cloud-agent-mcp.json",
+      "copilot-custom-agent-mcp.frontmatter.md",
+      "docs/copilot-mcp.md"
+    ]);
+    var COPILOT_MCP_FILES = Object.freeze({
+      ".vscode/mcp.json": '{\n  "$comment": "GENERATED by scripts/generate-copilot-mcp.js from MCP_MANIFEST / CANONICAL_TOOL_NAMES (src/routes/mcp-streamable.js). Do not hand-edit; re-run the generator.",\n  "servers": {\n    "coderifts": {\n      "type": "http",\n      "url": "https://app.coderifts.com/mcp",\n      "headers": {\n        "Authorization": "Bearer ${input:coderifts_api_key}"\n      }\n    }\n  },\n  "inputs": [\n    {\n      "type": "promptString",\n      "id": "coderifts_api_key",\n      "description": "CodeRifts API key (https://coderifts.com) \u2014 Authorization Bearer",\n      "password": true\n    }\n  ]\n}\n',
+      "copilot-cloud-agent-mcp.json": '{\n  "mcpServers": {\n    "coderifts": {\n      "type": "http",\n      "url": "https://app.coderifts.com/mcp",\n      "tools": [\n        "preflight_change_set",\n        "verify_receipt",\n        "get_decision_details"\n      ],\n      "headers": {\n        "Authorization": "Bearer ${COPILOT_MCP_CODERIFTS_API_KEY}"\n      }\n    }\n  }\n}\n',
+      "copilot-custom-agent-mcp.frontmatter.md": "---\n# GENERATED by scripts/generate-copilot-mcp.js from MCP_MANIFEST / CANONICAL_TOOL_NAMES (src/routes/mcp-streamable.js). Do not hand-edit; re-run the generator.\nname: coderifts-governance\ndescription: >\n  CodeRifts API governance \u2014 preflight contract change sets before merge/deploy/publish,\n  verify receipts, look up prior decisions. Branch on execution_action only.\ntools: ['coderifts/preflight_change_set', 'coderifts/verify_receipt', 'coderifts/get_decision_details']\nmcp-servers:\n  coderifts:\n    type: http\n    url: https://app.coderifts.com/mcp\n    tools:\n      - preflight_change_set\n      - verify_receipt\n      - get_decision_details\n    headers:\n      Authorization: Bearer ${{ secrets.COPILOT_MCP_CODERIFTS_API_KEY }}\n---\n\nYou are a CodeRifts-aware agent. Before merge, deploy, publish, or tool registration when\ncontract artifacts changed, call `coderifts/preflight_change_set` with the complete base\u2192head\nchange set. Branch on `execution_action` only (CONTINUE, CONTINUE_WITH_MONITORING,\nREQUEST_APPROVAL, STOP). Do not treat `decision` or `safe_for_agent` as control flow.\nUse `coderifts/verify_receipt` to check an existing receipt; `coderifts/get_decision_details`\nfor a prior decision_id.\n",
+      "docs/copilot-mcp.md": '# CodeRifts + GitHub Copilot MCP\n\n<!-- GENERATED by scripts/generate-copilot-mcp.js from MCP_MANIFEST / CANONICAL_TOOL_NAMES (src/routes/mcp-streamable.js). Do not hand-edit; re-run the generator. -->\n\nWire the **hosted** CodeRifts MCP server (`https://app.coderifts.com/mcp`) into every Copilot surface from **one**\nsource of truth (`CANONICAL_TOOL_NAMES` in `src/routes/mcp-streamable.js`).\n\n## Canonical tools (live tools/list)\n\n- `preflight_change_set`\n- `verify_receipt`\n- `get_decision_details`\n\nDo **not** list hidden/advanced aliases here. Only these 3 tools are the default\nagent-facing surface.\n\n## The servers-vs-mcpServers trap\n\n| Surface | Config location | Root key | Auth |\n|---------|-----------------|----------|------|\n| **VS Code / Copilot Chat** | `.vscode/mcp.json` | **`servers`** | `${input:coderifts_api_key}` + `inputs[]` |\n| **Copilot cloud agent + code review** | Repo **Settings \u2192 Copilot \u2192 MCP servers** (paste JSON) | **`mcpServers`** | Agents secret `COPILOT_MCP_CODERIFTS_API_KEY` in `headers` |\n| **Custom agent** (org/enterprise) | Agent profile `.md` YAML frontmatter | **`mcp-servers`** | `${{ secrets.COPILOT_MCP_CODERIFTS_API_KEY }}` |\n\nCursor / Claude Desktop / Grok use `mcpServers` in their own files \u2014 that is a **different**\necosystem. Do not copy a Cursor config into `.vscode/mcp.json`, and do not paste a VS Code\n`servers` document into GitHub repo Settings.\n\n## 1. VS Code / Copilot Chat (developer surface)\n\n1. Get an API key at https://coderifts.com\n2. Write the generated file to `.vscode/mcp.json` (or run `coderifts copilot-setup`)\n3. Reload VS Code; when prompted, paste the API key for `coderifts_api_key`\n4. In Copilot Chat Agent mode, confirm tools: preflight_change_set, verify_receipt, get_decision_details\n\n```json\n{\n  "$comment": "GENERATED by scripts/generate-copilot-mcp.js from MCP_MANIFEST / CANONICAL_TOOL_NAMES (src/routes/mcp-streamable.js). Do not hand-edit; re-run the generator.",\n  "servers": {\n    "coderifts": {\n      "type": "http",\n      "url": "https://app.coderifts.com/mcp",\n      "headers": {\n        "Authorization": "Bearer ${input:coderifts_api_key}"\n      }\n    }\n  },\n  "inputs": [\n    {\n      "type": "promptString",\n      "id": "coderifts_api_key",\n      "description": "CodeRifts API key (https://coderifts.com) \u2014 Authorization Bearer",\n      "password": true\n    }\n  ]\n}\n```\n\n## 2. Copilot cloud agent (PR / issue governance surface)\n\n1. Repo **Settings \u2192 Copilot \u2192 MCP servers** (or **Cloud agent \u2192 MCP configuration**)\n2. Paste the JSON below (root key **`mcpServers`**, includes required `tools` allowlist)\n3. Add an Agents secret: name `COPILOT_MCP_CODERIFTS_API_KEY`, value = CodeRifts API key\n4. Save. Validate: assign an issue to Copilot \u2192 session logs \u2192 **Start MCP Servers**\n\n```json\n{\n  "mcpServers": {\n    "coderifts": {\n      "type": "http",\n      "url": "https://app.coderifts.com/mcp",\n      "tools": [\n        "preflight_change_set",\n        "verify_receipt",\n        "get_decision_details"\n      ],\n      "headers": {\n        "Authorization": "Bearer ${COPILOT_MCP_CODERIFTS_API_KEY}"\n      }\n    }\n  }\n}\n```\n\nNotes:\n\n- Cloud agent does **not** support OAuth remote MCP; Bearer is correct for CodeRifts.\n- Cloud agent does **not** support interactive `inputs` \u2014 use Agents secrets only.\n- `tools` is required; list the 3 canonical tools (or `["*"]` only if you accept every tool the server exposes).\n\n## 3. Custom agent (optional org/enterprise)\n\nAdd `mcp-servers` to the agent profile frontmatter (see generated\n`copilot-custom-agent-mcp.frontmatter.md`). Tool names may be namespaced as\n`coderifts/<tool>` in the profile `tools` list.\n\n## Regenerate / drift-check\n\n```bash\nnode scripts/generate-copilot-mcp.js\nnode scripts/generate-copilot-mcp.js --check\ncoderifts copilot-setup --out .          # write into a repo\ncoderifts copilot-setup --check          # drift vs embedded\n```\n\nServer URL and tool names always come from the live manifest \u2014 never hand-edit tool lists.\n'
+    });
+    module2.exports = { COPILOT_MCP_FILES, COPILOT_MCP_PATHS };
+  }
+});
+
+// src/commands/copilot-setup.js
+var require_copilot_setup = __commonJS({
+  "src/commands/copilot-setup.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var chalk = require_source();
+    var { COPILOT_MCP_FILES, COPILOT_MCP_PATHS } = require_copilot_mcp_embedded();
+    if (process.env.NO_COLOR) chalk.level = 0;
+    var USAGE = `Usage: coderifts copilot-setup [--out <dir>] [--check] [--force]
+
+  --out <dir>   Target directory (default: current working directory)
+  --check       Exit 0 if on-disk files match embedded content; exit 1 on drift
+  --force       Overwrite existing files (default: skip collisions)
+  Unknown flags exit 1 (never silently ignored).
+
+Writes:
+  .vscode/mcp.json                         VS Code / Copilot Chat (root key: servers)
+  copilot-cloud-agent-mcp.json             Paste into Settings \u2192 Copilot \u2192 MCP (mcpServers)
+  copilot-custom-agent-mcp.frontmatter.md  Custom agent YAML frontmatter
+  docs/copilot-mcp.md                      Install guide
+`;
+    function parseCopilotSetupArgs(argv) {
+      const args = argv.slice(2);
+      let out = null;
+      let check = false;
+      let force = false;
+      let i = 0;
+      while (i < args.length && !String(args[i]).startsWith("-")) i += 1;
+      while (i < args.length) {
+        const a = args[i];
+        if (a === "--out") {
+          const v = args[i + 1];
+          if (v == null || v.startsWith("-")) {
+            return { out, check, force, error: `copilot-setup: --out requires a path
+${USAGE}` };
+          }
+          out = path.resolve(v);
+          i += 2;
+          continue;
+        }
+        if (a === "--check") {
+          check = true;
+          i += 1;
+          continue;
+        }
+        if (a === "--force") {
+          force = true;
+          i += 1;
+          continue;
+        }
+        if (a.startsWith("-")) {
+          return { out, check, force, error: `copilot-setup: unrecognized argument: ${a}
+${USAGE}` };
+        }
+        return { out, check, force, error: `copilot-setup: unrecognized argument: ${a}
+${USAGE}` };
+      }
+      return { out, check, force };
+    }
+    function runCopilotSetup(options = {}, deps = {}) {
+      const log = deps.log || console.log.bind(console);
+      const logErr = deps.logErr || console.error.bind(console);
+      const doExit = deps.exit !== false;
+      const cwd = deps.cwd || process.cwd();
+      const exists = deps.exists || fs.existsSync.bind(fs);
+      const readFile = deps.readFile || ((p) => fs.readFileSync(p, "utf8"));
+      const writeFile = deps.writeFile || ((p, c) => {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        fs.writeFileSync(p, c, "utf8");
+      });
+      let outDir = options.out ? path.resolve(String(options.out)) : cwd;
+      let check = !!options.check;
+      let force = !!options.force;
+      if (deps.argv) {
+        const parsed = parseCopilotSetupArgs(deps.argv);
+        if (parsed.error) {
+          logErr(parsed.error.trimEnd());
+          if (doExit) process.exit(1);
+          return { exitCode: 1, code: "USAGE", message: parsed.error };
+        }
+        if (parsed.out) outDir = parsed.out;
+        check = parsed.check;
+        force = parsed.force;
+      }
+      const files = deps.files || COPILOT_MCP_FILES;
+      const relPaths = deps.paths || COPILOT_MCP_PATHS;
+      if (check) {
+        let stale = false;
+        for (const rel of relPaths) {
+          const fp = path.join(outDir, rel);
+          const expected = files[rel];
+          if (!exists(fp)) {
+            logErr(chalk.red(`copilot-setup --check: missing ${rel}`));
+            stale = true;
+            continue;
+          }
+          const onDisk = readFile(fp);
+          if (onDisk !== expected) {
+            logErr(chalk.red(`copilot-setup --check: drift ${rel}`));
+            stale = true;
+          }
+        }
+        if (stale) {
+          logErr("Run: coderifts copilot-setup --out " + outDir + " --force");
+          if (doExit) process.exit(1);
+          return { exitCode: 1, code: "DRIFT", outDir };
+        }
+        log(chalk.green(`copilot-setup: up to date (${outDir}, ${relPaths.length} files)`));
+        if (doExit) process.exit(0);
+        return { exitCode: 0, code: "UP_TO_DATE", outDir };
+      }
+      const summary = { written: [], skipped: [], forced: [] };
+      for (const rel of relPaths) {
+        const fp = path.join(outDir, rel);
+        const content = files[rel];
+        if (exists(fp) && !force) {
+          summary.skipped.push(rel);
+          continue;
+        }
+        if (exists(fp) && force) summary.forced.push(rel);
+        writeFile(fp, content);
+        summary.written.push(rel);
+      }
+      if (!options.json) {
+        log(chalk.bold("CodeRifts copilot-setup"));
+        log(`  target: ${outDir}`);
+        for (const rel of summary.written) {
+          const tag = summary.forced.includes(rel) ? "overwrote" : "wrote";
+          log(chalk.green(`  ${tag}:   ${rel}`));
+        }
+        for (const rel of summary.skipped) {
+          log(chalk.yellow(`  skipped: ${rel} (exists; use --force to overwrite)`));
+        }
+        log("");
+        log(chalk.dim('  VS Code:  open .vscode/mcp.json \u2014 root key is "servers"'));
+        log(chalk.dim("  Cloud:    paste copilot-cloud-agent-mcp.json into Settings \u2192 Copilot \u2192 MCP"));
+        log(chalk.dim("  Secret:   COPILOT_MCP_CODERIFTS_API_KEY (Agents secret) = CodeRifts API key"));
+        log(chalk.dim(`  ${summary.written.length} written, ${summary.skipped.length} skipped`));
+      }
+      if (doExit) process.exit(0);
+      return { exitCode: 0, code: "OK", outDir, ...summary };
+    }
+    module2.exports = {
+      runCopilotSetup,
+      parseCopilotSetupArgs,
+      COPILOT_MCP_FILES,
+      COPILOT_MCP_PATHS,
+      USAGE
+    };
+  }
+});
+
+// src/commands/lock.js
+var require_lock = __commonJS({
+  "src/commands/lock.js"(exports2, module2) {
+    "use strict";
+    var fs = require("fs");
+    var path = require("path");
+    var chalk = require_source();
+    var { getApiKey } = require_config();
+    var { cloudGetLock } = require_cloud();
+    if (process.env.NO_COLOR) chalk.level = 0;
+    var DEFAULT_OUT = "coderifts.lock";
+    var EPHEMERAL_LOCK_KEYS = Object.freeze([
+      "correlation_id",
+      "generated_at",
+      "request_correlation_id",
+      "meta"
+    ]);
+    var COMMITTED_KEY_ORDER = Object.freeze([
+      "lockfile_version",
+      "repo",
+      "provenance",
+      "agents",
+      "last_accepted_fingerprint",
+      "decision_spec_version",
+      "receipt_kind"
+    ]);
+    var USAGE = [
+      "Usage: coderifts lock --repo owner/repo [--out coderifts.lock]",
+      "   or: coderifts lock owner/repo [--out path]",
+      "",
+      "Fetches the observed agent-contract lockfile (coderifts.lock v1) and writes it to disk.",
+      "Requires a cloud API key (coderifts login or CODERIFTS_API_KEY).",
+      "Observed-only: agents[] come from real usage observations; empty when none recorded.",
+      "Written file is byte-stable for the same state (no correlation_id / generated_at)."
+    ].join("\n");
+    function isValidRepo(full) {
+      const parts = String(full || "").split("/");
+      if (parts.length !== 2) return false;
+      const [owner, repo] = parts.map((p) => p.trim());
+      return !!(owner && repo);
+    }
+    function toCommittedLockfile(doc) {
+      const src = doc && typeof doc === "object" && !Array.isArray(doc) ? doc : {};
+      const out = {};
+      for (const key of COMMITTED_KEY_ORDER) {
+        if (!Object.prototype.hasOwnProperty.call(src, key)) continue;
+        if (EPHEMERAL_LOCK_KEYS.includes(key)) continue;
+        out[key] = src[key];
+      }
+      for (const k of EPHEMERAL_LOCK_KEYS) {
+        if (Object.prototype.hasOwnProperty.call(out, k)) delete out[k];
+      }
+      return out;
+    }
+    function renderLockfileJson(doc) {
+      return `${JSON.stringify(doc, null, 2)}
+`;
+    }
+    async function runLock(options = {}, deps = {}) {
+      const getKey = deps.getApiKey || getApiKey;
+      const fetchLock = deps.cloudGetLock || cloudGetLock;
+      const log = deps.log || console.log;
+      const errLog = deps.errLog || console.error;
+      const writeFile = deps.writeFile || ((p, c) => {
+        fs.mkdirSync(path.dirname(path.resolve(p)), { recursive: true });
+        fs.writeFileSync(p, c, "utf8");
+      });
+      const cwd = deps.cwd || process.cwd();
+      const repo = options.repo != null && String(options.repo).trim() ? String(options.repo).trim() : null;
+      if (!repo) {
+        errLog(chalk.red("Error: missing repo"));
+        errLog(USAGE);
+        return { exitCode: 1, error: "missing_repo" };
+      }
+      if (!isValidRepo(repo)) {
+        errLog(chalk.red("Error: repo must be in owner/repo form (e.g. coderifts/app)"));
+        return { exitCode: 1, error: "invalid_repo" };
+      }
+      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" };
+      }
+      let doc;
+      try {
+        doc = await fetchLock(repo, apiKey);
+      } catch (e) {
+        const msg = e && e.message ? String(e.message) : "request failed";
+        errLog(chalk.red(`Error: ${msg}`));
+        if (e && e.code) errLog(chalk.dim(`  (${e.code})`));
+        return { exitCode: 1, error: msg };
+      }
+      if (!doc || typeof doc !== "object" || doc.lockfile_version == null) {
+        errLog(chalk.red("Error: invalid lockfile response from API"));
+        return { exitCode: 1, error: "invalid_response" };
+      }
+      const committed = toCommittedLockfile(doc);
+      const body = renderLockfileJson(committed);
+      const outRel = options.out != null && String(options.out).trim() ? String(options.out).trim() : DEFAULT_OUT;
+      const outPath = path.isAbsolute(outRel) ? outRel : path.join(cwd, outRel);
+      try {
+        writeFile(outPath, body);
+      } catch (e) {
+        const msg = e && e.message ? String(e.message) : "write failed";
+        errLog(chalk.red(`Error: failed to write ${outPath}: ${msg}`));
+        return { exitCode: 1, error: msg };
+      }
+      if (options.json) {
+        log(body.trimEnd());
+      } else {
+        const nAgents = Array.isArray(committed.agents) ? committed.agents.length : 0;
+        const nOps = Array.isArray(committed.agents) ? committed.agents.reduce((n, a) => n + (a.operations && a.operations.length || 0), 0) : 0;
+        log(chalk.bold("CodeRifts lock (observed)"));
+        log(`  repo:     ${committed.repo || repo}`);
+        log(`  wrote:    ${outPath}`);
+        log(`  agents:   ${nAgents}  operations: ${nOps}`);
+        log(`  fingerprint: ${committed.last_accepted_fingerprint || chalk.dim("(none)")}`);
+        log(chalk.dim("  Observed-only; file is byte-stable (no correlation_id / generated_at)."));
+      }
+      return { exitCode: 0, doc, committed, outPath };
+    }
+    module2.exports = {
+      runLock,
+      renderLockfileJson,
+      toCommittedLockfile,
+      isValidRepo,
+      DEFAULT_OUT,
+      EPHEMERAL_LOCK_KEYS,
+      COMMITTED_KEY_ORDER,
+      USAGE
+    };
+  }
+});
+
+// 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) {
@@ -99148,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") {
@@ -99180,6 +100023,48 @@ program.command("agent-setup").description("Write AGENTS.md / CLAUDE.md / Cursor
   const { runAgentSetup } = require_agent_setup();
   runAgentSetup(options, { exit: true });
 });
+program.command("copilot-setup").description("Write GitHub Copilot MCP configs (.vscode/mcp.json + cloud-agent paste JSON + docs)").option("--out <dir>", "Target directory (default: current working directory)").option("--check", "Exit 0 if on-disk files match embedded content; exit 1 on drift").option("--force", "Overwrite existing files (default: skip collisions)").action((options) => {
+  const { runCopilotSetup } = require_copilot_setup();
+  runCopilotSetup(options, { exit: true });
+});
+program.command("lock [repo]").description("Fetch the observed agent-contract lockfile (coderifts.lock v1) for a repo").option("--repo <owner/repo>", "Repository (owner/repo); also accepted as a positional argument").option("--out <path>", "Output path (default: coderifts.lock in cwd)").option("--json", "Print the lock document JSON to stdout (still writes --out)").action(async (repoPositional, options) => {
+  const { runLock } = require_lock();
+  const result = await runLock({
+    ...options,
+    repo: options.repo || repoPositional || null
+  });
+  if (result && typeof result.exitCode === "number") {
+    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.0.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"
   },