@sema-agent/core 7.45.0 → 7.47.0

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;

package/dist/core/runner/persisted-path-rows.js

@@ -1,7 +1,6 @@
 import { ownerStoreOf } from "../permission-rule-provider.js";
-import { PATH_RULE_FACES, READ_RULE_TOOL, eligiblePersisted, isUsablePathBase, ruleBasesNeeded } from "../permission-rule-model.js";
-import { isAbsolutePathForm, pathFamilyOf } from "../../tools/fs/safety.js";
-import { pathRuleDenyRowOf } from "../permission-rules.js";
+import { PATH_RULE_FACES, READ_RULE_TOOL, eligiblePersisted } from "../permission-rule-model.js";
+import { bindPathRules, persistedRowAnchors, projectScopeIdentity } from "../path-rule-binding.js";
 import { inlineUntrusted } from "../untrusted-text.js";
 import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, gateWaitFailureOf, withGateTimeout } from "../gate-bounded-await.js";
 import { thrownText } from "../thrown-value.js";
@@ -21,11 +20,11 @@ export async function persistedPathRowsOf(cfg) {
     }
     if (view.unreadable !== undefined)
         skipped(cfg, view.unreadable, view.unreadableSources);
-    const call = { tool: READ_RULE_TOOL, cwd: cfg.root, sessionId: cfg.sessionId };
-    const bases = { root: cfg.root, ...(cfg.home !== undefined && isAbsolutePathForm(cfg.home) ? { home: cfg.home } : {}) };
-    const family = pathFamilyOf(bases);
+    cfg.onRowsDropped(view.droppedRows);
+    const scopeIdentity = await projectScopeIdentity(view.rules, cfg.rootCanonical, cfg.leads);
+    const call = { tool: READ_RULE_TOOL, cwd: cfg.root, sessionId: cfg.sessionId, ...(scopeIdentity !== undefined ? { scopeIdentity } : {}) };
     const readDirectories = [];
-    const denyRows = [];
+    const denySpecs = [];
     for (const rule of view.rules) {
         if (rule.status !== "live")
             continue;
@@ -37,12 +36,15 @@ export async function persistedPathRowsOf(cfg) {
         const faces = PATH_RULE_FACES[rule.tool]?.deny;
         if (rule.behavior !== "deny" || faces === undefined || (rule.match !== "path" && rule.match !== "subpath") || !eligiblePersisted(rule, { ...call, tool: rule.tool }, "deny"))
             continue;
-        const missing = ruleBasesNeeded(rule).filter((b) => !isUsablePathBase(b === "cwd" ? bases.root : bases[b], family));
-        if (missing.length > 0) {
-            cfg.onDisclosure(`the persisted deny rule ${inlineUntrusted(rule.rule, 200)} needs a ${missing.join(" / ")} base this task does not declare — the shell's file commands and the search tools do not judge it on this leg`);
+        denySpecs.push({ parsed: rule, ruleText: rule.rule, faces, rule });
+    }
+    const denyRows = [];
+    for (const row of bindPathRules(denySpecs, (spec) => persistedRowAnchors(spec.rule.scope, cfg.chainTop))) {
+        if (row.unanchored !== undefined) {
+            cfg.onDisclosure(`the persisted deny rule ${inlineUntrusted(row.rule, 200)} needs a ${row.unanchored.join(" / ")} base this task does not declare — the shell's file commands and the search tools do not judge it on this leg`);
             continue;
         }
-        denyRows.push(pathRuleDenyRowOf({ parsed: rule, ruleText: rule.rule, faces }, bases));
+        denyRows.push(row);
     }
     return { readDirectories, denyRows };
 }
@@ -68,6 +70,20 @@ export function ruleStoreUnreadableNotice(onNotice, ids) {
         deliverEngineNotice(onNotice, { code: "permission.rule_store_unavailable", message: SKIPPED_STORE_SENTENCE[at](which), detail: { at, sessionId: ids.sessionId, runId: ids.runId } });
     };
 }
