@sema-agent/core 7.45.0 → 7.47.0

package/dist/core/permission-rules.js

@@ -1,15 +1,14 @@
 import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { splitNamespacedName } from "./tool-name-aliases.js";
-import { catalogRuleFaceOf, pathTargetOf } from "./tool-registry.js";
+import { catalogRuleFaceOf, isShellFaceToolName, pathTargetOf } from "./tool-registry.js";
 import { indexOfUnescaped, lastIndexOfUnescaped, parsePermissionRule } from "./permission-rule-syntax.js";
-import { NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, pathRuleHeadOf, pathRuleReachOf, programRunReachOf, ruleBasesNeeded, ruleToolGrammarOf } from "./permission-rule-model.js";
-import { pathFamilyOf, pathIdentityOf, spellingOfIdentity } from "../tools/fs/safety.js";
-import { effectivePathTargetOf } from "./effective-path-target.js";
-import { protectivePathTargetOf } from "./tool-registry.js";
+import { COMMAND_RULE_TOOL, NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, laneToolNamesOf, nameRuleAdmits, nameRuleSubjectOf, parseRuleText, programRunReachOf, ruleBasesNeeded, ruleToolGrammarOf } from "./permission-rule-model.js";
+import { pathFamilyOf } from "../tools/fs/safety.js";
+import { callTargetReadingOf, callTargetViewsOf } from "./effective-path-target.js";
+import { bindPathRules, pathRowsReach, policyAnchors, rowsWhereTheyLead } from "./path-rule-binding.js";
 import { ruleDenialSentence } from "./rule-denial-sentence.js";
 import { heldValues } from "./tool-name-readings.js";
 export { parsePermissionRule };
