@sema-agent/core 5.59.0 → 5.60.1

package/dist/core/context-edit.js

@@ -1,7 +1,11 @@
+import { createHash } from "node:crypto";
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
-import { offloadPagebackHint } from "./tool-result-store.js";
+import { PERSISTED_OUTPUT_PREFIX, offloadPagebackHint } from "./tool-result-store.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
+const CC_CLEARED_MARKER = "[Old tool result content cleared]";
+const LEGACY_CLEARED_EXTENDED_PREFIX = "[tool result cleared to save context —";
+const CC_CLEARED_EXTENDED_PREFIX = "[Old tool result content cleared —";
 const refNote = (ref) => offloadPagebackHint(ref, "cleared");
 const mediaNote = (blocks) => {
     const byType = new Map();
@@ -17,9 +21,10 @@ const mediaNote = (blocks) => {
     const breakdown = [...byType].map(([t, c]) => `${c} ${t}`).join(", ");
     return `${n} attachments (${breakdown}) no longer visible after this clear`;
 };
-const clearedMarker = (notes) => {
+const clearedMarker = (notes, machine = "legacy") => {
     const present = notes.filter((n) => n !== undefined);
-    return present.length > 0 ? `[tool result cleared to save context — ${present.join("; ")}]` : CLEARED_MARKER;
+    const [plain, extendedPrefix] = machine === "cc" ? [CC_CLEARED_MARKER, CC_CLEARED_EXTENDED_PREFIX] : [CLEARED_MARKER, LEGACY_CLEARED_EXTENDED_PREFIX];
+    return present.length > 0 ? `${extendedPrefix} ${present.join("; ")}]` : plain;
 };
 export const EDIT_FRACTION = 0.7;
 export const CONTEXT_OUTPUT_RESERVE_TOKENS = 20000;
@@ -28,13 +33,16 @@ export function contextEditFrontier(window) {
     return Math.max(window - (CONTEXT_OUTPUT_RESERVE_TOKENS + COMPACTION_TRIGGER_BUFFER_TOKENS), Math.floor(window * EDIT_FRACTION));
 }
 export const DEFAULT_KEEP_RECENT_TOOL_RESULTS = 3;
+export const CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS = 5;
+export const MIN_CLEAR_SAVINGS_TOKENS = 20000;
+const MEDIA_BLOCK_SAVINGS_TOKENS = 2000;
 export const MIN_KEEP_RECENT_TOOL_RESULTS = 1;
-function resolveKeepRecentToolResults(value) {
+function resolveKeepRecentToolResults(value, defaultValue) {
     if (value === undefined)
-        return DEFAULT_KEEP_RECENT_TOOL_RESULTS;
+        return defaultValue;
     if (!Number.isSafeInteger(value) || value < 0) {
         throw new TypeError(`keepRecentToolResults must be a non-negative safe integer (got ${String(value)}); ` +
-            `omit it for the default ${DEFAULT_KEEP_RECENT_TOOL_RESULTS}`);
+            `omit it for the default ${defaultValue}`);
     }
     return Math.max(MIN_KEEP_RECENT_TOOL_RESULTS, value);
 }
@@ -49,12 +57,29 @@ export const COMPACTABLE_TOOLS = new Set([
     "Edit",
     "Write",
 ]);
-function isCleared(m) {
+function soleMarkerText(m) {
     const content = m.content;
     if (!Array.isArray(content) || content.length !== 1)
-        return false;
+        return undefined;
     const text = content[0].text;
-    return text === CLEARED_MARKER || (typeof text === "string" && text.startsWith("[tool result cleared to save context —"));
+    return typeof text === "string" ? text : undefined;
+}
+function isCleared(m, recognizeCcForms = false) {
+    const text = soleMarkerText(m);
+    if (text === undefined)
+        return false;
+    if (text === CLEARED_MARKER || text.startsWith(LEGACY_CLEARED_EXTENDED_PREFIX))
+        return true;
+    return recognizeCcForms && (text === CC_CLEARED_MARKER || text.startsWith(CC_CLEARED_EXTENDED_PREFIX));
+}
+function isCcCleared(m) {
+    if (isCleared(m, true))
+        return true;
+    const content = m.content;
+    if (!Array.isArray(content) || content.length === 0)
+        return false;
+    const first = content[0];
+    return first?.type === "text" && typeof first.text === "string" && first.text.startsWith(PERSISTED_OUTPUT_PREFIX);
 }
 export function dropEmptyFailureAssistants(messages) {
     const isJunk = (m) => {
@@ -67,8 +92,56 @@ export function dropEmptyFailureAssistants(messages) {
     };
     return messages.some(isJunk) ? messages.filter((m) => !isJunk(m)) : messages;
 }
+function structuralClearSavings(target) {
+    const content = Array.isArray(target.content) ? target.content : [];
+    let saved = 0;
+    for (const c of content) {
+        const block = c;
+        if (block?.type === "text") {
+            saved += typeof block.text === "string" ? Math.round(block.text.length / 4) : 0;
+        }
+        else {
+            saved += MEDIA_BLOCK_SAVINGS_TOKENS;
+        }
+    }
+    return saved;
+}
+function clearOneResult(target, offload, machine) {
+    const rawContent = Array.isArray(target.content) ? target.content : [];
+    let ref;
+    if (offload) {
+        const fullText = rawContent
+            .filter((c) => c?.type === "text" && typeof c.text === "string")
+            .map((c) => c.text)
+            .join("\n");
+        if (target.toolCallId && fullText.trim().length > 0) {
+            try {
+                ref = refNote(offload.persist(target.toolCallId, fullText));
+            }
+            catch {
+                ref = undefined;
+            }
+        }
+    }
+    const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
+    const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined], machine);
+    return { ...target, content: [{ type: "text", text: marker }] };
+}
+function reportCleared(onCleared, clears, tokensSavedEstimate) {
+    if (!onCleared || clears.length === 0)
+        return;
+    try {
+        onCleared({ clears, tokensSavedEstimate });
+    }
+    catch {
+    }
+}
 export function clearStaleToolResults(messages, opts) {
     const cpt = opts.charsPerToken ?? DEFAULT_CHARS_PER_TOKEN;
+    const machine = opts.machine ?? "legacy";
+    if (machine !== "legacy" && machine !== "cc") {
+        throw new TypeError(`machine must be "legacy" | "cc" (got ${String(machine)}); omit it for the default "legacy"`);
+    }
     const anchored = opts.anchoredTotalTokens !== undefined;
     let total;
     let anchorIdx = -1;
@@ -85,48 +158,190 @@ export function clearStaleToolResults(messages, opts) {
     if (total <= opts.budgetTokens) {
         return messages;
     }
-    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults);
+    if (machine === "cc") {
+        return clearStaleToolResultsCc(messages, opts);
+    }
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, DEFAULT_KEEP_RECENT_TOOL_RESULTS);
     const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
-    const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
+    const toolResultCandidates = messages.flatMap((m, i) => isToolResult(m) && !isCleared(m, opts.recognizeCcMarkers === true) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
     const clearable = toolResultCandidates.slice(0, Math.max(0, toolResultCandidates.length - keep));
     if (clearable.length === 0) {
         return messages;
     }
     const out = messages.slice();
     let current = total;
+    const clears = [];
+    let savedEstimate = 0;
     for (const { idx, target } of clearable) {
         if (current <= opts.budgetTokens) {
             break;
         }
         const before = estimateTokens(target, cpt);
-        const rawContent = Array.isArray(target.content) ? target.content : [];
-        let ref;
-        if (opts.offload) {
-            const fullText = rawContent
-                .filter((c) => c?.type === "text" && typeof c.text === "string")
-                .map((c) => c.text)
-                .join("\n");
-            if (target.toolCallId && fullText.trim().length > 0) {
-                try {
-                    ref = refNote(opts.offload.persist(target.toolCallId, fullText));
-                }
-                catch {
-                    ref = undefined;
-                }
-            }
-        }
-        const mediaBlocks = rawContent.filter((c) => c?.type !== "text");
-        const marker = clearedMarker([ref, mediaBlocks.length > 0 ? mediaNote(mediaBlocks) : undefined]);
-        const cleared = { ...target, content: [{ type: "text", text: marker }] };
+        const cleared = clearOneResult(target, opts.offload, "legacy");
         out[idx] = cleared;
-        current -= idx > anchorIdx ? before - estimateTokens(cleared, cpt) : 0;
+        clears.push({ index: idx });
+        const delta = before - estimateTokens(cleared, cpt);
+        savedEstimate += delta;
+        current -= idx > anchorIdx ? delta : 0;
     }
+    reportCleared(opts.onCleared, clears, savedEstimate);
     return out;
 }
+function clearStaleToolResultsCc(messages, opts) {
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS);
+    const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
+    const candidates = messages.flatMap((m, i) => isToolResult(m) && compactable.has(m.toolName) ? [{ idx: i, target: m }] : []);
+    const beyondKeep = candidates.slice(0, Math.max(0, candidates.length - keep));
+    const clearable = beyondKeep.filter(({ target }) => !isCcCleared(target));
+    if (clearable.length === 0) {
+        return messages;
+    }
+    const tokensSaved = clearable.reduce((sum, { target }) => sum + structuralClearSavings(target), 0);
+    if (tokensSaved < MIN_CLEAR_SAVINGS_TOKENS) {
+        return messages;
+    }
+    const out = messages.slice();
+    const clears = [];
+    for (const { idx, target } of clearable) {
+        const src = opts.clearSource?.[idx];
+        const source = src !== undefined && isToolResult(src) && src.toolCallId === target.toolCallId ? src : target;
+        out[idx] = clearOneResult(source, opts.offload, "cc");
+        clears.push({ index: idx });
+    }
+    reportCleared(opts.onCleared, clears, tokensSaved);
+    return out;
+}
+export function resolveTriggerWindow(model) {
+    const physical = model.contextTokens ?? model.contextWindow;
+    const declared = model.autoCompactTokens;
+    if (declared !== undefined &&
+        Number.isFinite(declared) &&
+        declared > 0 &&
+        Number.isFinite(physical) &&
+        physical > 0 &&
+        declared > physical) {
+        return { window: physical, clamped: true, declaredAutoCompactTokens: declared, physicalWindow: physical };
+    }
+    return { window: declared ?? physical, clamped: false };
+}
 export function editBudget(model) {
-    const window = model.autoCompactTokens ?? model.contextTokens ?? model.contextWindow;
+    const window = resolveTriggerWindow(model).window;
     if (!Number.isFinite(window) || window <= 0) {
         return Number.POSITIVE_INFINITY;
     }
     return contextEditFrontier(window);
 }
+export function fingerprintToolResultOccurrence(m) {
+    const content = Array.isArray(m.content)
+        ? (m.content)
+        : [];
+    const canonical = content.map((c) => {
+        const block = c;
+        if (block?.type === "text" && typeof block.text === "string") {
+            return ["text", block.text];
+        }
+        return [block?.type ?? "?", block?.mimeType ?? "", typeof block?.data === "string" ? block.data : ""];
+    });
+    return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}
+export function createClearedProjectionLedger() {
+    return { entries: new Map() };
+}
+const OCCURRENCE_KEY_SEP = String.fromCharCode(0);
+function occurrenceGroupId(m) {
+    return `${m.toolCallId}${OCCURRENCE_KEY_SEP}${m.timestamp ?? 0}`;
+}
+export function planRejectionClears(messages, opts) {
+    const keep = resolveKeepRecentToolResults(opts.keepRecentToolResults, CC_DEFAULT_KEEP_RECENT_TOOL_RESULTS);
+    const compactable = opts.compactableTools ?? COMPACTABLE_TOOLS;
+    const candidates = messages.flatMap((m) => (isToolResult(m) && compactable.has(m.toolName) ? [m] : []));
+    const beyondKeep = candidates.slice(0, Math.max(0, candidates.length - keep));
+    const clearable = beyondKeep.flatMap((m) => {
+        if (isCcCleared(m))
+            return [];
+        const at = opts.keyOf(m);
+        return at === undefined ? [] : [{ m, at }];
+    });
+    if (clearable.length === 0)
+        return { declined: "no_candidates" };
+    const tokensSavedEstimate = clearable.reduce((sum, { m }) => sum + structuralClearSavings(m), 0);
+    if (tokensSavedEstimate < MIN_CLEAR_SAVINGS_TOKENS)
+        return { declined: "below_min_savings" };
+    const cleared = clearable.map(({ m, at }) => {
+        const source = at.occurrence !== undefined && isToolResult(at.occurrence) ? at.occurrence : m;
+        const clearedMsg = clearOneResult(source, opts.offload, "cc");
+        return { key: at.key, groupCount: at.groupCount, marker: clearedMsg.content[0]?.text ?? CC_CLEARED_MARKER, fp: at.fp };
+    });
+    return { cleared, tokensSavedEstimate };
+}
+export function replayClearedProjection(messages, ledger) {
+    const groups = new Map();
+    const byIndex = new Map();
+    const byObject = new WeakMap();
+    messages.forEach((m, i) => {
+        if (!isToolResult(m))
+            return;
+        const g = occurrenceGroupId(m);
+        const list = groups.get(g) ?? [];
+        byIndex.set(i, { group: g, dupIdx: list.length });
+        byObject.set(m, { group: g, dupIdx: list.length });
+        list.push(i);
+        groups.set(g, list);
+    });
+    const mintKey = (hit) => {
+        if (hit === undefined)
+            return undefined;
+        const list = groups.get(hit.group) ?? [];
+        const occurrenceIdx = list[hit.dupIdx];
+        return {
+            key: `${hit.group}${OCCURRENCE_KEY_SEP}${hit.dupIdx}`,
+            groupCount: list.length,
+            fp: occurrenceIdx === undefined ? "" : fingerprintToolResultOccurrence(messages[occurrenceIdx]),
+            ...(occurrenceIdx === undefined ? {} : { occurrence: messages[occurrenceIdx] }),
+        };
+    };
+    const index = {
+        keyAt: (i) => mintKey(byIndex.get(i)),
+        keyOf: (m) => {
+            const direct = byObject.get(m);
+            if (direct !== undefined)
+                return mintKey(direct);
+            if (!isToolResult(m))
+                return undefined;
+            const g = occurrenceGroupId(m);
+            const list = groups.get(g);
+            return list !== undefined && list.length === 1 ? mintKey({ group: g, dupIdx: 0 }) : undefined;
+        },
+    };
+    if (ledger.entries.size === 0) {
+        return { messages, index };
+    }
+    let out;
+    const rekeyed = new Map();
+    for (const [key, entry] of ledger.entries) {
+        const sep = key.lastIndexOf(OCCURRENCE_KEY_SEP);
+        const group = key.slice(0, sep);
+        const dupIdx = Number(key.slice(sep + 1));
+        const list = groups.get(group);
+        if (list === undefined)
+            continue;
+        const m = list.length;
+        const shrink = Math.max(0, entry.groupCount - m);
+        const mapped = dupIdx - shrink;
+        if (mapped < 0 || mapped >= m)
+            continue;
+        const targetIdx = list[mapped];
+        const target = messages[targetIdx];
+        if (soleMarkerText(target) !== entry.marker) {
+            if (fingerprintToolResultOccurrence(target) !== entry.fp)
+                continue;
+            out = out ?? messages.slice();
+            out[targetIdx] = { ...target, content: [{ type: "text", text: entry.marker }] };
+        }
+        rekeyed.set(`${group}${OCCURRENCE_KEY_SEP}${mapped}`, { marker: entry.marker, groupCount: m, fp: entry.fp });
+    }
+    ledger.entries.clear();
+    for (const [k, v] of rekeyed)
+        ledger.entries.set(k, v);
+    return { messages: out ?? messages, index };
+}

package/dist/core/governance-codes.d.ts

@@ -93,7 +93,7 @@ export type NoticeAudience = "user" | "operator";
  * src/ for notice mint shapes and names any code that is minted but unregistered, or registered but
  * no longer minted.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "task.injection_priority_unimplemented", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.read_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "delegation.transcript_integrity", "mcp.revocation_probe_failed", "workflow.governance_key_stripped", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "route.fallback_to_primary", "route.base_url_changed_key_unchanged", "task.user_steer_undrained", "task.user_followup_undrained", "task.injection_priority_unimplemented", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -17,6 +17,7 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.session_polluted",
     "memory.harvest_quarantined",
     "memory.delegation_static_mark_waived",
+    "memory.content_class_declared",
     "memory.consolidation_driver_superseded",
     "memory.challenge_sweep_failed",
     "memory.lineage_settle_failed",
@@ -85,6 +86,7 @@ export const RULE_SYNC_DROP_CODES = {
     server_rejected: "local-quarantined",
 };
 export const ENGINE_NOTICE_CODES = [
+    "config.autocompact_window_clamped",
     "config.env_timeout_discarded",
     "config.materialize_env_discarded",
     "config.models_swapped",
@@ -98,6 +100,7 @@ export const ENGINE_NOTICE_CODES = [
     "memory.session_polluted",
     "memory.harvest_quarantined",
     "memory.delegation_static_mark_waived",
+    "memory.content_class_declared",
     "memory.hold_opened",
     "memory.hold_released",
     "memory.hold_disposed",
@@ -122,6 +125,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "memory.hold_disposed": "user",
     "task.user_steer_undrained": "user",
     "task.user_followup_undrained": "user",
+    "config.autocompact_window_clamped": "operator",
     "config.env_timeout_discarded": "operator",
     "config.materialize_env_discarded": "operator",
     "config.models_swapped": "operator",
@@ -132,6 +136,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "delegation.transcript_integrity": "operator",
     "mcp.revocation_probe_failed": "operator",
     "workflow.governance_key_stripped": "operator",
+    "memory.content_class_declared": "operator",
     "memory.consolidation_recommended": "operator",
     "memory.consolidation_committed": "operator",
     "memory.consolidation_conflict": "operator",

package/dist/core/locked-config.d.ts

@@ -1,4 +1,4 @@
-import type { RunnerDeps, TaskSpec } from "./types.js";
+import type { McpServerSpec, RunnerDeps, TaskSpec } from "./types.js";
 import type { ToolPolicy } from "./tool-policy.js";
 /** The closed set of administratively lockable configuration keys. Adding a member is a deliberate
  *  edit HERE (tsc forces the registry row), never a free-form string. */
@@ -38,9 +38,12 @@ export interface LockedConfig {
 export interface LockedPreflight {
     /** The validated lock set (empty when the deployment declares none). */
     lockedKeys: ReadonlySet<LockedKey>;
-    /** Effective MCP server list for this task: `spec.mcp` when the key is unlocked; with `mcp`
-     *  locked a spec-supplied value has already been refused, so this is always `undefined` (core has
-     *  no deployment-level MCP seat — a locked deployment mounts no task-supplied servers). */
+    /** Effective MCP server list for this task: a validated, frozen SNAPSHOT of `spec.mcp` when the
+     *  key is unlocked (see {@link snapshotAndValidateMcpEntries} — the content-class declaration is read once
+     *  and judged here, so no mint site downstream can be handed a different value than the door
+     *  approved); with `mcp` locked a spec-supplied value has already been refused, so this is always
+     *  `undefined` (core has no deployment-level MCP seat — a locked deployment mounts no
+     *  task-supplied servers). */
     mcp: TaskSpec["mcp"];
     /** Effective caller tool policy: the same `spec.toolPolicy ?? deps.toolPolicy` slot the gate has
      *  always enforced, resolved ONCE here. With `toolPolicy` locked, the deployment's own
@@ -61,6 +64,35 @@ export interface LockedPreflight {
  * then fails the first prepare instead of silently guarding nothing).
  */
 export declare function resolveLockedKeys(config: LockedConfig | undefined): ReadonlySet<LockedKey>;
+/**
+ * design/378 — turn a caller-owned MCP entry list into FROZEN PLAIN DATA, reading every own property
+ * exactly once.
+ *
+ * WHY A COPY. `McpServerSpec.contentOrigin` decides whether a server's tools mark the session's
+ * memory, and the entry objects travel a long way: the preparation door validates them, then
+ * `materializeMcpTools` connects them, then every mid-task refresh re-reads the same object. A value
+ * read off a LIVE object is only true for as long as the object holds still, and the fail-open
+ * direction is the reachable one — so both boundaries consume data instead.
+ *
+ * The read discipline is the load-bearing part, and it is why this is a spread rather than
+ * "read the property, then copy the object": a getter answering ALTERNATING LEGAL values would
+ * satisfy any number of re-reads (`"external"` to a validator, `"local"` to a mint site), and no
+ * vocabulary guard anywhere has purchase on a legal value. One spread evaluates every own property
+ * EXACTLY ONCE and materializes the result as plain data; every later reader — validator, connect,
+ * refresh — then sees the same byte. Frozen so nothing downstream rewrites it.
+ *
+ * Boundary, stated: the copy is one level deep — nested option objects (transport, headers, env,
+ * toolAxes) stay shared with the caller's entry exactly as before, because the axis this owns is the
+ * content class; readers of the nested shapes normalize their own values (the transport DISCRIMINATOR
+ * is derived, never echoed raw). Own ENUMERABLE properties only: an entry whose fields live on a
+ * prototype was never the plain configuration record this type describes, and its absent class reads
+ * fail-closed like any other absence.
+ *
+ * Exported because the SECOND boundary needs the identical guarantee: `materializeMcpTools` is public
+ * and a library caller reaches it without passing any door, so it snapshots its own input through
+ * this same function (idempotent over an already-frozen entry). One spelling, both entrances.
+ */
+export declare function snapshotMcpEntries(entries: readonly McpServerSpec[]): McpServerSpec[];
 /**
  * The single preflight resolver: validate the lock declaration, refuse a spec that tries to occupy
  * a locked slot (`config.locked_key`, two-state — the whole prepare is rejected, nothing is

package/dist/core/locked-config.js

@@ -1,3 +1,5 @@
+import { isToolContentOrigin, TOOL_CONTENT_ORIGINS } from "./memory-engine/content-origin.js";
+import { inlineUntrusted } from "./untrusted-text.js";
 export const LOCKED_KEY_REGISTRY = {
     mcp: { specFields: ["mcp"] },
     toolPolicy: { specFields: ["toolPolicy", "basePolicyForResumeEdit"] },
@@ -23,6 +25,37 @@ export function resolveLockedKeys(config) {
     }
     return keys;
 }
+export function snapshotMcpEntries(entries) {
+    return entries.map((entry) => Object.freeze({ ...entry }));
+}
+function describeDeclared(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return `[unrepresentable ${typeof value}]`;
+        }
+    }
+}
+function snapshotAndValidateMcpEntries(entries) {
+    const copies = snapshotMcpEntries(entries);
+    for (const copy of copies) {
+        const declared = copy.contentOrigin;
+        if (declared !== undefined && !isToolContentOrigin(declared)) {
+            throw codedError("config.mcp_content_class", `MCP server ${inlineUntrusted(typeof copy.name === "string" ? JSON.stringify(copy.name) : describeDeclared(copy.name), 80)} declares contentOrigin ` +
+                `${inlineUntrusted(describeDeclared(declared), 80)}, which is not one of ` +
+                `${TOOL_CONTENT_ORIGINS.map((v) => `"${v}"`).join(" | ")}. The declaration decides whether this server's tools ` +
+                `mark the session's memory externally exposed — a value this engine cannot read is refused at the door rather ` +
+                `than folded to a class, because folding it would let a deployment believe a declaration is in force while every ` +
+                `call keeps writing a one-way durable mark.`);
+        }
+    }
+    return copies;
+}
 export function preflightLockedConfig(spec, deps) {
     const lockedKeys = resolveLockedKeys(deps.lockedConfig);
     for (const key of lockedKeys) {
@@ -36,7 +69,7 @@ export function preflightLockedConfig(spec, deps) {
     }
     return {
         lockedKeys,
-        mcp: lockedKeys.has("mcp") ? undefined : spec.mcp,
+        mcp: lockedKeys.has("mcp") || spec.mcp === undefined ? undefined : snapshotAndValidateMcpEntries(spec.mcp),
         toolPolicy: lockedKeys.has("toolPolicy") ? deps.toolPolicy : (spec.toolPolicy ?? deps.toolPolicy),
         basePolicyForResumeEdit: lockedKeys.has("toolPolicy") ? deps.basePolicyForResumeEdit : (spec.basePolicyForResumeEdit ?? deps.basePolicyForResumeEdit),
     };

package/dist/core/mcp.d.ts

@@ -177,11 +177,10 @@ export interface MaterializedMcp {
      * fails the WHOLE model request (provider 400), bricking the task for every healthy tool
      * (CC 2.1.216 ships the same intake prune, `tengu_mcp_drop_invalid_tool_schemas`).
      *
-     * HONEST REACH (pinned in mcp-dropped-tools.test.ts): with the bundled TS MCP SDK, a string-root
-     * schema already fails the SDK client's OWN zod at `listTools` — the whole server is skipped
-     * (warnings face) and this gate never sees the listing, losing healthy sibling tools with it
-     * (SDK-upstream failure mode, recorded). This per-tool gate is DEFENSE IN DEPTH: it binds when a
-     * transport/SDK revision delivers schemas the client does not fully validate.
+     * HONEST REACH (pinned in mcp-dropped-tools.test.ts): listings arrive through the lenient reader
+     * (`listToolsLenient` — raw request, no SDK-client zod pass), so a string-root or otherwise odd
+     * schema DOES reach this gate and is judged per tool; healthy siblings survive. This per-tool gate
+     * is therefore the PRIMARY adjudicator for schema shape, not a fallback behind SDK validation.
      *
      * The drop is NEVER silent, two faces (CC parity — its `mcp_dropped_tools_delta` system reminder):
      * - operator: prepare-task forwards each entry to `onError(phase:"mcp")` alongside `warnings`;

package/dist/core/mcp.js

@@ -14,6 +14,7 @@ import { truncateError } from "./tool-errors.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { discloseReminderShaped, observeReminderMarkEcho } from "./reminder-disclosure.js";
 import { withContentOrigin } from "./memory-engine/content-origin.js";
+import { snapshotMcpEntries } from "./locked-config.js";
 import { validateJsonSchemaShape } from "./runner/strict-output-schema.js";
 export const MCP_PREFIX = MCP_NAMESPACE.prefix;
 const MCP_OUTPUT_TOKENS_DEFAULT = 25_000;
@@ -753,8 +754,9 @@ export function mcpToolSchemaProblem(schema) {
     return undefined;
 }
 export async function materializeMcpTools(specs, principal, onElicit, imageResizer, reminderDisclosure, mcpRevocations) {
+    const entries = snapshotMcpEntries(specs);
     {
-        const collision = findNamespacePrefixCollision(MCP_NAMESPACE, specs.map((s) => s.name));
+        const collision = findNamespacePrefixCollision(MCP_NAMESPACE, entries.map((s) => s.name));
         if (collision) {
             const [a, b] = collision.peers;
             const e = new Error(a === b
@@ -801,11 +803,11 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
     const droppedTools = [];
     let disposing = false;
     const serverHandles = [];
-    const settled = await Promise.allSettled(specs.map((spec) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked)));
+    const settled = await Promise.allSettled(entries.map((spec) => connectServer(spec, principal, onElicit, imageResizer, mcpDisclosure, isServerRevoked)));
     try {
-        for (let i = 0; i < specs.length; i++) {
+        for (let i = 0; i < entries.length; i++) {
             const r = settled[i];
-            const spec = specs[i];
+            const spec = entries[i];
             if (r.status === "fulfilled") {
                 const s = r.value;
                 clients.push(s.client);
@@ -1513,6 +1515,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
     }
 }
 function intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked) {
+    const declaredContentOrigin = spec.contentOrigin;
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
@@ -1576,7 +1579,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         const mcpToolMeta = t._meta;
         const mcpMaxResultSizeChars = resolveMcpDeclaredResultSize(mcpToolMeta);
         const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
-        serverTools.push({
+        const mounted = {
             name: namespacedName,
             description: capMcpToolDescription(effectiveDescription ?? `MCP tool ${inlineUntrusted(sanitizeMcpModelFacingText(remoteName))} from ${spec.name}`),
             label: `${spec.name}:${remoteName}`,
@@ -1678,7 +1681,8 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
                     return { content, details: { type: "mcp", structuredContent: sc }, terminate: false };
                 return { content, details: res, terminate: false };
             },
-        });
+        };
+        serverTools.push(declaredContentOrigin !== undefined ? withContentOrigin(mounted, declaredContentOrigin) : mounted);
     }
     return { serverTools, serverAxes, dropped, advisories };
 }

package/dist/core/memory-engine/content-origin.d.ts

@@ -22,13 +22,22 @@
  * does not, the default is EXTERNAL (fail-closed: unknown = external), overridable only through the
  * explicit `TaskSpec.memory.trustedTools` allowlist. A core-mounted built-in without a declaration
  * defaults local: core owns those definitions, and the fail-closed default exists for tools core
- * CANNOT vouch for, not for its own.
+ * CANNOT vouch for, not for its own. A declaration is honored only when it SPELLS a member of the
+ * closed vocabulary — an unreadable one is not a declaration.
+ *
+ * The three tier names are BOUNDARY-RELATIVE, not statements about topology: `"local"` means "does
+ * not bring content from outside the deployment's trust boundary", which a unix socket to another
+ * process the deployment itself runs satisfies and a loopback HTTP call to somebody else's service
+ * does not. Distance is not the axis; whose content it is, is.
  *
  * There is deliberately no "gate inactive" state: every mounted tool gets a class.
  */
 import type { ToolContentOrigin } from "../types.js";
 export interface ClassifyToolContentOriginInput {
-    /** The tool's own `contentOrigin` declaration (ToolSpec/AgentTool carry) — wins when present. */
+    /** The tool's own `contentOrigin` declaration (ToolSpec/AgentTool carry) — wins when present AND
+     *  a member of the closed vocabulary ({@link isToolContentOrigin}); a present non-member is the
+     *  unreadable-declaration case and classifies EXTERNAL. The annotation is intent, not a guarantee:
+     *  the property rides tool objects untyped. */
     declared?: ToolContentOrigin;
     /** True ⇔ the name belongs to a protocol namespace (mcp__/a2a__ …) — an external channel. */
     isProtocolTool: boolean;
@@ -37,6 +46,10 @@ export interface ClassifyToolContentOriginInput {
     /** True ⇔ `TaskSpec.memory.trustedTools` names this tool (explicit host exemption). */
     trusted: boolean;
 }
+/** The vocabulary in wire/message order — the one spelling list a refusal quotes back. */
+export declare const TOOL_CONTENT_ORIGINS: readonly ToolContentOrigin[];
+/** Runtime membership in the closed vocabulary. */
+export declare function isToolContentOrigin(value: unknown): value is ToolContentOrigin;
 export declare function classifyToolContentOrigin(input: ClassifyToolContentOriginInput): ToolContentOrigin;
 /**
  * Declare `origin` on a tool object built OUTSIDE `defineTool` — a raw AgentTool literal, which is
@@ -60,6 +73,15 @@ export interface AgentToolFace {
 export interface AgentPoolTool {
     name: string;
     aliases?: readonly string[];
+    /** The pool row's own declaration — a STATIC surface the deployment writes when it composes the
+     *  delegation tool, and the only class information this judgment has about the child's roster.
+     *
+     *  A per-entry MCP declaration (design/378, `McpServerSpec.contentOrigin`) does NOT reach here: the
+     *  pool is a declaration, not a live roster, and this judgment never sees the server entries. A
+     *  deployment that hands a declared server's `mcp__` tools to children MIRRORS the value onto the
+     *  matching pool rows; not mirroring it leaves them on the protocol arm, so the delegation reads
+     *  external and the parent over-marks — the safe direction, and the reason this is a documented
+     *  duty rather than a refusal. */
     contentOrigin?: ToolContentOrigin;
 }
 /**

package/dist/core/memory-engine/content-origin.js

@@ -1,6 +1,11 @@
+const TOOL_CONTENT_ORIGIN_SET = { external: true, execution: true, local: true };
+export const TOOL_CONTENT_ORIGINS = Object.keys(TOOL_CONTENT_ORIGIN_SET);
+export function isToolContentOrigin(value) {
+    return typeof value === "string" && Object.prototype.hasOwnProperty.call(TOOL_CONTENT_ORIGIN_SET, value);
+}
 export function classifyToolContentOrigin(input) {
     if (input.declared !== undefined)
-        return input.declared;
+        return isToolContentOrigin(input.declared) ? input.declared : "external";
     if (input.trusted)
         return "local";
     if (input.isProtocolTool)