ruvnet-brain 4.0.36 → 4.2.2-dev

package/plugin/hooks/hook-contracts.json

@@ -1,5 +1,5 @@
 {
-  "_note": "OUT-OF-SHIM HOOK CONTRACTS (ADR-055 §6). The per-hook contract — event, matcher, layer, codeRoot, mode, offBehavior, failureBehavior, timeout, budgets, state, dependencies, reachesStrangers, owner — is carried NATIVELY by plugin/scripts/hook-shim.mjs's dispatch table for every shim-routed registration. Everything registered outside that table has nowhere to carry it, which is how the whole non-plugin two thirds of this machine's mesh ended up with no declared answer to 'what happens when the brain is off' (ADR-055 F14). This file is the other half: a checked-in contract for every registration this REPO owns but does not route through the shim. scripts/hook-registry.mjs reads both, and tests/unit/hook-registry-lint.test.mjs fails any repo-owned registration absent from both — so a new one cannot be added silently. SCOPE, deliberately: this file declares only registrations THIS repo owns (plugin/hooks/hooks.json and this project's .claude/settings.json). It does NOT declare contracts for the machine owner's ~/.claude/settings.json or for third-party plugins — those are not ours to specify, and inventing an offBehavior for someone else's hook would be exactly the fiction the lint exists to prevent. They stay visible as documented machine-local findings in the lint's expected-red block.",
+  "_note": "OUT-OF-SHIM HOOK CONTRACTS (ADR-055 \u00a76). The per-hook contract \u2014 event, matcher, layer, codeRoot, mode, offBehavior, failureBehavior, timeout, budgets, state, dependencies, reachesStrangers, owner \u2014 is carried NATIVELY by plugin/scripts/hook-shim.mjs's dispatch table for every shim-routed registration. Everything registered outside that table has nowhere to carry it, which is how the whole non-plugin two thirds of this machine's mesh ended up with no declared answer to 'what happens when the brain is off' (ADR-055 F14). This file is the other half: a checked-in contract for every registration this REPO owns but does not route through the shim. scripts/hook-registry.mjs reads both, and tests/unit/hook-registry-lint.test.mjs fails any repo-owned registration absent from both \u2014 so a new one cannot be added silently. SCOPE, deliberately: this file declares only registrations THIS repo owns (plugin/hooks/hooks.json and this project's .claude/settings.json). It does NOT declare contracts for the machine owner's ~/.claude/settings.json or for third-party plugins \u2014 those are not ours to specify, and inventing an offBehavior for someone else's hook would be exactly the fiction the lint exists to prevent. They stay visible as documented machine-local findings in the lint's expected-red block.",
   "_version": 1,
   "contracts": [
     {
@@ -10,44 +10,34 @@
       "commandIncludes": "version-bump-gate.sh",
       "mode": "blocking",
       "offBehavior": "run",
-      "offReason": "ADR-054's discriminator, applied literally: this is an HONESTY wall, not a retrieval feature. It refuses a commit that changes behaviour without bumping the version — the signal every user's updater reads. Nothing about that becomes acceptable because the owner switched the retrieval brain off, and the gate reads git state only: no corpus, no network, no brain.",
-      "failureBehavior": "fail-open — a crash or unparseable payload permits the command and records degraded health; malfunction is never a decision (ADR-055 §1.2)",
+      "offReason": "ADR-054's discriminator, applied literally: this is an HONESTY wall, not a retrieval feature. It refuses a commit that changes behaviour without bumping the version \u2014 the signal every user's updater reads. Nothing about that becomes acceptable because the owner switched the retrieval brain off, and the gate reads git state only: no corpus, no network, no brain.",
+      "failureBehavior": "fail-open \u2014 a crash or unparseable payload permits the command and records degraded health; malfunction is never a decision (ADR-055 \u00a71.2)",
       "timeoutSeconds": 5,
       "warmP95BudgetMs": 50,
       "coldBudgetMs": 500,
       "stdoutCapBytes": 4096,
-      "stateRead": ["git HEAD", "plugin/.claude-plugin/plugin.json"],
+      "stateRead": [
+        "git HEAD",
+        "plugin/.claude-plugin/plugin.json"
+      ],
       "stateWritten": [],
-      "dependencies": ["bash", "git"],
+      "dependencies": [
+        "bash",
+        "git"
+      ],
       "reachesStrangers": false,
-      "owner": "ruvnet-brain (this repo only — ADR-053; it enforces a rule that is true here and nowhere else)",
+      "owner": "ruvnet-brain (this repo only \u2014 ADR-053; it enforces a rule that is true here and nowhere else)",
       "note": "Project-scoped on purpose: it lived in the GLOBAL settings until 2026-07-14, taxing every Bash call in 34+ projects with a rule true in one."
     }
   ],
   "matcherAllowlist": [
-    {
-      "layer": "plugin",
-      "event": "PreToolUse",
-      "matcher": "Write|Edit|Bash",
-      "handler": "hijack-ruvnet.sh",
-      "reason": "UNANCHORED, known (ADR-055 F4). Claude Code SEARCHES the tool name, so this also selects MultiEdit, NotebookEdit, TodoWrite and BashOutput — an advisory hook firing on four tools nobody chose. Advisory, so the blast radius is wasted latency rather than a wrong refusal.",
-      "retiredBy": "ADR-055 build item 3 (four plane dispatchers) — registration changes are SHELL changes and item 2 (battery v2) must land first, so this is recorded, not fixed out of order."
-    },
     {
       "layer": "plugin",
       "event": "PreToolUse",
       "matcher": "Bash",
       "handler": "verify-interface.sh",
-      "reason": "UNANCHORED, known (ADR-055 F4/F12): also selects BashOutput. One of three blocking walls on the same event that each re-parse the same payload — the parse-once execution-guard is the real fix, not six anchor characters.",
-      "retiredBy": "ADR-055 build item 3 (execution-guard.mjs — ONE registration, ONE parse)"
-    },
-    {
-      "layer": "plugin",
-      "event": "PreToolUse",
-      "matcher": "Bash",
-      "handler": "design-wall.sh",
-      "reason": "UNANCHORED, known (ADR-055 F4/F12) — same pair as verify-interface above, same fix.",
-      "retiredBy": "ADR-055 build item 3 (execution-guard.mjs)"
+      "reason": "UNANCHORED, known (ADR-055 F4/F12): also selects BashOutput. One of three blocking walls on the same event that each re-parse the same payload \u2014 the parse-once execution-guard is the real fix, not six anchor characters.",
+      "retiredBy": "ADR-055 build item 3 (execution-guard.mjs \u2014 ONE registration, ONE parse)"
     },
     {
       "layer": "plugin",

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "POSIX Stable Spine (ADR-023): every hook routes through hook-shim.mjs, which resolves the active generation per invocation. Advisory hooks fail open; blocking hooks preserve their exit-code contract.",
+  "description": "POSIX Stable Spine (ADR-023): every hook routes through hook-shim.mjs, which resolves the active generation per invocation. Advisory hooks fail open. ADR-067: exactly ONE hook may refuse a given tool call \u2014 decision-gate.mjs composes every policy into one decision. TIMEOUTS ARE A CONTRACT, NOT A GUESS: both decision-gate PreToolUse entries declare 5s, and the gate self-caps at DEFAULT_BUDGET_MS=2000 + MIN_HEADROOM_MS=3000, which is EXACTLY 5000ms \u2014 the relationship is the point, not the numbers. They ran at 10s for six days and that was earned at the time: an audit on 2026-08-13 timed 14 runs in unrelated projects and SIX exceeded 5s (up to 5700ms, including a plain `ls -la` at 5109ms), and because the host KILLS an over-timeout hook and renders it as a FAILED PreToolUse HOOK, the gate was producing the \"ton of hook errors\" this plugin was reported for while refusing nothing. RE-MEASURED 2026-08-19, after the adr-currency two-pass fix landed: the same full shim+gate path now runs 405-438ms in a stranger project and 412-438ms in this repo \u2014 about 10x faster \u2014 so the 10s ceiling was no longer earned by any measurement, and a ceiling nobody needs is charged to the USER, who waits behind it on every single Write and Bash. A budget is widened by evidence and must be narrowed again when the evidence goes away. The number is asserted, not asserted-to: decision-gate.mjs exports DEFAULT_BUDGET_MS + MIN_HEADROOM_MS and tests/unit/decision-gate.test.mjs reads the timeout out of THIS file and goes red if the two stop fitting. Comment keys (_note and friends) must NOT be added to this file: ADR-055 F17 records that Codex's plugin parser rejects them.",
   "hooks": {
     "SessionStart": [
       {
@@ -59,36 +59,31 @@
     ],
     "PreToolUse": [
       {
-        "matcher": "Write|Edit|Bash",
+        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit)$",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" hijack-ruvnet || true",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" decision-gate write",
             "timeout": 5
           }
         ]
       },
       {
-        "matcher": "^(Task|Agent)$",
+        "matcher": "^Bash$",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" route-dispatch || true",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" decision-gate bash",
             "timeout": 5
           }
         ]
       },
       {
-        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit)$",
+        "matcher": "^(Task|Agent)$",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" ground-before-write || true",
-            "timeout": 5
-          },
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" protect-state",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" route-dispatch || true",
             "timeout": 5
           }
         ]
