@sema-agent/core 7.45.0 → 7.47.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 { readToolNameList, resolveToolSubset, snapshotDefinitionLists, snapshotToolNameList, toolNameAllowed, toolNameListFlaw } 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";
@@ -271,8 +272,10 @@ const worktreeUnavailableSentence = (reason) => `Sub-agent not started: isolatio
 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,
@@ -1270,6 +1273,8 @@ 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)
@@ -1386,15 +1391,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
         })),
         ...(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"),
@@ -1755,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"
@@ -1808,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)
@@ -1842,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;
@@ -1921,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] } : {}),
@@ -2167,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 }
@@ -2201,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] } : {}),
@@ -2686,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?.({
@@ -3464,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?.({
@@ -3869,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

@@ -93,4 +93,20 @@ export declare function allowedToolNames(allowTools: unknown): ReadonlySet<strin
  * 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[];
+};

package/dist/agents/tool-filter.js

@@ -1,4 +1,5 @@
 import { parsePermissionRule } from "../core/permission-rule-syntax.js";
+import { HAND_TOOLS } from "../core/tool-catalog-entries.js";
 export function readDeniedEntry(entry) {
     if (typeof entry !== "string")
         return { kind: "not_a_string", type: valueTypeLabel(entry) };
@@ -137,3 +138,9 @@ export function resolveToolSubset(pool, allowTools, denyTools) {
         return (!allow || matches(allow)) && (!deny || !matches(deny));
     });
 }
+export function resolveAgentToolSubset(pool, allowTools, denyTools) {
+    const kept = new Set(resolveToolSubset([...pool, ...HAND_TOOLS], allowTools, denyTools));
+    const handed = pool.filter((t) => kept.has(t));
+    const mountedUnder = new Set(handed.map((t) => t.name));
+    return { handed, withheldHands: HAND_TOOLS.filter((t) => !kept.has(t) && !mountedUnder.has(t.name)).map((t) => t.name) };
+}

package/dist/core/agent-config-dir.d.ts

@@ -0,0 +1,20 @@
+/** The configuration directory's name below a home: the one segment the deny tables spell the agent's own settings under. */
+export declare const AGENT_CONFIG_DIR_SEGMENT = ".sema";
+/** The code a declared root that names no directory is refused with, wherever it is declared. */
+export declare const AGENT_CONFIG_DIR_INVALID_CODE = "config.agent_config_dir_invalid";
+/** A run (the `/`-separated segments of a deny row, home word already removed) read below the configuration directory:
+ *  `.sema/settings.json` ⇒ `settings.json`, `.sema` ⇒ `""`, and `undefined` for a run that does not open with the
+ *  directory's name. The first segment is compared as the row compares it (ASCII-case-insensitive unless the row opts out).
+ *
+ *  @contract agent_config_dir.one_reading — which rows a declared configuration root relocates is decided HERE and nowhere
+ *  else: a row that opens with the `.sema` segment names its tail below the root, in the read placement, in the always-on
+ *  write-protection table and in the opt-in deny set alike; the root adds a place and never moves the default one, a row that
+ *  does not open with that segment keeps its place, and a face with a list of its own of "the rows that relocate" is a fork
+ *  of this sentence, not a variant of it. */
+export declare function agentConfigDirTail(run: string, caseSensitive?: boolean): string | undefined;
+/** The segments of a declared root in lexical normal form — what a path's leading segments are compared with. */
+export declare function agentConfigDirSegments(dir: string): string[];
+/** The declared configuration root as given (`undefined` = none declared, the default location), or a refusal naming the
+ *  seat and the shape of the value: not a string, empty, not absolute, no such directory, not a directory, not readable.
+ *  The directory is looked at on the host's own file system — the host that declares the root is the host that keeps it. */
+export declare function checkedAgentConfigDir(value: string | undefined, seat: string): string | undefined;

package/dist/core/agent-config-dir.js

@@ -0,0 +1,49 @@
+import { statSync } from "node:fs";
+import { isAbsolutePathForm, normalizeAbsPathLexically } from "../tools/fs/safety.js";
+export const AGENT_CONFIG_DIR_SEGMENT = ".sema";
+export const AGENT_CONFIG_DIR_INVALID_CODE = "config.agent_config_dir_invalid";
+export function agentConfigDirTail(run, caseSensitive = false) {
+    const [first, ...rest] = run.split("/").filter((segment) => segment.length > 0);
+    if (first === undefined)
+        return undefined;
+    const folded = caseSensitive ? first : first.replace(/[A-Z]/g, (c) => c.toLowerCase());
+    return folded === AGENT_CONFIG_DIR_SEGMENT ? rest.join("/") : undefined;
+}
+export function agentConfigDirSegments(dir) {
+    return normalizeAbsPathLexically(dir).split(/[\\/]/).filter((segment) => segment.length > 0);
+}
+function shown(value) {
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return typeof value;
+    }
+}
+function invalidAgentConfigDir(seat, value, why) {
+    const e = new Error(`${seat} ${shown(value)} ${why} — it must be the absolute path of an existing directory (the host's own configuration root); ` +
+        `a value that names no directory would guard nothing, so it is refused rather than read as the default \`~/${AGENT_CONFIG_DIR_SEGMENT}\` location.`);
+    e.code = AGENT_CONFIG_DIR_INVALID_CODE;
+    return e;
+}
+export function checkedAgentConfigDir(value, seat) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw invalidAgentConfigDir(seat, value, `is a ${value === null ? "null" : typeof value}, not a string`);
+    if (value.length === 0)
+        throw invalidAgentConfigDir(seat, value, "is an empty string");
+    if (!isAbsolutePathForm(value))
+        throw invalidAgentConfigDir(seat, value, "is not an absolute path");
+    let isDirectory;
+    try {
+        isDirectory = statSync(value).isDirectory();
+    }
+    catch (e) {
+        const code = typeof e === "object" && e !== null && "code" in e && typeof e.code === "string" ? e.code : "unreadable";
+        throw invalidAgentConfigDir(seat, value, code === "ENOENT" || code === "ENOTDIR" ? "names no existing directory" : `could not be examined (${code})`);
+    }
+    if (!isDirectory)
+        throw invalidAgentConfigDir(seat, value, "names a file, not a directory");
+    return value;
+}

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

