@sema-agent/core 7.44.0 → 7.46.0

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

@@ -0,0 +1,110 @@
+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
+ * delegation tool's per-call or per-definition `isolation: "worktree"`.
+ *
+ * Only an `executionEnvFactory` can: it builds one execution env per task, so a child can be rooted
+ * wherever the request says. A static `executionEnv` is ONE shared env with ONE cwd — every child that
+ * runs on it runs in the caller's root, whatever tree it was asked to work in. A request the deployment
+ * cannot honor is refused before the child starts (and, for a worktree, before one is minted); each site
+ * 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

@@ -0,0 +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

@@ -31,7 +31,7 @@ import type { MaterializedA2a } from "../a2a.js";
 import type { CompactionForkContext, CompactionPhaseDurations, MaybeCompactOptions, RapidRefillState } from "../auto-compaction.js";
 import type { AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import type { AutoModeDecider, AutoModeDenialTracker, DenialLimitFallbackFace } from "../auto-mode.js";
-import type { SettlementKind } from "../gate-outcome.js";
+import type { HostDecider, SettlementKind } from "../gate-outcome.js";
 import type { CacheBreakDetector, ToolFingerprintInput } from "../cache-break-detector.js";
 import type { Checkpoint, CheckpointState, CheckpointStore, CheckpointToken, PendingSteerEntry, PlatformLimitReason, ReopenReason, ResourceLedger, ResourceLimitReason, ResumeOutcome, SerializedCheckpointState } from "../checkpoint-store.js";
 import type { ExecutionOutcomeRecordWord } from "../checkpoint-execution-record.js";
@@ -391,6 +391,10 @@ export interface Prepared {
     /** The per-task logical cwd ref when a real shell is mounted (else undefined). The Runner
      *  reads `cwdRef.current` after each tool to detect a `cd` move and emit `workspace_changed`. */
     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 —
@@ -442,7 +446,7 @@ export interface Prepared {
         toolCallId: string;
         toolName: string;
         args: unknown;
-        decidedBy: "person" | "sla_timeout" | "policy";
+        decidedBy: HostDecider;
     }) => Promise<{
         readonly refused: string;
     } | {
@@ -1415,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).
@@ -2135,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`
@@ -2235,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;
@@ -2245,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.
@@ -2748,6 +2796,10 @@ export interface RunnerSelfSeat {
         toolPolicy?: RunnerDeps["toolPolicy"];
         hooks?: RunnerDeps["hooks"];
     };
+    /** Whether a child task THIS runner runs can be placed in a tree other than the caller's (an explicit cwd, a worktree):
+     *  true only when its deps carry an `executionEnvFactory` (live read — `swapDeps` replaces the deps). The delegation tool asks
+     *  the runner that will run the child, not the one that ran the parent leg. Absent on a hand-built seat ⇒ read as "cannot say" ⇒ no; a hand-built seat answers for the runner its `runTask` forwards to. */
+    canRerootChild?(): boolean;
     /** Fire `RunnerDeps.onTaskOutcome` through the swallow-guarded chokepoint (thin compositions emit at their terminal state). */
     emitTaskOutcome(outcome: TaskOutcome): void;
     /** Run a task to completion. `internals` is the TRUSTED run-scoped channel (never a TaskSpec field). */

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). */

package/dist/core/runner/permission-rule-lanes.js

@@ -2,8 +2,8 @@ import { persistedRuleMandateOf, ruleClearanceOf } from "../ask-origin.js";
 import {} from "../hooks.js";
 import { adjudicatePersistedNameRules, adjudicatePersistedPathRules, adjudicatePersistedRules, callPathFaceOf, faceAskSpeaksFor, laneToolNamesOf, nameRuleSubjectOf, ruleToolGrammarOf, segmentCoverageOf, suggestRuleForName, suggestRulesForCommand } from "../permission-rule-model.js";
 import { isAbsolutePathForm } from "../../tools/fs/safety.js";
-import { effectivePathTargetOf } from "../effective-path-target.js";
-import { declaredPathTargetOf, protectivePathTargetOf } from "../tool-registry.js";
+import { callTargetViewsOf } from "../effective-path-target.js";
+import { bindPathRules, persistedRowAnchors, projectScopeIdentity } from "../path-rule-binding.js";
 import { heldBy, seatOf, wireOf } from "../tool-name-readings.js";
 import { orgRuleVerdictFor, settleOrgVerdictWithin } from "../permission-rule-org.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "../ask-question.js";
@@ -13,6 +13,7 @@ import { strongestAnswer } from "../persisted-rule-arms.js";
 import { gateWaitFailureOf, withGateTimeout } from "../gate-bounded-await.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS } from "../permission-rule-org.js";
 export const PERSISTED_RULE_TOOL = "Bash";
+const NO_LEADS = new Map();
 const HANDOFF_BOUND = 256;
 export function inheritedAskRuleEvidence(provider) {
     const org = provider?.partitions.org === true ? "not_adjudicated" : "not_wired";
@@ -40,12 +41,11 @@ export function persistedRuleAnswerOf(verdict) {
     return persistedRuleHitOf(verdict);
 }
 export function pathRuleLaneAnswer(table, req, ctx) {
-    const bases = { ...(ctx.root !== undefined ? { root: ctx.root } : {}), ...(ctx.liveCwd !== undefined ? { cwd: ctx.liveCwd } : {}), ...(ctx.home !== undefined ? { home: ctx.home } : {}) };
-    const tighten = effectivePathTargetOf(req, protectivePathTargetOf(req), bases);
-    const allow = effectivePathTargetOf(req, declaredPathTargetOf(req), bases);
+    const tighten = callTargetViewsOf(req, "tighten");
+    const allow = callTargetViewsOf(req, "allow");
     if (tighten === undefined && allow === undefined)
         return undefined;
-    return persistedRuleAnswerOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId, face: callPathFaceOf(req) }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, bases));
+    return persistedRuleAnswerOf(adjudicatePersistedPathRules(table, { tool: req.toolName, cwd: ctx.root, sessionId: ctx.sessionId, face: callPathFaceOf(req), ...(ctx.scopeIdentity !== undefined ? { scopeIdentity: ctx.scopeIdentity } : {}) }, { ...(tighten !== undefined ? { tighten } : {}), ...(allow !== undefined ? { allow } : {}) }, ctx.anchorsOf, ctx.leads));
 }
 export function orgRuleLane(cfg) {
     return {
@@ -141,8 +141,12 @@ export function createPermissionRuleLanes(cfg) {
         }
         if (view.unreadable !== undefined)
             skipped(view.unreadable, view.unreadableSources);
+        cfg.onRowsDropped(view.droppedRows);
         try {
-            const answer = strongestAnswer(judged.map(([n, grammar]) => judgeAgainst(view.rules.filter((r) => r.behavior !== "allow" || cfg.stripsAllow?.(r, req) !== true), { ...req, toolName: n }, grammar)));
+            const table = view.rules.filter((r) => r.behavior !== "allow" || cfg.stripsAllow?.(r, req) !== true);
+            const leads = judged.some(([, g]) => g === "path") ? await cfg.leads.resolve(bindPathRules(table.filter((r) => r.match === "path" || r.match === "subpath").map((r) => ({ parsed: r, ruleText: r.rule, rule: r })), (spec) => anchorsOf(spec.rule))) : NO_LEADS;
+            const scopeIdentity = await projectScopeIdentity(table, cfg.rootCanonical, cfg.leads);
+            const answer = strongestAnswer(judged.map(([n, grammar]) => judgeAgainst(table, { ...req, toolName: n }, grammar, leads, scopeIdentity)));
             return view.unreadable !== undefined && (answer === undefined || "segmentCoverage" in answer) ? { unreadable: true } : answer;
         }
         catch (err) {
@@ -151,20 +155,22 @@ export function createPermissionRuleLanes(cfg) {
             return { unreadable: true, reason: why };
         }
     };
-    const judgeAgainst = (table, req, grammar) => {
+    const anchorsOf = (rule) => persistedRowAnchors(rule.scope, cfg.chainTop);
+    const judgeAgainst = (table, req, grammar, leads, scopeIdentity) => {
         const liveCwd = cfg.liveCwd();
+        const scope = scopeIdentity !== undefined ? { scopeIdentity } : {};
         if (grammar === "path")
-            return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, liveCwd, home: cfg.home });
+            return pathRuleLaneAnswer(table, req, { root: cfg.root, sessionId: cfg.sessionId, anchorsOf, leads, ...scope });
         if (grammar === "name")
-            return persistedRuleAnswerOf(adjudicatePersistedNameRules(table, { tool: req.toolName, name: nameRuleSubjectOf(req.toolName, req.args), cwd: cfg.root, sessionId: cfg.sessionId }));
+            return persistedRuleAnswerOf(adjudicatePersistedNameRules(table, { tool: req.toolName, name: nameRuleSubjectOf(req.toolName, req.args), cwd: cfg.root, sessionId: cfg.sessionId, ...scope }));
         const command = req.args?.command;
         if (typeof command !== "string")
             return undefined;
         const execCwd = liveCwd !== undefined ? { execCwd: liveCwd } : {};
-        const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+        const verdict = adjudicatePersistedRules(table, { tool: req.toolName, command, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd, ...scope });
         if (verdict !== undefined)
             return persistedRuleAnswerOf(verdict);
-        const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd });
+        const coverage = segmentCoverageOf(command, { persisted: table }, { tool: req.toolName, cwd: cfg.root, sessionId: cfg.sessionId, ...execCwd, ...scope });
         return coverage !== undefined ? { segmentCoverage: coverage } : undefined;
     };
     const skipped = (why, sources) => (cfg.onDisclosure(why), cfg.onStoreUnreadable("call", sources), { unreadable: true });

package/dist/core/runner/persisted-path-rows.d.ts

@@ -3,14 +3,16 @@
  * per call).
  */
 import { type EffectivePermissionRules, type PermissionRuleStoreProvider } from "../permission-rule-provider.js";
-import type { PathRuleDenyRow } from "../../tools/fs/read-deny.js";
+import { type PathRuleBases } from "../permission-rule-model.js";
+import { type BoundPathRule, type HeadLeads } from "../path-rule-binding.js";
 import type { RunnerDeps } from "../runner-deps.js";
 /** The person's persisted PATH rows a leg's read face takes at prepare ({@link persistedPathRowsOf}). */
 export interface PersistedPathRows {
     /** Every live `Read(//dir/**)` allow row's directory (lexical, absolute): a standing yes to reads under it. */
     readonly readDirectories: readonly string[];
-    /** Every live face-keyed path DENY row (`Read(...)`, `Edit(...)`), as a deny-table row resolved at the task's bases. */
-    readonly denyRows: readonly PathRuleDenyRow[];
+    /** Every live face-keyed path DENY row (`Read(...)`, `Edit(...)`), bound at its anchors (a project row at its scope root,
+     *  the rest at the chain's top leg). */
+    readonly denyRows: readonly BoundPathRule[];
 }
 /**
  * The person's persisted PATH rows, read ONCE at prepare from the same store query the gate's lanes read per call: a
@@ -22,19 +24,28 @@ export interface PersistedPathRows {
  * rows. A read that failed (or did not answer in time) ⇒ no rows, and a partition the read could not read ⇒ none of ITS
  * rows (the partition that was read contributes its own): what could not be read is skipped for this run's tables — its
  * directories widen nothing and its deny rows judge nothing here — disclosed on the trace and announced to the person
- * (`onUnread`); the next prepare reads again, as it would for a row the store gained mid-run. A deny row whose
- * pattern needs a base the task cannot supply (`~/` with no declared home) is left to the per-call lane and disclosed.
+ * (`onUnread`); the next prepare reads again, as it would for a row the store gained mid-run. A deny row is anchored by
+ * its scope (`persistedRowAnchors`: a project row at its own scope root, a global / session row at the chain's top leg,
+ * `~/` at the top leg's home); one whose pattern needs an anchor the chain does not supply (`~/` with no declared home) is
+ * left to the per-call lane and disclosed.
  */
 export declare function persistedPathRowsOf(cfg: {
     provider: PermissionRuleStoreProvider | undefined;
     localOwnerDeclared: boolean;
     principal: string | undefined;
     sessionId: string;
+    /** The leg's own root: which project rows apply to this leg (either spelling of it — {@link projectScopeIdentity}). */
     root: string;
-    home: string | undefined;
+    rootCanonical: string | undefined;
+    /** The leg's resolution of locations (a project row's scope root, where it leads). */
+    leads: HeadLeads;
+    /** The anchors of the global / session rows and of `~/`: the chain's top leg's root and home. */
+    chainTop: PathRuleBases;
     onDisclosure: (message: string) => void;
     /** The person is told the store (or the named sources of it) was skipped ({@link ruleStoreUnreadableNotice}). */
     onUnread: (at: "prepare", sources?: EffectivePermissionRules["unreadableSources"]) => void;
+    /** The person is told rows were left out ({@link ruleRowsDroppedNotice}). */
+    onRowsDropped: (rows: EffectivePermissionRules["droppedRows"]) => void;
     /** The run's cut: a read that has not answered by then (or by the gate's await bound) reads as unreadable. */
     signal?: AbortSignal;
 }): Promise<PersistedPathRows>;
@@ -48,6 +59,16 @@ export declare function ruleStoreUnreadableNotice(onNotice: RunnerDeps["onNotice
     readonly sessionId: string;
     readonly runId: string;
 }): (at: "prepare" | "call", sources?: EffectivePermissionRules["unreadableSources"]) => void;
+/**
+ * The run's ONE `permission.rule_row_dropped` notice (audience user): the person's store served project-scoped rows whose
+ * scope root is not a complete absolute path, left out of the checks; minted by whichever read met them first (the
+ * prepare read of the path rows, or a call's own read on the rule lane), once per run. The sentence names no path; the
+ * rows (bounded) ride the detail. The trace keeps every read's line.
+ */
+export declare function ruleRowsDroppedNotice(onNotice: RunnerDeps["onNotice"], ids: {
+    readonly sessionId: string;
+    readonly runId: string;
+}): (rows: EffectivePermissionRules["droppedRows"]) => void;
 /** {@link persistedPathRowsOf} for one task's prepare: only where a read face mounts (hands), disclosed on the run's trace,
  *  cut by the run's own signals. `undefined` = nothing to read, returned synchronously: a run with no person's store (or
  *  no hands) gains no suspension point on its prepare. */
@@ -56,9 +77,12 @@ export declare function persistedPathRowsOfTask(t: {
     principal: string | undefined;
     sessionId: string;
     root: string;
-    home: string | undefined;
+    rootCanonical: string | undefined;
+    leads: HeadLeads;
+    chainTop: PathRuleBases;
     taskId: string;
     handsEnabled: boolean;
     signals: readonly AbortSignal[];
     onUnread: (at: "prepare", sources?: EffectivePermissionRules["unreadableSources"]) => void;
+    onRowsDropped: (rows: EffectivePermissionRules["droppedRows"]) => void;
 }): Promise<PersistedPathRows> | undefined;