@coderifts/agent-hooks 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 0.2.2 — 2026-10-03
+
+### Changed
+
+- **Every refusal names two more limits.** `DOES_NOT_PROVE` (gate.js), carried on every refusal and approval request, and inherited by the shell refusal, now also says:
+  - that a refusal by a hook installed outside managed settings is not final: since Claude Code 2.1.287 a user-installed mod runs before it, can answer the call so the hook never runs, and can approve a call the hook blocked;
+  - that a timed-out hook does not block the call: the fail-closed path covers an error inside the hook, not Claude Code's hook timeout. This holds for this hook only when `CODERIFTS_TIMEOUT_MS` is at least the hook timeout; the default 5000 ms aborts inside the 8 s timeout the snippet sets.
+
+## Unreleased — 2026-09-27
+
+### Fixed
+
+- **Edit sent a fragment as the whole file.** `new_string` went to CodeRifts as the after body, so a
+  one-line Edit read as "everything else was removed". The after body is now the file on disk with
+  the edit applied (`replace_all` honoured); MultiEdit applies `edits` in order (it used to read a
+  `content` key that MultiEdit does not have). An edit that does not apply → exit 2, nothing sent.
+  The 0.2.0 test that pinned the fragment is rewritten; its `old_string` was not in the fixture.
+
+### Changed
+
+- **The Bash hole is narrowed, not closed.** Matcher `Write|Edit|MultiEdit|Bash`. A Bash command that
+  names a recognised contract file with a write shape is **denied** with a pointer to Write/Edit;
+  reads pass; nothing is sent to CodeRifts. Deny, not ask (#39344: a hook ask was reported to
+  override a settings deny). A write that does not name the file is still not seen — the refusal
+  text says so. Same bypass class as anthropics/claude-code #31292.
+
 ## 0.2.0 — 2026-09-13
 
 **(a) New host.** Claude Code PreToolUse adapter. Same `gate.js`; new stdin envelope.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeRifts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -46,6 +46,8 @@ Does not prove:
   - that the bytes finally written are the bytes checked — nothing here locks the file between this answer and the write
   - that the other tool calls in this run were checked — each call is judged alone
   - that a contract artifact this gate does not recognise was seen at all
