@sema-agent/core 5.54.0 → 5.56.0

package/dist/core/hooks.js

@@ -6,6 +6,92 @@ import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
 import { createSafeNotifier } from "./safe-notify.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
+export const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
+const MAX_HOOK_TIMEOUT_MS = 2_147_483_647;
+const POST_ABORT_GRACE_MS = 1_000;
+export function postAbortGraceMs(remainingMs) {
+    return Math.max(0, Math.min(POST_ABORT_GRACE_MS, remainingMs));
+}
+const badHookTimeoutReported = new WeakSet();
+export function resolveHookTimeoutMs(supplied, report, owner) {
+    if (supplied === undefined)
+        return DEFAULT_HOOK_TIMEOUT_MS;
+    if (Number.isFinite(supplied) && supplied >= 0 && supplied <= MAX_HOOK_TIMEOUT_MS)
+        return supplied;
+    if (report !== undefined && !(owner !== undefined && badHookTimeoutReported.has(owner))) {
+        if (owner !== undefined)
+            badHookTimeoutReported.add(owner);
+        try {
+            report(new Error(`Hooks.timeoutMs must be a non-negative finite number no greater than ${MAX_HOOK_TIMEOUT_MS} (got ${String(supplied)}) — ` +
+                `every hook seat falls back to the ${DEFAULT_HOOK_TIMEOUT_MS}ms default`));
+        }
+        catch {
+        }
+    }
+    return DEFAULT_HOOK_TIMEOUT_MS;
+}
+export async function runHookSeat(seat, bound, call) {
+    void seat;
+    const timeoutMs = resolveHookTimeoutMs(bound.timeoutMs, bound.onBadTimeout, bound.owner);
+    const taskSignal = bound.signal;
+    const controller = new AbortController();
+    const pending = Promise.resolve(call(controller.signal));
+    const startedAt = performance.now();
+    return await new Promise((resolve, reject) => {
+        let settled = false;
+        let listening = false;
+        let timer;
+        const clearTimer = () => {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            timer = undefined;
+        };
+        const finish = (act) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimer();
+            if (listening)
+                taskSignal?.removeEventListener("abort", onAbort);
+            act();
+        };
+        const expire = (cause) => finish(() => {
+            void pending.then(undefined, () => {
+            });
+            resolve({ expired: true, cause });
+            queueMicrotask(() => {
+                try {
+                    controller.abort();
+                }
+                catch {
+                }
+            });
+        });
+        const collapseToGrace = () => {
+            if (settled)
+                return;
+            clearTimer();
+            timer = setTimeout(() => expire("aborted"), postAbortGraceMs(timeoutMs - (performance.now() - startedAt)));
+        };
+        const onAbort = () => (bound.abortEnds === true ? expire("aborted") : collapseToGrace());
+        timer = setTimeout(() => expire("timeout"), timeoutMs);
+        if (taskSignal !== undefined) {
+            if (taskSignal.aborted) {
+                onAbort();
+            }
+            else {
+                taskSignal.addEventListener("abort", onAbort, { once: true });
+                listening = true;
+            }
+        }
+        pending.then((value) => finish(() => resolve({ expired: false, value })), (err) => finish(() => reject(err instanceof Error ? err : new Error(String(err)))));
+    });
+}
+export function hookSeatExpiredError(seat, timeoutMs, cause, consequence) {
+    return new Error(cause === "timeout"
+        ? `the deployment's ${seat} hook did not answer within its ${timeoutMs}ms bound (Hooks.timeoutMs) — ${consequence}`
+        : `the deployment's ${seat} hook had not answered when the task was cancelled — ${consequence}`);
+}
 export function cloneObserverInput(input) {
     try {
         return structuredClone(input);
@@ -202,17 +288,35 @@ function preToolUseCrashReason(subject, err) {
         `This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the ` +
         `same hook and fails the same way. Hook error: ${cause || "(no message)"}`);
 }
+function preToolUseUnansweredReason(subject, timeoutMs, cause) {
+    return cause === "timeout"
+        ? `a PreToolUse hook did not answer within its ${timeoutMs}ms bound while screening ${subject}; the call was ` +
+            `NOT executed (fail-closed). This is a failure of the deployment's hook, NOT of the tool itself — the ` +
+            `screening face never returned a verdict, so nothing was decided about this call either way.`
+        : `the task was cancelled while a PreToolUse hook was still screening ${subject}; the call was NOT executed ` +
+            `(fail-closed). No verdict was reached — this is the run ending, not the tool failing.`;
+}
 function screenPreToolUseResult(r) {
     if (r === undefined)
         return undefined;
     return refuseOutOfContractDecision(r, { reasonIsNonInput: true });
 }
-export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash) {
+export function createPreToolUseConstraintPolicy(preToolUse, env, onCrash, timeoutMs) {
     return brandPolicyAskClass({
         check: async (req) => {
             let r;
+            const boundMs = resolveHookTimeoutMs(timeoutMs, onCrash);
             try {
-                r = screenPreToolUseResult(await preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, ...(env !== undefined ? { env } : {}) }));
+                const seat = await runHookSeat("preToolUse", { timeoutMs: boundMs }, (sig) => preToolUse(req.toolName, req.args, { toolCallId: req.toolCallId, toolName: req.toolName, signal: sig, ...(env !== undefined ? { env } : {}) }));
+                if (seat.expired) {
+                    try {
+                        onCrash?.(hookSeatExpiredError("preToolUse", boundMs, seat.cause, `the inherited screening of "${req.toolName}" was refused fail-closed`));
+                    }
+                    catch {
+                    }
+                    return { action: "deny", message: preToolUseUnansweredReason(`this call to "${req.toolName}"`, boundMs, seat.cause), decisionReason: "hook" };
+                }
+                r = screenPreToolUseResult(seat.value);
             }
             catch (err) {
                 try {
@@ -284,9 +388,14 @@ export function persistedRuleMandateOf(marks) {
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
-    const hookCtx = () => ({
+    const hookCtx = (seatSignal) => ({
         toolCallId,
         toolName,
+        ...(seatSignal !== undefined ? { signal: seatSignal } : {}),
+        ...(() => {
+            const c = input.trackedCwd?.();
+            return typeof c === "string" ? { cwd: c } : {};
+        })(),
         ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
         ...(input.identity !== undefined ? { identity: input.identity } : {}),
     });
@@ -296,17 +405,47 @@ export async function runToolGate(input) {
     let parkFailed;
     let askDenyResolution;
     const notifier = createSafeNotifier(input.onNotifyError !== undefined ? { onError: input.onNotifyError } : undefined);
+    const hookSeatMs = resolveHookTimeoutMs(input.hookTimeoutMs, (err) => traceHookCrash(input, err, notifier));
+    const seatBound = (abortEnds) => ({
+        timeoutMs: hookSeatMs,
+        ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}),
+        ...(abortEnds ? { abortEnds: true } : {}),
+    });
+    const preToolUseUnansweredBlock = async (subject, cause) => {
+        const reason = preToolUseUnansweredReason(subject, hookSeatMs, cause);
+        if (cause === "timeout") {
+            traceHookCrash(input, hookSeatExpiredError("preToolUse", hookSeatMs, cause, `${subject} was NOT executed (fail-closed) and the screening face was signalled to stop`), notifier);
+        }
+        return reason;
+    };
+    const notifyPermissionDeniedSeat = async (payload) => {
+        if (input.permissionDenied === undefined)
+            return;
+        await notifier.notifyAsync(async () => {
+            const seat = await runHookSeat("permissionDenied", seatBound(false), (sig) => input.permissionDenied?.({ ...payload, signal: sig }));
+            if (seat.expired)
+                throw hookSeatExpiredError("permissionDenied", hookSeatMs, seat.cause, "the deny observation was abandoned; the deny itself is unchanged");
+        }, "toolGate.permissionDenied");
+    };
     if (preToolUse) {
         let r;
+        let unanswered;
         try {
-            r = screenPreToolUseResult(await preToolUse(toolName, currentInput, hookCtx()));
+            const seat = await runHookSeat("preToolUse", seatBound(true), (sig) => preToolUse(toolName, currentInput, hookCtx(sig)));
+            if (seat.expired)
+                unanswered = seat.cause;
+            else
+                r = screenPreToolUseResult(seat.value);
         }
         catch (err) {
             const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
             traceHookCrash(input, err, notifier);
-            if (input.permissionDenied) {
-                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
-            }
+            await notifyPermissionDeniedSeat({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) });
+            return { block: true, reason: formatHookFeedback(reason, input.reminderMark), preToolContext };
+        }
+        if (unanswered !== undefined) {
+            const reason = await preToolUseUnansweredBlock(`this call to "${toolName}"`, unanswered);
+            await notifyPermissionDeniedSeat({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) });
             return { block: true, reason: formatHookFeedback(reason, input.reminderMark), preToolContext };
         }
         if (r) {
@@ -548,7 +687,7 @@ export async function runToolGate(input) {
                 catch {
                     return { unreadable: true };
                 }
-                return await pendingHit.then(normalizePersistedRuleHit).catch(() => ({ unreadable: true }));
+                return await settleOrgVerdictWithin(pendingHit.then(normalizePersistedRuleHit).catch(() => ({ unreadable: true })), { unreadable: true }, { ...(input.abortSignal !== undefined ? { signal: input.abortSignal } : {}), timeoutMs: ORG_ADJUDICATION_TIMEOUT_MS });
             })();
             const hitEntry = answer.hit;
             const hit = hitEntry?.rule;
@@ -714,8 +853,13 @@ export async function runToolGate(input) {
                     }
                     if (preToolUse) {
                         let hr;
+                        let hrUnanswered;
                         try {
-                            hr = screenPreToolUseResult(await preToolUse(toolName, editArgs, hookCtx()));
+                            const seat = await runHookSeat("preToolUse", seatBound(true), (sig) => preToolUse(toolName, editArgs, hookCtx(sig)));
+                            if (seat.expired)
+                                hrUnanswered = seat.cause;
+                            else
+                                hr = screenPreToolUseResult(seat.value);
                         }
                         catch (err) {
                             traceHookCrash(input, err, notifier);
@@ -723,6 +867,11 @@ export async function runToolGate(input) {
                             denySource = "hook";
                             break;
                         }
+                        if (hrUnanswered !== undefined) {
+                            editDenied = { action: "deny", message: await preToolUseUnansweredBlock(`the approved edit for "${toolName}"`, hrUnanswered) };
+                            denySource = "hook";
+                            break;
+                        }
                         if (hr) {
                             if (hr.additionalContext)
                                 preToolContext.push(hr.additionalContext);
@@ -828,9 +977,7 @@ export async function runToolGate(input) {
             currentInput = decision.updatedInput;
         }
         const denyResolution = askDenyResolution ?? coreMintedResolutionOf(decision, { toolCallId, toolName });
-        if (input.permissionDenied) {
-            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(denyResolution !== undefined ? { resolution: denyResolution } : {}), ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
-        }
+        await notifyPermissionDeniedSeat({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(denyResolution !== undefined ? { resolution: denyResolution } : {}), ...(input.identity !== undefined ? { identity: input.identity } : {}) });
         const denySettledBy = decision.settledBy;
         const denyApprover = denySettledBy !== undefined ? resolvedApprover : undefined;
         return {

package/dist/core/human-input-projection.d.ts

@@ -4,8 +4,13 @@
  * One renderer covers every human-input carrier: the core-side five (objective / live steer /
  * nextTurn / the resume tail's parked-steer frames / the wake message) and a serving layer's own
  * carriers through the same contract. The division of labor is fixed (ruled 2026-08-05): the INGRESS
- * sanitizes text and mints the {@link ActorAssertion}; this module only PROJECTS — it renders the
- * speaker label ahead of the text, and it never sanitizes, truncates, or rewrites the text itself.
+ * sanitizes text and mints the {@link ActorAssertion}; `projectHumanInput` only PROJECTS — it renders
+ * the speaker label ahead of the text, and it never sanitizes, truncates, or rewrites the text itself.
+ *
+ * The module also owns the DELIVERY frame that tells the model where a human frame arrived
+ * ({@link frameMidTurnUserInput}, backlog #389). That is a separate concern from attribution and runs
+ * AFTER projection (the speaker label belongs to the text; the delivery frame belongs around it) — it is
+ * housed here so every model-facing wrapper for human input has one home.
  *
  * Envelope contract:
  *  - no `actor` ⇒ BYTE-IDENTICAL passthrough. Every pre-171 caller and every single-user host
@@ -35,6 +40,19 @@ export interface HumanInputFrame {
     actor?: ActorAssertion;
     source: HumanInputSource;
 }
+/**
+ * backlog #389 伴生 (V-3 of the steer/interrupt/lifecycle anchor audit) — wrap ONE live caller steer in
+ * the mid-turn delivery frame.
+ *
+ * Scope, deliberately: the UNTRUSTED caller lane only. A `trusted` steer already rides a
+ * `<system-reminder>` (supervisor authority, CC's own non-user-source framing), and a delegated child's
+ * operator steer carries its own explicit operator frame — the bare lane was exactly the most-travelled
+ * one: a person typing while the run works.
+ *
+ * Static strings (no per-call interpolation), and a blank projection is returned VERBATIM so the
+ * harness's empty-injection no-op stays a no-op — a frame must never materialize from nothing.
+ */
+export declare function frameMidTurnUserInput(projected: string): string;
 /**
  * Render the speaker envelope for one human-input frame. Pure; see the module contract above.
  * Call BEFORE any trust framing (`formatHookFeedback` / `delimitUntrusted`) so the label stays

package/dist/core/human-input-projection.js

@@ -2,6 +2,15 @@ import { snapshotActorAssertion } from "../internal/llm.js";
 import { uuidv7 } from "../internal/harness.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { attrEscape, EXTERNAL_SOURCE_MAX } from "./task-notification.js";
+const MID_TURN_USER_INPUT_HEAD = "The user sent a new message while you were working:\n";
+const MID_TURN_USER_INPUT_TAIL = "\n\nThis is how a message sent mid-turn is surfaced: within the turn that is still running, often " +
+    "alongside the next tool result, rather than as a separate conversation turn. Address the message " +
+    "above as you continue this turn.";
+export function frameMidTurnUserInput(projected) {
+    if (projected.trim().length === 0)
+        return projected;
+    return `${MID_TURN_USER_INPUT_HEAD}${projected}${MID_TURN_USER_INPUT_TAIL}`;
+}
 export function projectHumanInput(frame) {
     if (frame.actor === undefined || frame.source === "system")
         return frame.text;

package/dist/core/lsp-diagnostics.d.ts

@@ -1,19 +1,3 @@
-/**
- * design/121 — LSP diagnostics registry + model-facing formatting (CC 2.1.198 parity).
- *
- * CC's two diagnostics sources (IDE MCP baseline/diff + passive LSP publishDiagnostics) collapse to
- * ONE in sema: the passive registry. The "only NEW diagnostics" semantics CC gets from per-file
- * baselines falls out of the delivered-set here — a diagnostic is injected at most once PER RUN, and a
- * run editing a file clears its delivered set so a persisting problem can resurface (CC `Fjn` same
- * behavior). The registry object itself is deployment-scoped, so "per run" is a keyed fact, not an
- * object lifetime; see {@link LspDiagnosticsRegistry}.
- *
- * Volumes and wire format are CC-exact (198:320661 `Njn=10, nqa=30`; 198:320480-320505 summary +
- * 4000-char cap; severity symbols ✖/⚠/ℹ/★).
- *
- * NOT durable: diagnostics regenerate from the language server on the next edit; a suspend/resume
- * simply starts empty (recorded in design/121 §2).
- */
 /** One LSP diagnostic, the subset the model/shell needs (LSP `Diagnostic` narrowed). */
 export interface LspDiagnostic {
     message: string;
@@ -102,7 +86,25 @@ export declare class LspDiagnosticsRegistry {
  *   {symbol} [Line {line+1}:{col+1}] {message}[ [{code}]][ ({source})]
  * ```
  * capped at 4000 chars with an honest `…[truncated]` tail.
+ *
+ * ENVELOPE CONTAINMENT (untrusted-text.ts `ENGINE_ENVELOPES`, the `new-diagnostics` row): the
+ * per-diagnostic strings (`message`, `code`, `source`) and the file basename come from a LANGUAGE
+ * SERVER — a process the engine launches over repository content, i.e. the same trust class as the
+ * repository. They land inside the `<new-diagnostics>` envelope, and (since this block is now
+ * delivered inside a marked reminder shell) inside an authority-marked reminder too, so a diagnostic
+ * message carrying `</new-diagnostics>` closed the envelope and placed server text at the top level
+ * of engine-authored authority. CC 223 does not neutralize here either — a deliberate, disclosed
+ * hardening divergence: CC ships the same block inside the same reminder shell, so the hole exists on
+ * both sides and only the fix is ours. Neutralization runs BEFORE the join, so the 4000-char cap
+ * still bounds the FINAL text and can never cut inside a neutralized marker's own bytes.
  */
 export declare function formatDiagnosticsSummary(files: LspFileDiagnostics[]): string;
-/** CC 198 model-facing injection block (198:320500-320503), verbatim framing. */
+/** CC 198 model-facing injection block (198:320500-320503), verbatim framing.
+ *
+ *  DELIVERY (design/319 sibling work): the runner shells this block in a MARKED `<system-reminder>`
+ *  before steering it — CC 223 `case "diagnostics"` does the same (`ih([Vr({content: …})])` → the
+ *  reminder wrap), and until that was matched this was the engine's only authority text reaching the
+ *  model as a bare block with no provenance mark at all. The block's own bytes are unchanged; the
+ *  shell is applied at the delivery site (runtask), not baked in here, so this exported renderer keeps
+ *  serving callers that place the block themselves. */
 export declare function formatDiagnosticsBlock(files: LspFileDiagnostics[]): string;

package/dist/core/lsp-diagnostics.js

@@ -1,3 +1,4 @@
+import { sanitizeUntrustedText, SHELLED_BODY_ENVELOPE_TAGS } from "./untrusted-text.js";
 const MAX_PER_FILE = 10;
 const MAX_TOTAL = 30;
 const MAX_SUMMARY_CHARS = 4000;
@@ -79,14 +80,19 @@ function basenameOfUri(uri) {
     return idx >= 0 ? path.slice(idx + 1) : path;
 }
 export function formatDiagnosticsSummary(files) {
+    const safe = (t) => sanitizeUntrustedText(t, SHELLED_BODY_ENVELOPE_TAGS);
     const lines = [];
     for (const f of files) {
-        lines.push(`${basenameOfUri(f.uri)}:`);
+        lines.push(`${safe(basenameOfUri(f.uri))}:`);
         for (const d of f.diagnostics) {
-            const pos = d.range ? `[Line ${d.range.start.line + 1}:${d.range.start.character + 1}] ` : "";
-            const code = d.code !== undefined ? ` [${d.code}]` : "";
-            const source = d.source ? ` (${d.source})` : "";
-            lines.push(`  ${severitySymbol(d.severity)} ${pos}${d.message}${code}${source}`);
+            const startLine = d.range?.start?.line;
+            const startChar = d.range?.start?.character;
+            const pos = typeof startLine === "number" && Number.isFinite(startLine) && typeof startChar === "number" && Number.isFinite(startChar)
+                ? `[Line ${Math.trunc(startLine) + 1}:${Math.trunc(startChar) + 1}] `
+                : "";
+            const code = d.code !== undefined ? ` [${safe(String(d.code))}]` : "";
+            const source = d.source ? ` (${safe(String(d.source))})` : "";
+            lines.push(`  ${severitySymbol(d.severity)} ${pos}${safe(String(d.message))}${code}${source}`);
         }
     }
     const summary = lines.join("\n");

package/dist/core/mcp.d.ts

@@ -488,6 +488,30 @@ interface McpContentItem {
     };
 }
 export declare function mapContent(content: Array<McpContentItem>, serverName?: string, imageResizer?: McpImageResizer): Promise<Array<TextContent | ImageContent>>;
+/**
+ * Connect to each MCP server, list its tools, and wrap them as AgentTools.
+ * Tools are namespaced `mcp__<server>__<tool>` (CC parity) to avoid collisions. The model sees each
+ * tool's real JSON-Schema (`inputSchema`), which the agent loop validates natively.
+ *
+ * Fail-open (design/29): a server that fails to connect or list tools is SKIPPED — its error is
+ * returned in `warnings`, the healthy servers still materialize. A single misconfigured server
+ * (bad stdio command, unreachable URL) never bricks the whole task.
+ *
+ * Call `dispose()` when the task finishes — connections are task-scoped, never persisted.
+ */
+/**
+ * Invisible / format / private-use / unassigned characters stripped out of every model-facing string a
+ * server advertises — CC `MZg` :144247. CC spells this as the property class BELOW followed by five
+ * explicit ranges (zero-width U+200B–U+200F, bidi embedding U+202A–U+202E, bidi isolates U+2066–U+2069,
+ * the BOM, and the BMP private-use area); on this engine's Unicode data every one of those code points
+ * is already `Cf` or `Co`, so the class alone is byte-equivalent to CC's expression and the source stays
+ * free of literal invisible characters (a file carrying them is a grep blind spot, and this repo has
+ * paid for that once already). The equivalence is asserted by a pin, not assumed — a Unicode-data change
+ * that moved any of those ranges out of the class would open exactly the hole this strips.
+ *
+ * `\p{Cc}` is deliberately NOT here: newlines and tabs are legitimate description formatting.
+ */
+export declare const MCP_INVISIBLE_TEXT_RE: RegExp;
 /** One tool's schema-normalization outcome (CC 220 `zyo` @336616-336654's return shape). */
 export type McpSchemaNormalizeResult = {
     outcome: "unchanged";
@@ -537,6 +561,28 @@ export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormal
  * to catch, and this gate alone does not catch it (no type key ⇒ passes the root-type check; the
  * combinator's own structure is legal JSON Schema ⇒ passes validateJsonSchemaShape too).
  */
+/**
+ * A schema defect the operator must HEAR about but that must not cost the tool its mount — returns a
+ * core-authored sentence, or `undefined` when there is nothing to say.
+ *
+ * Today that is exactly one thing: a TOP-LEVEL parameter name outside `[a-zA-Z0-9_.-]{1,64}`. A name
+ * like `"user name"` is rejected at the Anthropic wire, and because the tool table rides EVERY request
+ * it takes the whole request down with it — while the operator previously got nothing at all pointing
+ * at the cause (no warning, no drop record, just a task that stopped working). CC checks the identical
+ * names against the identical expression (`EX_`/`_xo` :325793/:325824, reported as `check:"propertyKey"`).
+ *
+ * WHY AN ADVISORY AND NOT A DROP, stated because the sibling structural gate above does drop: CC's own
+ * disposition here is keep-and-warn — its drop arm sits behind a rollout flag that ships OFF (`Xyd` /
+ * `Yyd` :354641/:354622, an empty remote-config list ⇒ false), so CC's shipped behavior is to keep the
+ * tool and warn "requests that include it may fail". The difference from the structural half is real
+ * and not a technicality: a schema with no object root is unusable everywhere, whereas this charset is
+ * ONE provider's rule, and this engine is bring-your-own-model. Dropping here would delete a working
+ * tool from a deployment whose provider accepts the name — a Chinese- or Japanese-named parameter is
+ * the ordinary case, not a hostile one. Detection was the gap; removal was never the mandate.
+ *
+ * TOP-LEVEL only, like CC: a nested property name is not what the provider validates.
+ */
+export declare function mcpToolSchemaAdvisory(schema: unknown): string | undefined;
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
 export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer, // design/116 CONFIRM-1 seam: deployment-injected; default = auto-detected sharp
 reminderDisclosure?: {

package/dist/core/mcp.js

@@ -537,6 +537,82 @@ export async function mapContent(content, serverName, imageResizer) {
     }
     return out;
 }
+export const MCP_INVISIBLE_TEXT_RE = /[\p{Cf}\p{Co}\p{Cn}]/gu;
+const MCP_SANITIZE_MAX_ROUNDS = 10;
+function sanitizeMcpModelFacingText(text) {
+    let out = text;
+    for (let round = 0; round < MCP_SANITIZE_MAX_ROUNDS; round++) {
+        const next = out.normalize("NFKC").replace(MCP_INVISIBLE_TEXT_RE, "");
+        if (next === out)
+            return out;
+        out = next;
+    }
+    return out.replace(MCP_INVISIBLE_TEXT_RE, "");
+}
+const MCP_SCHEMA_PROSE_KEYS = new Set(["description", "title", "$comment"]);
+const MCP_SCHEMA_CHILD_SEAT = new Map([
+    ...["properties", "definitions", "$defs", "dependentSchemas"].map((k) => [k, "properties"]),
+    ...["patternProperties"].map((k) => [k, "schemaMap"]),
+    ...["items", "prefixItems", "additionalItems", "additionalProperties", "unevaluatedItems", "unevaluatedProperties", "contains", "propertyNames", "contentSchema", "not", "if", "then", "else", "allOf", "anyOf", "oneOf"].map((k) => [k, "schema"]),
+    ...["required", "dependentRequired", "dependencies", "$ref", "$dynamicRef", "$id", "$anchor", "$dynamicAnchor"].map((k) => [k, "nameRefs"]),
+]);
+class McpPayloadKeyCollision extends Error {
+}
+function sanitizeMcpSchemaNameRefs(value) {
+    if (typeof value === "string")
+        return sanitizeMcpModelFacingText(value);
+    if (Array.isArray(value))
+        return value.map(sanitizeMcpSchemaNameRefs);
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, v] of Object.entries(value)) {
+            const neutralized = sanitizeMcpModelFacingText(key);
+            if (Object.hasOwn(out, neutralized))
+                throw new McpPayloadKeyCollision(neutralized);
+            out[neutralized] = Array.isArray(v) ? sanitizeMcpSchemaNameRefs(v) : sanitizeMcpModelFacingValue(v, "schema");
+        }
+        return out;
+    }
+    return value;
+}
+function sanitizeMcpModelFacingValue(value, seat = "schema") {
+    if (seat === "data")
+        return value;
+    if (seat === "nameRefs")
+        return sanitizeMcpSchemaNameRefs(value);
+    if (Array.isArray(value))
+        return value.map((v) => sanitizeMcpModelFacingValue(v, seat === "schema" ? "schema" : "data"));
+    if (value !== null && typeof value === "object") {
+        const out = Object.create(null);
+        for (const [key, v] of Object.entries(value)) {
+            if (seat === "schemaMap") {
+                out[key] = sanitizeMcpModelFacingValue(v, "schema");
+                continue;
+            }
+            const neutralized = sanitizeMcpModelFacingText(key);
+            if (Object.hasOwn(out, neutralized))
+                throw new McpPayloadKeyCollision(neutralized);
+            if (seat === "properties") {
+                out[neutralized] = sanitizeMcpModelFacingValue(v, "schema");
+                continue;
+            }
+            if (MCP_SCHEMA_PROSE_KEYS.has(neutralized)) {
+                out[neutralized] = typeof v === "string" ? sanitizeMcpModelFacingText(v) : v;
+                continue;
+            }
+            out[neutralized] = sanitizeMcpModelFacingValue(v, MCP_SCHEMA_CHILD_SEAT.get(neutralized) ?? "data");
+        }
+        return out;
+    }
+    return value;
+}
+const MCP_TOOL_DESCRIPTION_MAX_CHARS = 2048;
+const MCP_TOOL_DESCRIPTION_TRUNCATION_MARK = "… [truncated]";
+function capMcpToolDescription(description) {
+    if (description.length <= MCP_TOOL_DESCRIPTION_MAX_CHARS)
+        return description;
+    return sliceHeadSafe(description, MCP_TOOL_DESCRIPTION_MAX_CHARS) + MCP_TOOL_DESCRIPTION_TRUNCATION_MARK;
+}
 const MCP_SCHEMA_COMBINATOR_KEYS = ["anyOf", "oneOf", "allOf"];
 const MCP_SCHEMA_PROP_NAME_RE = /^[a-zA-Z0-9_.-]{1,64}$/;
 const MCP_SCHEMA_CARRY_KEYS = ["$defs", "definitions", "$schema", "additionalProperties", "description", "title"];
@@ -643,6 +719,19 @@ export function normalizeMcpToolSchema(schema) {
         return { outcome: "drop", reason: `input schema uses top-level ${combinatorsPresent.join("/")} and could not be normalized` };
     }
 }
+export function mcpToolSchemaAdvisory(schema) {
+    if (schema === undefined || !isPlainSchemaObject(schema))
+        return undefined;
+    const properties = schema.properties;
+    if (!isPlainSchemaObject(properties))
+        return undefined;
+    for (const key of Object.keys(properties)) {
+        if (!MCP_SCHEMA_PROP_NAME_RE.test(key)) {
+            return `its parameter name ${inlineUntrusted(JSON.stringify(key), 80)} is outside the character set some providers accept for tool parameters (${MCP_SCHEMA_PROP_NAME_RE.source}); requests carrying this tool may be rejected by such a provider`;
+        }
+    }
+    return undefined;
+}
 export function mcpToolSchemaProblem(schema) {
     if (schema === undefined)
         return undefined;
@@ -741,6 +830,11 @@ export async function materializeMcpTools(specs, principal, onElicit, imageResiz
                     resourceServers.push(s.resourceServer);
                 for (const d of s.dropped)
                     droppedTools.push({ server: inlineUntrusted(spec.name, 160), ...d });
+                for (const a of s.schemaAdvisories)
+                    warnings.push(schemaAdvisoryWarning(spec.name, a.tool, a.reason));
+                if (s.toolsCapabilityAbsent === true && spec.allowTools !== undefined && spec.allowTools.length > 0) {
+                    warnings.push(toolsCapabilityAbsentWarning(spec.name));
+                }
                 if (s.listingIncomplete)
                     warnings.push(listingIncompleteWarning(spec.name, s.listingIncomplete));
                 statuses.push(s.status);
@@ -1329,6 +1423,8 @@ export function parseCallToolResultLenient(data) {
 }
 const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
 async function listToolsLenient(client, options) {
+    if (!client.getServerCapabilities()?.tools)
+        return { tools: [], toolsCapabilityAbsent: true };
     const walk = await walkMcpListPages(async (cursor, remainingMs) => {
         const page = await client.request({ method: "tools/list", params: cursor === undefined ? {} : { cursor } }, LenientListToolsResultSchema, { ...options, timeout: remainingMs });
         return {
@@ -1379,7 +1475,7 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
         };
         const listed = await listToolsLenient(client, startupOpts);
         cacheMcpToolMetadata(client, listed.tools);
-        const { serverTools, serverAxes, dropped } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
+        const { serverTools, serverAxes, dropped, advisories } = intakeListedTools(listed, spec, client, health, imageResizer, reminderDisclosure, isServerRevoked);
         const caps = client.getServerCapabilities();
         const resourceInfo = caps?.resources
             ? {
@@ -1403,6 +1499,8 @@ async function connectServer(spec, principal, onElicit, imageResizer, reminderDi
             tools: serverTools,
             axes: serverAxes,
             dropped,
+            schemaAdvisories: advisories,
+            ...(listed.toolsCapabilityAbsent === true ? { toolsCapabilityAbsent: true } : {}),
             listedTools: listed.tools,
             ...(instructions ? { instructions } : {}),
             ...(listed.incomplete !== undefined ? { listingIncomplete: listed.incomplete } : {}),
@@ -1418,14 +1516,28 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
     const serverTools = [];
     const serverAxes = [];
     const dropped = [];
+    const advisories = [];
     const mintedNames = new Map();
     for (const t of listed.tools) {
         if (spec.allowTools && !spec.allowTools.includes(t.name)) {
             continue;
         }
-        const normalized = normalizeMcpToolSchema(t.inputSchema);
-        let effectiveInputSchema = t.inputSchema;
-        let effectiveDescription = t.description !== undefined ? sanitizeUntrustedText(t.description) : undefined;
+        let modelFacingSchema;
+        let sanitizedDescription;
+        try {
+            modelFacingSchema = sanitizeMcpModelFacingValue(t.inputSchema);
+            sanitizedDescription = t.description !== undefined ? sanitizeMcpModelFacingText(t.description) : undefined;
+        }
+        catch (err) {
+            const reason = err instanceof McpPayloadKeyCollision
+                ? `two of its advertised names neutralize to the same model-facing spelling ${inlineUntrusted(JSON.stringify(err.message), 80)}; one parameter would have vanished from the schema the model is given while the server still expects it`
+                : "advertised tool payload could not be neutralized for model-facing display (pathological nesting)";
+            dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(reason, 240) });
+            continue;
+        }
+        const normalized = normalizeMcpToolSchema(modelFacingSchema);
+        let effectiveInputSchema = modelFacingSchema;
+        let effectiveDescription = sanitizedDescription !== undefined ? sanitizeUntrustedText(sanitizedDescription) : undefined;
         if (normalized.outcome === "drop") {
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(normalized.reason, 240) });
             continue;
@@ -1439,6 +1551,10 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             dropped.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaProblem, 240) });
             continue;
         }
+        const schemaAdvisory = mcpToolSchemaAdvisory(effectiveInputSchema);
+        if (schemaAdvisory !== undefined) {
+            advisories.push({ tool: inlineUntrusted(t.name), reason: inlineUntrusted(schemaAdvisory, 240) });
+        }
         const remoteName = t.name;
         const namespacedName = mintNamespacedToolName(MCP_NAMESPACE, spec.name, remoteName);
         const mintedBy = mintedNames.get(namespacedName);
@@ -1462,7 +1578,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
         const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
         serverTools.push({
             name: namespacedName,
-            description: effectiveDescription ?? `MCP tool ${remoteName} from ${spec.name}`,
+            description: capMcpToolDescription(effectiveDescription ?? `MCP tool ${inlineUntrusted(sanitizeMcpModelFacingText(remoteName))} from ${spec.name}`),
             label: `${spec.name}:${remoteName}`,
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
@@ -1564,13 +1680,23 @@ function intakeListedTools(listed, spec, client, health, imageResizer, reminderD
             },
         });
     }
-    return { serverTools, serverAxes, dropped };
+    return { serverTools, serverAxes, dropped, advisories };
 }
 function asServerWarning(spec, err) {
     const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${namedMcpFailureText(err)})`, { cause: err });
     warning.code = "mcp.server_unavailable";
     return warning;
 }
+function schemaAdvisoryWarning(server, tool, reason) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" tool "${tool}" is mounted, but ${reason}.`);
+    warning.code = "mcp.tool_schema_advisory";
+    return warning;
+}
+function toolsCapabilityAbsentWarning(server) {
+    const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" declared no "tools" capability, so no tool listing was requested and none of the tools named in this server's allowTools can be mounted. If the server does serve tools, it must declare the capability at initialize.`);
+    warning.code = "mcp.tools_capability_absent";
+    return warning;
+}
 function listingIncompleteWarning(server, flag) {
     const warning = new Error(`mcp: server "${inlineUntrusted(server, 160)}" listed its tools INCOMPLETELY — ${listingIncompleteNote(flag)}. The tools beyond the ${flag.pages} page${flag.pages === 1 ? "" : "s"} retrieved are NOT mounted for this task.`);
     warning.code = "mcp.listing_incomplete";