@sema-agent/core 5.54.0 → 5.56.0

package/dist/core/runner/turn-attachments.js

@@ -1,5 +1,5 @@
 import { PRESENT_PLAN_TOOL_NAME } from "../present-plan-tool.js";
-import { defuseFenceMarkers, delimitUntrusted, sanitizeUntrustedText } from "../untrusted-text.js";
+import { delimitUntrustedWithClip, sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "../untrusted-text.js";
 import { protocolOf } from "../protocol-table.js";
 import { buildSkillsBlock, skillListingLine } from "./synthetic-tools.js";
 import { TOOL_SEARCH_NAME as TOOL_SEARCH_TOOL_NAME } from "./tool-disclosure.js";
@@ -20,6 +20,11 @@ export const CHANGED_FILES_MTIME_EPS_MS = 2000;
 export const ATTACHMENT_BYTE_CAP = 8 * 1024;
 const PROJECTION_ITEMS_MAX = 50;
 const PROJECTION_CONTENT_MAX = 80;
+const ATTACHMENT_TAGS_DEFAULT = [...SHELLED_BODY_ENVELOPE_TAGS];
+const ATTACHMENT_TAGS_SKILLS_OWNER = SHELLED_BODY_ENVELOPE_TAGS.filter((t) => t !== "skills");
+export function attachmentEnvelopeTags(source) {
+    return source === "skills_listing" ? ATTACHMENT_TAGS_SKILLS_OWNER : ATTACHMENT_TAGS_DEFAULT;
+}
 export const INSTRUCTIONS_CHANGE_BYTE_CAP = 512;
 export function createAttachmentState() {
     return {
@@ -358,8 +363,9 @@ export function renderBudgetUsd(used, total) {
     return `USD budget: $${used}/$${total}; $${total - used} remaining`;
 }
 export function renderOrphanedBackgroundTasks(tasks) {
+    const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     return (`The container was restarted. The following background tasks were running and are now stopped:\n` +
-        tasks.map((t) => `- ${t.description || "(no description)"} (task ${t.id})`).join("\n") +
+        tasks.map((t) => `- ${safe(t.description || "(no description)")} (task ${safe(t.id)})`).join("\n") +
         `\nRe-create them if still needed.`);
 }
 function renderChangedFiles(paths) {
@@ -449,7 +455,7 @@ export const AGENT_TOOLS_NOTE_DEFAULT = "All tools";
 export const AGENT_CONCURRENCY_NOTE = "When you launch multiple agents for independent work, send them in a single message with multiple tool uses so they run concurrently.";
 export const AMBIENT_CONTEXT_NOTE = "This is ambient context — do not narrate it to the user unless they ask or it is directly relevant to their request.";
 export function agentListingInitialHeader(toolName) {
-    return `Available agent types for the ${toolName} tool:`;
+    return `Available agent types for the ${sanitizeUntrustedText(toolName, SHELLED_BODY_ENVELOPE_TAGS)} tool:`;
 }
 export function replayAnnouncedListing(texts, headers) {
     let announced;
@@ -492,13 +498,17 @@ export function replayAnnouncedListing(texts, headers) {
     return announced;
 }
 export const AGENT_LISTING_REMOVED_HEADER = "The following agent types are no longer available:";
+function listingIdentity(name) {
+    return sanitizeUntrustedText(name, SHELLED_BODY_ENVELOPE_TAGS);
+}
 export function agentListingDeltaHeader(toolName) {
-    return `New agent types are now available for the ${toolName} tool:`;
+    return `New agent types are now available for the ${sanitizeUntrustedText(toolName, SHELLED_BODY_ENVELOPE_TAGS)} tool:`;
 }
 export function renderAgentListingDelta(state, entries, toolName, models) {
+    const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     const line = (e) => {
-        const base = e.description ? `- ${e.name}: ${e.description}` : `- ${e.name}`;
-        return `${base} (Tools: ${e.tools ?? AGENT_TOOLS_NOTE_DEFAULT})`;
+        const base = e.description ? `- ${safe(e.name)}: ${safe(e.description)}` : `- ${safe(e.name)}`;
+        return `${base} (Tools: ${safe(e.tools ?? AGENT_TOOLS_NOTE_DEFAULT)})`;
     };
     const announced = state.announcedAgentTypes;
     if (announced === undefined) {
@@ -511,18 +521,22 @@ export function renderAgentListingDelta(state, entries, toolName, models) {
             blocks.push(modelsAvailableLine(models));
         return blocks.join("\n\n");
     }
-    const added = entries.filter((e) => !announced.has(e.name)).toSorted((a, b) => a.name.localeCompare(b.name));
-    const removed = [...announced.keys()].filter((n) => !entries.some((e) => e.name === n)).sort();
+    const announcedIds = new Set([...announced.keys()].map(listingIdentity));
+    const added = entries.filter((e) => !announcedIds.has(listingIdentity(e.name))).toSorted((a, b) => a.name.localeCompare(b.name));
+    const removed = [...announced.keys()]
+        .filter((n) => !entries.some((e) => listingIdentity(e.name) === listingIdentity(n)))
+        .sort();
     const modelsDrifted = state.announcedModels !== undefined &&
         models !== undefined &&
-        (state.announcedModels.length !== models.length || state.announcedModels.some((m, i) => m !== models[i]));
+        (state.announcedModels.length !== models.length ||
+            state.announcedModels.some((m, i) => listingIdentity(m) !== listingIdentity(models[i])));
     if (added.length === 0 && removed.length === 0 && !modelsDrifted)
         return undefined;
     const blocks = [];
     if (added.length > 0)
         blocks.push(`${agentListingDeltaHeader(toolName)}\n${added.map(line).join("\n")}`);
     if (removed.length > 0) {
-        blocks.push(`${AGENT_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${n}`).join("\n")}`);
+        blocks.push(`${AGENT_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${safe(n)}`).join("\n")}`);
         blocks.push(AMBIENT_CONTEXT_NOTE);
     }
     if (modelsDrifted)
@@ -531,7 +545,8 @@ export function renderAgentListingDelta(state, entries, toolName, models) {
 }
 export const MODELS_AVAILABLE_PREFIX = "Models available for the 'model' parameter: ";
 function modelsAvailableLine(models) {
-    return `${MODELS_AVAILABLE_PREFIX}${models.length > 0 ? models.join(", ") : "(none)"}`;
+    const named = models.map((m) => sanitizeUntrustedText(m, SHELLED_BODY_ENVELOPE_TAGS));
+    return `${MODELS_AVAILABLE_PREFIX}${named.length > 0 ? named.join(", ") : "(none)"}`;
 }
 export function replayAnnouncedModels(texts) {
     let last;
@@ -563,15 +578,16 @@ export function renderSkillsListingDelta(state, entries) {
             return undefined;
         return buildSkillsBlock(entries);
     }
-    const added = entries.filter((e) => !announced.has(e.name));
-    const removed = [...announced.keys()].filter((n) => !entries.some((e) => e.name === n));
+    const announcedIds = new Set([...announced.keys()].map(listingIdentity));
+    const added = entries.filter((e) => !announcedIds.has(listingIdentity(e.name)));
+    const removed = [...announced.keys()].filter((n) => !entries.some((e) => listingIdentity(e.name) === listingIdentity(n)));
     if (added.length === 0 && removed.length === 0)
         return undefined;
     const blocks = [];
     if (added.length > 0)
         blocks.push(`${SKILLS_LISTING_DELTA_HEADER}\n${added.map((e) => skillListingLine(e)).join("\n")}`);
     if (removed.length > 0) {
-        blocks.push(`${SKILLS_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${n}`).join("\n")}`);
+        blocks.push(`${SKILLS_LISTING_REMOVED_HEADER}\n${removed.map((n) => `- ${sanitizeUntrustedText(n, SHELLED_BODY_ENVELOPE_TAGS)}`).join("\n")}`);
         blocks.push(AMBIENT_CONTEXT_NOTE);
     }
     return blocks.join("\n\n");
@@ -581,12 +597,10 @@ export function commitSkillsListing(state, entries) {
 }
 export const MCP_INSTRUCTIONS_MAX_CHARS = 8 * 1024;
 export function fenceMcpServerInstructions(server, text) {
-    const neutralized = defuseFenceMarkers(sanitizeUntrustedText(text));
-    const clipped = [...neutralized].length > MCP_INSTRUCTIONS_MAX_CHARS;
-    const fenced = delimitUntrusted(`MCP server "${server}" instructions`, neutralized, MCP_INSTRUCTIONS_MAX_CHARS);
-    return clipped
-        ? `${fenced}\n(Truncated by the agent runtime: this server's instructions exceeded ${MCP_INSTRUCTIONS_MAX_CHARS} characters.)`
-        : fenced;
+    const fence = delimitUntrustedWithClip(`MCP server "${server}" instructions`, text, MCP_INSTRUCTIONS_MAX_CHARS);
+    return fence.clipped
+        ? `${fence.text}\n(Truncated by the agent runtime: this server's instructions exceeded ${MCP_INSTRUCTIONS_MAX_CHARS} characters.)`
+        : fence.text;
 }
 export function renderMcpInstructionsDelta(added, removed) {
     const blocks = [];

package/dist/core/session-reconcile.d.ts

@@ -84,6 +84,38 @@ export interface ReconcileReport {
  * `runner.resume()` uses a checkpoint-aware entry that bypasses this reconcile entirely for those calls.
  */
 export declare function findOrphanToolCalls(messages: AgentMessage[], suspendedBatch?: ReadonlySet<string>): OrphanToolCall[];
+/**
+ * backlog #389 伴生 (D-2) — CC 2.1.223's interruption markers, VERBATIM (`$U`/`CR` @ `CC:151120-151121`,
+ * minted as a USER message by `Jce` @ `CC:640141-640154`). CC mints one on every abort whose reason is
+ * outside `{"interrupt","refusal-fallback-edit"}` — and the interactive Esc / remote cancel, which is
+ * what `TaskStream.interrupt()` corresponds to, is precisely on the minting side (`CC:1033698-1033733`).
+ * The suppressed reason is the one case where the user's own replacement message is already the context.
+ *
+ * Taken verbatim rather than reworded: this string is an INPUT to later reasoning in CC (its own
+ * "interrupted then immediately retried the same action" rule reads it back), and the constitution's
+ * standing rule is that a question CC has answered is answered in CC's form.
+ */
+export declare const INTERRUPTED_BY_USER_MARKER = "[Request interrupted by user]";
+/** backlog #389 伴生 — the tool-use variant (`CR`): the run was cut while a tool batch was in flight. */
+export declare const INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER = "[Request interrupted by user for tool use]";
+/**
+ * backlog #389 伴生 (D-2) — append the interruption marker so the SESSION records that a person stopped
+ * this run.
+ *
+ * Without it, an interrupt that lands on the model stream (no tool call in flight) leaves literally no
+ * trace: the orphan reconcile has nothing to close, and the empty aborted assistant is deliberately not
+ * persisted (`isEmptyFailureAssistant`). The next run on that session then reads a transcript in which
+ * the half-finished work simply stops, and continues as if it had ended by itself.
+ *
+ * MUST be called AFTER {@link reconcileInterruptedSession} on the same interruption: a user message
+ * placed between an assistant's tool calls and their results is exactly the invalid sequence the
+ * reconcile exists to prevent.
+ *
+ * Returns the persisted entry id so the caller can mint its `message_committed` frame.
+ */
+export declare function appendInterruptionMarker(session: Session, opts: {
+    toolUseInFlight: boolean;
+}): Promise<string>;
 /**
  * Reconcile a resumed session's active branch: close any orphan tool calls with a synthetic
  * interrupted `toolResult` (never re-running the tool). Returns what was recovered.

package/dist/core/session-reconcile.js

@@ -81,6 +81,21 @@ export function findOrphanToolCalls(messages, suspendedBatch) {
     });
     return orphans;
 }
+export const INTERRUPTED_BY_USER_MARKER = "[Request interrupted by user]";
+export const INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER = "[Request interrupted by user for tool use]";
+export async function appendInterruptionMarker(session, opts) {
+    return await session.appendMessage({
+        role: "user",
+        content: [
+            {
+                type: "text",
+                text: opts.toolUseInFlight ? INTERRUPTED_BY_USER_FOR_TOOL_USE_MARKER : INTERRUPTED_BY_USER_MARKER,
+            },
+        ],
+        provenance: "engine-note",
+        timestamp: Date.now(),
+    });
+}
 export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch, startedToolCallIds) {
     const { messages } = await session.buildContext();
     const orphans = findOrphanToolCalls(messages, suspendedBatch).filter((o) => o.kind !== "result");

package/dist/core/task-notification.d.ts

@@ -2,6 +2,16 @@
  *  lines from a still-running watch). Everything else is a terminal completion notification. */
 export type TaskNotificationStatus = "completed" | "failed" | "killed" | "cancelled" | "event";
 export type SystemInjectionPriority = "now" | "next" | "later";
+/** The closed value set of {@link SystemInjectionPriority}, as data — the wire-facing entries validate
+ *  against THIS rather than against three inline string literals, so widening the type widens the guard.
+ *  (Names taken verbatim from CC 2.1.223's `UYo` @ `CC:644918`; see the semantics note on
+ *  {@link SystemInjection.priority} for which of CC's behaviors this engine implements.) */
+export declare const SYSTEM_INJECTION_PRIORITIES: readonly SystemInjectionPriority[];
+/** backlog #389 伴生 (D-3, bad-value loudness) — is this a priority this engine knows at all? A value
+ *  outside the set is a caller bug that must be refused, never silently folded into a default: the
+ *  no-subscriber retain path indexes `queues[priority]` and the park path stores it verbatim, so an
+ *  unknown value used to travel until something downstream failed on it (or didn't, and lied). */
+export declare function isSystemInjectionPriority(value: unknown): value is SystemInjectionPriority;
 export interface TaskNotificationPayload {
     task_id: string;
     /** design/144 §2: `"external"` is CORE-MINTED ONLY — `TaskStream.notify()` casts it onto every
@@ -137,13 +147,30 @@ export interface ExternalNotificationInput {
 }
 export interface SystemInjection<TPayload = unknown> {
     kind: "task_notification";
-    /** design/116 §7, re-anchored 2026-08-05 (CC 2.1.221): EVERY priority delivers at the NEXT turn
-     *  boundary via harness.steer(), mid-work included — CC's queued task-notification inputs are
-     *  unconditionally deliverable at the boundary, and the old later→followUp mapping (deliver only
-     *  when the agent would otherwise stop) starved busy models of the very completion they were told
-     *  not to poll for. Delivery is ARRIVAL order (consecutive frames batch); `priority` affects only the park/uplink
-     *  path. A delivery that races the agent going idle parks on PendingSessionNotifications for the
-     *  session's next run. `drain()` serves that parked lane. */
+    /**
+     * design/116 §7 — in THIS engine every priority delivers at the NEXT turn boundary via
+     * `harness.steer()`, mid-work included, in ARRIVAL order (consecutive frames batch); `priority`
+     * affects only the park/uplink path. A delivery that races the agent going idle parks on
+     * PendingSessionNotifications for the session's next run; `drain()` serves that parked lane.
+     *
+     * **Anchor correction (backlog #389 伴生 / hallucination audit H-1).** The 2026-08-05 re-anchor
+     * justified flattening the ladder with "CC's queued task-notification inputs are UNCONDITIONALLY
+     * deliverable at the boundary (CC 2.1.221)". That sentence is FALSE as a statement about CC, on
+     * 221 and 223 alike: the mid-turn fold is gated at `getCommandsByMaxPriority("next")`
+     * (`pretty221.js:449195` / `pretty223.js:415586`), which admits `now`+`next` and EXCLUDES `later`
+     * — and `enqueuePendingNotification` defaults to `later`. CC's background-completion notices fold
+     * mid-turn because they explicitly say `priority:"next"`; its ultraplan/artifact notices take the
+     * default and deliberately do NOT. So all three of CC's values carry live delivery semantics
+     * (`now` = abort the running turn, `next` = fold into it, `later` = wait for the next one).
+     *
+     * The engineering conclusion the re-anchor reached — a background completion must reach a busy
+     * model at the boundary rather than starve behind a "deliver only when it would otherwise stop"
+     * rule — stands on its own. What does not stand is the claim that CC has no ladder. Restoring the
+     * `later` = "do not fold into the running turn" arm is a behavior-face change and `now` = "abort
+     * the running turn" is a new capability; both are ruled changes, not silent ones. Until then the
+     * gap is DISCLOSED at the injection funnel rather than left as a silently inert knob (`now` is
+     * announced, an unknown value is refused) — the bad-value loudness rule.
+     */
     priority: SystemInjectionPriority;
     dedupKey: string;
     payload: TPayload;

package/dist/core/task-notification.js

@@ -1,4 +1,8 @@
 import { inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
+export const SYSTEM_INJECTION_PRIORITIES = ["now", "next", "later"];
+export function isSystemInjectionPriority(value) {
+    return typeof value === "string" && SYSTEM_INJECTION_PRIORITIES.includes(value);
+}
 const TASK_NOTIFICATION_TAGS = [
     "task-notification",
     "task-id",
@@ -214,6 +218,9 @@ export class SystemInjectionQueue {
     listeners = new Set();
     droppedOldest = 0;
     enqueue(item) {
+        if (!isSystemInjectionPriority(item.priority)) {
+            throw new Error(`SystemInjectionQueue: unknown priority ${JSON.stringify(item.priority)} — expected one of ${SYSTEM_INJECTION_PRIORITIES.join("/")}`);
+        }
         if (this.dedup.has(item.dedupKey))
             return false;
         this.dedup.add(item.dedupKey);
@@ -239,7 +246,10 @@ export class SystemInjectionQueue {
         return true;
     }
     drain(priority) {
-        const priorities = priority ? [priority] : ["now", "next", "later"];
+        if (priority !== undefined && !isSystemInjectionPriority(priority)) {
+            throw new Error(`SystemInjectionQueue: unknown priority ${JSON.stringify(priority)} — expected one of ${SYSTEM_INJECTION_PRIORITIES.join("/")}`);
+        }
+        const priorities = priority ? [priority] : [...SYSTEM_INJECTION_PRIORITIES];
         const out = [];
         for (const p of priorities) {
             const q = this.queues[p];

package/dist/core/task-registry-agent.d.ts

@@ -166,11 +166,23 @@ export declare function parkBackgroundAgentLane(core: DurableAgentCore, id: stri
  * design/153 §7.1 (件1 codex HIGH split-brain fence) — the registry-aware reconciliation entry an
  * IN-PROCESS deployment calls on its retention cadence. Two halves, one call:
  *  1. LIVE half: this instance's own parked handles are probed against their checkpoint and, on
- *     expired/missing, settled failed THROUGH the handle (poll/stop/durable row stay coherent —
- *     quiescence poked, arbitration closure dropped, durable clear rides the settle write).
+ *     expired/missing/DECIDED-ELSEWHERE, settled failed THROUGH the handle (poll/stop/durable row
+ *     stay coherent — quiescence poked, arbitration closure dropped, durable clear rides the settle
+ *     write).
  *  2. STORE half: delegates to the store-level {@link reconcileParkedAgents} with
  *     `excludeWriterId` = this instance's writerId, so foreign (dead-process) rows are cleaned
  *     without ever touching a row this process is live-managing.
+ *
+ * backlog #400 — the live half used to skip EVERY non-expired/missing state, `resolved` included, and
+ * that was the whole zombie: a parked row whose checkpoint was decided by the task-level
+ * `resumeCheckpoint` leg (a serving layer's documented fallback when its parked-row discriminator
+ * misses) is decided but still says `parked`, its side effects already executed by a path that never
+ * touched this registry. Nothing else could reach it either — a re-claim answers
+ * `checkpoint_not_pending`, and the store half excludes exactly the rows this process live-manages —
+ * so it stayed `parked` for the life of the process. It now converges here. The one `resolved` case
+ * that must still be LET THROUGH is the registry's own claim window (reservation → consume flip): that
+ * skip is load-bearing, and it is now expressed as what it actually is — a claim in flight — instead
+ * of as a blanket state filter that also swallowed the case with no claimant at all.
  */
 export declare function reconcileParkedAgentsLane(core: DurableAgentCore, stores: {
     agentStore: import("./background-agent-store.js").BackgroundAgentStore;
@@ -275,7 +287,12 @@ export declare function abortBackgroundAgentsForOwnerLane(core: DurableAgentCore
  *  SendMessage consume, so the two verbs can never drift. Ladder:
  *   0a. verbatim `handle.name` match — LATEST-WINS (CC SendMessage.md: "a newer agent took the name
  *       (latest wins)"; older rows stay task_id-addressable), any status (names keep working after
- *       completion — the resume face is the CC "resumes it from its transcript" counterpart);
+ *       completion — the resume face is the CC "resumes it from its transcript" counterpart).
+ *       **Latest-wins is RESOLUTION, not permission to redirect a conversation**: CC pairs the same
+ *       resolver with a per-conversation pin guard (`send_message_pin_guard`), and SendMessage REFUSES
+ *       a send whose name has changed hands since this caller last used it. That guard lives at the
+ *       SendMessage face (`createSendMessageTool`), exactly as it does upstream — this resolver stays
+ *       a pure resolver, and TaskStop keeps its own (preferRunning) posture untouched;
  *   0b. normalized `handle.name` match — same latest-wins (the spawn regex bans whitespace, so
  *       normalization here is effectively NFKC+lowercase: "Builder"/"builder" share the name pool);
  *   1+. the pre-[c209] description layers, UNCHANGED (exact → normalized, running-preferred +

package/dist/core/task-registry-agent.js

@@ -484,12 +484,41 @@ export async function reconcileParkedAgentsLane(core, stores, scope, now, opts)
                 state = "unreadable";
             }
         }
-        if (state !== "expired" && state !== "missing")
+        let error;
+        if (state === "expired" || state === "missing") {
+            error = `approval checkpoint ${state} while parked (reconciled)`;
+        }
+        else if (state === "resolved") {
+            let row;
+            try {
+                row = await stores.agentStore.get(handle.id, scope);
+            }
+            catch {
+                continue;
+            }
+            if (row === null || row.status !== "parked" || row.parkClaimId !== undefined)
+                continue;
+            try {
+                const reread = (await stores.checkpointStore.get(token));
+                if (reread === null || reread.status !== "resolved")
+                    continue;
+            }
+            catch {
+                continue;
+            }
+            error =
+                "approval checkpoint resolved outside the registry's claim path while parked — the decision was " +
+                    "redeemed by another leg and this row's outcome is unknown (reconciled)";
+        }
+        else {
             continue;
+        }
         if (handle.status !== "parked")
             continue;
+        if (handle.parkedCheckpointToken !== token)
+            continue;
         handle.status = "failed";
-        handle.error = `approval checkpoint ${state} while parked (reconciled)`;
+        handle.error = error;
         handle.parkedCheckpointToken = undefined;
         handle.resolveParkedStop = undefined;
         handle.updatedAt = now;

package/dist/core/tool-policy.d.ts

@@ -383,6 +383,29 @@ export interface ToolPolicyProjection {
      */
     readonly requiresLiveRemainder: boolean;
 }
+/**
+ * The entries of a tool-NAME list whose reach is a set of names rather than one name — the covering
+ * spellings (`<ns>__<peer>`, `<ns>__<peer>__<glob>`) of ANY protocol namespace, which CC's rule
+ * matcher resolves and an exact-membership test silently cannot. Every name-keyed lane in this file
+ * consults these ALONGSIDE its exact set: a covering spelling can never equal a minted tool name (`*`
+ * is outside the minted charset and a minted name always carries a tool segment), so leaving it in the
+ * exact set too costs nothing and keeps the projection/audit faces reporting the operator's own spelling.
+ *
+ * Namespace-generic on purpose: the covering grammar is a property of the shared `<prefix><peer>__<tool>`
+ * name shape, not of MCP, and keying it to one prefix made every sibling-namespace covering rule
+ * (`a2a__<peer>__*`) compile clean and match nothing — inert in the deny half, and in an ALLOW list the
+ * removal of that peer's whole tool set.
+ *
+ * The list is usually empty, which is why every call site tests it before scanning.
+ *
+ * Exported for the OTHER name-keyed lane in this engine — the persisted session/ancestor rules in
+ * `session-rule-policy.ts`. Not part of the public API (`src/index.ts` re-exports by name and does not
+ * list these): all four publishers of {@link ToolPolicyNameSets} must resolve a covering entry the same
+ * way, because the prepare-time audit's exemption for these spellings speaks for all of them at once.
+ */
+export declare function namespacedCoveringEntries(entries: readonly string[] | undefined): readonly string[];
+/** Does any covering entry reach `toolName`? See {@link namespacedCoveringEntries}. */
+export declare function namespacedCoveringHit(covering: readonly string[], toolName: string): boolean;
 /**
  * Execute a persisted {@link ToolPolicyProjection} against a call (F-012 L1): returns the first
  * component's deny, or `undefined` when the projection has no opinion (it is deny-only by

package/dist/core/tool-policy.js

@@ -5,7 +5,8 @@ import { join, normalize as normalizePath, posix as posixPath, sep, win32 as win
 import { BASH_READONLY_DEFAULT_ALLOW, parseLeadingCommandName } from "../tools/fs/index.js";
 import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
-import { parsePermissionRule } from "./permission-rules.js";
+import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
+import { protocolOf } from "./protocol-table.js";
 import { isAbsolutePathForm, isWinFormPath, writeTargetPath } from "../tools/fs/safety.js";
 const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable"];
 const DECISION_REASON_SET = new Set(DECISION_REASONS);
@@ -36,16 +37,22 @@ export const ASK_EVIDENCE_ABSENCE_VALUES = ["not_wired", "not_adjudicated", "una
 export function decisionText(d) {
     return d.message;
 }
+export function namespacedCoveringEntries(entries) {
+    return (entries ?? []).filter(isNamespacedCoveringRuleName);
+}
+export function namespacedCoveringHit(covering, toolName) {
+    return covering.length > 0 && covering.some((e) => namespacedRuleNameCovers(e, toolName));
+}
 export function checkToolPolicyProjection(projection, req) {
     for (const c of projection.components) {
         if (c.kind === "tool_deny") {
-            if (c.names.includes(req.toolName)) {
+            if (c.names.includes(req.toolName) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by a frozen inherited policy projection` };
             }
             continue;
         }
         if (c.kind === "tool_allowlist") {
-            if (!c.names.includes(req.toolName)) {
+            if (!c.names.includes(req.toolName) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in a frozen inherited policy projection's allowlist` };
             }
             continue;
@@ -173,11 +180,15 @@ export function createAllowDenyPolicy(opts) {
             return undefined;
         const kept = [];
         for (const entry of entries) {
-            if (entry.startsWith("mcp__")) {
-                const segments = entry.slice("mcp__".length).split("__");
-                if (segments.some((seg) => seg.length === 0)) {
-                    const lesson = `a malformed MCP tool name (empty segment) — it can never match any mounted tool. ` +
-                        `Use \`mcp__<server>\` for every tool of a server, or \`mcp__<server>__<tool>\` for one tool.`;
+            const ns = protocolOf(entry);
+            if (ns !== undefined) {
+                const suffix = entry.slice(ns.prefix.length);
+                const sep = suffix.indexOf("__");
+                const malformed = suffix.length === 0 || sep === 0 || (sep > 0 && suffix.length === sep + 2);
+                if (malformed) {
+                    const family = ns.id.toUpperCase();
+                    const lesson = `a malformed ${family} tool name (empty peer or tool segment) — it can never match any mounted tool. ` +
+                        `Use \`${ns.prefix}<peer>\` for every tool of a peer, or \`${ns.prefix}<peer>__<tool>\` for one tool.`;
                     invalid.push({ entry, list, message: `"${entry}" is ${lesson}`, lesson });
                     continue;
                 }
@@ -218,6 +229,8 @@ export function createAllowDenyPolicy(opts) {
     opts = { ...opts, ...(screenedAllow ? { allow: screenedAllow } : {}), ...(screenedDeny ? { deny: screenedDeny } : {}) };
     const allow = opts.allow ? new Set(opts.allow) : undefined;
     const deny = new Set(opts.deny ?? []);
+    const denyCovering = namespacedCoveringEntries(opts.deny);
+    const allowCovering = namespacedCoveringEntries(opts.allow);
     return {
         projection: {
             components: [
@@ -229,10 +242,10 @@ export function createAllowDenyPolicy(opts) {
         nameSets: [{ ...(opts.allow ? { allow: [...opts.allow] } : {}), ...(opts.deny ? { deny: [...opts.deny] } : {}) }],
         check(req) {
             const toolName = req.toolName;
-            if (deny.has(toolName)) {
+            if (deny.has(toolName) || namespacedCoveringHit(denyCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (allow && !allow.has(toolName)) {
+            if (allow && !allow.has(toolName) && !namespacedCoveringHit(allowCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in the allowlist` };
             }
             return ALLOW;
@@ -249,6 +262,9 @@ export function createApprovalPolicy(opts) {
     const need = new Set(opts.requireApproval);
     const deny = new Set(opts.deny ?? []);
     const auto = new Set(opts.autoAllow ?? []);
+    const needCovering = namespacedCoveringEntries(opts.requireApproval);
+    const denyCovering = namespacedCoveringEntries(opts.deny);
+    const autoCovering = namespacedCoveringEntries(opts.autoAllow);
     return {
         projection: {
             components: [
@@ -266,10 +282,10 @@ export function createApprovalPolicy(opts) {
         ],
         async check(req, signal) {
             const toolName = req.toolName;
-            if (deny.has(toolName)) {
+            if (deny.has(toolName) || namespacedCoveringHit(denyCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (need.has(toolName)) {
+            if (need.has(toolName) || namespacedCoveringHit(needCovering, toolName)) {
                 if (signal?.aborted) {
                     return withCoreMintedResolution({ action: "deny", message: `approval aborted for "${req.toolName}" (task ended)`, settledBy: "aborted" }, "task_aborted", req);
                 }
@@ -303,7 +319,7 @@ export function createApprovalPolicy(opts) {
                 }
                 return withCoreMintedResolution({ action: "deny", message: `approval denied for "${req.toolName}"`, settledBy: "human" }, "human_refused", req);
             }
-            if (opts.denyByDefault && !auto.has(toolName)) {
+            if (opts.denyByDefault && !auto.has(toolName) && !namespacedCoveringHit(autoCovering, toolName)) {
                 return { action: "deny", message: `tool "${req.toolName}" requires explicit allow` };
             }
             return ALLOW;