+export function ruleRowsDroppedNotice(onNotice, ids) {
+    let sent = false;
+    return (rows) => {
+        if (sent || rows === undefined || rows.length === 0)
+            return;
+        sent = true;
+        const one = rows.length === 1;
+        deliverEngineNotice(onNotice, {
+            code: "permission.rule_row_dropped",
+            message: `${rows.length} of your persisted permission rule rows ${one ? "is" : "are"} scoped to a project directory that is not written as a complete absolute path, so ${one ? "it takes" : "they take"} no part in this run's checks — a deny or ask row among them protects nothing. Rewrite ${one ? "it" : "them"} with the project's full path, or remove ${one ? "it" : "them"} (this notice's detail names ${one ? "it" : "them"}).`,
+            detail: { rows: rows.slice(0, 8).map((r) => ({ rule: inlineUntrusted(r.rule, 200), scopeRoot: inlineUntrusted(r.scopeRoot, 200) })), count: rows.length, sessionId: ids.sessionId, runId: ids.runId },
+        });
+    };
+}
 function readsPersistedPathRows(provider, principal, localOwnerDeclared) {
     return provider.partitions.durable && ((principal !== undefined && principal !== "") || localOwnerDeclared);
 }
@@ -81,9 +97,12 @@ export function persistedPathRowsOfTask(t) {
         principal: t.principal,
         sessionId: t.sessionId,
         root: t.root,
-        home: t.home,
+        rootCanonical: t.rootCanonical,
+        leads: t.leads,
+        chainTop: t.chainTop,
         onDisclosure: (message) => emitTrace(t.deps.tracer, () => ({ kind: "permission.rule_store_unreadable", version: 1, taskId: t.taskId, message, ts: Date.now() })),
         onUnread: t.onUnread,
+        onRowsDropped: t.onRowsDropped,
         signal: AbortSignal.any([...t.signals]),
     });
 }

package/dist/core/runner/prepare-ask-lane.d.ts

@@ -1,3 +1,4 @@
+import type { CallTargetStamp } from "../effective-path-target.js";
 import type { AgentTool } from "../../internal/harness.js";
 import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import type { AutoModeDenialTracker } from "../auto-mode.js";
@@ -30,6 +31,9 @@ export interface PrepareAskLaneInput {
     handsCwdRef: CwdRef | undefined;
     /** borrowed-readonly — the root the hand tools resolve root-relative spellings against, or undefined (hands-less). */
     handsRoot: string | undefined;
+    /** borrowed-readonly — the leg's target-reading stamp ({@link CallTargetStamp}), or undefined (hands-less): the request a
+     *  policy judges carries a reading of its own args. Called at RUN time; a seat with nothing to stamp answers undefined. */
+    stampCallTarget: CallTargetStamp | undefined;
     /** borrowed-readonly — the run's advertised-writable-directory seat, or undefined (hands-less / nothing advertised). `roots` is read at RUN time, never captured: it is the fence's own admitted list and the write gate's exemption domain must be that same list. Not written here. */
     advertisedWritableDirs: Pick<AdvertisedWritableDirs, "roots"> | undefined;
     /** borrowed-readonly — the shared mount roster; read at RUN time by the approval-preview projection (alias-aware

package/dist/core/runner/prepare-ask-lane.js

@@ -59,14 +59,16 @@ function resolveApprovalPreview(tools, toolName, args) {
     }
 }
 export function prepareAskLane(input) {
-    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, handsRoot, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, grantBindingOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash, grantReadRoot } = input;
+    const { gateMachineryActive, abortController, effectivePolicy, budgetSnapshot, handsCwdRef, handsRoot, stampCallTarget, advertisedWritableDirs, tools, inheritedUnavailableAsks, inheritedAskGrants, onAsk, humanReviewRef, now, ruleOffersOf, grantBindingOf, askSourceIdentity, riskAxesOf, autoModeDenialTracking, spec, deps, sessionId, runId, hooks, hookTimeoutMs, notifyOwnHookCrash, grantReadRoot } = input;
     if (!gateMachineryActive)
         return { askLane: undefined };
     const composedCallSignal = (callSignal) => composeCallSignal(abortController.signal, callSignal);
     const adjudicate = effectivePolicy
         ? (req, callSignal) => {
             const signal = composedCallSignal(callSignal);
-            return raceAbort(Promise.resolve(effectivePolicy.check({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}), ...(handsRoot !== undefined ? { root: handsRoot } : {}), ...advertisedWritableRootsSeat(advertisedWritableDirs) }, signal)), signal, () => ({
+            const stampedReq = () => ({ ...req, budget: budgetSnapshot, ...(handsCwdRef !== undefined ? { cwd: handsCwdRef.current } : {}), ...(handsRoot !== undefined ? { root: handsRoot } : {}), ...advertisedWritableRootsSeat(advertisedWritableDirs) });
+            const withReading = stampCallTarget?.(stampedReq(), signal);
+            return raceAbort(withReading === undefined ? Promise.resolve(effectivePolicy.check(stampedReq(), signal)) : withReading.then((r) => effectivePolicy.check(r, signal)), signal, () => ({
                 action: "deny",
                 message: "policy check aborted (task timed out or cancelled)",
             }));

package/dist/core/runner/prepare-execution-env.d.ts

@@ -1,6 +1,6 @@
 import type { ExecutionEnv } from "../../internal/harness.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
-import type { PrepareResume, RollbackStack, RunInternals } from "./contracts.js";
+import type { ChildPlacement, PrepareResume, RollbackStack, RunInternals } from "./contracts.js";
 /**
  * The ONE reference to a factory-minted env, shared by the driver's detach guard and the rollback entry
  * this phase registers. `current` is the minted env, or `undefined` when the run has none / after the
@@ -19,7 +19,7 @@ export interface PrepareExecutionEnvInput {
     spec: Pick<TaskSpec, "taskId">;
     /** borrowed-readonly — the trusted spawn-side requests: the explicit cwd (a contract), the isolation
      *  request and the parent's cwd (both threaded to the factory ctx). */
-    internals: Pick<RunInternals, "requestedCwd" | "isolation" | "parentCwd"> | undefined;
+    internals: Pick<RunInternals, "requestedCwd" | "isolation" | "parentCwd" | "callerRoot" | "worktreeOffered"> | undefined;
     /** borrowed-readonly — the resume leg, read only to refuse an explicit cwd that a checkpoint workspace
      *  restore would overrule. */
     resume: Pick<PrepareResume, "workspaceHandle"> | undefined;
@@ -50,5 +50,8 @@ export interface PrepareExecutionEnvResult {
     /** borrowed-readonly — the INITIAL task root (the workspace-restore phase may re-root it and returns the
      *  settled root under the NEW name `taskRootFinal`). */
     taskRootInitial: string;
+    /** borrowed-readonly — where a CHILD landed against where its caller asked ({@link childPlacementOnLeg}); absent on a leg no
+     *  delegation caller placed (no `callerRoot`). */
+    placement: ChildPlacement | undefined;
 }
 export declare function prepareExecutionEnv(input: PrepareExecutionEnvInput): Promise<PrepareExecutionEnvResult>;

package/dist/core/runner/prepare-execution-env.js

@@ -1,7 +1,7 @@
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasDestroy } from "../remote-env.js";
 import { announceMalformedCapabilities } from "./env-capability-census.js";
