coderifts 4.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 4.1.0
+
+### Added
+
+- **`coderifts claude-hook` JSONL GuardEvent log.** When `CODERIFTS_GUARD_EVENT_LOG` is
+  set to an absolute file path, the hook appends one JSON object per line:
+  `preflight_start` / `preflight_result` / `preflight_unavailable` / `detection_skip`
+  plus terminal `hook_blocked` (exit 2) / `hook_continue` (exit 0) /
+  `hook_advisory_passthrough` (ADVISORY exit 0). Extra fields: `tool`, `path`,
+  `trigger_source:"claude_hook"`, `fingerprint` when the authorize envelope
+  returns one, `sessionId` (`CODERIFTS_SESSION_ID` or per-process). Unset env
+  → no file. Log write errors are swallowed and printed to stderr; **exit
+  codes are unchanged**. The hook does not claim `enforced` (no
+  receipt-verified execution path).
+
 ## 4.0.0
 
 **Breaking** — `coderifts claude-hook` is fail-closed by default. The CLI now
@@ -28,6 +43,15 @@ depends on `@coderifts/agent-guard` ^8.1.1.
   (never widen).
 - **`MIN_GUARD_MAJOR`:** 6 → 8 (`scripts/assert-guard-major.js`).
 
+### Added
+- **`coderifts agent-setup` writes `.claude/settings.json`.** PreToolUse hook
+  (`matcher: Write|Edit|MultiEdit` → `coderifts claude-hook`, timeout 60)
+  beside the six rule files. Fail-closed default (P0-3/P0-4). Explicit
+  opt-out documented on stdout: `CODERIFTS_ADVISORY=1`. `--check` is
+  byte-stable against the embed (same drift-gate as the six rule files).
+  Existing `.claude/settings.json` is skipped (no merge); `--force`
+  replaces the **entire** file.
+
 ### Fixed
 - **Installer copy (P0 #9 / e76e846):** `agent-setup` / `init` teach
   guard@8 execution-state **DEFAULT ON**, not the old OFF.

package/README.md

@@ -301,7 +301,8 @@ coderifts enforce --repo owner/repo --apply
 
 ### Agent host files (`coderifts agent-setup`)
 
-Writes the six CodeRifts agent-host rule files into the current repo (or `--out <dir>`):
+Writes the six CodeRifts agent-host rule files **plus** the Claude Code
+PreToolUse hook settings into the current repo (or `--out <dir>`):
 
 | File | Host |
 |------|------|
@@ -311,6 +312,16 @@ Writes the six CodeRifts agent-host rule files into the current repo (or `--out
 | `.github/copilot-instructions.md` | GitHub Copilot |
 | `coderifts-langgraph-policy.js` | LangGraph |
 | `openai-agent-instructions.md` | OpenAI Agents SDK |
+| `.claude/settings.json` | Claude Code PreToolUse → `coderifts claude-hook` (fail-closed) |
+
+The generated `.claude/settings.json` matches the recipe above (`matcher`
+`Write|Edit|MultiEdit`, `command` `coderifts claude-hook`, `timeout` 60).
+Default is **fail-closed** (missing key / API down → exit 2). Explicit
+opt-out: `CODERIFTS_ADVISORY=1|true`. `CODERIFTS_STRICT=1` cannot be
+weakened by ADVISORY. Existing files are skipped unless `--force`.
+`--force` **replaces the entire** `.claude/settings.json` (no merge into
+permissions / other hooks). If the file already exists, add the PreToolUse
+recipe by hand or accept a full replace.
 
 ```bash
 coderifts agent-setup              # write (skip existing files)

package/dist/cli.js

@@ -3007,7 +3007,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "coderifts",
-      version: "4.0.0",
+      version: "4.1.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",
@@ -100059,7 +100059,8 @@ var require_agent_host_files_embedded = __commonJS({
       ".cursor/rules/coderifts.mdc",
       ".github/copilot-instructions.md",
       "coderifts-langgraph-policy.js",
-      "openai-agent-instructions.md"
+      "openai-agent-instructions.md",
+      ".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',
@@ -100067,7 +100068,8 @@ var require_agent_host_files_embedded = __commonJS({
       ".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'
+      "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',
+      ".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 };
   }
@@ -100207,6 +100209,15 @@ ${USAGE}` };
         for (const line of AGENT_SETUP_WARN_TELEMETRY_LINES) {
           log(line);
         }
+        if (summary.skipped.includes(".claude/settings.json")) {
+          for (const line of AGENT_SETUP_HOOK_SKIP_LINES) {
+            log(line);
+          }
+        } else if (summary.written.includes(".claude/settings.json")) {
+          for (const line of AGENT_SETUP_HOOK_WIRE_LINES) {
+            log(line);
+          }
+        }
       }
       if (doExit) process.exit(0);
       return { exitCode: 0, code: "OK", outDir, ...summary };
@@ -100222,13 +100233,28 @@ ${USAGE}` };
       chalk.dim("    \xB7 missing artifacts/fingerprint \u2192 execution_state_unmeasurable (quiet)"),
       chalk.dim("  Merge gate block is separate: coderifts setup-required-check --apply")
     ]);
+    var AGENT_SETUP_HOOK_WIRE_LINES = Object.freeze([
+      chalk.bold("  Claude Code hook (.claude/settings.json): fail-closed PreToolUse"),
+      chalk.dim("  matcher Write|Edit|MultiEdit \u2192 coderifts claude-hook (exit 2 = BLOCK)."),
+      chalk.dim("  Missing key / API down / unreadable spec \u2192 exit 2 (enforce_indeterminate), not ALLOW."),
+      chalk.dim("  Opt-out: CODERIFTS_ADVISORY=1|true restores soft-allow when governance could not run."),
+      chalk.dim("  CODERIFTS_STRICT=1 cannot be weakened by ADVISORY.")
+    ]);
+    var AGENT_SETUP_HOOK_SKIP_LINES = Object.freeze([
+      chalk.yellow("  .claude/settings.json exists \u2014 left unchanged (installer does not merge)."),
+      chalk.dim("  --force replaces the ENTIRE file (not just the PreToolUse hook)."),
+      chalk.dim("  To wire fail-closed: add PreToolUse \u2192 coderifts claude-hook by hand, or --force."),
+      chalk.dim("  Opt-out if wired: CODERIFTS_ADVISORY=1|true. CODERIFTS_STRICT cannot weaken.")
+    ]);
     module2.exports = {
       runAgentSetup,
       parseAgentSetupArgs,
       AGENT_HOST_FILES,
       AGENT_HOST_PATHS,
       USAGE,
-      AGENT_SETUP_WARN_TELEMETRY_LINES
+      AGENT_SETUP_WARN_TELEMETRY_LINES,
+      AGENT_SETUP_HOOK_WIRE_LINES,
+      AGENT_SETUP_HOOK_SKIP_LINES
     };
   }
 });
