@sema-agent/core 7.44.0 → 7.46.0

package/dist/agents/extra-tool-names.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The roster a host declares for a delegation tool's `extraTools` factory (`SubagentToolOptions.extraToolNames`): every tool
+ * the factory may inject at a spawn, by the names it answers to and its content class. Declared, the delegation tool's pool can
+ * be listed again — the judgment of a denied-tools list and the memory content-origin reader read it exactly as they read the
+ * static pool. Each spawn then checks the factory's products against it: a product the roster does not declare (a name or an
+ * alias no entry carries), or declares nearer to home than the product says it is (its content class further out than the
+ * entry's), refuses that spawn. The roster is an upper bound: a declared tool the factory did not inject this time is fine.
+ *
+ * One code for every way the declaration fails, `config.extra_tool_names`, with the arm on `detail.reason`: `shape` (the value
+ * is not a roster — refused where the delegation tool is built), `undeclared_name` / `undeclared_origin` (a product the roster
+ * does not cover — refused at the spawn). A host value is never printed or converted: a sentence names an entry's place and
+ * the TYPE of what it found there.
+ */
+import type { ToolContentOrigin, ToolSpec } from "../core/types.js";
+export declare const EXTRA_TOOL_NAMES_CODE = "config.extra_tool_names";
+/** Which way a declaration failed (`detail.reason`). */
+export type ExtraToolNamesReason = "shape" | "undeclared_name" | "undeclared_origin";
+/** One declared tool, as the delegation tool keeps it (a frozen copy of the host's entry). */
+export interface ExtraToolDeclaration {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+    readonly contentOrigin?: ToolContentOrigin;
+}
+/** The error a failed declaration is refused with: the code, and the arm on `detail.reason`. */
+export declare function extraToolNamesError(message: string, reason: ExtraToolNamesReason): Error & {
+    code: string;
+    detail: {
+        reason: ExtraToolNamesReason;
+    };
+};
+/**
+ * The host's declaration, read ONCE into frozen copies (a later change to the host's array does not reach the pool), or a
+ * refusal (`shape`): a roster on a delegation tool with no factory, a value that is not a list, an entry that is not an object, a
+ * name that is not a non-empty string, aliases that are not a list of non-empty strings, a content class outside the vocabulary,
+ * or one spelling in two entries.
+ */
+export declare function readExtraToolNames(value: unknown, hasFactory: boolean): readonly ExtraToolDeclaration[];
+/**
+ * Whether one factory product is a tool the roster declares, as declared — answering to exactly one entry's names, its class no
+ * further out than the entry's: undefined when it is, else the arm and the sentence (the delegation tool's name, the product's
+ * offending name or class, the roster). A product's content class is its own
+ * declaration when that is a vocabulary member, else external — the class an undeclared host tool reads as; an entry that
+ * states no class allows any.
+ */
+export declare function undeclaredExtraTool(roster: readonly ExtraToolDeclaration[], product: ToolSpec, toolName: string): {
+    reason: Exclude<ExtraToolNamesReason, "shape">;
+    sentence: string;
+} | undefined;
+/** One row of a delegation tool's pool face (`ToolSpec.agentToolPool`): a tool's names and its declared content class. */
+export interface DelegationPoolRow {
+    name: string;
+    aliases?: readonly string[];
+    contentOrigin?: ToolContentOrigin;
+}
+/**
+ * The pool a delegation tool's agent faces narrow FROM (`ToolSpec.agentToolPool`, read by the judgment of a denied-tools list and
+ * by the memory content-origin reader): what the tool hands its children — its own captured set, not the parent's roster (the two
+ * may differ, and a parent mounting only the delegation tool can still offer children a network tool) — plus the tools its factory
+ * is declared to inject. Absent when a factory has no declared roster: that pool does not exist until the call happens, and the
+ * readers take an absent pool as unknowable (the memory reader: external). Without an explicit pool the inherited surface is the
+ * face — its spawn-time narrowing only removes entries.
+ */
+export declare function delegationPoolFace(staticPool: readonly ToolSpec[], hasFactory: boolean, roster: readonly ExtraToolDeclaration[] | undefined): DelegationPoolRow[] | undefined;
+/** The first factory product the roster does not declare (see {@link undeclaredExtraTool}), or undefined when every one is declared. */
+export declare function firstUndeclaredExtraTool(roster: readonly ExtraToolDeclaration[], products: readonly ToolSpec[], toolName: string): ReturnType<typeof undeclaredExtraTool>;

package/dist/agents/extra-tool-names.js

@@ -0,0 +1,124 @@
+import { isToolContentOrigin } from "../core/memory-engine/content-origin.js";
+import { inlineUntrusted } from "../core/untrusted-text.js";
+import { readToolNameList, valueTypeLabel } from "./tool-filter.js";
+export const EXTRA_TOOL_NAMES_CODE = "config.extra_tool_names";
+export function extraToolNamesError(message, reason) {
+    const e = new Error(message);
+    e.code = EXTRA_TOOL_NAMES_CODE;
+    e.detail = { reason };
+    return e;
+}
+const shape = (what) => extraToolNamesError(`createSubagentTool: extraToolNames ${what} — it declares the tools the extraTools factory may inject, each { name, aliases?, contentOrigin? }. Fix the declaration.`, "shape");
+function own(entry, key) {
+    try {
+        return { ok: true, value: entry[key] };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+export function readExtraToolNames(value, hasFactory) {
+    if (!hasFactory)
+        throw extraToolNamesError("createSubagentTool: extraToolNames declares the tools an extraTools factory may inject, and this delegation tool has no extraTools factory. Remove the declaration or add the factory.", "shape");
+    const list = readToolNameList(value);
+    if (list.kind === "not_a_list")
+        throw shape(`is a value that is ${list.type}, not a list`);
+    if (list.kind === "unreadable")
+        throw shape("is a list whose entries cannot be read (an accessor or a proxy trap threw)");
+    const out = [];
+    const owner = new Map();
+    list.entries.forEach((entry, index) => {
+        const at = `entry ${index + 1}`;
+        if (entry === null || typeof entry !== "object" || valueTypeLabel(entry) !== "an object")
+            throw shape(`${at} is a value that is ${valueTypeLabel(entry)}, not an object`);
+        const name = own(entry, "name");
+        if (!name.ok)
+            throw shape(`${at}: its name cannot be read`);
+        if (typeof name.value !== "string" || name.value === "")
+            throw shape(`${at}: its name is ${typeof name.value === "string" ? "empty" : `a value that is ${valueTypeLabel(name.value)}`}, not a tool name`);
+        const aliasesRead = own(entry, "aliases");
+        if (!aliasesRead.ok)
+            throw shape(`${at}: its aliases cannot be read`);
+        let aliases;
+        if (aliasesRead.value !== undefined) {
+            const al = readToolNameList(aliasesRead.value);
+            if (al.kind !== "entries")
+                throw shape(`${at}: its aliases are ${al.kind === "not_a_list" ? `a value that is ${al.type}` : "a list that cannot be read"}, not a list of names`);
+            aliases = [];
+            for (const a of al.entries) {
+                if (typeof a !== "string" || a === "")
+                    throw shape(`${at}: an alias is ${typeof a === "string" ? "empty" : `a value that is ${valueTypeLabel(a)}`}, not a tool name`);
+                aliases.push(a);
+            }
+        }
+        const originRead = own(entry, "contentOrigin");
+        if (!originRead.ok)
+            throw shape(`${at}: its contentOrigin cannot be read`);
+        if (originRead.value !== undefined && !isToolContentOrigin(originRead.value))
+            throw shape(`${at}: its contentOrigin is not one of "local", "execution", "external"`);
+        for (const spelling of new Set([name.value, ...(aliases ?? [])])) {
+            const first = owner.get(spelling);
+            if (first !== undefined)
+                throw shape(`entries ${first + 1} and ${index + 1} both answer to ${JSON.stringify(inlineUntrusted(spelling, 80))}`);
+            owner.set(spelling, index);
+        }
+        out.push(Object.freeze({
+            name: name.value,
+            ...(aliases !== undefined ? { aliases: Object.freeze(aliases) } : {}),
+            ...(originRead.value !== undefined ? { contentOrigin: originRead.value } : {}),
+        }));
+    });
+    return Object.freeze(out);
+}
+const REACH = { local: 0, execution: 1, external: 2 };
+const quoted = (name) => `"${inlineUntrusted(name, 80)}"`;
+function rosterPhrase(roster) {
+    const shown = roster.slice(0, 8).map((e) => quoted(e.name));
+    return roster.length === 0 ? "none" : shown.join(", ") + (roster.length > shown.length ? `, … (${roster.length - shown.length} more)` : "");
+}
+export function undeclaredExtraTool(roster, product, toolName) {
+    const where = `the extraTools factory of delegation tool ${quoted(toolName)}`;
+    const tail = "the declaration is the upper bound of what the factory may inject. Fix the declaration or the factory.";
+    const name = product.name;
+    if (typeof name !== "string")
+        return { reason: "undeclared_name", sentence: `${where} injected a tool whose name is a value that is ${valueTypeLabel(name)}, which its declared extra tools (extraToolNames: ${rosterPhrase(roster)}) cannot name — ${tail}` };
+    const entry = roster.find((e) => e.name === name || (e.aliases?.includes(name) ?? false));
+    if (entry === undefined)
+        return { reason: "undeclared_name", sentence: `${where} injected tool ${quoted(name)}, which its declared extra tools (extraToolNames: ${rosterPhrase(roster)}) do not name — ${tail}` };
+    const spellings = new Set([entry.name, ...(entry.aliases ?? [])]);
+    const aliases = product.aliases;
+    const aliasList = Array.isArray(aliases) ? aliases : [];
+    for (const alias of aliasList) {
+        if (typeof alias !== "string" || !spellings.has(alias)) {
+            const said = typeof alias === "string" ? quoted(alias) : `a value that is ${valueTypeLabel(alias)}`;
+            return { reason: "undeclared_name", sentence: `${where} injected tool ${quoted(name)} answering to ${said}, which its declared extra tools (extraToolNames: ${rosterPhrase(roster)}) do not name — ${tail}` };
+        }
+    }
+    const answers = new Set([name, ...aliasList]);
+    const missing = [...spellings].find((n) => !answers.has(n));
+    if (missing !== undefined)
+        return { reason: "undeclared_name", sentence: `${where} injected tool ${quoted(name)}, which does not answer to ${quoted(missing)} as its declared extra tools (extraToolNames: ${rosterPhrase(roster)}) say it does — ${tail}` };
+    const stated = product.contentOrigin;
+    const productClass = isToolContentOrigin(stated) ? stated : "external";
+    const declaredClass = entry.contentOrigin ?? "external";
+    if (REACH[productClass] > REACH[declaredClass]) {
+        return { reason: "undeclared_origin", sentence: `${where} injected tool ${quoted(name)} of content class "${productClass}", which its declared extra tools (extraToolNames: ${rosterPhrase(roster)}) state as "${declaredClass}" — ${tail}` };
+    }
+    return undefined;
+}
+export function delegationPoolFace(staticPool, hasFactory, roster) {
+    if (hasFactory && roster === undefined)
+        return undefined;
+    return [...staticPool, ...(roster ?? [])].map((t) => {
+        const origin = t.contentOrigin;
+        return { name: t.name, ...(t.aliases !== undefined ? { aliases: t.aliases } : {}), ...(origin !== undefined ? { contentOrigin: origin } : {}) };
+    });
+}
+export function firstUndeclaredExtraTool(roster, products, toolName) {
+    for (const product of products) {
+        const flaw = undeclaredExtraTool(roster, product, toolName);
+        if (flaw !== undefined)
+            return flaw;
+    }
+    return undefined;
+}

package/dist/agents/subagent.d.ts

@@ -704,13 +704,13 @@ export interface SubagentToolOptions {
     inheritedTools?: ToolSpec[];
     /**
      * Tool-level allowlist (design/38 1A), used when NO `agent` is selected (a selected agent definition's
-     * own `allowTools`/`denyTools` REPLACE these). When set, the child sees only these tools from `tools`
-     * (`["*"]` = all). Omit for the whole `tools` pool. Allowlist is the security-recommended shape.
+     * own `allowTools`/`denyTools` REPLACE these). When set, the child sees only these of its pool and of the engine's hand
+     * tools its run mounts (Read / Write / Bash …) (`["*"]` = all). Omit for everything. Allowlist is the security-recommended shape.
      * NOTE: this filters only the WORK tools — the nested delegation tool is governed by `maxDepth`, not
      * allow/deny. To deny the child any further delegation, set `maxDepth: 1` (not a `denyTools` entry).
      */
     allowTools?: string[];
-    /** Tool-level denylist (design/38 1A), used when no `agent` is selected: names removed (a deny wins). */
+    /** Tool-level denylist (design/38 1A), used when no `agent` is selected: names removed from the pool and the hand tools (a deny wins). */
     denyTools?: string[];
     /** System prompt / persona for the child. Default (1.259.0, CC 198 parity): the LEAN
      *  {@link SUBAGENT_PROMPT} (agent persona + return contract), NOT the full default constitution role
@@ -764,10 +764,11 @@ export interface SubagentToolOptions {
      * call's parent coordinates, to produce tool instances that cannot sit in the mount-time static
      * `tools` pool (the deployment case: per-task tools issued by a task-env registry — the static pool
      * is fixed at `createSubagentTool({...})` time, before any task exists). The products are MERGED
-     * INTO the `tools` pool and then flow through the EXACT SAME `resolveToolSubset` whitelist as the
+     * INTO the `tools` pool and then flow through the EXACT SAME subset reading as the
      * static tools — an agent definition's `allowTools`/`denyTools` (or the tool-level ones when no
      * agent is selected) govern them verbatim: an explicit allowlist must NAME an injected tool for the
-     * child to see it; `"*"`/absent allowlist = all. Nested delegation threads the SAME factory down
+     * child to see it; `"*"`/absent allowlist = all. Without {@link extraToolNames} the pool cannot be listed before a spawn.
+     * Nested delegation threads the SAME factory down
      * (`createSubagentToolNode(opts, depth+1)` carries it), so a grandchild spawn re-evaluates it — per-spawn,
      * at every level; each child gets its own instances bound to its own spawn moment (the
      * server-side factory is execute-time late-bound, so per-spawn evaluation is the confirmed shape).
@@ -788,6 +789,17 @@ export interface SubagentToolOptions {
      * tightening layer on the supported paths, never the only line of defense.
      */
     extraTools?: (ctx: SubagentSpawnContext) => ToolSpec[] | Promise<ToolSpec[]>;
+    /**
+     * The roster of {@link extraTools} — every tool it may inject: names, aliases, content class (absent = external). The declared
+     * tools join the pool, so the pool is listable before a spawn; a product outside the roster refuses that spawn
+     * (`config.extra_tool_names`, `detail.reason` `undeclared_name` / `undeclared_origin`, also to {@link onExtraToolsError});
+     * a malformed roster, or one with no factory, throws where the tool is built (`shape`). Absent ⇒ as before. See extra-tool-names.ts.
+     */
+    extraToolNames?: ReadonlyArray<{
+        name: string;
+        aliases?: readonly string[];
+        contentOrigin?: import("../core/types.js").ToolContentOrigin;
+    }>;
     /**
      * extraTools 快审 S3 — host-side sink for the ORIGINAL `extraTools` factory error (and the S4
      * budget-exceeded signal). The model-facing report deliberately carries only the fixed

package/dist/agents/subagent.js

@@ -15,7 +15,8 @@ export { childThinkingSeat, deploymentSubagentThinking, deploymentSubagentTierMo
 import { OUTPUT_TOOL_NAME, REPORT_BLOCKED_TOOL_NAME } from "../core/runner/synthetic-tools.js";
 import { TOOL_SEARCH_NAME } from "../core/runner/tool-disclosure.js";
 import { OFFLOAD_TOOL_NAME } from "../core/tool-result-store.js";
-import { resolveToolSubset, toolNameAllowed } from "./tool-filter.js";
+import { readToolNameList, resolveAgentToolSubset, snapshotDefinitionLists, snapshotToolNameList, toolNameAllowed, toolNameListFlaw } from "./tool-filter.js";
+import { EXTRA_TOOL_NAMES_CODE, delegationPoolFace, extraToolNamesError, firstUndeclaredExtraTool, readExtraToolNames } from "./extra-tool-names.js";
 import { builtinAgentDefinitions } from "./builtin-agents.js";
 import { SUBAGENT_PROMPT } from "../prompts/default.js";
 import { hasSessionFork } from "../core/session.js";
@@ -267,6 +268,19 @@ export function forkGovernanceDenial(enableFork, allowFork) {
         return "principal";
     return undefined;
 }
+const worktreeUnavailableSentence = (reason) => `Sub-agent not started: isolation "worktree" is unavailable on this run (${reason}). Retry without the isolation parameter.`;
+const WORKTREE_UNAVAILABLE = {
+    readOnly: worktreeUnavailableSentence("no worktree capability — a read-only run mints no worktree"),
+    needsFactory: worktreeUnavailableSentence("this deployment has no executionEnvFactory — a static execution environment has one shared working directory, so the child would run in this run's own root instead of a worktree; deploy an executionEnvFactory to enable worktree isolation"),
+    notHonored: worktreeUnavailableSentence("the execution environment factory placed the child inside this run's own tree instead of the worktree it was offered — it would have read and written this checkout; the worktree was removed and the child was not started"),
+    seatSilent: worktreeUnavailableSentence("the runner this tool runs children on does not declare whether it can place a child in a tree other than the caller's (its seat has no canRerootChild), and an undeclared answer is read as no; use a Runner, or add that method to the seat"),
+};
+const placementRefused = (terminal) => terminal?.kind === "failed" && terminal.code === "isolation.unavailable";
+const isolationUnavailable = (content) => ({
+    isError: true,
+    content,
+    details: { error: "isolation.unavailable" },
+});
 export function createSubagentWorktreeHelper(baseEnv, repoRoot) {
     const handles = new Map();
     return {
@@ -1259,13 +1273,17 @@ export function createSubagentTool(opts) {
         opts = { ...opts, builtinAgents: catalog.builtinAgents };
     }
     const assemblyModels = opts.models ?? catalog?.models;
+    if (opts.extraToolNames !== undefined)
+        opts = { ...opts, extraToolNames: readExtraToolNames(opts.extraToolNames, opts.extraTools !== undefined) };
+    if (opts.denyTools !== undefined)
+        opts = { ...opts, denyTools: snapshotToolNameList(opts.denyTools) };
+    if (opts.allowTools !== undefined)
+        opts = { ...opts, allowTools: snapshotToolNameList(opts.allowTools) };
     if (opts.agents?.length) {
         opts = {
             ...opts,
             agents: opts.agents.map((a) => ({
-                ...a,
-                ...(a.allowTools !== undefined ? { allowTools: [...a.allowTools] } : {}),
-                ...(a.denyTools !== undefined ? { denyTools: [...a.denyTools] } : {}),
+                ...snapshotDefinitionLists(a),
                 ...(a.skills !== undefined ? { skills: [...a.skills] } : {}),
             })),
         };
@@ -1302,9 +1320,11 @@ export function createSubagentTool(opts) {
     return built;
 }
 export function agentToolsNote(def) {
-    const allow = def.allowTools;
-    const hasAllow = allow !== undefined && allow.length > 0 && !allow.includes("*");
-    const deny = def.denyTools ?? [];
+    const allowRead = readToolNameList(def.allowTools);
+    const allow = allowRead.kind === "entries" ? allowRead.entries.filter((entry) => typeof entry === "string") : [];
+    const hasAllow = allow.length > 0 && !allow.includes("*");
+    const denyRead = readToolNameList(def.denyTools);
+    const deny = denyRead.kind === "entries" ? denyRead.entries.filter((entry) => typeof entry === "string") : [];
     const hasDeny = deny.length > 0;
     if (hasAllow && hasDeny) {
         const denied = new Set(deny);
@@ -1367,23 +1387,18 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             ...(a.allowTools !== undefined ? { allowTools: a.allowTools } : {}),
             ...(a.denyTools !== undefined ? { denyTools: a.denyTools } : {}),
             ...(depthPermitsNesting && toolNameAllowed(delegationToolName, a.allowTools, a.denyTools) ? { canRedelegate: true } : {}),
+            ...(depth === 0 && !builtins.includes(a) ? { authored: true } : {}),
         })),
         ...(forkOffered ? [{ name: FORK_SUBAGENT_TYPE, ...(depthPermitsNesting ? { canRedelegate: true } : {}) }] : []),
     ];
-    const agentToolPool = opts.extraTools !== undefined
-        ? undefined
-        : (opts.tools ?? opts.inheritedTools ?? []).map((t) => ({
-            name: t.name,
-            ...(t.aliases !== undefined ? { aliases: t.aliases } : {}),
-            ...(t.contentOrigin !== undefined
-                ? { contentOrigin: t.contentOrigin }
-                : {}),
-        }));
+    const agentToolPool = delegationPoolFace(opts.tools ?? opts.inheritedTools ?? [], opts.extraTools !== undefined, opts.extraToolNames);
     return {
         name: opts.name ?? DEFAULT_SUBAGENT_TOOL_NAME,
         ...toolFace("agent"),
         agentListing,
         agentToolFaces,
+        ...(depth === 0 && opts.allowTools !== undefined ? { agentToolLevelAllowTools: opts.allowTools } : {}),
+        ...(depth === 0 && opts.denyTools !== undefined ? { agentToolLevelDenyTools: opts.denyTools } : {}),
         ...(agentToolPool !== undefined ? { agentToolPool } : {}),
         ...(rosterNames !== undefined ? { agentModels: rosterNames } : {}),
         executionMode: "parallel",
@@ -1527,6 +1542,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     details: { error: "unknown subagent_type" },
                 };
             }
+            const allowFlaw = toolNameListFlaw(`delegation tool "${toolName}": ${def !== undefined ? `agent definition "${def.name}"` : "the tool-level list"}`, "allowed", def !== undefined ? def.allowTools : opts.allowTools);
+            if (allowFlaw !== undefined)
+                return { isError: true, content: `Sub-agent not started: ${inlineUntrusted(allowFlaw, 480)}`, details: { error: "config.agent.unknown_tool" } };
             if (a.name !== undefined && typeof a.name !== "string") {
                 return { isError: true, content: "Sub-agent not started: name must be a string.", details: { error: "name.invalid" } };
             }
@@ -1717,13 +1735,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
             let worktreeDir;
             if (reviveClaim === undefined && (a.isolation ?? def?.isolation) === "worktree") {
                 const iso = ctx.worktreeIsolation;
-                if (!iso) {
-                    return {
-                        isError: true,
-                        content: `Sub-agent not started: isolation "worktree" is unavailable on this run (no worktree capability — read-only run or no execution environment). Retry without the isolation parameter.`,
-                        details: { error: "isolation.unavailable" },
-                    };
-                }
+                if (!iso)
+                    return isolationUnavailable(WORKTREE_UNAVAILABLE.readOnly);
+                const reroots = opts.runner.canRerootChild?.();
+                if (reroots !== true)
+                    return isolationUnavailable(reroots === undefined ? WORKTREE_UNAVAILABLE.seatSilent : WORKTREE_UNAVAILABLE.needsFactory);
                 try {
                     worktreeDir = (await iso.mint(ctx.toolCallId)).worktreeDir;
                 }
@@ -1736,11 +1752,16 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
             }
             let worktreeKeptPath;
-            const finishWorktree = async () => {
+            let childPlacement;
+            const finishWorktree = async (terminal) => {
                 if (worktreeDir === undefined)
                     return undefined;
                 try {
                     const outcome = await ctx.worktreeIsolation.finish(worktreeDir);
+                    if (placementRefused(terminal))
+                        return undefined;
+                    if (childPlacement?.placement === "elsewhere")
+                        return `worktree: none — the execution environment ran the agent at ${inlineUntrusted(childPlacement.cwd, REPORT_FIELD_MAX)}, not in the worktree it was offered (${outcome === "pruned" ? "removed unused" : `kept at ${worktreeDir}: it changed though the agent never worked in it`})`;
                     if (outcome === "kept")
                         worktreeKeptPath = worktreeDir;
                     return outcome === "pruned"
@@ -1789,14 +1810,15 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         reportExtraToolsError(e);
                     }
                 }
-                if (ctx.signal?.aborted) {
+                const notStarted = async (why, details) => {
                     const wt = await finishWorktree();
-                    return {
-                        isError: true,
-                        content: `Sub-agent not started: the parent task was aborted while extraTools was being evaluated.${wt ? `\n${wt}` : ""}`,
-                        details: { error: "aborted" },
-                    };
-                }
+                    return { isError: true, content: `Sub-agent not started: ${why.slice(0, 1600)}${wt ? `\n${wt}` : ""}`, details };
+                };
+                if (ctx.signal?.aborted)
+                    return notStarted("the parent task was aborted while extraTools was being evaluated.", { error: "aborted" });
+                const undeclared = opts.extraToolNames !== undefined ? firstUndeclaredExtraTool(opts.extraToolNames, injectedTools, toolName) : undefined;
+                if (undeclared !== undefined)
+                    return (reportExtraToolsError(extraToolNamesError(undeclared.sentence, undeclared.reason)), notStarted(undeclared.sentence, { error: EXTRA_TOOL_NAMES_CODE, reason: undeclared.reason }));
             }
             const inherited = opts.tools === undefined && extraToolsNote === undefined ? inheritedChildPool(opts.inheritedTools ?? [], ctx.mountsCallerTool, wantsBackground && agentName === undefined && !wantsFork) : [];
             if (extraToolsNote !== undefined && opts.tools === undefined && (opts.inheritedTools?.length ?? 0) > 0)
@@ -1823,8 +1845,10 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 childPool = [...(opts.tools ?? inherited.filter((t) => ![t.name, ...(t.aliases ?? [])].some((n) => taken.has(n)))), ...accepted];
             }
-            const allowed = new Set([...resolveToolSubset(childPool, def ? def.allowTools : opts.allowTools, def ? def.denyTools : opts.denyTools), ...(agentName !== undefined ? teammateInheritedFamily(childPool.filter((t) => inherited.includes(t)), def ? def.denyTools : opts.denyTools) : [])]);
+            const subset = resolveAgentToolSubset(childPool, def ? def.allowTools : opts.allowTools, def ? def.denyTools : opts.denyTools);
+            const allowed = new Set([...subset.handed, ...(agentName !== undefined ? teammateInheritedFamily(childPool.filter((t) => inherited.includes(t)), def ? def.denyTools : opts.denyTools) : [])]);
             const childTools = childPool.filter((t) => allowed.has(t));
+            const childExcludeTools = ctx.excludeTools !== undefined || subset.withheldHands.length > 0 ? [...new Set([...(ctx.excludeTools ?? []), ...subset.withheldHands])] : undefined;
             const childSystemPrompt = def?.systemPrompt ?? opts.systemPrompt;
             const childDefaultPersona = childSystemPrompt === undefined && !wantsFork ? SUBAGENT_PROMPT : undefined;
             const defMaxTurns = typeof def?.maxTurns === "number" && Number.isFinite(def.maxTurns) && def.maxTurns > 0 ? def.maxTurns : undefined;
@@ -1902,7 +1926,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     ...(ctx.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: ctx.getApiKeyAndHeaders } : {}),
                     ...(ctx.checkpointStoreForChildren !== undefined ? { checkpointStore: ctx.checkpointStoreForChildren } : {}),
                     tools: [reportTool],
-                    ...(ctx.excludeTools !== undefined ? { excludeTools: [...ctx.excludeTools] } : {}),
+                    ...(childExcludeTools !== undefined ? { excludeTools: [...childExcludeTools] } : {}),
                     ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
                     ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                     ...(ctx.restoreGatedTools !== undefined ? { restoreGatedTools: ctx.restoreGatedTools === true ? true : [...ctx.restoreGatedTools] } : {}),
@@ -2148,8 +2172,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 })(),
                 ...(ctx.subagentRetain !== undefined ? { parentRetainLedger: ctx.subagentRetain } : {}),
                 onForwardEvent: recordingForward,
+                ...(ctx.parentCwd !== undefined ? { callerRoot: ctx.parentCwd } : {}),
                 ...(worktreeDir !== undefined
-                    ? { parentCwd: worktreeDir }
+                    ? { parentCwd: worktreeDir, worktreeOffered: true, onWorkspaceResolved: (ws) => void (childPlacement = ws) }
                     : childCwd !== undefined
                         ?
                             { parentCwd: childCwd, requestedCwd: childCwd }
@@ -2182,7 +2207,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.checkpointStoreForChildren !== undefined ? { checkpointStore: ctx.checkpointStoreForChildren } : {}),
                 ...(childOnAsk !== undefined ? { onAsk: childOnAsk } : {}),
                 ...childClampSeats({ handsReadOnly: ctx.handsReadOnly, interactiveTools: ctx.interactiveTools, approvalReach: ctx.approvalReach, readFace: ctx.readFace, writeFace: ctx.writeFace, readDenyPatterns: ctx.readDenyPatterns }),
-                ...(ctx.excludeTools !== undefined ? { excludeTools: [...ctx.excludeTools] } : {}),
+                ...(childExcludeTools !== undefined ? { excludeTools: [...childExcludeTools] } : {}),
                 ...(ctx.deferTools !== undefined ? { deferTools: [...ctx.deferTools] } : {}),
                 ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                 ...(ctx.restoreGatedTools !== undefined ? { restoreGatedTools: ctx.restoreGatedTools === true ? true : [...ctx.restoreGatedTools] } : {}),
@@ -2667,7 +2692,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const childFace = terminalProjection(child.terminal);
                         settleForkRow(child.terminal);
                         dropHostAbortListener();
-                        await finishWorktree();
+                        await finishWorktree(child.terminal);
                         try {
                             const nsb = child.stats.nested;
                             ctx.reportUsage?.({
@@ -3445,7 +3470,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     settleDelegationRow(child.terminal);
                     closeObserverWindow(childFace.status);
                     dropHostAbortListener();
-                    await finishWorktree();
+                    await finishWorktree(child.terminal);
                     try {
                         const ns2 = child.stats.nested;
                         ctx.reportUsage?.({
@@ -3850,7 +3875,9 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     }
                 }
             }
-            const worktreeLine = await finishWorktree();
+            const worktreeLine = await finishWorktree(child.terminal);
+            if (worktreeDir !== undefined && placementRefused(child.terminal))
+                return isolationUnavailable(WORKTREE_UNAVAILABLE.notHonored);
             const errClass = classifySubagentError(child.terminal);
             const lines = [
                 ...(handbackWarning ? [handbackWarning, ""] : []),

package/dist/agents/tool-filter.d.ts

@@ -1,4 +1,4 @@
-import type { ToolSpec } from "../core/types.js";
+import type { AgentDefinition, ToolSpec } from "../core/types.js";
 /**
  * Per-agent tool allow/deny (design/38 1A). Statically narrows a tool POOL to the subset a delegated
  * sub-agent / team member may use — assembly-time filtering (the tool simply never appears in the
@@ -16,13 +16,74 @@ import type { ToolSpec } from "../core/types.js";
  * Anchored (dual-leg verified): this spawn-time item-level filter IS the upstream shape for allow
  * entries — CC's resolveAgentTools partitions unknown names into an `invalidTools` bucket nobody
  * consumes at runtime, and a live 2.1.207 probe shows the agent stays listed/delegable with the
- * unknown item silently dropped, zero warnings. The asymmetric prepare-time fail-loud for
- * `TaskSpec.agents` DENY entries is a deliberate sema extension (no upstream deny-list exists): an
- * allow-typo silently narrows (safe direction), a deny-typo silently widens (unacceptable).
+ * unknown item silently dropped, zero warnings. A DENY entry is read as the reference reads it
+ * ({@link readDeniedEntry}: `Tool(content)` names `Tool`, the content is not read, the whole tool is hidden). The
+ * list is judged once before the run, from every place a deployment writes one (prepare's
+ * `judgeDeniedToolNames`): a spelling that can name no tool is refused, the rest is told to the host.
  *
  * Note: `"*"` in `allowTools` is the "allow all" sentinel, so a tool literally NAMED `"*"` cannot be
  * the sole allowed tool via this path (tool names are conventionally identifiers, so this is moot).
  */
+/**
+ * How ONE denied-tools entry is read — the reference reads each as a rule string, without trimming: `Tool(content)` names
+ * `Tool` (the content is dropped, so the whole tool is hidden), `Tool()` and `Tool(*)` are the bare name, and anything else
+ * — a malformed paren form, an entry with surrounding whitespace — is the whole string, which names no tool. A value that is
+ * not a string (a list a host read from a file can hold anything) names no tool either: it reads as `not_a_string` with a
+ * fixed label of its TYPE, and nothing about the value is read, converted or printed — `typeof` and the array test only.
+ */
+export type DeniedEntryReading = {
+    readonly kind: "name";
+    readonly name: string;
+    readonly content: boolean;
+} | {
+    readonly kind: "not_a_string";
+    readonly type: string;
+};
+export declare function readDeniedEntry(entry: unknown): DeniedEntryReading;
+/** A fixed label of a host value's TYPE for a sentence that must not print or convert the value (`typeof` and the array test only). */
+export declare function valueTypeLabel(value: unknown): string;
+/**
+ * How a tool-name list's VALUE (an agent definition's allowed-tools or denied-tools list) reads as a list. A host that reads its
+ * definitions from a file can hand over anything, and a list can be hostile as a container (an accessor or a proxy trap that
+ * throws, an overridden iterator, holes): it is read BY INDEX over its length, once, into a dense copy — no iterator of the host
+ * runs, a hole reads as `undefined` (an entry that is not a string) — and a value that is not an array, or an array whose read
+ * throws, is reported as such and never printed or converted.
+ */
+export type ToolNameListReading = {
+    readonly kind: "entries";
+    readonly entries: readonly unknown[];
+} | {
+    readonly kind: "not_a_list";
+    readonly type: string;
+} | {
+    readonly kind: "unreadable";
+};
+export declare function readToolNameList(value: unknown): ToolNameListReading;
+/** A tool-name list as the mount keeps it: the dense copy when it reads as a list, the failure marker when it cannot be read, else
+ *  the value itself (not a list: the judge refuses it, and its type never changes). */
+export declare function snapshotToolNameList(value: unknown): unknown;
+/** The two tool-name lists of a definition, and the words a sentence calls each. */
+export type ToolNameListSide = "allowed" | "denied";
+/** The sentence for an entry that is not a string: it can be no tool name; the sentence names its place and its type, never its value. */
+export declare function notAStringSentence(where: string, side: ToolNameListSide, index: number, type: string): string;
+/** The sentence for a value that is not a list, or a list that cannot be read: it names the type, never the value. */
+export declare function notAListSentence(where: string, side: ToolNameListSide, list: Exclude<ToolNameListReading, {
+    kind: "entries";
+}>): string;
+/**
+ * Why a host-written tool-name list cannot be one, as a sentence — or `undefined` when it is absent (`undefined` / `null`) or a list
+ * of strings. The one reading the judgment before the run and the spawn-time check of a tool that never went through prepare share.
+ */
+export declare function toolNameListFlaw(where: string, side: ToolNameListSide, value: unknown): string | undefined;
+/** A definition with its two tool-name lists replaced by their one copy — the copy every later reader (the judgment before the
+ *  run, the roster, the filter at each spawn) takes instead of the host's container. */
+export declare function snapshotDefinitionLists(def: AgentDefinition): AgentDefinition;
+/**
+ * The names an allowed-tools value admits, or `undefined` when it names no allowlist: absent, `null`, or a list holding the
+ * wildcard. A list admits its string entries (an entry that is not a string admits nothing); a value that is not a list admits
+ * NOTHING — the judge before the run refuses it, and a reader that meets it first fails closed.
+ */
+export declare function allowedToolNames(allowTools: unknown): ReadonlySet<string> | undefined;
 /**
  * Membership check for ONE tool name under the same allow/deny semantics as {@link resolveToolSubset}
  * (canonicalized both sides; `"*"` allow sentinel; deny wins). Used by the delegation tool to decide
@@ -32,4 +93,20 @@ import type { ToolSpec } from "../core/types.js";
  * TOOL-level allow/deny keeps its own semantics (delegation governed by `maxDepth`).
  */
 export declare function toolNameAllowed(name: string, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): boolean;
-export declare function resolveToolSubset(pool: ReadonlyArray<ToolSpec>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): ToolSpec[];
+export declare function resolveToolSubset<T extends {
+    readonly name: string;
+    readonly aliases?: readonly string[];
+} = ToolSpec>(pool: ReadonlyArray<T>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): T[];
+/**
+ * What ONE agent's tool-name lists leave it, read once over everything it can get: the tools the delegation tool hands it
+ * (`handed` — its pool and the factory's products, the subset in pool order) and the engine's hand tools its own run mounts
+ * over an execution environment ({@link HAND_TOOLS} — `withheldHands`, the wire names the lists take away, which the spawn
+ * adds to the child's exclusion list: the one fact every reader of "is this tool mounted" consults). One
+ * {@link resolveToolSubset} call over both halves, so a name reads the same whichever half carries it. The exclusion list
+ * unmounts by wire name, so a withheld hand name that a handed tool is mounted under stays off it (it would take the kept
+ * tool with it); a handed tool's alias does not count — the exclusion never reaches an alias, so the hand tool stays withheld.
+ */
+export declare function resolveAgentToolSubset(pool: ReadonlyArray<ToolSpec>, allowTools?: ReadonlyArray<string>, denyTools?: ReadonlyArray<string>): {
+    handed: ToolSpec[];
+    withheldHands: string[];
+};