prism-mcp-server 20.10.0 → 20.11.0

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/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;
+}

package/dist/selfUpdate.js

@@ -0,0 +1,109 @@
+/**
+ * Self-update for `prism connect` — the converge command.
+ *
+ * The operator's model, which this implements: connect re-checks EVERYTHING —
+ * package version, host configs, hooks, skills — and applies what's needed.
+ * Before this, `npm i -g` and `prism connect` were two separate steps, and a
+ * machine that ran only the second stayed on old code with fresh config: the
+ * "hook exists but the CLI behind it is stale" state observed live on
+ * 2026-08-13, where a rebuilt hook called a pre-fix global CLI and quietly
+ * injected two skills instead of three.
+ *
+ * After a successful update, the caller RE-EXECS the new binary so the rest
+ * of connect runs with the code it just installed — reconciliation logic from
+ * the new version, not the old one.
+ *
+ * What this deliberately does NOT do: touch Codex hook trust. Convergence
+ * covers everything software may legitimately converge; approving our own
+ * execution is not in that set.
+ */
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+const PACKAGE = "prism-mcp-server";
+function defaultFetchLatest() {
+    return execFileSync("npm", ["view", PACKAGE, "version"], {
+        encoding: "utf8",
+        timeout: 15_000,
+    }).trim();
+}
+function defaultInstall(version) {
+    // Inherits the operator's npm prefix (.npmrc / NPM_CONFIG_PREFIX), so the
+    // update lands where their `prism` actually resolves from.
+    execFileSync("npm", ["install", "-g", `${PACKAGE}@${version}`], {
+        stdio: "inherit",
+        timeout: 300_000,
+    });
+}
+/** Plain numeric semver compare; returns true when b is newer than a. */
+export function isNewer(a, b) {
+    const pa = a.split(".").map((n) => parseInt(n, 10));
+    const pb = b.split(".").map((n) => parseInt(n, 10));
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (y > x)
+            return true;
+        if (y < x)
+            return false;
+    }
+    return false;
+}
+export function maybeSelfUpdate(deps) {
+    const env = deps.env ?? process.env;
+    const log = deps.log ?? (() => { });
+    const fetchLatest = deps.fetchLatest ?? defaultFetchLatest;
+    const install = deps.install ?? defaultInstall;
+    if (env.PRISM_NO_SELF_UPDATE === "1") {
+        return { action: "skipped", detail: "PRISM_NO_SELF_UPDATE=1" };
+    }
+    // Test runners must never reach the network or npm -g.
+    if (env.VITEST || env.NODE_ENV === "test") {
+        return { action: "skipped", detail: "test environment" };
+    }
+    // A -local.N or any prerelease build is a developer's hand-installed
+    // artifact; "updating" it to the registry release would be a DOWNGRADE of
+    // intent. Converging dev builds is the developer's call, not ours.
+    if (deps.currentVersion.includes("-")) {
+        return { action: "skipped", detail: `dev build ${deps.currentVersion} — not touching it` };
+    }
+    // A CLI running from a source checkout (repo dist, not node_modules) must
+    // never self-update: `npm i -g` would update the GLOBAL install while the
+    // re-exec re-ran THIS checkout's old code under a "updated" banner — the
+    // exact stale-code-fresh-claim confusion connect exists to end.
+    if (deps.invokedFrom) {
+        // argv[1] for a global install is the BIN SYMLINK (~/.npm-global/bin/prism),
+        // whose path contains no node_modules — judging the raw path would disable
+        // self-update for every normal install (caught empirically in review).
+        // The realpath resolves through the symlink into lib/node_modules/…
+        let resolved = deps.invokedFrom;
+        try {
+            resolved = realpathSync(deps.invokedFrom);
+        }
+        catch { /* keep raw */ }
+        if (!resolved.includes("node_modules")) {
+            return { action: "skipped", detail: `running from a checkout (${resolved}) — update the checkout with git, not npm` };
+        }
+    }
+    let latest;
+    try {
+        latest = fetchLatest();
+    }
+    catch (error) {
+        // Offline connect must still converge configs with the code it has.
+        return { action: "failed", detail: `registry unreachable (${error instanceof Error ? error.message.split("\n")[0] : String(error)}) — continuing with ${deps.currentVersion}` };
+    }
+    if (!/^\d+\.\d+\.\d+$/.test(latest)) {
+        return { action: "failed", detail: `registry returned unexpected version "${latest}" — continuing` };
+    }
+    if (!isNewer(deps.currentVersion, latest)) {
+        return { action: "current", detail: `${deps.currentVersion} is current`, latest };
+    }
+    log(`prism ${deps.currentVersion} → ${latest}: updating before configuring …`);
+    try {
+        install(latest);
+    }
+    catch (error) {
+        return { action: "failed", detail: `npm install -g failed (${error instanceof Error ? error.message.split("\n")[0] : String(error)}) — continuing with ${deps.currentVersion}`, latest };
+    }
+    return { action: "updated", detail: `now on ${latest}`, latest };
+}

package/dist/server.js