@@ -1,7 +1,7 @@
 import { type RuleToolNameVerdict } from "./tool-name-aliases.js";
-import { type ToolCallRequest } from "./tool-policy.js";
+import type { ToolCallRequest } from "./tool-policy.js";
 import { type AllowRuleMember, type AllowRuleShadow } from "./allow-rule-shadow.js";
-import { type PersistedRule } from "./permission-rule-model.js";
+import { type PathRuleBases, type PersistedRule } from "./permission-rule-model.js";
 import { type AskClass, type AssertAllKeysHandled, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
 import { type ToolNameListReading } from "../agents/tool-filter.js";
 import { type EngineNotice } from "./engine-notice.js";
@@ -94,12 +94,14 @@ export interface AllowEntryRow {
     readonly entry: string;
     readonly compiled: CompiledAllowEntry;
 }
-/** The call facts a content row is judged against — the persisted lane's own bases. */
+/** The facts a list's content row is judged under: the leg's root and session (which rows apply), the live working
+ *  directory (where a command's `cd` lands), and the ANCHORS of the list's path rows — the leg the list was installed
+ *  on (its root and environment home): a path row of a list never moves with a `cd`. */
 export interface AllowEntryJudgeContext {
     readonly root: string | undefined;
     readonly sessionId: string | undefined;
     readonly liveCwd: () => string | undefined;
-    readonly home: string | undefined;
+    readonly anchors: PathRuleBases;
 }
 /**
  * The ONE list matcher, both directions — the rows that speak for the call, or undefined. ALLOW: the first name row that

package/dist/core/allow-entry.js

@@ -1,11 +1,11 @@
 import { heldBy } from "./tool-name-readings.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { judgeRuleToolName, splitNamespacedName } from "./tool-name-aliases.js";
-import { catalogToolNames } from "./tool-registry.js";
-import { COARSE_SHELL_TOOLS } from "./tool-policy.js";
+import { catalogToolNames, isShellFaceToolName } from "./tool-registry.js";
 import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
 import { COMMAND_RULE_TOOL, READ_RULE_TOOL, findAdmittingRule, laneToolNamesOf, 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";
 import { mandateDisclosureOf } from "./ask-origin.js";
 import { inlineUntrusted } from "./untrusted-text.js";
@@ -67,7 +67,7 @@ function readAllowEntry(raw, behavior, roster) {
                 return row({ kind: "namespace", pattern: name });
             return row({ kind: "tool", name });
         }
-        return row(COARSE_SHELL_TOOLS.includes(name) ? { kind: "shell", name } : { kind: "tool", name });
+        return row(isShellFaceToolName(name) ? { kind: "shell", name } : { kind: "tool", name });
     }
     if (name === COMMAND_RULE_TOOL) {
         const allowRead = parseRuleText(raw, behavior);
@@ -146,7 +146,7 @@ export function autoStripped(compiled, call) {
         case "shell":
             return true;
         case "tool":
-            return call !== undefined && answersTo(call, (n) => COARSE_SHELL_TOOLS.includes(n));
+            return call !== undefined && answersTo(call, isShellFaceToolName);
         case "command":
             return shellContentStripped(shellRuleContent(compiled.rule));
         case "namespace":
@@ -162,6 +162,7 @@ export function autoStripped(compiled, call) {
 export function autoStrippedRule(rule, call) {
     return rule.behavior === "allow" && rule.tool === COMMAND_RULE_TOOL && autoStripped({ kind: "command", rule }, call);
 }
+const NO_LEADS = new Map();
 function nameRowReaches(compiled, req) {
     const covers = compiled.kind === "namespace" ? (n) => namespacedRuleNameCovers(compiled.pattern, n) : compiled.kind === "tool" || compiled.kind === "shell" ? (n) => n === compiled.name : undefined;
     return covers !== undefined && answersTo(req, covers);
@@ -203,7 +204,7 @@ export function judgeAllowEntries(rows, req, behavior, ctx) {
     if (pathRows.length > 0) {
         const table = pathRows.map((r) => r.compiled.rule);
         for (const name of laneToolNamesOf(req).filter((n) => ruleToolGrammarOf(n) === "path")) {
-            const answer = pathRuleLaneAnswer(table, { ...req, toolName: name }, { root: ctx.root, sessionId: ctx.sessionId, liveCwd, home: ctx.home });
+            const answer = pathRuleLaneAnswer(table, { ...req, toolName: name }, { root: ctx.root, sessionId: ctx.sessionId, anchorsOf: () => ctx.anchors, leads: callTargetReadingOf(req)?.leads ?? NO_LEADS });
             const spoke = answer !== undefined && ("unreadable" in answer ? behavior === "deny" : "behavior" in answer && answer.behavior === behavior);
             if (spoke) {
                 const rule = answer !== undefined && "rules" in answer ? answer.rules[0]?.rule : undefined;