@sema-agent/core 7.24.3 → 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/permission-rules.js

@@ -5,6 +5,7 @@ import { PATH_RULE_BASE_LABEL, isUsablePathBase, parseRuleText, pathRuleReachOf,
 import { pathFamilyOf } from "../tools/fs/safety.js";
 import { effectivePathTargetOf } from "./effective-path-target.js";
 import { protectivePathTargetOf } from "./tool-registry.js";
+import { ruleDenialSentence } from "./rule-denial-sentence.js";
 export { parsePermissionRule };
 export const BASH_GENERIC_PARAMS = new Set(catalogRuleFaceOf("Bash")?.params ?? []);
 const DEFAULT_CAPS = {
@@ -267,8 +268,11 @@ function matchParamRules(rules, args, maxScalarValueChars) {
     }
     return undefined;
 }
-function ruleMessage(kind, ruleText, source) {
-    return `${kind} by permission rule "${ruleText}"${source ? ` (${source})` : ""}`;
+function ruleDenial(req, ruleText, source) {
+    return ruleDenialSentence({ source: "permission", tool: req.toolName, rule: ruleText, ...(source ? { origin: source } : {}) });
+}
+function ruleAskMessage(ruleText, source) {
+    return `flagged by permission rule "${ruleText}"${source ? ` (${source})` : ""}`;
 }
 export function createPermissionRulePolicy(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
@@ -357,45 +361,45 @@ export function createPermissionRulePolicy(rules, opts) {
             const entry = byTool.get(req.toolName);
             const covering = hasCovering && protocolOf(req.toolName) !== undefined;
             if (entry?.bare.deny) {
-                return { action: "deny", message: ruleMessage("denied", entry.bare.deny.ruleText, entry.bare.deny.source) };
+                return { action: "deny", message: ruleDenial(req, entry.bare.deny.ruleText, entry.bare.deny.source) };
             }
             if (covering) {
                 const coveringDeny = coveringHit(namespacedCovering.deny, req.toolName);
                 if (coveringDeny)
-                    return { action: "deny", message: ruleMessage("denied", coveringDeny.ruleText, coveringDeny.source) };
+                    return { action: "deny", message: ruleDenial(req, coveringDeny.ruleText, coveringDeny.source) };
             }
             const contentDeny = entry !== undefined ? contentHit(entry.content.deny, req) : undefined;
             if (contentDeny !== undefined && contentDeny.unreadable === undefined) {
-                return { action: "deny", message: ruleMessage("denied", contentDeny.rule.ruleText, contentDeny.rule.source) };
+                return { action: "deny", message: ruleDenial(req, contentDeny.rule.ruleText, contentDeny.rule.source) };
             }
             if (entry) {
                 const paramDeny = matchParamRules(entry.param.deny, req.args, caps.maxScalarValueChars);
                 if (paramDeny) {
-                    return { action: "deny", message: ruleMessage("denied", paramDeny.ruleText, paramDeny.source) };
+                    return { action: "deny", message: ruleDenial(req, paramDeny.ruleText, paramDeny.source) };
                 }
             }
             if (contentDeny?.unreadable !== undefined)
                 return unreadableAsk({ rule: contentDeny.rule, unreadable: contentDeny.unreadable }, req);
             if (entry) {
                 if (entry.bare.ask) {
-                    return { action: "ask", message: ruleMessage("flagged", entry.bare.ask.ruleText, entry.bare.ask.source), matchedAskRule: entry.bare.ask.ruleText };
+                    return { action: "ask", message: ruleAskMessage(entry.bare.ask.ruleText, entry.bare.ask.source), matchedAskRule: entry.bare.ask.ruleText };
                 }
             }
             if (covering) {
                 const coveringAsk = coveringHit(namespacedCovering.ask, req.toolName);
                 if (coveringAsk)
-                    return { action: "ask", message: ruleMessage("flagged", coveringAsk.ruleText, coveringAsk.source), matchedAskRule: coveringAsk.ruleText };
+                    return { action: "ask", message: ruleAskMessage(coveringAsk.ruleText, coveringAsk.source), matchedAskRule: coveringAsk.ruleText };
             }
             if (entry) {
                 const contentAsk = contentHit(entry.content.ask, req);
                 if (contentAsk !== undefined) {
                     if (contentAsk.unreadable !== undefined)
                         return unreadableAsk({ rule: contentAsk.rule, unreadable: contentAsk.unreadable }, req);
-                    return { action: "ask", message: ruleMessage("flagged", contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
+                    return { action: "ask", message: ruleAskMessage(contentAsk.rule.ruleText, contentAsk.rule.source), matchedAskRule: contentAsk.rule.ruleText };
                 }
                 const paramAsk = matchParamRules(entry.param.ask, req.args, caps.maxScalarValueChars);
                 if (paramAsk) {
-                    return { action: "ask", message: ruleMessage("flagged", paramAsk.ruleText, paramAsk.source), matchedAskRule: paramAsk.ruleText };
+                    return { action: "ask", message: ruleAskMessage(paramAsk.ruleText, paramAsk.source), matchedAskRule: paramAsk.ruleText };
                 }
                 if (entry.bare.allow) {
                     return { action: "allow" };

package/dist/core/rule-denial-sentence.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The ONE mint for "a rule refused this call".
+ *
+ * WHY IT EXISTS. The engine has two rule stores that can refuse a tool call — the per-session policy rows
+ * a deployment writes against a session id, and the declarative permission rules compiled from a settings
+ * layer — and each used to spell its refusal in its own grammar at its own site: `tool "X" is denied by a
+ * session rule` beside `denied by permission rule "R" (layer)`, with the session lane's four containment
+ * arms in three further shapes and the resumed-execution re-check asserting a source ("a session rule")
+ * that was only ever one of the narrowing layers it speaks for. A consumer reading those strings could not
+ * tell WHICH store had spoken, which is precisely the confusion that produced the wrong answer to "is the
+ * rule store re-read at every gate?" — the two stores were being described as one.
+ *
+ * So: one grammar, one vocabulary of sources, one place to change either.
+ */
+/**
+ * The closed vocabulary of rule sources a refusal may name, each with the two spellings the sentence needs:
+ * `bare` when the source has no rule text to quote, `named` when it does. The type is DERIVED from this
+ * table, so a source without its spellings is not expressible and no fence is needed to say so.
+ *
+ * The words are the ENGINE'S rule-bearing faces, not a settings layer's (`source`/`origin` are different
+ * questions: WHICH STORE spoke, versus WHERE in that store's layering the row was written — the second
+ * rides `origin`).
+ */
+declare const RULE_SOURCE_PHRASE: {
+    /** The per-session policy rows (`SessionPolicyStore`), folded in as a deny-narrowing layer. */
+    readonly session: {
+        readonly bare: "a session rule";
+        readonly named: "session rule";
+    };
+    /** The declarative permission rules compiled from a deployment's settings layers. */
+    readonly permission: {
+        readonly bare: "a permission rule";
+        readonly named: "permission rule";
+    };
+    /**
+     * The deny-narrowing fold as a WHOLE — session rules, inherited ancestor rules, the frozen constraint
+     * projections and the active skill scope. Used where the refusing layer's own sentence is carried as the
+     * detail and the wrapper must not claim to know which of them spoke.
+     */
+    readonly narrowing: {
+        readonly bare: "a narrowing policy layer";
+        readonly named: "narrowing policy layer";
+    };
+};
+/** A rule-bearing face that can refuse a call ({@link RULE_SOURCE_PHRASE} holds the whole vocabulary). */
+export type RuleDenialSource = keyof typeof RULE_SOURCE_PHRASE;
+/** How a refusal names `source` in prose, with no rule text to quote — for a sentence this module does not
+ *  mint whole (a wrapper that carries the refusing layer's own sentence as its body). */
+export declare function ruleSourcePhrase(source: RuleDenialSource): string;
+/**
+ * Mint the refusal.
+ *
+ * @contract rule_denial.one_sentence — every refusal a RULE STORE mints reads
+ * `[tool "<tool>" is ]denied by <source>[ "<rule>"][ (<origin>)][: <detail>]`, composed here and nowhere
+ * else: the call is named first, then WHICH rule-bearing face refused (from the closed source vocabulary),
+ * then the rule's own text and the layer it was written in where the source has them, and last the reason
+ * this call failed the rule. A consumer reading a refusal can therefore always tell the session-policy
+ * store's answer from the permission rules' — and a carrier sentence that already named the call omits the
+ * head rather than spelling a second grammar.
+ *
+ * - `tool` — named when the sentence stands alone; omitted when a carrier sentence already named the call.
+ * - `rule` — the rule's own text, when the source has one to quote (a permission rule does; a session
+ *   policy row is structured fields, not a rule DSL, so it does not).
+ * - `origin` — where in that store's layering the row was written (e.g. a settings layer's key path).
+ * - `detail` — WHY this call failed the rule, when the source word alone does not say it (an allowlist
+ *   miss, a write the confinement cannot place, the refusing layer's own sentence).
+ */
+export declare function ruleDenialSentence(spec: {
+    source: RuleDenialSource;
+    tool?: string;
+    rule?: string;
+    origin?: string;
+    detail?: string;
+}): string;
+export {};

package/dist/core/rule-denial-sentence.js

@@ -0,0 +1,16 @@
+const RULE_SOURCE_PHRASE = {
+    session: { bare: "a session rule", named: "session rule" },
+    permission: { bare: "a permission rule", named: "permission rule" },
+    narrowing: { bare: "a narrowing policy layer", named: "narrowing policy layer" },
+};
+export function ruleSourcePhrase(source) {
+    return RULE_SOURCE_PHRASE[source].bare;
+}
+export function ruleDenialSentence(spec) {
+    const phrase = RULE_SOURCE_PHRASE[spec.source];
+    const by = spec.rule === undefined ? phrase.bare : `${phrase.named} ${JSON.stringify(spec.rule)}`;
+    const head = spec.tool === undefined ? "" : `tool ${JSON.stringify(spec.tool)} is `;
+    const origin = spec.origin === undefined ? "" : ` (${spec.origin})`;
+    const detail = spec.detail === undefined ? "" : `: ${spec.detail}`;
+    return `${head}denied by ${by}${origin}${detail}`;
+}

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