ruvnet-brain 4.3.20 → 4.3.25

package/plugin/hooks/codex-hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. SessionStart restores the canonical project checkpoint and Stop invokes only the project-scoped, explicitly authorized continuation gate; both are bounded and fail open.",
+  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps only the pre-existing, project-scoped continuation gate. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 §Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on — that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered — today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses.",
   "hooks": {
     "SessionStart": [
       {
@@ -20,10 +20,73 @@
             "type": "command",
             "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 continuation-gate",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 grounding-turn-gate",
+            "timeout": 10
           }
         ],
         "matcher": "*"
       }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit|apply_patch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 6500 decision-gate write",
+            "timeout": 8
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(?:.*__)?search_ruvnet$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 4500 grounding-stamp",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 2500 unprompted-speech UserPromptSubmit",
+            "timeout": 3
+          },
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 ground-ruvnet",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 4500 grounding-turn-mark",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 session-snapshot SessionEnd",
+            "timeout": 10
+          }
+        ]
+      }
     ]
   }
 }

package/plugin/hooks/hook-contracts.json

@@ -1,22 +1,280 @@
 {
-  "_note": "The legacy automatic gate collection remains retired. Exactly two continuity handlers are permitted: SessionStart restores canonical project progression; Stop may nudge one explicitly authorized, project-scoped objective. No other Brain hook may be registered.",
-  "_version": 3,
+  "_note": "The legacy automatic gate collection remains retired. What is permitted is the continuity plane below and nothing else: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint; Stop may nudge one explicitly authorized project-scoped objective AND capture a project snapshot; PreCompact and SessionEnd capture a project snapshot. Version 3 of this file permitted exactly two handlers, which was not a safety property but a contradiction: it demanded a restore while forbidding any event that could WRITE the journal the restore reads, so the canonical store held zero progression rows. Adding to this list is still a deliberate act that must pass `npm run hooks:check`; what changed is that the shape can now express the plane that actually works. Amended 2026-09-11 (Stuart): the continuity-only charter had retired the ONLY enforcement of ADR-0012 — never write rUv-product code the brain has not seen — and the failure it exists to prevent recurred the day it was measured absent. The plane now also carries three grounding registrations: ground-ruvnet (UserPromptSubmit, grounding injection — a second owner of that event, scoped by ADR-040 §Amendment 2026-09-11 to directives rather than speech), decision-gate’s write route (PreToolUse, the one refuser, ADR-067), and grounding-stamp (PostToolUse on a successful search_ruvnet, the receipt that opens the write gate). Amended 2026-09-12: the 2026-09-11 claim that Codex PreToolUse/PostToolUse delivery had never been observed was measured with a prompt that never invoked a tool (`codex exec \"reply OK\"`), so it was an untested path, not a failing one. Re-measured with prompts that actually call a tool (a real apply_patch write, a real MCP search_ruvnet call against this repo's own server): both events FIRED on codex-cli 0.154.0 with real payloads. decision-gate's write route and grounding-stamp are now dual-host (see _codexCapture and contracts below); the bash route (exec_command) remains Claude-only — today's measurement did not exercise it. Also amended 2026-09-12: added grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — ground-ruvnet's Gate 1 directive is advisory, so nothing previously checked whether the model complied before the turn ended. grounding-turn-mark records that Gate 1 fired for a turn; grounding-turn-gate forces continuation at Stop if grounding-stamp's own evidence shows no search_ruvnet call happened since. Both dual-host from the start (the Stop-block contract is already proven on Codex via continuation-gate).",
+  "_version": 7,
+  "_eventOwners": [
+    {
+      "event": "SessionStart",
+      "owner": "session-start",
+      "class": "continuity recovery",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Restore the newest coherent committed checkpoint. Reads only; ADR-073 §5 forbids replaying the outbox here because replay is a write and a write costs more than this boundary's whole budget."
+    },
+    {
+      "event": "UserPromptSubmit",
+      "owner": "unprompted-speech",
+      "class": "advisory delivery",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "The sole writer of unprompted user-facing bytes (ADR-040 / DDD-0004). Producers run as candidates behind it; it alone applies policy and writes the envelope."
+    },
+    {
+      "event": "Stop",
+      "owner": "continuation-gate",
+      "class": "continuation nudge",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "May request one continuation for one explicitly authorized, project-scoped objective read from the user's own work ledger (ADR-043). Never a refusal, never a second task store."
+    },
+    {
+      "event": "Stop",
+      "owner": "session-snapshot",
+      "class": "continuity capture",
+      "hosts": [
+        "claude"
+      ],
+      "responsibility": "Append one project snapshot to the canonical store and commit any outbox debt a previously interrupted session left behind."
+    },
+    {
+      "event": "PreCompact",
+      "owner": "session-snapshot",
+      "class": "continuity capture",
+      "hosts": [
+        "claude"
+      ],
+      "responsibility": "The boundary at which context is about to be lost — capture before it is."
+    },
+    {
+      "event": "SessionEnd",
+      "owner": "session-snapshot",
+      "class": "continuity capture",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "The boundary at which the session is about to be gone — capture before it is."
+    },
+    {
+      "event": "UserPromptSubmit",
+      "owner": "ground-ruvnet",
+      "class": "grounding injection",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Injects a grounding directive into the model’s context when the prompt names the rUv stack, reaches for a classical default, or asks to build: call search_ruvnet before you assert. Not speech — emits no advocacy, promotion, lesson or alarm and reads no dial; silenced by the brain switch (ADR-054); scoped by ADR-040 §Amendment 2026-09-11."
+    },
+    {
+      "event": "PreToolUse",
+      "owner": "decision-gate",
+      "class": "consequential-action authorization",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "The ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067): composes protect-state, hijack-ruvnet, ground-before-write (ADR-0012) and adr-currency into one decision with one reason. Fails open on its own errors. apply_patch is Codex's raw write-tool name, added to the shared matcher 2026-09-12 after a real apply_patch call was measured to fire PreToolUse live (codex-cli 0.154.0); codex-hook-adapter.mjs normalizes it to the same Edit shape decision-gate.mjs's policies already read on Claude."
+    },
+    {
+      "event": "PostToolUse",
+      "owner": "grounding-stamp",
+      "class": "grounding receipt",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "After a SUCCESSFUL search_ruvnet, records which rUv products were consulted (a 24h stamp per term named in the query). It is the key that opens ground-before-write; without it the write gate would refuse every rUv-product write forever. Extended to Codex 2026-09-12: a real MCP search_ruvnet call fired PostToolUse with tool_name mcp__ruvnet_brain__search_ruvnet, which the existing matcher already recognized unchanged."
+    },
+    {
+      "event": "UserPromptSubmit",
+      "owner": "grounding-turn-mark",
+      "class": "grounding turn marker",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "Records that ground-ruvnet's Gate 1 (the same regex, proven byte-identical by test) matched this turn's prompt, so grounding-turn-gate has something to check at Stop — Stop's own payload carries no prompt text. Writes only a marker file under ~/.cache/ruvnet-brain/grounding-turn/; never blocks, never speaks to the model."
+    },
+    {
+      "event": "Stop",
+      "owner": "grounding-turn-gate",
+      "class": "answered-without-search enforcement",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "responsibility": "The 'answered without searching' gate (2026-09-12): if grounding-turn-mark's marker shows Gate 1 fired this turn and grounding-stamp's own stamp evidence shows no search_ruvnet call happened since, forces continuation via the same hookSpecificOutput.additionalContext contract continuation-gate already uses on both hosts. A separate registration from continuation-gate — see grounding-turn-gate.mjs's header for why folding it into that file's ledger/cooldown semantics would corrupt them rather than extend them. Consumes its marker unconditionally so a stale one can never pressure an unrelated later turn."
+    }
+  ],
+  "_notInThisPlane": [
+    {
+      "id": "decision-gate (bash route)",
+      "class": "consequential-action authorization",
+      "adr": "ADR-067",
+      "reachability": "The bash sub-event (protect-state, identifier-preflight, spend-guard, degradation-watch, hijack-ruvnet, design-wall) stays reachable through hook-shim.mjs by explicit invocation and is not registered: the 2026-09-11 mandate was the WRITE path (ADR-0012), and no host has proven PreToolUse delivery for Bash under the plane’s measured-not-assumed rule. The write route IS in the plane — see contracts."
+    },
+    {
+      "id": "execution-policy",
+      "class": "consequential-action authorization",
+      "adr": "ADR-075",
+      "reachability": "Reachable through `npm run execution-policy:check` and scripts/execution-policy.mjs at the host's consequential-execution boundary. It is an authorization decision point, not an automatic lifecycle registration."
+    }
+  ],
+  "_codexCapture": {
+    "state": "partial",
+    "measuredOn": "2026-09-12",
+    "host": "codex-cli 0.154.0",
+    "method": "2026-09-11: a probe hook was registered in a temporary CODEX_HOME on all twelve event names the installed binary declares, and a real `codex exec \"reply OK\"` was run against it — a prompt that never invokes a tool. 2026-09-12: re-probed with prompts that DO invoke a tool — a real apply_patch write, and a real MCP call to this repo's own plugin/mcp/server.mjs registered as `search_ruvnet` in the probe's CODEX_HOME config.toml.",
+    "fired": [
+      "SessionStart",
+      "UserPromptSubmit",
+      "SessionEnd",
+      "PreToolUse (apply_patch write; tool_input.command carried the raw patch)",
+      "PostToolUse (apply_patch write; tool_response = \"Exit code: 0 … Success. Updated the following files: A <path>\")",
+      "PreToolUse (MCP search_ruvnet; tool_name mcp__ruvnet_brain__search_ruvnet, tool_input.query preserved verbatim)",
+      "PostToolUse (MCP search_ruvnet; tool_response.content[0].text carried the \"Searched N RuvNet repos\" banner)"
+    ],
+    "notObserved": {
+      "Stop": "The 2026-09-11 probe turn never completed, so run_turn_stop_hooks had no completion to fire on. The binary declares the event and StopCommandOutputWire, so this is not-proven rather than unsupported. Stop keeps only the pre-existing continuation gate; no capture handler was added to an event whose delivery has not been seen.",
+      "PreCompact": "A one-line turn never approaches a compaction threshold. The binary declares PreCompact and PreCompactCommandOutputWire. No capture handler registered."
+    },
+    "consequence": "Codex captures at SessionEnd only; Stop/PreCompact remain unproven and unregistered as above (unchanged by this measurement). PreToolUse/PostToolUse are now proven for a write (apply_patch) and an MCP tool call (search_ruvnet) specifically, and decision-gate's write route plus grounding-stamp are registered on Codex accordingly (see contracts below). Bash-class tool calls (exec_command) were not exercised by this measurement and remain unregistered — extending on unexercised evidence would repeat the exact mistake this record corrects."
+  },
   "contracts": [
     {
       "id": "session-start",
       "event": "SessionStart",
-      "hosts": ["claude", "codex"],
+      "hosts": [
+        "claude",
+        "codex"
+      ],
       "mode": "advisory",
       "offBehavior": "partial",
-      "matcher": "startup|resume|clear|compact|fork"
+      "matcher": "startup|resume|clear|compact|fork",
+      "timeout": 5
+    },
+    {
+      "id": "unprompted-speech",
+      "event": "UserPromptSubmit",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "blocking",
+      "offBehavior": "silence",
+      "matcher": "*",
+      "timeout": 3
     },
     {
       "id": "continuation-gate",
       "event": "Stop",
-      "hosts": ["claude", "codex"],
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "run",
+      "matcher": "*",
+      "timeout": 10
+    },
+    {
+      "id": "session-snapshot",
+      "event": "Stop",
+      "hosts": [
+        "claude"
+      ],
+      "mode": "advisory",
+      "offBehavior": "run",
+      "matcher": "*",
+      "timeout": 10
+    },
+    {
+      "id": "session-snapshot",
+      "event": "PreCompact",
+      "hosts": [
+        "claude"
+      ],
+      "mode": "advisory",
+      "offBehavior": "run",
+      "matcher": "*",
+      "timeout": 10
+    },
+    {
+      "id": "session-snapshot",
+      "event": "SessionEnd",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
       "mode": "advisory",
       "offBehavior": "run",
-      "matcher": "*"
+      "matcher": "*",
+      "timeout": 10
+    },
+    {
+      "id": "ground-ruvnet",
+      "event": "UserPromptSubmit",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "*",
+      "timeout": 10
+    },
+    {
+      "id": "decision-gate",
+      "event": "PreToolUse",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "blocking",
+      "offBehavior": "run",
+      "matcher": "^(Write|Edit|MultiEdit|NotebookEdit|apply_patch)$",
+      "timeout": 5
+    },
+    {
+      "id": "grounding-stamp",
+      "event": "PostToolUse",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "^(?:.*__)?search_ruvnet$",
+      "timeout": 5
+    },
+    {
+      "id": "grounding-turn-mark",
+      "event": "UserPromptSubmit",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "*",
+      "timeout": 5
+    },
+    {
+      "id": "grounding-turn-gate",
+      "event": "Stop",
+      "hosts": [
+        "claude",
+        "codex"
+      ],
+      "mode": "advisory",
+      "offBehavior": "silence",
+      "matcher": "*",
+      "timeout": 10
     }
   ],
   "matcherAllowlist": [
@@ -27,12 +285,47 @@
       "reason": "SessionStart is a lifecycle source matcher, not a tool matcher.",
       "retiredBy": "continuity-only lifecycle plane"
     },
+    {
+      "layer": "plugin",
+      "event": "UserPromptSubmit",
+      "matcher": "*",
+      "reason": "UserPromptSubmit is a prompt lifecycle event, not a tool matcher; the runtime is the sole writer of unprompted bytes (ADR-040/DDD-0004).",
+      "retiredBy": "continuity-only lifecycle plane"
+    },
     {
       "layer": "plugin",
       "event": "Stop",
       "matcher": "*",
       "reason": "Stop is a lifecycle event; wildcard is the host contract.",
       "retiredBy": "continuity-only lifecycle plane"
+    },
+    {
+      "layer": "plugin",
+      "event": "PreCompact",
+      "matcher": "*",
+      "reason": "PreCompact is a lifecycle event; wildcard is the host contract.",
+      "retiredBy": "continuity-only lifecycle plane"
+    },
+    {
+      "layer": "plugin",
+      "event": "SessionEnd",
+      "matcher": "*",
+      "reason": "SessionEnd is a lifecycle event; wildcard is the host contract.",
+      "retiredBy": "continuity-only lifecycle plane"
+    },
+    {
+      "layer": "plugin",
+      "event": "PreToolUse",
+      "matcher": "^(Write|Edit|MultiEdit|NotebookEdit|apply_patch)$",
+      "reason": "The write-class tools, anchored — the exact matcher ADR-067 shipped and hook-registry-lint’s matcher-semantics test models. Claude Code matchers are searches, so the anchors are load-bearing. apply_patch (Codex's raw write-tool name) was added 2026-09-12 after a real apply_patch call was measured to fire this event live on codex-cli 0.154.0 — a dead branch on Claude, which never names a tool apply_patch.",
+      "retiredBy": "not retired — registered 2026-09-11 (ADR-0012 / ADR-067, Stuart mandate); extended to Codex 2026-09-12"
+    },
+    {
+      "layer": "plugin",
+      "event": "PostToolUse",
+      "matcher": "^(?:.*__)?search_ruvnet$",
+      "reason": "The grounding tool with or without an MCP server prefix (mcp__plugin_ruvnet-brain_ruvnet-brain__search_ruvnet, or Codex's mcp__ruvnet_brain__search_ruvnet, measured live 2026-09-12). Only a successful search may mint a stamp; the body checks the result banner.",
+      "retiredBy": "not retired — registered 2026-09-11 (ADR-0012); Codex host proven reachable 2026-09-12, matcher unchanged"
     }
   ]
 }

