@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/runner/sub-agent-deny-lists.d.ts

@@ -1,29 +1,84 @@
 /**
  * THE judgment of every tool-name list one prepared task receives — the run's own selector lists (`TaskSpec.allowTools` /
- * `TaskSpec.excludeTools`, unless the delegation lane spawned it — its spawning run judged them where they were mounted), the definitions it
- * carries (`TaskSpec.agents`), and the definitions and tool-level lists a mounted delegation tool carries (the `authored` faces
- * — the engine's built-ins are not judged; only a tool a deployment mounted (depth 0) publishes them). One rule for both sides:
- * a value that is not a list, an entry that is not a string and a spelling that can name no tool are REFUSED; an entry whose
- * name no tool of the universe answers to (a server this deployment does not declare, a stale or misspelt name) is KEPT as
- * written — the selector reads every entry by name, so a denied one hides a tool of that name whenever one is mounted and an
- * allowed one admits it — and told to the host, one account per entry. And one contradiction, judged on every leg: a
- * denylist (the run's own or one of its ceiling) that reaches a tool the leg's kind relies on (the catalog's protocol column)
- * is refused — neither a silently ignored deny nor a silently crippled leg.
+ * `TaskSpec.excludeTools`; when the delegation lane spawned it, its spawning run judged them where they were mounted, and the evidence
+ * it handed down spares them here), the definitions it carries (`TaskSpec.agents`), and the definitions and tool-level lists a mounted
+ * delegation tool carries (the `authored` faces — the engine's built-ins are not judged; only a tool a deployment mounted (depth 0)
+ * publishes them). One rule for both sides: a value that is not a list, an entry that is not a string, a spelling that can name no tool
+ * and a spelling that is another spelling of a tool the list's universe carries (`BASH` beside `Bash`) are REFUSED; an entry whose
+ * name no tool of the universe answers to (a server this deployment does not declare, a misspelt name) is KEPT as written — the
+ * selector reads every entry by name, so a denied one hides a tool of that name whenever one is mounted and an allowed one admits
+ * it — and told to the host, one account per entry. And one contradiction, judged on every leg: a denylist (the run's own or one
+ * of its ceiling) that reaches a tool the leg's kind relies on (the catalog's protocol column) is refused — neither a silently
+ * ignored deny nor a silently crippled leg.
  *
- * Universe = the task's assembled roster before the valve, every tool the catalog describes, every mounted delegation tool's
- * pool and the caller's own tools (names and aliases), and the protocol peers the task declares (a namespaced spelling under a
- * declared peer names a tool of it — the peer's tool list is runtime data, so the peer is what is checked). A delegation tool
- * whose factory injects tools per spawn with no declared roster (`extraTools`) lists none of them here; a kept entry reaches
- * its products by name like any other later-mounted tool.
+ * Two kinds of list, two universes. A ROOT-facing list bounds the tools of the run that holds it: the run's own lists (also the
+ * ceiling of every child), the policy name audit and the session-rules write gate ask the same question of it. Its universe is the
+ * run's roster before the valve, the caller's own tools, every tool the catalog describes (`rootFacingToolNames`) and the exact
+ * names of the pools its reachable delegation tools declare and can list — and another spelling of a carried name is always refused,
+ * whatever a delegation tool injects per spawn. A CHILD-facing list bounds a child that does not exist yet: a definition's two
+ * lists and a delegation tool's two lists. Its universe is the pool the delegation tool that hands the child declares (names, aliases, the
+ * declared `extraToolNames`, and the tool's own name: the child is handed the tool again, rebuilt, while its depth allows) and the catalog — not the
+ * spawning run's roster, which the child is not handed; every definition is judged against each reachable delegation tool's own pool; a delegation tool whose factory
+ * injects tools per spawn with no declared roster lists none of its pool, so there another spelling is kept and told (it may be one
+ * of that pool's own). Only the delegation tools the run's own selector leaves are read, in both: a tool it takes out hands nobody
+ * anything. A layer a run inherits (its ceiling) is not asked again: the run that wrote it asked its own universe, and a layer a
+ * checkpoint row restored is read for its spelling before the claim. The same goes for the lists a delegation tool hands its child
+ * (the child's own): when the spawning run read them against a pool it could list, its evidence spares them in the child. When it
+ * could not (the keep above), the child is the run whose roster can answer — it refuses another spelling of a tool of its own
+ * universe (its roster, the catalog, the pools it can list, and the delegation tool that spawned it, under its exact mounted name: a name
+ * of the child's lineage, mounted at its depth or not — an exact hit of that name is the tool's own, whatever else reads as a twin of it),
+ * and the spawning run already told what it kept, so nothing is told a second time.
  *
  * Throws `config.tool_face_control` for the run's own lists and the protocol contradiction, `config.agent.unknown_tool` for a
- * definition's or a delegation tool's lists — synchronous, like the phase that calls it.
+ * definition's or a delegation tool's lists (`detail.reason`: `unknown_name` for a spelling no tool name can have, `near_miss` for
+ * another spelling of a tool of the universe) — synchronous, like the phase that calls it.
  */
 import type { AgentTool } from "../../internal/harness.js";
+import { valveLeaves } from "../../agents/tool-filter.js";
 import { type ProtocolId } from "../protocol-table.js";
 import type { ToolLegKind, ToolSelectorLayer } from "../tool-face.js";
+import { type ConstraintChainEntry } from "../tool-policy.js";
 import type { TaskSpec } from "../types.js";
