@sema-agent/core 7.45.0 → 7.46.0

package/dist/core/effective-path-target.d.ts

@@ -20,9 +20,19 @@
  *
  * The fix is not a fourth arm in the lanes: it is that "which base does this tool resolve against, and what
  * does it target when the slot is empty" is a FACT OF THE TOOL, so the tool declares it once and both
- * sides read the declaration. {@link pathTargetBaseOf} is the shared SELECTION (which base), and each side
- * then applies its own identity to the selected base — lexical-normal here (the rule family's one path
- * identity, zero IO), canonical (symlink-resolving, IO) inside the tool.
+ * sides read the declaration. {@link pathTargetBaseOf} is the shared SELECTION (which base).
+ *
+ * ## The views of one target
+ *
+ * A target is seen three ways: its LEXICAL view (the spelling joined to the selected base, `.` / `..` folded —
+ * zero IO), its CANONICAL view (the same spelling resolved by the execution environment: symlinks, aliases of the
+ * tree, the disk's own case) and the HOPS of its leaf's symlink chain. {@link readPathViews} is the one producer of
+ * those views — the tool's own resolution and its deny judgment read it, and so does {@link readCallTarget}, which
+ * a Runner stamp point calls once per adjudicated call and hands to every rule lane as
+ * `ToolCallRequest.targetReading`. Every rule lane reads a call's target through ONE reader, {@link callTargetViewsOf}:
+ * the reading's views when the call carries one, else the call's own lexical view (a bare request). The judgment over
+ * those views is the deny tables' (`pathRowsReach`): any view a deny or ask row reaches is reached; an allow row admits a
+ * call only when it admits every view of the declared reading.
  *
  * ## What it does NOT decide
  *
@@ -35,7 +45,9 @@
  * rule family reaches it, and the rule grammar is derived from the catalog's path targets), so it has no
  * declaration to read; the day it declares one, it reads the same selector as everything else.
  */
-import { type PathFamily, type PathIdentity, type Win32NamespaceRefusal } from "../tools/fs/safety.js";
+import { canonicalizeTarget, type PathFamily, type PathIdentity, type Win32NamespaceRefusal } from "../tools/fs/safety.js";
+import type { TargetViews } from "../tools/fs/read-deny.js";
+import type { ExecutionEnv } from "../internal/harness-types.js";
 import type { ToolCallPathTarget } from "./tool-face.js";
 import { type ToolCallLike } from "./tool-registry.js";
 /** The bases of ONE CALL a target resolves against: the task root, and the live tracked working directory
@@ -114,3 +126,123 @@ export declare function effectivePathSpellingOf(call: ToolCallLike, pt: ToolCall
 } | {
     readonly refused: Win32NamespaceRefusal;
 } | undefined;
+/**
+ * ONE reading of a call's path slot as VIEWS. `path`: the LEXICAL view (the spelling joined to the selected base and
+ * folded — a native spelling of the tree's family), the CANONICAL view when the environment answered (absent ⇒ not asked
+ * or no answer: an absent view takes no part in a judgment and is never a refusal) and the HOPS of the leaf's symlink
+ * chain when the environment declares one. `unreadable` / `refused` read as in {@link PathTargetReading}.
+ */
+export type CallTargetView = {
+    readonly kind: "path";
+    readonly lexical: string;
+    readonly canonical?: string;
+    readonly hops?: readonly string[];
+} | {
+    readonly kind: "unreadable";
+    readonly reason: string;
+} | {
+    readonly kind: "refused";
+    readonly reason: Win32NamespaceRefusal;
+};
+/**
+ * A call's TARGET READING: the views of each reading of its path slot — `protective`, the tightening direction's
+ * ({@link protectivePathTargetOf}), and `declared`, the allow direction's ({@link declaredPathTargetOf}; absent on a
+ * request that carries no face). It carries no root and no cwd: the call's own `root` / `cwd` are the only copies.
+ */
+export interface CallTargetReading {
+    readonly protective?: CallTargetView;
+    readonly declared?: CallTargetView;
+    /** Where each location on the way to a rule row's head that this leg's lanes hold LEADS in the leg's environment (a
+     *  link, a firmlink, an alias of the tree) — the rows' twins are judged there too. A fact of the judging leg, taken
+     *  once per location per leg; absent when no row head leads elsewhere. */
+    readonly leads?: ReadonlyMap<string, string>;
+}
+/** The environment's answer the canonical view rests on — the throat's own, so the tool keeps reading the refusal it gave. */
+export type CanonicalAnswer = Awaited<ReturnType<typeof canonicalizeTarget>>;
+/** The three views of one spelling as {@link readPathViews} produces them. */
+export interface PathViews {
+    readonly lexical: PathTargetReading;
+    /** `undefined` ⇒ the environment was not asked (none supplied, or a spelling this reading cannot locate). */
+    readonly canonical?: CanonicalAnswer;
+    readonly hops: readonly string[];
+}
+/**
+ * The ONE producer of a target's views: `spelled` against `base` (the base the tool's declaration selected), under the
+ * tree `bases` names. Lexical through the same resolution {@link effectivePathTargetOf} reads; canonical through the
+ * throat's own canonicalizer; the hops (when `opts.hops` and the canonical view answered) through the leaf's chain. The
+ * tool's resolution and deny judgment read this, and so does {@link readCallTarget}; an environment that THROWS
+ * propagates here (each caller holds its own posture: the tool refuses, the reading leaves the view absent).
+ */
+export declare function readPathViews(env: ExecutionEnv | undefined, spelled: string, base: string | undefined, bases: ToolPathBases, signal?: AbortSignal, opts?: {
+    readonly hops?: boolean;
+}): Promise<PathViews>;
+/** The identity of an ABSOLUTE spelling under the tree `bases` names — the target side's one prelude (family, namespace
+ *  screen, identity) for a path a judge already holds (a canonical key, a hop, a lexical view). `undefined` when the
+ *  spelling is not an absolute path of that tree. */
+export declare function absoluteTargetIdentityOf(spelled: string, bases: ToolPathBases): PathIdentity | undefined;
+/**
+ * A call's target reading under ONE call's facts: its `root` / `cwd` (the bases the stamp point reads off the leg) and
+ * the execution environment `env` (absent ⇒ the lexical views alone — the pre-claim recheck, which has no environment).
+ * A canonical view the environment cannot answer (or throws on) is absent, never a refusal (an absent view does not vote).
+ * The two readings share their views when they select the same spelling against the same base (one canonicalization).
+ */
+export declare function readCallTarget(env: ExecutionEnv | undefined, call: ToolCallLike & {
+    readonly root?: string | undefined;
+    readonly cwd?: string | undefined;
+}, signal?: AbortSignal, leads?: ReadonlyMap<string, string | undefined>): Promise<CallTargetReading>;
+/**
+ * `req` with its arguments replaced by `args` and — when `req` carries a reading of its own args — a reading of the NEW
+ * args taken the same way (same environment, same root / cwd, same face). Every seat that rewrites a request's arguments
+ * and hands it on (a composition's rewrite cascade, a re-judgment of the final or an edited form) goes through here, so the
+ * next layer never judges a request its reading does not describe. `signal` is the CURRENT call's: a reading never carries
+ * one call's cancellation into another's. `undefined` ⇒ nothing to re-read: use `{ ...req, args }`.
+ */
+export declare function withArgsReading<R extends {
+    readonly args: unknown;
+    readonly targetReading?: CallTargetReading | undefined;
+}>(req: R, args: unknown, signal: AbortSignal | undefined): Promise<R> | undefined;
+/** The request's target reading, when it describes the request's own `args` (the object it was taken for); otherwise
+ *  nothing — a rule lane then judges the lexical view it always judged. Every rule lane reads the reading through here. */
+export declare function callTargetReadingOf(req: {
+    readonly args: unknown;
+    readonly targetReading?: CallTargetReading | undefined;
+}): CallTargetReading | undefined;
+/**
+ * THE one reader of a call's target for every rule lane, in one direction's reading (`tighten` = the protective reading,
+ * `allow` = the declared one): the views of the call's target reading when it carries one of its own args (lexical,
+ * canonical, the leaf chain's hops), else the call's own lexical view — resolved against the call's `root` / `cwd` when it
+ * carries either, else against `bare` (a host's direct call of a policy: the bases it declared). `undefined` = the call
+ * names no path in this reading (or a spelling the throat refuses — no rule speaks about it); an `unreadable` answer =
+ * the call names a path this reading cannot locate.
+ */
+export declare function callTargetViewsOf(req: ToolCallLike & {
+    readonly root?: string | undefined;
+    readonly cwd?: string | undefined;
+    readonly targetReading?: CallTargetReading | undefined;
+}, direction: "tighten" | "allow", bare?: ToolPathBases): TargetViews | undefined;
+/**
+ * A leg's STAMP seat: `req` with a target reading of its own args, or `undefined` when there is nothing to stamp — the
+ * leg's lanes hold no path rule, the request already carries a reading of its args, or its args are not an object. The
+ * reading is taken under the request's own `root` / `cwd` when it carries them, else the leg's (the same values every
+ * Runner seat stamps), and memoized per args object within one call (its `toolCallId`), so every lane reading one call
+ * costs one reading. `undefined`
+ * rather than a resolved request, so a seat with nothing to do adds no suspension point.
+ */
+export type CallTargetStamp = <R extends ToolCallLike & {
+    readonly toolCallId?: string;
+    readonly root?: string | undefined;
+    readonly cwd?: string | undefined;
+    readonly targetReading?: CallTargetReading | undefined;
+}>(req: R, signal?: AbortSignal) => Promise<R & {
+    readonly targetReading: CallTargetReading;
+}> | undefined;
+/** The stamp seat of one leg: its execution environment, its root and live working directory, whether its lanes hold a
+ *  path rule (read per call — an activated skill can add one), and where the heads of the rows its lanes hold lead in its
+ *  environment (resolved once per location per leg). */
+export declare function legCallTargetStamp(leg: {
+    readonly env: ExecutionEnv;
+    readonly root: string;
+    readonly cwd: () => string | undefined;
+    readonly judgesPaths: () => boolean;
+    readonly leads: () => Promise<ReadonlyMap<string, string | undefined>>;
+}): CallTargetStamp;

package/dist/core/effective-path-target.js

@@ -1,5 +1,7 @@
-import { isAbsoluteForFamily, joinForFamily, pathFamilyOf, pathIdentityOf, win32NamespaceScreen } from "../tools/fs/safety.js";
-import { pathTargetValue } from "./tool-registry.js";
+import { canonicalizeTarget, isAbsoluteForFamily, joinForFamily, pathFamilyOf, pathIdentityOf, spellingOfIdentity, win32NamespaceScreen } from "../tools/fs/safety.js";
+import { declaredPathTargetOf, pathTargetValue, protectivePathTargetOf } from "./tool-registry.js";
+import { symlinkChainHops } from "./path-identity.js";
+import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, withGateTimeout } from "./gate-bounded-await.js";
 export function pathTargetBaseOf(pt, bases) {
     return (pt?.base ?? "cwd") === "root" ? bases.root : (bases.cwd ?? bases.root);
 }