@@ -102,36 +97,6 @@
             "timeout": 5
           }
         ]
-      },
-      {
-        "matcher": "Bash",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" design-wall",
-            "timeout": 5
-          }
-        ]
-      },
-      {
-        "matcher": "^(Write|Edit|MultiEdit)$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech PreToolUse-write",
-            "timeout": 5
-          }
-        ]
-      },
-      {
-        "matcher": "^Bash$",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech PreToolUse-bash",
-            "timeout": 5
-          }
-        ]
       }
     ],
     "PostToolUse": [

package/plugin/mcp/server.mjs

@@ -33,6 +33,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import readline from 'node:readline';
+import { writeOwn as writeOwnReadiness } from '../scripts/mcp-readiness.mjs';
 import { callManagedCli, MANAGED_CLI_TOOLS } from './managed-cli-interface.mjs';
 
 const BRAIN_HOME = process.env.RUVNET_BRAIN_HOME || path.join(os.homedir(), '.cache', 'ruvnet-brain');
@@ -66,12 +67,16 @@ const clientOk = (id, result) => out({ jsonrpc: '2.0', id, result });
 const clientErr = (id, code, message) => out({ jsonrpc: '2.0', id, error: { code, message } });
 const readJSON = (f) => { try { return JSON.parse(fs.readFileSync(f, 'utf8')); } catch { return null; } };
 
+/**
+ * ISSUE #133 (second half). This used to write ONE shared file, last writer wins — so a second MCP
+ * shell's `degraded` overwrote this one's `ready`, and `--doctor` reported the state of whichever
+ * process wrote last as the state of the machine. A process now owns only its own record; the
+ * machine-level answer is DERIVED from the live ones by mcp-readiness.mjs. Same fix as everything
+ * else closed today: one producer per fact.
+ */
 function writeReadiness(value) {
   try {
-    fs.mkdirSync(BRAIN_HOME, { recursive: true });
-    const tmp = `${READINESS}.${process.pid}.${Date.now()}.tmp`;
-    fs.writeFileSync(tmp, `${JSON.stringify({ ...value, pid: process.pid, at: new Date().toISOString() })}\n`, { mode: 0o600 });
-    fs.renameSync(tmp, READINESS);
+    writeOwnReadiness(BRAIN_HOME, value);
   } catch (error) {
     console.error(`[ruvnet-brain] could not persist MCP readiness: ${error.message}`);
   }
@@ -194,11 +199,23 @@ async function ensureChild() {
         const waiter = c.pending.get(msg.id);
         if (waiter) { c.pending.delete(msg.id); waiter.resolve(msg); }
       });
-      proc.on('exit', () => {
+      proc.on('exit', (code, signal) => {
         if (child === c) child = null;
         for (const [, p] of c.pending) p.reject(new Error('brain worker exited'));
         c.pending.clear();
-        if (!c.intentionalStop) {
+        // A CLEAN EXIT IS NOT A CRASH (issue #133, the sibling of the #122 idle-exit fix).
+        //
+        // #122 gave the worker a 15-minute idle retirement so a quiet session stops holding 3-15GB.
+        // It exits deliberately, with process.exit(0). This handler only knew about
+        // `intentionalStop`, which the PARENT sets when IT kills the child — so the worker retiring
+        // ITSELF was recorded as `degraded / worker-exit … exited unexpectedly`, and --doctor then
+        // exited 1 on a machine where nothing was wrong and the next search would respawn it by
+        // design. A fix that frees memory should not make the product report itself broken.
+        //
+        // Exit 0 with no signal is a deliberate stop — the idle retirement, or stdin EOF when the
+        // host goes away. A crash carries a non-zero code or a signal, and still degrades.
+        const cleanExit = code === 0 && !signal;
+        if (!c.intentionalStop && !cleanExit) {
           writeReadiness({
             state: 'degraded', phase: 'worker-exit', generation: c.generation,
             elapsedMs: Date.now() - startedAt, retryable: true,

package/plugin/scripts/adr-currency-gate.mjs

@@ -0,0 +1,150 @@
+/**
+ * adr-currency-gate.mjs — the ADR check, moved from the LAST possible moment to the FIRST.
+ *
+ * WHAT HAPPENED, 2026-08-13. Three commits touched code governed by ADR-055, 065, 066 and 067. All
+ * four ADRs were left describing a world the code had left. The pre-push gate caught it and refused
+ * — correctly, and it is a good gate. But look at WHEN: after the files were written, after three
+ * commits, after I had moved on. By then the work read as a toll booth, and my own words for it were
+ * "real work I skipped". The owner quoted that line back at me as the exhibit, and he was right to.
+ *
+ * A gate at push time cannot shape the work; it can only penalise it afterwards. Worse, it TRAINS
+ * the behaviour it exists to stop — if the wall is at the end, the cheap move is always to run at it
+ * and let it sort you out. The instinct the owner keeps asking for is not something exhortation can
+ * install; it is what you get when the right action is the only action available at the moment of
+ * acting.
+ *
+ * SO THIS FIRES ON THE EDIT, AND IT REFUSES DEBT RATHER THAN CHANGE. It does NOT ask you to document
+ * an edit you have not made yet — that would be incoherent. It refuses to let you write MORE code
+ * governed by a document that is ALREADY stale from your last round. One unreconciled ADR is a
+ * conversation; four is the mess that shipped today.
+ *
+ * REUSED, NOT REIMPLEMENTED. Every verdict comes from `scripts/doc-currency.mjs` — the same
+ * `evaluateDoc`/`resolveGoverned` the pre-push gate calls. A second implementation of "is this ADR
+ * current" would be one fact restated in two places, which is the defect this repo has paid for at
+ * least five times (orgTotalApprox in two producers, seven store-root expressions, a hand-listed
+ * import graph in four fixtures, two ship-command definitions shipped disagreeing on day one).
+ *
+ * FAIL OPEN, ALWAYS. Not a git repo, unreadable doc, git unavailable, anything unexpected: ALLOW,
+ * silently. An adversarial review earlier today found a sibling hook turning a missing `sqlite3`
+ * into a confident claim that the memory store was corrupt. A gate that fabricates a reason is worse
+ * than no gate, because it spends the credibility every other gate is drawing on.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(HERE, '..', '..');
+
+/** States that mean "the code moved and nobody has reconciled the document since". */
+const STALE = new Set(['presumed-stale']);
+
+/**
+ * Which documents govern this file, and are they current?
+ *
+ * Only the ADRs that actually govern the edited path are evaluated — `evaluate()` walks 83 documents
+ * with git calls per document, which is fine for a pre-push gate and far too slow for something on
+ * the Write path. Same logic, narrower question.
+ */
+/**
+ * doc-currency lives OUTSIDE the payload, and that is correct rather than an oversight worked
+ * around. `plugin/` is what reaches a user (marketplace.json `"source": "./plugin"`), a user's
+ * install has no `docs/adr/`, and a gate about THIS repo's ADRs has nothing to say there. A static
+ * `import('../../scripts/doc-currency.mjs')` would have shipped a specifier that resolves only in a
+ * checkout and throws ERR_MODULE_NOT_FOUND on every real install — the exact defect ADR-065 exists
+ * to stop, which `payload-self-contained.test.mjs` caught in the very commit citing ADR-065.
+ *
+ * So the dependency is resolved at runtime and its ABSENCE IS A CLEAN SKIP, not an error: outside a
+ * checkout this gate simply has no opinion.
+ */
+async function loadDocCurrency(root) {
+  const p = path.join(root, 'scripts', 'doc-currency.mjs');
+  if (!fs.existsSync(p)) return null;
+  try { return await import(pathToFileURL(p).href); } catch { return null; }
+}
+
+export async function staleGovernorsOf(relPath, { root = REPO, docCurrency = null, readFile = null } = {}) {
+  const mod = docCurrency ?? await loadDocCurrency(root);
+  if (!mod) return [];
+  const { listDocs, evaluateDoc, parseFrontmatter, DEFAULT_DIRS, isGitRepo } = mod;
+  // `readFile` is injectable for one reason, and it is not tidiness: with `fs.readFileSync` hardcoded
+  // here, a test that injects `listDocs`/`parseFrontmatter` never reaches them — the read throws on a
+  // fixture path that does not exist, the loop `continue`s, and NO CANDIDATE IS EVER FOUND. The first
+  // mutation run of this file reported "STALE ADR -> DID NOT FIRE", while all three allow-cases
+  // passed. A suite of only allow-cases would have shipped this green and unfireable, which is the
+  // exact defect class this repo has now hit four times in one day.
+  const read = readFile ?? ((p) => fs.readFileSync(p, 'utf8'));
+  if (!isGitRepo(root)) return [];
+
+  // TWO PASSES, AND THE ORDER IS THE WHOLE DESIGN. Measured before writing it, not after:
+  // `evaluateDoc` costs ~190-240ms because it shells out to git, and there are 83 documents — a
+  // naive loop is ~19 SECONDS on the Write path, which would make this the gate everybody disables.
+  // Reading frontmatter for all 83 costs 40ms total. So: cheap pass to find WHICH documents govern
+  // this file (usually one), expensive pass on only those. ~250ms typical, and exactly 40ms for the
+  // overwhelmingly common case of a file no ADR governs.
+  const candidates = [];
+  for (const docRel of listDocs(root, DEFAULT_DIRS)) {
+    let fm;
+    try { fm = parseFrontmatter(read(path.join(root, docRel))); } catch { continue; }
+    const governs = fm?.keys?.governs;
+    if (!Array.isArray(governs)) continue;
+    // Entries are exact paths or directory prefixes, read the way the pre-push gate reads them.
+    const governsThis = governs.some((p) => typeof p === 'string'
+      && (relPath === p || relPath.startsWith(p.endsWith('/') ? p : `${p}/`)));
+    if (governsThis) candidates.push({ docRel, id: fm?.keys?.id ?? path.basename(docRel) });
+  }
+  if (!candidates.length) return [];
+
+  const out = [];
+  for (const c of candidates) {
+    let doc;
+    try { doc = evaluateDoc(root, c.docRel); } catch { continue; }
+    if (STALE.has(doc?.drift?.state)) out.push({ doc: c.docRel, id: c.id, why: doc?.drift?.why ?? '' });
+  }
+  return out;
+}
+
+export function refusalText(relPath, stale) {
+  const names = stale.map((s) => `${s.id} (${s.doc})`).join('\n           ');
+  return `⛔ BLOCKED — ${relPath} is governed by a document that is ALREADY stale.
+
+  stale:   ${names}
+
+Reconcile it BEFORE writing more of what it governs. Not because the rule says so, but because
+this is the moment the reconciliation is cheap: you still remember what changed and why. On
+2026-08-13 four ADRs went stale together and the pre-push gate caught them after three commits,
+when the work read as a toll booth and got called "real work I skipped".
+
+  1. add a Currency-log row to the document: what changed, and why, with referents
+  2. \`node scripts/doc-currency.mjs --fix\` backfills only the dates git can prove
+  3. status, and every claim in the row, is yours to make — no script may write it
+
+An ADR describing a world the code left is worse than no ADR: the next reader trusts it.`;
+}
+
+const isMain = (() => {
+  try { return process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url); }
+  catch { return false; }
+})();
+
+if (isMain) {
+  // Every failure path below ALLOWS. This gate may never be the reason work cannot proceed for a
+  // reason it cannot explain.
+  let allow = 0;
+  try {
+    const payload = fs.readFileSync(0, 'utf8');
+    const input = JSON.parse(payload)?.tool_input ?? {};
+    const file = input.file_path || input.path || '';
+    if (!file) process.exit(allow);
+    const rel = path.relative(REPO, path.resolve(file));
+    // Edits OUTSIDE the repo, and edits to the documents themselves, are never blocked — the second
+    // exemption is essential: reconciling a stale ADR must not be refused by the staleness it fixes.
+    if (rel.startsWith('..') || rel.startsWith('docs/')) process.exit(allow);
+    const stale = await staleGovernorsOf(rel);
+    if (!stale.length) process.exit(allow);
+    process.stderr.write(`${refusalText(rel, stale)}\n`);
+    process.exit(2);
+  } catch {
+    process.exit(allow);
+  }
+}

package/plugin/scripts/capability-registry.mjs

@@ -244,13 +244,22 @@ function lineCount(file) {
  */
 export function dispatchGateWiring({ repo = REPO, home = HOME } = {}) {
   const PREIMAGE = new Set(['plugin', 'marketplace-clone']);
+  // 'codex' joined hook-registry.mjs's mesh 2026-08-20 (Dream Cycle cross-host-conformance) so M1/
+  // M3/M5/M6 could see codex-hooks.json — but this function asks a CLAUDE CODE question ("is a
+  // PreToolUse gate on subagent dispatch wired to the cheap-model router" for THIS session), and
+  // Claude Code never loads codex-hooks.json under any circumstance. Without this exclusion, a
+  // resolved codex route-dispatch registration (now correctly matched to route-dispatch.sh via the
+  // shared shim table) reported `wired: true` on a machine that had never installed Codex at all —
+  // caught by re-running this function before/after the hook-registry.mjs change.
+  const NOT_CLAUDE_CODE = new Set(['codex']);
   let records;
   try { records = buildRegistry({ repo, home }).records; }
   catch { return { wired: false, layer: null, unreadable: true }; }
   const hits = records.filter((r) => r.event === 'PreToolUse'
     && r.handler === 'route-dispatch.sh'
     && r.tools.some((t) => t === 'Task' || t === 'Agent' || t === '*')
-    && !PREIMAGE.has(r.layer));
+    && !PREIMAGE.has(r.layer)
+    && !NOT_CLAUDE_CODE.has(r.layer));
   const external = hits.find((r) => r.layer !== 'plugin-installed');
   if (external) return { wired: true, layer: external.layer, unreadable: false };
   const enabled = Object.entries(readJSON(path.join(home, '.claude/settings.json')).value?.enabledPlugins || {})

package/plugin/scripts/codex-hook-adapter.mjs

@@ -1,4 +1,32 @@
 #!/usr/bin/env node
+/**
+ * codex-hook-adapter.mjs — the host boundary. Codex payloads in, shared Brain hook bodies out, and
+ * Codex-VALID output back.
+ *
+ * THE OUTPUT CONTRACT IS NOT GUESSED. Every rule below was read out of the real host: the JSON
+ * schemas Codex 0.147.0 carries inside its own binary — `<event>.command.output`, extracted
+ * 2026-08-14 with `strings` from
+ * `~/.codex/packages/standalone/releases/0.147.0-aarch64-apple-darwin/bin/codex` — plus the host's
+ * own error strings. The three that shaped this file:
+ *
+ *   · "hook returned invalid post-tool-use JSON output"  — PostToolUse stdout is PARSED. Plain text
+ *     is a host error, not a message. signal-watch.mjs prints one advisory LINE on a failed
+ *     gh/vercel/npm command, which reached Codex as invalid JSON on every such command, and nothing
+ *     in this file wrapped it: the old envelope branch covered SessionStart and UserPromptSubmit
+ *     only. Measured before the fix: raw text passed straight through.
+ *   · The events that may carry `hookSpecificOutput.additionalContext` are exactly the ones with a
+ *     *HookSpecificOutputWire definition — PreToolUse, PostToolUse, PermissionRequest, SessionStart,
+ *     SubagentStart, UserPromptSubmit. `session-end.command.output` DOES NOT EXIST, and
+ *     pre-compact/post-compact/stop/subagent-stop have no additionalContext at all. So for those,
+ *     unparseable stdout is DROPPED. Wrapping it would trade a silent no-op for a host error.
+ *   · "PreToolUse hook returned unsupported permissionDecision:allow" / ":ask" — the wire enum has
+ *     three values and Codex accepts exactly one of them, `deny`. Anything else is stripped, which
+ *     is why the pre-existing `defer` strip is now a general rule rather than one special case.
+ *
+ * Exit-2-plus-stderr is the refusal channel on every blocking event ("PreToolUse hook exited with
+ * code 2 but did not write a blocking reason to stderr" is the host's complaint when the stderr half
+ * is missing), so a non-zero status is forwarded verbatim and never reinterpreted.
+ */
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
@@ -13,8 +41,27 @@ const event = String(input.hook_event_name || '');
 let adapted = false;
 const codexToolName = String(input.tool_name).toLowerCase();
 
+/**
+ * Events whose output schema defines a *HookSpecificOutputWire with `additionalContext`. Only these
+ * may carry a hook's prose back to the model.
+ */
+const CONTEXT_EVENTS = new Set([
+  'PreToolUse', 'PostToolUse', 'PermissionRequest', 'SessionStart', 'SubagentStart', 'UserPromptSubmit',
+]);
+
+/** Every file an apply_patch touches, in patch order. Codex patches are routinely multi-file. */
+export function patchFiles(patch) {
+  const out = [];
+  for (const m of String(patch || '').matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/gm)) {
+    const f = m[1].trim();
+    if (f && !out.includes(f)) out.push(f);
+  }
+  return out;
+}
+
 // Codex names these tools differently from the shared Claude hook contracts. Normalize at the
 // host boundary once so every existing safety/learning body sees the same typed event.
+let files = [];
 if (['exec_command', 'functions.exec_command', 'functions__exec_command'].includes(codexToolName)) {
   input.tool_name = 'Bash';
   input.tool_input = {
@@ -24,11 +71,11 @@ if (['exec_command', 'functions.exec_command', 'functions__exec_command'].includ
   adapted = true;
 } else if (codexToolName === 'apply_patch') {
   const patch = typeof input.tool_input?.command === 'string' ? input.tool_input.command : '';
-  const filePath = patch.match(/^\*\*\* (?:Add|Update|Delete) File: (.+)$/m)?.[1]?.trim() || '';
+  files = patchFiles(patch);
   input.tool_name = 'Edit';
   input.tool_input = {
     ...(input.tool_input || {}),
-    ...(filePath ? { file_path: filePath } : {}),
+    ...(files[0] ? { file_path: files[0] } : {}),
     new_string: patch,
   };
   adapted = true;
@@ -51,40 +98,95 @@ const env = {
   CLAUDE_PROJECT_DIR: String(input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd()),
   RUVNET_HOOK_HOST: 'codex',
 };
-const result = spawnSync(process.execPath, [shim, hookId, ...process.argv.slice(3)], {
-  input: hookInput,
-  encoding: 'utf8',
-  env,
+
+const runShim = (payload) => spawnSync(process.execPath, [shim, hookId, ...process.argv.slice(3)], {
+  input: payload, encoding: 'utf8', env,
 });
 
-if (result.status && result.stderr) process.stderr.write(result.stderr);
-if (result.status) process.exit(result.status);
+/**
+ * ONE PAYLOAD PER FILE for a multi-file patch.
+ *
+ * Every write policy on both hosts reads a single `tool_input.file_path` (protect-brain-state.sh
+ * line 56, ground-before-write.sh line 109, adr-currency-gate.mjs line 137). A Codex `apply_patch`
+ * carries N files in one call, so exposing only the first meant files 2..N were never shown to any
+ * wall — the same shape as every other defect in this area: the check exists and points one surface
+ * away from the failure.
+ *
+ * BOUNDED, because the wrapper SIGKILLs this process at its own budget and a kill is invisible. The
+ * wrapper hands its budget down; iteration stops at 75% of it and ALLOWS, which is decision-gate's
+ * own rule for a blown budget ("a blown budget ALLOWS and says nothing"): the gate's slowness must
+ * never be indistinguishable from the user doing something wrong.
+ */
+const BUDGET_MS = Number(process.env.RUVNET_CODEX_BUDGET_MS) || 0;
+const started = Date.now();
+const spent = () => Date.now() - started;
+
+const payloads = files.length > 1
+  ? files.map((file) => JSON.stringify({
+    ...input,
+    tool_input: { ...input.tool_input, file_path: file },
+  }))
+  : [hookInput];
 
-const stdout = result.stdout || '';
-if (!stdout) process.exit(0);
+const stdouts = [];
+for (const payload of payloads) {
+  const r = runShim(payload);
+  // A refusal (or any error) from ANY file is the decision for the whole patch, forwarded verbatim
+  // and immediately — there is nothing to compose once one wall has said no.
+  if (r.status && r.stderr) process.stderr.write(r.stderr);
+  if (r.status) process.exit(r.status);
+  if (r.stdout) stdouts.push(r.stdout);
+  if (BUDGET_MS && spent() > BUDGET_MS * 0.75) break;
+}
+
+if (!stdouts.length) process.exit(0);
+
+/** Merge N bodies' output into ONE value. Envelopes join by context; anything else joins as text. */
+function merge(outs) {
+  if (outs.length === 1) return outs[0];
+  const parsedAll = outs.map((s) => { try { return JSON.parse(s); } catch { return null; } });
+  const contexts = parsedAll.map((p) => p?.hookSpecificOutput?.additionalContext);
+  if (parsedAll.every((p) => p) && contexts.every((c) => typeof c === 'string')) {
+    const first = parsedAll[0];
+    return JSON.stringify({
+      ...first,
+      hookSpecificOutput: { ...first.hookSpecificOutput, additionalContext: contexts.join('\n') },
+    });
+  }
+  return outs.map((s) => s.trim()).filter(Boolean).join('\n');
+}
+
+const stdout = merge(stdouts);
 
 let parsed = null;
-try { parsed = JSON.parse(stdout); } catch { /* plain text is valid for some Codex events */ }
+try { parsed = JSON.parse(stdout); } catch { /* a shared body may legitimately print prose */ }
 
 if (event === 'Stop') {
   const reason = parsed?.hookSpecificOutput?.additionalContext
     || parsed?.reason
     || parsed?.stopReason;
+  // `stop.command.output` has no hookSpecificOutput; `decision: "block"` REQUIRES a non-empty
+  // `reason` ("Stop hook returned decision:block without a non-empty reason"). No reason ⇒ say
+  // nothing at all, which is the allow.
   if (reason) process.stdout.write(JSON.stringify({ decision: 'block', reason }));
   process.exit(0);
 }
 
-if ((event === 'SessionStart' || event === 'UserPromptSubmit') && !parsed) {
-  process.stdout.write(JSON.stringify({
-    hookSpecificOutput: {
-      hookEventName: event,
-      additionalContext: stdout,
-    },
-  }));
+if (!parsed) {
+  // Prose from a shared body. It is only deliverable on an event whose schema has somewhere to put
+  // it; everywhere else it is dropped rather than emitted as output the host will reject.
+  if (CONTEXT_EVENTS.has(event)) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: { hookEventName: event, additionalContext: stdout },
+    }));
+  }
   process.exit(0);
 }
 
-if (parsed?.hookSpecificOutput?.permissionDecision === 'defer') {
+// `deny` is the only permissionDecision Codex accepts; `allow`, `ask` and the shared bodies' own
+// `defer` are all rejected by name. Strip, then drop an envelope that has nothing left to say.
+const decision = parsed?.hookSpecificOutput?.permissionDecision;
+if (decision && decision !== 'deny') {
   delete parsed.hookSpecificOutput.permissionDecision;
   if (Object.keys(parsed.hookSpecificOutput).length === 1 && parsed.hookSpecificOutput.hookEventName) {
     delete parsed.hookSpecificOutput;