-import type { AnnounceOnceSink } from "./contracts.js";
+import type { CheckpointErrorReason } from "../checkpoint-store.js";
+import type { AnnounceOnceSink, RunInternals } from "./contracts.js";
+/** What the delegation tools a run mounts hand their children (the pools of {@link delegationPoolReading}). */
+interface DelegationPoolReading {
+    readonly tools: NonNullable<TaskSpec["tools"]>;
+    readonly names: Set<string>;
+    readonly complete: boolean;
+}
+/**
+ * THE judgment of the name a delegation tool is mounted under: the name it declares for itself (`createSubagentTool({ name })`, the default
+ * name when none is given), which the factory binds to the `execute` that carries the delegation out ({@link declaredDelegationNameOf}) —
+ * so a copy of the tool, a product of it, a stripped or shell copy all still say it. A delegation tool is ONE tool with ONE name: the lists
+ * of its agent definitions, the copy of it a child is handed, the rebuilt copy a run's own definitions produce and the prompt text it speaks
+ * all say the declared name, while the roster, the pool reading and the model's call say the mounted one. A mount whose `name` differs from
+ * the declared one makes the tool answer to two names — a denied list that names one of them is read against the other — so it is REFUSED,
+ * naming both names and the two ways to one name. This is the sentence of that refusal for the first such entry of the rosters given — or
+ * `undefined`; it never throws (an entry whose members cannot be read is not judged here: the roster snapshot refuses it). A tool the
+ * factory did not make, and a roster that is no list (the doors' to judge), are not read.
+ */
+export declare function renamedDelegationMountSentence(...rosters: unknown[]): string | undefined;
+/**
+ * The refusal of a renamed delegation mount at prepare (`config.tool_face_control`, `detail.reason: "renamed_mount"`), asked of every roster
+ * the run holds: the one the caller mounted and the one the per-task rebuild (a function the caller's tool supplies) handed back. A resume
+ * asks the roster it is handed once more before the claim (this same function, through the resume screen's config-refusal channel), so the row stays pending.
+ */
+export declare function refuseRenamedDelegationMounts(...rosters: unknown[]): void;
+/**
+ * THE reading of what the delegation tools a run mounts hand their children, read after the run's own tool valve: only a delegation
+ * tool the valve leaves (`leaves`, the valve's one reading — `valveLeaves`) counts — one it takes out hands nobody anything, and neither
+ * its pool names nor an unlistable pool of it belong to any universe. The tools themselves, every pool tool's name and alias (a declared
+ * `extraToolNames` roster included), and whether every one of those pools can be listed: a delegation tool whose factory injects tools
+ * per spawn with no declared roster has no listable pool (the static `tools` it was given included), so a name outside the listed ones
+ * may be one of its own. This is the one place the pool side of both universes is defined; the list judgment below and the policy name
+ * audit ask it.
+ */
+export declare function delegationPoolReading(callerTools: NonNullable<TaskSpec["tools"]>, leaves: ReturnType<typeof valveLeaves>): DelegationPoolReading;
+/** The arms of this module's `config.tool_face_control` refusal that a resume carries before the claim as `detail.reason` of a `checkpoint.config_refused` — the same words
+ *  ({@link CheckpointErrorReason}): a list the row recorded that is not a list / has a member that is not a string / has a spelling no tool name can have / is not in the
+ *  spelling a row records, a record that is not one, a renamed delegation mount, an occupied table of declared names. */
+export type PersistedToolFaceReason = Extract<CheckpointErrorReason, "not_a_list" | "not_a_string" | "unknown_name" | "unsupported_pattern" | "invalid_record" | "renamed_mount" | "registry_occupied">;
 /**
  * The names a definition's denied-tools entries stand for, for a lane that has neither a roster nor a notice sink at the point
  * it builds its own policy (a workflow leg's agentType): each entry is read by the one reading, so `Tool(content)` denies the
@@ -32,6 +87,22 @@ import type { AnnounceOnceSink } from "./contracts.js";
  * leg's roster and a sink; the leg's own policy-name audit is what reads them.
  */
 export declare function deniedToolNamesOf(where: string, value: unknown): string[];
