@sema-agent/core 7.51.2 → 7.53.0

package/dist/brain/route-conformance.js

@@ -1,7 +1,7 @@
 export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
     {
         name: "per-model-on-root",
-        intent: "a per-model credential is paired by construction, on the deployment root",
+        intent: "a per-model credential not bound yet is servable, on the deployment root",
         model: { id: "m-main", baseUrl: "https://gw.example.com" },
         credential: { source: "per-model", apiKey: "k-main" },
         config: { baseUrl: "https://gw.example.com" },
@@ -9,7 +9,7 @@ export const ROUTE_ADJUDICATION_CONFORMANCE_CORPUS = [
     },
     {
         name: "per-model-off-root",
-        intent: "a per-model credential is paired by construction even off the deployment root (the resolver was asked about THIS entry)",
+        intent: "a per-model credential not bound yet is servable off the deployment root too (the resolver was asked about THIS entry)",
         model: { id: "m-third", baseUrl: "https://third-party.example.net/v1" },
         credential: { source: "per-model", apiKey: "k-third" },
         config: { baseUrl: "https://gw.example.com" },

package/dist/brain/routing.d.ts

@@ -5,9 +5,31 @@ export interface RoutingBrainOptions {
     /** Brain used when no route matches. If omitted, an unmatched model yields an error. */
     fallback?: Brain;
 }
+/** The two `Model` fields a route can be named by — a catalog entry that carries only a provider word is as good a subject as a whole `Model`. */
+type RouteWords = {
+    readonly provider?: string | undefined;
+    readonly api?: string | undefined;
+};
+/**
+ * THE judge of which line serves a model: the model's route word (`provider`, or `api` when `by` says so) IF the route table
+ * has an OWN route under that word, else `undefined` — the fallback (the deployment's gateway) serves it. A word the model
+ * carries without a route, and a model with no string word at all, both answer `undefined`: a route that is not mounted is
+ * not a line, whatever the model says.
+ *
+ * `routes` is the route TABLE itself — the very object a host hands {@link createRoutingBrain}, which asks this function for
+ * every request — so the judge and the router answer from one reading of one table, whatever its shape. The question is
+ * `Object.hasOwn(routes, word)`: it evaluates no entry and lists no keys, so a non-enumerable own route is a route, a lazily
+ * keyed table is asked about the one name it is asked about, and a name the table only inherits (`constructor`, `__proto__`)
+ * is not a route. The judge never reads a route's value: a route mounted under the word IS the line, and when its value is not
+ * a brain the router fails that request on that line (an error terminal naming the route) rather than moving it to the
+ * fallback — so the line this answers is the line the request was sent to, either way. A table that cannot answer the question
+ * (it is not an object, or its trap throws) throws here, and the router fails the request with an error terminal.
+ */
+export declare function brainLaneOf(model: RouteWords, routes: Readonly<Record<string, unknown>>, by?: NonNullable<RoutingBrainOptions["by"]>): string | undefined;
 /**
  * Route to different brains by a Model field (default `model.provider`). Lets one Runner serve
- * multiple providers/gateways; compose with `createFailoverBrain` for per-route failover.
+ * multiple providers/gateways; compose with `createFailoverBrain` for per-route failover. Which route serves a
+ * model is {@link brainLaneOf}'s answer.
  *
  * @example
  * createRoutingBrain({
@@ -16,3 +38,4 @@ export interface RoutingBrainOptions {
  * }, { fallback: createOpenAIBrain({ baseUrl: VLLM }) });
  */
 export declare function createRoutingBrain(routes: Record<string, Brain>, opts?: RoutingBrainOptions): Brain;
+export {};

package/dist/brain/routing.js

@@ -1,42 +1,77 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { ZERO_USAGE } from "./errors.js";
-function errorMessage(model, text) {
+function errorMessage(who, text) {
     return {
         role: "assistant",
         content: [{ type: "text", text: "" }],
-        api: model.api,
-        provider: model.provider,
-        model: model.id,
+        api: who.api,
+        provider: who.provider,
+        model: who.id,
         stopReason: "error",
         errorMessage: text,
         usage: ZERO_USAGE,
         timestamp: Date.now(),
     };
 }
+const BLANK_IDENTITY = { api: "", provider: "", id: "" };
+function spelled(word) {
+    return (typeof word === "object" && word !== null) || typeof word === "function" ? `[${typeof word}]` : String(word);
+}
+function routeKeyOf(model, by) {
+    return by === "api" ? model.api : model.provider;
+}
+function isBrain(value) {
+    return value !== null && typeof value === "object" && typeof value.stream === "function";
+}
+export function brainLaneOf(model, routes, by = "provider") {
+    const word = routeKeyOf(model, by);
+    return typeof word === "string" && Object.hasOwn(routes, word) ? word : undefined;
+}
 export function createRoutingBrain(routes, opts = {}) {
     const by = opts.by ?? "provider";
     const resolveTarget = (model) => {
-        const key = by === "api" ? model.api : model.provider;
-        const routed = Object.hasOwn(routes, key) ? routes[key] : undefined;
-        const matched = routed !== null && typeof routed === "object" && typeof routed.stream === "function"
-            ? routed
-            : undefined;
-        return matched ?? opts.fallback;
+        const lane = brainLaneOf(model, routes, by);
+        if (lane === undefined)
+            return { target: opts.fallback };
+        const routed = routes[lane];
+        return isBrain(routed) ? { target: routed } : { broken: `route ${by}="${lane}" is mounted but its value is not a brain` };
     };
     const stream = (model, context, options) => {
-        const key = by === "api" ? model.api : model.provider;
-        const target = resolveTarget(model);
-        if (!target) {
+        const reject = (text, named) => {
             const out = createAssistantMessageEventStream();
-            out.push({
-                type: "error",
-                reason: "error",
-                error: errorMessage(model, `createRoutingBrain: no brain for ${by}="${key}"`),
-            });
+            try {
+                const wordOf = (field) => (field === by && named !== undefined ? named.value : model[field]);
+                out.push({ type: "error", reason: "error", error: errorMessage({ api: wordOf("api"), provider: wordOf("provider"), id: wordOf("id") }, text) });
+            }
+            catch {
+                out.push({ type: "error", reason: "error", error: errorMessage(BLANK_IDENTITY, `${text} (the model's own words could not be read either)`) });
+            }
             return out;
+        };
+        let word;
+        try {
+            word = { value: routeKeyOf(model, by) };
         }
+        catch {
+            return reject(`createRoutingBrain: the model's ${by} could not be read`);
+        }
+        const named = word.value;
+        const asked = { api: named, provider: named };
+        let resolved;
+        try {
+            resolved = resolveTarget(asked);
+        }
+        catch {
+            return reject(`createRoutingBrain: the route table threw while ${by}="${spelled(named)}" was looked up`, word);
+        }
+        const target = "target" in resolved ? resolved.target : undefined;
+        if (!target)
+            return reject("broken" in resolved ? `createRoutingBrain: ${resolved.broken}` : `createRoutingBrain: no brain for ${by}="${spelled(named)}"`, word);
         return target.stream(model, context, options);
     };
-    const adjudicateRoute = (model, perModelAuth) => resolveTarget(model)?.adjudicateRoute?.(model, perModelAuth);
+    const adjudicateRoute = (model, perModelAuth) => {
+        const resolved = resolveTarget(model);
+        return "target" in resolved ? resolved.target?.adjudicateRoute?.(model, perModelAuth) : undefined;
+    };
     return { stream, adjudicateRoute };
 }

package/dist/brain/status-sink.d.ts

@@ -150,3 +150,21 @@ export declare function runWithExtraBodyDropped<T>(observe: (r: ExtraBodyDropped
 /** Report the strip of the request the engine has SELECTED to send, to the active per-run sink, if any (called at the
  *  engine's commit points, never from `buildRequest`, which is also built speculatively). */
 export declare function reportExtraBodyDropped(report: ExtraBodyDroppedReport): void;
+/** A request refused because the per-model credential it would carry is bound to another origin: the catalog id it was
+ *  for and the two origins, each in its DISPLAY spelling. Never a value, never a digest of one. */
+export interface CredentialOriginRefusalReport {
+    modelId: string;
+    boundOrigin: string;
+    requestOrigin: string;
+}
+/**
+ * Run `fn` with a per-run credential-origin refusal sink in scope — the FIFTH brain→runner ALS channel, with the fourth's
+ * shape and for its reasons: the WHOLE leg (a refused compaction summary, side query or classifier call is refused for the
+ * same reason as a turn), not shielded around the leg's internal calls, not revoked on settlement, no-op outside the scope.
+ * The refusal is already decided when it is reported.
+ */
+export declare function runWithCredentialOriginRefusals<T>(observe: (r: CredentialOriginRefusalReport) => void, fn: () => Promise<T>): Promise<T>;
+/** Report a credential-origin refusal to the active per-run sink, if any (called by the request gate's refusal,
+ *  `routeRefusalError`; a judgment that only advises reports nothing). The
+ *  observer is the Runner's own seat, whose one delivery is the guarded `deliverEngineNotice` — nothing is swallowed here. */
+export declare function reportCredentialOriginRefusal(report: CredentialOriginRefusalReport): void;

package/dist/brain/status-sink.js

@@ -68,3 +68,10 @@ export function reportExtraBodyDropped(report) {
     catch {
     }
 }
+const credentialOriginRefusalSinkStore = new AsyncLocalStorage();
+export function runWithCredentialOriginRefusals(observe, fn) {
+    return credentialOriginRefusalSinkStore.run({ observe }, fn);
+}
+export function reportCredentialOriginRefusal(report) {
+    credentialOriginRefusalSinkStore.getStore()?.observe(report);
+}

package/dist/brain/timeout.js

@@ -1,14 +1,15 @@
+import { describeRejectedValue } from "../core/tool-search-setting.js";
 export const MAX_TIMER_DELAY_MS = 2_147_483_647;
 export function resolveStallTimeoutMs(value, knob) {
     if (value === undefined)
         return undefined;
     if (!Number.isFinite(value) || value < 0) {
-        const e = new Error(`${knob} must be a non-negative finite number of milliseconds (got ${String(value)})`);
+        const e = new Error(`${knob} must be a non-negative finite number of milliseconds (got ${describeRejectedValue(value)})`);
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
     if (value > MAX_TIMER_DELAY_MS) {
-        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${String(value)}). Pass 0 to disable it.`);
+        const e = new Error(`${knob} must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so this watchdog would abort every call instead of tolerating a long one (got ${describeRejectedValue(value)}). Pass 0 to disable it.`);
         e.code = "config.stall_timeout_invalid";
         throw e;
     }
@@ -112,12 +113,12 @@ export function resolveBrainCallGuardrailMs(knob) {
     if (knob === false || knob === 0)
         return undefined;
     if (typeof knob !== "number" || !Number.isFinite(knob) || knob < 0) {
-        const e = new Error(`brainCallGuardrailMs must be a positive number of milliseconds, 0, or false (got ${String(knob)})`);
+        const e = new Error(`brainCallGuardrailMs must be a positive number of milliseconds, 0, or false (got ${describeRejectedValue(knob)})`);
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }
     if (knob > MAX_TIMER_DELAY_MS) {
-        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${String(knob)}). Pass false or 0 to turn the backstop off.`);
+        const e = new Error(`brainCallGuardrailMs must not exceed ${MAX_TIMER_DELAY_MS}ms (~24.8 days) — a host timer truncates a larger delay and fires immediately, so the backstop would abort every model call (got ${describeRejectedValue(knob)}). Pass false or 0 to turn the backstop off.`);
         e.code = "config.brain_call_guardrail_invalid";
         throw e;
     }

package/dist/core/a2a.d.ts

@@ -69,8 +69,11 @@ export interface MaterializedA2a {
     /** One entry per DECLARED peer, in declaration order, ready or failed — the declaration as this materialization read it once. */
     statuses: A2aPeerStatus[];
     /** Re-read one peer's card (or every declared peer) and re-derive its tools. Unlike the MCP refresh
-     *  this dials nothing new — every A2A call is a fresh request anyway — so a peer that failed at
-     *  prepare time can genuinely recover here. */
+     *  this dials nothing new — every A2A call is a fresh request anyway — so a peer whose card or network
+     *  failed at prepare time can genuinely recover here. The DECLARATION is not re-read: a refresh works
+     *  from the copy this materialization took and judged — the members too (`headers`, `allowSkills`,
+     *  `toolAxes` are copied, not shared) — so a declaration refused then is refused again and a caller
+     *  rewriting its object afterwards, by replacing a member or by editing one in place, changes nothing. */
     refresh: (peer?: string) => Promise<A2aRefreshResult[]>;
     /**
      * Task teardown. There is no socket to close (every call is its own request), so what this owns is the

package/dist/core/a2a.js

@@ -5,6 +5,7 @@ import { assertEndpointBound, redirectPolicy, resolveProtocolHttpHeaders, underD
 import { describeHttpTransportFailure } from "./mcp-failure.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName } from "./protocol-naming.js";
 import { A2A_NAMESPACE } from "./protocol-table.js";
+import { judgeEntryToolAxes, refusedDeclarer, snapshotDeclaredEntry } from "./locked-config.js";
 import { delimitUntrusted, inlineUntrusted } from "./untrusted-text.js";
 import { thrownText } from "./thrown-value.js";
 const A2A_REQUEST_TIMEOUT_MS = 30_000;
@@ -540,25 +541,39 @@ function buildSkillTool(spec, t, skill, lifecycle) {
         },
     };
 }
-async function materializePeer(declaredSpec, principal, lifecycle, signal) {
-    const spec = Object.freeze({ ...declaredSpec });
+function declaredPeerOf(declared, index) {
+    let snapshot;
+    try {
+        snapshot = snapshotDeclaredEntry(declared, "a2a");
+    }
+    catch (err) {
+        return { spec: { name: refusedDeclarer(err) ?? `(peer #${index + 1}, name unreadable)` }, refusal: err };
+    }
+    const judged = judgeEntryToolAxes(snapshot, "a2a");
+    return judged.ok ? { spec: judged.entry } : { spec: snapshot, refusal: judged.error };
+}
+async function materializePeer(peer, principal, lifecycle, signal) {
+    if ("refusal" in peer)
+        throw peer.refusal;
+    const { spec } = peer;
+    const declaredAxes = spec.toolAxes;
     const headers = resolveProtocolHttpHeaders(A2A_NAMESPACE.id, spec, principal);
     const discovery = { peer: spec.name, endpoint: spec.url, headers };
     const card = readCard(spec.name, await discoverCardBody(spec, discovery, signal), spec.url);
     assertEndpointBound(A2A_NAMESPACE.id, spec.name, card.endpoint, spec.cardUrl === undefined ? [spec.url] : [spec.url, spec.cardUrl], headers);
     const transport = { peer: spec.name, endpoint: card.endpoint, headers };
     const tools = [];
-    const axes = [];
+    const skillAxes = [];
     for (const skill of card.skills) {
         if (spec.allowSkills !== undefined && !spec.allowSkills.includes(skill.id))
             continue;
         const tool = buildSkillTool(spec, transport, skill, lifecycle);
         tools.push(tool);
-        axes.push(a2aAxisFor(tool.name, spec.toolAxes?.[skill.id]));
+        skillAxes.push(a2aAxisFor(tool.name, declaredAxes?.[skill.id]));
     }
     return {
         tools,
-        axes,
+        axes: skillAxes,
         status: {
             name: spec.name,
             status: "ready",
@@ -576,8 +591,9 @@ function asPeerWarning(spec, err) {
     return warning;
 }
 export async function materializeA2aTools(specs, principal, signal) {
-    if (specs.length > 0) {
-        const collision = findNamespacePrefixCollision(A2A_NAMESPACE, specs.map((s) => s.name));
+    const peers = specs.map((spec, index) => declaredPeerOf(spec, index));
+    if (peers.length > 0) {
+        const collision = findNamespacePrefixCollision(A2A_NAMESPACE, peers.map((p) => p.spec.name));
         if (collision) {
             const [a, b] = collision.peers;
             const e = new Error(a === b
@@ -592,9 +608,9 @@ export async function materializeA2aTools(specs, principal, signal) {
     const toolAxes = [];
     const warnings = [];
     const statuses = [];
-    const settled = await Promise.allSettled(specs.map((spec) => materializePeer(spec, principal, lifecycle, signal)));
-    for (let i = 0; i < specs.length; i++) {
-        const spec = specs[i];
+    const settled = await Promise.allSettled(peers.map((peer) => materializePeer(peer, principal, lifecycle, signal)));
+    for (let i = 0; i < peers.length; i++) {
+        const spec = peers[i].spec;
         const outcome = settled[i];
         if (outcome.status === "fulfilled") {
             tools.push(...outcome.value.tools);
@@ -613,12 +629,13 @@ export async function materializeA2aTools(specs, principal, signal) {
         statuses,
         refresh: async (peer) => {
             const prefixOf = (name) => mintNamespacePrefix(A2A_NAMESPACE, name);
-            const targets = peer !== undefined ? specs.filter((s) => s.name === peer) : specs;
+            const targets = peer !== undefined ? peers.filter((p) => p.spec.name === peer) : peers;
             if (peer !== undefined && targets.length === 0) {
                 return [{ peer, prefix: prefixOf(peer), status: "failed", toolCount: 0, added: [], removed: [], error: "no peer of that name is declared for this task" }];
             }
             const results = [];
-            for (const spec of targets) {
+            for (const target of targets) {
+                const { spec } = target;
                 const prefix = prefixOf(spec.name);
                 if (lifecycle.disposed) {
                     results.push({ peer: spec.name, prefix, status: "disposed", toolCount: 0, added: [], removed: [] });
@@ -626,7 +643,7 @@ export async function materializeA2aTools(specs, principal, signal) {
                 }
                 const previous = statuses.find((s) => s.name === spec.name)?.toolNames ?? [];
                 try {
-                    const fresh = await materializePeer(spec, principal, lifecycle, signal);
+                    const fresh = await materializePeer(target, principal, lifecycle, signal);
                     const names = fresh.tools.map((t) => t.name);
                     results.push({
                         peer: spec.name,

package/dist/core/allow-entry.d.ts

@@ -8,8 +8,9 @@ import { type EngineNotice } from "./engine-notice.js";
 /** Why an entry grants (or refuses) nothing — the closed set the start-of-run notice names, for every list. `tool_name`: the
  *  entry's tool name is one the name judgment reads as stale against the run's roster (`verdict` says which); `near_miss`: the
  *  run mounts no tool of that exact name but mounts one that differs only by case (`currentName` is its spelling);
- *  `earlier_grammar`: a session's stored rules are written in an earlier rule grammar, in which the entry named no tool (the
- *  session store's list reading, `compileSessionRuleBucket` — this reader never answers it). */
+ *  `earlier_grammar`: a session's stored rules are written in an earlier rule grammar, in which the entry named no tool, or which
+ *  read an entry this grammar reads as no rule (the session store's list reading, `compileSessionRuleBucket` — this reader never
+ *  answers it). */
 export declare const ALLOW_ENTRY_INERT_REASONS: readonly ["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"];
 export type AllowEntryInertReason = (typeof ALLOW_ENTRY_INERT_REASONS)[number];
 /** The facts beside a reason: for `tool_name` / `near_miss` the judgment's word, the judgment's own one-line sentence when it has
@@ -21,7 +22,13 @@ export interface AllowEntryInertDetail {
     readonly guidance?: string;
     readonly currentName?: string;
     readonly valueType?: string;
+    /** Where the spelling of a `near_miss` comes from, when the station that read it reads more than the run's roster
+     *  ({@link NearMissCarrier}); absent ⇒ the roster the run mounts. A sentence only — never a field of a wire detail. */
+    readonly carriedBy?: NearMissCarrier;
 }
+/** Who carries the spelling a near miss reads as another spelling of: the roster the run mounts, a delegation tool's pool, or
+ *  only the engine's tool catalog (a tool the engine may mount, which this run's roster does not carry). */
+export type NearMissCarrier = "run" | "pool" | "catalog";
 /**
  * How a list member that is not a string is named wherever a list's entries are named (the inert record's `entry`, the Skill
  * card's binding): its TYPE, in a spelling no readable entry can have — a readable entry's name holds no whitespace and a
@@ -64,6 +71,25 @@ export type CompiledAllowEntry = {
     readonly kind: "domain";
     readonly rule: PersistedRule;
 };
+/**
+ * THE near-miss reading of a tool name the judgment calls current: the spelling the run mounts when the run mounts no tool of this
+ * exact name but one that differs from it only by case (`BASH` beside `Bash`), else `undefined`. Two kinds of name are never a near
+ * miss, because the roster they would be read against is not the final one: an engine tool's (the engine mounts some of its tools
+ * after a list is read) and a protocol tool's (a refresh mounts and unmounts them while the run goes on) — in both the exact
+ * spelling can be the right one by the time it matters. Every station that asks "is this name a case twin of a mounted tool" reads
+ * this answer: an entry list ({@link readRuleEntry}), a tool policy's name lists (the prepare-time policy-name audit).
+ */
+export declare function nearMissSpellingOf(name: string, roster: ReadonlySet<string>): string | undefined;
+/**
+ * THE universe a ROOT-facing tool-name list is read against: every name the engine's catalog carries, and the names the reader knows
+ * are carried (`carried`). A list is root-facing when it bounds the tools of the run that holds it — the run's own `allowTools` /
+ * `excludeTools` (also the ceiling of its children), a tool policy's name lists, a session's stored rules — and its reader is that
+ * run (`carried`: its roster, the caller's own tools, and the exact names of the pools its reachable delegation tools declare and can
+ * list) or the store that writes the rules (`carried`: the tools its deployment declared). Another spelling of a carried name is
+ * always refused there, whatever a delegation tool injects per spawn: the run's own tools are known, and an entry that is a case
+ * twin of one of them names the other tool by mistake. A delegation tool's pool that cannot be listed carries nothing here.
+ */
+export declare function rootFacingToolNames(carried: Iterable<string>): Set<string>;
 /** What one rule entry means under one direction ({@link readRuleEntry}): the row the grammar compiles it to, or the reason it
  *  reads as nothing with the facts a sentence about it names. */
 export type RuleEntryReading = {
@@ -87,9 +113,10 @@ export declare function compiledEntryName(compiled: CompiledAllowEntry): string;
 /**
  * Compile one list WHOLE through {@link readRuleEntry}: the entries it reads and the ones it reads as nothing (each with its
  * reason and, for a name the roster refuses, the judgment's word and the spelling to write). An allow list holding `*` voids
- * the list (every other entry on it reads as nothing too: the list grants nothing — the safe direction). A `*` on a deny list
- * reads as nothing by itself and the rest of that list still refuses: a deny list never loses an entry to a wildcard beside
- * it. `roster` as in {@link readRuleEntry}.
+ * the list (every other entry on it reads as nothing too: the list grants nothing — the safe direction) — `*` as the lenient
+ * rule parser names it ({@link namesWholeRoster}), so an entry the stricter entry grammar refuses (`* (*)`) still voids. A
+ * `*` on a deny list reads as nothing by itself and the rest of that list still refuses: a deny list never loses an entry to
+ * a wildcard beside it. `roster` as in {@link readRuleEntry}.
  */
 export declare function compileAllowList(entries: readonly string[], behavior: "allow" | "deny", roster?: ReadonlySet<string>): {
     rows: Array<{
@@ -136,7 +163,8 @@ export declare function uncoveredCommandSegment(rows: readonly AllowEntryRow[],
  * segment covered by a row — or, for a `grant` list, read-only by itself); deny: a row whose program run the call performs (the
  * wide tightening reading; a call that cannot be read against the row is refused too). PATH — the persisted path adjudication
  * (allow: the narrow reading, every view of the target inside what the row names; deny: any view reaching it). NAME / DOMAIN —
- * the one predicate of each (the name the call names, the host it fetches).
+ * the one predicate of each (the name the call names, the host it fetches); a keyed tool's call naming no value for its key is
+ * refused by a deny list's row of the key and granted by no allow row (the persisted walk's reading, `keyedValueAbsentReason`).
  */
 export declare function judgeAllowEntries<R extends AllowEntryRow>(rows: readonly R[], req: ToolCallRequest, behavior: "allow" | "deny", ctx: AllowEntryJudgeContext, posture?: AdmissionPosture): readonly R[] | undefined;
 /** The allow rows of a list, as the allow layer reads them in `mode`: the strip applied BEFORE the match (in `auto`). */
@@ -294,11 +322,16 @@ export type AllowEntryInertNote = ({
 } & AllowEntryInert) | ({
     readonly source: AllowEntrySource;
 } & AllowEntryInert);
+/**
+ * A list entry spelled so a person reads what the engine read: the entry as a JSON string — quotes, backslashes and the usual
+ * escapes — with every character that prints as nothing, or as a space, written as `\uXXXX` (`\u{…}` beyond the BMP) and a
+ * run of spaces kept space by space. Uncapped and one-to-one (two entries never share a spelling), so a value that BINDS an
+ * entry may hold it ({@link renderListEntry} is this, capped for a sentence).
+ */
+export declare function spelledListEntry(entry: string): string;
 /**
  * THE ONE WRITER of a list entry into a sentence (the start-of-run notice, a skill's refusal and its decisions, a sub-agent
- * list's refusals and advisories): the entry as a JSON string — quotes, backslashes and the usual escapes — with every
- * character that prints as nothing, or as a space, written as `\uXXXX` (`\u{…}` beyond the BMP) and a run of spaces kept
- * space by space, so what a person reads is what the engine read. Capped on what is printed.
+ * list's refusals and advisories): {@link spelledListEntry}, capped on what is printed.
  */
 export declare function renderListEntry(entry: string): string;
 /**

package/dist/core/allow-entry.js

@@ -1,9 +1,10 @@
 import { heldBy } from "./tool-name-readings.js";
-import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
+import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "./permission-rules.js";
+import { parsePermissionRule, ruleSpellingOf } from "./permission-rule-syntax.js";
 import { judgeRuleToolName, splitNamespacedName } from "./tool-name-aliases.js";
 import { catalogToolNames, isShellFaceToolName } from "./tool-registry.js";
 import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
-import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, domainRuleSubjectOf, laneToolNamesOf, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { COMMAND_RULE_TOOL, adjudicatePersistedDomainRules, adjudicatePersistedNameRules, commandCoverageOf, domainRuleSubjectOf, laneToolNamesOf, nameRuleSubjectOf, noticeRuleText, parseRuleText, programRunReachOf, ruleToolGrammarOf } from "./permission-rule-model.js";
 import { pathRuleLaneAnswer } from "./runner/permission-rule-lanes.js";
 import { callTargetReadingOf } from "./effective-path-target.js";
 import { splitShellCompoundSegments } from "../tools/fs/bash-readonly-classifier.js";
@@ -12,6 +13,7 @@ import { inlineUntrusted } from "./untrusted-text.js";
 import { valueTypeLabel } from "./tool-name-list.js";
 import { deliverEngineNotice } from "./engine-notice.js";
 export const ALLOW_ENTRY_INERT_REASONS = Object.freeze(["wildcard_all", "namespace_wildcard", "content_unsupported", "grammar", "tool_name", "near_miss", "earlier_grammar"]);
+const NEAR_MISS_CARRIER = { run: "the mounted spelling is", pool: "a delegation pool carries", catalog: "the engine's tool catalog names" };
 export function nonStringMemberLabel(value) {
     return `<not a string: ${valueTypeLabel(value)}>`;
 }
@@ -21,7 +23,6 @@ export function nonListValueLabel(read) {
 function ruleRowOf(parsed) {
     return { ...parsed, scope: { kind: "global" }, adds: [{ dot: { actor: "list", counter: 1 }, origin: "user", createdAt: "" }] };
 }
-const TOOL_NAME_SPELLING = /^[^\s()\p{Cc}\p{Cf}]+$/u;
 function mountedSpellingOf(name, roster) {
     const folded = name.toLowerCase();
     for (const mounted of roster)
@@ -29,6 +30,14 @@ function mountedSpellingOf(name, roster) {
             return mounted;
     return undefined;
 }
+export function nearMissSpellingOf(name, roster) {
+    if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
+        return undefined;
+    return mountedSpellingOf(name, roster);
+}
+export function rootFacingToolNames(carried) {
+    return new Set([...catalogToolNames(), ...carried]);
+}
 function toolNameReading(name, roster) {
     const verdict = judgeRuleToolName(name, roster);
     if (verdict.kind === "unprefixed_namespace")
@@ -36,9 +45,7 @@ function toolNameReading(name, roster) {
     if (verdict.kind !== "current") {
         return { kind: "inert", reason: "tool_name", verdict: verdict.kind, guidance: verdict.guidance, ...(verdict.currentName !== undefined ? { currentName: verdict.currentName } : {}) };
     }
-    if (roster.has(name) || catalogToolNames().has(name) || splitNamespacedName(name) !== undefined)
-        return undefined;
-    const mounted = mountedSpellingOf(name, roster);
+    const mounted = nearMissSpellingOf(name, roster);
     return mounted === undefined ? undefined : { kind: "inert", reason: "near_miss", currentName: mounted };
 }
 export function readRuleEntry(raw, behavior, roster) {
@@ -46,12 +53,10 @@ export function readRuleEntry(raw, behavior, roster) {
     const row = (compiled) => ({ kind: "row", compiled });
     if (typeof raw !== "string")
         return { kind: "inert", reason: "grammar", valueType: valueTypeLabel(raw) };
-    if (raw !== raw.trim())
+    const parsed = ruleSpellingOf(raw);
+    if (parsed === undefined)
         return inert("grammar");
-    const parsed = parsePermissionRule(raw);
     const name = parsed.toolName;
-    if (!TOOL_NAME_SPELLING.test(name))
-        return inert("grammar");
     if (name === "*")
         return inert("wildcard_all");
     if (roster !== undefined) {
@@ -98,7 +103,7 @@ function inertReasonOf(code) {
     return code === "unsupported.tool" ? "content_unsupported" : "grammar";
 }
 export function compileAllowList(entries, behavior, roster) {
-    const voided = behavior === "allow" && entries.some((e) => isWildcardAll(readRuleEntry(e, behavior)));
+    const voided = behavior === "allow" && entries.some(namesWholeRoster);
     const rows = [];
     const inert = [];
     for (const entry of entries) {
@@ -113,8 +118,8 @@ export function compileAllowList(entries, behavior, roster) {
     }
     return { rows, inert };
 }
-function isWildcardAll(read) {
-    return read.kind === "inert" && read.reason === "wildcard_all";
+function namesWholeRoster(entry) {
+    return typeof entry === "string" && entry === entry.trim() && parsePermissionRule(entry).toolName === "*";
 }
 function answersTo(req, has) {
     return heldBy("allowEntry.names", { has }, req);
@@ -415,11 +420,13 @@ function escapedCodePoint(ch) {
     const hex = cp.toString(16).padStart(4, "0");
     return cp > 0xffff ? `\\u{${hex}}` : `\\u${hex}`;
 }
-export function renderListEntry(entry) {
-    const quoted = JSON.stringify(entry)
+export function spelledListEntry(entry) {
+    return JSON.stringify(entry)
         .replace(/ {2,}/g, (run) => "\\u0020".repeat(run.length))
         .replace(UNSEEN_IN_ENTRY, (ch) => (ch === " " ? ch : escapedCodePoint(ch)));
-    return inlineUntrusted(quoted, ENTRY_RENDER_MAX);
+}
+export function renderListEntry(entry) {
+    return inlineUntrusted(spelledListEntry(entry), ENTRY_RENDER_MAX);
 }
 export function inertEntryPhrase(e) {
     if (e.valueType !== undefined)
@@ -427,7 +434,7 @@ export function inertEntryPhrase(e) {
     const spelling = e.currentName !== undefined ? inlineUntrusted(e.currentName, 120) : undefined;
     const why = (() => {
         if (e.reason === "near_miss")
-            return `near_miss: the mounted spelling is "${spelling}"`;
+            return `near_miss: ${NEAR_MISS_CARRIER[e.carriedBy ?? "run"]} "${spelling}"`;
         if (e.reason !== "tool_name" || e.verdict === undefined)
             return e.reason;
         switch (e.verdict) {
@@ -455,6 +462,6 @@ export function allowedToolsNotGrantedNotice(inert, sessionId) {
         message: `${inert.length} allowed-tools entr${inert.length === 1 ? "y grants" : "ies grant"} or refuse${inert.length === 1 ? "s" : ""} nothing — ${shown.join("; ")}${rest > 0 ? `; and ${rest} more` : ""}. ` +
             "A list holding `*` voids the list, `mcp__*` names no server, a rule the grammar refuses (`grammar`) or one on a tool with no such rule form (`content_unsupported`: an allow by path is an `Edit(…)` or `Read(…)` rule) grants nothing, and a tool name must be spelled as the tool is mounted; name the tools (or `mcp__<server>`) instead." +
             (refusing ? " Such an entry in a disallowed-tools list keeps its Skill from activating: a refusal that reads as nothing is not dropped." : ""),
-        detail: { ...(sessionId !== undefined ? { sessionId } : {}), entries: inert.map((e) => ({ ...e })) },
+        detail: { ...(sessionId !== undefined ? { sessionId } : {}), entries: inert.map((e) => ({ ...e, entry: noticeRuleText(e.entry) })) },
     };
 }