-import { deploymentCanRerootChild } from "./child-tree.js";
+import { childPlacementOnLeg, deploymentCanRerootChild, worktreeNotHonored } from "./child-tree.js";
 import { settleTeardownLeg } from "./teardown-bounded.js";
 export async function prepareExecutionEnv(input) {
     const { deps, spec, internals, resume, placementRootResolved, sessionId, forgetOnThrow, rollback } = input;
@@ -69,8 +69,15 @@ export async function prepareExecutionEnv(input) {
         }
     }
     const handsEnabled = ownedEnv !== undefined || deps.executionEnv !== undefined;
-    const taskRootInitial = internals?.isolation === "worktree" || internals?.requestedCwd !== undefined || !deps.rootPath ? executionEnv.cwd : deps.rootPath;
-    return { executionEnv, ownedEnvSeat, ownedEnvObservedAt, handsEnabled, taskRootInitial };
+    const taskRootInitial = internals?.isolation === "worktree" || internals?.requestedCwd !== undefined || internals?.worktreeOffered === true || !deps.rootPath ? executionEnv.cwd : deps.rootPath;
+    const placement = internals?.callerRoot === undefined ? undefined : await childPlacementOnLeg(executionEnv, { ...internals, callerRoot: internals.callerRoot }, taskRootInitial);
+    if (internals?.worktreeOffered === true && placement === "caller_tree") {
+        await settleTeardownLeg(() => forgetOnThrow(), "forgetOnThrow (worktree-not-honored leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+        await settleTeardownLeg(() => (ownedEnv && hasDestroy(ownedEnv) ? ownedEnv.destroy() : undefined), "ownedEnv.destroy (worktree-not-honored leg)", (err) => deps.onError?.(err, { phase: "config", sessionId }));
+        ownedEnvSeat.current = undefined;
+        throw worktreeNotHonored(executionEnv.cwd);
+    }
+    return { executionEnv, ownedEnvSeat, ownedEnvObservedAt, handsEnabled, taskRootInitial, placement };
 }
 function cwdConflictsRestoreError(requestedCwd) {
     const e = new Error(`RunInternals.requestedCwd ("${requestedCwd}") cannot be combined with a checkpoint workspace restore — ` +

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -24,6 +24,7 @@
  * gate outcome; nothing here changes a word, a source or an order — the stations are moved, not re-adjudicated.
  */
 import type { AgentHarness, AgentTool } from "../../internal/harness.js";
+import type { CallTargetStamp } from "../effective-path-target.js";
 import type { AskClass } from "../ask-class.js";
 import type { Arbitration, ToolMarkSource } from "../ask-origin.js";
 import { type PermissionModeController } from "../mode-policy.js";
@@ -152,6 +153,8 @@ export interface PrepareGateStationsInput {
     /** borrowed-readonly — the hand's live tracked cwd, or undefined; `current` is read per screening / per post seat. Not
      *  written here. */
     handsCwdRef: CwdRef | undefined;
+    /** borrowed-readonly — the leg's target-reading stamp, or undefined (hands-less): the gate stamps its request with it. */
+    stampCallTarget: CallTargetStamp | undefined;
     /** borrowed-readonly — the leg's read-deny table in force, read at a release: the active built-in tiers and the rows
      *  beside them (the deployment's and the task's patterns, the read-face rule rows). Empty ⇒ no table. */
     readDenyInForce: () => {

package/dist/core/runner/prepare-gate-stations.js

@@ -46,7 +46,7 @@ export function maybeHumanRejectionHalt(input) {
     };
 }
 export function prepareGateStations(input) {
-    const { askLane, parkAsk, tools, toolRosterDeltas, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, writeProtectionCheck, shellReadCheck, readFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, askRoute, permissionMode, toolMarkSources, a2aIsolatePeers, ancestorArbitrations, runId, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash, frameSettlement, seatInputsFor } = input;
+    const { askLane, parkAsk, tools, toolRosterDeltas, toolEffects, deps, toolCallGateArmedRef, effectivePolicy, hooks, egressTools, irreversibleTools, spec, complianceDenies, harness, blockedToolCalls, inheritedAskGrants, inheritedUnavailableAsks, foldAskClasses, ancestorSandboxAdmissions, preToolContexts, gateOutcomes, batchHaltRef, blockedTracked, hookIdentity, reminderMark, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, stampCallTarget, hookEnvFace, writeProtectionCheck, shellReadCheck, readFace, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, askRoute, permissionMode, toolMarkSources, a2aIsolatePeers, ancestorArbitrations, runId, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash, frameSettlement, seatInputsFor } = input;
     const gatePreToolUse = ownGatePreToolUse !== undefined ? (name, args, ctx) => ownGatePreToolUse(name, args, { ...ctx, permissionMode: permissionMode.observed }) : undefined;
     const releasesAnnounced = new Map();
     const onModeReleased = (info) => {
@@ -120,6 +120,7 @@ export function prepareGateStations(input) {
                         ...(gatePreToolUse !== undefined ? { preToolUse: gatePreToolUse } : {}),
                         hookTimeoutMs,
                         ...(handsCwdRef !== undefined ? { trackedCwd: () => handsCwdRef.current } : {}),
+                        ...(stampCallTarget !== undefined ? { stampCallTarget } : {}),
                         ...(hookEnvFace !== undefined ? { hookEnv: hookEnvFace } : {}),
                         toolFaceOf: (name) => toolCallFaceOf(toolRosterDeltas.current, name === e.toolName ? called.toolName : name),
                         adjudicate,

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -1,6 +1,7 @@
 import { type BeforeWriteHook, type CwdRef, type PathRuleDenyRow, type ContainmentFace } from "../../tools/fs/index.js";
 import { type ReadFileState } from "../../tools/fs/safety.js";
 import { type PlacedReadDenyMatcher } from "../../tools/fs/read-deny-home.js";
+import type { HeadLeads } from "../path-rule-binding.js";
 import { type ShellReadAdmission, type ShellReadCheck } from "../../tools/fs/shell-read-check.js";
 import type { ShellReadBoundary } from "../../tools/fs/shell-read-judge.js";
 import type { RunnerDeps, ShellGateDoctrine, TaskSpec } from "../types.js";
@@ -54,9 +55,12 @@ export interface PrepareHandsReadFaceInput {
     /** borrowed-readonly — the registry scope (`internals?.registryScope ?? spec.principal ??
      *  "default"`, computed in the driver); the band's task-registry scope. */
     taskScope: string;
-    /** borrowed-readonly — the deny tables' permission-rule rows: the path deny rules of the leg's caller policy and of every
-     *  ancestor's (`toolPolicyPathDenyRules`); joined to the read face's matcher and to the shell station's write face. */
-    pathDenyRules: readonly PathRuleDenyRow[];
+    /** borrowed-readonly — the deny tables' permission-rule rows: the face-keyed path deny rules of the leg's caller policy and
+     *  of every ancestor's, each bound where it was installed (`toolPolicyPathRules`), and the person's deny rows; joined to the
+     *  read face's matcher and to the shell station's write face. */
+    denyRuleRows: readonly PathRuleDenyRow[];
+    /** borrowed-readonly — the leg's one resolution of where rule heads lead (the rows' twins, the same the gate's lanes read). */
+    headLeads: HeadLeads;
     /** borrowed-readonly — the two judges a shell command's write targets meet for the mode's file-command placement: the
      *  leg's write-protection judge (read per judgment — it is compiled at the manifest phase, before any gate is mounted)
      *  and the chain's write-target guard (`toolPolicyWriteTargetGuard`). Absent ⇒ neither (a standalone phase drive). */
@@ -93,7 +97,7 @@ export interface PrepareHandsReadFaceInput {
      *  object (R-4: `deps.onError?.()` keeps its receiver; a new deps read must widen this Pick).
      *  `readDenyBuiltinTiers`/`readDenyBuiltinExclude` are SNAPSHOTTED before the first await that
      *  precedes the toolkit compile (the caller retains these arrays by reference). */
-    deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "readFace" | "writeFace" | "permissionRuleStore" | "hands">;
+    deps: Pick<RunnerDeps, "onError" | "onNotice" | "tracer" | "readDenyPatterns" | "readDenyBuiltinTiers" | "readDenyBuiltinExclude" | "agentConfigDir" | "readFace" | "writeFace" | "permissionRuleStore" | "hands">;
     /** borrowed-readonly — the trusted spawn-side seats the band forwards: the finished-command
      *  notification lane, the mid-flight detach hub, and the Runner's per-session
      *  read-state seats (absent on a standalone prepare ⇒ the transcript-replay rung covers alone). */

package/dist/core/runner/prepare-hands-readface.js

@@ -2,13 +2,13 @@ import { emitTrace } from "../trace.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { bashReversibilityProbe, activeReadDenyBuiltinTiers, readDenyBuiltinConfigOf, compileReadDeny, compileWriteDeny, withRuleRowsWhereTheyLead, readDenySeat, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, inheritSessionReadFileState, backgroundOutputReadExemption, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { bashReversibilityProbe, activeReadDenyBuiltinTiers, readDenyBuiltinConfigOf, compileReadDeny, compileWriteDeny, rowsWhereTheyLead, readDenySeat, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, inheritSessionReadFileState, backgroundOutputReadExemption, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
 import { resolveKey, sha256 } from "../../tools/fs/safety.js";
-import { placeReadDenyAtHome, whereItsAnsweredPrefixLeads } from "../../tools/fs/read-deny-home.js";
+import { placeReadDenyAtHome } from "../../tools/fs/read-deny-home.js";
 import { createShellOverflowSpoolFence } from "../../tools/fs/fs-shared.js";
 import { createShellReadStation } from "../../tools/fs/shell-read-check.js";
 import { composeReadChecks, createFileReadStation } from "../../tools/fs/file-read-check.js";
-import { readTargetToolNames } from "../tool-registry.js";
+import { isShellFaceToolName, predictMountedToolNames, readTargetToolNames } from "../tool-registry.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
@@ -203,6 +203,7 @@ export async function prepareHandsMount(input) {
         const handsIncludeShell = !(executionEnv instanceof StubExecutionEnv);
         const handsReadOnly = spec.handsReadOnly === true;
         backgroundTaskToolsActive = handsIncludeShell && !handsReadOnly && hasBackgroundShell(executionEnv);
+        const shellFaceHere = [...predictMountedToolNames(new Set(backgroundTaskToolsActive ? ["hands", "backgroundTasks"] : ["hands"]))].filter(isShellFaceToolName);
         wsSnapshot = resume !== undefined || !(handsIncludeShell && !handsReadOnly) ? undefined : await session.getWorkspaceState().catch(() => undefined);
         rebaseWsPath = (p) => (wsSnapshot === undefined || wsSnapshot.taskRoot === rootCanonical ? p : rebaseWorkspacePath(p, wsSnapshot.taskRoot, rootCanonical));
         if (handsIncludeShell && !handsReadOnly) {
@@ -220,8 +221,8 @@ export async function prepareHandsMount(input) {
         const seedReadFaceSection = resume?.seed.readFace;
         const readDenyAdditions = [...(deps.readDenyPatterns ?? []), ...(spec.readDenyPatterns ?? []), ...(seedReadFaceSection?.denyEntries ?? [])];
         const readDenyBuiltinCfg = readDenyBuiltinConfigOf({ tiers: deps.readDenyBuiltinTiers, exclude: deps.readDenyBuiltinExclude });
-        const pathDenyRules = await withRuleRowsWhereTheyLead(input.pathDenyRules, (head) => whereItsAnsweredPrefixLeads(executionEnv, head));
-        const readDenyPlacement = await placeReadDenyAtHome(executionEnv, (homes, linked) => compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg, pathDenyRules, homes, linked));
+        const denyRuleRows = rowsWhereTheyLead(input.denyRuleRows, await input.headLeads.resolve(input.denyRuleRows));
+        const readDenyPlacement = await placeReadDenyAtHome(executionEnv, (homes, linked) => compileReadDeny(readDenyAdditions, "readDenyPatterns", readDenyBuiltinCfg, denyRuleRows, homes, linked), undefined, undefined, deps.agentConfigDir);
         readDenyMatcher = readDenyPlacement.matcher;
         readDenyBuiltinTiersActive = activeReadDenyBuiltinTiers(readDenyBuiltinCfg);
         readDenyAdditionsNormalized = compileReadDeny(readDenyAdditions, "readDenyPatterns", { tiers: [] }).entries;
@@ -291,7 +292,7 @@ export async function prepareHandsMount(input) {
                 }
                 : undefined;
         const denySeat = readDenySeat(readDenyMatcher);
-        const writeDeny = compileWriteDeny(pathDenyRules);
+        const writeDeny = compileWriteDeny(denyRuleRows);
         const writeDenySeat = writeDeny.ruleRows.length > 0 ? { writeDenyMatch: (p) => writeDeny.matchPath(p)?.pattern ?? null } : {};
         const shellReadBoundary = () => ({
             roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
@@ -307,7 +308,7 @@ export async function prepareHandsMount(input) {
         if (handsIncludeShell) {
             const spoolFence = handsReadOnly ? createShellOverflowSpoolFence(executionEnv) : undefined;
             const readonlyBoundary = () => spoolFence !== undefined ? { roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical], cwd: rootCanonical, ...denySeat, ...writeDenySeat, alsoInside: spoolFence } : undefined;
-            shellReadTools = new Set(handsReadOnly ? ["Bash"] : backgroundTaskToolsActive ? ["Bash", "Monitor"] : ["Bash"]);
+            shellReadTools = new Set(shellFaceHere);
             shellReadStation = createShellReadStation({
                 env: executionEnv,
                 tools: shellReadTools,
@@ -334,7 +335,7 @@ export async function prepareHandsMount(input) {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
             additionalReadRoots: additionalReadRootsCanonical,
             ...(readDenyAdditions.length > 0 ? { readDenyPatterns: readDenyAdditions } : {}),
-            ...(pathDenyRules.length > 0 ? { pathDenyRules } : {}),
+            ...(denyRuleRows.length > 0 ? { pathDenyRules: denyRuleRows } : {}),
             readDenyHomes: readDenyPlacement.homes,
             readDenyHomeLinks: readDenyPlacement.linked,
             ...(readDenyBuiltinCfg.tiers !== undefined ? { readDenyBuiltinTiers: readDenyBuiltinCfg.tiers } : {}),
@@ -400,9 +401,8 @@ export async function prepareHandsMount(input) {
                 if (seatOwned)
                     shellGatedTools.add(name);
             };
-            installShellSeat("Bash");
-            if (backgroundTaskToolsActive)
-                installShellSeat("Monitor");
+            for (const name of shellFaceHere)
+                installShellSeat(name);
         }
     }
     return {