+/**
+ * THE read-back of the tool names a checkpoint row carries, before the claim: the ceiling the resumed leg will run under when it is
+ * the row's (`ceiling`: absent when a live seat hands one) — each layer read by {@link readSelectorLayer} as a recorded layer — and
+ * the frozen policy chain (`inheritedGate.constraintChain`; each component's members {@link projectionToolNames} names), whose
+ * replay matches a name as recorded, which is the rule syntax's reading only for a name in its canonical spelling. The refusal
+ * sentence of the first entry neither reading may be applied to, naming it and where it sits, or `undefined`; a member that is not
+ * a list, or an entry that is not a string, is named by its type only. And the delegation tool the row records as having written the
+ * leg's own lists (`ownLists`, absent when a live seat hands one): it joins the universe those lists are asked of, so it must be a name.
+ * The refusal is its sentence and the arm it is ({@link CheckpointErrorReason}); {@link refusePersistedToolNames} throws it as prepare's own refusal.
+ */
+export declare function persistedToolNamesRefusal(ceiling: unknown, chain: readonly ConstraintChainEntry[] | undefined, ownLists?: unknown): {
+    readonly message: string;
+    readonly reason: PersistedToolFaceReason;
+} | undefined;
+/** {@link persistedToolNamesRefusal} as prepare's own refusal (`config.tool_face_control`, the arm as `detail.reason`): what a resume's pre-claim screen throws through the resume's one refusal channel. */
+export declare function refusePersistedToolNames(ceiling: unknown, chain: readonly ConstraintChainEntry[] | undefined, ownLists?: unknown): void;
 /**
  * The upstream judgment of a run's own lists, when it holds: the evidence digest the spawning run handed down (live) or the resumed row
  * recorded, returned only when it equals the digest of the lists this prepare read — the evidence is bound to the lists it was minted
@@ -41,9 +112,21 @@ export declare function boundToolListsJudgment(evidence: string | undefined, own
     readonly allow: readonly string[] | undefined;
     readonly exclude: readonly string[] | undefined;
 }): string | undefined;
+/**
+ * The record of the delegation tool that wrote a leg's own lists, held only for the lists it wrote: the live seat's (the delegation lane
+ * mints it with the digest of exactly the lists it handed the child) or, with none, the resumed row's. A prepare whose own lists digest to
+ * the record's `lists` keeps it — they are the lists that tool wrote, so their refusals name it and its name is a name of the leg's
+ * lineage; any other lists (a resume whose host handed another table) are the host's own `TaskSpec` seats, and the leg asks them as such
+ * with no lineage name cleared. A record that is not one (a host that set the live seat itself) refuses the leg, as a row's does before the
+ * claim: `config.tool_face_control`, `detail.reason: "invalid_record"`.
+ */
+export declare function boundOwnToolLists(record: unknown, own: {
+    readonly allow: readonly string[] | undefined;
+    readonly exclude: readonly string[] | undefined;
+}): RunInternals["ownToolLists"];
 export interface RunToolListsInput {
-    /** borrowed-readonly — the REBOUND spec: `agents` (the task's definitions) and `tools` (the caller's tools and the mounted delegation tools). */
-    spec: Pick<TaskSpec, "agents" | "tools">;
+    /** borrowed-readonly — the REBOUND spec: `agents` (the task's definitions), `tools` (the caller's tools and the mounted delegation tools) and `excludeAllTools` (the valve's whole-face switch, which takes the delegation tools out too). */
+    spec: Pick<TaskSpec, "agents" | "tools" | "excludeAllTools">;
     /** borrowed-readonly — the assembled mount array BEFORE the selector's valve (names + aliases = the roster half of the universe). */
     tools: ReadonlyArray<AgentTool>;
     /** borrowed-readonly — the peers the task declares, per protocol of the protocol table (its MCP servers, its A2A peers): a namespaced
@@ -61,15 +144,33 @@ export interface RunToolListsInput {
     /** borrowed-readonly — every layer of the run's selector (the ceiling, then its own) and the kinds of leg it is. */
     layers: readonly ToolSelectorLayer[];
     legs: readonly ToolLegKind[];
-    /** True ⇔ the spawning run's prepare judged exactly these own lists where they were mounted — the evidence digest it handed down
-     *  (live, or recorded on the resumed row) equals the digest of the lists this prepare read ({@link boundToolListsJudgment}). */
+    /** True ⇔ the spawning run's prepare judged exactly these own lists where they were mounted, against a pool it could list (as the
+     *  child-facing lists of the delegation tool or definition that wrote them) — the evidence digest it handed down (live, or recorded
+     *  on the resumed row) equals the digest of the lists this prepare read ({@link boundToolListsJudgment}). They are then not judged
+     *  again: neither told nor refused. */
     judgedUpstream: boolean;
-    /** Whose lists the run's own are, when the run that spawned it wrote them ({@link delegationListWhere}); absent ⇒ the run's own
-     *  `TaskSpec` seats. */
-    ownWhere: string | undefined;
+    /** True ⇔ a delegation lane spawned this leg inside a prepared run, which read these own lists against a pool it could not list: it
+     *  kept what it could not judge and told it (no evidence digest was handed down). They are judged here, against this leg's roster,
+     *  and refused as any own list is — but nothing is told a second time. Absent ⇒ nobody told. */
+    toldUpstream?: boolean;
+    /** The delegation tool (and the agent definition) whose lists the run's own are, when the run that spawned it wrote them
+     *  (`RunInternals.ownToolLists`); absent ⇒ the run's own `TaskSpec` seats. Its sentence is {@link delegationListWhere}; its tool name is
+     *  a name of the leg's lineage, so the run's own lists are asked of a universe that carries it. */
+    ownBy: RunInternals["ownToolLists"];
     /** borrowed-readonly — the once-per-session ledger whose operator sink carries the notices. */
     onceLedger: Pick<AnnounceOnceSink, "onError">;
     /** borrowed-readonly — the acquired session's id (operator-line context). */
     sessionId: string;
 }
 export declare function judgeRunToolLists(input: RunToolListsInput): void;
+/**
+ * THE judgment of a tool ceiling a HOST wrote (`RunWorkflowOptions.toolCeiling`), asked of one workflow agent's spec before it launches.
+ * A ceiling a prepared run hands down was judged where it was written and is not asked again; one a host wrote was judged nowhere, and
+ * it bounds the tools of every agent that holds it — a root-facing list: it is read against the catalog, the agent's caller tools and the
+ * listable pools of the delegation tools the agent's own selector leaves (the layers above the host's — a launching run's —, the host's
+ * and the agent's own lists together: a tool they take out hands nobody anything), and another spelling of one of those is refused (`config.tool_face_control`,
+ * `detail.reason: "near_miss"`) rather than kept as a deny that hides nothing. A name no tool answers to stays kept (a tool of that
+ * name may be mounted later), unannounced: the host wrote no spec this leg could name the list of.
+ */
+export declare function judgeHostToolCeiling(layers: readonly ToolSelectorLayer[], agent: Pick<TaskSpec, "tools" | "allowTools" | "excludeTools" | "excludeAllTools">, above?: readonly ToolSelectorLayer[]): void;
+export {};

package/dist/core/runner/sub-agent-deny-lists.js

@@ -1,11 +1,63 @@
-import { deniedProtocolTools, delegationListWhere, listReaches, notAListSentence, toolListsDigest, notAStringSentence, readAllowedToolList, readDeniedEntry, readDeniedToolList } from "../../agents/tool-filter.js";
+import { compileToolSelector, valveLeaves, deniedProtocolTools, delegationListWhere, isCanonicalToolName, isToolSelectorLayer, listReaches, notAListSentence, toolListsDigest, notAStringSentence, readAllowedToolList, readDeniedEntry, readDeniedToolList } from "../../agents/tool-filter.js";
 import { readToolNameList, valueTypeLabel } from "../tool-name-list.js";
