@coderifts/agent-hooks 0.3.3 → 0.3.5

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-hooks",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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,17 @@
 # Changelog
 
+## 0.3.5 — 2026-10-09
+### Fixed
+- **The Claude Code hook runs when invoked through a symlinked path.** The entry check resolves the invoked path and this file. The same check in `scripts/sync-version.mjs` does too. If the check cannot tell, the entry runs.
+- **contract-write 1.3.2 (no decision changes).** The generated copy adds `readPlan` and `pendingListings`.
+
+## 0.3.4 — 2026-10-09
+### Fixed
+- **A plain `mcp.json` that is both an MCP client configuration and a tool manifest, or that does not parse, is not
+  read or sent and is not passed (contract-write 1.3.1).** On the Claude Code file tools and on the OpenClaw tool
+  shapes the gate asks, with one sentence: split the server list and the tool manifest into separate files, or make
+  the file valid JSON (no comments) to have it checked.
+
 ## 0.3.3 — 2026-10-08
 ### Fixed
 - **A plain `mcp.json` is decided by its content (contract-write 1.3.0, P65c).** 0.3.2 skipped every `mcp.json` by

package/claude-code/hook.mjs

@@ -16,9 +16,8 @@
  *     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 { afterText, decideToolCall } from "../contract-write.mjs";
+import { invokedDirectly } from "../entry-guard.mjs";
 import { createGate, DOES_NOT_PROVE, governanceUnavailable, hostIo } from "../gate.js";
 
 /** The file after an Edit (`params` is the edit) or a MultiEdit (`params.edits`, in order): contract-write's afterText. */
@@ -166,8 +165,6 @@ async function main() {
   process.exit(out.exitCode);
 }
 