@@ -73,3 +75,109 @@ function readingOf(r) {
 function unreadableBase(base) {
     return { kind: "unreadable", reason: base === undefined ? "the call's path is relative to a base that was not supplied" : `the base this call resolves against (${JSON.stringify(base)}) is not a fully-qualified path of this tree's family` };
 }
+export async function readPathViews(env, spelled, base, bases, signal, opts) {
+    const lexical = resolveSpelling(spelled, base, bases);
+    const family = pathFamilyOf(bases);
+    if (env === undefined || family === undefined || lexical?.kind === "unreadable")
+        return { lexical, hops: [] };
+    const canonical = await canonicalizeTarget(env, spelled, signal, family, base);
+    const climbs = (s) => s !== undefined && (family === "win" ? /(^|[\\/])\.\.([\\/]|$)/ : /(^|\/)\.\.(\/|$)/).test(s);
+    const followsALink = canonical.ok && (climbs(spelled) || climbs(base) || lexical?.kind !== "path" || absoluteTargetIdentityOf(canonical.key, bases) !== lexical.identity);
+    const hops = opts?.hops === true && followsALink ? await withGateTimeout(symlinkChainHops(env, spelled, signal, family, base), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "canonicalChain").catch(() => []) : [];
+    return { lexical, canonical, hops };
+}
+export function absoluteTargetIdentityOf(spelled, bases) {
+    const r = pathIdentityOf(spelled, pathFamilyOf(bases), bases.root ?? bases.cwd);
+    return r.ok ? r.identity : undefined;
+}
+const READ_FOR = new WeakMap();
+const REREAD = new WeakMap();
+export async function readCallTarget(env, call, signal, leads) {
+    const bases = { ...(call.root !== undefined ? { root: call.root } : {}), ...(call.cwd !== undefined ? { cwd: call.cwd } : {}) };
+    const family = pathFamilyOf(bases);
+    const views = new Map();
+    const viewOf = (pt) => {
+        const sel = effectivePathSpellingOf(call, pt, bases);
+        if (sel === undefined)
+            return Promise.resolve(undefined);
+        if ("refused" in sel)
+            return Promise.resolve({ kind: "refused", reason: sel.refused });
+        const target = sel.spelled !== undefined ? { spelled: sel.spelled, base: sel.base } : sel.base !== undefined && isAbsoluteForFamily(family, sel.base) ? { spelled: sel.base, base: undefined } : undefined;
+        if (target === undefined)
+            return Promise.resolve(unreadableBase(sel.base));
+        const { spelled, base } = target;
+        const key = JSON.stringify([spelled, base ?? null]);
+        const prior = views.get(key);
+        if (prior !== undefined)
+            return prior;
+        const read = readPathViews(env, spelled, base, bases, signal, { hops: true })
+            .catch(() => ({ lexical: resolveSpelling(spelled, base, bases), hops: [] }))
+            .then((v) => viewFrom(v, family));
+        views.set(key, read);
+        return read;
+    };
+    const protective = await viewOf(protectivePathTargetOf(call));
+    const declared = call.face === undefined ? undefined : await viewOf(declaredPathTargetOf(call));
+    const led = leads === undefined ? undefined : [...leads].filter((e) => e[1] !== undefined && e[1] !== e[0]);
+    const reading = Object.freeze({ ...(protective !== undefined ? { protective } : {}), ...(declared !== undefined ? { declared } : {}), ...(led !== undefined && led.length > 0 ? { leads: new Map(led) } : {}) });
+    if (typeof call.args === "object" && call.args !== null)
+        READ_FOR.set(reading, call.args);
+    REREAD.set(reading, (args, rereadSignal) => readCallTarget(env, { ...call, args }, rereadSignal, leads));
+    return reading;
+}
+export function withArgsReading(req, args, signal) {
+    const reading = callTargetReadingOf(req);
+    const reread = reading === undefined ? undefined : REREAD.get(reading);
+    return reread === undefined ? undefined : reread(args, signal).then((targetReading) => ({ ...req, args, targetReading }));
+}
+function viewFrom(v, family) {
+    if (v.lexical === undefined)
+        return undefined;
+    if (v.lexical.kind !== "path")
+        return Object.freeze({ ...v.lexical });
+    const canonical = v.canonical?.ok === true ? v.canonical.key : undefined;
+    return Object.freeze({ kind: "path", lexical: spellingOfIdentity(v.lexical.identity, family), ...(canonical !== undefined ? { canonical } : {}), ...(v.hops.length > 0 ? { hops: Object.freeze([...v.hops]) } : {}) });
+}
+export function callTargetReadingOf(req) {
+    const r = req.targetReading;
+    return r !== undefined && READ_FOR.get(r) === req.args ? r : undefined;
+}
+export function callTargetViewsOf(req, direction, bare = {}) {
+    const reading = callTargetReadingOf(req);
+    if (reading !== undefined) {
+        const v = direction === "tighten" ? reading.protective : reading.declared;
+        if (v === undefined || v.kind === "refused")
+            return undefined;
+        if (v.kind === "unreadable")
+            return { spellings: [], unreadable: v.reason };
+        const spellings = [v.lexical];
+        for (const s of [v.canonical, ...(v.hops ?? [])])
+            if (s !== undefined && !spellings.includes(s))
+                spellings.push(s);
+        return { spellings };
+    }
+    const own = req.root !== undefined || req.cwd !== undefined ? { ...(req.root !== undefined ? { root: req.root } : {}), ...(req.cwd !== undefined ? { cwd: req.cwd } : {}) } : bare;
+    const target = effectivePathTargetOf(req, direction === "tighten" ? protectivePathTargetOf(req) : declaredPathTargetOf(req), own);
+    if (target === undefined || target.kind === "refused")
+        return undefined;
+    if (target.kind === "unreadable")
+        return { spellings: [], unreadable: target.reason };
+    return { spellings: [spellingOfIdentity(target.identity, pathFamilyOf(own))] };
+}
+export function legCallTargetStamp(leg) {
+    const taken = new WeakMap();
+    return (req, signal) => {
+        const args = req.args;
+        if (typeof args !== "object" || args === null || callTargetReadingOf(req) !== undefined || !leg.judgesPaths())
+            return undefined;
+        const root = req.root ?? leg.root;
+        const cwd = req.cwd ?? leg.cwd();
+        const prior = taken.get(args);
+        const reading = prior !== undefined && prior.root === root && prior.cwd === cwd && prior.toolName === req.toolName && prior.toolCallId === req.toolCallId && prior.face === req.face
+            ? prior.reading
+            : leg.leads().then((leads) => readCallTarget(leg.env, { toolName: req.toolName, args, ...(req.face !== undefined ? { face: req.face } : {}), root, ...(cwd !== undefined ? { cwd } : {}) }, signal, leads));
+        if (prior?.reading !== reading)
+            taken.set(args, { root, cwd, toolName: req.toolName, toolCallId: req.toolCallId, face: req.face, reading });
+        return reading.then((targetReading) => ({ ...req, targetReading }));
+    };
+}

package/dist/core/engine-notice.d.ts

@@ -368,6 +368,11 @@ export interface EngineNotice {
      *    (one call's own rule check — every later call reads again, so the rows apply as soon as a read succeeds). Once
      *    per run, whichever read fails first; the trace keeps every read's line (`permission.rule_store_unreadable`).
      *    `detail: { at, sessionId, runId }`. Audience `user`.
+     *  - `"permission.rule_row_dropped"` — the person's store served project-scoped rows whose scope root is not a
+     *    complete absolute path (only a foreign writer or a hand edit makes one; every engine write face refuses it): they
+     *    take no part in this run's checks — a deny or ask row among them protects nothing — until they are rewritten or
+     *    removed. Once per run, by whichever read met them first. `detail: { rows, count, sessionId, runId }` — `rows`
+     *    the first eight `{ rule, scopeRoot }` (each bounded), `count` all of them. Audience `user`.
      *  - `"config.durable_gate_unavailable"` — a durable-approval MANDATE is in force on a leg with NO
      *    checkpoint store: the per-principal `forceDurableGate` entitlement, or the task's own
      *    `durableApproval` opt-in with no live approver seat (`durableMandateSourceOf`, the predicate the

package/dist/core/gate-fold.js

@@ -13,6 +13,9 @@ export async function runGateFold(pass) {
     const { input, toolName, toolCallId, callSignal, ledger, notifier, adjudicate } = pass;
     const boundedAwaitDeadlineMs = createGateDeadline(input, notifier);
     pass.req = { toolName, args: pass.currentInput, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
+    const stamped = input.stampCallTarget?.(pass.req, callSignal ?? input.abortSignal);
+    if (stamped !== undefined)
+        pass.req = await stamped;
     pass.decision = adjudicate ? refuseOutOfContractDecision(await (callSignal !== undefined ? adjudicate(pass.req, callSignal) : adjudicate(pass.req))) : { action: "allow" };
     {
         const refusedBy = ledger.fromDecision(pass.decision);

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";
@@ -118,7 +119,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 +141,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 +580,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 +594,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/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;
+}