prism-mcp-server 20.9.2 → 20.10.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/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/server.js

@@ -336,7 +336,7 @@ export const PRISM_SERVER_INSTRUCTIONS = `Prism MCP — The Mind Palace for AI A
     `Do not substitute session_load_context while session_bootstrap is available; use session_load_context ` +
     `only for an explicit project reload or as an older-server fallback. ` +
     `Use session_save_ledger to log completed work and session_save_handoff to preserve state for the next session. ` +
-    `Reuse the conversation_id returned by session_bootstrap in structuredContent for those saves and for ` +
+    `Reuse the conversation_id from session_bootstrap's <prism_session /> line for those saves and for ` +
     `session_detect_drift, the 60-minute goal-alignment drift check. Do not add the id to the visible greeting.\n\n` +
     `${LOCAL_FIRST_POLICY_TEXT}\n\n` +
     `${EVIDENCE_WORKFLOW_POLICY_TEXT}\n\n` +

package/dist/tools/ledgerHandlers.js

@@ -143,6 +143,15 @@ function stripSkillFrontmatter(raw) {
         return text; // unterminated frontmatter — inline as-is
     return text.slice(text.indexOf("\n", end + 1) + 1).trim();
 }
+/**
+ * Room reserved for the trailing <prism_session /> facts line so it never
+ * competes with the skill block. The allocator below already subtracts
+ * systemReadyBlock.length — skills are protected and PROJECTS absorb budget
+ * pressure — so the facts line is reserved the same way rather than capping
+ * the assembled text, which truncates from the TAIL and would eat the very
+ * skill block this whole fix exists to deliver.
+ */
+const SESSION_FACTS_RESERVE = 256;
 const NATIVE_STARTUP_MAX_CHARS = {
     quick: 4_000,
     standard: 8_000,
@@ -1425,7 +1434,13 @@ export async function sessionLoadContextHandler(args, options = {}) {
                 // here; without it a stale cached table would never be detected on
                 // this path, since there is no portal response to compare against.
                 const manifestVersion = Number(await getSetting("skill_manifest:routing_version", ""));
-                const matched = (await resolvePromptSkillNames(prompt, Number.isFinite(manifestVersion) && manifestVersion > 0 ? manifestVersion : undefined)).filter((name) => entitledSkillNames.has(name));
+                // Account/team skills can never appear in the PUBLIC routing table —
+                // listing a private skill's name and trigger words in a world-readable
+                // file is the leak this feature exists to avoid — so they declare
+                // `prompt_triggers` in their own frontmatter and are matched here, on
+                // device, from bodies already cached for injection.
+                const scoped = await collectSkillTriggersOnThisMachine();
+                const matched = (await resolvePromptSkillNames(prompt, Number.isFinite(manifestVersion) && manifestVersion > 0 ? manifestVersion : undefined, scoped?.triggers)).filter((name) => entitledSkillNames.has(name) || scoped?.localNames.has(name));
                 if (matched.length > 0) {
                     const shown = matched.slice(0, MAX_SYMPTOM_SKILLS);
                     const overflow = matched.length - shown.length;
@@ -1789,6 +1804,108 @@ export async function seedAndRecallDemoMemory(conversationId) {
         return null;
     }
 }
+/**
+ * Machine-readable session facts, carried INSIDE the text block.
+ *
+ * Why not `structuredContent`: a tool result may carry both a text block and
+ * `structuredContent`, and a host is free to surface only the latter — Claude
+ * Code does exactly that, so from 2026-07-22 (when structuredContent was added
+ * here) until this fix, every Claude Code session received these 129 bytes of
+ * JSON and NONE of the ~7KB startup text: no memory context, no protected
+ * skill floor, no symptom-triggered skills. Measured three ways: a text-only
+ * tool (session_health_check) arrived intact, this one and skill_manage did
+ * not, and Claude Code v2.1.212 delivered the full text before the change and
+ * 129 bytes after it — same host version, so the regression was ours.
+ *
+ * MCP pairs `structuredContent` with an `outputSchema`; Prism declares none,
+ * so emitting it was out of spec and a host preferring it is reasonable. The
+ * facts now ride in the text, which every host renders.
+ */
+export function buildSessionFactsLine(facts) {
+    // Attribute-safe, NOT markdown-escaped: escapeNativeMarkdown backslashes
+    // hyphens, which corrupts every UUID it touches (`conv-abc` → `conv\-abc`)
+    // and would make the id unusable by the caller it exists for. Strip only
+    // what can break out of the attribute or the line.
+    const safe = (value) => value.replace(/[\u0000-\u001f\u007f"<>]+/g, " ").trim();
+    const attrs = Object.entries(facts)
+        .map(([key, value]) => `${key}="${safe(String(Array.isArray(value) ? value.join(",") : value))}"`)
+        .join(" ");
+    return `<prism_session ${attrs} />`;
+}
+/**
+ * Prompt triggers declared by skills on this machine.
+ *
+ * Two sources, because a skill can reach a machine two ways:
+ *   - the `skill:<name>` settings cache, which backs body injection for every
+ *     DELIVERED skill (platform, account, team); and
+ *   - local skill directories, for skills saved with scope "local", which are
+ *     written straight to disk and never enter that cache.
+ *
+ * Missing the second source made `prompt_triggers` silently do nothing for
+ * local skills — the same "configured and inert" experience the feature exists
+ * to remove. Local skill NAMES are returned too: the caller filters matches by
+ * entitlement, and a local skill is not in the entitlement manifest, so without
+ * this it would match and then be discarded. A file the user wrote on their own
+ * machine needs no entitlement.
+ *
+ * Failures are swallowed — a broken trigger degrades to "the public table
+ * only", never takes down startup.
+ */
+async function collectSkillTriggersOnThisMachine() {
+    try {
+        const { collectScopedTriggers, collectLocalSkillTriggers } = await import("./scopedSkillTriggers.js");
+        const merged = {};
+        const localNames = new Set();
+        const errors = [];
+        const settings = await getAllSettings();
+        const bodies = [];
+        for (const [key, value] of Object.entries(settings)) {
+            if (key.startsWith("skill:") && value)
+                bodies.push([key.slice("skill:".length), value]);
+        }
+        if (bodies.length > 0) {
+            const delivered = collectScopedTriggers(bodies);
+            for (const [pattern, names] of Object.entries(delivered.triggers)) {
+                (merged[pattern] ||= []).push(...names);
+            }
+            errors.push(...delivered.errors);
+        }
+        // Isolated: a disk problem (or a host without the local root) must not cost
+        // us the DELIVERED skills' triggers, which are already in hand.
+        try {
+            const { readdir, stat, readFile } = await import("node:fs/promises");
+            const { join } = await import("node:path");
+            // The skills root is overridable per caller and per home; skillManifestSync
+            // owns it. Scanning the canonical root alone is sufficient because
+            // skill_save writes every local skill there before mirroring.
+            const { resolveCanonicalSkillsDir } = await import("../skillManifestSync.js");
+            const local = await collectLocalSkillTriggers([resolveCanonicalSkillsDir()], {
+                readdir: (path) => readdir(path),
+                stat: async (path) => ({ size: (await stat(path)).size }),
+                readFile: (path) => readFile(path, "utf8"),
+            }, join);
+            for (const [pattern, names] of Object.entries(local.triggers)) {
+                (merged[pattern] ||= []).push(...names);
+            }
+            for (const name of local.names)
+                localNames.add(name);
+            errors.push(...local.errors);
+        }
+        catch (error) {
+            debugLog(`[skill-triggers] local scan skipped: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        for (const error of errors) {
+            // Loud, not silent: a rejected trigger looks exactly like the defect this
+            // feature fixes — a skill that is installed and never fires.
+            debugLog(`[skill-triggers] ignored trigger in "${error.skill}": ${error.reason}`);
+        }
+        return Object.keys(merged).length > 0 ? { triggers: merged, localNames } : undefined;
+    }
+    catch (error) {
+        debugLog(`[skill-triggers] collection failed: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+}
 export async function sessionBootstrapHandler(args = {}, options = {}) {
     if (typeof args !== "object" || args === null || Array.isArray(args)) {
         throw new Error("Invalid arguments for session_bootstrap");
@@ -1877,10 +1994,9 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
             return {
                 content: [{
                         type: "text",
-                        text: capNativeStartupText(firstRunText, depth),
+                        text: capNativeStartupText(firstRunText, depth, undefined, `\n\n${buildSessionFactsLine({ conversation_id: conversationId, projects: "", depth, first_run: true })}`),
                     }],
                 isError: false,
-                structuredContent: { conversation_id: conversationId, projects: [], depth, first_run: true },
             };
         }
         const unconfiguredState = (depth === "quick" ? "" : `\n- 📝 **Last Session Summary:** Not loaded`) +
@@ -1891,10 +2007,9 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
         return {
             content: [{
                     type: "text",
-                    text: capNativeStartupText(noProjectsText, depth),
+                    text: capNativeStartupText(noProjectsText, depth, undefined, `\n\n${buildSessionFactsLine({ conversation_id: conversationId, projects: "", depth })}`),
                 }],
             isError: false,
-            structuredContent: { conversation_id: conversationId, projects: [], depth },
         };
     }
     const startupMaxChars = NATIVE_STARTUP_MAX_CHARS[depth];
@@ -1909,7 +2024,7 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
         const omissionLength = omittedProjectsText ? omittedProjectsText.length + 2 : 0;
         const separatorsLength = Math.max(0, renderedProjectCount - 1) * 2;
         perProjectMaxChars = Math.floor((startupMaxChars - startupHeader.length - systemReadyBlock.length - LOCAL_STARTUP_FALLBACK_NOTICE.length -
-            6 - omissionLength - separatorsLength) /
+            SESSION_FACTS_RESERVE - 6 - omissionLength - separatorsLength) /
             renderedProjectCount);
         if (perProjectMaxChars >= 512 || renderedProjectCount === 1)
             break;
@@ -1970,15 +2085,17 @@ export async function sessionBootstrapHandler(args = {}, options = {}) {
                 type: "text",
                 text: `${startupHeader}\n\n${fallbackNotice}${startupContext.loaded.join("\n\n")}` +
                     (omittedProjectsText ? `\n\n${omittedProjectsText}` : "") +
-                    `\n\n${systemReadyBlock}`,
+                    `\n\n${systemReadyBlock}` +
+                    // Appended, not capped: SESSION_FACTS_RESERVE already bought this room
+                    // out of the PROJECT budget, so nothing here can displace the skills.
+                    `\n\n${buildSessionFactsLine({
+                        conversation_id: conversationId,
+                        projects: compactWithOmissionCount(renderedProjects.join(","), 120),
+                        depth,
+                        context_source: usedLocalFallback ? "local-last-good" : activeStorageBackend,
+                    })}`,
             }],
         isError: startupContext.hadError,
-        structuredContent: {
-            conversation_id: conversationId,
-            projects: renderedProjects,
-            depth,
-            context_source: usedLocalFallback ? "local-last-good" : activeStorageBackend,
-        },
     };
 }
 export async function memoryHistoryHandler(args) {

package/dist/tools/scopedSkillTriggers.js

@@ -0,0 +1,228 @@
+/**
+ * Prompt triggers declared by a skill, in its own frontmatter.
+ *
+ * WHY THIS EXISTS
+ * Prompt-keyword routing matches against the PUBLIC, unauthenticated routing
+ * table (`/_internal/skills-routing.json`). A private account or team skill can
+ * never be listed there — the name and its trigger words would be world
+ * readable — so scoped skills were delivered to disk and then never surfaced by
+ * any prompt. They were installed and inert.
+ *
+ * The fix keeps the trigger exactly as private as the body that declares it:
+ *
+ *     ---
+ *     name: my-skill
+ *     description: …
+ *     prompt_triggers:
+ *       - "\\binvoice\\b.{0,20}\\bsubmit\\b"
+ *       - "quarterly close"
+ *     ---
+ *
+ * The body already reaches this machine through the AUTHENTICATED manifest and
+ * is cached as `skill:<name>`, so the triggers ride along with it. Nothing new
+ * is transmitted, no schema changes, and matching stays on-device — the user's
+ * prompt still never leaves the machine.
+ *
+ * SAFETY: these patterns come from user-authored content and are compiled on the
+ * startup path, where a pathological regex would hang every session for everyone
+ * the skill is shared with. Limits below are deliberately strict, and anything
+ * rejected is reported rather than silently dropped — a trigger that never fires
+ * is indistinguishable from the bug this file fixes.
+ */
+/** Per skill. A skill needing more than this is describing too much. */
+export const MAX_TRIGGERS_PER_SKILL = 5;
+/** Per pattern. Long patterns are where catastrophic backtracking hides. */
+export const MAX_TRIGGER_LENGTH = 200;
+/**
+ * Reject patterns that can backtrack catastrophically.
+ *
+ * RULE: a group may not be quantified. Exponential backtracking needs the
+ * engine to try many different ways to split the SAME substring, and in
+ * practice that requires a repeated group — `(a+)+`, `(a|aa)+`, `(\w+\s?)*`,
+ * `(.*a){20}`. Refusing `)` followed by `+`, `*` or `{n,m}` kills the whole
+ * family with one check that is trivial to read and cannot be argued with.
+ *
+ * This replaced a shape-matching heuristic that only caught the textbook
+ * `(a+)+`. Measured against it, `((a+))+` slipped through nested parens and
+ * `(a|aa)+` — the canonical example — slipped through because it contains no
+ * inner quantifier at all; the latter took 447ms on 36 characters and grows
+ * exponentially, so a trigger inside the 200-char cap could hang startup for
+ * every member of a team it is shared with. JavaScript has no regex timeout:
+ * once a match begins there is no way to interrupt it, which is why this must
+ * be refused BEFORE compilation rather than bounded at runtime.
+ *
+ * Cost: a legitimate quantified group must be rewritten. Every trigger shape
+ * seen in practice — word boundaries, proximity via `.{0,n}`, alternation
+ * without repetition — is unaffected.
+ */
+function isCatastrophic(pattern) {
+    return /\)\s*(?:[+*]|\{\d+(?:,\d*)?\})/.test(pattern);
+}
+function validateTrigger(pattern) {
+    if (!pattern.trim())
+        return "empty pattern";
+    if (pattern.length > MAX_TRIGGER_LENGTH)
+        return `pattern exceeds ${MAX_TRIGGER_LENGTH} chars`;
+    if (isCatastrophic(pattern))
+        return "a quantified group can backtrack catastrophically — rewrite without repeating a group";
+    try {
+        new RegExp(pattern, "i");
+    }
+    catch (error) {
+        return `invalid regex: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    return null;
+}
+/**
+ * Strip surrounding quotes, applying YAML's double-quote escaping.
+ *
+ * This matters more than it looks. In a double-quoted YAML scalar `\\b` means
+ * a single backslash followed by b — i.e. the regex `\b` — so an author writing
+ * the natural `- "\\binvoice\\b"` must get a word-boundary matcher. Passing
+ * the raw text through instead yields `\\binvoice\\b`, which matches a literal
+ * backslash and therefore NEVER fires: a skill that looks correctly configured
+ * and is silently inert, which is the exact defect this file exists to end.
+ * Single-quoted and bare scalars are taken literally, as YAML specifies.
+ */
+function unquote(value) {
+    const doubleQuoted = value.match(/^"(.*)"$/);
+    if (doubleQuoted)
+        return doubleQuoted[1].replace(/\\\\/g, "\\");
+    const singleQuoted = value.match(/^'(.*)'$/);
+    if (singleQuoted)
+        return singleQuoted[1];
+    return value;
+}
+/**
+ * Pull `prompt_triggers` out of one skill body.
+ *
+ * Supports both YAML shapes authors actually write — a block list and an inline
+ * array — without adding a YAML dependency, matching the hand-rolled frontmatter
+ * reader already used by skill_save so the two agree on what a skill file is.
+ */
+export function extractSkillTriggers(skillName, content) {
+    const result = { triggers: {}, errors: [] };
+    const frontmatter = content.match(/^---\n([\s\S]*?)\n---/);
+    if (!frontmatter)
+        return result;
+    const body = frontmatter[1];
+    const raw = [];
+    const inline = body.match(/^prompt_triggers:\s*\[(.*)\]\s*$/m);
+    if (inline) {
+        for (const item of inline[1].split(",")) {
+            const value = unquote(item.trim());
+            if (value)
+                raw.push(value);
+        }
+    }
+    else {
+        const blockStart = body.match(/^prompt_triggers:\s*$/m);
+        if (blockStart) {
+            const after = body.slice(body.indexOf(blockStart[0]) + blockStart[0].length);
+            for (const line of after.split("\n")) {
+                // Stop at the next top-level key: an unterminated list must not swallow
+                // the rest of the frontmatter and turn `description:` into a trigger.
+                if (/^[A-Za-z_-]+:/.test(line))
+                    break;
+                const item = line.match(/^\s*-\s*(.+?)\s*$/);
+                if (!item)
+                    continue;
+                raw.push(unquote(item[1]));
+            }
+        }
+    }
+    if (raw.length === 0)
+        return result;
+    for (const pattern of raw.slice(0, MAX_TRIGGERS_PER_SKILL)) {
+        const problem = validateTrigger(pattern);
+        if (problem) {
+            result.errors.push({ skill: skillName, pattern: pattern.slice(0, 80), reason: problem });
+            continue;
+        }
+        (result.triggers[pattern] ||= []).push(skillName);
+    }
+    for (const pattern of raw.slice(MAX_TRIGGERS_PER_SKILL)) {
+        result.errors.push({
+            skill: skillName,
+            pattern: pattern.slice(0, 80),
+            reason: `exceeds ${MAX_TRIGGERS_PER_SKILL} triggers per skill`,
+        });
+    }
+    return result;
+}
+/**
+ * Merge the triggers declared by every cached skill body.
+ *
+ * `skills` is the `skill:<name> -> content` cache that already backs body
+ * injection, so this covers exactly the entitled set: anything routable here is
+ * something the caller is allowed to inline, and nothing else.
+ */
+/**
+ * Read triggers from LOCAL skill files (`~/.agents/skills`, `~/.claude/skills`).
+ *
+ * Local is a first-class scope in skill_save, but local skills are written
+ * straight to disk and never enter the `skill:<name>` settings cache, so a
+ * trigger declared in one would have been read by nothing — the author gets the
+ * same "configured and inert" experience this whole feature exists to remove.
+ *
+ * Bounded deliberately: this runs on the startup path. Files are skipped above
+ * MAX_LOCAL_FILE_BYTES, at most MAX_LOCAL_SKILLS directories are considered, and
+ * every error is swallowed per-entry — an unreadable skill directory must not be
+ * able to fail a session.
+ */
+const MAX_LOCAL_SKILLS = 300;
+const MAX_LOCAL_FILE_BYTES = 64 * 1024;
+export async function collectLocalSkillTriggers(roots, fs, join) {
+    const merged = { triggers: {}, errors: [], names: [] };
+    let budget = MAX_LOCAL_SKILLS;
+    const seen = new Set();
+    for (const root of roots) {
+        let entries;
+        try {
+            entries = await fs.readdir(root);
+        }
+        catch {
+            continue; // root absent — normal
+        }
+        for (const name of entries) {
+            if (budget-- <= 0)
+                break;
+            if (seen.has(name))
+                continue; // same skill mirrored in both roots
+            const path = join(root, name, "SKILL.md");
+            try {
+                const info = await fs.stat(path);
+                if (info.size > MAX_LOCAL_FILE_BYTES)
+                    continue;
+                const content = await fs.readFile(path);
+                if (!content.includes("prompt_triggers"))
+                    continue;
+                seen.add(name);
+                const extracted = extractSkillTriggers(name, content);
+                if (Object.keys(extracted.triggers).length > 0)
+                    merged.names.push(name);
+                for (const [pattern, names] of Object.entries(extracted.triggers)) {
+                    (merged.triggers[pattern] ||= []).push(...names);
+                }
+                merged.errors.push(...extracted.errors);
+            }
+            catch {
+                continue; // not a skill dir, or unreadable
+            }
+        }
+    }
+    return merged;
+}
+export function collectScopedTriggers(skills) {
+    const merged = { triggers: {}, errors: [] };
+    for (const [name, content] of skills) {
+        if (!content || !content.includes("prompt_triggers"))
+            continue; // cheap pre-filter
+        const extracted = extractSkillTriggers(name, content);
+        for (const [pattern, names] of Object.entries(extracted.triggers)) {
+            (merged.triggers[pattern] ||= []).push(...names);
+        }
+        merged.errors.push(...extracted.errors);
+    }
+    return merged;
+}

package/dist/tools/sessionMemoryDefinitions.js

@@ -172,7 +172,7 @@ export const SESSION_BOOTSTRAP_TOOL = {
         "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. Do not guess or pass a project or depth. Prism returns a stable " +
-        "conversation_id in structuredContent; reuse it for session_save_ledger, session_save_handoff, and " +
+        "conversation_id on the trailing <prism_session /> line; reuse it for session_save_ledger, session_save_handoff, and " +
         "session_detect_drift throughout this conversation without adding it to the visible greeting.",
     annotations: {
         readOnlyHint: true,
@@ -185,7 +185,7 @@ export const SESSION_BOOTSTRAP_TOOL = {
         properties: {
             conversation_id: {
                 type: "string",
-                description: "Optional stable key for this conversation. When omitted, Prism generates one and returns it in structuredContent.",
+                description: "Optional stable key for this conversation. When omitted, Prism generates one and returns it on the trailing <prism_session /> line.",
             },
             prompt: {
                 type: "string",

package/dist/tools/skillRouting.js

@@ -310,13 +310,22 @@ export function _applyPromptRouting(base, prompt, promptKeywords) {
  *   path has no portal response, so without this it could serve a stale table
  *   indefinitely and never detect drift). The skill manifest carries one.
  */
-export async function resolvePromptSkillNames(prompt, expectVersion) {
+export async function resolvePromptSkillNames(prompt, expectVersion, scopedTriggers) {
     if (!prompt)
         return [];
     const kw = await fetchKeywordTable(expectVersion);
-    if (!kw)
+    // Scoped triggers must still route when the PUBLIC table is unavailable:
+    // they are declared in skill bodies already on this machine and owe nothing
+    // to a network fetch. Returning [] here would make a private skill's routing
+    // depend on a public file it can never appear in.
+    const publicKeywords = kw?.prompt_keywords ?? {};
+    if (!kw && !scopedTriggers)
         return [];
-    return _applyPromptRouting([], prompt, kw.prompt_keywords).map((s) => s.name);
+    const combined = { ...publicKeywords };
+    for (const [pattern, names] of Object.entries(scopedTriggers ?? {})) {
+        combined[pattern] = [...(combined[pattern] ?? []), ...names];
+    }
+    return _applyPromptRouting([], prompt, combined).map((s) => s.name);
 }
 /**
  * Free tier resolves to an empty set portal-side, so adding prompt-matched

package/dist/tools/skillScopeHandlers.js

@@ -23,6 +23,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { getSetting } from "../storage/configStorage.js";
 import { getSynaluxJwt } from "../utils/synaluxJwt.js";
+import { extractSkillTriggers } from "./scopedSkillTriggers.js";
 import { triggerSkillManifestSync } from "../skillManifestSync.js";
 import { mkdirUsable } from "../utils/usableDirectory.js";
 const STRICT_SKILL_NAME = /^[a-z0-9][a-z0-9_-]{0,127}$/;
@@ -31,8 +32,19 @@ const STRICT_SKILL_NAME = /^[a-z0-9][a-z0-9_-]{0,127}$/;
 const MAX_CONTENT_BYTES = 25_000;
 const MAX_DESCRIPTION_CHARS = 500;
 const API_PATH = "/api/v1/prism/user-skills";
+/**
+ * Structured data is SERIALIZED INTO the text, never returned as
+ * `structuredContent`. A host may surface structuredContent and drop the text
+ * block — Claude Code does — which silently discarded every explanation this
+ * tool produced ("saved as YOUR account skill", the floor-guard refusal, the
+ * how-to-share hint), leaving raw JSON. See buildSessionFactsLine in
+ * ledgerHandlers.ts for the measurements behind this rule.
+ */
 function text(message, extra, isError = false) {
-    return { content: [{ type: "text", text: message }], ...(isError ? { isError } : {}), ...(extra ? { structuredContent: extra } : {}) };
+    const body = extra
+        ? `${message}\n\n\`\`\`json\n${JSON.stringify(extra, null, 2)}\n\`\`\``
+        : message;
+    return { content: [{ type: "text", text: body }], ...(isError ? { isError } : {}) };
 }
 async function synaluxBaseUrl() {
     const configured = process.env.PRISM_SYNALUX_BASE_URL?.trim() || process.env.SYNALUX_BASE_URL?.trim() ||
@@ -64,6 +76,23 @@ function frontmatterProblems(name, content) {
     }
     return null;
 }
+/**
+ * Refuse a bad `prompt_triggers` entry at SAVE time.
+ *
+ * The on-device collector already skips invalid patterns, so nothing unsafe can
+ * reach the matcher either way — but a silently skipped trigger is exactly the
+ * symptom this feature was built to remove: a skill that looks configured and
+ * never fires. Failing the save is the only point where the author is present
+ * to read the reason.
+ */
+function triggerProblems(name, content) {
+    const { errors } = extractSkillTriggers(name, content);
+    if (errors.length === 0)
+        return null;
+    const first = errors[0];
+    return `prompt_triggers rejected ("${first.pattern}"): ${first.reason}. ` +
+        `A trigger that cannot compile would leave this skill installed but never activated.`;
+}
 function validateSkillInput(name, content) {
     if (typeof name !== "string" || !STRICT_SKILL_NAME.test(name)) {
         return "invalid skill name: lowercase letters, digits, - and _ only (max 128 chars)";
@@ -73,7 +102,10 @@ function validateSkillInput(name, content) {
     if (Buffer.byteLength(content, "utf8") > MAX_CONTENT_BYTES) {
         return `content exceeds the ${MAX_CONTENT_BYTES}-byte context-fit limit shared by every delivered skill; move reference material out or split it`;
     }
-    return frontmatterProblems(name, content);
+    const frontmatter = frontmatterProblems(name, content);
+    if (frontmatter)
+        return frontmatter;
+    return triggerProblems(name, content);
 }
 /** Local skill roots that hosts read natively. Never Prism-managed dirs. */
 function localSkillRoots() {
@@ -145,7 +177,11 @@ export const SKILL_SAVE_TOOL = {
     description: "Save a skill at one of three scopes: local (this machine only, works signed out), " +
         "user (your account — follows you to every machine), or team (a workspace — delivered to its members; " +
         "owner/admin only, optionally targeted with assign_to). Default when signed in is USER; team is never " +
-        "a default. Content must be a SKILL.md body with frontmatter (name, description).",
+        "a default. Content must be a SKILL.md body with frontmatter (name, description). " +
+        "To make the skill load automatically when a prompt matches, add prompt_triggers to the " +
+        "frontmatter — a list of up to 5 case-insensitive regexes. They stay as private as the skill " +
+        "itself (matching happens on-device; scoped skills cannot use the public routing table):\n" +
+        "  prompt_triggers:\n    - \"\\\\binvoice\\\\b.{0,20}\\\\bsubmit\\\\b\"",
     inputSchema: {
         type: "object",
         properties: {

package/dist/utils/skillBudget.js

@@ -80,14 +80,30 @@ export function assembleSkillBlock(entries, budgetChars) {
     const ordered = [...entries].sort(fillOrder);
     const unbudgeted = !Number.isFinite(budgetChars) || budgetChars <= 0;
     let block = "";
+    let unprotectedChars = 0;
     const inlined = [];
     const overflow = [];
     for (const e of ordered) {
         const piece = render(e);
-        // Protected always inline; others only while they fit.
-        if (unbudgeted || e.protected || block.length + piece.length <= budgetChars) {
+        // Protected always inline and NEVER debit the budget: the tranche is
+        // documented as ADDITIVE on top of the floor. The previous check
+        // compared block.length — which the floor had already filled — so with
+        // a ~46KB floor against 2-16KB tranches, NO unprotected skill ever
+        // inlined at any normal budget. Rank was irrelevant; the budget was
+        // pre-spent. Found 2026-08-11 tracing why a prompt-matched
+        // verified-shipping still sat in overflow while an agent shipped
+        // unverified UI claims; the 2026-08-03 note ("no unprotected universal
+        // was ever inlined") had recorded this symptom and it was treated by
+        // protecting one skill instead of fixing the accounting.
+        if (unbudgeted || e.protected) {
             block += piece;
             inlined.push(e.name);
+            continue;
+        }
+        if (unprotectedChars + piece.length <= budgetChars) {
+            block += piece;
+            unprotectedChars += piece.length;
+            inlined.push(e.name);
         }
         else {
             overflow.push(e.name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prism-mcp-server",
-  "version": "20.9.2",
+  "version": "20.10.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.",
   "module": "index.ts",