@sema-agent/core 7.24.4 → 7.25.0

package/dist/core/permission-rule-store.js

@@ -56,19 +56,19 @@ export function assertDeleteDeltaCarriesNoAdd(delta) {
     }
 }
 export function assertWriteDeltaScopeDurable(delta) {
-    const scope = delta.kind === "redemption-add" ? delta.scope : delta.tombstone?.scope;
+    const scope = delta.kind === "tighten-delete" ? delta.tombstone?.scope : delta.scope;
     if (scope?.kind === "session") {
-        const e = new Error(delta.kind === "redemption-add"
-            ? "a session-scope rule cannot enter the persisted store — its home is the session's own overlay (design/382 §4.3); refusing the redemption-add"
-            : "a session-scope tombstone cannot enter the persisted store — session rows are not individually deletable and die with their session (design/382 §4.3/§10); refusing the tighten-delete");
+        const e = new Error(delta.kind === "tighten-delete"
+            ? "a session-scope tombstone cannot enter the persisted store — session rows are not individually deletable and die with their session (design/382 §4.3/§10); refusing the tighten-delete"
+            : `a session-scope rule cannot enter the persisted store — its home is the session's own overlay (design/382 §4.3); refusing the ${delta.kind}`);
         e.code = "unsupported.session_scope_store";
         throw e;
     }
     if (!isValidDurableScope(scope)) {
-        throw new Error(delta.kind === "redemption-add"
-            ? "a redemption-add whose scope is not a well-formed durable scope cannot enter the persisted store (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write"
-            :
-                "a tighten-delete must carry a tombstone whose scope is a well-formed durable scope (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write");
+        throw new Error(delta.kind === "tighten-delete"
+            ?
+                "a tighten-delete must carry a tombstone whose scope is a well-formed durable scope (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write"
+            : `a ${delta.kind} whose scope is not a well-formed durable scope cannot enter the persisted store (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write`);
     }
 }
 export function isValidConsentScope(scope) {
@@ -393,6 +393,7 @@ export async function ruleStoreChecksum(payload) {
     const { createHash } = await import("node:crypto");
     return `sha256:${createHash("sha256").update(canonicalize(payload), "utf8").digest("hex")}`;
 }
+export const REMOVAL_LIVENESS_WORDS = ["yes", "no", "unknown"];
 const REMOVE_MAX_ATTEMPTS = 8;
 export async function removePersistedRule(opts) {
     const behavior = opts.behavior;
@@ -435,6 +436,7 @@ export async function removePersistedRule(opts) {
     const tombstone = { behavior, rule, scope, removedDots, deletedBy: await writer.nextDot() };
     let expectedRev = snapshot.rev;
     let lastError = "";
+    let applyThrew = false;
     for (let attempt = 0; attempt < REMOVE_MAX_ATTEMPTS; attempt++) {
         try {
             const res = await writer.apply({ kind: "tighten-delete", tombstone }, { expectedRev });
@@ -442,37 +444,181 @@ export async function removePersistedRule(opts) {
                 return { status: "failed", error: `the store refused the tombstone (${res.refused}) — nothing was removed` };
             }
             if (!("conflict" in res)) {
-                let stillLive = false;
+                let stillLive;
                 try {
                     const after = await store.effective();
                     if (after.unreadable !== undefined)
                         throw new Error(after.unreadable);
-                    stillLive = after.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r));
+                    stillLive = after.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) ? "yes" : "no";
                 }
                 catch {
-                    stillLive = false;
+                    stillLive = "unknown";
                 }
                 return { status: "removed", rev: res.rev, stillLive };
             }
             expectedRev = res.rev;
         }
         catch (err) {
+            applyThrew = true;
             lastError = errText(err);
             break;
         }
     }