-export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 function describeBehavior(v) {
     switch (typeof v) {
         case "undefined": return "undefined";
@@ -93,22 +92,6 @@ export const fileToolParamVocabulary = (canonicalTool) => {
     const face = catalogRuleFaceOf(canonicalTool);
     return face?.params === undefined || pathTargetOf(canonicalTool) === undefined ? undefined : new Set(face.params);
 };
-export function pathRuleDenyRowOf(rule, bases) {
-    const family = pathFamilyOf(bases);
-    const tree = bases.root ?? bases.cwd;
-    const head = pathRuleHeadOf(rule.parsed, bases);
-    return {
-        rule: rule.ruleText,
-        tool: rule.parsed.tool,
-        pattern: parsePermissionRule(rule.ruleText).ruleContent ?? "",
-        faces: rule.faces,
-        reaches: (absolutePath) => {
-            const id = pathIdentityOf(absolutePath, family, tree);
-            return id.ok && pathRuleReachOf(rule.parsed, id.identity, bases).reach !== "not_reached";
-        },
-        ...(head !== undefined ? { head: spellingOfIdentity(head, family) } : {}),
-    };
-}
 function countStars(s) {
     let n = 0;
     for (const c of s)
@@ -126,13 +109,14 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
         return { face, judged: face !== undefined };
     };
     const byTool = new Map();
+    const command = { deny: [], ask: [] };
     const namespacedCovering = { deny: [], ask: [] };
     const issues = [];
     const bad = (rule, code, message) => {
         issues.push({ rule, code, message });
     };
     if (rules.length > caps.maxRules) {
-        return { byTool, namespacedCovering, issues: [{ rule: "", code: "invalid.cap_exceeded", message: `${rules.length} rules > maxRules ${caps.maxRules}` }] };
+        return { byTool, command, namespacedCovering, issues: [{ rule: "", code: "invalid.cap_exceeded", message: `${rules.length} rules > maxRules ${caps.maxRules}` }] };
     }
     for (const r of rules) {
         const text = r.rule;
@@ -190,17 +174,24 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
         }
         const content = parsed.ruleContent;
         const colon = content.indexOf(":");
-        if (toolName === "Bash") {
+        if (isShellFaceToolName(toolName)) {
             const paramPart = colon > 0 ? content.slice(0, colon).trim() : "";
-            const looksLikeParamRule = colon > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(paramPart) && BASH_GENERIC_PARAMS.has(paramPart);
-            if (!looksLikeParamRule || content.endsWith(":*")) {
+            const declaresParam = (tool) => colon > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(paramPart) && (catalogRuleFaceOf(tool)?.params ?? []).includes(paramPart);
+            const looksLikeParamRule = declaresParam(toolName);
+            if (toolName !== COMMAND_RULE_TOOL && !looksLikeParamRule) {
+                const commandWordParam = declaresParam(COMMAND_RULE_TOOL) && !content.endsWith(":*");
+                bad(text, "invalid.command_rule", commandWordParam
+                    ? `"${text}" is a parameter rule on "${paramPart}", which ${toolName} does not declare (its rule parameters: ${(catalogRuleFaceOf(toolName)?.params ?? []).join(", ")}); a parameter rule reaches only the tool that declares the parameter, so ${COMMAND_RULE_TOOL}(${content}) is a rule on ${COMMAND_RULE_TOOL}'s own argument and does not reach ${toolName}. A shell command rule is written ${COMMAND_RULE_TOOL}(<command>) — it reaches ${toolName} and every other tool that runs a shell command by the command it runs.`
+                    : `a shell command rule is written ${COMMAND_RULE_TOOL}(…) — it reaches ${toolName} and every other tool that runs a shell command by the command it runs; "${text}" names no rule upstream reads. Write ${COMMAND_RULE_TOOL}(${content}).`);
+                continue;
+            }
+            if (toolName === COMMAND_RULE_TOOL && (!looksLikeParamRule || content.endsWith(":*"))) {
                 const parsedCommand = parseRuleText(text, verb);
                 if ("reject" in parsedCommand) {
                     bad(text, "invalid.command_rule", `${parsedCommand.reject.code}: ${parsedCommand.reject.message}`);
                     continue;
                 }
-                entry.content[verb].push({ parsed: parsedCommand.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
-                byTool.set(toolName, entry);
+                command[verb].push({ parsed: parsedCommand.rule, ruleText: text, ...(r.source !== undefined ? { source: r.source } : {}) });
                 continue;
             }
         }
@@ -233,9 +224,9 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
                     continue;
                 }
                 for (const base of ruleBasesNeeded(parsedPath.rule)) {
-                    const value = base === "cwd" ? (pathBases.cwd ?? pathBases.root) : pathBases[base];
-                    if (!isUsablePathBase(value, pathFamilyOf(pathBases))) {
-                        bad(text, "unsupported.path_base", `"${text}" is relative to ${PATH_RULE_BASE_LABEL[base]}, and this policy was given no absolute \`pathBases.${base}\`${base === "cwd" ? " (or `root`)" : ""} to resolve it against — the rule could not be judged on any call`);
+                    const declared = base === "cwd" ? (pathBases.cwd ?? pathBases.root) : pathBases[base];
+                    if (declared !== undefined && !isUsablePathBase(declared, pathFamilyOf(pathBases))) {
+                        bad(text, "unsupported.path_base", `"${text}" is relative to ${PATH_RULE_BASE_LABEL[base]}, and the \`pathBases.${base === "cwd" && pathBases.cwd === undefined ? "root" : base}\` this policy declares is not an absolute path of its tree's family — the rule could not be judged on any call`);
                     }
                 }
                 if (issues.length > 0 && issues[issues.length - 1].rule === text && issues[issues.length - 1].code === "unsupported.path_base")
@@ -280,7 +271,7 @@ function compile(rules, caps, primaryFieldGeneric, ruleFaces, pathBases = {}) {
         entry.param[verb].push({ param, pattern, behavior: verb, ruleText: text, source: r.source });
         byTool.set(toolName, entry);
     }
-    return { byTool, namespacedCovering, issues };
+    return { byTool, command, namespacedCovering, issues };
 }
 export function validatePermissionRules(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
@@ -315,10 +306,11 @@ function ruleDenial(req, ruleText, source) {
 function ruleAskMessage(ruleText, source) {
     return `flagged by permission rule "${ruleText}"${source ? ` (${source})` : ""}`;
 }
+const NO_LEADS = new Map();
 export function createPermissionRulePolicy(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
     const pathBases = opts?.pathBases ?? {};
-    const { byTool, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.ruleFaces, pathBases);
+    const { byTool, command, namespacedCovering, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.ruleFaces, pathBases);
     const setLevelCap = issues.some((i) => i.code === "invalid.cap_exceeded" && i.rule === "");
     if (issues.length > 0 && ((opts?.onInvalidRule ?? "throw") === "throw" || setLevelCap)) {
         const e = new Error(`createPermissionRulePolicy: ${issues.length} invalid/unsupported rule(s):\n` +
@@ -350,6 +342,9 @@ export function createPermissionRulePolicy(rules, opts) {
         if (entry.bare.ask !== undefined || entry.param.ask.length > 0 || entry.content.ask.length > 0)
             nameSets.ask.push(toolName);
     }
+    for (const behavior of ["deny", "ask"])
+        if (command[behavior].length > 0 && !nameSets[behavior].includes(COMMAND_RULE_TOOL))
+            nameSets[behavior].push(COMMAND_RULE_TOOL);
     for (const behavior of ["deny", "ask"]) {
         for (const r of namespacedCovering[behavior])
             nameSets[behavior].push(r.ruleName);
@@ -360,19 +355,57 @@ export function createPermissionRulePolicy(rules, opts) {
         deny: [...byTool.values()].flatMap((e) => e.content.deny.filter((r) => r.faces !== undefined)),
         ask: [...byTool.values()].flatMap((e) => e.content.ask.filter((r) => r.faces !== undefined)),
     };
-    const pathDenyRules = faceRules.deny.map((r) => pathRuleDenyRowOf({ parsed: r.parsed, ruleText: r.ruleText, faces: r.faces }, pathBases));
-    const contentLaneOf = (behavior, entry, callFace) => [
+    const contentLaneOf = (behavior, entry, shellCall, callFace) => [
         ...(entry?.content[behavior].filter((r) => r.faces === undefined) ?? []),
+        ...(shellCall ? command[behavior] : []),
         ...(callFace !== undefined ? faceRules[behavior].filter((r) => r.faces.includes(callFace)) : []),
     ];
-    const commandParam = catalogRuleFaceOf("Bash")?.primaryParams[0] ?? "command";
-    const policyNamesTree = pathBases.root !== undefined || pathBases.cwd !== undefined;
-    const callBasesOf = (req) => policyNamesTree ? pathBases : { ...pathBases, ...(typeof req.root === "string" ? { root: req.root } : {}), ...(typeof req.cwd === "string" ? { cwd: req.cwd } : {}) };
+    const hasCommandRules = command.deny.length > 0 || command.ask.length > 0;
+    const commandParam = catalogRuleFaceOf(COMMAND_RULE_TOOL)?.primaryParams[0] ?? "command";
+    const pathRuleOf = new Map();
+    for (const e of byTool.values()) {
+        for (const behavior of ["deny", "ask"]) {
+            for (const r of e.content[behavior]) {
+                if (r.parsed.match !== "path" && r.parsed.match !== "subpath")
+                    continue;
+                pathRuleOf.set(r, { parsed: r.parsed, ruleText: r.ruleText, ...(behavior === "deny" && r.faces !== undefined ? { faces: r.faces } : {}) });
+            }
+        }
+    }
+    const pathSpecs = [...pathRuleOf.values()];
+    const bound = new Map();
+    const boundAt = (anchors) => {
+        const key = JSON.stringify([anchors.root ?? null, anchors.cwd ?? null, anchors.home ?? null]);
+        const prior = bound.get(key);
+        if (prior !== undefined)
+            return prior;
+        const rows = bindPathRules(pathSpecs, anchors);
+        const of = new Map();
+        [...pathRuleOf.keys()].forEach((r, i) => of.set(r, rows[i]));
+        const out = { rows, of };
+        bound.set(key, out);
+        return out;
+    };
     const contentHit = (lane, req) => {
         if (lane.length === 0)
             return undefined;
-        const bases = callBasesOf(req);
-        const target = effectivePathTargetOf(req, protectivePathTargetOf(req), bases);
+        const pathLane = lane.filter((r) => pathRuleOf.has(r));
+        if (pathLane.length > 0) {
+            const views = callTargetViewsOf(req, "tighten", { ...(pathBases.root !== undefined ? { root: pathBases.root } : {}), ...(pathBases.cwd !== undefined ? { cwd: pathBases.cwd } : {}) });
+            if (views !== undefined) {
+                const { of } = boundAt(policyAnchors(pathBases, req.pathRuleAnchors));
+                const rows = rowsWhereTheyLead(pathLane.map((r) => of.get(r)), callTargetReadingOf(req)?.leads ?? NO_LEADS);
+                const hit = pathRowsReach(rows, views, "tighten");
+                const rule = hit === undefined ? undefined : pathLane.find((r) => of.get(r).spec === hit.row.spec);
+                if (hit !== undefined && hit.unreadable === undefined)
+                    return { rule: rule };
+                if (hit !== undefined)
+                    return judgeOthers(lane.filter((r) => !pathRuleOf.has(r)), req) ?? { rule: rule, unreadable: hit.unreadable };
+            }
+        }
+        return judgeOthers(lane.filter((r) => !pathRuleOf.has(r)), req);
+    };
+    const judgeOthers = (lane, req) => {
         const command = isPlainObjectArgs(req.args) ? req.args[commandParam] : undefined;
         let unreadable;
         for (const r of lane) {
@@ -382,20 +415,6 @@ export function createPermissionRulePolicy(rules, opts) {
                     return { rule: r };
                 continue;
             }
-            if (r.parsed.match === "subpath" || r.parsed.match === "path") {
-                if (target === undefined || target.kind === "refused")
-                    continue;
-                if (target.kind === "unreadable") {
-                    unreadable ??= { rule: r, unreadable: target.reason };
-                    continue;
-                }
-                const outcome = pathRuleReachOf(r.parsed, target.identity, bases);
-                if (outcome.reach === "reached")
-                    return { rule: r };
-                if (outcome.reach === "unreadable")
-                    unreadable ??= { rule: r, unreadable: outcome.reason };
-                continue;
-            }
             if (typeof command !== "string")
                 continue;
             const outcome = programRunReachOf(r.parsed, command);
@@ -430,7 +449,7 @@ export function createPermissionRulePolicy(rules, opts) {
     };
     return {
         nameSets: [nameSets],
-        ...(pathDenyRules.length > 0 ? { pathDenyRules } : {}),
+        ...(pathSpecs.length > 0 ? { pathRules: (anchors) => boundAt(policyAnchors(pathBases, anchors)).rows } : {}),
         check(req) {
             const entry = entryFor(req);
             const covering = hasCovering && protocolOf(req.toolName) !== undefined;
@@ -443,7 +462,8 @@ export function createPermissionRulePolicy(rules, opts) {
                     return { action: "deny", message: ruleDenial(req, coveringDeny.ruleText, coveringDeny.source) };
             }
             const callFace = faceRules.deny.length > 0 || faceRules.ask.length > 0 ? callPathFaceOf(req) : undefined;
-            const denyLane = contentLaneOf("deny", entry, callFace);
+            const shellCall = hasCommandRules && laneToolNamesOf(req).includes(COMMAND_RULE_TOOL);
+            const denyLane = contentLaneOf("deny", entry, shellCall, callFace);
             const contentDeny = denyLane.length > 0 ? contentHit(denyLane, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
                 return { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
@@ -466,7 +486,7 @@ export function createPermissionRulePolicy(rules, opts) {
                 if (coveringAsk)
                     return { action: "ask", message: ruleAskMessage(coveringAsk.ruleText, coveringAsk.source), matchedAskRule: coveringAsk.ruleText };
             }
-            const askLane = contentLaneOf("ask", entry, callFace);
+            const askLane = contentLaneOf("ask", entry, shellCall, callFace);
             const contentAsk = askLane.length > 0 ? contentHit(askLane, req) : undefined;
             if (contentAsk !== undefined) {
                 if (contentAsk.unreadable !== undefined)

package/dist/core/runner/child-tree.d.ts

@@ -1,4 +1,9 @@
 import type { RunnerDeps } from "../types.js";
+import type { ExecutionEnv } from "../../internal/harness.js";
+import type { PathRuleBases } from "../permission-rule-model.js";
+import type { ChildPlacement, InheritedGate, RunInternals } from "./contracts.js";
+import type { ToolPolicy } from "../tool-policy.js";
+import { CheckpointError } from "../checkpoint-store.js";
 /**
  * Whether this deployment can place a child agent in a tree OTHER than the caller's — the one fact behind
  * every request of that shape: an explicit `cwd`, a workflow agent's `isolation: "worktree"`, and the
@@ -11,3 +16,95 @@ import type { RunnerDeps } from "../types.js";
  * keeps its own code and sentence for the refusal, but none decides the condition itself.
  */
 export declare function deploymentCanRerootChild(deps: Pick<RunnerDeps, "executionEnvFactory">): boolean;
+/**
+ * Where a child the caller asked to place at `asked` actually landed (`childRoot`, the root its environment gave it) — the
+ * ONE judgment every reader of that fact takes
+ * (the delegation tool's worktree request, and the anchors of the rules the child inherits):
+ *  · `honored` — the environment's root is where the child was asked to be (canonical on both sides);
+ *  · `caller_tree` — it is not, and it lies inside the caller's own tree (`callerRoot`): the same filesystem, the wrong
+ *    directory — a worktree request then fails (the child would write the caller's checkout);
+ *  · `elsewhere` — neither: another filesystem namespace (a sandbox the factory minted). The child runs there, it is not
+ *    in the worktree it was offered, and it takes the caller's path rules again at its own anchors.
+ * A path the environment cannot canonicalize is compared as spelled. Residual: two namespaces that hold the same path
+ * string, with a factory claiming to honor it, read `honored`.
+ */
+export declare function childPlacementOf(env: Pick<ExecutionEnv, "canonicalPath">, childRoot: string, asked: string | undefined, callerRoot: string): Promise<ChildPlacement>;
+/** A delegated leg's placement: the place asked for is the hint (a minted worktree, an explicit cwd, the caller's own cwd)
+ *  — or, for a worktree the factory mints itself (`isolation`), that worktree on the caller's host (a remote environment's
+ *  is another namespace). A leg no delegation caller placed (no `callerRoot`) has no placement and reads nothing. */
+export declare function childPlacementOnLeg(env: ExecutionEnv, internals: Pick<RunInternals, "isolation" | "parentCwd"> & {
+    readonly callerRoot: string;
+}, root: string): Promise<ChildPlacement>;
+/** The refusal of a worktree the caller minted for a child its environment placed in the caller's own tree. */
+export declare function worktreeNotHonored(cwd: string): Error & {
+    code: "isolation.unavailable";
+};
+/**
+ * The chain's top leg's anchors as THIS leg reads them (the person's global / session path rows and every `~/` row anchor
+ * there): the chain's own (`live` as recorded, else the checkpoint's `seed` rebased — {@link recordedAnchors}), unless this
+ * leg is a child placed `elsewhere` or no chain names one — then this leg is the top. A recorded root that is not an
+ * absolute path anchors nothing: the rows it would anchor read `unreadable`.
+ */
+export declare function chainTopAnchors(cfg: {
+    leg: PathRuleBases;
+    live: InheritedGate["pathRuleAnchors"];
+    seed: InheritedGate["pathRuleAnchors"];
+    placement: ChildPlacement | undefined;
+    rebase: (p: string) => string;
+}): PathRuleBases;
+/** The installation records a leg reads: the live chain's (as recorded), else the checkpoint's (through the workspace rebase). */
+export interface ChainInstallations {
+    readonly live: InheritedGate["pathRuleInstallations"];
+    readonly seed: InheritedGate["pathRuleInstallations"];
+}
+/** Why no usable record says where a chain entry was installed: no record (a chain written before the record existed), a
+ *  record that does not cover the chain position for position, or a member that names no absolute root. */
+export type ChainInstallationGap = "absent" | "misaligned" | "invalid";
+/**
+ * The chain entries a leg could not install where they were installed: each UNINSTALLED entry (a host re-supplying a
+ * chain) whose path rules depend on the installing leg, with no usable record of that leg. Such a chain is refused —
+ * installing those entries anywhere else (the chain's top leg, this leg) would move what they protect. Entries whose rules
+ * do not depend on it, and installed entries, never need a record.
+ */
+export declare function chainInstallationGaps(chain: readonly ToolPolicy[], installations: ChainInstallations, rebase: (p: string) => string): Array<{
+    readonly position: number;
+    readonly gap: ChainInstallationGap;
+}>;
+/** The refusal of a chain with {@link chainInstallationGaps} (`resume.parent_constraint_mismatch`, `detail.reason` naming
+ *  the first gap's form); `pending` says the checkpoint is still pending (the refusal came before the claim). */
+export declare function chainInstallationRefusal(gaps: ReadonlyArray<{
+    readonly position: number;
+    readonly gap: ChainInstallationGap;
+}>, pending: boolean): CheckpointError;
+/**
+ * How a leg holds a caller policy — its own (`TaskSpec.toolPolicy` / `RunnerDeps.toolPolicy`) or one its delegation chain
+ * hands it: a policy is installed where it ENTERS the chain, and a child holds its ancestor's installation (one object,
+ * the same anchors) — its own caller slot included when that slot names the policy an ancestor installed. Installed again:
+ * on a child placed `elsewhere` (another filesystem namespace — the ancestor's anchors name another namespace's files), at
+ * this leg's anchors; a chain entry handed uninstalled (a host re-supplying a chain), where its installing leg recorded it
+ * (`InheritedGate.pathRuleInstallations`, live or from the checkpoint). An uninstalled entry whose rules depend on that
+ * leg and whose record is not usable refuses the leg ({@link chainInstallationRefusal}); one whose rules do not, reads
+ * the same wherever it is installed (the chain's top leg).
+ */
+export declare function chainPolicyOnLeg(cfg: {
+    leg: PathRuleBases;
+    chainTop: PathRuleBases;
+    placement: ChildPlacement | undefined;
+    chain: readonly ToolPolicy[];
+    installations: ChainInstallations;
+    rebase: (p: string) => string;
+}): {
+    own: (policy: ToolPolicy | undefined) => ToolPolicy | undefined;
+    chained: (policy: ToolPolicy, position: number) => ToolPolicy;
+};
+/** The installation record of a chain entry (its root and home), `null` for an entry with no path rules installed. */
+export declare function installationRecordOf(policy: ToolPolicy): {
+    readonly root: string;
+    readonly home?: string;
+} | null;
+/** What a leg hands its children about anchors (data half): the chain's top leg's anchors — the person's global / session
+ *  rows and every `~/` row anchor there — and where each entry handed down was installed, position for position (a chain
+ *  re-supplied uninstalled is installed there again; absent when no entry is an installation). */
+export declare function chainAnchorRecords(chainTop: PathRuleBases, chain: readonly {
+    readonly policy: ToolPolicy;
+}[]): Pick<InheritedGate, "pathRuleAnchors" | "pathRuleInstallations">;

package/dist/core/runner/child-tree.js

@@ -1,3 +1,107 @@
+import { isRemoteExecutionEnv } from "../remote-env.js";
+import { isAbsolutePathForm } from "../../tools/fs/safety.js";
+import { installPolicyAnchors, installationAnchorsOf, installedFrom } from "../path-rule-binding.js";
+import { CheckpointError } from "../checkpoint-store.js";
 export function deploymentCanRerootChild(deps) {
     return deps.executionEnvFactory !== undefined;
 }
+export async function childPlacementOf(env, childRoot, asked, callerRoot) {
+    const canon = async (p) => {
+        try {
+            const r = await env.canonicalPath(p);
+            return r.ok ? r.value : p;
+        }
+        catch {
+            return p;
+        }
+    };
+    const root = await canon(childRoot);
+    if (asked !== undefined && (await canon(asked)) === root)
+        return "honored";
+    const tree = await canon(callerRoot);
+    const sep = tree.includes("\\") && !tree.includes("/") ? "\\" : "/";
+    return root === tree || root.startsWith(tree.endsWith(sep) ? tree : tree + sep) ? "caller_tree" : "elsewhere";
+}
+export function childPlacementOnLeg(env, internals, root) {
+    const asked = internals.isolation === "worktree" ? (isRemoteExecutionEnv(env) ? undefined : root) : internals.parentCwd;
+    return childPlacementOf(env, root, asked, internals.callerRoot);
+}
+export function worktreeNotHonored(cwd) {
+    return Object.assign(new Error(`isolation "worktree" was requested but cannot be honored: the execution environment factory placed the sub-agent at "${cwd}", inside the caller's own tree, instead of the worktree it was offered. The sub-agent was not started (fail-closed — no silent fallback to the shared working tree).`), { code: "isolation.unavailable" });
+}
+const AS_RECORDED = (p) => p;
+function recordedAnchors(r, rebase) {
+    if (r === null || r === undefined)
+        return undefined;
+    const read = (v) => {
+        if (typeof v !== "string")
+            return undefined;
+        const p = rebase(v);
+        return isAbsolutePathForm(p) ? p : undefined;
+    };
+    const [root, home] = [read(r.root), read(r.home)];
+    return { ...(root !== undefined ? { root } : {}), ...(home !== undefined ? { home } : {}) };
+}
+export function chainTopAnchors(cfg) {
+    if (cfg.placement === "elsewhere")
+        return cfg.leg;
+    return (cfg.live !== undefined ? recordedAnchors(cfg.live, AS_RECORDED) : recordedAnchors(cfg.seed, cfg.rebase)) ?? cfg.leg;
+}
+const GAP_REASON = { absent: "installation_record_absent", misaligned: "installation_record_misaligned", invalid: "installation_record_invalid" };
+function dependsOnInstallation(policy) {
+    if (installedFrom(policy) !== undefined)
+        return false;
+    return typeof policy.pathRules === "function" && policy.pathRules({}).some((row) => row.unanchored !== undefined);
+}
+function recordedInstallation(installations, chainLength, position, rebase) {
+    const [record, read] = installations.live !== undefined ? [installations.live, AS_RECORDED] : [installations.seed, rebase];
+    if (record === undefined)
+        return "absent";
+    if (record.length !== chainLength)
+        return "misaligned";
+    const a = recordedAnchors(record[position], read);
+    return a?.root === undefined ? "invalid" : a;
+}
+export function chainInstallationGaps(chain, installations, rebase) {
+    return chain.flatMap((policy, position) => {
+        if (!dependsOnInstallation(policy))
+            return [];
+        const r = recordedInstallation(installations, chain.length, position, rebase);
+        return typeof r === "string" ? [{ position, gap: r }] : [];
+    });
+}
+export function chainInstallationRefusal(gaps, pending) {
+    const first = gaps[0];
+    const form = { absent: "absent (a chain written before installation records existed, or one built without them)", misaligned: "misaligned (it does not cover the chain entry for entry)", invalid: "invalid for that entry (it names no absolute root)" }[first.gap];
+    return new CheckpointError("resume.parent_constraint_mismatch", `the parent-constraint chain carries ${gaps.length} polic${gaps.length === 1 ? "y" : "ies"} (entry ${gaps.map((g) => g.position).join(", ")}) whose path rules resolve against the leg that installed ${gaps.length === 1 ? "it" : "them"}, and the installation record is ${form} — installing ${gaps.length === 1 ? "it" : "them"} anywhere else would move what ${gaps.length === 1 ? "it protects" : "they protect"}, so the chain is refused` +
+        (pending ? " before the claim (the checkpoint stays pending). A task parked before 7.46.0 under such a chain cannot be resumed by this version: let a worker of the version that parked it finish it, or let it expire and submit the task again." : "."), { reason: GAP_REASON[first.gap] });
+}
+export function chainPolicyOnLeg(cfg) {
+    if (cfg.placement !== "elsewhere") {
+        const gaps = chainInstallationGaps(cfg.chain, cfg.installations, cfg.rebase);
+        if (gaps.length > 0)
+            throw chainInstallationRefusal(gaps, false);
+    }
+    const recorded = (position) => {
+        const r = recordedInstallation(cfg.installations, cfg.chain.length, position, cfg.rebase);
+        return typeof r === "string" ? undefined : r;
+    };
+    const chained = (policy, position) => (cfg.placement === "elsewhere" ? installPolicyAnchors(policy, cfg.leg) : installedFrom(policy) !== undefined ? policy : installPolicyAnchors(policy, recorded(position) ?? cfg.chainTop)) ?? policy;
+    const own = (policy) => {
+        if (policy === undefined)
+            return undefined;
+        const position = cfg.placement === "elsewhere" ? -1 : cfg.chain.findIndex((c) => (installedFrom(c) ?? c) === (installedFrom(policy) ?? policy));
+        return position >= 0 ? chained(cfg.chain[position], position) : installPolicyAnchors(policy, cfg.leg);
+    };
+    return { own, chained };
+}
+export function installationRecordOf(policy) {
+    const a = installationAnchorsOf(policy);
+    return a?.root === undefined ? null : { root: a.root, ...(a.home !== undefined ? { home: a.home } : {}) };
+}
+export function chainAnchorRecords(chainTop, chain) {
+    return {
+        ...(chainTop.root !== undefined ? { pathRuleAnchors: { root: chainTop.root, ...(chainTop.home !== undefined ? { home: chainTop.home } : {}) } } : {}),
+        ...(chain.some((pc) => installationAnchorsOf(pc.policy)?.root !== undefined) ? { pathRuleInstallations: chain.map((pc) => installationRecordOf(pc.policy)) } : {}),
+    };
+}

package/dist/core/runner/construction-doors.d.ts

@@ -0,0 +1,5 @@
+import type { RunnerDeps } from "../types.js";
+/** The retired-seat door ({@link assertNoRetiredRunnerDeps}), then the seats whose value is screened at construction and
+ *  never again: the declared configuration root must be the absolute path of an existing directory — a root that names no
+ *  directory guards nothing, so it is refused here rather than read as absent. */
+export declare function assertRunnerDepsDoors(deps: RunnerDeps): void;

package/dist/core/runner/construction-doors.js

@@ -0,0 +1,6 @@
+import { checkedAgentConfigDir } from "../agent-config-dir.js";
+import { assertNoRetiredRunnerDeps } from "./retired-runner-deps.js";
+export function assertRunnerDepsDoors(deps) {
+    assertNoRetiredRunnerDeps(deps);
+    checkedAgentConfigDir(deps.agentConfigDir, "RunnerDeps.agentConfigDir");
+}

package/dist/core/runner/contracts.d.ts

@@ -393,6 +393,8 @@ export interface Prepared {
     cwdRef?: CwdRef;
     /** The root the hand tools resolve root-relative spellings against (present with hands; read-only hands included). */
     handsRoot?: string;
+    /** The leg's target-reading stamp (present with hands): the resume belts stamp the executed bytes' request with it. */
+    stampCallTarget?: import("../effective-path-target.js").CallTargetStamp;
     /** The run's TOOL-PROGRESS lane seat, late-bound for the same reason `harnessRef` is (the tool band is
      *  built during prepare; the lane needs `pushContent` and `ident`, which exist only after it returns).
      *  The driver binds `current` right after `pushContent` exists. Always present on a completed prepare —
@@ -1417,6 +1419,29 @@ export interface InheritedGate {
      * had a governance surface (their opaque posture is untouched). Serializable; persists on checkpoints.
      */
     orgAdmissionGoverned?: true;
+    /**
+     * The chain's TOP leg's root and environment home (data half, serializable; persists on the checkpoint's data half):
+     * the anchors of the person's global and session path rows and of every `~/` row on this chain — a child judges them
+     * where the chain was installed, not at its own root (a project row anchors at its own scope root). Emitted by every leg
+     * that hands a chain down (a top leg emits its own). Absent on an older chain ⇒ the child is its own top. A child placed
+     * in ANOTHER filesystem namespace (its environment did not put it where it was asked, outside the caller's tree) ignores
+     * it and takes its own leg as the top.
+     */
+    pathRuleAnchors?: {
+        readonly root: string;
+        readonly home?: string;
+    };
+    /**
+     * Where each `parentConstraints` entry was INSTALLED (data half, serializable; persists on the checkpoint's data half):
+     * position for position with `parentConstraints`, the root and home its path rules are anchored at (`null` for an entry
+     * with no path rules). A chain re-supplied with uninstalled policies (a resume in another process, a host-built chain)
+     * installs each where this records — never at another leg's anchors. Absent on an older chain: an uninstalled entry is
+     * installed at the chain's top leg (`pathRuleAnchors`).
+     */
+    pathRuleInstallations?: ReadonlyArray<{
+        readonly root: string;
+        readonly home?: string;
+    } | null>;
     /** Live ancestor caller-policy constraints (opaque half), ancestors first. `policy` is the ancestor's
      *  RESOLVED caller policy (`spec.toolPolicy ?? deps.toolPolicy` — the same slot the ancestor itself
      *  enforces, so a deps-level baseline is inherited too).
@@ -2137,6 +2162,20 @@ export interface RunInternals {
      * callers (ctx-injection posture, same as `parentCwd`).
      */
     requestedCwd?: string;
+    /**
+     * The SPAWNING run's own root, filled ONLY by core delegation callers beside `parentCwd` (ctx-injection posture): with
+     * it the child's prepare judges where its environment actually placed it against where it was asked
+     * (`childPlacementOf`, child-tree.ts: honored / inside the caller's tree / elsewhere) — the fact the
+     * worktree request below and the anchors of the rules the child inherits read. Absent ⇒ no placement is judged (a top
+     * leg, a caller that does not delegate through core).
+     */
+    callerRoot?: string;
+    /**
+     * `parentCwd` is a worktree the caller minted for THIS child (the delegation tool's `isolation: "worktree"`): a child
+     * its environment placed inside the caller's own tree instead is refused before it starts (`isolation.unavailable`).
+     * Filled ONLY by the core delegation tool; never a {@link TaskSpec} field.
+     */
+    worktreeOffered?: true;
     /**
      * Subagent steer verb (dogfood finding 2026-07-03, "中途插话"): the host run's opt-in
      * SUBAGENT-STEER-HANDLE sink. When set, `createSubagentTool` runs each child via `runTaskStream`
@@ -2237,6 +2276,10 @@ export interface RunInternals {
  * non-isolated run reports its plain root with `isolated: false` — the observation face stays complete, while
  * the honest non-claim keeps a consumer from mistaking a SHARED tree for its own worktree.
  */
+/** Where a delegated child's environment placed it against where its caller asked (`childPlacementOf`, child-tree.ts):
+ *  `honored` — where it was asked; `caller_tree` — elsewhere inside the caller's own tree; `elsewhere` — another
+ *  filesystem namespace. */
+export type ChildPlacement = "honored" | "caller_tree" | "elsewhere";
 export interface ResolvedWorkspace {
     /** The task's effective working root — the same value every fence / LSP / prompt consumer uses. */
     cwd: string;
@@ -2247,6 +2290,9 @@ export interface ResolvedWorkspace {
      *  or names an unrelated directory — on the host. `isolated && !remote` is the only combination under
      *  which `cwd` is a host path a consumer may diff / merge / remove. */
     remote: boolean;
+    /** Where a delegated child's environment placed it against where its caller asked; absent on a leg no delegation
+     *  caller placed. */
+    placement?: ChildPlacement;
 }
 /**
  * The resolver's answer, with the WITHHELD cause beside the value.

package/dist/core/runner/gate-exit.d.ts

@@ -23,7 +23,7 @@
  */
 import { type ClassifierDenyCause, type DeniedBy, type GateOutcome, type ModeRefusal, type ModeRelease, type Settlement } from "../gate-outcome.js";
 import type { AutoModeClassifierRound } from "../auto-mode.js";
-import { type Arbitration, type AskClassification, type AskOrigin, type AskOriginFacts } from "../ask-origin.js";
+import { type Arbitration, type AskClassification, type AskFace, type AskOrigin, type AskOriginFacts } from "../ask-origin.js";
 import { type PermissionResult, type ResolvedAsk, type ToolCallRequest } from "../tool-policy.js";
 import type { SafeNotifier } from "../safe-notify.js";
 import type { HookSeatOutcome, PermissionDeniedPayload, PreToolUseResult, ToolGateInput, ToolGateResult } from "../hooks.js";
@@ -143,6 +143,9 @@ export interface PreToolUseScreening {
     /** The model-facing text for an answer the decision receipt refused (an ENGINE fail-closed, not the face's deny). */
     refusedReason(answer: PreToolUseResult): string;
 }
+/** The FACE a pass's questions are put on ({@link askFaceOf} of the call's wire name) — the one reading of it the
+ *  write-protection tighten (the fold) and every class derivation (the lanes) make. */
+export declare function passAskFace(pass: Pick<GatePass, "req">): AskFace;
 /**
  * ONE gate pass — the record the station groups (`runGateFold`, `runGateLanes`) and the exits read and write,
  * built once per call by `runToolGate` before the screening pass. What used to be the closure-captured `let`

package/dist/core/runner/gate-exit.js

@@ -1,5 +1,6 @@
 import { screenGateOutcome, SETTLEMENT_IS_REFUSAL } from "../gate-outcome.js";
-import { classifyAsk, headlessApprovalRemedy } from "../ask-origin.js";
+import { askFaceOf, classifyAsk, headlessApprovalRemedy } from "../ask-origin.js";
+import { wireOf } from "../tool-name-readings.js";
 import { isProtectedWrite } from "../tool-registry.js";
 import { askUnresolvableCauseOf, classifierDenyCauseOf, classifierRoundOf, decisionText, engineSettlementOf } from "../tool-policy.js";
 import { askUnresolvableRemedySeat } from "../ask-unresolvable-notice.js";
@@ -97,6 +98,9 @@ function withParkFailureCause(reason, parkFailed) {
         `(${inlineUntrusted(parkFailed, PARK_FAILURE_CAUSE_MAX)}), so the refusal above is what the fallback had ` +
         `left to say, not the reason the call stopped.`);
 }
+export function passAskFace(pass) {
+    return askFaceOf(wireOf("gate.askFace", pass.req));
+}
 export async function engineFailClosedExit(pass, reason) {
     const { input, toolName, toolCallId, notifyPermissionDenied } = pass;
     const gate = directDeny("hook");