prism-mcp-server 20.9.3 → 20.11.0

package/README.md

@@ -116,7 +116,7 @@ or by re-enabling after each run.
 <details>
 <summary>Release history (optional)</summary>
 
-## What's New in v20.9.0
+## What's New in v20.9.0 – v20.9.3
 
 - **Your skills follow your account.** `skill_save` stores a skill at the
   scope you choose: this machine only (`local`, works offline and signed out),
@@ -128,6 +128,19 @@ or by re-enabling after each run.
   them any time, losslessly. Deleting a scoped skill archives its final
   content locally first, so nothing is ever silently unrecoverable.
 
+- **Delivery that queues instead of failing.** Concurrent sessions no longer
+  starve skill sync on the local config store (WAL + busy-timeout) — a failure
+  that previously reported only "partial" where nobody could see it.
+- **Withheld rules still bind.** When the context budget can't inline a
+  skill's text, the manifest of withheld names now states that those skills
+  still govern the work and names every way to load them before completion
+  claims.
+- **The budget the floor never spent.** A long-standing accounting bug meant
+  no unprotected skill ever inlined at any normal context level — the
+  always-inlined protected floor was debiting the budget meant for everything
+  else. Task-matched skills (like the completion-evidence checklist) now
+  actually arrive.
+
 ## What's New in v20.8.2
 
 - **Skill delivery now admits failure instead of hiding it.** A filesystem