@@ -91,7 +91,7 @@ import { LOCAL_FIRST_POLICY_TEXT } from "./localFirstPolicy.js";
 // ─── Import Tool Definitions (schemas) and Handlers (implementations) ─────
 import { WEB_SEARCH_TOOL, BRAVE_WEB_SEARCH_CODE_MODE_TOOL, LOCAL_SEARCH_TOOL, BRAVE_LOCAL_SEARCH_CODE_MODE_TOOL, CODE_MODE_TRANSFORM_TOOL, BRAVE_ANSWERS_TOOL, RESEARCH_PAPER_ANALYSIS_TOOL, webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, braveLocalSearchCodeModeHandler, codeModeTransformHandler, braveAnswersHandler, researchPaperAnalysisHandler, } from "./tools/index.js";
 // Session memory tools — only used if Supabase is configured
-import { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, SESSION_BOOTSTRAP_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, 
+import { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, SESSION_BOOTSTRAP_TOOL, SESSION_ROUTE_PROMPT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, 
 // ─── v0.4.0: New tool definitions (Enhancements #2 and #4) ───
 SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, 
 // ─── v2.0: Time Travel tool definitions ───
@@ -123,7 +123,7 @@ ONBOARDING_WIZARD_TOOL, EXTRACT_ENTITIES_TOOL, API_ANALYTICS_TOOL, BACKUP_DATABA
 // v15.5: Knowledge Ingestion
 KNOWLEDGE_INGEST_TOOL, 
 // v19.2: Inference Metrics
-INFERENCE_METRICS_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
+INFERENCE_METRICS_TOOL, sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, sessionRoutePromptHandler, knowledgeSearchHandler, knowledgeForgetHandler, 
 // ─── v0.4.0: New tool handlers ───
 compactLedgerHandler, sessionSearchMemoryHandler, backfillEmbeddingsHandler, sessionBackfillLinksHandler, sessionSynthesizeEdgesHandler, sessionCognitiveRouteHandler, 
 // ─── v2.0: Time Travel handlers ───
@@ -186,6 +186,7 @@ const BASE_TOOLS = [
 function buildSessionMemoryTools() {
     return [
         SESSION_BOOTSTRAP_TOOL, // session_bootstrap — hook-free configured first-turn greeting + context
+        SESSION_ROUTE_PROMPT_TOOL, // session_route_prompt — routes EVERY turn after the first
         SKILL_SAVE_TOOL, // skill_save — save a skill at local/user/team scope
         SKILL_MANAGE_TOOL, // skill_manage — list/delete scoped skills, release/restore platform skills
         SESSION_SAVE_LEDGER_TOOL, // session_save_ledger — append immutable session log
@@ -259,6 +260,23 @@ let storageIsReady = false;
 // session_load_context. Used by deferred auto-push to avoid duplicates when a
 // native host complies with the hook-free first-turn instruction.
 let contextLoadedByClient = false;
+// ─── prism-route hook self-heal ──────────────────────────────
+// The safety net of the three install paths (connect, postinstall, here):
+// covers installs that skipped npm scripts and machines that never re-ran
+// connect. Idempotent and version-marked, so the steady-state cost is two
+// stat calls a few seconds after boot. Opt out: PRISM_DISABLE_HOOK_AUTOINSTALL=1.
+// Guarded against test runners: five suites import this module, and a
+// module-scope timer would otherwise rewrite the DEVELOPER'S real host
+// configs five seconds into every vitest run.
+if (process.env.PRISM_DISABLE_HOOK_AUTOINSTALL !== "1" &&
+    !process.env.VITEST &&
+    process.env.NODE_ENV !== "test") {
+    setTimeout(() => {
+        import("./promptRouteHostHook.js")
+            .then((m) => m.ensurePromptRouteHook({ mode: "auto" }))
+            .catch(() => { });
+    }, 5000).unref();
+}
 /**
  * Notifies subscribed clients that a resource has changed.
  *
@@ -330,6 +348,7 @@ export const PRISM_SERVER_INSTRUCTIONS = `Prism MCP — The Mind Palace for AI A
     `trigger rules — read each before proposing any change. Surfacing a name is not loading it: hosts that ` +
     `do not auto-load skill files must fetch each body with knowledge_search, passing the skill name ` +
     `exactly as listed. ` +
+    `AFTER that first turn, routing does not stop: call session_route_prompt at the start of any turn where the user states a new task, changes the kind of work, or reports a defect, passing their verbatim message as {prompt} and the skills you already hold as {loaded}. session_bootstrap routes only turn one, so without this a long session keeps working with whatever it happened to load hours earlier. The call is cheap — a single line when nothing new matches, and never the same skill twice. When it returns skills, read and follow them before doing the work. ` +
     `Emit no preamble. Print the complete tool result verbatim as the entire first-turn startup display, before any optional ` +
     `answer. Do not summarize, paraphrase, rename headings, reformat, or omit any returned section. Preserve its order and ` +
     `line content. For a greeting-only prompt, stop after the verbatim startup display. ` +
@@ -765,6 +784,12 @@ export function createServer() {
                         contextLoadedByClient = true;
                         result = await sessionBootstrapHandler(args);
                         break;
+                    case "session_route_prompt":
+                        // Deliberately NOT gated on SESSION_MEMORY_ENABLED: routing is
+                        // on-device against a cached table, so it must keep working when
+                        // the memory backend is unconfigured or unreachable.
+                        result = await sessionRoutePromptHandler(args);
+                        break;
                     case "knowledge_search":
                         if (!SESSION_MEMORY_ENABLED)
                             throw new Error("Session memory not configured. Set SUPABASE_URL and SUPABASE_KEY.");

package/dist/tools/index.js

@@ -26,9 +26,9 @@ export { webSearchHandler, braveWebSearchCodeModeHandler, localSearchHandler, br
 // This file always exports them — server.ts decides whether to include them in the tool list.
 //
 // v0.4.0: Added SESSION_COMPACT_LEDGER_TOOL and SESSION_SEARCH_MEMORY_TOOL
-export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, SESSION_BOOTSTRAP_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_BACKFILL_EMBEDDINGS_TOOL, SESSION_FORGET_MEMORY_TOOL, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, SESSION_BACKFILL_LINKS_TOOL, MAINTENANCE_VACUUM_TOOL, isDeepStoragePurgeArgs, SESSION_SYNTHESIZE_EDGES_TOOL, isSessionSynthesizeEdgesArgs, SESSION_COGNITIVE_ROUTE_TOOL, isSessionCognitiveRouteArgs, SESSION_TASK_ROUTE_TOOL, isSessionTaskRouteArgs, ONBOARDING_WIZARD_TOOL, EXTRACT_ENTITIES_TOOL, API_ANALYTICS_TOOL, BACKUP_DATABASE_TOOL, CONFIGURE_NOTIFICATIONS_TOOL, QUERY_MEMORY_NATURAL_TOOL } from "./sessionMemoryDefinitions.js";
+export { SESSION_SAVE_LEDGER_TOOL, SESSION_SAVE_HANDOFF_TOOL, SESSION_LOAD_CONTEXT_TOOL, SESSION_BOOTSTRAP_TOOL, SESSION_ROUTE_PROMPT_TOOL, KNOWLEDGE_SEARCH_TOOL, KNOWLEDGE_FORGET_TOOL, SESSION_COMPACT_LEDGER_TOOL, SESSION_SEARCH_MEMORY_TOOL, MEMORY_HISTORY_TOOL, MEMORY_CHECKOUT_TOOL, SESSION_SAVE_IMAGE_TOOL, SESSION_VIEW_IMAGE_TOOL, SESSION_HEALTH_CHECK_TOOL, SESSION_BACKFILL_EMBEDDINGS_TOOL, SESSION_FORGET_MEMORY_TOOL, SESSION_EXPORT_MEMORY_TOOL, KNOWLEDGE_SET_RETENTION_TOOL, SESSION_SAVE_EXPERIENCE_TOOL, KNOWLEDGE_UPVOTE_TOOL, KNOWLEDGE_DOWNVOTE_TOOL, KNOWLEDGE_SYNC_RULES_TOOL, DEEP_STORAGE_PURGE_TOOL, SESSION_INTUITIVE_RECALL_TOOL, SESSION_BACKFILL_LINKS_TOOL, MAINTENANCE_VACUUM_TOOL, isDeepStoragePurgeArgs, SESSION_SYNTHESIZE_EDGES_TOOL, isSessionSynthesizeEdgesArgs, SESSION_COGNITIVE_ROUTE_TOOL, isSessionCognitiveRouteArgs, SESSION_TASK_ROUTE_TOOL, isSessionTaskRouteArgs, ONBOARDING_WIZARD_TOOL, EXTRACT_ENTITIES_TOOL, API_ANALYTICS_TOOL, BACKUP_DATABASE_TOOL, CONFIGURE_NOTIFICATIONS_TOOL, QUERY_MEMORY_NATURAL_TOOL } from "./sessionMemoryDefinitions.js";
 // 1. Ledger (Core CRUD & State)
-export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, sessionSaveExperienceHandler, sessionSaveImageHandler, sessionViewImageHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionForgetMemoryHandler, sessionExportMemoryHandler } from "./ledgerHandlers.js";
+export { sessionSaveLedgerHandler, sessionSaveHandoffHandler, sessionLoadContextHandler, sessionBootstrapHandler, sessionRoutePromptHandler, runPromptRouteFromCache, sessionSaveExperienceHandler, sessionSaveImageHandler, sessionViewImageHandler, memoryHistoryHandler, memoryCheckoutHandler, sessionForgetMemoryHandler, sessionExportMemoryHandler } from "./ledgerHandlers.js";
 // 2. Graph (Semantic Search & Weighting)
 export { sessionSearchMemoryHandler, knowledgeSearchHandler, sessionIntuitiveRecallHandler, knowledgeUpvoteHandler, knowledgeDownvoteHandler, knowledgeForgetHandler, knowledgeSyncRulesHandler, sessionSynthesizeEdgesHandler, sessionCognitiveRouteHandler } from "./graphHandlers.js";
 // 3. Hygiene (Maintenance & Integrity)

package/dist/tools/ledgerHandlers.js

@@ -1793,14 +1793,21 @@ export async function seedAndRecallDemoMemory(conversationId) {
             limit: "1",
         }));
         const recalled = rows[0];
-        if (!recalled?.summary)
+        if (!recalled?.summary) {
+            console.error(`[first-run-demo] read-back returned ${Array.isArray(rows) ? rows.length : "non-array"} rows — seed row not visible`);
             return null;
+        }
         const todo = Array.isArray(recalled.todos) && recalled.todos[0] ? `\n  - TODO it carried: ${recalled.todos[0]}` : "";
         return (`- 🧠 **Watch this — Prism just saved a memory and recalled it from disk:**\n` +
             `  - "${recalled.summary}"${todo}\n` +
             `  - This round-trip is what every future session gets: your decisions, TODOs, and changed files, back the moment you return. (Demo lives in the \`${DEMO_PROJECT}\` project — delete it anytime.)`);
     }
-    catch {
+    catch (error) {
+        // Still swallow — a first run must never break on a demo — but say WHY on
+        // stderr. This block went missing intermittently on one CI leg
+        // (ubuntu/node 20) and the silent catch made every investigation start
+        // from nothing: the failure was only ever visible as an ABSENT paragraph.
+        console.error(`[first-run-demo] seed/recall failed: ${error instanceof Error ? `${error.name}: ${error.message}\n${error.stack}` : String(error)}`);
         return null;
     }
 }
@@ -1851,7 +1858,7 @@ export function buildSessionFactsLine(facts) {
  * Failures are swallowed — a broken trigger degrades to "the public table
  * only", never takes down startup.
  */
-async function collectSkillTriggersOnThisMachine() {
+export async function collectSkillTriggersOnThisMachine() {
     try {
         const { collectScopedTriggers, collectLocalSkillTriggers } = await import("./scopedSkillTriggers.js");
         const merged = {};
@@ -1906,6 +1913,64 @@ async function collectSkillTriggersOnThisMachine() {
         return undefined;
     }
 }
+/**
+ * session_route_prompt — the mid-session half of skill routing.
+ *
+ * Everything here is deliberately borrowed from the first-turn path rather
+ * than reimplemented: the same on-device matcher, the same scoped-frontmatter
+ * triggers, the same entitlement set and the same local-skill bypass. A second
+ * implementation would drift, and a routing table that behaves differently at
+ * turn 500 than at turn 1 is worse than no routing at all.
+ */
+/**
+ * Prompt routing from CACHED state only — no network, no manifest sync.
+ *
+ * Shared by the MCP tool and the `prism route-prompt` CLI (which the
+ * prism-route host hook shells out to on every prompt). Entitlement comes
+ * from the last-synced manifest in the settings DB; the server refreshes it
+ * at startup, and a per-prompt path must never trigger a portal round-trip.
+ * One implementation on purpose: a table that matches differently in the
+ * hook than in the server is worse than no hook.
+ */
+export async function runPromptRouteFromCache(prompt, loaded) {
+    const { routePrompt } = await import("./promptRouteHandler.js");
+    const { resolvePromptSkillNames, _setStorage } = await import("./skillRouting.js");
+    // The CLI is a fresh process per prompt: without storage wiring the keyword
+    // table can neither be read from disk (offline = dead routing) nor
+    // persisted after a fetch (every prompt = a network GET). The server paths
+    // wire this at bootstrap; the CLI must do it itself.
+    _setStorage(async (key, value) => { await setSetting(key, value); }, async (key) => getSetting(key, ""));
+    return routePrompt(prompt, loaded, {
+        resolvePromptSkillNames,
+        collectTriggers: collectSkillTriggersOnThisMachine,
+        entitledNames: async () => {
+            try {
+                const parsed = JSON.parse(await getSetting("skill_manifest:names", "[]"));
+                return new Set(Array.isArray(parsed) ? parsed.filter((n) => typeof n === "string") : []);
+            }
+            catch {
+                return new Set();
+            }
+        },
+        getBody: (name) => getSetting(`skill:${name}`, ""),
+        manifestVersion: async () => {
+            const v = Number(await getSetting("skill_manifest:routing_version", ""));
+            return Number.isFinite(v) && v > 0 ? v : undefined;
+        },
+    });
+}
+export async function sessionRoutePromptHandler(args) {
+    const input = (typeof args === "object" && args !== null && !Array.isArray(args) ? args : {});
+    const prompt = typeof input.prompt === "string" ? input.prompt : "";
+    const loaded = Array.isArray(input.loaded)
+        ? input.loaded.filter((n) => typeof n === "string")
+        : [];
+    const result = await runPromptRouteFromCache(prompt, loaded);
+    // Text only, never structuredContent. A result carrying both lets a host
+    // surface just the structured half — which is exactly how Claude Code
+    // silently dropped the bootstrap payload for three weeks.
+    return { content: [{ type: "text", text: result.text }] };
+}
 export async function sessionBootstrapHandler(args = {}, options = {}) {
     if (typeof args !== "object" || args === null || Array.isArray(args)) {
         throw new Error("Invalid arguments for session_bootstrap");

package/dist/tools/promptRouteHandler.js

@@ -0,0 +1,208 @@
+/**
+ * session_route_prompt — mid-session skill routing.
+ *
+ * THE GAP THIS CLOSES (2026-08-12). Skill routing runs at session_bootstrap,
+ * which by instruction happens on the first turn. Long sessions are where the
+ * work actually is: an eight-hour session was asked six times for a UI/UX
+ * review, and even after the routing table learned those phrasings, nothing
+ * could deliver the skill — the ask arrived at turn ~530 and routing had run
+ * at turn 1. The agent substituted source-grep assertions for rendered
+ * evidence and shipped six reactive patches.
+ *
+ * WHY THIS IS A TOOL AND NOT AUTOMATIC. An MCP server never sees the user's
+ * prompt; the protocol only carries what a tool call carries. Truly automatic
+ * per-prompt injection needs a HOST hook, which the operator has ruled out.
+ * This is the honest approximation: the model passes the prompt, we match it
+ * on-device and return only what is genuinely new.
+ *
+ * CHEAP BY CONSTRUCTION, because an instruction to call it every turn is only
+ * affordable if the common answer is nearly free:
+ *   - the overwhelmingly common result is "no new skills", a one-line reply;
+ *   - `loaded` lets the caller declare what it already has, so a skill is
+ *     never re-injected and a repeated call costs nothing;
+ *   - bodies are capped, so a pathological match cannot dump the budget.
+ *
+ * The prompt is matched ON DEVICE against the same table and the same scoped
+ * frontmatter triggers session_bootstrap uses. It is never transmitted.
+ */
+import { debugLog } from "../utils/logger.js";
+/** Never return more than this many bodies in one call. */
+export const MAX_ROUTED_SKILLS = 3;
+/** Hard ceiling on returned characters, so one call cannot flood the window.
+ *  Sized from measurement, not taste: the UI-review bundle
+ *  (visual-screenshot-verification + playwright-screenshot-discipline +
+ *  verified-shipping) is ~24.5k, and at 24k the third — the EVIDENCE-CLAIM
+ *  rules, arguably the one that matters most at the merge moment — was
+ *  reported "matched, not injected" on the first UI turn of a live session.
+ *  A cap that trims the bundle it was built for is mis-sized. */
+export const MAX_ROUTED_CHARS = 30_000;
+/** What a HOST will actually hand the model inline from a hook. Claude Code
+ *  hard-caps hook additionalContext at 10,000 chars — over that, the full text
+ *  goes to a file and the model gets a 2KB preview (three live instances
+ *  observed 2026-08-13: 13.2/18/18.9KB injections, all offloaded). Codex
+ *  truncates at ~2,500 tokens by default. MAX_ROUTED_CHARS bounds the PAYLOAD;
+ *  this bounds what may ride INLINE through a hook — anything larger must be
+ *  our own offload file with an imperative pointer, not the host's silent one. */
+export const HOOK_INLINE_SAFE_CHARS = 9_800;
+/**
+ * Match a prompt and return ONLY skills the caller does not already have.
+ *
+ * Pure over its deps so the tests exercise real matching rather than mocks of
+ * the thing under test.
+ */
+export async function routePrompt(prompt, loaded, deps) {
+    const trimmed = (prompt || "").trim();
+    if (!trimmed) {
+        return { names: [], alreadyLoaded: [], overflow: [], text: "No prompt supplied — nothing to route." };
+    }
+    const scoped = await deps.collectTriggers().catch(() => undefined);
+    const version = await deps.manifestVersion().catch(() => undefined);
+    let matched = [];
+    try {
+        matched = await deps.resolvePromptSkillNames(trimmed, version, scoped?.triggers);
+    }
+    catch (error) {
+        // Routing must never take down the turn that asked for it.
+        debugLog(`[session_route_prompt] match failed: ${error instanceof Error ? error.message : String(error)}`);
+        return { names: [], alreadyLoaded: [], overflow: [], text: "No new skills for this prompt." };
+    }
+    const entitled = await deps.entitledNames().catch(() => new Set());
+    // A local skill is on disk and not in the delivery manifest, so entitlement
+    // cannot see it — the same bypass session_bootstrap applies.
+    const permitted = matched.filter((n) => entitled.has(n) || scoped?.localNames.has(n));
+    const have = new Set(loaded.map((n) => n.trim()).filter(Boolean));
+    const alreadyLoaded = permitted.filter((n) => have.has(n));
+    const fresh = permitted.filter((n) => !have.has(n));
+    if (fresh.length === 0) {
+        // The common case, and it must stay one cheap line: an instruction to call
+        // this every turn is only reasonable if silence is nearly free.
+        return {
+            names: [], alreadyLoaded, overflow: [],
+            text: "No new skills for this prompt.",
+        };
+    }
+    const selected = fresh.slice(0, MAX_ROUTED_SKILLS);
+    const overflow = fresh.slice(MAX_ROUTED_SKILLS);
+    const blocks = [];
+    const delivered = [];
+    let budget = MAX_ROUTED_CHARS;
+    for (const name of selected) {
+        const body = (await deps.getBody(name).catch(() => "")).trim();
+        if (!body) {
+            // Routed but undeliverable is the exact defect this feature exists to
+            // surface. Say so rather than returning a name with nothing behind it.
+            blocks.push(`### ${name}\n(no content on this machine — run skill sync)`);
+            delivered.push(name);
+            continue;
+        }
+        if (body.length > budget) {
+            overflow.push(name);
+            continue;
+        }
+        budget -= body.length;
+        blocks.push(`### ${name}\n${body}`);
+        delivered.push(name);
+    }
+    if (delivered.length === 0) {
+        return { names: [], alreadyLoaded, overflow, text: "No new skills for this prompt." };
+    }
+    // Imperative, not a label. A bare list is decorative; nothing else in this
+    // path tells the agent these rules bind the work it is about to do.
+    //
+    // The overflow list is CAPPED: the header feeds reshapeForInlineBudget's
+    // base text, whose budget guarantee (and the pointer's first-2KB placement)
+    // holds only if the header is bounded. An unbounded list of matched names
+    // was measured at 12,950 chars for a 400-skill match — over the host cap
+    // before a single body was added.
+    const overflowShown = overflow.slice(0, 8);
+    const overflowNote = overflow.length > 0
+        ? `\n\nAlso matched, not injected: ${overflowShown.join(", ")}${overflow.length > overflowShown.length ? ` (+${overflow.length - overflowShown.length} more)` : ""}.`
+        : "";
+    const header = `**Skills now active for this task:** ${delivered.join(", ")}\n\n` +
+        `These apply to the work you are about to do. Read and follow them before proceeding.` +
+        overflowNote;
+    return { names: delivered, alreadyLoaded, overflow, header, blocks, text: `${header}\n\n${blocks.join("\n\n")}` };
+}
+/**
+ * Fit a routed payload under a host's inline hook cap.
+ *
+ * The host's own overflow handling is the failure mode, not the fallback:
+ * Claude Code silently swaps anything over 10k chars for a 2KB preview, and
+ * nothing tells the model to go read the rest. So when the payload is over
+ * budget WE offload it — to a file we name, behind an imperative that sits in
+ * the first 2KB where every host preview window can still deliver it — and
+ * inline as many whole priority bodies as fit.
+ *
+ * Pure over its writer so tests exercise the real budgeting.
+ */
+export function reshapeForInlineBudget(result, budgetChars, writeOffload) {
+    const full = result.text;
+    if (full.length <= budgetChars || !result.header || !result.blocks || result.blocks.length === 0) {
+        return { text: full, offloaded: false };
+    }
+    let offloadPath;
+    try {
+        offloadPath = writeOffload(full);
+    }
+    catch {
+        offloadPath = undefined;
+    }
+    // POINTER FIRST. Recoverability outranks prose order: skill names are
+    // unbounded (portal manifest, unvalidated), so any text placed before the
+    // pointer can push it past the ~2KB preview a host shows for offloaded
+    // context — or under the final clamp, slice it off entirely. Round-2 review
+    // measured both: 200-char names put the pointer at offset ~2,374 with the
+    // clamp never firing. With the pointer leading, its path sits within the
+    // first ~120 chars no matter what the header does.
+    const pieces = [];
+    if (offloadPath) {
+        pieces.push(`**Host hook context is size-capped — the full text of all ${result.names.length} skill(s) is saved at: ${offloadPath}**\n` +
+            `**Read that file now and follow those skills before proceeding. If the host shows "Full output saved to" with another path above, Read that file instead.**`);
+    }
+    pieces.push(result.header);
+    // Loud-failure footer when there is no offload file to point at — a
+    // silently dropped skill is the defect this feature exists for. The reserve
+    // is an EXACT FIXPOINT over the skipped set, not a bound: reserving for all
+    // delivered names was measured skipping a body that previously fit (188
+    // wasted chars), and a guessed constant was measured overrunning by 99.
+    // The skipped set only grows as the reserve grows, so this converges in at
+    // most blocks+1 rounds.
+    const footerFor = (names) => `\n\n**Not inlined (host size cap, offload unavailable): ${names.join(", ")} — fetch each with knowledge_search and follow it before proceeding.**`;
+    const base = pieces.join("\n\n");
+    const blocks = result.blocks; // narrowed once — the closure below defeats TS narrowing on result
+    const fill = (reserve) => {
+        let filled = base;
+        const skipped = [];
+        for (let i = 0; i < blocks.length; i++) {
+            const candidate = `${filled}\n\n${blocks[i]}`;
+            if (candidate.length <= budgetChars - reserve) {
+                filled = candidate;
+            }
+            else {
+                skipped.push(result.names[i] ?? `skill ${i + 1}`);
+            }
+        }
+        return { filled, skipped };
+    };
+    let attempt = fill(0);
+    if (!offloadPath) {
+        for (let round = 0; round <= blocks.length && attempt.skipped.length > 0; round++) {
+            const next = fill(footerFor(attempt.skipped).length);
+            const converged = next.skipped.length === attempt.skipped.length;
+            attempt = next;
+            if (converged)
+                break;
+        }
+    }
+    let inline = attempt.filled;
+    if (!offloadPath && attempt.skipped.length > 0) {
+        inline += footerFor(attempt.skipped);
+    }
+    // Belt over the construction: the budget is a HOST hard cap, and "the data
+    // stayed small" is not an invariant. The pointer leads, so a slice keeps
+    // the recoverable part.
+    if (inline.length > budgetChars) {
+        inline = inline.slice(0, budgetChars);
+    }
+    return { text: inline, offloaded: true, offloadPath };
+}

package/dist/tools/sessionMemoryDefinitions.js

@@ -159,6 +159,50 @@ export const SESSION_LOAD_CONTEXT_TOOL = {
     },
 };
 // ─── Hook-free Session Bootstrap ──────────────────────────────
+/**
+ * Mid-session counterpart to session_bootstrap.
+ *
+ * session_bootstrap routes the FIRST prompt. This routes every prompt after
+ * it, which is where long sessions actually do their work — the 2026-08-12
+ * incident asked for a UI/UX review at turn ~530 and no skill could reach it.
+ */
+export const SESSION_ROUTE_PROMPT_TOOL = {
+    name: "session_route_prompt",
+    description: "Call this at the START of any turn where the user states a NEW task, changes the kind of work, or reports a " +
+        "defect \u2014 passing their verbatim message as {prompt: \"...\"} and the skills you already have as {loaded: [...]}. " +
+        "session_bootstrap routes only the first turn of a conversation; this routes every turn after it, so a long " +
+        "session still picks up the skills its current work requires. The prompt is matched ON-DEVICE against the same " +
+        "table and the same account-scoped frontmatter triggers; it never leaves the machine. Calling it is cheap: when " +
+        "nothing new matches it returns a single line, and anything named in `loaded` is never returned again. When it " +
+        "does return skills, read and follow them before doing the work \u2014 they are the rules for the task at hand, " +
+        "not background. Skip it only for follow-ups within work you have already routed.",
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    inputSchema: {
+        type: "object",
+        properties: {
+            prompt: {
+                type: "string",
+                description: "The user's verbatim message for this turn. Matched on-device; never transmitted.",
+            },
+            loaded: {
+                type: "array",
+                items: { type: "string" },
+                description: "Skill names already active in this conversation, including those from the first-turn startup display. " +
+                    "Anything listed here is never returned again, which is what keeps repeat calls free.",
+            },
+            project: {
+                type: "string",
+                description: "Optional project override. Omit to use the session's project.",
+            },
+        },
+        required: ["prompt"],
+    },
+};
 export const SESSION_BOOTSTRAP_TOOL = {
     name: "session_bootstrap",
     description: "IMPORTANT: On the first user turn of every conversation, including a greeting, call this tool exactly once " +

package/dist/tools/skillRouting.js

@@ -210,6 +210,24 @@ async function fetchKeywordTable(expectVersion) {
     }
     if (kwCache && Date.now() - kwCache.at < TABLE_TTL)
         return kwCache.table;
+    // Persisted-first when the version is KNOWN-GOOD. The in-memory cache is
+    // per-process, and the route-prompt CLI is a fresh process on EVERY user
+    // prompt — without this, each prompt made a network GET (measured: a
+    // captive-portal network stalled every prompt 5.5s, and offline routed
+    // nothing because a fresh process had no fallback wired). A persisted
+    // table whose version equals what the manifest sync last reported is
+    // exactly as fresh as a re-download; version bumps still refetch below.
+    if (expectVersion !== undefined && readFn) {
+        try {
+            const stored = await readFn(TABLE_STORAGE_KEY);
+            const parsed = stored ? JSON.parse(stored) : null;
+            if (isKeywordTable(parsed) && parsed.version === expectVersion) {
+                kwCache = { table: parsed, at: Date.now() };
+                return parsed;
+            }
+        }
+        catch { /* fall through to network */ }
+    }
     if (!kwInflight) {
         kwInflight = (async () => {
             try {

package/dist/tools/skillScopeHandlers.js

@@ -231,7 +231,15 @@ export async function skillSaveHandler(args) {
     const where = effectiveScope === "user"
         ? `saved as YOUR account skill (version ${String(body.version)}) — say "make it a team skill" to share it with a workspace`
         : `saved as a TEAM skill for workspace ${String(workspaceId)} (version ${String(body.version)})${Array.isArray(assignTo) && assignTo.length > 0 ? `, targeted to ${assignTo.length} member(s)` : ", delivered to all members"}`;
-    return text(`${where}. Delivery: ${delivery}.`, { scope: effectiveScope, name: skillName, version: body.version });
+    // A skill without triggers is discoverable but never auto-loads — on every
+    // machine it reaches, it behaves exactly like the delivered-but-inert defect
+    // prompt_triggers was built to end. Every pre-trigger scoped skill shipped
+    // this way and each needed a manual backfill; say it at save time, the one
+    // moment the author is present.
+    const routingNote = Object.keys(extractSkillTriggers(skillName, skillContent).triggers).length === 0
+        ? " NOTE: no prompt_triggers declared — this skill appears in host catalogs but will NOT auto-load on matching prompts. Add a prompt_triggers list to its frontmatter to route it."
+        : "";
+    return text(`${where}. Delivery: ${delivery}.${routingNote}`, { scope: effectiveScope, name: skillName, version: body.version });
 }
 export const SKILL_MANAGE_TOOL = {
     name: "skill_manage",

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.10.0",
+  "version": "20.11.0",
   "mcpName": "io.github.dcostenco/prism-coder",
-  "description": "Persistent session memory for AI coding agents that never leaves your machine \u2014 including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
+  "description": "Persistent session memory for AI coding agents that never leaves your machine — including the on-device model that reasons over it. Restores your prior decisions, open TODOs, and changed files across sessions; adds associative recall of related past work, semantic drift detection, and local inference. Local-first by default. Works with Claude Code, Cursor, and Codex.",
   "module": "index.ts",
   "type": "module",
   "main": "dist/server.js",
@@ -32,7 +32,8 @@
     "test:routing:live": "npm run build && node scripts/prism-infer-live-test.mjs",
     "test:routing:models": "npm run build && node scripts/prism-infer-live-test.mjs --infer",
     "test:mcp": "node ./test_cross_mcp.js",
-    "import": "node dist/utils/universalImporter.js"
+    "import": "node dist/utils/universalImporter.js",
+    "postinstall": "node -e \"import('./dist/postinstall.js').catch(()=>{})\""
   },
   "keywords": [
     "mcp-server",

package/scripts/dev/browse.py

@@ -1249,6 +1249,37 @@ def cmd_open(session, url):
     return result
 
 
+def _enforce_max_edge(path, max_edge):
+    """Downscale an image in place so its longest edge is <= max_edge.
+
+    Returns a warning string when the image remains oversized (no scaler
+    available), else None. Never raises: a failed downscale must not turn a
+    real capture into a failure — but it must not stay silent either.
+    """
+    try:
+        import shutil as _shutil, subprocess as _subprocess
+        if _shutil.which("sips"):
+            _subprocess.run(["sips", "-Z", str(max_edge), str(path)],
+                            capture_output=True, timeout=30, check=True)
+            return None
+        try:
+            from PIL import Image  # type: ignore
+            with Image.open(path) as im:
+                w, h = im.size
+                if max(w, h) <= max_edge:
+                    return None
+                scale = max_edge / max(w, h)
+                im.resize((int(w * scale), int(h * scale))).save(path)
+            return None
+        except ImportError:
+            pass
+        return (f"image may exceed {max_edge}px and no scaler is available "
+                f"(sips/Pillow) — large images poison Claude image attach "
+                f"after ~20 images per conversation")
+    except Exception as error:  # noqa: BLE001 — never fail a capture on scaling
+        return f"downscale failed ({error}); image may exceed {max_edge}px"
+
+
 def cmd_screenshot(session, output=None, cleanup=False, full_page=True, selector=None):
     """Capture a screenshot and validate that it is not an empty frame."""
     session.screenshot_counter += 1
@@ -1269,6 +1300,18 @@ def cmd_screenshot(session, output=None, cleanup=False, full_page=True, selector
     else:
         session.page.screenshot(path=str(path), full_page=full_page)
 
+    # ── Anthropic many-image rule (learned live, 2026-08-13) ─────────────
+    # Past ~20 images in a conversation, the API caps every image at 2000px
+    # per dimension and re-validates the WHOLE history on each request. One
+    # oversized capture early in a session poisons every later attach — the
+    # agent that must LOOK at screenshots loses the ability to see them,
+    # mid-conversation, permanently. Full-page captures routinely exceed
+    # 2000px in height, so every capture is normalized to a 1900px long edge
+    # here, at the source. sips is macOS-only; elsewhere we fall back to
+    # Pillow if present and otherwise WARN LOUDLY rather than emit poison
+    # silently.
+    _downscale_warning = _enforce_max_edge(path, 1900)
+
     size = path.stat().st_size
     audit_log("screenshot", str(path), f"size={size},ephemeral={cleanup}")
     result = {
@@ -1281,6 +1324,8 @@ def cmd_screenshot(session, output=None, cleanup=False, full_page=True, selector
     # A blank or error frame must not report success: a screenshot is evidence
     # only if something actually rendered.
     warnings = []
+    if _downscale_warning:
+        warnings.append(_downscale_warning)
     if size < MIN_SCREENSHOT_BYTES:
         result["status"] = "failed"
         warnings.append(f"image is {size} bytes, below the {MIN_SCREENSHOT_BYTES}-byte floor")