package/plugin/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain continuity plane. The broad legacy grounding, routing, learning, and release interceptors remain retired. Only SessionStart project restoration and the ledger-scoped Stop continuation handler are automatic; both are advisory, bounded, and fail open.",
+  "description": "RuvNet Brain lifecycle plane. The broad legacy routing, learning, and release interceptors remain retired. What is automatic is exactly: SessionStart restores the canonical project checkpoint; UserPromptSubmit runs the single unprompted-speech chokepoint AND the ground-ruvnet grounding injection (a directive to the model, not speech — ADR-040 §Amendment 2026-09-11); PreToolUse runs decision-gate's write route, the ONE process that may refuse a Write/Edit/MultiEdit/NotebookEdit/apply_patch (ADR-067, composing ground-before-write per ADR-0012) — apply_patch is Codex's own write tool name, added 2026-09-12 once a real apply_patch call was measured to fire this event live (codex-hooks.json carries the matching Codex registration; this is a dead branch on Claude, which never names a tool apply_patch); PostToolUse on a successful search_ruvnet mints the grounding stamp that opens that gate; grounding-turn-mark (UserPromptSubmit) records that the grounding directive fired this turn, and grounding-turn-gate (Stop) forces continuation if no search_ruvnet call was recorded since — the \"answered without searching\" gate, added 2026-09-12 (a directive alone is advisory; nothing previously checked whether the model actually complied); Stop also runs the ledger-scoped continuation handler and captures a project snapshot; PreCompact and SessionEnd capture a project snapshot. Every capture is bounded and fails open; only decision-gate may block on exit code, and it fails open on its own errors — grounding-turn-gate and continuation-gate force continuation via the Stop stdout envelope instead, which is advisory in the shim's own mode table but still keeps the agent working.",
   "hooks": {
     "SessionStart": [
       {
@@ -13,6 +13,52 @@
         ]
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" unprompted-speech UserPromptSubmit",
+            "timeout": 3
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" ground-ruvnet || true",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" grounding-turn-mark || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit|NotebookEdit|apply_patch)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" decision-gate write",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(?:.*__)?search_ruvnet$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" grounding-stamp || true",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
     "Stop": [
       {
         "matcher": "*",
@@ -21,6 +67,40 @@
             "type": "command",
             "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" continuation-gate || true",
             "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-snapshot Stop || true",
+            "timeout": 10
+          },
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" grounding-turn-gate || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-snapshot PreCompact || true",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hook-shim.mjs\" session-snapshot SessionEnd || true",
+            "timeout": 10
           }
         ]
       }

