@sema-agent/core 7.45.0 → 7.47.0

package/dist/core/gate-lanes.js

@@ -1,3 +1,4 @@
+import { withArgsReading } from "./effective-path-target.js";
 import { attestClassifierDenyCause, classifierDenyCauseOf, decisionText, refuseOutOfContractDecision } from "./tool-policy.js";
 import { arbitrateByMode, classifyAsk, fileCommandOptionsSentence, persistedRuleMandateOf, ruleClearanceOf, safetyAxisOf, stampAskOrigin } from "./ask-origin.js";
 import { classifierParseFailureDenyMessage, denialLimitFallbackMessage, rungDidNotRule, unarmedWindow } from "./auto-mode.js";
@@ -16,7 +17,7 @@ import { callFaceSeat } from "./tool-roster.js";
 import { heldBy, wireOf } from "./tool-name-readings.js";
 import { asksUnstated, modeAcceptsFileCommand, permissionSeatAt, unstatedAskMessage } from "./mode-policy.js";
 import { ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON } from "./permission-rule-org.js";
-import { exitGate } from "./runner/gate-exit.js";
+import { exitGate, passAskFace } from "./runner/gate-exit.js";
 import { readOrgRuleLane, readPersistedRuleLane } from "./rule-lane-reads.js";
 import { traceHookCrash } from "./gate-crash-trace.js";
 import { createGateDeadline, awaitWriteProtectionJudgment, withGateTimeout } from "./gate-bounded-await.js";
@@ -51,6 +52,7 @@ export async function runGateLanes(pass) {
         ...(input.toolMarkSources !== undefined ? { toolMarkSources: input.toolMarkSources } : {}),
         ...(input.a2aIsolatePeers === true ? { a2aIsolatePeers: true } : {}),
         ...(readFaceNow !== undefined ? { readFace: readFaceNow } : {}),
+        askFace: passAskFace(pass),
     });
     const classifyStanding = (unstamped, facts) => (pass.askClassification = classifyAsk(unstamped, facts));
     let orgTightenCount = 0;
