@coderifts/agent-hooks 0.2.1 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hooks",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Ask CodeRifts before Claude Code writes a contract artifact (OpenAPI, AsyncAPI, GraphQL, protobuf, MCP manifest).",
   "author": {
     "name": "CodeRifts",

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 0.3.0 — 2026-10-03
+
+### Changed
+
+- **One decision function with `coderifts claude-hook` and the CodeRifts mod.** `contract-write.mjs` (a byte copy of `@coderifts/contract-path`'s, with `contract-write.sha256` beside it) decides which path is a contract file and of what type, the text an Edit or MultiEdit leaves, and what a Bash command writes. `gate.js` and `claude-code/hook.mjs` keep no list of their own.
+- **Artifact types are the change-set surface's own:** a `.proto` is sent as `grpc` and an MCP manifest or tool list as `mcp_manifest` (they were `protobuf` and `mcp`, which the surface does not analyze). `classifyPath` returns the new types; `ARTIFACT_TYPES` is gone.
+- **Bash, by write target.** A shell write to a named contract file is still denied. A read of one now passes (`cat openapi.yaml > /tmp/x` was denied before). A write that can reach a contract file without naming it (`find … -exec sed -i`, `xargs`, a glob, `rm -rf <dir>`, `git stash pop`, `git reset --hard`, a pipe into `sh`) now **asks** when a contract file is under its reach.
+- **Edit:** `replace_all` and the empty-`old_string` create form follow Claude Code; an edit that does not apply says which `old_string` was not found.
+- **Two more limits** on every refusal: that the hook was running (`disableAllHooks` in any settings file, `--safe-mode`, `--bare`), and that a contract generated from source code was checked.
+
+## 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

package/README.md

@@ -46,6 +46,10 @@ 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, and a plugin hook runs after the mods even when managed settings force-enable the plugin
+  - 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)
+  - that the hook was running — disableAllHooks in any settings file (the project's .claude/settings.json included, which a shell command can rewrite unless the sandbox protects it), --safe-mode or --bare turns it off
+  - that a contract generated from source code was checked — a contract generated from source code (annotations, decorators, a build step) changes when the source changes; the hooks see the source edit, not the contract; the required check sees the generated contract
 ```
 
 ## Fail-closed
@@ -67,22 +71,43 @@ lets the write through. That host behaviour cannot be fixed in this package.
 ## Shell writes (Claude Code)
 
 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:
+hook never sees the bytes it would leave — so the hook reads what the command **writes**, with the
+decision function `coderifts claude-hook` and the CodeRifts mod use too (`contract-write.mjs`, a
+copy of `@coderifts/contract-path`'s):
+
+- **A write to a named contract file is denied** (a redirect into it, `tee`, `sed -i`/`perl -i`,
+  the destination of `cp`/`install`/`ln`/`rsync`, `mv`/`rm`, `git checkout|restore -- <file>`,
+  `--out <file>`, `open(<file>, "w")` in inline Python or Node, `curl -o`), with a pointer to the
+  Write or Edit tool, where the gate does see the change. Nothing is sent to CodeRifts for a Bash call.
+- **A write that can reach a contract file without naming it asks**: `find <dir> -exec sed -i …`
+  or `-delete`, `xargs` into a writer, a glob, `rm -rf <dir>`, `git stash pop`, `git reset --hard`,
+  `git checkout -- .`, inline code that walks a directory, a pipe into `sh`, a target the command
+  builds from a variable it does not set. It asks only when a contract file is under that
+  directory; `find . -name '*.pyc' -delete` and `rm -rf build` pass.
+- **A read passes**, even of a contract file: `cat openapi.yaml > /tmp/copy`, `cp openapi.yaml /tmp/`,
+  `git diff`, `grep`, `oasdiff`.
+
+Measured on 2026-10-03 on two corpora: the 22 benign forms of the Skillkeel tamper corpus pass; 12 of
+its 83 tamper cases ask, each a write that reaches the working tree without naming a file (`rm -rf .`,
+`git reset --hard`, `git clean -fdx`, `git checkout -- .`, `xargs rm`, a pipe into `sh`); of our 16
+contract-file-write cases, the 11 that change a contract are stopped and the 5 benign ones go through.
+
+An ask does not weaken a deny: on Claude Code 2.1.288 a settings `deny` rule held over this hook's
+`ask` and over an `allow` (measured in `bypassPermissions` mode). The earlier report that a hook ask
+overrode a deny rule (anthropics/claude-code #39344) did not reproduce.
+
+It reads the command text; it does not parse shell or run it. A command shape it does not recognise
+passes — a script that writes a contract file itself (`node scripts/generate.js`), a variable it
+cannot resolve to a name — and every shell refusal says so:
 
 Does not prove:
   - that a contract file written by a shell command this hook did not recognise was seen at all
 
+The sandbox closes what the text cannot: with `sandbox.filesystem.denyWrite` listing the contract
+paths, every sandboxed command and its child processes are refused the write (measured on macOS:
+`python -c`, `find -exec sed -i`, `xargs cp`, also in `bypassPermissions` mode; on Linux a wildcard
+entry is skipped, so list concrete paths). The Write and Edit tools stay with this hook.
+
 ## Edit and MultiEdit
 
 `new_string` is a fragment, not the file. The gate reads the file on disk and sends it with the

package/claude-code/hook.mjs

@@ -8,32 +8,22 @@
  *   block               → JSON deny (reason includes Does not prove)
  *   transport/parse/throw → exit 2 + stderr  (the host is fail-open otherwise)
  *
- * 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.
+ * Which call touches a contract file is decided by contract-write.mjs, the one decision function
+ * `coderifts claude-hook` and the CodeRifts mod run too (0.3.0, 2026-10-03):
+ *   - Edit/MultiEdit carry an edit, not a body; the after file is the one on disk with it applied.
+ *   - Bash is not gated (the after bytes are unknown). A command that writes a named contract file
+ *     is denied with a pointer to Write/Edit, where the gate does see it; one that can write a
+ *     directory holding a contract without naming it (find -exec, xargs, a glob, a tree-wide git
+ *     restore, an interpreter, a pipe into sh) asks.
  */
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-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);
-}
+import { afterText, decideToolCall } from "../contract-write.mjs";
+import { createGate, DOES_NOT_PROVE, hostIo } from "../gate.js";
 
-/** The file after an Edit (`params` is the edit) or a MultiEdit (`params.edits`, in order). */
+/** The file after an Edit (`params` is the edit) or a MultiEdit (`params.edits`, in order): contract-write's afterText. */
 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;
+  return afterText(Array.isArray(params.edits) ? "MultiEdit" : "Edit", params, before);
 }
 
 /** Claude Code Write/Edit/MultiEdit → the path/content keys `resolveTarget` reads. */
@@ -43,46 +33,36 @@ export const CLAUDE_TOOL_SHAPES = Object.freeze({
   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.`,
+/** contract-write's Bash decision as this hook's text: refusal or ask, each with what it proves. */
+export async function shellDecision(command, io) {
+  const d = await decideToolCall({ tool: "Bash", input: { command } }, io);
+  if (d.action === "pass") return null;
+  const named = d.action === "refuse";
+  const lines = [
+    named
+      ? `CodeRifts cannot see a contract change made by a shell command (${d.paths.map((p) => p.path).join(", ")}).`
+      : `CodeRifts cannot see what this shell command writes under ${d.scopes.map((s) => (s === "." ? "the working tree" : s)).join(", ")}, and a contract file is there.`,
+    named
+      ? `Use the Write or Edit tool for contract files, so the change is checked before it lands.`
+      : `Use the Write or Edit tool for contract files, or confirm that this command leaves them alone.`,
+    named
+      ? `Proves: only that this command names a recognised contract file with a write shape.`
+      : `Proves: only that this command has a write shape (${d.by.join(", ")}) that can reach a contract file without naming it.`,
     `Does not prove:`,
     ...SHELL_DOES_NOT_PROVE.map((l) => `  - ${l}`),
-  ].join("\n");
+  ];
+  return { decision: named ? "deny" : "ask", text: lines.join("\n") };
+}
+
+/** Kept for 0.2.x callers: the refusal text for a command, or null (named writes only). */
+export async function shellContractWrite(command, io = hostIo(process.cwd())) {
+  const r = await shellDecision(command, io);
+  return r && r.decision === "deny" ? r.text : null;
 }
 
 const ASK_TITLES = new Set([
@@ -151,13 +131,18 @@ export async function runClaudeHook(stdinText, { env = process.env, deps } = {})
   }
 
   if (payload.tool_name === "Bash") {
-    const refusal = shellContractWrite(payload.tool_input?.command);
-    return refusal ? jsonDecision("deny", refusal) : emptyPass();
+    try {
+      const r = await shellDecision(String(payload.tool_input?.command ?? ""), hostIo(payload.cwd, deps?.readFile, deps?.listDir));
+      return r ? jsonDecision(r.decision, r.text) : emptyPass();
+    } catch (err) {
+      return failClosed(`CodeRifts Claude hook failed on a Bash call (${String(err?.message ?? err)}). Not knowing is not permission.`);
+    }
   }
 
   const event = {
     toolName: payload.tool_name,
     params: payload.tool_input ?? {},
+    cwd: payload.cwd,
   };
 
   try {

package/claude-code/marketplace-entry.json

@@ -5,7 +5,7 @@
     "repo": "coderifts/agent-hooks"
   },
   "description": "Host adapters for CodeRifts: Claude Code PreToolUse asks before Write/Edit of OpenAPI, AsyncAPI, GraphQL, protobuf, or MCP manifest files. Not the GitHub Action (coderifts/contract-gate) and not the guard library (@coderifts/agent-guard).",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "author": {
     "name": "CodeRifts",
     "email": "peter@coderifts.com"

package/contract-write.mjs

@@ -0,0 +1,731 @@
+// @coderifts/contract-path · contract-write — does this tool call touch an API contract file?
+//
+// ONE decision function for the three local entry points (2026-10-03, CC-2 T2): the agent-hooks
+// Claude Code hook (claude-code/hook.mjs), the CLI's `coderifts claude-hook`, and the CodeRifts mod
+// (agent/hooks/register.js). Before this file each had its own path list, its own Edit apply and its
+// own Bash rule, and they disagreed: the CLI did not read Bash at all, agent-hooks passed a shell
+// write that did not name the file (`find api -exec sed -i …`), the mod read Write/Edit/MultiEdit
+// only, and the three sent three different artifact types for the same `.proto`.
+//
+// What it decides, for one call:
+//   Write / Edit / MultiEdit   the contract file it touches, and the text before and after
+//   Bash, a named contract     a write shape on a command that names a contract file → refuse,
+//                              with a pointer to Write/Edit, where the after text is seen
+//   Bash, no name              a write shape that can reach a directory holding a contract
+//                              without naming the file (find -exec, xargs, a glob, a tree-wide
+//                              git restore, an interpreter, an obfuscated command) → ask
+//
+// What it does not do: parse shell. The Bash rules read the command text, so a command they do not
+// recognise passes; the required check on the pull request is the guarantee, and every refusal
+// says so. A hook is feedback, not the boundary.
+//
+// Pure: no imports, no I/O. Each entry point passes what it read (the file, a directory listing)
+// in `io`. That is what lets the mod load it (a hooks module imports only files of its own plugin),
+// and what lets one parity test drive all three.
+//
+// CANONICAL SOURCE: coderifts-app packages/contract-path/contract-write.mjs. The copies are
+// written by scripts/generate-contract-write-copies.js, byte for byte (the CommonJS twin is a
+// mechanical transform), and its --check fails on any difference. Do not edit a copy.
+
+export const CONTRACT_WRITE_VERSION = '1.1.0';
+
+/** What a shell write to a named contract file gets, and what an unnamed one gets. */
+export const SHELL_NAMED_DECISION = 'refuse';
+export const SHELL_UNNAMED_DECISION = 'ask';
+
+/** How far the walk goes under a scope before it stops looking (see `findUnder`). */
+export const LISTING_LIMITS = Object.freeze({ depth: 8, entries: 5000 });
+
+// ---- paths -----------------------------------------------------------------------------------
+
+/** The @coderifts/contract-path list (index.cjs), word for word; test/contract-write.test.js holds them equal. */
+export const CONTRACT_EXT = /\.(ya?ml|json|graphql|gql|proto)$/i;
+
+export function looksLikeContractPath(p) {
+  const s = String(p || '').toLowerCase();
+  if (s.includes('node_modules/') || s.includes('vendor/')) return false;
+  return CONTRACT_EXT.test(s) && (s.includes('openapi') || s.includes('swagger') || s.includes('asyncapi')
+    || s.endsWith('.graphql') || s.endsWith('.gql') || s.endsWith('.proto') || s.includes('mcp'));
+}
+
+export function typeForPath(p) {
+  const s = String(p).toLowerCase();
+  if (s.endsWith('.graphql') || s.endsWith('.gql')) return 'graphql';
+  if (s.endsWith('.proto')) return 'grpc';
+  if (s.includes('asyncapi')) return 'asyncapi';
+  if (s.includes('mcp')) return 'mcp_manifest';
+  return 'openapi';
+}
+
+/*
+ * Two names the hooks gated before this file and the list above does not carry: the CLI's agent
+ * tool schemas (`*tool-schema*.json`) and agent-hooks' MCP tool lists (`tools.json`,
+ * `tools.wire.v1.json`). Kept, so no entry point gates less than it did; the required check's own
+ * list (index.cjs) is unchanged.
+ */
+const HOOK_EXTRAS = Object.freeze([
+  [/(^|\/)[^/]*tool-schema[^/]*\.json$/i, 'agent_tools'],
+  [/(^|\/)tools\.(wire\.v1\.)?json$/i, 'mcp_manifest'],
+]);
+
+/** `a/./b/../c` → `a/c`; backslashes become slashes; a leading `./` goes. */
+export function normalizePath(p) {
+  const s = String(p || '').replace(/\\/g, '/');
+  const abs = s.startsWith('/');
+  const out = [];
+  for (const seg of s.split('/')) {
+    if (seg === '' || seg === '.') continue;
+    if (seg === '..' && out.length && out[out.length - 1] !== '..') out.pop();
+    else if (seg !== '..' || !abs) out.push(seg);
+  }
+  return (abs ? '/' : '') + out.join('/');
+}
+
+/** The path relative to `cwd` when it is inside it, otherwise the normalized path. */
+export function relativePath(cwd, p) {
+  const file = normalizePath(p);
+  const root = normalizePath(cwd || '');
+  if (root && file.startsWith(`${root}/`)) return file.slice(root.length + 1);
+  return file;
+}
+
+function globToRegExp(pattern) {
+  let out = '^';
+  const src = normalizePath(pattern);
+  for (let i = 0; i < src.length;) {
+    if (src.startsWith('**/', i)) { out += '(?:.*/)?'; i += 3; } else if (src.startsWith('**', i)) { out += '.*'; i += 2; } else if (src[i] === '*') { out += '[^/]*'; i += 1; } else if (src[i] === '?') { out += '[^/]'; i += 1; } else { out += src[i].replace(/[.+^${}()|[\]\\]/g, '\\$&'); i += 1; }
+  }
+  return new RegExp(`${out}$`, 'i');
+}
+
+/** A `.coderifts.yml` schema entry or a `coderifts.specPath` value: an exact path, a tail, or a glob. */
+export function matchesPattern(rel, pattern) {
+  const p = normalizePath(pattern);
+  if (!p) return false;
+  if (/[*?]/.test(p)) return globToRegExp(p).test(rel);
+  return rel === p || rel.endsWith(`/${p}`);
+}
+
+/**
+ * The contract type of a path, or null when it is not a contract file.
+ * `named` (always gated) and `excluded` (never) are the project's own lists; excluded wins.
+ */
+export function contractType(p, { named = [], excluded = [] } = {}) {
+  const rel = normalizePath(p);
+  if (!rel) return null;
+  if (excluded.some((x) => matchesPattern(rel, x))) return null;
+  for (const [re, type] of HOOK_EXTRAS) if (re.test(rel) && !/(^|\/)(node_modules|vendor)\//i.test(rel)) return type;
+  if (looksLikeContractPath(rel)) return typeForPath(rel);
+  if (named.some((x) => matchesPattern(rel, x))) return typeForPath(rel);
+  return null;
+}
+
+// ---- Write / Edit / MultiEdit ----------------------------------------------------------------
+
+const FILE_TOOLS = Object.freeze({ write: 'Write', edit: 'Edit', multiedit: 'MultiEdit', multi_edit: 'MultiEdit' });
+
+/** First present value among the snake_case and camelCase spellings hosts use. */
+function field(obj, ...keys) {
+  for (const k of keys) if (obj && obj[k] !== undefined && obj[k] !== null) return obj[k];
+  return undefined;
+}
+
+/** `Write`, `Edit`, `MultiEdit`, `Bash`, or null for a tool this module does not read. */
+export function toolKind(name) {
+  const s = String(name || '');
+  if (s === 'Bash' || s.toLowerCase() === 'bash') return 'Bash';
+  return FILE_TOOLS[s.toLowerCase()] || null;
+}
+
+export function filePathOf(input) {
+  const p = field(input, 'file_path', 'filePath', 'path', 'target_file', 'targetFile');
+  return typeof p === 'string' && p !== '' ? p : null;
+}
+
+function applyOne(text, edit) {
+  const from = field(edit, 'old_string', 'oldString');
+  const to = field(edit, 'new_string', 'newString');
+  if (typeof from !== 'string' || typeof to !== 'string') return null;
+  if (from === '') return text === '' ? to : null; // Claude Code's "create with Edit"
+  if (!text.includes(from)) return null;
+  return field(edit, 'replace_all', 'replaceAll') === true ? text.split(from).join(to) : text.replace(from, () => to);
+}
+
+/** The file after the call, or null when the call does not apply to `before` (never guessed). */
+export function afterText(tool, input, before) {
+  const kind = toolKind(tool);
+  if (kind === 'Write') {
+    const c = field(input, 'content', 'contents');
+    return typeof c === 'string' ? c : null;
+  }
+  if (kind !== 'Edit' && kind !== 'MultiEdit') return null;
+  const edits = kind === 'MultiEdit' ? field(input, 'edits', 'Edits') : [input];
+  if (!Array.isArray(edits) || edits.length === 0) return null;
+  let text = before;
+  for (const e of edits) {
+    text = applyOne(text, e);
+    if (text === null) return null;
+  }
+  return text;
+}
+
+/** Why `afterText` returned null, in words a person can act on. */
+export function afterFailure(tool, input, before) {
+  const kind = toolKind(tool);
+  if (kind === 'Write') return 'its content is missing or not a string';
+  if (kind !== 'Edit' && kind !== 'MultiEdit') return `${String(tool)} is not a file tool`;
+  const edits = kind === 'MultiEdit' ? field(input, 'edits', 'Edits') : [input];
+  if (!Array.isArray(edits) || edits.length === 0) return 'its edits are missing or empty';
+  let text = before;
+  for (let i = 0; i < edits.length; i += 1) {
+    const at = kind === 'MultiEdit' ? ` (edits[${i}])` : '';
+    const from = field(edits[i], 'old_string', 'oldString');
+    if (typeof from !== 'string' || typeof field(edits[i], 'new_string', 'newString') !== 'string') return `old_string/new_string missing${at}`;
+    if (from === '' && text !== '') return `an empty old_string creates a file, and this one is not empty${at}`;
+    if (from !== '' && !text.includes(from)) return `old_string not found in the file${at}`;
+    text = applyOne(text, edits[i]);
+  }
+  return 'it does not apply';
+}
+
+// ---- Bash ------------------------------------------------------------------------------------
+//
+// One question per command: which paths can it write? Each rule below names the write TARGETS of
+// one command shape — a redirect, tee, `sed -i`, the destination of cp / install / ln / rsync,
+// every argument of mv / rm, a git pathspec, an `--out` value, the paths in an interpreter's
+// inline code. A target that is a contract file is a named write (refused, with a pointer to
+// Write/Edit). A target that is a directory, a glob, or unknown (`.`, an expansion) is a scope:
+// it asks when the entry point's listing shows a contract file under it. A path the command only
+// reads (`cat openapi.yaml > /tmp/x`, `cp openapi.yaml /tmp/`) is not a target.
+
+const COPY_CMDS = new Set(['cp', 'install', 'ln', 'rsync']);
+const REMOVE_CMDS = new Set(['rm', 'truncate', 'shred', 'unlink', 'mv']);
+const INPLACE_CMDS = new Set(['sed', 'perl', 'ruby']);
+const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash']);
+const INTERPRETERS = new Set(['python', 'python3', 'node', 'ruby', 'perl', 'deno', 'bun']);
+const PREFIXES = new Set(['sudo', 'command', 'exec', 'time', 'nohup', 'env', 'nice', 'do', 'then', 'else', 'elif', '{', '(', '!']);
+const OUT_FLAGS = /^--(out|output|outfile|out-file|output-file|write)(=(.*))?$/;
+const UNKNOWN = '.';
+
+const HEREDOC = /(?<!<)<<(?!<)-?\s*(['"]?)([A-Za-z_][A-Za-z0-9_]*)\1/g;
+
+/**
+ * Heredoc bodies are a command's stdin, not commands: `cat > notes.md <<'EOF'` followed by prose
+ * must not be read as shell. Returns the command without the bodies, and the bodies in order.
+ */
+function splitHeredocs(command) {
+  const lines = String(command).split('\n');
+  const kept = [];
+  const bodies = [];
+  for (let i = 0; i < lines.length; i += 1) {
+    kept.push(lines[i]);
+    for (const m of lines[i].matchAll(HEREDOC)) {
+      const body = [];
+      i += 1;
+      while (i < lines.length && lines[i].trim() !== m[2]) { body.push(lines[i]); i += 1; }
+      bodies.push(body.join('\n'));
+    }
+  }
+  return { text: kept.join('\n'), bodies };
+}
+
+/** Words of one command, with simple quoting honoured (no expansion). */
+function words(segment) {
+  const out = [];
+  const re = /'([^']*)'|"((?:\\.|[^"\\])*)"|(\S+)/g;
+  let m;
+  while ((m = re.exec(segment)) !== null) out.push(m[1] ?? m[2] ?? m[3]);
+  return out;
+}
+
+/**
+ * Redirect targets of one command, read outside quotes: `> f`, `>> f`, `>| f`, `&> f`, `2> f`.
+ * `>&2` / `2>&1` are descriptors, not paths.
+ */
+function redirects(text) {
+  const out = [];
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (quote) { if (ch === quote) quote = null; continue; }
+    if (ch === '\'' || ch === '"') { quote = ch; continue; }
+    if (ch !== '>') continue;
+    let j = i + 1;
+    if (text[j] === '>' || text[j] === '|') j += 1;
+    if (text[j] === '&') { i = j; continue; }
+    while (text[j] === ' ' || text[j] === '\t') j += 1;
+    const m = /^('[^']*'|"[^"]*"|[^\s;|&<>()]+)/.exec(text.slice(j));
+    if (m) { out.push(m[1].replace(/^['"]|['"]$/g, '')); i = j + m[1].length - 1; }
+  }
+  return out;
+}
+
+/** Split on ; && || | & and newlines, outside quotes. Each part keeps the part piped into it. */
+function segments(command, bodies = []) {
+  const parts = [];
+  let cur = '';
+  let quote = null;
+  let pipedFrom = null;
+  const cut = (piped) => { parts.push({ text: cur, pipedFrom }); cur = ''; pipedFrom = piped ? parts.length - 1 : null; };
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    if (quote) { cur += ch; if (ch === quote) quote = null; continue; }
+    if (ch === '\'' || ch === '"') { quote = ch; cur += ch; continue; }
+    const two = command.slice(i, i + 2);
+    if (two === '&&' || two === '||') { cut(false); i += 1; continue; }
+    if (ch === '|' && command[i - 1] !== '>') { cut(true); continue; }
+    if (ch === ';' || ch === '\n' || (ch === '&' && command[i - 1] !== '>' && command[i + 1] !== '>')) { cut(false); continue; }
+    cur += ch;
+  }
+  cut(false);
+  let next = 0;
+  return parts
+    .map((p) => {
+      const count = [...p.text.matchAll(HEREDOC)].length;
+      const stdin = bodies.slice(next, next + count).join('\n');
+      next += count;
+      const bare = p.text.replace(HEREDOC, ' ').replace(/\d*>&\d*-?/g, ' ').replace(/\d?>>?\|?\s*('[^']*'|"[^"]*"|[^\s;|&<>()]+)/g, ' ').replace(/&>\s*\S+/g, ' ');
+      return { ...p, stdin, argv: argvOf(words(bare)) };
+    });
+}
+
+/** Drop leading VAR=value assignments and sudo/env-style prefixes. */
+function argvOf(ws) {
+  let i = 0;
+  while (i < ws.length && (/^[A-Za-z_][A-Za-z0-9_]*=/.test(ws[i]) || PREFIXES.has(ws[i]))) i += 1;
+  return ws.slice(i);
+}
+
+const isFlag = (w) => /^-/.test(w);
+const baseOf = (cmd) => String(cmd || '').split('/').pop();
+const operands = (ws) => ws.filter((w) => w !== '' && !isFlag(w));
+
+/** A path the shell expands ($VAR, $(…), `…`) can be anything: unknown. */
+const expanded = (t) => (/[`]|\$\(/.test(t) ? UNKNOWN : t);
+
+/** The files `sed -i` / `perl -pi` / `ruby -i` edit: the operands, less the script when it is the first one. */
+function inplaceTargets(rest) {
+  if (!rest.some((w) => /^-[a-zA-Z]*i/.test(w) || w === '--in-place' || w.startsWith('--in-place='))) return [];
+  const files = [];
+  let scriptGiven = false;
+  for (let i = 0; i < rest.length; i += 1) {
+    const w = rest[i];
+    if (w === '-e' || w === '-f' || w === '--expression' || w === '--file' || /^-[a-zA-Z]*[ef]$/.test(w) && !/^-[a-zA-Z]*i$/.test(w)) { scriptGiven = true; i += 1; continue; }
+    if (w === '' || isFlag(w)) continue;
+    files.push(w);
+  }
+  return (scriptGiven ? files : files.slice(1)).map(expanded);
+}
+
+/** find's reach as globs: each root, narrowed by -name / -iname / -path when present. */
+function findScopes(rest) {
+  const roots = [];
+  for (const w of rest) {
+    if (isFlag(w) || w === '(' || w === '!') break;
+    roots.push(expanded(w));
+  }
+  const starts = roots.length ? roots : [UNKNOWN];
+  const names = [];
+  const paths = [];
+  rest.forEach((w, i) => {
+    if ((w === '-name' || w === '-iname') && rest[i + 1]) names.push(rest[i + 1]);
+    if ((w === '-path' || w === '-ipath' || w === '-wholename') && rest[i + 1]) paths.push(rest[i + 1]);
+  });
+  if (!names.length && !paths.length) return starts;
+  return [...starts.flatMap((r) => names.map((n) => `${r}/**/${n}`)), ...paths];
+}
+
+/** The argv find runs with -exec / -execdir / -ok / -okdir, if any. */
+function findExec(rest) {
+  const at = rest.findIndex((w) => /^-(exec|execdir|ok|okdir)$/.test(w));
+  if (at < 0) return null;
+  const end = rest.findIndex((w, i) => i > at && (w === ';' || w === '\\;' || w === '+'));
+  return rest.slice(at + 1, end < 0 ? undefined : end);
+}
+
+/** The argv xargs runs (after its own options). */
+function xargsExec(rest) {
+  let i = 0;
+  while (i < rest.length && isFlag(rest[i])) i += /^-[IdLnPsE]$/.test(rest[i]) ? 2 : 1;
+  return rest.slice(i);
+}
+
+/** What xargs is fed: find's reach, echo's words, a lister's paths; else the working tree. */
+function xargsScopes(from) {
+  if (!from || !from.argv.length) return [UNKNOWN];
+  const [cmd, ...rest] = from.argv;
+  const base = baseOf(cmd);
+  if (base === 'find') return findScopes(rest);
+  if (base === 'echo' || base === 'printf') return operands(rest).map(expanded);
+  const listed = operands(rest).filter((w) => w === '.' || w.includes('/') || /[*?]/.test(w));
+  return listed.length ? listed.map(expanded) : [UNKNOWN];
+}
+
+/** Does this argv, run by find -exec or xargs on unseen paths, write them? */
+function writesArguments(argv) {
+  const [cmd, ...rest] = argv;
+  const base = baseOf(cmd);
+  if (COPY_CMDS.has(base) || REMOVE_CMDS.has(base) || base === 'tee' || base === 'patch') return true;
+  if (INPLACE_CMDS.has(base) && rest.some((w) => /^-[a-zA-Z]*i/.test(w))) return true;
+  if (SHELLS.has(base) && rest.includes('-c')) return true;
+  if (INTERPRETERS.has(base) && rest.some((w) => /^-[a-zA-Z]*[ce]$/.test(w))) return true; // inline code; running a script is not read as a write
+  if (base === 'git' && ['checkout', 'restore', 'rm', 'mv'].includes(rest[0])) return true;
+  return false;
+}
+
+/*
+ * git writes the working tree from the index or a commit: checkout / restore / rm / mv with a
+ * pathspec, reset --hard, stash pop / apply, clean, apply, am. A branch switch, merge, pull or
+ * rebase also moves contract files, and so does every other way a commit lands; those are left to
+ * the required check, which sees the commit (asking on every `git pull` teaches people to click
+ * through).
+ */
+function gitTargets(rest) {
+  const [sub, ...args] = rest;
+  const dd = args.indexOf('--');
+  const pathspec = (dd >= 0 ? args.slice(dd + 1) : operands(args).filter((w) => w === '.' || w.includes('/') || /[*?]/.test(w) || /\.[a-z]+$/i.test(w))).map(expanded);
+  if (['checkout', 'restore', 'rm', 'mv'].includes(sub)) return pathspec;
+  if (sub === 'reset') return args.includes('--hard') ? [UNKNOWN] : [];
+  if (sub === 'stash') return args[0] === 'pop' || args[0] === 'apply' ? [UNKNOWN] : [];
+  if (sub === 'clean' || sub === 'apply' || sub === 'am') return pathspec.length ? pathspec : [UNKNOWN];
+  return [];
+}
+
+/*
+ * The write calls of inline code, and where each one writes: its path argument as a string
+ * literal, or a name bound to one earlier in the same code (`p = 'x.json'` … `open(p, 'w')`).
+ * A write call whose target is neither is unknown (`.`); so is code that walks a directory.
+ */
+const WRITE_CALLS = Object.freeze([
+  /\bopen\s*\(\s*([^,()]+?)\s*,\s*(?:mode\s*=\s*)?['"][wax+]/g,
+  /\b(?:Path|pathlib\.Path)\s*\(\s*([^()]+?)\s*\)\s*\.(?:write_text|write_bytes|unlink|touch)\s*\(/g,
+  // \b: a match starts only where a word starts, so a long run of word characters is scanned once (no O(n²)).
+  /\b([A-Za-z_][A-Za-z0-9_]*)\s*\.(?:write_text|write_bytes)\s*\(/g,
+  /\b(?:fs\.)?(?:writeFileSync|writeFile|appendFileSync|appendFile|rmSync|unlinkSync|truncateSync)\s*\(\s*([^,()]+?)\s*[,)]/g,
+  /\bFile\.write\s*\(\s*([^,()]+?)\s*,/g,
+  /\bos\.(?:remove|unlink)\s*\(\s*([^,()]+?)\s*\)/g,
+  /\b(?:shutil\.(?:copy2?|copyfile|move)|os\.(?:rename|replace)|(?:fs\.)?(?:copyFileSync|renameSync))\s*\(\s*[^,()]+?\s*,\s*([^,()]+?)\s*[,)]/g,
+  /\bshutil\.rmtree\s*\(\s*([^,()]+?)\s*[,)]/g,
+]);
+const WRITE_ANY = /\bopen\s*\([^\n]{0,200}?['"][wax]\+?['"]\s*[,)]|\.write_(text|bytes)\s*\(|\b(writeFileSync|writeFile|appendFileSync|copyFileSync|renameSync|rmSync|unlinkSync)\s*\(|\bFile\.write\s*\(|\bos\.(remove|unlink|rename|replace)\s*\(|\bshutil\.(copy2?|copyfile|move|rmtree)\s*\(/;
+// Every pattern above is bounded or anchored at a word start: a 100 KB heredoc is read in linear time.
+const INTERPRETER_WALK = /os\.walk|glob\.|rglob|\.glob\(|readdirSync|Dir\.glob|Find::|globSync|os\.listdir/;
+
+/** A write call's argument as a path: a literal, a name bound to a literal, or unknown. */
+function argPath(arg, code) {
+  const a = String(arg).trim();
+  const lit = /^(?:[rbuf]{0,2})(['"])([^'"]*)\1$/.exec(a);
+  if (lit) return lit[2];
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(a)) {
+    const bound = new RegExp(`(?:^|[\\s;(,])(?:const |let |var )?${a}\\s*=\\s*(?:(?:pathlib\\.)?Path\\(\\s*)?(?:[rbuf]{0,2})(['"])([^'"\\n]*)\\1`).exec(code);
+    if (bound) return bound[2];
+  }
+  return UNKNOWN;
+}
+
+/** Inline code (-c / -e) or code on stdin (a heredoc): where its write calls write. */
+function interpreterTargets(rest, stdin) {
+  const flag = rest.findIndex((w) => /^-[a-zA-Z]*[ce]$/.test(w));
+  const code = flag >= 0 ? String(rest[flag + 1] ?? '') : (operands(rest).length === 0 || rest.includes('-') ? stdin : '');
+  if (!code) return [];
+  // Text the code carries as data (a triple-quoted block, a template literal) is not code that runs.
+  const live = code.replace(/"""[\s\S]*?"""|'''[\s\S]*?'''|`[^`]*`/g, '""');
+  const targets = WRITE_CALLS.flatMap((re) => [...live.matchAll(re)].map((m) => argPath(m[1], live)));
+  // A write call whose argument the patterns above could not read (`open(os.path.join(r, f), 'w')`)
+  // still writes somewhere: unknown.
+  const unread = WRITE_ANY.test(live) && targets.length === 0;
+  if (!targets.length && !unread) return [];
+  return INTERPRETER_WALK.test(live) || unread ? [...targets, UNKNOWN] : targets;
+}
+
+/** The output of --out / --output / --output-file … on any command. */
+function outFlagTargets(rest) {
+  const out = [];
+  rest.forEach((w, i) => {
+    const m = OUT_FLAGS.exec(w);
+    if (m) out.push(m[3] !== undefined ? m[3] : String(rest[i + 1] ?? ''));
+  });
+  return out.filter(Boolean).map(expanded);
+}
+
+/** The write targets of one command (argv after redirects are taken out). */
+function commandTargets(seg, all, depth) {
+  const [cmd, ...rest] = seg.argv;
+  const base = baseOf(cmd);
+  const out = outFlagTargets(rest);
+  if (!cmd) return out;
+  if (base === 'eval') return [UNKNOWN];
+  if (SHELLS.has(base)) {
+    const at = rest.indexOf('-c');
+    if (at >= 0) return depth < 2 ? shellWriteTargets(String(rest[at + 1] ?? ''), depth + 1) : [UNKNOWN];
+    return seg.pipedFrom !== null || seg.stdin ? [UNKNOWN] : out; // `… | sh`, `sh <<EOF` run unseen text
+  }
+  if (base === 'tee') return [...out, ...operands(rest).map(expanded)];
+  if (COPY_CMDS.has(base)) {
+    const t = rest.findIndex((w) => w === '-t' || w === '--target-directory');
+    const ops = operands(rest);
+    return [...out, ...(t >= 0 && rest[t + 1] ? [rest[t + 1]] : ops.slice(-1)).map(expanded)];
+  }
+  if (REMOVE_CMDS.has(base)) return [...out, ...operands(rest).map(expanded)];
+  if (INPLACE_CMDS.has(base)) {
+    const inplace = inplaceTargets(rest);
+    if (inplace.length || base === 'sed') return [...out, ...inplace];
+    return [...out, ...interpreterTargets(rest, seg.stdin)];
+  }
+  if (base === 'patch') { const ops = operands(rest); return [...out, ...(ops.length ? ops.map(expanded) : [UNKNOWN])]; }
+  if (base === 'dd') return [...out, ...rest.filter((w) => w.startsWith('of=')).map((w) => expanded(w.slice(3)))];
+  if (base === 'curl') return [...out, ...rest.flatMap((w, i) => (w === '-o' ? [expanded(String(rest[i + 1] ?? ''))] : []))];
+  if (base === 'wget') return [...out, ...rest.flatMap((w, i) => (w === '-O' ? [expanded(String(rest[i + 1] ?? ''))] : []))];
+  if (base === 'git') return [...out, ...gitTargets(rest)];
+  if ((base === 'tar' && /^-?[a-zA-Z]*x/.test(rest[0] || '')) || base === 'unzip') {
+    const at = rest.findIndex((w) => w === '-C' || w === '-d' || w === '--directory');
+    return [...out, at >= 0 && rest[at + 1] ? expanded(rest[at + 1]) : UNKNOWN];
+  }
+  if (base === 'find') {
+    const exec = findExec(rest);
+    return rest.includes('-delete') || (exec && writesArguments(exec)) ? [...out, ...findScopes(rest)] : out;
+  }
+  if (base === 'xargs') return writesArguments(xargsExec(rest)) ? [...out, ...xargsScopes(seg.pipedFrom === null ? null : all[seg.pipedFrom])] : out;
+  if (INTERPRETERS.has(base)) return [...out, ...interpreterTargets(rest, seg.stdin)];
+  return out;
+}
+
+/**
+ * Every path a command can write, as it is written in the command: a file, a directory, a glob,
+ * or `.` when the command does not say (an expansion, eval, a pipe into sh, a tree-wide git
+ * restore). A redirect into /dev/* is not a write to the tree.
+ */
+export function shellWriteTargets(command, depth = 0) {
+  return [...new Set(shellWrites(command, depth).map((w) => w.target))];
+}
+
+/** The same, with the command shape that writes each target (`redirect`, `rm`, `git stash`, …). */
+export function shellWrites(command, depth = 0) {
+  const { text, bodies } = splitHeredocs(String(command || ''));
+  const segs = segments(text, bodies);
+  const vars = {};
+  let dir = '';
+  const writes = [];
+  for (const seg of segs) {
+    for (const [, k] of seg.text.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=["']?\$\(mktemp\b/g)) vars[k] = '/tmp/mktemp'; // a fresh temp dir is outside the tree
+    const loop = /^\s*for\s+([A-Za-z_][A-Za-z0-9_]*)\s+in\s+(.+?)\s*$/.exec(seg.text);
+    if (loop && !/[$`*?]/.test(loop[2])) vars[loop[1]] = words(loop[2]); // `for r in a b; do … $r …`
+    for (const [, k, v] of seg.text.matchAll(/(?:^|\s)([A-Za-z_][A-Za-z0-9_]*)=('[^']*'|"[^"$`]*"|[^\s;|&$`'"]+)/g)) vars[k] = v.replace(/^['"]|['"]$/g, '');
+    const by = baseOf(seg.argv[0]) === 'git' ? `git ${seg.argv[1] ?? ''}`.trim() : baseOf(seg.argv[0]);
+    const own = [
+      ...redirects(seg.text).map((t) => ({ target: t, by: 'redirect' })),
+      ...commandTargets(seg, segs, depth).map((t) => ({ target: t, by })),
+    ];
+    for (const w of own) {
+      for (const t of resolveVars(w.target, vars)) {
+        const target = within(dir, t);
+        if (target && !target.startsWith('/dev/')) writes.push({ target, by: w.by });
+      }
+    }
+    if (seg.argv[0] === 'cd') dir = within(dir, resolveVars(String(seg.argv[1] ?? '~'), vars)[0] ?? '') || dir;
+  }
+  return writes;
+}
+
+/** `$f` / `${f}` with a value assigned earlier in the same command; anything else stays unknown. */
+function resolveVars(t, vars) {
+  let forms = [String(t)];
+  for (const [k, v] of Object.entries(vars)) {
+    const re = new RegExp(`\\$\\{?${k}\\}?(?![A-Za-z0-9_])`, 'g');
+    forms = forms.flatMap((f) => (re.test(f) ? (Array.isArray(v) ? v : [v]).map((x) => f.replace(re, () => x)) : [f]));
+  }
+  return forms.map((f) => {
+    const r = expanded(f);
+    if (!/\$/.test(r)) return r;
+    // `> "$LOG/run.txt"`: whatever $LOG is, a file named run.txt is not a contract file.
+    const name = r.split('/').pop();
+    if (!/\$/.test(name) && /\.[A-Za-z0-9]+$/.test(name) && !CONTRACT_EXT.test(name)) return '';
+    return UNKNOWN;
+  });
+}
+
+/** A target as seen from the directory a `cd` earlier in the command moved to. */
+function within(dir, t) {
+  if (!t || !dir) return t;
+  if (t.startsWith('/') || t.startsWith('~')) return t;
+  if (t === UNKNOWN) return dir;
+  return `${dir.replace(/\/$/, '')}/${t}`;
+}
+
+/**
+ * The home directory a `~` stands for. Read from the working directory (`/Users/<name>/…`,
+ * `/home/<name>/…`), not from the environment: the mod may not read one, and every entry point
+ * has to resolve `~` the same way. A tree outside those two answers null.
+ */
+export function homeOf(cwd) {
+  const m = /^(\/Users\/[^/]+|\/home\/[^/]+)(\/|$)/.exec(normalizePath(cwd || ''));
+  return m ? m[1] : null;
+}
+
+/** A target relative to the working tree, `.` for an ancestor of it, null outside it. */
+export function scopeInTree(target, { cwd = '' } = {}) {
+  let t = String(target);
+  if (t === '~' || t.startsWith('~/')) {
+    const home = homeOf(cwd);
+    if (!home) return UNKNOWN; // a home that cannot be read from the tree may hold it
+    t = home + t.slice(1);
+  }
+  if (!t.startsWith('/')) return normalizePath(t) || UNKNOWN;
+  const abs = normalizePath(t);
+  const root = normalizePath(cwd);
+  if (!root) return null;
+  if (abs === root || root.startsWith(`${abs === '/' ? '' : abs}/`)) return UNKNOWN;
+  if (abs.startsWith(`${root}/`)) return abs.slice(root.length + 1);
+  return null;
+}
+
+/** Does the listing under `scope` hold a contract file? A glob scope is matched against its directory's listing. */
+export function contractUnder(scope, listing, opts = {}) {
+  const s = normalizePath(scope) || UNKNOWN;
+  const files = Array.isArray(listing) ? listing : [];
+  if (/[*?]/.test(s)) return files.some((f) => globToRegExp(s).test(normalizePath(f)) && contractType(f, opts));
+  return files.some((f) => contractType(f, opts));
+}
+
+/** The directory an entry point lists for a scope: a glob's parent, `.` for the working tree. */
+export function listingRoot(scope) {
+  const s = normalizePath(scope) || UNKNOWN;
+  if (!/[*?]/.test(s)) return s;
+  const head = s.split('/');
+  const at = head.findIndex((p) => /[*?]/.test(p));
+  return head.slice(0, at).join('/') || UNKNOWN;
+}
+
+/** Directories the walk does not enter: no contract file there is gated (node_modules, vendor) or it is not the tree (.git). */
+const SKIP_DIRS = new Set(['.git', 'node_modules', 'vendor']);
+
+/**
+ * Walk `root` breadth-first with the host's one-level reader and stop at the first path `match`
+ * accepts. `listDir(dir)` → [{ name, kind: 'file' | 'directory' }], or null when `dir` is not a
+ * directory. Returns { found, complete }: complete is false when a limit stopped the walk, and the
+ * caller then treats the scope as holding a contract (not knowing is not a pass).
+ */
+export async function findUnder(listDir, root, match, limits = LISTING_LIMITS) {
+  const start = normalizePath(root) || UNKNOWN;
+  const top = await listDir(start);
+  if (!Array.isArray(top)) return { found: start !== UNKNOWN && match(start) ? start : null, complete: true };
+  let queue = [{ dir: start, entries: top, depth: 0 }];
+  let seen = 0;
+  while (queue.length) {
+    const next = [];
+    for (const { dir, entries, depth } of queue) {
+      for (const e of [...entries].sort((a, b) => String(a.name).localeCompare(String(b.name)))) {
+        seen += 1;
+        if (seen > limits.entries) return { found: null, complete: false };
+        const rel = dir === UNKNOWN ? String(e.name) : `${dir}/${e.name}`;
+        if (e.kind === 'directory') {
+          if (SKIP_DIRS.has(e.name)) continue;
+          if (depth + 1 > limits.depth) return { found: null, complete: false };
+          const sub = await listDir(rel);
+          if (Array.isArray(sub)) next.push({ dir: rel, entries: sub, depth: depth + 1 });
+        } else if (match(rel)) {
+          return { found: rel, complete: true };
+        }
+      }
+    }
+    queue = next;
+  }
+  return { found: null, complete: true };
+}
+
+// ---- the decision ------------------------------------------------------------------------------
+
+/**
+ * One tool call → what the entry point does with it.
+ *
+ *   { action: 'pass' }                                   not a contract call this module reads
+ *   { action: 'gate', path, rel, type, before, after }   send before/after to CodeRifts
+ *   { action: 'refuse', reason, why, … }                 refuse locally: a shell write to a named
+ *                                                       contract file, an edit that does not
+ *                                                       apply, a contract file it cannot read
+ *   { action: 'ask', reason, why, scopes }               a shell write that can reach a contract
+ *                                                       file without naming it
+ *
+ * io: { cwd, named, excluded,
+ *       readFile(path) → string | null when missing; throws when unreadable,
+ *       listDir(dir)   → [{ name, kind }] for one level (relative to cwd), null when not a directory;
+ *                        the walk (findUnder, LISTING_LIMITS) is this module's, so every entry
+ *                        point looks as far as the others,
+ *       listFiles(dir) → (instead of listDir) every file path under dir, for a host that has them }
+ * The readers may be async. With neither lister, a shell scope is assumed to hold a contract.
+ */
+export async function decideToolCall(call, io = {}) {
+  const kind = toolKind(call && (call.tool ?? call.tool_name));
+  const input = (call && (call.input ?? call.tool_input)) || {};
+  const opts = { named: io.named || [], excluded: io.excluded || [] };
+  if (kind === 'Bash') return decideShell(String(field(input, 'command') ?? ''), io, opts);
+  if (!kind) return { action: 'pass' };
+  const filePath = filePathOf(input);
+  if (!filePath) return { action: 'pass' };
+  const rel = relativePath(io.cwd, filePath);
+  const type = contractType(rel, opts);
+  if (!type) return { action: 'pass' };
+  let before;
+  try {
+    before = (await (io.readFile ? io.readFile(filePath) : null)) ?? '';
+  } catch (err) {
+    return { action: 'refuse', reason: 'unreadable', rel, type, why: `${rel} is a contract file and could not be read (${String((err && err.message) || err)})` };
+  }
+  const after = afterText(kind, input, before);
+  if (after === null) {
+    return { action: 'refuse', reason: 'edit_does_not_apply', rel, type, why: `the ${kind} does not apply to ${rel} as it is on disk (${afterFailure(kind, input, before)}), so there is no after text to check` };
+  }
+  return { action: 'gate', path: filePath, rel, type, before, after };
+}
+
+/** Is there a contract file under `scope`? Unknown (no reader, a limit hit) counts as yes. */
+async function mayHoldContract(scope, io, opts) {
+  const glob = /[*?]/.test(scope) ? globToRegExp(normalizePath(scope)) : null;
+  const match = (rel) => Boolean(contractType(rel, opts)) && (!glob || glob.test(normalizePath(rel)));
+  // A reader that throws is a scope this module could not look into: it counts as holding a contract.
+  try {
+    if (io.listDir) {
+      const r = await findUnder(io.listDir, listingRoot(scope), match);
+      return Boolean(r.found) || !r.complete;
+    }
+    if (io.listFiles) {
+      const listing = await io.listFiles(listingRoot(scope));
+      return !Array.isArray(listing) || contractUnder(scope, listing, opts);
+    }
+  } catch {
+    return true;
+  }
+  return true;
+}
+
+async function decideShell(command, io, opts) {
+  const named = [];
+  const scopes = new Map();
+  for (const { target, by } of shellWrites(command)) {
+    const inTree = scopeInTree(target, io);
+    if (inTree === null) continue;
+    const type = inTree !== UNKNOWN && !/[*?]/.test(inTree) ? contractType(inTree, opts) : null;
+    if (type) named.push({ path: target, type, by });
+    else scopes.set(inTree, [...(scopes.get(inTree) || []), by]);
+  }
+  if (named.length) {
+    return {
+      action: SHELL_NAMED_DECISION,
+      reason: 'shell_names_contract',
+      paths: named,
+      why: `this shell command writes ${named.map((n) => `${n.path} (${n.by})`).join(', ')}, and a shell write cannot be checked: the after text is not known. Use the Write or Edit tool for contract files`,
+    };
+  }
+  const reached = [];
+  for (const [scope, bys] of scopes) {
+    if (await mayHoldContract(scope, io, opts)) reached.push({ scope, by: [...new Set(bys)] });
+  }
+  if (!reached.length) return { action: 'pass' };
+  return {
+    action: SHELL_UNNAMED_DECISION,
+    reason: 'shell_may_write_contract',
+    scopes: reached.map((r) => r.scope),
+    by: [...new Set(reached.flatMap((r) => r.by))],
+    why: `this shell command can write files under ${reached.map((r) => `${r.scope === UNKNOWN ? 'the working tree' : r.scope} (${r.by.join(', ')})`).join(', ')} without naming them, and a contract file is there. Use the Write or Edit tool for contract files, or confirm that this command leaves them alone`,
+  };
+}

package/gate.js

@@ -4,24 +4,14 @@
  * `index.js` is the OpenClaw entry; everything decidable lives here.
  */
 
-import { readFile } from "node:fs/promises";
-
-/**
- * Path suffix -> the `type` the CodeRifts change-set surface expects.
- *
- * Deliberately a short, explicit list. A gate that tries to recognise every contract artifact ends
- * up guessing, and a gate that guesses either blocks documentation or waves through a schema. What
- * is not on this list is not gated — and the approval text says so, so nobody reads a CONTINUE as
- * "the whole change was checked".
- */
-export const ARTIFACT_TYPES = Object.freeze([
-  [/(^|\/)openapi[^/]*\.(ya?ml|json)$/i, "openapi"],
-  [/(^|\/)swagger[^/]*\.(ya?ml|json)$/i, "openapi"],
-  [/(^|\/)asyncapi[^/]*\.(ya?ml|json)$/i, "asyncapi"],
-  [/\.graphql$|\.gql$/i, "graphql"],
-  [/\.proto$/i, "protobuf"],
-  [/(^|\/)(mcp|tools)\.(wire\.v1\.)?json$/i, "mcp"],
-]);
+import { readFile, readdir } from "node:fs/promises";
+import { isAbsolute, resolve } from "node:path";
+// The one decision function this hook, `coderifts claude-hook` and the CodeRifts mod share
+// (2026-10-03): which path is a contract and of what type, the after text of an Edit, what a shell
+// command writes. A byte copy of @coderifts/contract-path's contract-write.mjs, written by the app's
+// scripts/generate-contract-write-copies.js; contract-write.sha256 beside it is checked by
+// test/contract-write-copy.test.js.
+import { contractType, decideToolCall, toolKind } from "./contract-write.mjs";
 
 /** Tools whose params carry a path and a new file body. */
 export const DEFAULT_TOOL_SHAPES = Object.freeze({
@@ -31,9 +21,15 @@ export const DEFAULT_TOOL_SHAPES = Object.freeze({
   str_replace_editor: { path: "path", content: "new_str" },
 });
 
+/**
+ * The contract type of a path (contract-write's list: OpenAPI/Swagger, AsyncAPI, GraphQL, protobuf,
+ * MCP manifests and tool lists, agent tool schemas), or null. Until 0.3.0 this file kept its own
+ * list and sent `protobuf` and `mcp`, which the change-set surface does not analyze; the types are
+ * now the surface's own (`grpc`, `mcp_manifest`). What is not on the list is not gated, and the
+ * refusal text says so.
+ */
 export function classifyPath(p) {
-  for (const [re, type] of ARTIFACT_TYPES) if (re.test(p)) return type;
-  return null;
+  return contractType(p);
 }
 
 /**
@@ -47,6 +43,13 @@ 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, and a plugin hook runs after the mods even when managed settings force-enable the plugin",
+  "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)",
+  // 0.3.0 (2026-10-03), measured on Claude Code 2.1.288 with a probe plugin: disableAllHooks from
+  // --settings and from the project's .claude/settings.json, --safe-mode and --bare each stopped a
+  // plugin's PreToolUse hook; a shell command rewrote .claude/settings.json unless the sandbox was on.
+  "that the hook was running — disableAllHooks in any settings file (the project's .claude/settings.json included, which a shell command can rewrite unless the sandbox protects it), --safe-mode or --bare turns it off",
+  "that a contract generated from source code was checked — a contract generated from source code (annotations, decorators, a build step) changes when the source changes; the hooks see the source edit, not the contract; the required check sees the generated contract",
 ]);
 
 /**
@@ -73,7 +76,7 @@ export function blockText(op, why) {
 }
 
 /** One JSON-RPC POST. No session handshake, no SDK — measured to be all the surface needs. */
-async function askCodeRifts({ endpoint, apiKey, timeoutMs, operation, artifact }) {
+export async function askCodeRifts({ endpoint, apiKey, timeoutMs, operation, artifact }) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   try {
@@ -221,6 +224,48 @@ export function resolveTarget(event, shapes) {
   return null;
 }
 
+/** The host readers contract-write takes: a missing file is null, an unreadable one throws. */
+export function hostIo(cwd, read = (p) => readFile(p, "utf8"), list = defaultListDir) {
+  const abs = (p) => (isAbsolute(p) ? p : resolve(cwd || process.cwd(), p));
+  return {
+    cwd: cwd || process.cwd(),
+    readFile: async (p) => {
+      try {
+        return await read(abs(p));
+      } catch (err) {
+        if (err && err.code === "ENOENT") return null;
+        throw err;
+      }
+    },
+    listDir: (dir) => list(abs(dir)),
+  };
+}
+
+async function defaultListDir(dir) {
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    return entries.map((e) => ({ name: e.name, kind: e.isDirectory() ? "directory" : "file" }));
+  } catch {
+    return null;
+  }
+}
+
+async function gateClaudeCall(event, { read, call, endpoint, apiKey, timeoutMs, operation }) {
+  const d = await decideToolCall({ tool: event.toolName, input: event.params ?? {} }, hostIo(event.cwd, read));
+  if (d.action === "pass") return undefined;
+  if (d.action !== "gate") {
+    return ask("CodeRifts gate could not read the proposed change", `${d.why}. It will not pass a change it has not seen.`);
+  }
+  const outcome = await call({
+    endpoint,
+    apiKey,
+    timeoutMs,
+    operation,
+    artifact: { id: d.path, type: d.type, before: d.before, after: d.after },
+  });
+  return decide(outcome, { operation, path: d.path });
+}
+
 /** The handler, with its I/O injected so a test can drive it without a network or a disk. */
 export function createGate(config = {}, deps = {}) {
   const endpoint = config.endpoint ?? "https://app.coderifts.com/mcp";
@@ -232,6 +277,11 @@ export function createGate(config = {}, deps = {}) {
   const read = deps.readFile ?? ((p) => readFile(p, "utf8"));
 
   return async function beforeToolCall(event) {
+    // A Claude Code file tool (Write / Edit / MultiEdit): contract-write decides the path, the type
+    // and the after text, as the CLI hook and the mod do.
+    const claudeTool = toolKind(event.toolName);
+    if (claudeTool && claudeTool !== "Bash") return gateClaudeCall(event, { read, call, endpoint, apiKey, timeoutMs, operation });
+
     const target = resolveTarget(event, shapes);
     // 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.

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "coderifts-contract-gate",
   "name": "CodeRifts contract gate",
   "description": "Ask CodeRifts before an agent writes a contract artifact.",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderifts/agent-hooks",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "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",
@@ -16,6 +16,7 @@
   "files": [
     "index.js",
     "gate.js",
+    "contract-write.mjs",
     "openclaw.plugin.json",
     "README.md",
     "CHANGELOG.md",