package/plugin/mcp/server.mjs

@@ -59,6 +59,29 @@ const SEARCH_TOOL = {
     },
     required: ['query'],
   },
+  // ── WHY THIS TOOL IS DECLARED READ-ONLY ───────────────────────────────────────────────────────
+  // Its three siblings below (MANAGED_CLI_TOOLS) have carried annotations since they shipped; this
+  // one did not, and a host that must assume the worst therefore assumed it. Observed 2026-09-11:
+  // Claude Code's plan mode REFUSED search_ruvnet three times in one session ("Cannot call
+  // search_ruvnet while in plan mode") — so the one tool whose entire purpose is grounding a plan
+  // in rUv's real source was unavailable at exactly the moment a plan is written. An unannotated
+  // tool is not a neutral default; it is a claim of "may mutate", made by omission.
+  //
+  // The claim is checked, not asserted. Every write reachable from a search_ruvnet call was walked
+  // (kb/forge-mcp-all.mjs meterLog + markGroundingProven, kb/brain-alarm.mjs health.json,
+  // kb/telemetry-ping.mjs stamp/queue, and this file's refreshLease): all of them land under
+  // ~/.cache/ruvnet-brain — or $XDG_CACHE_HOME/ruvnet-brain — plus $RUVNET_BRAIN_STATE_DIR for the
+  // off-switch READ. Nothing is written into the user's project tree, nothing is deleted, and
+  // nothing outside this cache is touched; that property is not incidental, it is the fix issue #36
+  // (mamd69) landed after three writers had scattered hidden directories through project trees.
+  // Internal receipt/cache/telemetry writes under the user's cache dir are exactly what
+  // readOnlyHint is meant to tolerate — the hint is about the caller's world, not about whether the
+  // process ever calls write(2).
+  //
+  // idempotentHint: the same question over the same immutable corpus snapshot returns the same
+  // ranked documents — the cross-encoder is byte-for-byte deterministic for a fixed batch
+  // (evals/runs/2026-07-27-cross-encoder-pool-cap.md) and the pool order is stable by construction.
+  annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
 };
 const FALLBACK_TOOLS = [SEARCH_TOOL, ...MANAGED_CLI_TOOLS];