@@ -101248,6 +101274,33 @@ var require_claude_hook = __commonJS({
       if (dr && typeof dr === "object" && dr.monitoringSinkWired === true) return true;
       return false;
     }
+    var HOOK_TRIGGER_SOURCE = "claude_hook";
+    function extractFingerprint(result) {
+      const d = result && typeof result === "object" && !Array.isArray(result) ? result : {};
+      const dr = d.decision_result && typeof d.decision_result === "object" ? d.decision_result : {};
+      const fp = dr.fingerprint || d.fingerprint || d.verdict_fingerprint || d.input_fingerprint;
+      return typeof fp === "string" && fp.length > 0 ? fp : void 0;
+    }
+    function hookSessionId(env) {
+      const fromEnv = env && env.CODERIFTS_SESSION_ID && String(env.CODERIFTS_SESSION_ID).trim();
+      if (fromEnv) return fromEnv;
+      if (!hookSessionId._gen) hookSessionId._gen = `hook-${process.pid}-${Date.now()}`;
+      return hookSessionId._gen;
+    }
+    function appendGuardEventLog(env, event, deps = {}) {
+      const p = env && env.CODERIFTS_GUARD_EVENT_LOG;
+      if (p == null || String(p).trim() === "") return;
+      const errLog = deps.errLog || ((m) => console.error(String(m)));
+      const append = deps.appendFileSync || ((file, data) => fs.appendFileSync(file, data));
+      try {
+        append(String(p).trim(), JSON.stringify(event) + "\n");
+      } catch (err) {
+        try {
+          errLog(`CodeRifts claude-hook: CODERIFTS_GUARD_EVENT_LOG write failed (${err && err.message})`);
+        } catch {
+        }
+      }
+    }
     function failClosedOrAdvisory({ advisory, strict, site, softMsg, why, errLog }) {
       if (advisory && !strict) {
         errLog(`${softMsg} (CODERIFTS_ADVISORY)`);
@@ -101443,32 +101496,65 @@ var require_claude_hook = __commonJS({
       const env = deps.env || process.env;
       const strict = isStrictMode(env);
       const advisory = isAdvisoryMode(env);
+      const sessionId = hookSessionId(env);
+      const logEv = (partial) => {
+        appendGuardEventLog(env, {
+          at: (/* @__PURE__ */ new Date()).toISOString(),
+          sessionId,
+          trigger_source: HOOK_TRIGGER_SOURCE,
+          ...partial
+        }, { errLog, appendFileSync: deps.appendFileSync });
+      };
+      let tool = null;
+      let filePathKnown = null;
+      const emitTerminal = (r) => {
+        const extra = {
+          tool: tool || void 0,
+          path: filePathKnown || void 0,
+          decision: r.decision != null ? r.decision : void 0,
+          decisionId: r.decisionId != null ? r.decisionId : void 0
+        };
+        if (r.exitCode === 2) {
+          logEv({ type: "hook_blocked", exit: 2, ...extra, 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 {
+          logEv({ type: "hook_continue", exit: 0, ...extra, cause: r.reason });
+        }
+        return r;
+      };
       const apiKey = resolveApiKey({ ...deps, cwd, env });
       if (!apiKey) {
-        return failClosedOrAdvisory({
+        logEv({ type: "preflight_unavailable", cause: "missing_api_key" });
+        return emitTerminal(failClosedOrAdvisory({
           advisory,
           strict,
           site: "missing_api_key",
           why: "no API key",
           softMsg: "CodeRifts claude-hook: no API key (coderifts login / CODERIFTS_API_KEY / git config coderifts.apiKey) \u2014 allowing",
           errLog
-        });
+        }));
       }
       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" };
+        logEv({ type: "detection_skip", signals: ["stdin_unparseable"] });
+        return emitTerminal({ exitCode: 0, 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)");
-        return { exitCode: 0, reason: "missing_file_path" };
+        logEv({ type: "detection_skip", signals: ["missing_file_path"], tool });
+        return emitTerminal({ exitCode: 0, reason: "missing_file_path" });
       }
+      filePathKnown = filePath;
       const specPath = resolveSpecPath({ ...deps, cwd });
       if (!isSpecPath(filePath, specPath)) {
-        return { exitCode: 0, reason: "not_spec_path" };
+        logEv({ type: "detection_skip", signals: ["not_spec_path"], tool, path: filePath });
+        return emitTerminal({ exitCode: 0, reason: "not_spec_path" });
       }
       const absPath = path.isAbsolute(filePath) ? filePath : path.resolve(cwd, filePath);
       let diskBefore = "";
@@ -101476,30 +101562,34 @@ var require_claude_hook = __commonJS({
         try {
           diskBefore = readFile(absPath, "utf8");
         } catch (e) {
-          return failClosedOrAdvisory({
+          logEv({ type: "preflight_unavailable", cause: "disk_unreadable", tool, path: filePath });
+          return emitTerminal(failClosedOrAdvisory({
             advisory,
             strict,
             site: "disk_unreadable",
             why: `cannot read contract file ${absPath}`,
             softMsg: `CodeRifts claude-hook: cannot read ${absPath} \u2014 allowing (soft)`,
             errLog
-          });
+          }));
         }
       }
       const derived = deriveAfterContent(toolName, toolInput, diskBefore);
       if (!derived.ok) {
-        return failClosedOrAdvisory({
+        logEv({ type: "preflight_unavailable", cause: "edit_apply_failed", tool, path: filePath });
+        return emitTerminal(failClosedOrAdvisory({
           advisory,
           strict,
           site: "edit_apply_failed",
           why: derived.reason,
           softMsg: `CodeRifts claude-hook: ${derived.reason} \u2014 allowing (soft; never guess edit apply)`,
           errLog
-        });
+        }));
       }
       if (diskBefore === derived.after) {
-        return { exitCode: 0, reason: "identical" };
+        logEv({ type: "detection_skip", signals: ["identical"], tool, path: filePath });
+        return emitTerminal({ exitCode: 0, reason: "identical" });
       }
+      logEv({ type: "preflight_start", tool, path: filePath });
       let result;
       try {
         result = await authorize(diskBefore, derived.after, apiKey, {
@@ -101508,54 +101598,65 @@ var require_claude_hook = __commonJS({
         });
       } catch (e) {
         const msg = e && e.message ? String(e.message) : "request failed";
-        return failClosedOrAdvisory({
+        logEv({ type: "preflight_unavailable", cause: "api_unreachable", tool, path: filePath });
+        return emitTerminal(failClosedOrAdvisory({
           advisory,
           strict,
           site: "api_unreachable",
           why: `API unreachable: ${msg}`,
           softMsg: `CodeRifts claude-hook: API unreachable (${msg}) \u2014 allowing (soft; availability must not brick the editor)`,
           errLog
-        });
+        }));
       }
       const mapped = mapDecisionSeverity(result);
+      const fingerprint = extractFingerprint(result);
       const idPart = mapped.decisionId ? ` decision_id=${mapped.decisionId}` : "";
       const decPart = mapped.decision ? ` decision=${mapped.decision}` : "";
       const eaPart = mapped.executionAction ? ` execution_action=${mapped.executionAction}` : "";
+      const actionForLog = mapped.executionAction || (mapped.severity === "BLOCK" || mapped.severity === "UNKNOWN" || mapped.severity === "INDETERMINATE" ? "STOP" : mapped.severity === "REQUIRE_APPROVAL" ? "REQUEST_APPROVAL" : mapped.severity === "MONITOR" || mapped.severity === "WARN" ? "CONTINUE_WITH_MONITORING" : "CONTINUE");
+      logEv({
+        type: "preflight_result",
+        action: actionForLog,
+        decisionId: mapped.decisionId || void 0,
+        fingerprint,
+        tool,
+        path: filePath
+      });
       if (mapped.severity === "INDETERMINATE") {
         errLog(
           "CodeRifts claude-hook: BLOCKED (indeterminate response \u2014 no execution_action and no decision; not permission)"
         );
-        return {
+        return emitTerminal({
           exitCode: 2,
           reason: "indeterminate",
           severity: "INDETERMINATE",
           decision: mapped.decision,
           decisionId: mapped.decisionId
-        };
+        });
       }
       if (mapped.severity === "BLOCK" || mapped.severity === "UNKNOWN") {
         errLog(
           `CodeRifts claude-hook: BLOCKED${decPart}${eaPart}${idPart}` + (mapped.severity === "UNKNOWN" ? " (unrecognised execution_action)" : "")
         );
-        return {
+        return emitTerminal({
           exitCode: 2,
           reason: mapped.severity === "UNKNOWN" ? "unknown_action" : "block",
           severity: mapped.severity,
           decision: mapped.decision,
           decisionId: mapped.decisionId
-        };
+        });
       }
       if (mapped.severity === "REQUIRE_APPROVAL") {
         errLog(
           `CodeRifts claude-hook: BLOCKED approval_required${decPart}${eaPart}${idPart}`
         );
-        return {
+        return emitTerminal({
           exitCode: 2,
           reason: "approval_required",
           severity: mapped.severity,
           decision: mapped.decision,
           decisionId: mapped.decisionId
-        };
+        });
       }
       if (mapped.severity === "MONITOR" || mapped.severity === "WARN") {
         const sinkWired = isMonitoringSinkWired({ env, deps, result });
@@ -101563,29 +101664,29 @@ var require_claude_hook = __commonJS({
           errLog(
             `CodeRifts claude-hook: BLOCKED monitoring_unwired${decPart}${eaPart}${idPart} \u2014 CONTINUE_WITH_MONITORING requires CODERIFTS_MONITORING_SINK_WIRED=1 (host assertion; not delivery proof)`
           );
-          return {
+          return emitTerminal({
             exitCode: 2,
             reason: "monitoring_unwired",
             severity: mapped.severity === "WARN" ? "MONITOR" : mapped.severity,
             decision: mapped.decision,
             decisionId: mapped.decisionId
-          };
+          });
         }
-        return {
+        return emitTerminal({
           exitCode: 0,
           reason: "allow",
           severity: mapped.severity === "WARN" ? "MONITOR" : mapped.severity,
           decision: mapped.decision,
           decisionId: mapped.decisionId
-        };
+        });
       }
-      return {
+      return emitTerminal({
         exitCode: 0,
         reason: "allow",
         severity: "ALLOW",
         decision: mapped.decision,
         decisionId: mapped.decisionId
-      };
+      });
     }
     module2.exports = {
       runClaudeHook,
@@ -101604,7 +101705,10 @@ var require_claude_hook = __commonJS({
       softOrStrictBlock,
       DEFAULT_SPEC_PATH,
       CLOSED_ACTIONS,
-      USAGE
+      USAGE,
+      appendGuardEventLog,
+      extractFingerprint,
+      HOOK_TRIGGER_SOURCE
     };
   }
 });

package/package.json

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