-const invokedDirectly =
-  Boolean(process.argv[1]) && import.meta.url === pathToFileURL(resolve(process.argv[1])).href;
-if (invokedDirectly) {
+if (invokedDirectly(process.argv[1], import.meta.url)) {
   main();
 }

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.3.3",
+  "version": "0.3.5",
   "author": {
     "name": "CodeRifts",
     "email": "peter@coderifts.com"

package/contract-write.mjs

@@ -27,7 +27,7 @@
 // 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.3.0';
+export const CONTRACT_WRITE_VERSION = '1.3.2';
 
 /** What a shell write to a named contract file gets, and what an unnamed one gets. */
 export const SHELL_NAMED_DECISION = 'refuse';
@@ -65,26 +65,56 @@ export const MCP_JSON_BY_CONTENT = /(^|\/)mcp\.json$/i;
 const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
 
 /**
- * 'client_config' when the text is a JSON object with `mcpServers` or `servers` (an object) and no
- * `tools`; otherwise 'contract' — a `tools` key, any other shape, and text that does not parse
- * (fail-closed: what cannot be read as a client configuration is checked as a contract).
+ * The kind of a plain mcp.json's text, from its parsed TOP-LEVEL object (a leading BOM is ignored):
+ *   'client_config'  `mcpServers` or `servers` (an object) and no `tools`: never sent, counts as no file
+ *   'mixed'          `mcpServers` or `servers` (an object) AND `tools`: never sent, and not passed (P65d)
+ *   'unparseable'    JSON.parse fails (comments, a trailing comma, …): never sent, and not passed (P65d)
+ *   'contract'       anything else: a `tools` key, an object without a server list, a parsed non-object
+ * 1.3.1 (P65d, 2026-10-09): 1.3.0 checked `tools` first and called a parse failure a contract, so a server
+ * list with a `tools` key, and a client configuration with a comment, were sent as contracts.
  */
 export function mcpJsonKind(text) {
   let doc;
   try {
     doc = JSON.parse(String(text ?? '').replace(/^\uFEFF/, ''));
   } catch {
-    return 'contract';
+    return 'unparseable';
   }
-  if (!isObject(doc) || 'tools' in doc) return 'contract';
-  return isObject(doc.mcpServers) || isObject(doc.servers) ? 'client_config' : 'contract';
+  if (!isObject(doc)) return 'contract';
+  const servers = isObject(doc.mcpServers) || isObject(doc.servers);
+  if (servers) return 'tools' in doc ? 'mixed' : 'client_config';
+  return 'contract';
+}
+
+/** The kind of one present side of a content-decided path; null for any other path or an empty side. */
+export function mcpJsonContentKind(path, text) {
+  if (typeof text !== 'string' || text === '') return null;
+  const rel = normalizePath(path);
+  if (!MCP_JSON_BY_CONTENT.test(rel) || MCP_CLIENT_CONFIG.test(rel)) return null;
+  return mcpJsonKind(text);
 }
 
 /** True when `path` is decided by content and `text` (one side, present) is a client configuration. */
 export function isClientConfigContent(path, text) {
-  if (typeof text !== 'string' || text === '') return false;
-  const rel = normalizePath(path);
-  return MCP_JSON_BY_CONTENT.test(rel) && !MCP_CLIENT_CONFIG.test(rel) && mcpJsonKind(text) === 'client_config';
+  return mcpJsonContentKind(path, text) === 'client_config';
+}
+
+/** 'mixed' or 'unparseable': never sent, and never passed silently — the hooks ask, the check is red. */
+export function isHeldContent(path, text) {
+  const k = mcpJsonContentKind(path, text);
+  return k === 'mixed' || k === 'unparseable';
+}
+
+/** Every side whose text no entry point sends: a client configuration, 'mixed', 'unparseable'. */
+export function isNeverSent(path, text) {
+  return isClientConfigContent(path, text) || isHeldContent(path, text);
+}
+
+/** The one sentence every entry point says for a held side; null for any other kind. */
+export function heldWhy(path, kind) {
+  if (kind === 'mixed') return `${path} is both an MCP client configuration and a tool manifest; it is not read or sent — split the server list and the tool manifest into separate files.`;
+  if (kind === 'unparseable') return `${path} does not parse as JSON; it is not read or sent — a client configuration may hold credentials. Make it valid JSON (no comments) to have it checked.`;
+  return null;
 }
 
 export function looksLikeContractPath(p) {
@@ -682,6 +712,67 @@ export async function findUnder(listDir, root, match, limits = LISTING_LIMITS) {
   return { found: null, complete: true };
 }
 
+// ---- what a host reads ahead of the decision ---------------------------------------------------
+
+/*
+ * 1.3.2 (2026-10-09, the CodeRifts mod, plugin 1.2.9): a host that cannot let this module call its
+ * readers (the Claude directory reads every `return` in a hook's text as the hook's answer, and every
+ * mods API call reached through a helper is listed "via" it) reads AHEAD instead: readPlan names every
+ * file and every listing root decideToolCall can ask for on this call, and pendingListings names the
+ * directories the walk under those roots can still ask for, given the listings already read. The host
+ * reads those, then passes decideToolCall an io that only looks the answers up. Pure: no I/O here.
+ */
+
+/**
+ * The reads decideToolCall can make for one call, from the same functions it decides with:
+ *   files  every path it can pass to io.readFile (verbatim)
+ *   roots  every listing root it can walk with io.listDir (findUnder's start, before normalizing)
+ * A superset: decideShell reads the named content-decided files of every target, and walks the
+ * scopes only when no target names a contract or a held file.
+ */
+export function readPlan(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') {
+    const files = [];
+    const roots = [];
+    const root = normalizePath(io.cwd || '');
+    for (const { target } of shellWrites(String(field(input, 'command') ?? ''))) {
+      const inTree = scopeInTree(target, io);
+      if (inTree === null) continue;
+      const type = inTree !== UNKNOWN && !/[*?]/.test(inTree) ? contractType(inTree, opts) : null;
+      if (type) {
+        if (MCP_JSON_BY_CONTENT.test(inTree)) files.push(root ? `${root}/${inTree}` : inTree);
+      } else {
+        roots.push(listingRoot(inTree));
+      }
+    }
+    return { files: [...new Set(files)], roots: [...new Set(roots)] };
+  }
+  if (!kind) return { files: [], roots: [] };
+  const filePath = filePathOf(input);
+  if (!filePath) return { files: [], roots: [] };
+  return contractType(relativePath(io.cwd, filePath), opts) ? { files: [filePath], roots: [] } : { files: [], roots: [] };
+}
+
+/**
+ * The directories the walk under `roots` can still ask for, given `listings` ({ dir: entries | null },
+ * the one-level answers already read, keyed as findUnder asks for them). The walk is findUnder itself,
+ * never stopping at a match, within the same limits — so the directories decideToolCall's walk asks
+ * for are a subset of what this keeps naming until it names none.
+ */
+export async function pendingListings(roots, listings = {}, limits = LISTING_LIMITS) {
+  const missing = new Set();
+  const listDir = async (dir) => {
+    if (Object.prototype.hasOwnProperty.call(listings, dir)) return listings[dir];
+    missing.add(dir);
+    return null;
+  };
+  for (const r of roots || []) await findUnder(listDir, r, () => false, limits);
+  return [...missing];
+}
+
 // ---- the decision ------------------------------------------------------------------------------
 
 /**
@@ -720,10 +811,16 @@ export async function decideToolCall(call, io = {}) {
   } 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)})` };
   }
+  // 1.3.1 (P65d): a held side ('mixed', 'unparseable') — the file on disk, or the text the call writes —
+  // is not sent and not passed: the hooks ask, with the sentence. Nothing of it is in the answer.
+  const heldBefore = mcpJsonContentKind(rel, before);
+  if (heldBefore === 'mixed' || heldBefore === 'unparseable') return held(rel, type, heldBefore);
   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` };
   }
+  const heldAfter = mcpJsonContentKind(rel, after);
+  if (heldAfter === 'mixed' || heldAfter === 'unparseable') return held(rel, type, heldAfter);
   // 1.3.0 (P65c): a plain mcp.json is decided by content, here, before anything is sent. A side that is
   // a client configuration counts as no file: both such → pass; one → the manifest added or removed.
   const clientBefore = isClientConfigContent(rel, before);
@@ -737,14 +834,22 @@ export async function decideToolCall(call, io = {}) {
   return { action: 'gate', path: filePath, rel, type, before, after };
 }
 
-/** A shell write to a plain mcp.json that is a client configuration on disk is not a contract write. */
-async function clientConfigOnDisk(rel, io) {
-  if (!MCP_JSON_BY_CONTENT.test(rel) || !io.readFile) return false;
+/** The answer for a held side: ask, with the sentence; no text of the file. */
+function held(rel, type, kind) {
+  return { action: 'ask', reason: 'mcp_json_held', rel, type, kind, scopes: [rel], why: heldWhy(rel, kind) };
+}
+
+/**
+ * The content kind of a plain mcp.json on disk, for a shell write that names it (null: not content-
+ * decided, missing, or unreadable — those stay the contract write they were).
+ */
+async function contentKindOnDisk(rel, io) {
+  if (!MCP_JSON_BY_CONTENT.test(rel) || !io.readFile) return null;
   const root = normalizePath(io.cwd || '');
   try {
-    return isClientConfigContent(rel, await io.readFile(root ? `${root}/${rel}` : rel));
+    return mcpJsonContentKind(rel, await io.readFile(root ? `${root}/${rel}` : rel));
   } catch {
-    return false;
+    return null;
   }
 }
 
@@ -770,12 +875,16 @@ async function mayHoldContract(scope, io, opts) {
 
 async function decideShell(command, io, opts) {
   const named = [];
+  const heldPaths = [];
   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 && await clientConfigOnDisk(inTree, io)) continue;
+    const onDisk = type ? await contentKindOnDisk(inTree, io) : null;
+    if (onDisk === 'client_config') continue;
+    // 1.3.1 (P65d): a held file on disk is not a contract write to refuse, and not a pass: ask.
+    if (onDisk === 'mixed' || onDisk === 'unparseable') { heldPaths.push({ rel: inTree, kind: onDisk }); continue; }
     if (type) named.push({ path: target, type, by });
     else scopes.set(inTree, [...(scopes.get(inTree) || []), by]);
   }
@@ -787,6 +896,15 @@ async function decideShell(command, io, opts) {
       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`,
     };
   }
+  if (heldPaths.length) {
+    return {
+      action: 'ask',
+      reason: 'mcp_json_held',
+      kind: heldPaths[0].kind,
+      scopes: heldPaths.map((h) => h.rel),
+      why: heldPaths.map((h) => heldWhy(h.rel, h.kind)).join(' '),
+    };
+  }
   const reached = [];
   for (const [scope, bys] of scopes) {
     if (await mayHoldContract(scope, io, opts)) reached.push({ scope, by: [...new Set(bys)] });

package/entry-guard.mjs

@@ -0,0 +1,19 @@
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Whether `moduleUrl` is the process entry.
+ *
+ * Node sets `import.meta.url` to the real path of the module and leaves
+ * `process.argv[1]` as the path it was invoked with. Both sides are realpath'd.
+ * No argv, no module URL, or a realpath that throws → true (the entry runs).
+ * A resolved path that is a different file → false (this module was imported).
+ */
+export function invokedDirectly(argv1, moduleUrl) {
+  if (!argv1 || !moduleUrl) return true;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return true;
+  }
+}

package/gate.js

@@ -11,7 +11,7 @@ import { isAbsolute, resolve } from "node:path";
 // 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, isClientConfigContent, toolKind } from "./contract-write.mjs";
+import { contractType, decideToolCall, heldWhy, isClientConfigContent, mcpJsonContentKind, toolKind } from "./contract-write.mjs";
 
 /** Tools whose params carry a path and a new file body. */
 export const DEFAULT_TOOL_SHAPES = Object.freeze({
@@ -264,6 +264,9 @@ async function defaultListDir(dir) {
 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;
+  // 0.3.4 (P65d): a plain mcp.json that is both a client configuration and a tool manifest, or that does
+  // not parse — contract-write's 'mcp_json_held'. Not sent, not passed: the user is asked, with its sentence.
+  if (d.reason === "mcp_json_held") return ask("CodeRifts gate: this mcp.json is not checked", d.why);
   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.`);
   }
@@ -327,6 +330,10 @@ export function createGate(config = {}, deps = {}) {
     // 0.3.3 (P65c): a plain mcp.json is decided by its content (contract-write's function), as on the
     // Claude Code path. A side that is an MCP client configuration counts as no file and is never sent;
     // both such sides → this gate never claimed the call.
+    // 0.3.4 (P65d): a held side ('mixed' / 'unparseable') is never sent and not passed: ask, with the sentence.
+    const heldKind = [before, after].map((t) => mcpJsonContentKind(target.path, t)).find((k) => k === "mixed" || k === "unparseable");
+    if (heldKind) return ask("CodeRifts gate: this mcp.json is not checked", heldWhy(target.path, heldKind));
+
     const clientBefore = isClientConfigContent(target.path, before);
     const clientAfter = isClientConfigContent(target.path, after);
     const sentBefore = clientBefore ? "" : before;

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.3.3",
+  "version": "0.3.5",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coderifts/agent-hooks",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "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",
@@ -15,6 +15,7 @@
   "main": "./index.js",
   "files": [
     "index.js",
+    "entry-guard.mjs",
     "gate.js",
     "contract-write.mjs",
     "openclaw.plugin.json",