-    const reason = lastError !== "" ? lastError : `optimistic-concurrency retries exhausted after ${REMOVE_MAX_ATTEMPTS} attempts`;
+    const reason = applyThrew
+        ? lastError !== ""
+            ? lastError
+            : "the permission-rule store threw while applying the tombstone, with no message"
+        : `optimistic-concurrency retries exhausted after ${REMOVE_MAX_ATTEMPTS} attempts`;
     try {
         const after = await writer.readRaw();
         const landed = after.tombstones.some((t) => t.deletedBy.actor === tombstone.deletedBy.actor && t.deletedBy.counter === tombstone.deletedBy.counter);
-        return landed
-            ? { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) }
-            : { status: "failed", error: `${reason} (read-back confirms no tombstone was written)` };
+        if (landed) {
+            return { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) ? "yes" : "no" };
+        }
+        return {
+            status: "failed",
+            error: applyThrew
+                ? `${reason}; the store retains no tombstone for this removal, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()`
+                : `${reason} (read-back confirms no tombstone was written)`,
+        };
     }
     catch (err) {
         return { status: "failed", error: `${reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
     }
 }
+const RULE_ADD_MAX_ATTEMPTS = 8;
+const SESSION_ENDED_REFUSAL = "the session this authorization targets has ended — a session rule dies with its session, and a late or replayed redemption cannot revive it (re-trigger the command in a live session for a fresh card)";
+export async function landRuleAdd(args) {
+    switch (args.delta.kind) {
+        case "redemption-add":
+        case "tighten-add":
+            break;
+        default: {
+            const unreachable = args.delta;
+            throw new Error(`landRuleAdd: unhandled add delta ${JSON.stringify(unreachable)}`);
+        }
+    }
+    for (let attempt = 0; attempt < RULE_ADD_MAX_ATTEMPTS; attempt++) {
+        let rev;
+        try {
+            const snapshot = await args.store.effective();
+            if (snapshot.unreadable !== undefined)
+                throw new Error(snapshot.unreadable);
+            rev = snapshot.rev;
+            const refusal = await args.preflight?.(snapshot);
+            if (refusal !== undefined)
+                return { landed: false, reason: refusal, committed: "no" };
+        }
+        catch (err) {
+            return { landed: false, reason: `could not read the permission-rule store: ${errText(err)}`, committed: "no" };
+        }
+        let res;
+        try {
+            res = await args.writer.apply(args.delta, { expectedRev: rev });
+        }
+        catch (err) {
+            return { landed: false, reason: `the permission-rule store refused the write: ${errText(err)}`, committed: "unknown" };
+        }
+        if ("refused" in res)
+            return { landed: false, reason: SESSION_ENDED_REFUSAL, committed: "no" };
+        if (!("conflict" in res))
+            return { landed: true, rev: res.rev };
+    }
+    return { landed: false, reason: `optimistic-concurrency retries exhausted after ${RULE_ADD_MAX_ATTEMPTS} attempts`, committed: "no" };
+}
+export async function addPersistedRule(opts) {
+    const behavior = opts.behavior;
+    const ruleText = opts.rule;
+    const scope = structuredClone(opts.scope);
+    const target = opts.principal;
+    if (!isRuleBehavior(behavior)) {
+        return { status: "failed", error: `addPersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry` };
+    }
+    if (behavior === "allow") {
+        return {
+            status: "failed",
+            error: "addPersistedRule: an allow cannot be written through this entry — a standing approval is a person's yes and takes a consent record (prepare → confirm → redeem); this entry writes the tightening direction (deny/ask) only",
+        };
+    }
+    if (!isValidConsentScope(scope)) {
+        return { status: "failed", error: `addPersistedRule: ${escapeForDisclosure(JSON.stringify(scope))} is not a valid rule scope — refusing to write a row nothing can read back` };
+    }
+    const parsed = parseRuleText(ruleText, behavior);
+    if ("reject" in parsed)
+        return { status: "failed", error: `addPersistedRule: ${parsed.reject.code}: ${parsed.reject.message}` };
+    const identity = { behavior, rule: parsed.rule.rule, scope };
+    const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
+    const provider = opts.provider;
+    if (owner.kind === "local-owner" && provider.forLocalOwner === undefined) {
+        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be added through it" };
+    }
+    const store = owner.kind === "local-owner" ? provider.forLocalOwner() : provider.forPrincipal(owner.principal);
+    const writer = writerOf(store);
+    if (writer === undefined) {
+        return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be added through it" };
+    }
+    const query = scope.kind === "session" ? { sessionId: scope.sessionId } : undefined;
+    let snapshot;
+    try {
+        snapshot = await store.effective(query);
+    }
+    catch (err) {
+        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}` };
+    }
+    if (snapshot.unreadable !== undefined)
+        return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}` };
+    if (snapshot.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)))
+        return { status: "no-op", rev: snapshot.rev };
+    let dot;
+    try {
+        dot = await writer.nextDot();
+    }
+    catch (err) {
+        return { status: "failed", error: `could not mint the add's dot: ${errText(err)}` };
+    }
+    const landing = await landRuleAdd({
+        store,
+        writer,
+        delta: {
+            kind: "tighten-add",
+            behavior,
+            rule: parsed.rule.rule,
+            scope,
+            tool: parsed.rule.tool,
+            match: parsed.rule.match,
+            command: parsed.rule.command,
+            add: { dot, origin: "user", createdAt: new Date().toISOString() },
+        },
+    });
+    if (landing.landed)
+        return { status: "added", rev: landing.rev, dot };
+    if (landing.committed === "no")
+        return { status: "failed", error: landing.reason };
+    try {
+        let rev;
+        let rows;
+        let quarantinedRows = [];
+        if (scope.kind === "session") {
+            const view = await store.effective(query);
+            if (view.unreadable !== undefined)
+                throw new Error(view.unreadable);
+            ({ rev, rules: rows } = view);
+        }
+        else {
+            const raw = await writer.readRaw();
+            ({ rev, rules: rows } = raw);
+            quarantinedRows = raw.quarantined ?? [];
+        }
+        const stood = rows.some((r) => sameRuleIdentity(r, identity) && r.adds.some((a) => sameDot(a.dot, dot))) ||
+            quarantinedRows.some((q) => sameDot(q.add.dot, dot));
+        return stood
+            ? { status: "added", rev, dot }
+            : { status: "failed", error: `${landing.reason}; the store retains no trace of this add, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()` };
+    }
+    catch (err) {
+        return { status: "failed", error: `${landing.reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
+    }
+}
 export function errText(err) {
     return thrownText(err);
 }
@@ -525,6 +671,10 @@ export class InMemoryDurableRulePartition {
                 assertRedemptionNotQuarantined(this.quarantinedRows, delta);
                 this.rules = foldDelta(this.rules, delta);
             }
+            else if (delta.kind === "tighten-add") {
+                assertWriteDeltaScopeDurable(delta);
+                this.rules = foldDelta(this.rules, delta);
+            }
             else if (delta.kind === "tighten-delete") {
                 assertWriteDeltaScopeDurable(delta);
                 assertDeleteDeltaCarriesNoAdd(delta);

package/dist/core/runner/contracts.d.ts

@@ -382,6 +382,10 @@ export interface Prepared {
     /** The deployment's own caller policy, re-checked on a durable resume ONLY when the approver
      *  rewrote the pending call's args (see the composition site for why the edit case is special). */
     basePolicyForResumeEdit?: ToolPolicy;
+    /** The leg's shell READ STATION, re-run on a durable RESUME before an approved shell call executes: the parked leg's
+     *  admission died with that leg, so the resumed bytes are judged (and admitted for their pre-spawn re-establishment)
+     *  on THIS leg — a deny row found now vetoes, an operator's edit is judged on the `rejudge` seat. */
+    shellReadCheck?: import("../../tools/fs/shell-read-check.js").ShellReadCheck;
     /** The ORG adjudication face, re-resolved on a durable RESUME before an approved
      *  pending call executes. The resume path bypasses the harness gate by design (a human already
      *  adjudicated the checkpointed call), which is exactly where org policy skew is most likely: the
@@ -437,6 +441,14 @@ export interface Prepared {
      * leg always knows its identity.
      */
     hookIdentity: HookInvocationIdentity;
+    /**
+     * This session's DURABLE box, present iff this leg mounted the session-box drain (a top-level leg
+     * over a cross-process-safe mailbox with a grammatical session id). The notification lane binds it
+     * to the park seat ({@link import("../task-notification.js").PendingSessionNotifications.bindSessionBox})
+     * so a child's uplink frame parked for this session while it is idle lands in the box the next run
+     * drains — one mount judgment, the drain and the park read it alike. Absent ⇒ in-process parking.
+     */
+    sessionBox?: import("../task-notification.js").SessionBoxBinding;
     /**
      * The per-invocation TIME BOUND every hook seat of this leg runs under (`Hooks.timeoutMs`, already
      * validated — a garbage value was refused to the default and disclosed ONCE, here, rather than on
@@ -1252,6 +1264,7 @@ export interface InheritedGate {
         sessionId: string;
         principal?: string;
         rev: number;
+        gen?: number;
         rules: SessionPermissionRules;
     }>;
     /** The chain's effective shell-gate doctrine — the child folds it by max-rank with its own spec. */
@@ -1700,6 +1713,14 @@ export interface RunInternals {
      * every described child a "teammate" (clamp over-wide, addendum over-composed).
      */
     explicitAgentName?: string;
+    /**
+     * The RESOLVED subagent type this child was spawned as (`"general-purpose"` / `"fork"` / a roster
+     * definition's name — the same word the fleet row's `agentType` column carries; never the
+     * description). Read by the hook identity envelope (`identity.agentType`) so a process-level hook
+     * seat can tell WHAT kind of child it is serving without parsing display text. Trusted run-scoped
+     * channel (NOT a {@link TaskSpec} field); absent on a top-level run and on a workflow-lane agent.
+     */
+    spawnAgentType?: string;
     /**
      * The SPAWNING run's taskId, threaded at spawn (from the parent's
      * `ToolExecuteContext.taskId`) so this child's `task_progress` ticks carry `parentTaskId`. Lets a UI build the
@@ -1897,7 +1918,20 @@ export interface RunInternals {
      */
     parentNotify?: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
-    }) => void;
+    }) => unknown;
+    /**
+     * The ONE address `SendMessage("main")` names for this child — the session that hosts this child's
+     * lifecycle — paired with {@link parentNotify} at the same mint, three arms:
+     *  · a fresh spawn: the SPAWNER's session, whose live injector is `parentNotify`;
+     *  · a revival by that tree's ROOT (or any top-level session): the REVIVER's session, its injector;
+     *  · a revival by a SIBLING child, or by a host verb with no session: the row's ROOT session, and
+     *    NO `parentNotify` — a sibling is a peer the child addresses by name, not its main, and there is
+     *    no live callback into the root from either reviver. Such a child's "main" send reads the
+     *    honest not-deliverable text; its terminal still reaches the root through the root-anchor arm.
+     * The uplink receipt names this id so the model knows WHICH conversation "main" is. Absent on a
+     * top-level run. Trusted run-scoped channel (never a {@link TaskSpec} field).
+     */
+    uplinkSessionId?: string;
     /**
      * The PARENT run's subagent-retain ledger, threaded to a CHILD so its
      * SendMessage can continue a RETAINED SIBLING (the sibling's retain entry lives on the parent's
@@ -1917,7 +1951,7 @@ export interface RunInternals {
      */
     onNotifyInjectorReady?: (inject: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
-    }) => Promise<"queued" | "parked" | "dropped_duplicate">) => void;
+    }) => Promise<import("../task-notification.js").NotificationInjectionOutcome>) => void;
     /**
      * Per-task ISOLATION hint, a TRUSTED run-scoped channel filled ONLY by a core caller
      * (the workflow's `ctx.agent` when the SCRIPT passed `{ isolation: "worktree" }` as an OPTION) — NEVER a

package/dist/core/runner/gate-exit.d.ts

@@ -219,6 +219,15 @@ export interface GatePass {
      *  that ended as a refusal). The exit mints the outcome from it beside the ledger's `settled`; a refusal
      *  that reaches the exit without it is an engine defect and the mint throws. */
     deniedBy: DeniedBy | undefined;
+    /** borrowed-mutable — a refusing station's STRUCTURED details (the shell read station's refusal card), written
+     *  beside `deniedBy` by that station alone; the exit puts it on the gate result for the loop's error result.
+     *  OPTIONAL (the `probeUnanswered` form): the dispatch that builds the pass has nothing to declare here. */
+    denyDetails?: unknown;
+    /** borrowed-mutable — the shell read station's containment card behind a standing MANDATED ask (an out-of-root
+     *  or unestablishable read): when that ask ends as a refusal (a person's no, nobody to ask), the exit puts the
+     *  card on the gate result, so the refusal's `tool_end` still says WHAT was found (`readonly_out_of_root`) beside
+     *  WHO refused (`ask_resolution`). Writer: the fold's read station. */
+    shellReadDetails?: unknown;
     /** borrowed-mutable — the FORM of the classifier round behind a deny (`unavailable` / `parse_error`), written
      *  beside `deniedBy` by the gate's own classifier step (its attestation, read once) or by the fold / the
      *  re-check when an inherited station's attested deny arrives through the chain; undefined for a ruling
@@ -251,6 +260,11 @@ export interface GatePass {
      *  twin on the answered side, and narrower: the ask stays ordinary for every ANSWERER, and only the allow
      *  layer's read-only-command arm stands down. Writer: the fold. Reader: that arm, and nothing else. */
     probeBoundaryDeclined?: true;
+    /** borrowed-mutable — the shell read station minted the standing ask's directory-grant offer
+     *  (`probeReadRootCandidate`). Read by the classify seat's shape probe, which withdraws the offer when its
+     *  own objection stands beside the station's — the grant answers the station's finding, not the shape's.
+     *  Writer: the fold's read station. */
+    shellReadOffer?: true;
     /** borrowed-mutable — the write-protection judge covered this call and its table MATCHED: the allow
      *  layer must not clear the surviving ask, a live decider still may. Writer: the fold's fourth tighten,
      *  on BOTH its arms. Reader: the lanes' mandate. */

package/dist/core/runner/gate-exit.js

@@ -135,6 +135,10 @@ export async function exitGate(pass) {
             block: true,
             reason: formatHookFeedback(denyReason, input.reminderMark),
             gate,
+            ...(() => {
+                const details = pass.denyDetails ?? pass.shellReadDetails;
+                return details !== undefined ? { details } : {};
+            })(),
             preToolContext: pass.preToolContext,
         };
     }

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -1,7 +1,7 @@
 import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import { type PeerLaneRefs } from "../../agents/peer-session-drain.js";
 import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";
-import type { BashReadonlyRootBoundary } from "../../tools/fs/bash-readonly-classifier.js";
+import type { ShellReadAdmission } from "../../tools/fs/shell-read-check.js";
 import { type WorktreeSessionRef } from "../../tools/worktree.js";
 import type { CwdRef } from "../../tools/fs/index.js";
 import { type ToolResultStore } from "../tool-result-store.js";
@@ -19,7 +19,7 @@ export interface PrepareDelegationSurfaceInput {
     deps: Pick<RunnerDeps, "workflowRunStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "peerAdmission" | "peerDirectory" | "onNotice" | "onBackgroundChildEvent" | "tracer">;
     /** borrowed-readonly — the trusted spawn-side channel: `parentNotify` (the delegated-child door), the uplink / sibling /
      *  identity seats the SendMessage mount forwards, `onTaskNotification`, `onSubagentSpawn`. Never mutated. */
-    internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;
+    internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "uplinkSessionId" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;
     /** borrowed-readonly — the resume leg, or undefined: `seed.activeWorktree` seeds the worktree session (checkpoint first). */
     resume: Pick<PrepareResume, "seed"> | undefined;
     /** borrowed-readonly — the acquired session id (the mounts' session axis). */
@@ -37,8 +37,8 @@ export interface PrepareDelegationSurfaceInput {
     runnerSelf: RunnerSelfSeat | undefined;
     /** borrowed-readonly — the background/workflow door's first half: the hands mount decided a real shell with write hands. */
     backgroundTaskToolsActive: boolean;
-    /** borrowed-readonly — this run's shell read boundary (declared at the hands phase), for `Monitor`: the only P11 face that spawns a shell command. */
-    shellReadBoundarySeat: (() => BashReadonlyRootBoundary | undefined) | undefined;
+    /** borrowed-readonly — this run's shell read station's pre-spawn ADMISSION (declared at the hands phase), for `Monitor`: the only P11 face that spawns a shell command. */
+    shellReadAdmission: ShellReadAdmission | undefined;
     /** borrowed-readonly — the door's second half: the Workflow tool is on the roster. */
     workflowToolsActive: boolean;
     /** borrowed-readonly — the peer lane's mount verdict for this leg. */

package/dist/core/runner/prepare-delegation-surface.js

@@ -56,6 +56,7 @@ export function prepareDelegationSurface(input) {
                 ...(internals?.parentNotify !== undefined
                     ? { uplink: internals.parentNotify, ...(internals.parentPeerRef !== undefined ? { uplinkRecipient: internals.parentPeerRef } : {}) }
                     : {}),
+                ...(internals?.uplinkSessionId !== undefined ? { uplinkSessionId: internals.uplinkSessionId } : {}),
                 ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
                 ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
                 ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
@@ -103,7 +104,7 @@ export function prepareDelegationSurface(input) {
         envHandToolNames.add("Monitor");
         roster.mount(firstPartyOffload(createMonitorTool(executionEnv, {
             registry: defaultTaskRegistry,
-            ...(input.shellReadBoundarySeat !== undefined ? { readBoundary: input.shellReadBoundarySeat } : {}),
+            ...(input.shellReadAdmission !== undefined ? { shellReadAdmission: input.shellReadAdmission } : {}),
             owner: hostTaskId,
             scope: taskScope,
             ...(sessionId !== undefined ? { sessionId } : {}),

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

@@ -31,6 +31,7 @@ import type { ToolPolicy } from "../tool-policy.js";
 import { type GateOutcome } from "../gate-outcome.js";
 import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
 import type { WriteProtectionCheck } from "../write-protect.js";
+import type { ShellReadCheck } from "../../tools/fs/shell-read-check.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes } from "./contracts.js";
 import type { StopForDenialLimit } from "./denial-limit-arms.js";
@@ -153,6 +154,9 @@ export interface PrepareGateStationsInput {
      *  emptied the table: no judge, and no tighten mounted at all. Carried rather than compiled a second time
      *  here — two compiles are two judges, free to disagree about the seats they were handed. */
     writeProtectionCheck: WriteProtectionCheck | undefined;
+    /** borrowed-readonly — the leg's shell READ STATION (`ToolGateInput.shellReadCheck`), mounted by the hands phase, or
+     *  undefined with no real shell: no station, nothing judged. */
+    shellReadCheck: ShellReadCheck | undefined;
     /** borrowed-readonly — the per-tool irreversibility tier handed to the gate per call. */
     irreversibilityTier: IrreversibilityTier;
     /** borrowed-readonly — the per-tool reversibility probes handed to the gate per call. */

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

@@ -41,7 +41,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, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, writeProtectionCheck, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash } = 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, planModeRef, hostTaskId, sessionId, ownGatePreToolUse, hookTimeoutMs, handsCwdRef, hookEnvFace, writeProtectionCheck, shellReadCheck, irreversibilityTier, reversibilityProbes, abortController, shellGatedTools, autoModeDecider, autoModeDenialTracking, stopForDenialLimit, permissionRuleLane, permissionRuleOrgLane, questionToolMounted, sandboxAdmissionArmed, sandboxBoundaryCapable, emitSandboxAdmitted, delegation, notifyOwnHookCrash } = input;
     if (askLane !== undefined && parkAsk !== undefined) {
         const { adjudicate, resolveAskBound, notifyPermissionDenied, notifyHookError } = askLane;
         const { resolveContentAsk, suspendAsk } = parkAsk;
@@ -58,7 +58,8 @@ export function prepareGateStations(input) {
                 irreversibleTools.size > 0 ||
                 spec.enablePlanMode === true ||
                 complianceDenies.has("web_fetch") ||
-                writeProtectionArmed;
+                writeProtectionArmed ||
+                shellReadCheck !== undefined;
         if (toolCallGateArmedRef.armed) {
             harness.on("tool_call", async (e) => {
                 blockedToolCalls.delete(e.toolCallId);
@@ -112,6 +113,7 @@ export function prepareGateStations(input) {
                         egress: egressTools.has(e.toolName),
                         peerMessage: e.toolName === SEND_MESSAGE_TOOL_NAME,
                         ...(writeProtectionCheck !== undefined ? { writeProtectionCheck } : {}),
+                        ...(shellReadCheck !== undefined ? { shellReadCheck } : {}),
                         irreversibility: irreversibilityTier.get(e.toolName),
                         reversibilityProbe: reversibilityProbes.get(e.toolName),
                         abortSignal: abortController.signal,
@@ -204,11 +206,12 @@ export function prepareGateStations(input) {
                         toolName: e.toolName,
                         toolCallId: e.toolCallId,
                     });
+                    const details = result.details !== undefined ? { details: result.details } : {};
                     if (haltRemaining !== undefined) {
                         batchHaltRef.current = { rejectedToolCallId: e.toolCallId };
-                        return { block: true, reason: result.reason, haltRemaining };
+                        return { block: true, reason: result.reason, ...details, haltRemaining };
                     }
-                    return { block: true, reason: result.reason };
+                    return { block: true, reason: result.reason, ...details };
                 }
                 return result.updatedInput !== undefined ? { updatedInput: result.updatedInput } : undefined;
             });

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

@@ -1,5 +1,6 @@
-import { type BashReadonlyRootBoundary, type BeforeWriteHook, type CwdRef, type ReadDenyMatcher, type ContainmentFace } from "../../tools/fs/index.js";
+import { type BeforeWriteHook, type CwdRef, type ReadDenyMatcher, type ContainmentFace } from "../../tools/fs/index.js";
 import { type ReadFileState } from "../../tools/fs/safety.js";
+import { type ShellReadAdmission, type ShellReadCheck } from "../../tools/fs/shell-read-check.js";
 import type { RunnerDeps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { Model } from "../../internal/llm.js";
 import type { AgentHarness, AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
@@ -266,9 +267,12 @@ export interface PrepareHandsReadFaceResult {
     /** owned — real shell + write hands + background-capable env: gates the driver's TaskOutput/
      *  TaskStop/Monitor/SendMessage mounts (P11) and the Monitor arm of the shellGate fold here. */
     backgroundTaskToolsActive: boolean;
-    /** owned — this run's shell read BOUNDARY, published for a P11 face that spawns a shell command and
-     *  mounts LATER than the band (`Monitor`): the SAME closure the band's shell faces got. ⇔ hands. */
-    shellReadBoundarySeat: (() => BashReadonlyRootBoundary | undefined) | undefined;
+    /** owned — this run's shell READ STATION, the gate input (`ToolGateInput.shellReadCheck`): ONE judgment of
+     *  where a shell command reads, for every shell face this leg mounts, under every doctrine. ⇔ a real shell. */
+    shellReadCheck: ShellReadCheck | undefined;
+    /** owned — the same station's pre-spawn ADMISSION, published for the P11 face that spawns a shell command
+     *  and mounts LATER than the band (`Monitor`): the SAME function the band's shell faces got. ⇔ a real shell. */
+    shellReadAdmission: ShellReadAdmission | undefined;
     /** write-back (D-3 hold) — the run's RESOLVED read face where hands mount; undefined ⇔ no hands
      *  (the hands-less value lives in `handsLessResolvedFace`). The driver assigns this onto its
      *  outer `let` for the call-time closures (ctx enrichment / checkpoint mint / envFacts). */

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

@@ -3,8 +3,10 @@ import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
 import { boundaryIsTheSandbox } from "../remote-env.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { bashReadBoundaryProbe, bashReversibilityProbe, activeReadDenyBuiltinTiers, compileReadDeny, readDenySeat, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, inheritSessionReadFileState, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { bashReversibilityProbe, activeReadDenyBuiltinTiers, compileReadDeny, readDenySeat, createHandsToolkit, deploymentFaceClampNotice, pdfModelCapabilitiesOf, inheritSessionReadFileState, resolveContainmentFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
 import { resolveKey, sha256 } from "../../tools/fs/safety.js";
+import { createShellOverflowSpoolFence } from "../../tools/fs/fs-shared.js";
+import { createShellReadStation } from "../../tools/fs/shell-read-check.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
 import { deliverEngineNotice } from "../types.js";
@@ -137,7 +139,8 @@ export function resolveHandsLessReadFace(input) {
         wsSnapshot: undefined,
         rebaseWsPath: (p) => p,
         backgroundTaskToolsActive: false,
-        shellReadBoundarySeat: undefined,
+        shellReadCheck: undefined,
+        shellReadAdmission: undefined,
         resolvedReadFace: undefined,
         resolvedWriteFace: undefined,
         readDenyAdditionsNormalized,
@@ -168,7 +171,7 @@ export async function prepareHandsMount(input) {
     let wsSnapshot;
     let rebaseWsPath = (p) => p;
     let backgroundTaskToolsActive = false;
-    let shellReadBoundarySeat;
+    let shellReadStation;
     let resolvedReadFace;
     let resolvedWriteFace;
     let readDenyAdditionsNormalized = [];
@@ -337,7 +340,17 @@ export async function prepareHandsMount(input) {
             ...denySeat,
             ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
         });
-        shellReadBoundarySeat = shellReadBoundary;
+        if (handsIncludeShell) {
+            const readonlyBoundary = handsReadOnly
+                ? { roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical], cwd: rootCanonical, ...denySeat, alsoInside: createShellOverflowSpoolFence(executionEnv) }
+                : undefined;
+            shellReadStation = createShellReadStation({
+                env: executionEnv,
+                tools: new Set(handsReadOnly ? ["Bash"] : backgroundTaskToolsActive ? ["Bash", "Monitor"] : ["Bash"]),
+                seatOf: () => (handsReadOnly ? "readonly" : effectiveShellGate === "classify" ? "bash_classify" : "bash_off"),
+                boundaryOf: () => readonlyBoundary ?? shellReadBoundary(),
+            });
+        }
         const band = createHandsToolkit(executionEnv, readFileState, rootCanonical, {
             ...(additionalRootsCanonical.length > 0 ? { additionalRoots: additionalRootsCanonical } : {}),
             ...(additionalReadRootsCanonical.length > 0 ? { additionalReadRoots: additionalReadRootsCanonical } : {}),
@@ -352,7 +365,7 @@ export async function prepareHandsMount(input) {
             ...(input.onFileEdited !== undefined ? { onFileEdited: input.onFileEdited } : {}),
             includeShell: handsIncludeShell,
             readOnly: handsReadOnly,
-            shellReadBoundary,
+            ...(shellReadStation !== undefined ? { shellReadAdmission: shellReadStation.admit } : {}),
             ...(handsCwdRef ? { cwdRef: handsCwdRef } : {}),
             taskRegistry: defaultTaskRegistry,
             taskOwner: hostTaskId,
@@ -395,7 +408,7 @@ export async function prepareHandsMount(input) {
         if (!(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
             if (shellGate === "off") {
                 deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — the read boundary is ` +
-                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated${boundaryIsTheSandbox(executionEnv) ? "" : "; a read that only leaves the roots after symlink resolution is refused before it runs"}), but no ` +
+                    `still judged on every command (a deny-listed read is refused; an out-of-root read asks, and the ask is mandated${boundaryIsTheSandbox(executionEnv) ? "; under an isolated sandbox the paths are judged as written" : "; the paths are judged as the filesystem resolves them, symlinks and patterns included"}), but no ` +
                     `residual shell-risk classifier is installed: writes, egress and unknown commands are adjudicated by ` +
                     `the ordinary policy/hook chain only. Set spec.shellGate to "classify" or "always" if this deployment ` +
                     `expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
@@ -405,12 +418,13 @@ export async function prepareHandsMount(input) {
                 const seatOwned = !egressTools.has(name) && tierBefore !== "always" && tierBefore !== "maybe";
                 if (seatOwned)
                     shellGatedTools.add(name);
+                if (shellGate === "off" && tierBefore !== "always")
+                    return;
                 const tier = shellGate === "always" || tierBefore === "always" ? "always" : "maybe";
                 irreversibilityTier.set(name, tier);
                 irreversibleTools.add(name);
-                if (seatOwned && tier === "maybe") {
-                    reversibilityProbes.set(name, shellGate === "classify" ? bashReversibilityProbe(undefined, shellReadBoundary) : bashReadBoundaryProbe(shellReadBoundary));
-                }
+                if (seatOwned && tier === "maybe")
+                    reversibilityProbes.set(name, bashReversibilityProbe(undefined, shellReadBoundary));
             };
             installShellSeat("Bash");
             if (backgroundTaskToolsActive)
@@ -425,7 +439,8 @@ export async function prepareHandsMount(input) {
         wsSnapshot,
         rebaseWsPath,
         backgroundTaskToolsActive,
-        shellReadBoundarySeat,
+        shellReadCheck: shellReadStation?.check,
+        shellReadAdmission: shellReadStation?.admit,
         resolvedReadFace,
         resolvedWriteFace,
         handsLessResolvedWriteFace,

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

@@ -208,9 +208,32 @@ export interface PrepareInheritedGateResult {
             sessionId: string;
             principal?: string;
             rev: number;
+            gen?: number;
             rules: SessionPermissionRules;
         };
     };
+    /** borrowed-mutable — the ANCESTOR twin of {@link PrepareInheritedGateResult.ownSessionRulesRef}, keyed by
+     *  the entry's POSITION in `inheritedAncestorRules`. Writers: the policy chain's ancestor layers, each time
+     *  one comes to enforce a newer row than it prepared with. Read by {@link ancestorRulesNow}. Position, not
+     *  `(sessionId, principal)`: the chain may legitimately carry two entries of the same identity with
+     *  DIFFERENT floors (a leg whose own session is also an ancestor's, a seed and a live channel that both
+     *  name it), each compiled into its own layer with its own floor — and a by-identity key lets the layer
+     *  that advanced overwrite the entry of the layer that did not, publishing the weaker floor over the
+     *  stronger one. A layer upgrades its OWN entry; position is what "its own" means. */
+    ancestorSessionRulesRef: {
+        current: Map<number, {
+            sessionId: string;
+            principal?: string;
+            rev: number;
+            gen?: number;
+            rules: SessionPermissionRules;
+        }>;
+    };
+    /** owned — the ancestor rules AS THIS LEG NOW ENFORCES THEM: the inherited entries with the seat above
+     *  overlaid. The ONE projection, called by the child-chain assembly at spawn and by the checkpoint writer
+     *  at suspend — two faces of one rule ("what a later reader inherits is what this leg enforces"), which
+     *  were two implementations while the checkpoint cloned the prepare-time list. */
+    ancestorRulesNow: () => InheritedGate["ancestorRules"];
     /** borrowed-mutable — THIS task's own frozen admitted org scopes for its children's chain. Writers: the memory phase's
      *  admission door, once per leg. Read by the chain assembly (always emitted, empty = no org plane). */
     memoryAdmittedOrgScopesRef: {