-import { compileAllowList, inertEntryPhrase, renderListEntry } from "../allow-entry.js";
+import { compileAllowList, inertEntryPhrase, renderListEntry, rootFacingToolNames } from "../allow-entry.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { ENGINE_TOOLS } from "../tool-catalog-entries.js";
+import { callerToolNameProblem } from "../caller-tool-name.js";
 import { mintNamespacePrefix } from "../protocol-naming.js";
 import { PROTOCOL_TABLE, protocolOf } from "../protocol-table.js";
-import { splitNamespacedName } from "../tool-name-aliases.js";
+import { mountedToolNames, splitNamespacedName } from "../tool-name-aliases.js";
+import { projectionToolNames } from "../tool-policy.js";
+import { declaredDelegationNameOf } from "../delegation-name.js";
+export function renamedDelegationMountSentence(...rosters) {
+    for (const tools of rosters) {
+        if (!Array.isArray(tools))
+            continue;
+        for (const t of tools) {
+            const declared = declaredDelegationNameOf(t);
+            if (declared === undefined)
+                continue;
+            try {
+                const mounted = t.name;
+                if (declared === mounted)
+                    continue;
+                return `The delegation tool declared as "${inlineUntrusted(declared, 80)}" is mounted under the name "${inlineUntrusted(String(mounted), 80)}": one tool would answer to two names (the agent definitions' tool lists, the copy a child is handed and the tool's prompt text speak the declared one; the roster and the model's call speak the mounted one). Mount it under its declared name, or declare the name you mount it under (\`createSubagentTool({ name })\`).`;
+            }
+            catch {
+            }
+        }
+    }
+    return undefined;
+}
+export function refuseRenamedDelegationMounts(...rosters) {
+    const sentence = renamedDelegationMountSentence(...rosters);
+    if (sentence !== undefined)
+        throw refused(sentence, "config.tool_face_control", "renamed_mount");
+}
+function poolOf(tools) {
+    return { tools, names: mountedToolNames([...tools.map((t) => ({ name: t.name })), ...tools.flatMap((t) => t.agentToolPool ?? [])]), complete: tools.every((t) => t.agentToolPool !== undefined) };
+}
+export function delegationPoolReading(callerTools, leaves) {
+    return poolOf(callerTools.filter((t) => t.agentToolFaces !== undefined && leaves(t)));
+}
+function peersOf(known, declaredPeers) {
+    const peers = new Set(PROTOCOL_TABLE.flatMap((ns) => (declaredPeers[ns.id] ?? []).map((p) => mintNamespacePrefix(ns, p.name))));
+    for (const name of known) {
+        const ns = protocolOf(name);
+        const split = ns !== undefined ? splitNamespacedName(name) : undefined;
+        if (split !== undefined && split.peer !== "")
+            peers.add(mintNamespacePrefix(split.ns, split.peer));
+    }
+    return peers;
+}
+function rootFacingUniverse(mounted, pool, declaredPeers) {
+    const known = rootFacingToolNames([...mounted, ...pool.names]);
+    return { known, peers: peersOf(known, declaredPeers), complete: true, carrierOf: (name) => (mounted.has(name) ? "run" : pool.names.has(name) ? "pool" : "catalog") };
+}
+function childFacingUniverse(pool, declaredPeers) {
+    const known = new Set([...mountedToolNames(ENGINE_TOOLS), ...pool.names]);
+    return { known, peers: peersOf(known, declaredPeers), complete: pool.complete, carrierOf: (name) => (pool.names.has(name) ? "pool" : "catalog") };
+}
 const DENY_LIST_NAMES_ONLY = "To block by path or command, write a deny rule in the caller's permission policy: a tool-name list only takes tool names (it narrows which tools are mounted).";
 function universeCarries(reach, entry, universe) {
     for (const name of universe.known)
@@ -23,34 +75,46 @@ function refused(message, code, reason) {
     return e;
 }
 const LIST_WORD = { allowed: "allowed tools", denied: "denied tools" };
+const NEAR_MISS_EFFECT = {
+    allowed: "it admits nothing, so the tool it was written for is not granted",
+    denied: "it hides nothing, so the tool it was written for stays available to the agent",
+};
+function nearMissRefusal(where, side, flaw, code) {
+    return refused(`${where} declares tool ${inertEntryPhrase(flaw)} in its ${LIST_WORD[side]}, a spelling that reaches no tool a run mounts — ${NEAR_MISS_EFFECT[side]}. Write the name as the tool is mounted.`, code, "near_miss");
+}
 function grammarRefusal(where, side, flaw, code) {
     return refused(`${where} declares tool ${inertEntryPhrase(flaw)} in its ${LIST_WORD[side]}, a spelling no tool name can have — fix the entry. ${DENY_LIST_NAMES_ONLY}`, code, "unknown_name");
 }
+function readableToolNameList(where, side, value, code) {
+    if (value === undefined || value === null)
+        return [];
+    const list = readToolNameList(value);
+    if (list.kind !== "entries")
+        throw refused(notAListSentence(where, side, list), code, "not_a_list");
+    return list.entries.map((entry, index) => {
+        const read = readDeniedEntry(entry);
+        if (read.kind === "not_a_string")
+            throw refused(notAStringSentence(where, side, index, read.type), code, "not_a_string");
+        if (read.kind === "unreadable")
+            throw grammarRefusal(where, side, { entry: read.entry, reason: "grammar" }, code);
+        if (side === "denied" && read.name === "*") {
+            throw refused(`${where} declares ${renderListEntry(entry)} in its ${LIST_WORD[side]}: a denied list has no wildcard — the entry would hide nothing. To give the agent no tools, write an empty allowed list.`, code, "unsupported_pattern");
+        }
+        return { entry: entry, name: read.name, content: read.content };
+    });
+}
 const KEPT_ENTRY = {
     allowed: "it grants nothing today and stays in force for a tool of that name mounted later",
     denied: "it denies nothing today and stays in force for a tool of that name mounted later",
 };
+const KEPT_ENTRY_UNLISTED_POOL = "so it is kept here: the pool this delegation tool hands its child cannot be listed, and the spawned child judges the entry against its own roster (another spelling of a tool it carries refuses the child before it starts; an exact name takes effect; a name nothing answers to there stays in force for a tool of that name mounted later)";
 const PEER_WORD = { mcp: "MCP server", a2a: "A2A peer" };
 function judgeToolNameList(where, side, value, universe, advise, code) {
-    if (value === undefined || value === null)
-        return;
-    const list = readToolNameList(value);
-    if (list.kind !== "entries")
-        throw refused(notAListSentence(where, side, list), code, "not_a_list");
-    let index = -1;
-    for (const entry of list.entries) {
-        index += 1;
-        if (typeof entry !== "string")
-            throw refused(notAStringSentence(where, side, index, valueTypeLabel(entry)), code, "not_a_string");
-        if (entry === "*") {
-            if (side === "allowed")
-                continue;
-            throw refused(`${where} declares "*" in its ${LIST_WORD[side]}: a denied list has no wildcard — the entry would hide nothing. To give the agent no tools, write an empty allowed list.`, code, "unsupported_pattern");
-        }
-        const read = readDeniedEntry(entry);
-        const toolName = read.kind === "name" ? read.name : entry;
-        const name = side === "denied" ? toolName : entry;
-        const content = side === "denied" && read.kind === "name" && read.content;
+    for (const { entry, name: toolName, content: written } of readableToolNameList(where, side, value, code)) {
+        if (toolName === "*" && !written)
+            continue;
+        const name = side === "denied" || !written ? toolName : entry;
+        const content = side === "denied" && written;
         const reach = side === "denied" ? readDeniedToolList([entry]) : (readAllowedToolList([entry]) ?? readDeniedToolList([]));
         const split = splitNamespacedName(name);
         if (split !== undefined && split.peer === "*" && split.tool === undefined) {
@@ -59,9 +123,9 @@ function judgeToolNameList(where, side, value, universe, advise, code) {
             throw refused(`${where} declares ${renderListEntry(entry)} in its ${LIST_WORD[side]}: an allowed list has no protocol-wide form — name a peer (\`${split.ns.prefix}<peer>\`) or its tools.`, code, "unsupported_pattern");
         }
         const { inert } = compileAllowList([toolName], "deny", universe.known);
-        const flaw = inert[0] === undefined ? undefined : { ...inert[0], entry };
-        if (flaw !== undefined && flaw.reason === "grammar")
-            throw grammarRefusal(where, side, flaw, code);
+        const flaw = inert[0] === undefined ? undefined : { ...inert[0], entry, ...(inert[0].reason === "near_miss" && inert[0].currentName !== undefined ? { carriedBy: universe.carrierOf(inert[0].currentName) } : {}) };
+        if (universe.complete && flaw?.currentName !== undefined)
+            throw nearMissRefusal(where, side, flaw, code);
         if (toolName !== name) {
             advise(new Error(`${where} declares ${renderListEntry(entry)} in its allowed tools: an allowed list names tools, not content, so this entry grants nothing — name the tool "${inlineUntrusted(toolName, 80)}" to grant it, or move the content rule to a denied list or a permission rule.`));
             continue;
@@ -73,29 +137,117 @@ function judgeToolNameList(where, side, value, universe, advise, code) {
         }
         const phrase = flaw !== undefined ? inertEntryPhrase(flaw) : renderListEntry(entry);
         const undeclared = split !== undefined && split.peer !== "" && !split.peer.includes("*") && !universe.peers.has(mintNamespacePrefix(split.ns, split.peer));
-        const why = undeclared ? `no ${PEER_WORD[split.ns.id]} named "${inlineUntrusted(split.peer, 80)}" is declared for this task` : "no tool of this task answers to that name";
-        advise(new Error(`${where} declares tool ${phrase} in its ${LIST_WORD[side]}: ${why}, so ${KEPT_ENTRY[side]}. If the name is misspelt, fix the entry.`));
+        const why = undeclared ? `no ${PEER_WORD[split.ns.id]} named "${inlineUntrusted(split.peer, 80)}" is declared for this task` : universe.complete ? "no tool of this task answers to that name" : "no tool this run can list answers to that name";
+        advise(new Error(`${where} declares tool ${phrase} in its ${LIST_WORD[side]}: ${why}, ${universe.complete ? `so ${KEPT_ENTRY[side]}` : KEPT_ENTRY_UNLISTED_POOL}. If the name is misspelt, fix the entry.`));
     }
 }
 export function deniedToolNamesOf(where, value) {
-    const list = readToolNameList(value);
-    if (list.kind !== "entries")
-        throw refused(notAListSentence(where, "denied", list), "config.agent.unknown_tool", "not_a_list");
-    return list.entries.map((entry, index) => {
-        if (entry === "*")
-            return entry;
-        const read = readDeniedEntry(entry);
-        if (read.kind === "not_a_string")
-            throw refused(notAStringSentence(where, "denied", index, read.type), "config.agent.unknown_tool", "not_a_string");
-        const flaw = compileAllowList([read.name], "deny").inert[0];
-        if (flaw !== undefined && flaw.reason === "grammar")
-            throw grammarRefusal(where, "denied", { ...flaw, entry: read.name }, "config.agent.unknown_tool");
-        return read.name;
-    });
+    return readableToolNameList(where, "denied", value, "config.agent.unknown_tool").map((read) => read.name);
+}
+function inheritedListsWhere(ceilings, i) {
+    const up = ceilings - 1 - i;
+    return up === 0 ? "the lists of the run this leg was spawned under" : `the lists of the run ${up} spawn${up === 1 ? "" : "s"} above the run this leg was spawned under`;
+}
+function readSelectorLayer(layer, layerWhere, listWhere, recorded) {
+    if (!isToolSelectorLayer(layer)) {
+        throw refused(`${layerWhere} are a value that is ${valueTypeLabel(layer)}, not a pair of tool-name lists (an allowed and a denied list) — the leg does not start. Fix the layer.`, "config.tool_face_control", "not_a_list");
+    }
+    for (const side of ["allowed", "denied"]) {
+        const where = listWhere(side);
+        const entries = readableToolNameList(where, side, side === "allowed" ? layer.allow : layer.deny, "config.tool_face_control");
+        const written = recorded ? entries.find((read) => !isCanonicalToolName(read.entry)) : undefined;
+        if (written !== undefined) {
+            throw refused(`${where} declares ${renderListEntry(written.entry)} in its ${LIST_WORD[side]}: a row records each tool name in its bare spelling (\`Read\`, never \`Read()\`, \`Read(*)\` or \`Read(…)\`), and this entry was recorded by an engine that read the list otherwise — it is read here neither as that engine read it nor as this one would`, "config.tool_face_control", "unsupported_pattern");
+        }
+    }
+}
+function ownToolListsFlaw(value) {
+    try {
+        if (typeof value !== "object" || value === null || Array.isArray(value))
+            return `a value that is ${valueTypeLabel(value)}, not a tool name with an agent definition name and the digest of the lists it wrote`;
+        const { toolName, definition, lists } = value;
+        if (typeof toolName !== "string" || toolName.length === 0)
+            return `a tool whose name is ${typeof toolName === "string" ? "empty" : `a value that is ${valueTypeLabel(toolName)}`}, not a tool name`;
+        const problem = callerToolNameProblem(toolName);
+        if (problem !== undefined)
+            return `a tool whose name is not one a caller tool can carry (${problem})`;
+        if (definition !== undefined && typeof definition !== "string")
+            return `an agent definition whose name is a value that is ${valueTypeLabel(definition)}, not a name`;
+        if (definition === "")
+            return "an agent definition whose name is empty, not a name";
+        if (lists === undefined)
+            return "a record with no digest of the lists it wrote";
+        if (typeof lists !== "string")
+            return `a digest of the lists it wrote that is a value that is ${valueTypeLabel(lists)}, not a digest`;
+        if (lists.length === 0)
+            return "a digest of the lists it wrote that is empty, not a digest";
+        return undefined;
+    }
+    catch {
+        return "a value that cannot be read";
+    }
+}
+export function persistedToolNamesRefusal(ceiling, chain, ownLists) {
+    const pending = "refused before the claim (the checkpoint stays pending): finish it on a worker of the engine that parked it, or expire it and run the work again";
+    const ownFlaw = ownLists === undefined ? undefined : ownToolListsFlaw(ownLists);
+    if (ownFlaw !== undefined)
+        return { message: `this leg's checkpoint row records the delegation tool that wrote its own lists as ${ownFlaw} — ${pending}`, reason: "invalid_record" };
+    if (ceiling !== undefined) {
+        const layers = readToolNameList(ceiling);
+        if (layers.kind !== "entries")
+            return { message: `the ceiling this leg's checkpoint row recorded is a value that is ${layers.kind === "not_a_list" ? layers.type : "a list that cannot be read"}, not a list of layers — ${pending}`, reason: "not_a_list" };
+        try {
+            layers.entries.forEach((layer, i) => readSelectorLayer(layer, inheritedListsWhere(layers.entries.length, i), () => inheritedListsWhere(layers.entries.length, i), true));
+        }
+        catch (e) {
+            return { message: `${e.message} — as this leg's checkpoint row recorded it; ${pending}`, reason: e.detail.reason };
+        }
+    }
+    if (!Array.isArray(chain))
+        return undefined;
+    const flaw = (() => {
+        for (const [layer, entry] of chain.entries()) {
+            if (typeof entry !== "object" || entry === null || "opaque" in entry || !Array.isArray(entry.components))
+                continue;
+            for (const c of entry.components) {
+                if (typeof c !== "object" || c === null)
+                    continue;
+                const { member, list } = projectionToolNames(c);
+                const where = `layer ${layer + 1}'s ${c.kind === "tool_deny" || c.kind === "tool_allowlist" || c.kind === "shell_command" ? `\`${c.kind}\`` : "component"} ${member}`;
+                const read = readToolNameList(list);
+                if (read.kind !== "entries")
+                    return { what: `${where} as a value that is ${read.kind === "not_a_list" ? read.type : "a list that cannot be read"}, not a list of tool names`, reason: "not_a_list" };
+                const at = read.entries.findIndex((name) => !isCanonicalToolName(name));
+                if (at < 0)
+                    continue;
+                const name = read.entries[at];
+                return typeof name === "string" ? { what: `${renderListEntry(name)} in ${where}`, reason: "unsupported_pattern" } : { what: `in ${where}, as entry ${at + 1}, a value that is ${valueTypeLabel(name)}`, reason: "not_a_string" };
+            }
+        }
+        return undefined;
+    })();
+    return flaw === undefined
+        ? undefined
+        : { reason: flaw.reason, message: `the checkpoint's frozen inherited constraint chain holds ${flaw.what}: a row records each tool name in its bare spelling (\`Read\`, never \`Read()\`, \`Read(*)\` or \`Read(…)\`), and this entry was recorded by a reading that is not the rule syntax's (an earlier engine's name set, or a policy that reads its lists as written) — it is replayed neither as that reading nor as this engine's; ${pending} (with the policy naming the tool itself)` };
+}
+export function refusePersistedToolNames(ceiling, chain, ownLists) {
+    const refusal = persistedToolNamesRefusal(ceiling, chain, ownLists);
+    if (refusal !== undefined)
+        throw refused(refusal.message, "config.tool_face_control", refusal.reason);
 }
 export function boundToolListsJudgment(evidence, own) {
     return evidence !== undefined && evidence === toolListsDigest(own.allow, own.exclude) ? evidence : undefined;
 }
+export function boundOwnToolLists(record, own) {
+    if (record === undefined)
+        return undefined;
+    const flaw = ownToolListsFlaw(record);
+    if (flaw !== undefined) {
+        throw refused(`this leg's internals (RunInternals.ownToolLists) record the delegation tool that wrote its own lists as ${flaw} — the leg does not start. Only the delegation lane writes that record: leave it out.`, "config.tool_face_control", "invalid_record");
+    }
+    const held = record;
+    return held.lists === toolListsDigest(own.allow, own.exclude) ? held : undefined;
+}
 export function judgeRunToolLists(input) {
     const { spec, tools, onceLedger, sessionId } = input;
     const advise = (err) => {
@@ -105,6 +257,13 @@ export function judgeRunToolLists(input) {
         catch {
         }
     };
+    const ownWhere = input.ownBy !== undefined ? delegationListWhere(input.ownBy.toolName, input.ownBy.definition) : undefined;
+    const ceilings = input.layers.length - 1;
+    input.layers.forEach((layer, i) => {
+        const own = i === ceilings;
+        const inherited = own ? undefined : inheritedListsWhere(ceilings, i);
+        readSelectorLayer(layer, inherited ?? "this run's own tool lists", (side) => inherited ?? ownWhere ?? (side === "allowed" ? "TaskSpec.allowTools" : "TaskSpec.excludeTools"), false);
+    });
     const denied = deniedProtocolTools(input.layers, input.legs);
     if (denied.length > 0) {
         const names = [...new Set(denied.map((h) => `"${h.name}"`))];
@@ -113,43 +272,29 @@ export function judgeRunToolLists(input) {
             const hits = denied.filter((h) => h.own === own).map((h) => `"${h.name}"`);
             return hits.length > 0 ? [`${whose} denies ${one ? "it" : hits.join(", ")}`] : [];
         };
-        const by = [...deniedBy(true, input.ownWhere ?? "this run's own excludeTools"), ...deniedBy(false, "an inherited list (the spawning run's excludeTools, or one it inherits)")];
+        const by = [...deniedBy(true, ownWhere ?? "this run's own excludeTools"), ...deniedBy(false, "an inherited list (the spawning run's excludeTools, or one it inherits)")];
         throw refused(`This kind of leg (${input.legs.join(", ")}) relies on ${names.join(", ")}, but ${by.join(" and ")} — the leg cannot work without ${one ? "it" : "them"}. Remove the entry from the list that names it.`, "config.tool_face_control", "protocol_denied");
     }
-    const delegationTools = (spec.tools ?? []).filter((t) => t.agentToolFaces !== undefined);
-    const known = new Set();
-    const add = (t) => {
-        known.add(t.name);
-        for (const a of t.aliases ?? [])
-            known.add(a);
-    };
-    for (const t of tools)
-        add(t);
-    for (const t of ENGINE_TOOLS)
-        add(t);
-    for (const t of spec.tools ?? [])
-        add(t);
-    for (const t of delegationTools)
-        for (const p of t.agentToolPool ?? [])
-            add(p);
-    const peers = new Set(PROTOCOL_TABLE.flatMap((ns) => (input.declaredPeers[ns.id] ?? []).map((p) => mintNamespacePrefix(ns, p.name))));
-    for (const name of known) {
-        const ns = protocolOf(name);
-        const split = ns !== undefined ? splitNamespacedName(name) : undefined;
-        if (split !== undefined && split.peer !== "")
-            peers.add(mintNamespacePrefix(split.ns, split.peer));
-    }
-    const universe = { known, peers };
+    const selector = compileToolSelector(input.layers, input.legs);
+    const pool = delegationPoolReading(spec.tools ?? [], valveLeaves(spec, selector));
+    const mounted = mountedToolNames([...tools, ...(spec.tools ?? [])]);
     if (!input.judgedUpstream) {
-        judgeToolNameList(input.ownWhere ?? "TaskSpec.allowTools", "allowed", input.own.allow, universe, advise, "config.tool_face_control");
-        judgeToolNameList(input.ownWhere ?? "TaskSpec.excludeTools", "denied", input.own.exclude, universe, advise, "config.tool_face_control");
+        const root = rootFacingUniverse(input.ownBy !== undefined ? new Set([...mounted, input.ownBy.toolName]) : mounted, pool, input.declaredPeers);
+        const own = [["allowed", input.own.allow], ["denied", input.own.exclude]];
+        const tell = input.toldUpstream === true ? () => undefined : advise;
+        for (const [side, value] of own)
+            judgeToolNameList(ownWhere ?? (side === "allowed" ? "TaskSpec.allowTools" : "TaskSpec.excludeTools"), side, value, root, tell, "config.tool_face_control");
     }
+    const children = new Map(pool.tools.map((t) => [t, childFacingUniverse(poolOf([t]), input.declaredPeers)]));
+    const taskTargets = pool.tools.length > 0 ? [...children.values()] : [childFacingUniverse(poolOf([]), input.declaredPeers)];
     for (const def of spec.agents ?? []) {
-        judgeToolNameList(`TaskSpec.agents: agent "${def.name}"`, "allowed", def.allowTools, universe, advise, "config.agent.unknown_tool");
-        judgeToolNameList(`TaskSpec.agents: agent "${def.name}"`, "denied", def.denyTools, universe, advise, "config.agent.unknown_tool");
+        for (const universe of taskTargets) {
+            judgeToolNameList(`TaskSpec.agents: agent "${def.name}"`, "allowed", def.allowTools, universe, advise, "config.agent.unknown_tool");
+            judgeToolNameList(`TaskSpec.agents: agent "${def.name}"`, "denied", def.denyTools, universe, advise, "config.agent.unknown_tool");
+        }
     }
     const replaced = new Set((spec.agents ?? []).map((d) => d.name));
-    for (const t of delegationTools) {
+    for (const [t, universe] of children) {
         for (const face of t.agentToolFaces ?? []) {
             if (face.authored === true && !replaced.has(face.name)) {
                 const faceWhere = delegationListWhere(t.name, face.name);
@@ -161,3 +306,17 @@ export function judgeRunToolLists(input) {
         judgeToolNameList(delegationListWhere(t.name, undefined), "denied", t.agentToolLevelDenyTools, universe, advise, "config.agent.unknown_tool");
     }
 }
+export function judgeHostToolCeiling(layers, agent, above = []) {
+    const where = (i) => `RunWorkflowOptions.toolCeiling, layer ${i + 1}`;
+    layers.forEach((layer, i) => readSelectorLayer(layer, where(i), () => where(i), false));
+    const callerTools = agent.tools ?? [];
+    const own = { ...(agent.allowTools != null ? { allow: agent.allowTools } : {}), deny: agent.excludeTools ?? [] };
+    const selector = compileToolSelector([...above, ...layers, own], ["delegated"]);
+    const pool = delegationPoolReading(callerTools, valveLeaves(agent, selector));
+    const universe = rootFacingUniverse(mountedToolNames(callerTools), pool, { mcp: undefined, a2a: undefined });
+    const unannounced = () => undefined;
+    layers.forEach((layer, i) => {
+        judgeToolNameList(where(i), "allowed", layer.allow, universe, unannounced, "config.tool_face_control");
+        judgeToolNameList(where(i), "denied", layer.deny, universe, unannounced, "config.tool_face_control");
+    });
+}

package/dist/core/runner/synthetic-tools.d.ts

@@ -110,8 +110,11 @@ export interface SkillListingEntry {
  *  and the tool, so what the prompt promises is exactly what the tool serves. Each field is READ ONCE, BY NAME, and
  *  both consumers see the copy: the gate screens this list while the invoke substitutes from it, so a `get baseDir()`
  *  answering those two reads differently passed a screen that measured a value the model never received — and a rest
- *  copy would silently drop an INHERITED or non-enumerable list. The two tables are read by {@link readSkillTable}. */
-export declare function normalizeSkills(skills: SkillLike[] | undefined): SkillLike[];
+ *  copy would silently drop an INHERITED or non-enumerable list. The two tables are read by {@link readSkillTable}.
+ *
+ *  The sorted view of {@link readSkillsSeat} (skills-seat.ts), which holds the seat's one reading — total over what a caller can
+ *  hand it, and once. */
+export declare function normalizeSkills(skills: unknown): SkillLike[];
 /** [c209-C] The skills listing's lead line — single-sourced so the run loop's durable-resume
  *  transcript probe (MED-3② skills arm, runtask) matches EXACTLY what the initial frame carries
  *  (probing the bare `<skills>` fence would be more collision-prone in model-quoted text). */

package/dist/core/runner/synthetic-tools.js

@@ -5,6 +5,7 @@ import { SKILL_LISTING_DEFAULT_BUDGET, SKILL_LISTING_DESC_MAX_CHARS_DEFAULT } fr
 import { readSkillTable, skillNamedBy } from "../skill-grant.js";
 import { toolFace } from "../tool-catalog-entries.js";
 import { substituteSkillRoot, substituteSkillRootBounded } from "./skill-base-dir.js";
+import { readSkillsSeat } from "./skills-seat.js";
 import { foldListingWithin } from "./listing-fold.js";
 export const OUTPUT_TOOL_NAME = "StructuredOutput";
 export const REPORT_BLOCKED_TOOL_NAME = "ReportBlocked";
@@ -109,18 +110,7 @@ function skillFilesSuffix(files) {
     return ` [files: ${shown.join(", ")}${more > 0 ? `, +${more} more` : ""}]`;
 }
 export function normalizeSkills(skills) {
-    const seen = new Set();
-    const out = [];
-    for (const s of skills ?? []) {
-        if (!seen.has(s.name)) {
-            seen.add(s.name);
-            const { name, description, content, allowedTools, disallowedTools, files, baseDir, ...rest } = s;
-            void rest;
-            const [allowed, denied] = [readSkillTable(allowedTools), readSkillTable(disallowedTools)];
-            out.push({ name, description, content, ...(allowed !== undefined ? { allowedTools: allowed } : {}), ...(denied !== undefined ? { disallowedTools: denied } : {}), ...(files !== undefined ? { files } : {}), ...(baseDir !== undefined ? { baseDir } : {}) });
-        }
-    }
-    return out.toSorted((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return readSkillsSeat(skills).toSorted((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
 }
 export const SKILLS_LISTING_PROBE_HEADER = "The following skills are available for this task.";
 export function skillListingLine(s, descMaxChars = SKILL_LISTING_DESC_MAX_CHARS_DEFAULT) {