package/dist/cli.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
+import { spawnSync } from 'node:child_process';
+import { readFileSync, mkdirSync, readdirSync, statSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { SqliteStorage } from './storage/sqlite.js';
 import { handleVerifyStatus, handleGenerateHarness } from './verification/cliHandler.js';
 import * as path from 'path';
@@ -172,8 +175,31 @@ program
     .option('--all', 'Target all supported hosts instead of auto-detecting installed hosts')
     .option('--dry-run', 'Preview configuration changes without writing files')
     .option('--refresh', 'Refresh only entries previously created by Prism; custom entries stay untouched')
+    .option('--no-self-update', 'Skip the npm self-update check; configure with the currently installed version')
     .action(async (options) => {
     try {
+        // ── Converge the PACKAGE first, then the configs ──────────────
+        // connect is the one command the operator runs to make a machine
+        // current; leaving it configuring with stale code produced the
+        // "fresh hook, stale CLI" state observed live on 2026-08-13. After a
+        // successful update we RE-EXEC the new binary so the remainder of
+        // connect runs the code it just installed. Dry runs never update.
+        if (options.selfUpdate !== false && !options.dryRun) {
+            const { maybeSelfUpdate } = await import('./selfUpdate.js');
+            const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+            const upd = maybeSelfUpdate({ currentVersion: pkg.version, invokedFrom: process.argv[1], log: (l) => console.log(l) });
+            if (upd.action === 'updated') {
+                console.log(`✓ prism updated to ${upd.latest}; re-running connect with the new version`);
+                const rerun = spawnSync(process.execPath, [process.argv[1], 'connect', ...process.argv.slice(3), '--no-self-update'], { stdio: 'inherit' });
+                process.exit(rerun.status ?? 0);
+            }
+            else if (upd.action === 'failed') {
+                console.log(`⚠ self-update: ${upd.detail}`);
+            }
+            else if (upd.action === 'skipped') {
+                console.log(`− self-update skipped: ${upd.detail}`);
+            }
+        }
         if (!options.dryRun) {
             console.log('Close target MCP hosts before registration so they cannot edit configuration concurrently.');
         }
@@ -275,6 +301,43 @@ program
             if (skillSync.status !== 'disabled') {
                 const changed = skillSync.installed.length + skillSync.updated.length + skillSync.pruned.length;
                 console.log(`✓ Synalux skills: ${skillSync.tier || 'free'} tier (${changed} changed)`);
+                // prism-route hook: AFTER sync success on purpose — a connect that
+                // fails must leave the machine untouched (pinned by the
+                // "keeps legacy Claude hooks when the snapshot fails" test).
+                {
+                    const hookHosts = [];
+                    if (summary.results.some((r) => (r.host === 'claude-code' || r.host === 'claude-desktop') && r.status !== 'error'))
+                        hookHosts.push('claude');
+                    if (summary.results.some((r) => r.host === 'codex' && r.status !== 'error'))
+                        hookHosts.push('codex');
+                    if (hookHosts.length > 0) {
+                        try {
+                            const { ensurePromptRouteHook } = await import('./promptRouteHostHook.js');
+                            for (const r of ensurePromptRouteHook({ hosts: hookHosts, mode: 'explicit' })) {
+                                const state = r.script === 'unchanged' && r.config === 'unchanged' ? 'up to date' : 'installed';
+                                if (r.host === 'codex' && r.codexApproval === 'pending-or-unknown') {
+                                    // Codex silently skips untrusted hooks — a green "installed"
+                                    // here would be the "configured and inert" lie.
+                                    console.log(`⚠ codex: prism-route hook ${state}, AWAITING TRUST — run codex, then /hooks, and trust the entry ending prism-route/on_prompt.py`);
+                                }
+                                else if (r.host === 'codex' && r.codexApproval === 'state-present-unverifiable') {
+                                    // Approvals are keyed by definition hash, whose algorithm is
+                                    // not public — once ANY trust state exists we cannot tell
+                                    // ours apart from here. Say exactly that; asserting AWAITING
+                                    // after the operator pressed t reads as "the trust didn't
+                                    // take", which is a false alarm against their own action.
+                                    console.log(`− codex: prism-route hook ${state}; trust state exists but is not verifiable from here — confirm once in /hooks`);
+                                }
+                                else {
+                                    console.log(`✓ ${r.host}: prism-route prompt hook ${state} (${r.scriptPath})`);
+                                }
+                            }
+                        }
+                        catch {
+                            console.error('⚠ prism-route hook installation failed — skills still route at session start');
+                        }
+                    }
+                }
                 if (skillSync.conflicts.length > 0) {
                     console.error(`⚠ Preserved locally modified skill conflicts: ${skillSync.conflicts.join(', ')}`);
                 }
@@ -380,6 +443,78 @@ program
 //
 // JSON MODE: Structured envelope for programmatic consumption
 // (session loader scripts, CI/CD pipelines, etc.).
+// ── route-prompt ──────────────────────────────────────────────
+// Called by the prism-route UserPromptSubmit hook on EVERY prompt in both
+// Claude Code and Codex, so the contract is: always exit 0, always print one
+// JSON object, and stay off the network (cached settings DB only). A hook
+// that can fail a turn gets uninstalled; a hook that is slow gets noticed.
+/** Deliberate offload for payloads over the host inline cap. The host's own
+ *  overflow path swaps the payload for a 2KB preview with no instruction to
+ *  read the rest; this file plus the inline pointer is the recoverable form. */
+function writeRouteOffload(fullText) {
+    try {
+        const dir = path.join(homedir(), '.prism-mcp', 'route-context');
+        mkdirSync(dir, { recursive: true });
+        try {
+            // Best-effort prune: one file per over-budget routed prompt, kept a week.
+            for (const f of readdirSync(dir)) {
+                const p = path.join(dir, f);
+                try {
+                    if (Date.now() - statSync(p).mtimeMs > 7 * 86_400_000)
+                        rmSync(p);
+                }
+                catch { /* skip unstat-able entries */ }
+            }
+        }
+        catch { /* prune failure never blocks the write */ }
+        const target = path.join(dir, `route-${Date.now()}-${process.pid}.md`);
+        writeFileSync(target, fullText);
+        return target;
+    }
+    catch {
+        return undefined; // reshape degrades to the loud in-band fallback
+    }
+}
+program
+    .command('route-prompt')
+    .description('Match a prompt (stdin) against skill triggers; prints {names, text} JSON. Used by the prism-route host hook.')
+    .option('--loaded <names>', 'Comma-separated skill names already active in the session')
+    .action(async (options) => {
+    try {
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        // A pasted log can be megabytes; triggers live in the first human-sized
+        // stretch of a prompt, and unbounded input is regex food.
+        const prompt = Buffer.concat(chunks).toString('utf8').slice(0, 100_000);
+        const loaded = (options.loaded ?? '')
+            .split(',')
+            .map((n) => n.trim())
+            .filter(Boolean);
+        const { runPromptRouteFromCache } = await import('./tools/ledgerHandlers.js');
+        const { reshapeForInlineBudget, HOOK_INLINE_SAFE_CHARS } = await import('./tools/promptRouteHandler.js');
+        const result = await runPromptRouteFromCache(prompt, loaded);
+        // The hook path must fit the host's inline cap; the MCP tool path
+        // (session_route_prompt) keeps the full 30k — tool results inline far
+        // higher than hook context does.
+        const shaped = result.names.length > 0
+            ? reshapeForInlineBudget(result, HOOK_INLINE_SAFE_CHARS, writeRouteOffload)
+            : { text: '' };
+        const payload = JSON.stringify({ names: result.names, text: result.names.length > 0 ? shaped.text : '' });
+        await new Promise((resolveWrite) => process.stdout.write(payload + '\n', () => resolveWrite()));
+    }
+    catch {
+        // Never break the hook: an empty result is a routing miss, not an error.
+        await new Promise((resolveWrite) => process.stdout.write('{"names":[],"text":""}\n', () => resolveWrite()));
+    }
+    finally {
+        try {
+            await closeStorage();
+        }
+        catch { /* exit anyway */ }
+        process.exit(0);
+    }
+});
 program
     .command('load <project>')
     .description('Load session context for a project (same output as session_load_context MCP tool)')

package/dist/connect.js

@@ -45,7 +45,7 @@ const CODEX_STARTUP_BODY = [
     "after the verbatim startup display. If `session_bootstrap` is deferred, use native tool discovery to load that",
     "exact tool, then invoke it. Do not use shell commands, file reads, subagents, or unrelated tool inspection as",
     "a substitute. Do not call `session_load_context`. If discovery or invocation fails, report",
-    "`Prism startup failure` and stop. Reuse the `conversation_id` returned in structuredContent for every",
+    "`Prism startup failure` and stop. Reuse the `conversation_id` returned on the `<prism_session />` line for every",
     "session_save_ledger, session_save_handoff, and session_detect_drift call in this conversation. This hook-free",
     "block is managed by `prism connect`; do not edit it manually.",
     "",
@@ -579,7 +579,7 @@ function serializeClaudeStartupBlock(newline) {
         "deferred, use native tool discovery/ToolSearch to load that",
         "exact tool, then invoke it. Do not use shell commands, file reads, subagents, or unrelated tool inspection",
         "as a substitute. Do not call `session_load_context`. If discovery or invocation fails, report",
-        "`Prism startup failure` and stop. Reuse the `conversation_id` returned in structuredContent for every",
+        "`Prism startup failure` and stop. Reuse the `conversation_id` returned on the `<prism_session />` line for every",
         "session_save_ledger, session_save_handoff, and session_detect_drift call in this conversation. This block is",
         "managed by `prism connect`; do not edit it manually.",
         "",
@@ -660,7 +660,7 @@ function serializeGeminiStartupBlock(newline) {
         "to load that exact tool, then invoke it.",
         "Do not use shell commands, file reads, subagents, or unrelated tool inspection as a substitute. Do not call",
         "`session_load_context`. If discovery or invocation fails, report `Prism startup failure` and stop. Reuse the",
-        "`conversation_id` returned in structuredContent for session_save_ledger, session_save_handoff, and",
+        "`conversation_id` returned on the `<prism_session />` line for session_save_ledger, session_save_handoff, and",
         "session_detect_drift calls. This block is managed by `prism connect`; do not edit it manually.",
         "",
         ...LOCAL_FIRST_POLICY_LINES,

package/dist/postinstall.js

@@ -0,0 +1,30 @@
+/**
+ * npm postinstall — the upgrade path for the prism-route hook.
+ *
+ * `prism connect` is only typed once per machine, so an upgrade that adds or
+ * fixes the hook would otherwise reach no one until they reconnect. Silent
+ * and always-exit-0: a hook installer must never break `npm install`.
+ */
+import { ensurePromptRouteHook } from "./promptRouteHostHook.js";
+try {
+    const results = ensurePromptRouteHook({ mode: "auto" });
+    if (process.env.PRISM_DEBUG) {
+        for (const r of results)
+            console.error(`[prism postinstall] ${r.host}: script=${r.script} config=${r.config}`);
+    }
+    // The ONE step install cannot do for the operator, said at the only moment
+    // they are certainly watching. Codex's hook-trust gate exists so software
+    // cannot approve its own execution — prism will never write that trust
+    // state (a compromised release would otherwise gain silent
+    // execute-on-every-prompt), so the honest maximum is to make the pending
+    // approval impossible to miss. Approval is per hook-version, not per
+    // release: it recurs only when the hook script itself changes.
+    const codex = results.find((r) => r.host === "codex");
+    if (codex && codex.codexApproval === "pending-or-unknown") {
+        console.error("\n[prism] Codex hook installed but NOT yet trusted — Codex silently skips it until you approve it once:\n" +
+            "[prism]   codex  ->  /hooks  ->  entry ending prism-route/on_prompt.py  ->  press t\n");
+    }
+}
+catch {
+    /* never fail an install */
+}

package/dist/promptRouteHostHook.js

@@ -0,0 +1,394 @@
+/**
+ * prism-route — self-installing UserPromptSubmit hook for Claude Code + Codex.
+ *
+ * WHY A HOST HOOK. An MCP server never sees the user's prompt; the protocol
+ * carries only what a tool call carries. session_route_prompt (the MCP tool)
+ * therefore depends on the model deciding to call it — near-automatic at
+ * best. A UserPromptSubmit hook is the only mechanism that fires on EVERY
+ * prompt regardless of model behaviour, on both hosts, which is what the
+ * operator requires ("i need automatic").
+ *
+ * WHY SELF-INSTALLING. The previous generation of prism hooks was provisioned
+ * by a bootstrap script once, then hand-maintained per machine — which is why
+ * this machine has them and the other team machines do not. This module is
+ * called from three places so no machine can miss it:
+ *   1. `prism connect`      — the explicit path,
+ *   2. npm postinstall      — the upgrade path,
+ *   3. MCP server startup   — the safety net for installs that skip scripts.
+ * All three converge here and the operation is idempotent: same version →
+ * no writes; registered → not re-registered; other people's hooks untouched.
+ *
+ * WHY THE HOOK SHELLS OUT TO `prism route-prompt` instead of matching in
+ * Python: the trigger table, scoped-frontmatter triggers, entitlement and
+ * caps live in the TypeScript matcher. A Python reimplementation would drift,
+ * and a table that matches differently in the hook than in the server is
+ * worse than no hook at all.
+ */
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+/** Bump to force the on-disk script to be rewritten on the next ensure. */
+export const PROMPT_ROUTE_HOOK_VERSION = "3";
+const MARKER_FILE = ".prism-managed.json";
+const SCRIPT_FILE = "on_prompt.py";
+const HOOK_DIR = "prism-route";
+/** Substring that identifies our entry inside a host hooks config. */
+const COMMAND_SIGNATURE = `${HOOK_DIR}/${SCRIPT_FILE}`;
+/**
+ * The command registered in the host config carries the version as an
+ * argument (the script ignores argv — it reads stdin). This is a SECURITY
+ * property, found by an external probe of Codex 0.146: Codex's hook-trust
+ * hash covers the CONFIGURED DEFINITION, not the file the command points at.
+ * With a stable command and a version-refreshed script, every prism upgrade
+ * would silently swap the executable content behind an already-trusted hash —
+ * exactly what the trust gate exists to prevent. Versioning the command
+ * changes the definition on every script change, forcing Codex to re-prompt.
+ * Cost: one approval per release, which is Codex's consent model working.
+ */
+function hookCommand(scriptPath) {
+    return `python3 ${scriptPath} --v${PROMPT_ROUTE_HOOK_VERSION}`;
+}
+/**
+ * The hook script. Python because both hosts' existing hook fleets are
+ * Python and the runtime is guaranteed present on macOS.
+ *
+ * Contract notes:
+ *  - stdin carries the host's JSON payload; `prompt` is the Claude Code key
+ *    and the fallbacks cover Codex's Claude-compatible hook payloads.
+ *  - It must NEVER fail the turn: every path ends in continue:true, and an
+ *    unexpected exception exits 0 with a pass-through.
+ *  - Per-session dedupe lives HERE (state/<session>.json), because the hook
+ *    is the only party that knows what it already injected. `loaded` is
+ *    passed to the CLI so the matcher never returns the same skill twice.
+ */
+export const PROMPT_ROUTE_HOOK_SCRIPT = `#!/usr/bin/env python3
+"""Prism-managed hook (prism-route v${PROMPT_ROUTE_HOOK_VERSION}).
+
+Routes every user prompt through the on-device skill matcher via
+'prism route-prompt'. Injects newly matched skill bodies as context.
+Managed by prism; edits are overwritten on version bumps.
+"""
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+
+
+def emit(extra=None):
+    out = {"continue": True, "suppressOutput": True}
+    if extra:
+        out["hookSpecificOutput"] = {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": extra,
+        }
+    print(json.dumps(out))
+
+
+def find_cli():
+    override = os.environ.get("PRISM_ROUTE_CLI")
+    if override and os.path.exists(override):
+        return override
+    found = shutil.which("prism")
+    if found:
+        return found
+    home = os.path.expanduser("~")
+    for candidate in (
+        os.path.join(home, ".npm-global", "bin", "prism"),
+        "/opt/homebrew/bin/prism",
+        "/usr/local/bin/prism",
+        os.path.join(home, "bin", "prism"),
+    ):
+        if os.path.exists(candidate):
+            return candidate
+    return None
+
+
+def main():
+    try:
+        raw = sys.stdin.read()
+        payload = json.loads(raw) if raw.strip() else {}
+    except Exception:
+        payload = {}
+
+    prompt = str(
+        payload.get("prompt")
+        or payload.get("message")
+        or payload.get("user_prompt")
+        or ""
+    ).strip()
+    # Slash commands and micro-prompts ("ok", "merge") never route; skipping
+    # them keeps the common turn free.
+    if len(prompt) < 6 or prompt.startswith("/"):
+        emit()
+        return
+    # A pasted log can be megabytes; triggers live in the first human-sized
+    # stretch, and the CLI caps identically on its side.
+    prompt = prompt[:100_000]
+
+    session = str(
+        payload.get("session_id")
+        or payload.get("sessionId")
+        or payload.get("conversation_id")
+        or "default"
+    )
+    session = re.sub(r"[^A-Za-z0-9._-]", "_", session).lstrip(".")[:80] or "default"
+
+    state_dir = os.path.join(os.path.dirname(os.path.abspath(__file__)), "state")
+    state_path = os.path.join(state_dir, session + ".json")
+    loaded = []
+    try:
+        with open(state_path) as fh:
+            data = json.load(fh)
+            if isinstance(data, list):
+                loaded = [n for n in data if isinstance(n, str)]
+    except Exception:
+        pass
+
+    cli = find_cli()
+    if not cli:
+        emit()
+        return
+
+    try:
+        result = subprocess.run(
+            [cli, "route-prompt", "--loaded", ",".join(loaded)],
+            input=prompt,
+            capture_output=True,
+            text=True,
+            timeout=10,
+        )
+    except Exception:
+        emit()
+        return
+    if result.returncode != 0:
+        emit()
+        return
+
+    # Parse the LAST line that is JSON: wrappers hooked into node via
+    # NODE_OPTIONS (dotenv banners and the like) print to stdout BEFORE the
+    # CLI's own output, and one polluted line must not kill routing.
+    data = None
+    for line in reversed(result.stdout.strip().splitlines()):
+        line = line.strip()
+        if line.startswith("{"):
+            try:
+                data = json.loads(line)
+                break
+            except Exception:
+                continue
+    if not isinstance(data, dict):
+        emit()
+        return
+    names = [n for n in (data.get("names") or []) if isinstance(n, str)]
+    text = data.get("text") or ""
+    if not names or not text:
+        emit()
+        return
+
+    try:
+        os.makedirs(state_dir, exist_ok=True)
+        merged = loaded + [n for n in names if n not in loaded]
+        with open(state_path, "w") as fh:
+            json.dump(merged, fh)
+    except Exception:
+        pass  # dedupe degrades, injection still happens
+
+    emit(text)
+
+
+if __name__ == "__main__":
+    try:
+        main()
+    except Exception:
+        print(json.dumps({"continue": True, "suppressOutput": True}))
+        sys.exit(0)
+`;
+/** Evidence that this host was already prism-integrated by explicit action. */
+function hostShowsPriorConsent(spec, homeDir) {
+    if (existsSync(join(spec.root, "hooks", HOOK_DIR, MARKER_FILE)))
+        return true;
+    const evidenceFiles = spec.host === "claude"
+        ? [join(homeDir, ".claude.json"), spec.configPath]
+        : [join(spec.root, "config.toml"), spec.configPath];
+    for (const file of evidenceFiles) {
+        try {
+            if (/prism/i.test(readFileSync(file, "utf8")))
+                return true;
+        }
+        catch { /* unreadable = no evidence */ }
+    }
+    return false;
+}
+function hostSpecs(homeDir, env) {
+    const codexHome = env.CODEX_HOME?.trim() ? resolve(env.CODEX_HOME.trim()) : join(homeDir, ".codex");
+    return [
+        { host: "claude", root: join(homeDir, ".claude"), configPath: join(homeDir, ".claude", "settings.json") },
+        // Codex keeps hooks in hooks.json, not settings.json — same schema.
+        { host: "codex", root: codexHome, configPath: join(codexHome, "hooks.json") },
+    ];
+}
+/**
+ * Coarse Codex approval detection. Codex persists hook approvals as a
+ * [hooks.state] table in config.toml keyed by definition hash; the hashing
+ * algorithm is not public, so the only honest signals are "a state section
+ * exists and mentions our hook path" (detected) or anything else
+ * (pending-or-unknown). Never treat unknown as approved.
+ */
+function detectCodexApproval(codexRoot) {
+    try {
+        const toml = readFileSync(join(codexRoot, "config.toml"), "utf8");
+        const hasState = /\[hooks\.state/.test(toml);
+        if (hasState && toml.includes(COMMAND_SIGNATURE))
+            return "detected";
+        // Approvals are keyed by definition hash (algorithm not public). Once ANY
+        // trust state exists we cannot distinguish ours from here — and claiming
+        // AWAITING TRUST after the operator pressed t would be a false alarm
+        // against their own action. Distinct state, distinct wording.
+        if (hasState)
+            return "state-present-unverifiable";
+    }
+    catch { /* unreadable = no evidence */ }
+    return "pending-or-unknown";
+}
+function writeAtomically(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    const tmp = `${path}.prism-tmp-${process.pid}`;
+    writeFileSync(tmp, content);
+    renameSync(tmp, path);
+}
+function ensureScript(hookDir) {
+    const markerPath = join(hookDir, MARKER_FILE);
+    const scriptPath = join(hookDir, SCRIPT_FILE);
+    let existingVersion;
+    try {
+        const marker = JSON.parse(readFileSync(markerPath, "utf8"));
+        // The durable off switch. Without it, an operator who deletes the entry
+        // or edits the script gets silently re-enabled by the next upgrade —
+        // self-healing becomes self-reinfecting. {"disabled": true} in the
+        // marker survives every ensure path, including version bumps.
+        if (marker.disabled === true)
+            return "disabled";
+        existingVersion = marker.version;
+    }
+    catch {
+        /* no marker — install */
+    }
+    const scriptExists = existsSync(scriptPath);
+    if (scriptExists && existingVersion === PROMPT_ROUTE_HOOK_VERSION)
+        return "unchanged";
+    writeAtomically(scriptPath, PROMPT_ROUTE_HOOK_SCRIPT);
+    chmodSync(scriptPath, 0o755);
+    mkdirSync(join(hookDir, "state"), { recursive: true });
+    writeAtomically(markerPath, `${JSON.stringify({ managedBy: "prism", feature: "prism-route", version: PROMPT_ROUTE_HOOK_VERSION }, null, 2)}\n`);
+    return scriptExists ? "refreshed" : "installed";
+}
+function ensureRegistered(configPath, scriptPath, host) {
+    // Codex truncates hook additionalContext at ~2,500 tokens by default —
+    // a head-and-tail preview of our payload, which defeats the injection.
+    // additionalContextLimit: 0 passes the full context through — per the Codex
+    // hooks reference (learn.chatgpt.com/docs/hooks, verified 2026-08-13):
+    // "Setting to 0 passes full context directly to the model". NOT an in-repo
+    // guarantee: if Codex ever re-reads 0 as a literal zero cap, injection dies
+    // silently there — re-verify with a live codex probe after any Codex
+    // upgrade. The payload is already bounded by HOOK_INLINE_SAFE_CHARS on the
+    // emitting side, so the pass-through is not unbounded. Claude Code has no
+    // such field (its 10k-char cap is not configurable) — never write unknown
+    // keys into settings.json (a manually-added stray field there is left
+    // alone, not stripped).
+    const wantsLimit = host === "codex";
+    let config = {};
+    let originalText;
+    try {
+        originalText = readFileSync(configPath, "utf8");
+        const parsed = JSON.parse(originalText);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            config = parsed;
+        }
+    }
+    catch {
+        /* missing or unreadable — create minimal */
+    }
+    const hooks = (config.hooks && typeof config.hooks === "object" && !Array.isArray(config.hooks)
+        ? config.hooks
+        : {});
+    const entries = Array.isArray(hooks.UserPromptSubmit) ? hooks.UserPromptSubmit : [];
+    const wanted = hookCommand(scriptPath);
+    let stale = false;
+    for (const entry of entries) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const inner = entry.hooks;
+        if (!Array.isArray(inner))
+            continue;
+        for (const h of inner) {
+            if (!h || typeof h !== "object")
+                continue;
+            // Normalize separators: on Windows join() registers a backslash path,
+            // and a forward-slash signature would never match — so every ensure
+            // would re-register a duplicate entry.
+            const command = String(h.command ?? "");
+            if (!command.replace(/\\/g, "/").includes(COMMAND_SIGNATURE))
+                continue;
+            const limitCurrent = !wantsLimit || h.additionalContextLimit === 0;
+            if (command === wanted && limitCurrent)
+                return "unchanged";
+            // Same hook, older definition: UPDATE it in place. This is what makes a
+            // refresh visible to Codex's definition-hash — and on Claude it is a
+            // harmless argv change.
+            h.command = wanted;
+            if (wantsLimit)
+                h.additionalContextLimit = 0;
+            stale = true;
+        }
+    }
+    if (!stale) {
+        entries.push({
+            matcher: "*",
+            hooks: [{ type: "command", command: wanted, timeout: 15, ...(wantsLimit ? { additionalContextLimit: 0 } : {}) }],
+        });
+    }
+    hooks.UserPromptSubmit = entries;
+    config.hooks = hooks;
+    writeAtomically(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    return stale ? "updated" : "registered";
+}
+/**
+ * Idempotently install the prism-route hook for both hosts.
+ * Never throws for a single host's failure — the other host still gets it.
+ */
+export function ensurePromptRouteHook(options = {}) {
+    const homeDir = options.homeDir ?? homedir();
+    const env = options.env ?? process.env;
+    const wanted = new Set(options.hosts ?? ["claude", "codex"]);
+    const onlyExisting = options.onlyExistingRoots ?? true;
+    const results = [];
+    for (const spec of hostSpecs(homeDir, env)) {
+        if (!wanted.has(spec.host))
+            continue;
+        if (onlyExisting && !existsSync(spec.root))
+            continue;
+        if ((options.mode ?? "explicit") === "auto" && !hostShowsPriorConsent(spec, homeDir))
+            continue;
+        try {
+            const hookDir = join(spec.root, "hooks", HOOK_DIR);
+            const script = ensureScript(hookDir);
+            if (script === "disabled")
+                continue; // operator opt-out — do not re-register either
+            const config = ensureRegistered(spec.configPath, join(hookDir, SCRIPT_FILE), spec.host);
+            const result = { host: spec.host, script, config, scriptPath: join(hookDir, SCRIPT_FILE), configPath: spec.configPath };
+            if (spec.host === "codex") {
+                // Never report a green "registered" as if it were active: Codex
+                // SILENTLY SKIPS untrusted hooks, and "installed but inert" is the
+                // exact failure class this feature exists to end.
+                result.codexApproval = detectCodexApproval(spec.root);
+            }
+            results.push(result);
+        }
+        catch {
+            // One host failing (permissions, odd config) must not block the other.
+        }
+    }
+    return results;
+}