ruvnet-brain 4.5.10 → 4.5.11

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.10 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.10-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.5.11 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.5.11-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 

package/bin/install.mjs

@@ -4931,7 +4931,7 @@ export function syncManagedRouterTools({ routerDir = path.join(os.homedir(), '.c
   const destination = path.join(routerDir, 'bin');
   fs.mkdirSync(destination, { recursive: true });
   let copied = 0;
-  for (const name of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'subscription-hosts.mjs', 'review-model-defaults.mjs', 'dual-host-deliberation.mjs', 'dual-host-suggest.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'metaharness-router.mjs', 'model-router-dispatch.mjs', 'model-currency.mjs', 'model-currency-evidence.mjs', 'user-model-prompt-hook.mjs', 'model-router-agent-hook.mjs', 'model-weekly-assessment.mjs', 'model-weekly-analyst.mjs', 'model-weekly-cycle.mjs', 'model-weekly-qualification.mjs', 'model-native-qualification.mjs', 'model-routing-launchers.mjs', 'model-terminal-gateway.mjs', 'model-terminal-launchers.mjs', 'claude-terminal-mod.mjs', 'model-native-catalog.mjs', 'model-analyst-sandbox.mjs', 'model-routing-policy-promotion.mjs', 'model-routing-gateway.mjs', 'native-subscription-usage.mjs', 'codex-routed.sh', 'goldie-weekly.sh']) {
+  for (const name of ['model-router-engine.mjs', 'model-router-setup.mjs', 'model-router-status.mjs', 'model-router-outcome.mjs', 'subscription-hosts.mjs', 'review-model-defaults.mjs', 'dual-host-deliberation.mjs', 'dual-host-suggest.mjs', 'route-cheap.mjs', 'dispatch-receipt.mjs', 'metaharness-receipts.mjs', 'metaharness-router.mjs', 'model-router-dispatch.mjs', 'model-currency.mjs', 'model-currency-evidence.mjs', 'user-model-prompt-hook.mjs', 'model-router-agent-hook.mjs', 'model-weekly-assessment.mjs', 'model-weekly-analyst.mjs', 'model-weekly-cycle.mjs', 'model-weekly-qualification.mjs', 'model-native-qualification.mjs', 'model-routing-launchers.mjs', 'model-terminal-gateway.mjs', 'model-terminal-launchers.mjs', 'claude-terminal-mod.mjs', 'claude-controlled-terminal.mjs', 'model-native-catalog.mjs', 'model-analyst-sandbox.mjs', 'model-routing-policy-promotion.mjs', 'model-routing-gateway.mjs', 'native-subscription-usage.mjs', 'codex-routed.sh', 'goldie-weekly.sh']) {
     const source = path.join(packageRoot, 'scripts', name);
     if (!fs.existsSync(source)) throw new Error(`Packaged router tool missing: ${name}`);
     const target = path.join(destination, name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.5.10",
+  "version": "4.5.11",
   "description": "One-command installer for RuvNet Brain \u2014 a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {
@@ -41,6 +41,7 @@
     "metaharness:receipts": "node scripts/metaharness-receipts.mjs",
     "route:cheap": "node scripts/route-cheap.mjs",
     "routing:eval": "node scripts/model-routing-eval.mjs",
+    "routing:hooks:plan": "node scripts/user-model-hook-install.mjs --plan",
     "hooks:security-guidance:compat": "node scripts/security-guidance-codex-compat.mjs",
     "route:receipt": "node scripts/dispatch-receipt.mjs",
     "trismart": "node scripts/trismart.mjs",

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.5.10",
+  "version": "4.5.11",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.5.10",
+  "version": "4.5.11",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/scripts/claude-controlled-terminal.mjs

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// A controlled prompt boundary using native print/SDK controls, not the native terminal UI.
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { createInterface } from 'node:readline/promises';
+import { pathToFileURL } from 'node:url';
+import { StringDecoder } from 'node:string_decoder';
+import { decideNativeTurn, appendGatewayReceipt } from './model-routing-gateway.mjs';
+import { subscriptionEnvironment, assertSubscriptionAuth, validateDispatchDecision } from './model-router-dispatch.mjs';
+import { validateClaudeTerminalSettings } from './model-terminal-launchers.mjs';
+
+const REFUSED = 'Controlled Claude turn refused; no fallback.';
+const uuid = value => /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i.test(value || '');
+const cleanText = value => String(value).replace(/[\x00-\x08\x0b-\x1f\x7f-\x9f]/g, '');
+const allocationEnv = /^(CLAUDE_CODE_EXTRA_BODY|CLAUDE_CODE_EFFORT_LEVEL|ANTHROPIC_DEFAULT_.*_MODEL|ANTHROPIC_MODEL|ANTHROPIC_SMALL_FAST_MODEL|CLAUDE_CODE_SUBAGENT_MODEL|CLAUDE_CODE_PLUGIN_(DIRS|CACHE_DIR|SEED_DIR)|CLAUDE_CODE_USE_COWORK_PLUGINS)$/;
+
+/** Classic Brain hooks/MCP/skills remain loaded; native request-rewriting modules are refused. */
+export function assertClaudeModuleBoundary(settings, { env = process.env, sessionId, read = fs.readFileSync } = {}) {
+  if (!settings || typeof settings !== 'object' || Object.keys(settings.env || {}).some(key => allocationEnv.test(key))) throw new Error(REFUSED);
+  const modules = value => value && typeof value === 'object' && Object.entries(value).some(([key, entry]) =>
+    key === 'modules' && (Array.isArray(entry) ? entry.length > 0 : Boolean(entry)) || modules(entry));
+  if (modules(settings.hooks)) throw new Error(REFUSED);
+  const config = env.CLAUDE_CONFIG_DIR || path.join(env.HOME || os.homedir(), '.claude');
+  const json = file => JSON.parse(read(file, 'utf8'));
+  const enabled = Object.entries(settings.enabledPlugins || {}).filter(([, value]) => value !== false).map(([key]) => key);
+  let registry;
+  if (enabled.length) registry = json(path.join(config, 'plugins', 'installed_plugins.json'));
+  for (const id of enabled) {
+    const installations = registry.plugins?.[id];
+    if (!Array.isArray(installations) || !installations.length) throw new Error(REFUSED);
+    const at = id.lastIndexOf('@'), name = id.slice(0, at), marketplace = id.slice(at + 1);
+    if (at < 1) throw new Error(REFUSED);
+    const known = json(path.join(config, 'plugins', 'known_marketplaces.json'));
+    const marketplaceRoot = known[marketplace]?.installLocation;
+    if (!path.isAbsolute(marketplaceRoot || '')) throw new Error(REFUSED);
+    const entry = json(path.join(marketplaceRoot, '.claude-plugin', 'marketplace.json')).plugins?.find(plugin => plugin.name === name);
+    if (!entry || modules(entry)) throw new Error(REFUSED);
+    // Refuse any registered module-bearing installation of an enabled ID; never guess scope precedence.
+    for (const installation of installations) {
+      const root = installation.installPath;
+      if (!path.isAbsolute(root || '')) throw new Error(REFUSED);
+      const manifestFiles = [path.join(root, '.claude-plugin', 'plugin.json'), path.join(root, 'plugin.json')];
+      // Native strict:false marketplace entries may supply the entire manifest (e.g. LSP plugins).
+      const manifests = manifestFiles.filter(file => fs.existsSync(file)).map(json);
+      if (!manifests.length && entry.strict === false) manifests.push(entry);
+      if (!manifests.length || manifests.some(modules)) throw new Error(REFUSED);
+      const hooks = [path.join(root, 'hooks', 'hooks.json')];
+      for (const relative of [...manifests.map(manifest => manifest.hooks), entry.hooks].flat().filter(value => typeof value === 'string')) {
+        const resolved = path.resolve(root, relative);
+        if (!resolved.startsWith(root + path.sep)) throw new Error(REFUSED);
+        hooks.push(resolved);
+      }
+      for (const file of hooks) if (fs.existsSync(file) && modules(json(file))) throw new Error(REFUSED);
+    }
+  }
+  const nonempty = folder => fs.existsSync(folder) && fs.readdirSync(folder).length > 0;
+  // Native 2.1.289 rft()/b(sessionId): <config-dir>/dev-mods/<session-id>.
+  if (nonempty(path.join(config, 'dev-mods', sessionId))) throw new Error(REFUSED);
+  const projects = path.join(config, 'projects');
+  if (fs.existsSync(projects)) for (const directory of fs.readdirSync(projects)) {
+    const transcript = path.join(projects, directory, `${sessionId}.jsonl`);
+    if (!fs.existsSync(transcript)) continue;
+    // A resumed transcript may restore a different dev-mods folder (native last-wins record).
+    for (const line of read(transcript, 'utf8').split('\n').filter(Boolean)) {
+      const record = JSON.parse(line);
+      if (record.type === 'dev-mods' && record.folder && nonempty(record.folder)) throw new Error(REFUSED);
+    }
+  }
+}
+
+/** Retire only the directly owned process; never infer descendant cleanup from its exit. */
+export function retireControlledClaudeChild(child, { graceMs = 200, killMs = 200 } = {}) {
+  return new Promise(resolve => {
+    let finished = false, escalation, deadline;
+    const finish = () => {
+      if (finished) return;
+      finished = true; clearTimeout(escalation); clearTimeout(deadline);
+      child.removeListener('close', finish);
+      for (const stream of [child.stdin, child.stdout, child.stderr]) { stream?.removeAllListeners('data'); stream?.destroy(); }
+      child.unref?.(); resolve();
+    };
+    child.once('close', finish);
+    const kill = signal => { try { child.kill(signal); } catch { /* bounded cleanup still proceeds */ } };
+    escalation = setTimeout(() => kill('SIGKILL'), graceMs);
+    deadline = setTimeout(finish, graceMs + killMs);
+    kill('SIGTERM');
+    if (child.exitCode != null || child.signalCode != null) finish();
+  });
+}
+
+export function controlledClaudeArguments(decision, sessionId, resume = false) {
+  if (decision?.harness !== 'claude-code' || decision.provider !== 'anthropic' || decision.subscriptionCovered !== true ||
+      !/^claude-[a-z0-9][a-z0-9.-]*$/.test(decision.model || '') ||
+      !['low', 'medium', 'high', 'xhigh', 'max'].includes(decision.effort) || !uuid(sessionId)) throw new Error(REFUSED);
+  return ['--print', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose',
+    '--model', decision.model, '--effort', decision.effort, '--permission-mode', 'manual', '--permission-prompts', 'host',
+    '--permission-prompt-tool', 'stdio',
+    '--disallowedTools', 'Agent,Task',
+    resume ? '--resume' : '--session-id', sessionId];
+}
+
+/** One native process per routed turn. Permission requests require an explicit host answer. */
+export async function runControlledClaudeTurn({ binary, prompt, sessionId = crypto.randomUUID(), resume = false,
+  cwd = process.cwd(), env = process.env, decide = decideNativeTurn, verifyDecision = validateDispatchDecision,
+  checkSettings = validateClaudeTerminalSettings, checkAuth = assertSubscriptionAuth, spawnNative = spawn,
+  probe = execFileSync, approve = async () => false, output = () => {}, receipt = appendGatewayReceipt,
+  checkModules = assertClaudeModuleBoundary, signal, timeoutMs = 900000, handshakeMs = 10000 } = {}) {
+  if (!path.isAbsolute(binary || '') || typeof prompt !== 'string' || !prompt.trim() || prompt.length > 200000 ||
+      /^\s*\//.test(prompt) || !Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 900000 ||
+      !Number.isSafeInteger(handshakeMs) || handshakeMs <= 0 || handshakeMs > 30000 || signal?.aborted) throw new Error(REFUSED);
+  // Extra body / effort env overrides can bypass the native CLI's requested allocation.
+  if (Object.keys(env).some(key => allocationEnv.test(key))) throw new Error(REFUSED);
+  const clean = subscriptionEnvironment(env);
+  const managed = process.platform === 'darwin' ? '/Library/Application Support/ClaudeCode/managed-settings.json' : '/etc/claude-code/managed-settings.json';
+  if (fs.existsSync(managed)) throw new Error('Managed Claude settings require separate module-boundary qualification.');
+  checkSettings({ env: clean, cwd, home: env.HOME || os.homedir() });
+  checkAuth('claude-code', { env: clean, probe: (_name, args, options) => probe(binary, args, options) });
+  const decision = await decide(prompt, 'claude-code', { env: clean });
+  verifyDecision(decision);
+  const args = controlledClaudeArguments(decision, sessionId, resume);
+  if (signal?.aborted) throw new Error(REFUSED);
+  const child = spawnNative(binary, args, { cwd, env: clean, shell: false, stdio: ['pipe', 'pipe', 'pipe'] });
+  return new Promise((resolve, reject) => {
+    let done = false, phase = 'initialize', buffer = '', bytes = 0, result, observed = false, permissions = false;
+    const decoder = new StringDecoder('utf8');
+    const ids = { initialize: crypto.randomUUID(), before: crypto.randomUUID(), after: crypto.randomUUID() };
+    let handshake;
+    const timer = setTimeout(() => fail(), timeoutMs);
+    const abort = () => fail();
+    signal?.addEventListener('abort', abort, { once: true });
+    const clear = () => { clearTimeout(timer); clearTimeout(handshake); signal?.removeEventListener('abort', abort); };
+    const fail = () => {
+      if (done) return;
+      done = true; clear();
+      void retireControlledClaudeChild(child).then(() => reject(new Error(REFUSED)));
+    };
+    const send = message => { if (!done) child.stdin.write(JSON.stringify(message) + '\n'); };
+    const control = which => {
+      phase = which; clearTimeout(handshake); handshake = setTimeout(fail, handshakeMs);
+      send({ type: 'control_request', request_id: ids[which], request: { subtype: which === 'initialize' ? 'initialize' : 'get_settings' } });
+    };
+    const settingsMatch = value => value?.applied?.model === decision.model && value.applied.effort === decision.effort && !value.errors?.length &&
+      Array.isArray(value.sources) && !value.sources.some(source => source.source === 'policySettings' && Object.keys(source.settings || {}).length);
+    const onMessage = async message => {
+      if (done) return;
+      if (message.type === 'control_response') {
+        const response = message.response;
+        if (response?.request_id !== ids[phase] || response.subtype !== 'success') return fail();
+        if (phase === 'initialize') return control('before');
+        if (!settingsMatch(response.response)) return fail();
+        if (phase === 'before') {
+          clearTimeout(handshake); phase = 'turn';
+          checkModules(response.response.effective, { env: clean, sessionId });
+          verifyDecision(decision); // Allocation may have changed while native startup was running.
+          receipt({ ts: new Date().toISOString(), harness: 'claude-code', status: 'native-settings-observed',
+            model: decision.model, effort: decision.effort, taskClass: decision.taskClass, modelObserved: false,
+            evidence: 'get_settings applied model and effort before prompt; execution identity pending' }, { env: clean });
+          send({ type: 'user', session_id: sessionId, message: { role: 'user', content: prompt } });
+        } else if (phase === 'after') { checkModules(response.response.effective, { env: clean, sessionId }); phase = 'exit'; clearTimeout(handshake); child.stdin.end(); }
+        else fail();
+        return;
+      }
+      if (message.type === 'control_request') {
+        if (phase !== 'turn' || permissions || message.request?.subtype !== 'can_use_tool' || typeof message.request_id !== 'string') return fail();
+        if (['Agent', 'Task'].includes(message.request.tool_name)) return fail();
+        permissions = true;
+        let allowed = false;
+        try { allowed = await approve(message.request) === true; } catch { allowed = false; }
+        permissions = false;
+        send({ type: 'control_response', response: { subtype: 'success', request_id: message.request_id,
+          response: allowed ? { behavior: 'allow', updatedInput: message.request.input } :
+            { behavior: 'deny', message: 'The host did not approve this tool request.' } } });
+        return;
+      }
+      if (message.session_id && message.session_id !== sessionId) return fail();
+      if (message.type === 'assistant' && !message.parent_tool_use_id) {
+        if (phase !== 'turn' || message.message?.model !== decision.model) return fail();
+        observed = true;
+        for (const block of message.message.content || []) if (block.type === 'text') output(cleanText(block.text));
+      }
+      if (message.type === 'result') {
+        if (phase !== 'turn' || permissions || !observed || message.session_id !== sessionId || message.subtype !== 'success' ||
+            message.is_error || message.permission_denials?.length || message.errors?.length) return fail();
+        result = message; control('after');
+      }
+    };
+    child.stdout.on('data', chunk => {
+      if (done) return;
+      bytes += chunk.length; if (bytes > 16 * 1024 * 1024) return fail();
+      buffer += decoder.write(chunk);
+      let newline;
+      while ((newline = buffer.indexOf('\n')) !== -1 && !done) {
+        const line = buffer.slice(0, newline); buffer = buffer.slice(newline + 1);
+        try { void onMessage(JSON.parse(line)).catch(fail); } catch { fail(); }
+      }
+    });
+    child.stderr.on('data', () => {}); // Native diagnostics may contain credentials or prompt text.
+    child.stdin.on('error', fail); child.once('error', fail);
+    child.once('close', code => {
+      if (done) return;
+      if (code !== 0 || phase !== 'exit' || !result || buffer.trim() || decoder.end()) return fail();
+      try {
+        receipt({ ts: new Date().toISOString(), harness: 'claude-code', status: 'completed', model: decision.model,
+          effort: decision.effort, taskClass: decision.taskClass, modelObserved: true,
+          evidence: 'assistant model observed; get_settings applied effort matched before and after turn; per-request effort not exposed' }, { env: clean });
+        done = true; clear(); resolve({ sessionId, decision, modelObserved: true, effortSettingsObserved: true, perRequestEffortObserved: false });
+      } catch { fail(); }
+    });
+    control('initialize');
+  });
+}
+
+/** Native tool approvals are presented by this host; --print supplies no terminal dialogs. */
+export async function launchControlledClaudeTerminal({ binary, args = [], input = process.stdin, output = process.stdout,
+  diagnostics = process.stderr, env = process.env, cwd = process.cwd(), runTurn = runControlledClaudeTurn } = {}) {
+  let sessionId, resume = false, initialPrompt, ownerBypass = false;
+  const remaining = [...args];
+  const invalid = () => new Error('Controlled Claude accepts only --resume <session UUID>, --permission-mode bypassPermissions, and a literal initial prompt.');
+  while (remaining[0]?.startsWith('-')) {
+    if (remaining[0] === '--resume' && !resume && uuid(remaining[1])) {
+      sessionId = remaining[1]; resume = true;
+    } else if (remaining[0] === '--permission-mode' && !ownerBypass && remaining[1] === 'bypassPermissions') {
+      ownerBypass = true;
+    } else throw invalid();
+    remaining.splice(0, 2);
+  }
+  if (remaining.some(arg => typeof arg !== 'string' || arg.startsWith('-'))) throw invalid();
+  if (remaining.length) initialPrompt = remaining.join(' ');
+  if (!input.isTTY || !output.isTTY) throw new Error('Controlled Claude requires a person at a terminal for prompts and approvals.');
+  const terminal = createInterface({ input, output });
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  terminal.on('SIGINT', cancel);
+  diagnostics.write('Controlled Claude: one reviewed native allocation per prompt; tool approvals are answered here. Native Agent/Task workers are disabled; use the managed dispatcher for independent child work. /exit closes.\n');
+  if (ownerBypass) diagnostics.write('Owner permission bypass is active: native tool requests are approved by this host automatically. Agent/Task remain refused; routing and subscription guards remain active.\n');
+  try {
+    while (!controller.signal.aborted) {
+      const prompt = initialPrompt ?? await terminal.question('Claude> '); initialPrompt = undefined;
+      if (prompt.trim() === '/exit') break;
+      if (!prompt.trim()) continue;
+      const turn = await runTurn({ binary, prompt, sessionId, resume, cwd, env, signal: controller.signal,
+        output: text => output.write(text + '\n'), approve: async request => {
+          if (['Agent', 'Task'].includes(request.tool_name)) return false;
+          const details = cleanText(JSON.stringify({ tool: request.tool_name, input: request.input, reason: request.decision_reason }));
+          output.write(`Native permission request (untrusted tool text):\n${details}\n`);
+          if (ownerBypass) return true;
+          return (await terminal.question('Approve this tool request? Type yes: ')).trim() === 'yes';
+        } });
+      sessionId = turn.sessionId; resume = true;
+      diagnostics.write(`Native session: ${sessionId} (resume with --resume ${sessionId})\n`);
+    }
+  } finally { terminal.close(); }
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const args = process.argv.slice(2);
+  if (args[0] !== '--real-binary' || !args[1] || args[2] !== '--') {
+    process.stderr.write('Expected --real-binary /absolute/native/claude -- [--resume UUID]\n'); process.exitCode = 1;
+  } else launchControlledClaudeTerminal({ binary: args[1], args: args.slice(3) }).catch(() => {
+    process.stderr.write(REFUSED + '\n'); process.exitCode = 1;
+  });
+}

package/scripts/model-terminal-launchers.mjs

@@ -111,7 +111,7 @@ export function installTerminalLaunchers({ home = os.homedir(), nodeBinary = pro
     if ([runner, ...Object.keys(contents)].includes(binary)) throw new Error('Native terminal launcher recursion refused');
   }
   const receipt = { apply, launchers, configPath, config, shellSource, shellConflicts: shell.conflicts, backups: [],
-    claudeEnforcementScope: realClaude ? 'Startup hook activation guard; continuing native worker enforcement requires separate proof' : null };
+    claudeEnforcementScope: realClaude ? 'Controlled native prompt boundary; model observations and effective effort settings checked for each completed turn' : null };
   if (!apply) return receipt;
   for (const file of [configPath, ...Object.keys(contents), ...(manageZsh ? [shellSource, zshrc] : [])]) {
     const original = backup(file); if (original) receipt.backups.push(original);
@@ -226,18 +226,22 @@ export function validateClaudeTerminalArguments(args) {
   return { options, prompts };
 }
 
+function claudeAdministrativeArguments(args) {
+  const administrativeArgs = args[0] === '--permission-mode' && args[1] === 'bypassPermissions' ? args.slice(2) : args;
+  const information = new Set(['--help', '-h', '--version', '-v']);
+  const ownerPermissionFlags = new Set(['--dangerously-skip-permissions', '--allow-dangerously-skip-permissions']);
+  return administrativeArgs.some(arg => information.has(arg)) &&
+    administrativeArgs.every(arg => information.has(arg) || ownerPermissionFlags.has(arg)) ||
+    ['auth', 'mcp', 'plugin', 'plugins', 'update', 'upgrade', 'doctor', 'install'].includes(administrativeArgs[0]);
+}
+
 /** Native plugin startup only: an unloaded/crashed native worker may skip subsequent hooks. */
 export async function runClaudeTerminal({ config, args = [], env = process.env, startupMs = 10000,
   tempRoot = os.tmpdir(), cwd = process.cwd(), signalSource = process, diagnostics = process.stderr } = {}) {
   if (env.RNB_TERMINAL_LAUNCH_ACTIVE) throw new Error('Native terminal launcher recursion refused');
   if (!Number.isFinite(startupMs) || startupMs <= 0 || startupMs > 60000) throw new Error('Bounded native hook startup deadline required');
   const binary = executable(config.realClaude), clean = subscriptionEnvironment(env);
-  const information = new Set(['--help', '-h', '--version', '-v']);
-  const ownerPermissionFlags = new Set(['--dangerously-skip-permissions', '--allow-dangerously-skip-permissions']);
-  const administrative = args.some((arg) => information.has(arg)) &&
-    args.every((arg) => information.has(arg) || ownerPermissionFlags.has(arg)) ||
-    ['auth', 'mcp', 'plugin', 'plugins', 'update', 'upgrade', 'doctor', 'install'].includes(args[0]);
-  if (administrative) {
+  if (claudeAdministrativeArguments(args)) {
     const child = spawn(binary, args, { env: clean, cwd, stdio: 'inherit', shell: false });
     const unforward = forwardSignals(child, signalSource);
     try { return await exitOf(child); } finally { unforward(); }
@@ -280,8 +284,14 @@ export async function runClaudeTerminal({ config, args = [], env = process.env,
   }
 }
 
-export async function runTerminalLauncher({ host, args, config, env = process.env, signalSource = process } = {}) {
-  if (host === 'claude') return runClaudeTerminal({ config, args, env, signalSource });
+export async function runTerminalLauncher({ host, args = [], config, env = process.env, signalSource = process } = {}) {
+  if (host === 'claude') {
+    if (claudeAdministrativeArguments(args)) return runClaudeTerminal({ config, args, env, signalSource });
+    if (env.RNB_TERMINAL_LAUNCH_ACTIVE) throw new Error('Native terminal launcher recursion refused');
+    const { launchControlledClaudeTerminal } = await import('./claude-controlled-terminal.mjs');
+    await launchControlledClaudeTerminal({ binary: executable(config.realClaude), args, env, cwd: process.cwd() });
+    return { code: 0, signal: null };
+  }
   if (host !== 'codex') throw new Error('Unsupported terminal host');
   const invocation = terminalInvocation({ host, args, config, env });
   const child = spawn(invocation.command, invocation.args, { env: { ...subscriptionEnvironment(env), RNB_TERMINAL_LAUNCH_ACTIVE: '1' }, stdio: 'inherit', shell: false });

package/scripts/release-qualification-contract.mjs

@@ -111,7 +111,8 @@ export const RELEASE_REQUIREMENTS = Object.freeze({
         "tests/unit/forge-update-apply-rollback.test.mjs",
         "tests/unit/forge-update-archive-digest.test.mjs",
         "tests/unit/kb-copy-proof-legacy-sidecars.test.mjs",
-        "tests/unit/kb-copy-proof-unknown-content.test.mjs"
+        "tests/unit/kb-copy-proof-unknown-content.test.mjs",
+        "tests/unit/user-model-hook-install.test.mjs"
       ]
     },
     {
@@ -134,8 +135,8 @@ export const RELEASE_REQUIREMENTS = Object.freeze({
         "tests/unit/model-routing-launchers.test.mjs"
       ],
       "platformFiles": {
-        "linux": ["tests/unit/model-terminal-gateway.test.mjs", "tests/unit/model-terminal-launchers.test.mjs"],
-        "macos": ["tests/unit/model-terminal-gateway.test.mjs", "tests/unit/model-terminal-launchers.test.mjs"],
+        "linux": ["tests/unit/model-terminal-gateway.test.mjs", "tests/unit/model-terminal-launchers.test.mjs", "tests/unit/claude-controlled-terminal.test.mjs"],
+        "macos": ["tests/unit/model-terminal-gateway.test.mjs", "tests/unit/model-terminal-launchers.test.mjs", "tests/unit/claude-controlled-terminal.test.mjs"],
         "windows": ["tests/unit/windows-terminal-boundary.test.mjs"]
       }
     },

package/scripts/user-model-hook-install.mjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// DISTINCT-FROM: scripts/model-router-setup.mjs — native per-user registration only; never deploys policy or runtime.
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import crypto from 'node:crypto';
+import { pathToFileURL } from 'node:url';
+
+export function shellQuote(value) { return `'${value.replaceAll("'", "'\\''")}'`; }
+
+// Parse only standalone literal argv. Shell expansion, operators and redirection are never ownership.
+function literalArgv(command) {
+  if (typeof command !== 'string') return null;
+  const args = []; let word = ''; let quote = ''; let active = false;
+  for (let i = 0; i < command.length; i++) {
+    const c = command[i];
+    if (quote === "'") { if (c === "'") quote = ''; else word += c; continue; }
+    if (quote === '"') {
+      if (c === '"') { quote = ''; continue; }
+      if ('$`\\'.includes(c)) return null;
+      word += c; continue;
+    }
+    if (c === "'" || c === '"') { quote = c; active = true; continue; }
+    if (c === '\\') { if (++i === command.length) return null; word += command[i]; active = true; continue; }
+    if (/\s/.test(c)) { if (active) { args.push(word); word = ''; active = false; } continue; }
+    if (';&|<>$`(){}*?!~'.includes(c)) return null;
+    word += c; active = true;
+  }
+  if (quote) return null;
+  if (active) args.push(word);
+  return args;
+}
+
+function realNode(command, nodeExecutable, searchPath) {
+  const candidates = path.isAbsolute(command) ? [command] : command === 'node'
+    ? searchPath.split(path.delimiter).filter(Boolean).map(dir => path.join(dir, command)) : [];
+  const trusted = fs.realpathSync(nodeExecutable);
+  for (const candidate of candidates) {
+    try { fs.accessSync(candidate, fs.constants.X_OK); return fs.realpathSync(candidate) === trusted; } catch { /* next PATH entry */ }
+  }
+  return false;
+}
+
+function assertSafePath(file, home) {
+  const relative = path.relative(home, file);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) throw new Error('Path escapes supplied home');
+  let cursor = home;
+  for (const part of ['', ...relative.split(path.sep)]) {
+    if (part) cursor = path.join(cursor, part);
+    try {
+      const stat = fs.lstatSync(cursor);
+      if (stat.isSymbolicLink()) throw new Error(`Symlink refused: ${cursor}`);
+      if (cursor !== file && !stat.isDirectory()) throw new Error(`Non-directory ancestor: ${cursor}`);
+      if (cursor === file && !stat.isFile()) throw new Error(`Non-file target: ${cursor}`);
+    } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  }
+}
+
+function configPlan(file, host, options) {
+  assertSafePath(file, options.home);
+  let before = null; let mode = 0o600;
+  try { before = fs.readFileSync(file, 'utf8'); mode = fs.statSync(file).mode & 0o777; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  let config;
+  try { config = before === null ? {} : JSON.parse(before); } catch { throw new Error(`Malformed JSON: ${file}`); }
+  const object = value => value && typeof value === 'object' && !Array.isArray(value);
+  if (!object(config) || (config.hooks !== undefined && !object(config.hooks))) throw new Error(`Malformed hooks object: ${file}`);
+  config.hooks ??= {};
+  const entries = config.hooks.UserPromptSubmit === undefined ? [] : config.hooks.UserPromptSubmit;
+  if (!Array.isArray(entries)) throw new Error(`Malformed UserPromptSubmit: ${file}`);
+  const owned = [];
+  for (const [index, entry] of entries.entries()) {
+    if (!object(entry) || !Array.isArray(entry.hooks)) throw new Error(`Malformed hook group: ${file}`);
+    for (const hook of entry.hooks) {
+      if (!object(hook) || typeof hook.type !== 'string') throw new Error(`Malformed hook: ${file}`);
+      if (hook.type !== 'command') continue;
+      if (typeof hook.command !== 'string') throw new Error(`Malformed command: ${file}`);
+      const args = literalArgv(hook.command);
+      const expected = host === 'claude' ? ['--claude'] : [];
+      if (args?.[1] === options.script && realNode(args[0], options.nodeExecutable, options.searchPath)
+          && JSON.stringify(args.slice(2)) === JSON.stringify(expected)) owned.push({ index, hook });
+      else if (args?.includes(options.script) || hook.command.includes(options.script)) {
+        throw new Error(`Unowned model-hook override requires review: ${file}`);
+      }
+    }
+  }
+  if (owned.length > 1) throw new Error(`Ambiguous duplicate owned registrations: ${file}`);
+  const nodeCommand = realNode('node', options.nodeExecutable, options.searchPath) ? 'node' : shellQuote(options.nodeExecutable);
+  const command = `${nodeCommand} ${shellQuote(options.script)}${host === 'claude' ? ' --claude' : ''}`;
+  if (!owned.length) entries.push({ hooks: [{ type: 'command', command, timeout: 3 }] });
+  // Existing exact registrations are preserved byte-for-byte, including private group options.
+  config.hooks.UserPromptSubmit = entries;
+  const after = owned.length ? before : `${JSON.stringify(config, null, 2)}\n`;
+  return { host, file, before, after, mode, changed: before !== after, registration: owned.length ? 'present' : 'add' };
+}
+
+export function planUserModelHooks({ home = os.homedir(), nodeExecutable = process.execPath, searchPath = process.env.PATH || '' } = {}) {
+  home = path.resolve(home);
+  const script = path.join(home, '.claude/model-router/bin/user-model-prompt-hook.mjs');
+  const options = { home, script, nodeExecutable: path.resolve(nodeExecutable), searchPath };
+  return { home, script, changes: [
+    configPlan(path.join(home, '.claude/settings.json'), 'claude', options),
+    configPlan(path.join(home, '.codex/hooks.json'), 'codex', options),
+  ] };
+}
+
+export function applyUserModelHooks(plan) {
+  assertSafePath(plan.script, plan.home);
+  if (!fs.existsSync(plan.script)) throw new Error('Install the user hook runtime before applying registrations');
+  // Validate every original before any writes, so stale plans never overwrite a concurrent edit.
+  for (const change of plan.changes) {
+    assertSafePath(change.file, plan.home);
+    const current = fs.existsSync(change.file) ? fs.readFileSync(change.file, 'utf8') : null;
+    if (current !== change.before) throw new Error(`Config changed since plan: ${change.file}`);
+  }
+  const written = [];
+  for (const change of plan.changes.filter(item => item.changed)) {
+    fs.mkdirSync(path.dirname(change.file), { recursive: true, mode: 0o700 });
+    assertSafePath(change.file, plan.home);
+    const suffix = `${Date.now()}-${crypto.randomBytes(6).toString('hex')}`;
+    const backup = change.before === null ? null : `${change.file}.backup-${suffix}`;
+    if (backup) fs.copyFileSync(change.file, backup, fs.constants.COPYFILE_EXCL);
+    const temporary = `${change.file}.tmp-${suffix}`;
+    let fd;
+    try {
+      fd = fs.openSync(temporary, 'wx', change.mode);
+      fs.writeFileSync(fd, change.after); fs.fchmodSync(fd, change.mode); fs.fsyncSync(fd); fs.closeSync(fd); fd = undefined;
+      assertSafePath(change.file, plan.home);
+      const latest = fs.existsSync(change.file) ? fs.readFileSync(change.file, 'utf8') : null;
+      if (latest !== change.before) throw new Error(`Config changed before rename: ${change.file}`);
+      fs.renameSync(temporary, change.file);
+      written.push({ file: change.file, backup });
+    } finally { if (fd !== undefined) fs.closeSync(fd); if (fs.existsSync(temporary)) fs.unlinkSync(temporary); }
+  }
+  return { applied: true, written };
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  try {
+    const args = process.argv.slice(2);
+    if (args.some(arg => !['--apply', '--dry-run', '--plan'].includes(arg))) throw new Error('Usage: user-model-hook-install.mjs [--apply|--dry-run|--plan]');
+    const plan = planUserModelHooks();
+    const result = args.includes('--apply') ? applyUserModelHooks(plan) : { applied: false, script: plan.script, changes: plan.changes.map(({ host, file, changed, registration }) => ({ host, file, changed, registration })) };
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  } catch (error) { process.stderr.write(`${error.message}\n`); process.exitCode = 1; }
+}