coderifts 4.1.0 → 4.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 4.1.1
+
+### Fixed
+
+- **P0-2: `mapDecisionSeverity` never maps missing `execution_action` to ALLOW.**
+  Missing EA in any body shape → `INDETERMINATE` (exit 2). Legacy decision→severity
+  map is allowed only when `decision_spec_version === "1.0"` on a non-v2 body
+  (no `decision_result`, no `preflight_mode`). Top-level-only `{decision:"ALLOW"}`
+  without that pin is not permission.
+- **P0-3: parse-gap is fail-closed by default.** Unparseable stdin and missing
+  `tool_input.file_path` → **exit 2**, stderr
+  `unparseable input — refusing (fail-closed); set CODERIFTS_ADVISORY=1 to soften`,
+  JSONL `hook_blocked` with `cause: stdin_unparseable|missing_file_path`.
+  `CODERIFTS_ADVISORY=1` restores exit 0. API-key-before-parse order is unchanged
+  (garbage stdin + no key → `missing_api_key`). Non-spec Write stays exit 0.
+  Unknown-tool-on-spec was already exit 2.
+
 ## 4.1.0
 
 ### Added

package/README.md

@@ -54,11 +54,12 @@ A `coderifts-report.json` file is always saved to the current directory.
 
 Interactive configuration generator. Creates a `.coderifts.yml` file with industry-specific presets:
 
-- Default (recommended)
-- Fintech / Payments
-- Healthcare / HIPAA
-- Platform / API-First
-- E-commerce
+- `startup-lean`
+- `growth-balanced`
+- `fintech-strict`
+- `public-api-safe`
+- `microservices-internal`
+- `ai-agent-platform`
 
 ### `coderifts login`
 
@@ -189,6 +190,13 @@ After upgrading the `coderifts` CLI, re-run `coderifts hook install` so the
 installed hook matches the package (already-installed hooks are not
 auto-updated).
 
+2-minute Claude Code path: `coderifts hook install --claude` writes a
+PreToolUse hook (`matcher: Write|Edit|MultiEdit` → `coderifts claude-hook`)
+into `.claude/settings.json` (JSON-merge, backup first, idempotent).
+`--global` writes `~/.claude/settings.json`. `--log <path>` embeds
+`CODERIFTS_GUARD_EVENT_LOG` and `CODERIFTS_SESSION_ID` in the command.
+Unparseable settings JSON → refuse, no write.
+
 ### Claude Code PreToolUse (`coderifts claude-hook`) — ID824
 
 Tool-call-time gate for **Claude Code**: blocks contract-touching `Write` /
@@ -198,13 +206,13 @@ Tool-call-time gate for **Claude Code**: blocks contract-touching `Write` /
 
 | 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) |
+| **2** | **BLOCK** — tool call cancelled; stderr is shown to the model. Default fail-closed: no key, API down, unreadable spec, parse-gap, missing `file_path` |
+| **0** | Allow (`CONTINUE`), or skip (non-spec path / identical content). `CODERIFTS_ADVISORY=1` restores soft-allow on could-not-run sites |
 | **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):
+**Install path:** `coderifts hook install --claude` (or `agent-setup` writes project `.claude/settings.json` when absent). Then set key + spec:
 
 ```bash
 git config coderifts.apiKey 'cr_live_…'          # or: coderifts login / CODERIFTS_API_KEY

package/bin/coderifts.js

@@ -283,9 +283,16 @@ const hookCmd = program
 hookCmd
   .command('install')
   .description('Install the CodeRifts pre-push hook in the current Git repo')
-  .action(() => {
+  .option('--claude', 'Write Claude Code PreToolUse hook to .claude/settings.json (JSON-merge)')
+  .option('--global', 'With --claude: write ~/.claude/settings.json instead of the project file')
+  .option('--log <path>', 'With --claude: embed CODERIFTS_GUARD_EVENT_LOG and CODERIFTS_SESSION_ID in the command')
+  .action((options) => {
     const { install } = require('../src/commands/hook');
-    install();
+    install({
+      claude: !!options.claude,
+      global: !!options.global,
+      log: options.log,
+    });
   });
 
 hookCmd

package/dist/cli.js

@@ -3007,7 +3007,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "coderifts",
-      version: "4.1.0",
+      version: "4.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",
@@ -72976,6 +72976,10 @@ var require_init = __commonJS({
         yaml: `# CodeRifts Policy: Startup Lean
 # For fast-moving teams that want safety without friction.
 # Catches critical breaking changes but stays out of your way.