@@ -118,7 +120,8 @@ export async function runGateLanes(pass) {
     pass.decision = orgAnswer.decision;
     const ruleCallUnreadableOf = (lane) => lane?.unreadable === true && lane.reason !== undefined;
     const readPersistedRules = (req) => readPersistedRuleLane(input.persistedRules, req, input.abortSignal);
-    const laneReq = { ...pass.req, ...(pass.policyRewrite !== undefined ? { args: pass.policyRewrite } : {}) };
+    const reread = pass.policyRewrite !== undefined ? withArgsReading(pass.req, pass.policyRewrite, pass.callSignal ?? input.abortSignal) : undefined;
+    const laneReq = reread !== undefined ? await reread : { ...pass.req, ...(pass.policyRewrite !== undefined ? { args: pass.policyRewrite } : {}) };
     const laneAnswer = input.persistedRules !== undefined && wireOf("lanes.persistedLaneSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME ? await readPersistedRules(laneReq) : undefined;
     {
         const tightened = applyPersistedTightening(pass.decision, laneAnswer);
@@ -139,6 +142,8 @@ export async function runGateLanes(pass) {
         if (pass.policyRewrite !== undefined) {
             pass.currentInput = pass.policyRewrite;
             pass.req.args = pass.policyRewrite;
+            if (laneReq.targetReading !== undefined)
+                pass.req.targetReading = laneReq.targetReading;
         }
         const ruleMayClear = () => ruleClearanceOf(pass.decision.action === "ask" ? pass.decision : undefined, mandateMarksNow()).ruleMayClear;
         const classMayClear = () => pass.decision.action === "ask" && classifyAsk(pass.decision, askOriginFacts(orgAnswer.org, ruleCallUnreadableOf(laneAnswer))).row.ruleMayClear;
@@ -576,8 +581,10 @@ export async function runGateLanes(pass) {
                         break;
                     }
                     let editRuleCallUnreadable = false;
+                    const editReread = withArgsReading(pass.req, editArgs, callSignal ?? input.abortSignal);
+                    const editLaneReq = editReread !== undefined ? await editReread : { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
                     if (input.persistedRules !== undefined && wireOf("lanes.persistedEditSkip", pass.req) !== ASK_USER_QUESTION_TOOL_NAME) {
-                        const editLane = await readPersistedRules({ toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) });
+                        const editLane = await readPersistedRules(editLaneReq);
                         editRuleCallUnreadable = ruleCallUnreadableOf(editLane);
                         const editTightened = applyPersistedTightening(recheck, editLane);
                         recheck = editTightened.decision;
@@ -588,7 +595,7 @@ export async function runGateLanes(pass) {
                             break;
                         }
                     }
-                    const editSkillRefusal = skillRowRefusal(input.skillGrants, { toolName, args: editArgs, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) });
+                    const editSkillRefusal = skillRowRefusal(input.skillGrants, editLaneReq);
                     if (editSkillRefusal !== undefined) {
                         editDenied = editSkillRefusal;
                         pass.deniedBy = "policy";

package/dist/core/gate-outcome.d.ts

@@ -343,9 +343,11 @@ export type GateDisposition = {
 /**
  * A permission MODE released a surviving ask — the allowed disposition's account of the question it did not put
  * to anyone: the mode, the disclosed class word (`askClass`, the first member of the folded set in `ASK_CLASSES`
- * order — one of {@link RELEASABLE_ASK_CLASSES}), the whole set, and the origin / mandate words the card would
+ * order — one of {@link releasableAskClassesFor} on the call's face), the whole set, and the origin / mandate words the card would
  * have shown. `reason` is a member of {@link import("./ask-origin.js").MODE_RELEASE_REASONS} (`isModeReleaseReason`):
- * `"rule_unreadable"` marks a release over a rule the call could not be read against; absent, the release names none.
+ * `"rule_unreadable"` marks a release over a rule the call could not be read against, `"write_protection_unresolved"` a release (the
+ * shell face) over a write target the judge could not resolve; absent, the release names none. The record carries no face, so the
+ * screen asks that SOME face releases the class.
  */
 export interface ModeRelease {
     mode: PermissionMode;

package/dist/core/gate-outcome.js

@@ -1,4 +1,4 @@
-import { isAskClass, isAskOrigin, isModeReleaseReason, isPermissionMode, RELEASABLE_ASK_CLASSES } from "./ask-origin.js";
+import { isAskClass, isAskOrigin, isModeReleaseReason, isPermissionMode, ASK_FACES, releasableAskClassesFor } from "./ask-origin.js";
 import { isAutoModeFallbackCause } from "./auto-mode.js";
 export const SETTLEMENT_KINDS = Object.freeze([
     "human_allowed",
@@ -139,7 +139,7 @@ export function screenGateOutcome(g) {
             defects.push("I7: a mode release carries no settlement — nobody answered the ask it released");
         if (r.mode !== "bypassPermissions")
             defects.push(`I7: a mode release names mode "${String(r.mode)}" — only bypassPermissions releases`);
-        if (!isAskClass(r.askClass) || !RELEASABLE_ASK_CLASSES.includes(r.askClass))
+        if (!isAskClass(r.askClass) || !ASK_FACES.some((face) => releasableAskClassesFor(face).includes(r.askClass)))
             defects.push(`I7: released.askClass "${String(r.askClass)}" is not a releasable class`);
         if (!Array.isArray(r.classes) || r.classes.length === 0 || !r.classes.every((c) => isAskClass(c)))
             defects.push("I7: released.classes must be a non-empty list of ask classes");

package/dist/core/governance-codes.d.ts

@@ -136,7 +136,7 @@ export type NoticeAudience = "user" | "operator";
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
  * so the catalog is not written a second time here and the two cannot drift.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.allowed_tool_not_granted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "route.tool_call_id_folded", "context.tool_turn_repaired", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "task.tool_turn_incomplete", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed", "instructions.source_changed", "session.records_skipped", "memory.layer_locked_legacy", "server.model_unreachable"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.rule_row_dropped", "permission.allowed_tool_not_granted", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "route.tool_call_id_folded", "context.tool_turn_repaired", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "task.tool_turn_incomplete", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed", "instructions.source_changed", "session.records_skipped", "memory.layer_locked_legacy", "server.model_unreachable"];
 /** A catalogued code (see {@link ENGINE_NOTICE_CODES}); {@link NOTICE_MINTER} says who mints it. NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */
@@ -181,6 +181,7 @@ declare const NOTICE_AUDIENCE_TABLE: {
     readonly "permission.ask_released_by_mode": "user";
     readonly "permission.read_deny_unapplied": "user";
     readonly "permission.rule_store_unavailable": "user";
+    readonly "permission.rule_row_dropped": "user";
     readonly "permission.allowed_tool_not_granted": "user";
     readonly "memory.capture_opted_out": "user";
     readonly "memory.capture_optout_unpersisted": "user";
@@ -295,6 +296,7 @@ declare const NOTICE_MINTER_TABLE: {
     readonly "permission.ask_released_by_mode": "engine";
     readonly "permission.read_deny_unapplied": "engine";
     readonly "permission.rule_store_unavailable": "engine";
+    readonly "permission.rule_row_dropped": "engine";
     readonly "permission.allowed_tool_not_granted": "engine";
     readonly "peer.inbound_disposition": "engine";
     readonly "peer.held_settled": "engine";

package/dist/core/governance-codes.js

@@ -144,6 +144,7 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
     "permission.ask_released_by_mode",
     "permission.read_deny_unapplied",
     "permission.rule_store_unavailable",
+    "permission.rule_row_dropped",
     "permission.allowed_tool_not_granted",
     "peer.inbound_disposition",
     "peer.held_settled",
@@ -229,6 +230,7 @@ const NOTICE_AUDIENCE_TABLE = {
     "permission.ask_released_by_mode": "user",
     "permission.read_deny_unapplied": "user",
     "permission.rule_store_unavailable": "user",
+    "permission.rule_row_dropped": "user",
     "permission.allowed_tool_not_granted": "user",
     "memory.capture_opted_out": "user",
     "memory.capture_optout_unpersisted": "user",
@@ -324,6 +326,7 @@ const NOTICE_MINTER_TABLE = {
     "permission.ask_released_by_mode": "engine",
     "permission.read_deny_unapplied": "engine",
     "permission.rule_store_unavailable": "engine",
+    "permission.rule_row_dropped": "engine",
     "permission.allowed_tool_not_granted": "engine",
     "peer.inbound_disposition": "engine",
     "peer.held_settled": "engine",

package/dist/core/hooks.d.ts

@@ -1,6 +1,7 @@
 import type { ActorAssertion, DocumentContent, ImageContent, TextContent } from "../internal/llm.js";
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
 import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallFace, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
+import type { CallTargetStamp } from "./effective-path-target.js";
 import type { GateOutcome } from "./gate-outcome.js";
 import { type PreToolUseScreening } from "./runner/gate-exit.js";
 export { normalizeOrgGateVerdict, normalizePersistedRuleHit } from "./rule-lane-reads.js";
@@ -1176,6 +1177,8 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
      *  starting directory and answer for a run that has since `cd`ed. Absent ⇒ the contexts carry no
      *  `cwd`, which is the honest answer for a run with no tracked one. */
     trackedCwd?: () => string | undefined;
+    /** The leg's target-reading stamp, applied where the gate's request is minted over the final args (a rewrite re-reads it: `withArgsReading`). */
+    stampCallTarget?: CallTargetStamp;
     /** The read-only env capability face put on every {@link HookToolContext} this gate call
      *  builds ({@link HookEnvCapabilities}). Built ONCE per task by the runner (after the env is minted) and
      *  passed through unchanged; omitted when the deployment wired no execution environment. */

package/dist/core/path-rule-binding.d.ts

@@ -0,0 +1,65 @@
+import { type PathRuleBase, type PathRuleBases, type PersistedRule, type RuleBehavior, type RuleScope, type ScopeRootIdentity } from "./permission-rule-model.js";
+import { type DenyFace, type JudgedPathRow, type PathRowReach } from "../tools/fs/read-deny.js";
+import { type ToolPolicy } from "./tool-policy.js";
+export { pathRowsReach, rowsWhereTheyLead, type PathRowsHit, type TargetViews } from "../tools/fs/read-deny.js";
+/** One path rule as a binding reads it: the parsed rule, its text, and — for a deny rule that guards a face of the
+ *  engine's deny tables — those faces (absent: the rule is judged on its own tool's calls only). */
+export interface PathRuleSpec {
+    readonly parsed: Pick<PersistedRule, "match" | "command" | "behavior" | "tool">;
+    readonly ruleText: string;
+    readonly faces?: readonly DenyFace[];
+}
+/** A rule bound to its anchors: a deny-table row (`faces` empty for a rule that guards no table face), its three-valued
+ *  reach over an absolute spelling, and the spec it was bound from. `unanchored` names the base words its pattern needs
+ *  that the anchors do not supply (the rule reads `unreadable` everywhere: a gate lane fails closed on it; a deny table
+ *  cannot judge it and leaves it to the gate). */
+export interface BoundPathRule<S extends PathRuleSpec = PathRuleSpec> extends JudgedPathRow {
+    readonly spec: S;
+    /** The rule's behavior (a deny table takes the `deny` rows that guard a face). */
+    readonly behavior: RuleBehavior;
+    readonly reach: (absolutePath: string) => PathRowReach;
+    readonly unanchored?: readonly PathRuleBase[];
+}
+/**
+ * The ONE binding of path rules to their anchors (`anchors`: one set for every spec, or a set per spec). Each row resolves
+ * its pattern once against its anchors and reads an absolute spelling under the anchors' family — a row installed on a win
+ * root reads `C:\proj\x`, `C:/proj/x` and `c:\proj\x` as one path; a row whose anchors name no tree reads the spelling's
+ * own family. The head (where the row's reach starts) is spelled for the environment, so a leg can judge the row where
+ * the head leads.
+ */
+export declare function bindPathRules<S extends PathRuleSpec>(specs: readonly S[], anchors: PathRuleBases | ((spec: S) => PathRuleBases)): BoundPathRule<S>[];
+/** A caller policy's anchors on the leg it is installed on: the declared `pathBases` word by word, else the leg's — `/x`
+ *  at the declared root (else the leg's root), a relative pattern at the declared cwd (else the `/x` anchor), `~/` at the
+ *  declared home (else the leg environment's). `install` absent (a policy called outside a Runner leg): the declaration
+ *  alone. */
+export declare function policyAnchors(declared: PathRuleBases, install: PathRuleBases | undefined): PathRuleBases;
+/** A stored row's anchors: a PROJECT row's `/x` and relative words at the row's own scope root (the project it was written
+ *  for), a global or session row's at the chain's top leg; `~/` at the top leg's home for every row. */
+export declare function persistedRowAnchors(scope: RuleScope, chainTop: PathRuleBases): PathRuleBases;
+/** A leg's root as an identity for project coverage ({@link ScopeRootIdentity}): its canonical root, and each project
+ *  row's scope root resolved through the leg's resolution (`leads`, each location once per leg) — so a row written under
+ *  one spelling of the project's directory applies to a leg rooted at another spelling of it. `undefined` when the leg
+ *  has no canonical root (the spellings alone are compared). */
+export declare function projectScopeIdentity(rules: readonly Pick<PersistedRule, "scope">[], canonicalRoot: string | undefined, leads: HeadLeads): Promise<ScopeRootIdentity | undefined>;
+/** A leg's resolution of the locations rule heads pass through: each location resolved once (twins are not refreshed
+ *  within a leg — a link re-pointed mid-leg is met through the row as spelled, and at its new location from the next
+ *  prepare; a location that does not resolve has no twin). `resolve` settles the parts of the given rows and answers
+ *  every location settled so far. */
+export interface HeadLeads {
+    resolve(rows: readonly Pick<JudgedPathRow, "head">[]): Promise<ReadonlyMap<string, string | undefined>>;
+}
+export declare function createHeadLeads(leadsTo: (part: string) => Promise<string | undefined>): HeadLeads;
+/**
+ * INSTALL a policy on a leg: its path rules are anchored at `anchors` (the leg's root and home; the policy's declared
+ * `pathBases` still win word by word) — once, for every judgment of the policy from then on: its `check` (the copy of each
+ * request it hands its inner check carries `ToolCallRequest.pathRuleAnchors`), the deny-table rows
+ * (`ToolPolicy.pathRules` answers with this installation's rows whatever it is given), and every child the leg hands
+ * the policy to as a parent constraint. A policy with no path rules is returned as it is. Installing an installed policy
+ * installs what it was installed FROM; one policy installed at the same anchors is one object (identity is the
+ * installation). Every member the policy carries rides as it holds it; the decision its `check` answers is untouched.
+ */
+export declare function installPolicyAnchors(policy: ToolPolicy | undefined, anchors: PathRuleBases): ToolPolicy | undefined;
+/** The policy an installation was installed from (`undefined`: not an installation). */
+export declare function installedFrom(policy: ToolPolicy | undefined): ToolPolicy | undefined;
+/** The anchors an installation was installed at (`undefined`: not an installation). */
+export declare function installationAnchorsOf(policy: ToolPolicy | undefined): PathRuleBases | undefined;

package/dist/core/path-rule-binding.js

@@ -0,0 +1,99 @@
+import { parsePermissionRule } from "./permission-rule-syntax.js";
+import { isUsablePathBase, pathRuleHeadOf, pathRuleReachOf, ruleBasesNeeded } from "./permission-rule-model.js";
+import { pathFamilyOf, spellingOfIdentity } from "../tools/fs/safety.js";
+import { absoluteTargetIdentityOf } from "./effective-path-target.js";
+import { locationLeadsTo, ruleHeadParts } from "../tools/fs/read-deny.js";
+import { carriedMembersOf } from "./tool-policy.js";
+export { pathRowsReach, rowsWhereTheyLead } from "../tools/fs/read-deny.js";
+const NOT_REACHED = { reach: "not_reached" };
+export function bindPathRules(specs, anchors) {
+    return specs.map((spec) => {
+        const a = typeof anchors === "function" ? anchors(spec) : anchors;
+        const family = pathFamilyOf(a);
+        const head = pathRuleHeadOf(spec.parsed, a);
+        const unanchored = ruleBasesNeeded(spec.parsed).filter((b) => !isUsablePathBase(b === "cwd" ? (a.cwd ?? a.root) : a[b], family));
+        const reach = (absolutePath) => {
+            const tree = a.root !== undefined || a.cwd !== undefined ? a : { root: absolutePath };
+            const id = absoluteTargetIdentityOf(absolutePath, tree);
+            return id === undefined ? NOT_REACHED : pathRuleReachOf(spec.parsed, id, a, pathFamilyOf(tree));
+        };
+        return {
+            spec,
+            behavior: spec.parsed.behavior,
+            rule: spec.ruleText,
+            tool: spec.parsed.tool,
+            pattern: parsePermissionRule(spec.ruleText).ruleContent ?? "",
+            faces: spec.faces ?? [],
+            reach,
+            reaches: (absolutePath) => reach(absolutePath).reach !== "not_reached",
+            ...(head !== undefined ? { head: spellingOfIdentity(head, family) } : {}),
+            ...(unanchored.length > 0 ? { unanchored } : {}),
+        };
+    });
+}
+export function policyAnchors(declared, install) {
+    const root = declared.root ?? install?.root;
+    const cwd = declared.cwd ?? root;
+    const home = declared.home ?? install?.home;
+    return { ...(root !== undefined ? { root } : {}), ...(cwd !== undefined ? { cwd } : {}), ...(home !== undefined ? { home } : {}) };
+}
+export function persistedRowAnchors(scope, chainTop) {
+    const root = scope.kind === "project" ? scope.root : chainTop.root;
+    return { ...(root !== undefined ? { root, cwd: root } : {}), ...(chainTop.home !== undefined ? { home: chainTop.home } : {}) };
+}
+export async function projectScopeIdentity(rules, canonicalRoot, leads) {
+    if (canonicalRoot === undefined)
+        return undefined;
+    const roots = rules.flatMap((r) => (r.scope.kind === "project" ? [{ head: r.scope.root }] : []));
+    const led = roots.length > 0 ? await leads.resolve(roots) : new Map();
+    return { canonicalRoot, canonicalOf: (root) => locationLeadsTo(root, led) };
+}
+export function createHeadLeads(leadsTo) {
+    const pending = new Map();
+    const settled = new Map();
+    return {
+        async resolve(rows) {
+            const parts = ruleHeadParts(rows).filter((p) => !settled.has(p));
+            await Promise.all(parts.map((part) => {
+                let p = pending.get(part);
+                if (p === undefined) {
+                    p = leadsTo(part).catch(() => undefined);
+                    pending.set(part, p);
+                }
+                return p.then((led) => settled.set(part, led));
+            }));
+            return settled;
+        },
+    };
+}
+const INSTALLED = new WeakMap();
+const INSTALLATIONS = new WeakMap();
+export function installPolicyAnchors(policy, anchors) {
+    if (policy === undefined)
+        return undefined;
+    const from = INSTALLED.get(policy)?.from ?? policy;
+    const rules = from.pathRules;
+    if (rules === undefined)
+        return from;
+    const key = JSON.stringify([anchors.root ?? null, anchors.cwd ?? null, anchors.home ?? null]);
+    const byAnchors = INSTALLATIONS.get(from) ?? new Map();
+    INSTALLATIONS.set(from, byAnchors);
+    const prior = byAnchors.get(key);
+    if (prior !== undefined)
+        return prior;
+    const seated = Object.freeze({ ...anchors });
+    const installed = {
+        ...carriedMembersOf(from),
+        pathRules: () => rules(seated),
+        check: (req, signal) => from.check({ ...req, pathRuleAnchors: seated }, signal),
+    };
+    INSTALLED.set(installed, { from, anchors: seated });
+    byAnchors.set(key, installed);
+    return installed;
+}
+export function installedFrom(policy) {
+    return policy === undefined ? undefined : INSTALLED.get(policy)?.from;
+}
+export function installationAnchorsOf(policy) {
+    return policy === undefined ? undefined : INSTALLED.get(policy)?.anchors;
+}

package/dist/core/permission-rule-model.d.ts

@@ -76,7 +76,7 @@ import { type DenyFace } from "../tools/fs/read-deny.js";
 import type { AssertAllKeysHandled } from "./ask-origin.js";
 import { type ToolCallLike } from "./tool-registry.js";
 import { type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
-import type { PathTargetReading } from "./effective-path-target.js";
+import { type TargetViews } from "./path-rule-binding.js";
 /**
  * The closed set of rule BEHAVIORS — what a matching rule says about the call. The upstream vocabulary
  * verbatim (`allow` / `deny` / `ask`, the three settings lists), in PRECEDENCE order: when rules of more
@@ -131,7 +131,9 @@ export declare function readRowBehavior(v: unknown): RuleBehavior | undefined;
  *  clears it. The org/hook/matchedAskRule immunities stay: those conjuncts live in the gate's
  *  persisted-rule lane and do not loosen with this set. */
 export type PersistedRuleTool = string;
-/** The one shell tool the command grammar speaks for. */
+/** The command grammar's ONE rule word — the spelling a shell command rule is written in (`Bash(<command>)`, upstream's).
+ *  A rule word, not a tool list: the calls a command rule reaches are the SHELL FACE's — every catalog definition whose
+ *  `command` the command grammar judges ({@link laneToolNamesOf}). */
 export declare const COMMAND_RULE_TOOL = "Bash";
 /** The one tool whose path family has an ALLOW form (the `Read(//abs-dir/**)` directory grant). */
 export declare const READ_RULE_TOOL = "Read";
@@ -144,7 +146,7 @@ export declare const READ_RULE_TOOL = "Read";
  * its tool's name as its reach (`Write(<path>)` is judged on the Write tool, a stricter reading the reference does not make).
  *
  * The two columns are enforced where each behavior can be: a deny row is exported to the engine's deny tables
- * (`ToolPolicy.pathDenyRules`, the person's rows at prepare), which refuse inside the tool, descend into a search's
+ * (`ToolPolicy.pathRules` bound where the policy is installed, the person's rows at prepare), which refuse inside the tool, descend into a search's
  * results and reach the shell's file commands; an ask is a question asked at the gate before the call runs, so it is
  * judged there, on the call's own path target only — it does not descend (a search rooted above the asked path is not
  * asked, and its results are not filtered).
@@ -167,8 +169,9 @@ export declare const NAME_RULE_FACES: Readonly<Record<string, {
     readonly params: readonly string[];
 }>>;
 /**
- * Which tools a rule may name — the model's tool set is DERIVED, never a hand-kept list: the shell tool
- * takes the COMMAND grammar; every tool the catalog declares a path target for (Read / Edit / Write /
+ * Which tools a rule may name — the model's tool set is DERIVED, never a hand-kept list: the command rule word
+ * ({@link COMMAND_RULE_TOOL}) takes the COMMAND grammar — the other shell-face tools take none of their own, their command is
+ * judged by the `Bash(…)` rules ({@link laneToolNamesOf}); every tool the catalog declares a path target for (Read / Edit / Write /
  * Glob / NotebookEdit / …, `pathTargetOf`) takes the PATH grammar; the tools of {@link NAME_RULE_FACES} take the NAME grammar.
  * A rule on any other tool has no content this model can judge and is refused (`unsupported.tool`). The tool set therefore
  * moves with the catalog's declarations, exactly as the protective fences' covered set does.
@@ -177,9 +180,12 @@ export declare function ruleToolGrammarOf(toolName: string): "command" | "path"
 /** The value a name-grammar tool's call carries in its name argument — the string every NAME rule is read against, the one a
  *  `Skill` call is resolved by — or undefined (not a name-grammar tool; no such argument; not a string). */
 export declare function nameRuleSubjectOf(toolName: string, args: unknown): string | undefined;
-/** The names the persisted grammar judges a call under: every name the call answers to (the model's spelling, the wire
- *  name, the other aliases that resolve to it) the grammar speaks for, so a stored `Bash(…)` or `Edit(…)` row reaches a
- *  tool that answers to that name under another wire name, as a policy's rule does. Empty ⇒ the grammar speaks for none. */
+/** The rule WORDS a call is judged under, once each: for every name the call answers to (the model's spelling, the wire
+ *  name, the other aliases that resolve to it), the word its rules are written in — a shell-face name's is the command
+ *  grammar's {@link COMMAND_RULE_TOOL} (a `Bash(<command>)` rule reaches `Monitor` as it reaches `Bash`), a path or name
+ *  tool's its own name — so a stored `Bash(…)` or `Edit(…)` row reaches a tool that answers to that name under another wire
+ *  name, as a policy's rule does. Every lane that judges a call by a rule's word reads it here: the policy compiler, the
+ *  person's stored rows, the org partition, the allow lists. Empty ⇒ no grammar speaks for the call. */
 export declare function laneToolNamesOf(req: Pick<import("./tool-policy.js").ToolCallRequest, "toolName" | "face">): readonly string[];
 /**
  * Match forms. Four members, two of them one predicate:
@@ -600,7 +606,7 @@ export declare function isUsablePathBase(base: string | undefined, family: PathF
  * defect (a `~/` deny falling back to the engine host's home guarded the wrong directory; a `/…` deny with
  * no root reached nothing at all).
  */
-export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: PathIdentity, bases: PathRuleBases): ProgramRunReachOutcome;
+export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: PathIdentity, bases: PathRuleBases, treeFamily?: PathFamily | undefined): ProgramRunReachOutcome;
 /**
  * Where a path rule's reach STARTS under the call's bases — its HEAD: the location the resolved pattern names before
  * its first segment carrying `*` (the whole path when none does), or a directory rule's directory. Everything the rule
@@ -772,7 +778,7 @@ export declare function lexicalNormalAbsolutePathOf(path: string, family: PathFa
  * there is nothing here for it to clear). As a DENY/ASK the same containment refuses or questions every
  * path under the directory, on whichever path tool the rule names.
  */
-export declare function directoryRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, path: PathIdentity, bases: PathRuleBases): boolean;
+export declare function directoryRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, path: PathIdentity, bases: PathRuleBases, treeFamily?: PathFamily | undefined): boolean;
 /** The identity of a directory SPELLING (the cd resolver's `/`-rooted output) under the call's tree, for the
  *  consumers that hand {@link directoryRuleAdmits} a spelling; a rule minted from it stores this form. */
 export declare function directoryIdentityOf(spelling: string, bases: PathRuleBases): PathIdentity | undefined;
@@ -785,7 +791,18 @@ export declare function directoryIdentityOf(spelling: string, bases: PathRuleBas
  *  r3-② cwd posture), never inferred from the process. ONE function on purpose: this is the scope
  *  conjunct of the single eligibility predicate ({@link eligibleContext}), and a sister predicate
  *  would be the second fact source the 375 §5.1 discipline exists to forbid. */
-export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined, sessionId?: string): boolean;
+export declare function scopeCoversCwd(scope: RuleScope, cwd: string | undefined, sessionId?: string, identity?: ScopeRootIdentity): boolean;
+/**
+ * A leg's root as an IDENTITY for project coverage: its canonical spelling, and the leg's resolution of a project row's
+ * scope root to the location it leads to. A DENY or ASK project row written under one spelling of a directory (a link the
+ * host spelled, a firmlink) covers a leg rooted at another spelling of the same directory: the row applies by where the two
+ * roots ARE, not only by how they are spelled. An allow row never reads it ({@link spelledScope}). A caller that holds no
+ * resolution (no leg, no environment) compares the spellings alone.
+ */
+export interface ScopeRootIdentity {
+    readonly canonicalRoot: string;
+    readonly canonicalOf: (root: string) => string | undefined;
+}
 /** Is this rule live — i.e. does it still carry at least one add? Deleted adds are removed by the store
  *  when tombstones are applied, so a rule with an empty `adds` is a rule that no longer exists. */
 export declare function isRuleLive(rule: PersistedRule): boolean;
@@ -815,6 +832,7 @@ export declare function eligibleContext(rule: {
     tool: string;
     cwd: string | undefined;
     sessionId?: string;
+    scopeIdentity?: ScopeRootIdentity;
 }): boolean;
 /**
  * design/375 §5.1 — MAY this PERSISTED rule participate in admitting this call at all? The liveness
@@ -834,7 +852,16 @@ export declare function eligiblePersisted(rule: PersistedRule, call: {
     tool: string;
     cwd: string | undefined;
     sessionId?: string;
+    scopeIdentity?: ScopeRootIdentity;
 }, behavior: RuleBehavior): boolean;
+/**
+ * The call context an ALLOW row's scope is judged in: the spellings alone. A deny or ask row applies wherever its project's
+ * directory is (its scope root resolved where it leads — more rows, only ever more protection); an allow row applies only
+ * where its scope root is SPELLED, so a link someone can re-point never carries a standing approval to another directory.
+ */
+export declare function spelledScope<C extends {
+    scopeIdentity?: ScopeRootIdentity;
+}>(call: C): Omit<C, "scopeIdentity">;
 /**
  * Find the rules that admit this command for a task in `cwd`, or `undefined`.
  *
@@ -914,19 +941,23 @@ export declare function adjudicatePersistedRules(rules: readonly PersistedRule[]
     cwd: string | undefined;
     sessionId?: string;
     execCwd?: string;
+    scopeIdentity?: ScopeRootIdentity;
 }): PersistedRuleVerdict | undefined;
 /**
  * The path-family sibling of {@link adjudicatePersistedRules}: the same precedence walk over the rules
- * of one path-targeting tool, judged on the call's resolved target path.
+ * of one path-targeting tool, judged on the call's target views by the one judgment every path rule meets
+ * ({@link pathRowsReach}: rows outer, views inner).
+ *
+ * TWO readings, because the two directions read the call's path slot differently (design/388 B6/B17): the
+ * tightening arms judge the PROTECTIVE reading's views (`views.tighten` — 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), every row
+ * also where its head leads (`leads`, the judging leg's resolution); the allow arm judges the DECLARED reading's views
+ * (`views.allow` — the face's OWN declaration only: a same-name tool that declares no path target is unconfirmable, and
+ * no grant admits it) with the directory rows, for the Read tool ONLY — a directory allow is a standing yes to reads,
+ * never to a write — and admits only when every view lies under the directory. Either reading may be absent (no
+ * resolvable path in that reading); the arm that needs it then speaks for nothing.
  *
- * TWO targets, because the two directions read the call's path slot differently (design/388 B6/B17): the
- * tightening arms judge the PROTECTIVE target (`protectivePathTargetOf` — 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) with {@link pathRuleReaches}; the allow arm judges the DECLARED target
- * (`declaredPathTargetOf` — the face's OWN declaration only: a same-name tool that declares no path
- * target is unconfirmable, and no grant admits it) with {@link directoryRuleAdmits}, and for the Read tool
- * ONLY — a directory allow is a standing yes to reads, never to a write. Either target may be absent
- * (no resolvable path in that reading); the arm that needs it then speaks for nothing.
+ * A row is anchored by `anchorsOf` (the person's rows: a project row at its scope root, the rest at the chain's top leg).
  *
  * `call.face` is the face the call's protective target is on (`read` / `write`): an ASK row speaks for the call when it
  * is the call's tool's row, or when {@link PATH_RULE_FACES} puts that face in the row's ask column (a `Read(<path>)` ask
@@ -938,10 +969,11 @@ export declare function adjudicatePersistedPathRules(rules: readonly PersistedRu
     cwd: string | undefined;
     sessionId?: string;
     face?: DenyFace | undefined;
-}, targets: {
-    readonly tighten?: PathTargetReading;
-    readonly allow?: PathTargetReading;
-}, bases: PathRuleBases): PersistedRuleVerdict | undefined;
+    scopeIdentity?: ScopeRootIdentity;
+}, views: {
+    readonly tighten?: TargetViews;
+    readonly allow?: TargetViews;
+}, anchorsOf: (rule: PersistedRule) => PathRuleBases, leads: ReadonlyMap<string, string | undefined>): PersistedRuleVerdict | undefined;
 /**
  * The name-family sibling of {@link adjudicatePersistedRules}: the same precedence walk over the rules of one name tool
  * ({@link NAME_RULE_FACES}), judged on the one string the call names (`nameRuleSubjectOf`). A rule of the tool speaks for the call
@@ -955,6 +987,7 @@ export declare function adjudicatePersistedNameRules(rules: readonly PersistedRu
     name: string | undefined;
     cwd: string | undefined;
     sessionId?: string;
+    scopeIdentity?: ScopeRootIdentity;
 }): PersistedRuleVerdict | undefined;
 /**
  * The ONE offer a name tool's approval card carries: the exact rule for the name the call carries (`Skill(<name>)`, the reference's
@@ -1009,6 +1042,8 @@ export declare function segmentCoverageOf(command: string, rules: {
     /** The relative-cd resolution base (see {@link findAdmittingRule}'s member of the same name) —
      *  defaults to `cwd`; scope/eligibility stays `cwd`. */
     execCwd?: string;
+    /** The leg's root as an identity for project coverage ({@link ScopeRootIdentity}). */
+    scopeIdentity?: ScopeRootIdentity;
 }): readonly SegmentCoverage[] | undefined;
 /** One row of a per-segment coverage table (see {@link segmentCoverageOf}): the FOLDED, trimmed
  *  segment text (a display/correlation seat, never adjudication input) and whether an eligible rule