+  - that the call was refused when this hook is installed outside managed settings — since Claude Code 2.1.287 a user-installed mod runs before it, can answer the call so the hook never runs, and can approve a call the hook blocked; only a hook in managed settings is final
+  - that a call was refused when the hook ran out of time — the fail-closed path covers an error inside the hook, not Claude Code's hook timeout: a timed-out PreToolUse command hook does not block the call (true for this hook only when CODERIFTS_TIMEOUT_MS is at least the hook timeout)
 ```
 
 ## Fail-closed
@@ -64,15 +66,30 @@ The hook entry sets `"timeout": 8` (**seconds** — Claude Code's unit, not mill
 gate's 5000 ms abort can finish first. If `node` itself hangs past 8 s, Claude Code still
 lets the write through. That host behaviour cannot be fixed in this package.
 
-## What this gate does not see (Claude Code)
+## Shell writes (Claude Code)
 
-The Claude Code matcher is `Write|Edit|MultiEdit`. A contract file written by a **shell
-command** (`cat > openapi.yaml`, `tee`, `python -c "open(...)"`, …) does not go through
-those tools, so this hook never runs. Parsing Bash to guess destination paths is not a
-gate — it would miss more than it caught. Treat a shell-written schema as unchecked.
+The Claude Code matcher is `Write|Edit|MultiEdit|Bash`. A shell command cannot be gated — the
+hook never sees the bytes it would leave — so the hook does something narrower: a Bash command
+that **names a recognised contract file and has a write shape** (a redirect, `tee`, `sed -i`,
+`perl -i`, `cp`/`mv`/`rm`, `git checkout|restore|apply`, `open(…, "w")`, `curl -o`, …) is
+**denied** with a pointer to the Write or Edit tool, where the gate does see the change.
+Reads (`cat`, `git diff`, `grep`, `oasdiff`) pass. Nothing is sent to CodeRifts for a Bash call.
+
+It is **deny, not ask**: a hook `ask` was reported to override a settings deny rule
+(anthropics/claude-code #39344), and an escalation that can downgrade someone else's deny is
+not one.
+
+It is not a parser. A write that does not name the file (`python script.py`, a variable, a
+glob) is not recognised, and every shell refusal says so:
 
 Does not prove:
-  - that a contract artifact written via Bash or PowerShell was seen at all
+  - that a contract file written by a shell command this hook did not recognise was seen at all
+
+## Edit and MultiEdit
+
+`new_string` is a fragment, not the file. The gate reads the file on disk and sends it with the
+edit applied (MultiEdit: every edit, in order). An edit whose `old_string` is not in the file is
+not guessed: exit 2.
 
 ## Configuration
 

package/claude-code/hook.mjs

@@ -8,19 +8,83 @@
  *   block               → JSON deny (reason includes Does not prove)
  *   transport/parse/throw → exit 2 + stderr  (the host is fail-open otherwise)
  *
- * `gate.js` is untouched. This file only remaps envelopes.
+ * Two Claude-specific inputs are resolved here, before the gate (2026-09-27):
+ *   - Edit/MultiEdit carry an edit, not a body; `applyEdits` builds the after file from the one on disk.
+ *   - Bash is not gated (the after bytes are unknown), but a command that names a recognised contract
+ *     file with a write shape is denied with a pointer to Write/Edit, where the gate does see it.
  */
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { createGate } from "../gate.js";
+import { classifyPath, createGate, DOES_NOT_PROVE } from "../gate.js";
+
+/** One Claude Code edit applied to `text`; null when old_string is not there to replace. */
+function applyOne(text, { old_string: from, new_string: to, replace_all: all } = {}) {
+  if (typeof from !== "string" || typeof to !== "string") return null;
+  if (from === "") return text === "" ? to : null; // Claude Code's "create via Edit" shape
+  if (!text.includes(from)) return null;
+  return all ? text.split(from).join(to) : text.replace(from, () => to);
+}
+
+/** The file after an Edit (`params` is the edit) or a MultiEdit (`params.edits`, in order). */
+export function applyEdits(params, before) {
+  const edits = Array.isArray(params.edits) ? params.edits : [params];
+  let text = before;
+  for (const e of edits) {
+    text = applyOne(text, e);
+    if (text === null) return null;
+  }
+  return text;
+}
 
 /** Claude Code Write/Edit/MultiEdit → the path/content keys `resolveTarget` reads. */
 export const CLAUDE_TOOL_SHAPES = Object.freeze({
   Write: { path: "file_path", content: "content" },
-  Edit: { path: "file_path", content: "new_string" },
-  MultiEdit: { path: "file_path", content: "content" },
+  Edit: { path: "file_path", apply: applyEdits },
+  MultiEdit: { path: "file_path", apply: applyEdits },
 });
 
+/*
+ * A write shape in a shell command. Not a parser and not a gate: it only decides whether a command
+ * that already NAMES a recognised contract file may be changing it. A miss is named in the refusal
+ * text (and the README); a false hit costs one redirect to the Write/Edit tool.
+ */
+const SHELL_WRITE = [
+  />/, // any redirect, incl. >> and heredoc targets
+  /\btee\b/,
+  /\b(sed|perl|ruby)\b[^|;&]*\s-[a-zA-Z]*i/,
+  /\b(cp|mv|rm|truncate|install|ln|rsync|dd|patch|unzip|tar)\b/,
+  /\bgit\s+(checkout|restore|apply|am|reset|stash|mv|rm)\b/,
+  /\bopen\s*\([^)]*,\s*['"][wax+]/,
+  /\b(writeFile(Sync)?|write_text|write_bytes)\b/,
+  /\b(curl|wget)\b[^|;&]*\s-(o|O)\b/,
+];
+
+/** Tokens a shell would split on, then the ones this gate recognises as a contract path. */
+function contractPathsIn(command) {
+  const tokens = command.split(/[\s;|&<>()'"`=,]+/).filter(Boolean);
+  return [...new Set(tokens.filter((t) => classifyPath(t)))];
+}
+
+const SHELL_DOES_NOT_PROVE = [
+  "that a contract file written by a shell command this hook did not recognise was seen at all",
+  ...DOES_NOT_PROVE.slice(1),
+];
+
+export function shellContractWrite(command) {
+  if (typeof command !== "string") return null;
+  // A redirect into a file descriptor (2>&1, >&2) is not a write to a path.
+  const probe = command.replace(/\d?>&\d/g, " ");
+  const paths = contractPathsIn(probe);
+  if (!paths.length || !SHELL_WRITE.some((re) => re.test(probe))) return null;
+  return [
+    `CodeRifts cannot see a contract change made by a shell command (${paths.join(", ")}).`,
+    `Use the Write or Edit tool for contract files, so the change is checked before it lands.`,
+    `Proves: only that this command names a recognised contract file with a write shape.`,
+    `Does not prove:`,
+    ...SHELL_DOES_NOT_PROVE.map((l) => `  - ${l}`),
+  ].join("\n");
+}
+
 const ASK_TITLES = new Set([
   "CodeRifts asks for approval",
   "CodeRifts returned analysis, not authorization",
@@ -86,6 +150,11 @@ export async function runClaudeHook(stdinText, { env = process.env, deps } = {})
     return failClosed("CodeRifts Claude hook: stdin JSON was not an object.");
   }
 
+  if (payload.tool_name === "Bash") {
+    const refusal = shellContractWrite(payload.tool_input?.command);
+    return refusal ? jsonDecision("deny", refusal) : emptyPass();
+  }
+
   const event = {
     toolName: payload.tool_name,
     params: payload.tool_input ?? {},

package/claude-code/settings.snippet.json

@@ -2,7 +2,7 @@
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|MultiEdit",
+        "matcher": "Write|Edit|MultiEdit|Bash",
         "hooks": [
           {
             "type": "command",

package/gate.js

@@ -47,6 +47,8 @@ export const DOES_NOT_PROVE = Object.freeze([
   "that the bytes finally written are the bytes checked — nothing here locks the file between this answer and the write",
   "that the other tool calls in this run were checked — each call is judged alone",
   "that a contract artifact this gate does not recognise was seen at all",
+  "that the call was refused when this hook is installed outside managed settings — since Claude Code 2.1.287 a user-installed mod runs before it, can answer the call so the hook never runs, and can approve a call the hook blocked; only a hook in managed settings is final",
+  "that a call was refused when the hook ran out of time — the fail-closed path covers an error inside the hook, not Claude Code's hook timeout: a timed-out PreToolUse command hook does not block the call (true for this hook only when CODERIFTS_TIMEOUT_MS is at least the hook timeout)",
 ]);
 
 /**
@@ -216,7 +218,7 @@ export function resolveTarget(event, shapes) {
   const candidates = [fromParams, ...(event.derivedPaths ?? [])].filter((p) => typeof p === "string" && p);
   for (const p of candidates) {
     const type = classifyPath(p);
-    if (type) return { path: p, type, content: shape ? event.params?.[shape.content] : undefined };
+    if (type) return { path: p, type, content: shape ? event.params?.[shape.content] : undefined, apply: shape?.apply };
   }
   return null;
 }
@@ -236,7 +238,7 @@ export function createGate(config = {}, deps = {}) {
     // Not a contract artifact this gate recognises. Staying out of the way is not a fail-open: the
     // gate never claimed this call, and DOES_NOT_PROVE says as much on every refusal it does make.
     if (!target) return undefined;
-    if (typeof target.content !== "string") {
+    if (!target.apply && typeof target.content !== "string") {
       return ask(
         "CodeRifts gate could not read the proposed change",
         `${target.path} is a contract artifact, but this gate could not find the new content in the ` +
@@ -251,12 +253,24 @@ export function createGate(config = {}, deps = {}) {
       before = ""; // A new file. An empty "before" is a real change set, not a missing one.
     }
 
+    // A tool whose params carry an edit, not a body (Claude Code Edit/MultiEdit): the after body is
+    // the file with the edit applied. An edit that does not apply is put to a human — sending a
+    // fragment as the whole file would read as "everything else was removed".
+    const after = target.apply ? target.apply(event.params ?? {}, before) : target.content;
+    if (typeof after !== "string") {
+      return ask(
+        "CodeRifts gate could not read the proposed change",
+        `${target.path} is a contract artifact, but the edit in "${event.toolName}" does not apply to ` +
+          `the file as it is on disk. It will not pass a change it has not seen.`,
+      );
+    }
+
     const outcome = await call({
       endpoint,
       apiKey,
       timeoutMs,
       operation,
-      artifact: { id: target.path, type: target.type, before, after: target.content },
+      artifact: { id: target.path, type: target.type, before, after },
     });
     return decide(outcome, { operation, path: target.path });
   };

package/hooks/hooks.json

@@ -1,9 +1,9 @@
 {
-  "description": "Ask CodeRifts before Write/Edit of a contract artifact. Host timeout is 8s (seconds). Gate budget is 5000ms. If this process hangs past the host timeout, Claude Code fail-opens — named in the README.",
+  "description": "Ask CodeRifts before Write/Edit of a contract artifact; deny a Bash command that names one with a write shape. Host timeout is 8s (seconds). Gate budget is 5000ms. If this process hangs past the host timeout, Claude Code fail-opens — named in the README.",
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|MultiEdit",
+        "matcher": "Write|Edit|MultiEdit|Bash",
         "hooks": [
           {
             "type": "command",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderifts/agent-hooks",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Ask CodeRifts before an agent writes a contract artifact (OpenClaw before_tool_call and Claude Code PreToolUse).",
   "license": "MIT",
   "homepage": "https://github.com/coderifts/agent-hooks#readme",
@@ -34,7 +34,9 @@
     }
   },
   "openclaw": {
-    "extensions": ["./index.js"],
+    "extensions": [
+      "./index.js"
+    ],
     "compat": {
       "pluginApi": ">=2026.6.35"
     },