+#
+# Decision Spec 2.0 (comment only \u2014 this file does not set agent protocol):
+#   branch on execution_action (CONTINUE | CONTINUE_WITH_MONITORING | REQUEST_APPROVAL | STOP).
+#   Unknown execution_action \u2192 STOP. Analyze is not permission; authorize is required to act.
 
 failOnBreaking: true
 
@@ -73350,7 +73354,9 @@ generator_detection: true
       chalk.dim("  For agent tool-call guarding: @coderifts/agent-guard requireExecutionStateMatch"),
       chalk.dim("    defaults ON (absent\u2192true) \u2014 observed drift STOPS. Opt-down: 'warn' (emit, proceed)"),
       chalk.dim("    or false (proceed-on-drift) \u2014 see: coderifts agent-setup"),
-      chalk.dim("  Agent-using repo? Run: coderifts agent-setup")
+      chalk.dim("  Agent-using repo? Run: coderifts agent-setup"),
+      chalk.dim("  Decision Spec 2.0: branch on execution_action (CONTINUE | CONTINUE_WITH_MONITORING |"),
+      chalk.dim("    REQUEST_APPROVAL | STOP). Unknown execution_action \u2192 STOP. Analyze is not permission.")
     ]);
     module2.exports = {
       init,
@@ -99438,6 +99444,7 @@ var require_hook = __commonJS({
     "use strict";
     var fs = require("fs");
     var path = require("path");
+    var os = require("os");
     var { execSync } = require("child_process");
     var HOOK_MARKER = "# CodeRifts pre-push hook";
     var PRE_PUSH_SCRIPT = `#!/bin/sh
@@ -99698,12 +99705,111 @@ exit 0
       const content = fs.readFileSync(hookPath, "utf-8");
       return content.includes(HOOK_MARKER);
     }
-    function install() {
-      const gitDir = findGitDir();
+    var CLAUDE_MATCHER = "Write|Edit|MultiEdit";
+    var CLAUDE_HOOK_BIN = "coderifts claude-hook";
+    function claudeSettingsPath({ global: isGlobal, cwd } = {}) {
+      if (isGlobal) return path.join(os.homedir(), ".claude", "settings.json");
+      return path.join(cwd || process.cwd(), ".claude", "settings.json");
+    }
+    function claudeHookCommand(logPath) {
+      if (!logPath) return CLAUDE_HOOK_BIN;
+      const abs = path.resolve(String(logPath));
+      return `CODERIFTS_GUARD_EVENT_LOG=${abs} CODERIFTS_SESSION_ID=coderifts-claude-hook ${CLAUDE_HOOK_BIN}`;
+    }
+    function isOurPreToolUseEntry(entry, command) {
+      if (!entry || typeof entry !== "object") return false;
+      if (entry.matcher !== CLAUDE_MATCHER) return false;
+      const hooks = Array.isArray(entry.hooks) ? entry.hooks : [];
+      return hooks.some((h) => h && h.type === "command" && String(h.command || "") === command);
+    }
+    function installClaudeHook(opts = {}) {
+      const cwd = opts.cwd || process.cwd();
+      const home = opts.homeDir || os.homedir();
+      const dest = opts.global ? path.join(home, ".claude", "settings.json") : path.join(cwd, ".claude", "settings.json");
+      const command = claudeHookCommand(opts.logPath);
+      const block = {
+        matcher: CLAUDE_MATCHER,
+        hooks: [{ type: "command", command, timeout: 60 }]
+      };
+      let existing = {};
+      let hadFile = false;
+      if (fs.existsSync(dest)) {
+        hadFile = true;
+        let raw;
+        try {
+          raw = fs.readFileSync(dest, "utf8");
+        } catch (err) {
+          const message = `Error: cannot read ${dest} (${err && err.message}) \u2014 refusing to write.`;
+          console.error(message);
+          process.exitCode = 1;
+          return { exitCode: 1, code: "READ_FAILED", path: dest, message };
+        }
+        if (String(raw).trim() !== "") {
+          try {
+            existing = JSON.parse(raw);
+          } catch (err) {
+            const message = `Error: ${dest} is not valid JSON \u2014 refusing (no write). Fix or remove the file, then re-run.`;
+            console.error(message);
+            process.exitCode = 1;
+            return { exitCode: 1, code: "PARSE_FAILED", path: dest, message };
+          }
+          if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
+            const message = `Error: ${dest} JSON root is not an object \u2014 refusing (no write).`;
+            console.error(message);
+            process.exitCode = 1;
+            return { exitCode: 1, code: "PARSE_FAILED", path: dest, message };
+          }
+        }
+      }
+      const hooksRoot = existing.hooks && typeof existing.hooks === "object" && !Array.isArray(existing.hooks) ? { ...existing.hooks } : {};
+      const pre = Array.isArray(hooksRoot.PreToolUse) ? hooksRoot.PreToolUse.slice() : [];
+      if (pre.some((e) => isOurPreToolUseEntry(e, command))) {
+        console.log(`Claude Code hook already installed at ${dest} (no-op).`);
+        return { exitCode: 0, code: "NOOP", path: dest, wrote: false };
+      }
+      const nextPre = pre.concat([block]);
+      const next = {
+        ...existing,
+        hooks: { ...hooksRoot, PreToolUse: nextPre }
+      };
+      const serialized = `${JSON.stringify(next, null, 2)}
+`;
+      let backedUp;
+      if (hadFile) {
+        backedUp = `${dest}.bak`;
+        fs.copyFileSync(dest, backedUp);
+      }
+      fs.mkdirSync(path.dirname(dest), { recursive: true });
+      fs.writeFileSync(dest, serialized, "utf8");
+      console.log(`Claude Code PreToolUse hook written to ${dest}`);
+      if (backedUp) console.log(`Backup: ${backedUp}`);
+      console.log("matcher Write|Edit|MultiEdit \u2192 coderifts claude-hook (exit 2 = BLOCK).");
+      return { exitCode: 0, code: "OK", path: dest, backedUp, wrote: true };
+    }
+    function install(options = {}) {
+      if (options.global && !options.claude) {
+        console.error("Error: --global requires --claude (writes ~/.claude/settings.json).");
+        process.exitCode = 1;
+        return { exitCode: 1, code: "USAGE" };
+      }
+      if (options.claude) {
+        const r = installClaudeHook({
+          global: !!options.global,
+          logPath: options.log,
+          cwd: options.cwd,
+          homeDir: options.homeDir
+        });
+        if (r.exitCode !== 0) return r;
+      }
+      const gitDir = findGitDir(options.cwd);
       if (!gitDir) {
+        if (options.claude) {
+          console.log("Not inside a Git repository \u2014 skipped pre-push hook.");
+          return { exitCode: 0, code: "OK" };
+        }
         console.error("Error: Not inside a Git repository.");
         process.exitCode = 1;
-        return;
+        return { exitCode: 1, code: "NO_GIT" };
       }
       const hooksDir = path.join(gitDir, "hooks");
       if (!fs.existsSync(hooksDir)) {
@@ -99782,7 +99888,19 @@ exit 0
         }
       }
     }
-    module2.exports = { install, uninstall, status, PRE_PUSH_SCRIPT, HOOK_MARKER, findGitDir, isCodeRiftsHook };
+    module2.exports = {
+      install,
+      uninstall,
+      status,
+      PRE_PUSH_SCRIPT,
+      HOOK_MARKER,
+      findGitDir,
+      isCodeRiftsHook,
+      installClaudeHook,
+      claudeSettingsPath,
+      claudeHookCommand,
+      CLAUDE_MATCHER
+    };
   }
 });
 
@@ -100063,12 +100181,12 @@ var require_agent_host_files_embedded = __commonJS({
       ".claude/settings.json"
     ]);
     var AGENT_HOST_FILES = Object.freeze({
-      "AGENTS.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts agent rules\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n',
-      "CLAUDE.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n',
-      ".cursor/rules/coderifts.mdc": '---\ndescription: CodeRifts API governance \u2014 when to preflight and how to branch\nglobs:\nalwaysApply: true\n---\n\n<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n',
-      ".github/copilot-instructions.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts instructions for GitHub Copilot\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n',
-      "coderifts-langgraph-policy.js": '// GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js\n// System policy string for a LangGraph (or similar) agent. Content is generated;\n// identical rule sentences to AGENTS.md / other formats.\n\'use strict\';\n\nmodule.exports = "Call `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\\n\\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\\n\\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\\n\\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\\n\\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not \\"proceed with caution\\" without monitoring.\\n\\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\\n\\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\\n\\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\\n\\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\\n\\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\\n\\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.";\n',
-      "openai-agent-instructions.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts agent instructions\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n',
+      "AGENTS.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts agent rules\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n\nTo act (mutate a contract, merge, deploy, or publish): call `preflight_change_set` with `preflight_mode` authorize. Analyze is informational (`may_execute` is always false) and is not permission. Read `execution_action` on the `decision_result` envelope.\n\nBefore acting under a held receipt: call `verify_receipt` with the intended `context` (operation, environment, repository, branch, pull_request) for THIS attempt. Do not act on a receipt whose scope does not match.\n\nAct only when `currently_authorized` is true (`control_envelope.receipt_view.currently_authorized`). A valid-looking token is not permission if `currently_authorized` is false or omitted.\n\nCommit / CAS evidence is a separate measurement (`commit_observation` on GuardOutcome). It is not a substitute for authorize + `currently_authorized`. Production hosts that want the fail-closed conjunction lock it with `profile: ENFORCING_STRICT` on withCodeRifts.\n',
+      "CLAUDE.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n\nTo act (mutate a contract, merge, deploy, or publish): call `preflight_change_set` with `preflight_mode` authorize. Analyze is informational (`may_execute` is always false) and is not permission. Read `execution_action` on the `decision_result` envelope.\n\nBefore acting under a held receipt: call `verify_receipt` with the intended `context` (operation, environment, repository, branch, pull_request) for THIS attempt. Do not act on a receipt whose scope does not match.\n\nAct only when `currently_authorized` is true (`control_envelope.receipt_view.currently_authorized`). A valid-looking token is not permission if `currently_authorized` is false or omitted.\n\nCommit / CAS evidence is a separate measurement (`commit_observation` on GuardOutcome). It is not a substitute for authorize + `currently_authorized`. Production hosts that want the fail-closed conjunction lock it with `profile: ENFORCING_STRICT` on withCodeRifts.\n',
+      ".cursor/rules/coderifts.mdc": '---\ndescription: CodeRifts API governance \u2014 when to preflight and how to branch\nglobs:\nalwaysApply: true\n---\n\n<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n\nTo act (mutate a contract, merge, deploy, or publish): call `preflight_change_set` with `preflight_mode` authorize. Analyze is informational (`may_execute` is always false) and is not permission. Read `execution_action` on the `decision_result` envelope.\n\nBefore acting under a held receipt: call `verify_receipt` with the intended `context` (operation, environment, repository, branch, pull_request) for THIS attempt. Do not act on a receipt whose scope does not match.\n\nAct only when `currently_authorized` is true (`control_envelope.receipt_view.currently_authorized`). A valid-looking token is not permission if `currently_authorized` is false or omitted.\n\nCommit / CAS evidence is a separate measurement (`commit_observation` on GuardOutcome). It is not a substitute for authorize + `currently_authorized`. Production hosts that want the fail-closed conjunction lock it with `profile: ENFORCING_STRICT` on withCodeRifts.\n',
+      ".github/copilot-instructions.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts instructions for GitHub Copilot\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n\nTo act (mutate a contract, merge, deploy, or publish): call `preflight_change_set` with `preflight_mode` authorize. Analyze is informational (`may_execute` is always false) and is not permission. Read `execution_action` on the `decision_result` envelope.\n\nBefore acting under a held receipt: call `verify_receipt` with the intended `context` (operation, environment, repository, branch, pull_request) for THIS attempt. Do not act on a receipt whose scope does not match.\n\nAct only when `currently_authorized` is true (`control_envelope.receipt_view.currently_authorized`). A valid-looking token is not permission if `currently_authorized` is false or omitted.\n\nCommit / CAS evidence is a separate measurement (`commit_observation` on GuardOutcome). It is not a substitute for authorize + `currently_authorized`. Production hosts that want the fail-closed conjunction lock it with `profile: ENFORCING_STRICT` on withCodeRifts.\n',
+      "coderifts-langgraph-policy.js": '// GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js\n// System policy string for a LangGraph (or similar) agent. Content is generated;\n// identical rule sentences to AGENTS.md / other formats.\n\'use strict\';\n\nmodule.exports = "Call `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\\n\\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\\n\\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\\n\\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\\n\\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not \\"proceed with caution\\" without monitoring.\\n\\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\\n\\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\\n\\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\\n\\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\\n\\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\\n\\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\\n\\nTo act (mutate a contract, merge, deploy, or publish): call `preflight_change_set` with `preflight_mode` authorize. Analyze is informational (`may_execute` is always false) and is not permission. Read `execution_action` on the `decision_result` envelope.\\n\\nBefore acting under a held receipt: call `verify_receipt` with the intended `context` (operation, environment, repository, branch, pull_request) for THIS attempt. Do not act on a receipt whose scope does not match.\\n\\nAct only when `currently_authorized` is true (`control_envelope.receipt_view.currently_authorized`). A valid-looking token is not permission if `currently_authorized` is false or omitted.\\n\\nCommit / CAS evidence is a separate measurement (`commit_observation` on GuardOutcome). It is not a substitute for authorize + `currently_authorized`. Production hosts that want the fail-closed conjunction lock it with `profile: ENFORCING_STRICT` on withCodeRifts.";\n',
+      "openai-agent-instructions.md": '<!-- GENERATED from CodeRifts agent-host-rule (single source). Do not edit rule sentences by hand; run: node scripts/generate-agent-host-files.js -->\n\n# CodeRifts agent instructions\n\nCall `preflight_change_set` before merge, deploy, publish, or tool registration when a contract artifact changed (OpenAPI/Swagger, GraphQL, gRPC/protobuf, AsyncAPI, MCP manifest, or agent tool schemas).\n\nSend the complete base-to-head change set: every changed contract artifact with full before and after content. Do not send a single-file subset when other contract files also change.\n\nBranch on `execution_action` only. Do not branch on `decision` and do not branch on `safe_for_agent` (not_for_control_flow_use_execution_action). Canonical `execution_action` values: CONTINUE, CONTINUE_WITH_MONITORING, REQUEST_APPROVAL, STOP.\n\nAn unrecognised `execution_action` is not permission: fail closed (halt or re-preflight). Well-known code: `not_permission_fail_closed`.\n\n`CONTINUE_WITH_MONITORING` requires a wired monitoring sink (`monitoringSinkWired`). It is not "proceed with caution" without monitoring.\n\nDo not call CodeRifts tools for a documentation-only change (README, guides, comments) with no contract artifact content change.\n\nIf you already hold a chain receipt and only need authenticity/lifecycle: `verify_receipt`. If you need a past decision by id: `get_decision_details`. Neither replaces preflight for a new change set.\n\nA receipt is operation-scoped: a merge receipt never authorizes a deploy or publish. When the operation changes, you MUST call `preflight_change_set` again with the new `context.operation` \u2014 do not decline, re-preflight.\n\nA stale or superseded receipt on a changed head requires a NEW preflight \u2014 `verify_receipt` cannot re-diff.\n\nFor mutating tools, put only the guarded version in the agent\'s tool table; keep the raw handler host-only and unreachable from that table. How you name tools is yours \u2014 this is a reachability property, not a product rename of host tools. CodeRifts cannot see or stop a raw call the host makes outside the table it returns; adopt this as a host convention, not as a guarantee from the package.\n\nCodeRifts reports a governance decision and `execution_action`; it does not by itself block merges. Blocking requires separate repository configuration (required status checks, enforcement) that this rule file does not set.\n\nTo act (mutate a contract, merge, deploy, or publish): call `preflight_change_set` with `preflight_mode` authorize. Analyze is informational (`may_execute` is always false) and is not permission. Read `execution_action` on the `decision_result` envelope.\n\nBefore acting under a held receipt: call `verify_receipt` with the intended `context` (operation, environment, repository, branch, pull_request) for THIS attempt. Do not act on a receipt whose scope does not match.\n\nAct only when `currently_authorized` is true (`control_envelope.receipt_view.currently_authorized`). A valid-looking token is not permission if `currently_authorized` is false or omitted.\n\nCommit / CAS evidence is a separate measurement (`commit_observation` on GuardOutcome). It is not a substitute for authorize + `currently_authorized`. Production hosts that want the fail-closed conjunction lock it with `profile: ENFORCING_STRICT` on withCodeRifts.\n',
       ".claude/settings.json": '{\n  "hooks": {\n    "PreToolUse": [\n      {\n        "matcher": "Write|Edit|MultiEdit",\n        "hooks": [\n          {\n            "type": "command",\n            "command": "coderifts claude-hook",\n            "timeout": 60\n          }\n        ]\n      }\n    ]\n  }\n}\n'
     });
     module2.exports = { AGENT_HOST_FILES, AGENT_HOST_PATHS };
@@ -101231,8 +101349,10 @@ var require_claude_hook = __commonJS({
       "  no API key / API unreachable / disk unreadable / edit-apply failure on the spec path",
       "  Absence of a key is not permission. Explicit opt-out: CODERIFTS_ADVISORY=1|true.",
       "",
-      "Still exit 0 (nothing to govern): unparseable stdin, missing file_path, non-spec path,",
-      "identical content.",
+      "Parse-gap DEFAULT (exit 2): unparseable stdin / missing file_path \u2014 refusing (fail-closed);",
+      "  set CODERIFTS_ADVISORY=1 to soften. JSONL hook_blocked cause stdin_unparseable|missing_file_path.",
+      "",
+      "Still exit 0 (nothing to govern): non-spec path, identical content.",
       "",
       "CONTINUE_WITH_MONITORING: allow only if the host asserts a sink",
       "  (CODERIFTS_MONITORING_SINK_WIRED=1|true or git config coderifts.monitoringSinkWired).",
@@ -101431,13 +101551,22 @@ var require_claude_hook = __commonJS({
       }
       return { ok: false, reason: `unsupported tool_name for content derive: ${name}` };
     }
+    function isV2DecisionBody(d, dr) {
+      if (dr && typeof dr === "object") return true;
+      if (d.preflight_mode != null && d.preflight_mode !== "") return true;
+      const ver = d.decision_spec_version;
+      return typeof ver === "string" && ver.startsWith("2.");
+    }
+    function allowLegacyDecisionMap(d, dr) {
+      return d.decision_spec_version === "1.0" && !isV2DecisionBody(d, dr);
+    }
     function mapDecisionSeverity(result) {
       const d = result && typeof result === "object" && !Array.isArray(result) ? result : {};
       let ea = null;
       const dr = d.decision_result;
-      if (dr && typeof dr === "object" && typeof dr.execution_action === "string") {
+      if (dr && typeof dr === "object" && typeof dr.execution_action === "string" && dr.execution_action !== "") {
         ea = dr.execution_action;
-      } else if (typeof d.execution_action === "string") {
+      } else if (typeof d.execution_action === "string" && d.execution_action !== "") {
         ea = d.execution_action;
       }
       const hasDecision = d.omega_decision != null && d.omega_decision !== "" || d.decision != null && d.decision !== "" || dr && typeof dr === "object" && dr.execution_action;
@@ -101462,7 +101591,7 @@ var require_claude_hook = __commonJS({
         } else {
           severity = "REQUIRE_APPROVAL";
         }
-      } else {
+      } else if (allowLegacyDecisionMap(d, dr)) {
         const od = d.omega_decision || d.decision;
         if (od == null || od === "") {
           severity = "INDETERMINATE";
@@ -101470,6 +101599,8 @@ var require_claude_hook = __commonJS({
         else if (od === "REQUIRE_APPROVAL") severity = "REQUIRE_APPROVAL";
         else if (od === "WARN") severity = "WARN";
         else severity = "ALLOW";
+      } else {
+        severity = "INDETERMINATE";
       }
       const decision = dr && dr.decision || d.decision || d.omega_decision || null;
       const decisionId = dr && dr.decision_id || d.decision_id || null;
@@ -101480,6 +101611,45 @@ var require_claude_hook = __commonJS({
         executionAction: ea
       };
     }
+    function renderDecisionWhy(result, opts = {}) {
+      const maxFixes = Number.isInteger(opts.maxFixes) ? opts.maxFixes : 5;
+      const maxLines = Number.isInteger(opts.maxLines) ? opts.maxLines : 13;
+      const d = result && typeof result === "object" && !Array.isArray(result) ? result : {};
+      const dr = d.decision_result && typeof d.decision_result === "object" ? d.decision_result : {};
+      const pick = (k) => dr[k] !== void 0 ? dr[k] : d[k];
+      const arr = (v) => Array.isArray(v) ? v : [];
+      const str = (v) => typeof v === "string" ? v.trim() : "";
+      const lines = [];
+      const reasonCodes = [];
+      for (const r of arr(pick("blocking_reasons"))) {
+        if (!r || typeof r !== "object") continue;
+        const code = str(r.code);
+        const message = str(r.message);
+        if (code) reasonCodes.push(code);
+        if (!code && !message) continue;
+        lines.push(`- ${code || "REASON"}${message ? `: ${message}` : ""}`);
+      }
+      for (const r of arr(pick("degraded_reasons"))) {
+        if (!r || typeof r !== "object") continue;
+        const code = str(r.code);
+        const message = str(r.message);
+        if (!code && !message) continue;
+        lines.push(`- degraded: ${[code, message].filter(Boolean).join(": ")}`);
+      }
+      const action = str(pick("required_action"));
+      if (action) lines.push(`- action: ${action}`);
+      const rt = pick("remediation_transaction");
+      const changes = arr(rt && typeof rt === "object" ? rt.required_changes : null).filter((c) => c && typeof c === "object");
+      const shown = changes.slice(0, maxFixes);
+      for (const c of shown) {
+        const target = str(c.target);
+        const instruction = str(c.instruction);
+        if (!instruction && !target) continue;
+        lines.push(`- fix${target ? ` (${target})` : ""}: ${instruction || str(c.precise_label)}`);
+      }
+      if (changes.length > shown.length) lines.push(`- fix: +${changes.length - shown.length} more`);
+      return { lines: lines.slice(0, maxLines), reasonCodes };
+    }
     async function runClaudeHook(options = {}, deps = {}) {
       const errLog = deps.errLog || ((m) => console.error(String(m)));
       const readStdin = deps.readStdin || (() => {
@@ -101515,7 +101685,14 @@ var require_claude_hook = __commonJS({
           decisionId: r.decisionId != null ? r.decisionId : void 0
         };
         if (r.exitCode === 2) {
-          logEv({ type: "hook_blocked", exit: 2, ...extra, cause: r.reason || r.site });
+          const reasons = Array.isArray(r.reasons) && r.reasons.length ? r.reasons : void 0;
+          logEv({
+            type: "hook_blocked",
+            exit: 2,
+            ...extra,
+            reasons,
+            cause: r.reason || r.site
+          });
         } else if (r.exitCode === 0 && r.site && advisory && !strict) {
           logEv({ type: "hook_advisory_passthrough", exit: 0, decision: r.decision || null, ...extra, cause: r.site });
         } else {
@@ -101535,20 +101712,27 @@ var require_claude_hook = __commonJS({
           errLog
         }));
       }
+      const PARSE_GAP_STDERR = "unparseable input \u2014 refusing (fail-closed); set CODERIFTS_ADVISORY=1 to soften";
       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)`);
-        logEv({ type: "detection_skip", signals: ["stdin_unparseable"] });
-        return emitTerminal({ exitCode: 0, reason: "stdin_unparseable" });
+        if (advisory && !strict) {
+          errLog(`CodeRifts claude-hook: ${parsed.reason} \u2014 allowing (CODERIFTS_ADVISORY)`);
+          return emitTerminal({ exitCode: 0, reason: "stdin_unparseable", site: "stdin_unparseable" });
+        }
+        errLog(`CodeRifts claude-hook: ${PARSE_GAP_STDERR}`);
+        return emitTerminal({ exitCode: 2, reason: "stdin_unparseable" });
       }
       const { toolName, toolInput } = parsed;
       tool = toolName;
       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)");
-        logEv({ type: "detection_skip", signals: ["missing_file_path"], tool });
-        return emitTerminal({ exitCode: 0, reason: "missing_file_path" });
+        if (advisory && !strict) {
+          errLog("CodeRifts claude-hook: tool_input.file_path missing \u2014 allowing (CODERIFTS_ADVISORY)");
+          return emitTerminal({ exitCode: 0, reason: "missing_file_path", site: "missing_file_path" });
+        }
+        errLog(`CodeRifts claude-hook: ${PARSE_GAP_STDERR}`);
+        return emitTerminal({ exitCode: 2, reason: "missing_file_path" });
       }
       filePathKnown = filePath;
       const specPath = resolveSpecPath({ ...deps, cwd });
@@ -101635,27 +101819,37 @@ var require_claude_hook = __commonJS({
         });
       }
       if (mapped.severity === "BLOCK" || mapped.severity === "UNKNOWN") {
+        const why = renderDecisionWhy(result);
         errLog(
-          `CodeRifts claude-hook: BLOCKED${decPart}${eaPart}${idPart}` + (mapped.severity === "UNKNOWN" ? " (unrecognised execution_action)" : "")
+          [
+            `CodeRifts claude-hook: BLOCKED${decPart}${eaPart}${idPart}` + (mapped.severity === "UNKNOWN" ? " (unrecognised execution_action)" : ""),
+            ...why.lines
+          ].join("\n")
         );
         return emitTerminal({
           exitCode: 2,
           reason: mapped.severity === "UNKNOWN" ? "unknown_action" : "block",
           severity: mapped.severity,
           decision: mapped.decision,
-          decisionId: mapped.decisionId
+          decisionId: mapped.decisionId,
+          reasons: why.reasonCodes
         });
       }
       if (mapped.severity === "REQUIRE_APPROVAL") {
+        const why = renderDecisionWhy(result);
         errLog(
-          `CodeRifts claude-hook: BLOCKED approval_required${decPart}${eaPart}${idPart}`
+          [
+            `CodeRifts claude-hook: BLOCKED approval_required${decPart}${eaPart}${idPart}`,
+            ...why.lines
+          ].join("\n")
         );
         return emitTerminal({
           exitCode: 2,
           reason: "approval_required",
           severity: mapped.severity,
           decision: mapped.decision,
-          decisionId: mapped.decisionId
+          decisionId: mapped.decisionId,
+          reasons: why.reasonCodes
         });
       }
       if (mapped.severity === "MONITOR" || mapped.severity === "WARN") {
@@ -101694,6 +101888,7 @@ var require_claude_hook = __commonJS({
       isSpecPath,
       deriveAfterContent,
       mapDecisionSeverity,
+      renderDecisionWhy,
       resolveApiKey,
       resolveSpecPath,
       readGitConfig,
@@ -103722,9 +103917,13 @@ ${USAGE}
   }
 });
 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(() => {
+hookCmd.command("install").description("Install the CodeRifts pre-push hook in the current Git repo").option("--claude", "Write Claude Code PreToolUse hook to .claude/settings.json (JSON-merge)").option("--global", "With --claude: write ~/.claude/settings.json instead of the project file").option("--log <path>", "With --claude: embed CODERIFTS_GUARD_EVENT_LOG and CODERIFTS_SESSION_ID in the command").action((options) => {
   const { install } = require_hook();
-  install();
+  install({
+    claude: !!options.claude,
+    global: !!options.global,
+    log: options.log
+  });
 });
 hookCmd.command("uninstall").description("Remove the CodeRifts pre-push hook from the current Git repo").action(() => {
   const { uninstall } = require_hook();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "coderifts",
-  "version": "4.1.0",
+  "version": "4.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",