@sema-agent/core 7.45.0 → 7.46.0

package/dist/core/permission-rules.js

@@ -2,10 +2,10 @@ import { MCP_NAMESPACE, protocolOf } from "./protocol-table.js";
 import { splitNamespacedName } from "./tool-name-aliases.js";
 import { catalogRuleFaceOf, 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 { NAME_RULE_FACES, PATH_RULE_BASE_LABEL, PATH_RULE_FACES, callPathFaceOf, isUsablePathBase, 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 };
@@ -93,22 +93,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)
@@ -233,9 +217,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")
@@ -315,6 +299,7 @@ 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 ?? {};
@@ -360,19 +345,55 @@ 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) => [
         ...(entry?.content[behavior].filter((r) => r.faces === undefined) ?? []),
         ...(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 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 +403,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 +437,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;

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/permission-rule-lanes.d.ts

@@ -28,8 +28,10 @@
 import type { AskRuleEvidence, ToolCallRequest } from "../tool-policy.js";
 import { persistedRuleMandateOf, type RuleClearanceFacts } from "../ask-origin.js";
 import { type OrgGateVerdict, type PersistedRuleAnswer, type PersistedRuleHit, type PersistedRuleUnreadable } from "../hooks.js";
-import type { PersistedRule, PersistedRuleVerdict, RuleOffer, SegmentCoverage } from "../permission-rule-model.js";
-import { type ToolCallLike } from "../tool-registry.js";
+import type { PersistedRule, PersistedRuleVerdict, RuleOffer, ScopeRootIdentity, SegmentCoverage } from "../permission-rule-model.js";
+import { type PathRuleBases } from "../permission-rule-model.js";
+import { type HeadLeads } from "../path-rule-binding.js";
+import type { ToolCallLike } from "../tool-registry.js";
 import { type OrgRuleResolution } from "../permission-rule-org.js";
 import { type EffectivePermissionRules, type PermissionRuleStoreProvider } from "../permission-rule-provider.js";
 /** The one SHELL tool the persisted-rule lane's COMMAND grammar speaks for (the rule-offer face mints for it and the
@@ -87,28 +89,25 @@ export declare function persistedRuleHitOf(verdict: PersistedRuleVerdict | undef
  *  question nobody can answer. Every other verdict is {@link persistedRuleHitOf}'s hit. */
 export declare function persistedRuleAnswerOf(verdict: PersistedRuleVerdict | undefined): PersistedRuleHit | PersistedRuleUnreadable | undefined;
 /**
- * Widened to every path-targeting tool — the persisted-rule lane's PATH arm: the call's
- * target path in the SAME lexical identity the rule family is defined over, resolved by the ONE reader every
- * fence and every tool goes through (`effectivePathTargetOf`), so the lane judges the path the tool will
- * really open. The tool's own declaration decides which base a relative spelling takes and what an ABSENT
- * slot means — the lane no longer guesses `liveCwd ?? root` for every tool, which was wrong for the two
- * search tools in three separate shapes (see effective-path-target.ts). Still zero IO.
+ * The persisted-rule lane's PATH arm, for every path-targeting tool (and the entry lists' path rows): the call's target
+ * read through the ONE reader every lane shares ({@link callTargetViewsOf} — the reading's views, else the call's own
+ * lexical view), its rows anchored by `ctx.anchorsOf` (a stored row: a project row at its scope root, the rest at the
+ * chain's top leg; a list's row: where the list was installed) and judged where their heads lead too (`ctx.leads`). The
+ * precedence walk, the admission predicates and the Read-only allow are the model's (`adjudicatePersistedPathRules`); which
+ * project rows apply is judged against the leg's own root (`ctx.root`). An ALLOW here clears ASKS only — the read fences
+ * judge inside the tool exactly as they would with no rule anywhere — and an unresolvable path is no verdict on the allow
+ * side and the fail-closed ask on the tightening side.
  *
- * TWO readings of the call's path slot, one per direction: the tightening arms judge
- * the PROTECTIVE target (the object face's declaration, the catalog's for the name as the floor — reading
- * the catalog for an undeclared same-name tool can only tighten a deny); the allow arm judges the DECLARED
- * target (the face's OWN declaration only — a same-name tool that declares no path target is unconfirmable
- * and no grant admits it). The precedence walk, the admission predicates and the Read-only allow are the
- * model's (`adjudicatePersistedPathRules`). An ALLOW here clears ASKS only — the read fences (workspace
- * containment, the sensitive-read deny face) judge inside the tool exactly as they would with no rule
- * anywhere — and an unresolvable path is simply no verdict (fail toward asking on the allow side, no
- * refusal on the tightening side: a rule about a path speaks about no other shape).
+ * TWO readings of the call's path slot, one per direction: the tightening arms judge the PROTECTIVE reading (the object
+ * face's declaration, the catalog's for the name as the floor); the allow arm the DECLARED one (the face's OWN
+ * declaration only — a same-name tool that declares no path target is unconfirmable and no grant admits it).
  */
-export declare function pathRuleLaneAnswer(table: readonly PersistedRule[], req: Pick<ToolCallRequest, "toolName" | "args" | "face">, ctx: {
+export declare function pathRuleLaneAnswer(table: readonly PersistedRule[], req: Pick<ToolCallRequest, "toolName" | "args" | "face" | "targetReading" | "root" | "cwd">, ctx: {
     root: string | undefined;
     sessionId: string | undefined;
-    liveCwd: string | undefined;
-    home: string | undefined;
+    anchorsOf: (rule: PersistedRule) => PathRuleBases;
+    leads: ReadonlyMap<string, string | undefined>;
+    scopeIdentity?: ScopeRootIdentity;
 }): PersistedRuleHit | PersistedRuleUnreadable | undefined;
 /** The two lanes prepare hands the gate. Each is `undefined` when its partition is not configured, so
  *  a deployment without one keeps a decision path byte-identical to a build without the feature. */
@@ -152,15 +151,23 @@ export declare function createPermissionRuleLanes(cfg: {
     principal: string | undefined;
     sessionId: string;
     /** The isolation-aware task root — the same value the file fence, the prompt cwd and the session rules
-     *  use, so a project-scoped rule agrees with every other place that says "this project". */
+     *  use, so a project-scoped rule agrees with every other place that says "this project" (which project rows apply). */
     root: string;
+    /** The same root's canonical spelling (`undefined`: none could be read): a project row applies when its scope root covers
+     *  either spelling of it — the row's root resolved where it leads ({@link projectScopeIdentity}). */
+    rootCanonical: string | undefined;
+    /** The anchors of the person's global and session rows and of every `~/` row: the root and home of the chain's top leg
+     *  (a project row anchors at its own scope root). */
+    chainTop: PathRuleBases;
+    /** The leg's resolution of the locations rule heads pass through (the rows' twins). */
+    leads: HeadLeads;
     /** The LIVE tracked working directory: the base a relative cd resolves against
      *  after an earlier observable `cd`; read per call. */
     liveCwd: () => string | undefined;
-    /** The EXECUTION ENVIRONMENT's home directory (`ExecutionEnv.homeDir`, adapter-declared), the base a
-     *  `~/` path rule resolves against. `undefined` = the adapter declares none: a `~/` deny/ask row then reads
-     *  UNREADABLE for every call (a fail-closed ask), never the engine process's home. A declared value that is
-     *  not an absolute path is refused HERE, loudly (a bad declaration is a wiring defect, not an absence). */
+    /** The EXECUTION ENVIRONMENT's home directory (`ExecutionEnv.homeDir`, adapter-declared), screened here: a declared
+     *  value that is not an absolute path is refused, loudly (a bad declaration is a wiring defect, not an absence). The
+     *  `~/` rows anchor at the chain's top leg's home (`chainTop.home`); `undefined` there = no home was declared: a `~/`
+     *  deny/ask row then reads UNREADABLE for every call (a fail-closed ask), never the engine process's home. */
     home: string | undefined;
     /** True iff the reserved question-tool NAME resolves to the ENGINE's own content-ask tool on this leg. */
     questionToolMounted: boolean;
@@ -173,6 +180,8 @@ export declare function createPermissionRuleLanes(cfg: {
     /** The person is told their store (or the named sources of it) was skipped for a call (the run's one notice,
      *  `ruleStoreUnreadableNotice`). */
     onStoreUnreadable: (at: "call", sources?: EffectivePermissionRules["unreadableSources"]) => void;
+    /** The person is told the store served rows that were left out (the run's one `permission.rule_row_dropped`). */
+    onRowsDropped: (rows: EffectivePermissionRules["droppedRows"]) => void;
     /** The run's cut: a read it interrupts is abandoned quietly — a cancelled wait is no fact about the store. */
     signal?: AbortSignal;
     /** The allow layer's auto strip over a stored ALLOW row (true ⇒ out of this call's table BEFORE the coverage is chosen). */