@sema-agent/core 5.37.0 → 5.39.0

package/dist/core/hooks.d.ts

@@ -2,6 +2,7 @@ import type { DocumentContent, ImageContent, TextContent } from "../internal/llm
 import type { ExecutionEnv, FileError, Result, SessionTreeEntry } from "../internal/harness-types.js";
 import type { DecisionReason, PermissionResult, ResolvedAsk, ToolCallRequest, ToolPolicy } from "./tool-policy.js";
 import { type AskClass } from "./ask-class.js";
+import type { WiringLegKind } from "./wiring-manifest.js";
 /**
  * In-process hook seam (design/37) — a provider-agnostic interception layer modeled on CC's hooks,
  * kept process-internal (no shell/HTTP executors, no settings files). The original tool-call trio:
@@ -67,7 +68,10 @@ export interface Hooks {
      */
     preToolUseObservational?: true;
     postToolUse?(toolName: string, input: unknown, output: HookToolOutput, ctx: HookToolContext): PostToolUseResult | undefined | Promise<PostToolUseResult | undefined>;
-    userPromptSubmit?(prompt: string): UserPromptSubmitResult | undefined | Promise<UserPromptSubmitResult | undefined>;
+    userPromptSubmit?(prompt: string, 
+    /** #281 件A (additive): the run/leg identity envelope — an implementation declaring only
+     *  `(prompt)` keeps working. Always supplied on the engine's emission. */
+    ctx?: UserPromptSubmitContext): UserPromptSubmitResult | undefined | Promise<UserPromptSubmitResult | undefined>;
     /**
      * roadmap #5 (CC 198 Stop hook, :473831-): runs when the agent WOULD OTHERWISE END its run (no
      * more tool calls, steering and follow-up queues dry). Return `{ block: reason }` to PUSH BACK —
@@ -106,7 +110,11 @@ export interface Hooks {
      */
     postToolBatch?(batch: PostToolBatchCall[], meta?: {
         injectedThisTurn: "final_verification" | "finalize";
-    }): PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>;
+    }, 
+    /** #281 件A (additive): the run/leg identity envelope, on its OWN parameter — `meta`'s presence
+     *  is an existing signal ("the engine injected at this boundary") that must not become
+     *  always-true just because identity rides along. Always supplied on the engine's emission. */
+    ctx?: PostToolBatchContext): PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>;
     /**
      * design/134 (CC PreCompact parity): runs before each compaction, AFTER the trigger gate and a
      * valid cut point are confirmed (so every preCompact corresponds to a compaction that would
@@ -177,6 +185,10 @@ export interface Hooks {
 export type PermissionDeniedSource = "policy" | "hook" | "safety" | "shellGate" | "planMode" | "classifier" | "org";
 /** The payload a {@link Hooks.permissionDenied} callback observes (CC-exact fields + `source`). */
 export interface PermissionDeniedPayload {
+    /** #281 件A — the run/leg identity envelope. Present on every ENGINE emission (the gate's single
+     *  deny exit, the hook-crash intercept, the plan-mode and compliance denies); absent only when a
+     *  host drives {@link runToolGate} without `ToolGateInput.identity`. */
+    identity?: HookInvocationIdentity;
     toolName: string;
     /** The FINAL (post-hook-rewrite / post-policy-rewrite) args the chain adjudicated — what would have
      *  executed; not necessarily the model's original args. */
@@ -198,6 +210,9 @@ export interface PermissionDeniedPayload {
 export declare function cloneObserverInput(input: unknown): unknown;
 /** Context for {@link Hooks.stopFailure} — aligned with the TaskResult error face (observe-only). */
 export interface StopFailureContext {
+    /** #281 件A — the run/leg identity envelope (always present on the engine's emission; the seat is
+     *  optional only because the envelope's whole contract is). See {@link HookInvocationIdentity}. */
+    identity?: HookInvocationIdentity;
     /** Human-readable error message (the assembled `errorMessage`; any `[code]` prefix already stripped). */
     error: string;
     /** Machine-readable kind — the assembled `errorCode` lifted from the brain's `[code]` prefix
@@ -242,6 +257,10 @@ export interface PostToolBatchResult {
 }
 /** Context for {@link Hooks.preCompact} (design/134). */
 export interface PreCompactContext {
+    /** #281 件A — the run/leg identity envelope. Present when the Runner drives the compaction (its
+     *  wrapper injects it); honestly absent when a deployment drives the compaction module directly
+     *  (presence law arm 3 on {@link HookInvocationIdentity}). */
+    identity?: HookInvocationIdentity;
     /** "auto" = threshold-triggered; "manual" = /compact; "forced" = promptTooLong recovery or
      *  trim-pressure propagation (block is ignored on forced — the compaction is not optional). */
     trigger: "auto" | "manual" | "forced";
@@ -260,6 +279,8 @@ export interface PreCompactResult {
 }
 /** Context for {@link Hooks.postCompact} (design/134, observe-only). */
 export interface PostCompactContext {
+    /** #281 件A — same presence law as {@link PreCompactContext.identity}. */
+    identity?: HookInvocationIdentity;
     trigger: "auto" | "manual" | "forced";
     /** The conversation summary the compaction produced (CC `compact_summary` parity). */
     summary: string;
@@ -268,6 +289,11 @@ export interface PostCompactContext {
 }
 /** Context for the {@link Hooks.stop} hook (CC `stop_hook_active` parity). */
 export interface StopHookContext {
+    /** #281 件A — the run/leg identity envelope. The load-bearing member for THIS seat: a process-level
+     *  `deps.hooks.stop` fires in root, delegated-child and resume legs alike, and previously could not
+     *  tell which run it was being asked to end (matrix row 10/13 residual). Always present on the
+     *  engine's stop-gate emission. */
+    identity?: HookInvocationIdentity;
     /** True when this run is already continuing because a previous stop() blocked — check it and
      *  return success (undefined) once your condition can't be improved, or you will loop to the cap. */
     stopHookActive: boolean;
@@ -394,10 +420,94 @@ export interface HookEnvCapabilities {
  *    {@link createCwdReader} carries the one live read under the same rules.
  */
 export declare function createHookEnvCapabilities(env: ExecutionEnv): HookEnvCapabilities;
+/**
+ * #281 件A — the UNIFIED IDENTITY ENVELOPE every hook invocation can carry (`ctx.identity`): which
+ * run, which leg, and where in the delegation tree the hook is firing. The CC analog is
+ * `createBaseHookInput`'s per-event base fields; the members here are sema's OWN identity facts
+ * (session/leg/delegation axes), not a transcription of CC's field names.
+ *
+ * WHY: `deps.hooks` is PROCESS-level — one `stop`/`preToolUse`/`permissionDenied` seat serves the
+ * root run, every delegated child and every resume leg at once, and before this envelope none of
+ * those invocations could say which leg they belonged to. Additive: every seat is
+ * `identity?: HookInvocationIdentity`, so a consumer that never reads it sees nothing new.
+ *
+ * PRESENCE LAW (which invocations carry it — stated here once, referenced per seat):
+ *  · PRESENT on every ENGINE-driven invocation of every hook seat: the tool gate's PreToolUse
+ *    screenings (phase 1 + the approval-edit re-screen), postToolUse / postToolUseFailure,
+ *    postToolBatch, userPromptSubmit, stop, stopFailure, preCompact / postCompact (the Runner's
+ *    wrapper injects it), and every engine `permissionDenied` emission (gate deny exit, hook-crash
+ *    intercept, plan-mode deny, compliance deny). The engine mints ONE frozen envelope per prepared
+ *    leg ({@link mintHookInvocationIdentity} — single mint home) and every station reuses it.
+ *  · HONESTLY ABSENT (no fabrication) at exactly four places, each structurally unable to know:
+ *     1. a HOST driving the exported {@link runToolGate} directly without supplying
+ *        `ToolGateInput.identity` — the engine cannot know a leg it is not running;
+ *     2. an inherited PreToolUse screening face riding a DESCENDANT's constraint fold
+ *        ({@link createPreToolUseConstraintPolicy}) — the fold consumes it as a `ToolPolicy`, whose
+ *        request shape carries no leg identity, and stamping the INSTALL-site leg would name the
+ *        wrong run;
+ *     3. a deployment driving the compaction module directly with its own `preCompact`/`postCompact`
+ *        options — those contexts are built below the runner, which is where the envelope lives;
+ *     4. the PRE-CAS durable-resume observation of a declared-observational PreToolUse face
+ *        (resumeStream's edited-args leg) — it runs BEFORE the resume leg prepares, so the leg's
+ *        envelope does not exist yet, and minting a partial one off the checkpoint would guess at
+ *        the delegation axes (the row persists `isDelegatedChild` alone; `insideFork`/`agentName`/
+ *        `parentToolCallId` are internals-only, and a wrong guess is worse than an honest
+ *        absence). The SAME face is re-consulted with full identity by the resumed leg's own gate.
+ *
+ * CONSUMER NOTE — the minted object is FROZEN and carries a NULL PROTOTYPE (same rule and same
+ * trade as {@link HookEnvCapabilities}: absence must be a fact about this object, not about what
+ * `Object.prototype` happens to hold). Read members directly (`identity.agentName`), test presence
+ * with `in` or `!== undefined`; do NOT call inherited methods on it — `identity.hasOwnProperty(...)`
+ * or implicit string coercion would throw, exactly as on the env capability face.
+ */
+export interface HookInvocationIdentity {
+    /** The run's session id (uuid domain) — the same key `TaskResult.sessionId` reports. */
+    readonly sessionId: string;
+    /** The run's unified task id (`spec.taskId ?? sessionId` — the value TaskEvent's `sourceTaskId`
+     *  and `task_progress` frames key on). Equal to {@link sessionId} when no task id was declared. */
+    readonly taskId: string;
+    /** Which prepared leg this invocation belongs to — the wiring manifest's own `leg.kind`
+     *  derivation, verbatim ({@link WiringLegKind}: `"root" | "child" | "resume"`). NOTE the fork
+     *  lane's legs read `"child"` here like any other delegation; {@link insideFork} is the
+     *  fork-lane discriminator. */
+    readonly legKind: WiringLegKind;
+    /** RB-204 delegation fact, verbatim: `true` iff this leg runs as a delegated child (every core
+     *  spawn lane — sync/steer/background/fork/workflow — sets it; a top-level run reads `false`). */
+    readonly isDelegatedChild: boolean;
+    /** Present (`true`) iff this leg IS a forked child (`Agent(subagent_type:"fork")` — the
+     *  design/110 trusted internals fact). Absent everywhere else. */
+    readonly insideFork?: true;
+    /** The delegated child's display name, when one was threaded at spawn (taskName / agent-type).
+     *  UNTRUSTED display text (model-chosen) — already single-line-bounded at mint (same
+     *  `inlineUntrusted` treatment as the `task_progress` name lane); never an identity key. */
+    readonly agentName?: string;
+    /** The spawning Agent tool call's own id, when this leg runs under one — the delegation-chain
+     *  position anchor ({@link import("./types.js").TaskEvent}'s `parentToolCallId` twin). Absent on
+     *  a top-level run and on a directly-started workflow child (no launching tool call — no id is
+     *  fabricated). */
+    readonly parentToolCallId?: string;
+}
+/**
+ * #281 件A — the ONE construction home of {@link HookInvocationIdentity} (domain-lexicon: one mint
+ * site; the runner calls it once per prepared leg and every hook station reuses the same object).
+ * Frozen AND null-prototype: the envelope is handed to arbitrarily many deployment callbacks, and a
+ * hook mutating `ctx.identity` must not rewrite what a later hook (or the delegation-lifecycle
+ * observer) reads. The null prototype is the {@link createHookEnvCapabilities} rule applied to the
+ * other absence-signaling face this module mints — "absent member" must be a fact about THIS object,
+ * and a frozen object with an ordinary prototype still answers `insideFork`/`agentName` reads (and
+ * `in` probes) from `Object.prototype`, so a prototype write elsewhere in the process could hand
+ * every leg a delegation axis the mint never stamped (codex r1). `agentName` is sanitized here — it
+ * is the only member whose value a model influences.
+ */
+export declare function mintHookInvocationIdentity(facts: HookInvocationIdentity): HookInvocationIdentity;
 /** Identifying context passed to tool hooks. */
 export interface HookToolContext {
     toolCallId: string;
     toolName: string;
+    /** #281 件A — the run/leg identity envelope; see {@link HookInvocationIdentity} for the presence
+     *  law (present on engine-driven gates; absent on a host-driven gate without
+     *  `ToolGateInput.identity` and on the delegation-fold twin). */
+    identity?: HookInvocationIdentity;
     /**
      * The read-only path-resolution face over the env the hands run against (see
      * {@link HookEnvCapabilities} for the why, and for why it is capabilities rather than the env object).
@@ -450,6 +560,18 @@ export interface PostToolUseResult {
     /** Appended to the result as a `<system-reminder>` the model can read. */
     additionalContext?: string;
 }
+/** #281 件A — the context of a {@link Hooks.userPromptSubmit} invocation (second parameter,
+ *  additive). Carries only the identity envelope today; an object so later additions stay additive. */
+export interface UserPromptSubmitContext {
+    /** The run/leg identity envelope — see {@link HookInvocationIdentity} for the presence law. */
+    identity?: HookInvocationIdentity;
+}
+/** #281 件A — the context of a {@link Hooks.postToolBatch} invocation (third parameter, additive —
+ *  deliberately NOT folded into `meta`, whose presence already means "the engine injected here"). */
+export interface PostToolBatchContext {
+    /** The run/leg identity envelope — see {@link HookInvocationIdentity} for the presence law. */
+    identity?: HookInvocationIdentity;
+}
 /** A UserPromptSubmit hook result: block the submission, or inject context ahead of the prompt. */
 export interface UserPromptSubmitResult {
     /** Block submission entirely; the task fails with this model-readable reason. */
@@ -672,6 +794,11 @@ export interface ToolGateInput {
         toolName: string;
         input: Record<string, unknown>;
     };
+    /** #281 件A — the run/leg identity envelope, put verbatim on every {@link HookToolContext} this
+     *  gate call builds and on every {@link PermissionDeniedPayload} it emits. The Runner supplies its
+     *  per-leg mint; a host driving the gate directly may omit it, and the contexts then carry no
+     *  identity (honest absence — this layer never fabricates a leg). */
+    identity?: HookInvocationIdentity;
     preToolUse?: Hooks["preToolUse"];
     /** 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
@@ -811,6 +938,29 @@ export interface ToolGateInput {
      * per-tool mark — attributes a tighten-deny to `source:"shellGate"` instead of `"safety"`.
      */
     shellGated?: boolean;
+    /**
+     * design/276 (CC 2.1.233 P11 arm 4): true when the called tool is the peer-message verb — a message
+     * to another agent (`SendMessage`). ENGINE-FILLED from the wire name at the caller, never a
+     * configuration knob; a caller's same-named shadow tool is keyed too (for a tighten, over-asking is
+     * the fail-safe direction). Under an armed {@link autoMode} the gate tightens a surviving `allow` to
+     * `ask` (the peer-referral tighten below) so the message passes the classifier's eye — its prompt
+     * already carries the Multi-Agent Coordination exemption, so the ordinary teammate message resolves
+     * allow and the injection-shaped one is what this member exists to catch. Absent/false, or with no
+     * armed auto mode, the decision path is byte-identical. Per-run semantic: armed by THIS run's
+     * resolved caps, never inherited down the delegation chain (CC parity — the mode predicate reads the
+     * SENDING session's own mode).
+     */
+    peerMessage?: boolean;
+    /**
+     * backlog #286 (CC 2.1.233 `DANGEROUS_*` parity): the write-protection judge — ENGINE-BUILT from
+     * the deployment's table seat by `createWriteProtectionCheck` (write-protect.ts), never a
+     * deployment callback (the deployment authors table ROWS, which are validated loudly at compile;
+     * the judge itself is pure and synchronous, so it is trusted here like the `egress` mark). Judges
+     * the FINAL args of a path-confinable write tool; a hit demotes a surviving `allow` to `ask`
+     * (the write-protection tighten below). Absent ⇒ the deployment replaced the table with `[]` (or
+     * the caller runs the gate without one) and the decision path is byte-identical.
+     */
+    writeProtectionCheck?: (toolName: string, args: unknown) => import("./write-protect.js").WriteProtectedHit | null;
     /**
      * design/143 批2 ([672]-A, CC 2.1.207 auto mode): when present, a surviving `ask` is routed to the
      * small-model policy CLASSIFIER before any human/durable resolution:

package/dist/core/hooks.js

@@ -78,6 +78,18 @@ export function createHookEnvCapabilities(env) {
     }
     return Object.freeze(face);
 }
+const IDENTITY_AGENT_NAME_MAX = 80;
+export function mintHookInvocationIdentity(facts) {
+    return Object.freeze(Object.assign(Object.create(null), {
+        sessionId: facts.sessionId,
+        taskId: facts.taskId,
+        legKind: facts.legKind,
+        isDelegatedChild: facts.isDelegatedChild,
+        ...(facts.insideFork === true ? { insideFork: true } : {}),
+        ...(facts.agentName !== undefined ? { agentName: inlineUntrusted(facts.agentName.slice(0, 320), IDENTITY_AGENT_NAME_MAX) } : {}),
+        ...(facts.parentToolCallId !== undefined ? { parentToolCallId: facts.parentToolCallId } : {}),
+    }));
+}
 export function formatHookFeedback(text) {
     return `<system-reminder>\n${text}\n</system-reminder>`;
 }
@@ -270,7 +282,12 @@ export function persistedRuleMandateOf(marks) {
 export async function runToolGate(input) {
     const { event, preToolUse, adjudicate, resolveAsk, suspendAsk } = input;
     const { toolCallId, toolName } = event;
-    const hookCtx = () => ({ toolCallId, toolName, ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}) });
+    const hookCtx = () => ({
+        toolCallId,
+        toolName,
+        ...(input.hookEnv !== undefined ? { env: input.hookEnv } : {}),
+        ...(input.identity !== undefined ? { identity: input.identity } : {}),
+    });
     let currentInput = event.input;
     const preToolContext = [];
     let hookAsk;
@@ -285,7 +302,7 @@ export async function runToolGate(input) {
             const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
             traceHookCrash(input, err, notifier);
             if (input.permissionDenied) {
-                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook" }), "toolGate.permissionDenied");
+                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook", ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
             }
             return { block: true, reason: formatHookFeedback(reason), preToolContext };
         }
@@ -381,6 +398,25 @@ export async function runToolGate(input) {
             denySource = input.shellGated === true ? "shellGate" : "safety";
         }
     }
+    if (input.peerMessage === true && decision.action === "allow" && input.autoMode !== undefined && !input.autoMode.decider.breakerOpen()) {
+        decision = {
+            action: "ask",
+            message: `tool "${toolName}" sends a message to another agent — routed for classifier review in auto mode`,
+            decisionReason: "safety",
+        };
+        denySource = "safety";
+    }
+    if (decision.action === "allow" && input.writeProtectionCheck !== undefined) {
+        const writeProtectedHit = input.writeProtectionCheck(toolName, policyRewrite !== undefined ? policyRewrite : currentInput);
+        if (writeProtectedHit !== null) {
+            decision = {
+                action: "ask",
+                message: `tool "${toolName}" writes to a write-protected path (table entry "${writeProtectedHit.name}") — explicit approval required`,
+                decisionReason: "safety",
+            };
+            denySource = "safety";
+        }
+    }
     let orgRealApprovalRequired = false;
     let orgAskOrigin;
     let orgTightenCount = 0;
@@ -556,6 +592,7 @@ export async function runToolGate(input) {
             decision.decisionReason !== "hook" &&
             hookAsk === undefined &&
             input.egress !== true &&
+            input.peerMessage !== true &&
             input.sandboxAdmission.boundaryCapable !== true) {
             const recorded = input.sandboxAdmission.askClassesOf(toolCallId);
             const admissible = recorded !== undefined && recorded.length > 0 && recorded.every((r) => r.cls === "sandbox_local");
@@ -638,6 +675,7 @@ export async function runToolGate(input) {
             if (decision.action === "allow" && decision.updatedInput !== undefined) {
                 let editArgs = decision.updatedInput;
                 let editDenied;
+                let editRewrittenSinceHuman = false;
                 for (let round = 0;; round++) {
                     if (round >= 3) {
                         editDenied = {
@@ -674,8 +712,10 @@ export async function runToolGate(input) {
                                 denySource = "hook";
                                 break;
                             }
-                            if (hr.updatedInput !== undefined)
+                            if (hr.updatedInput !== undefined) {
                                 editArgs = hr.updatedInput;
+                                editRewrittenSinceHuman = true;
+                            }
                         }
                     }
                     if (!adjudicate && input.orgRules === undefined)
@@ -697,8 +737,10 @@ export async function runToolGate(input) {
                         denySource = "policy";
                         break;
                     }
-                    if (recheck.updatedInput !== undefined)
+                    if (recheck.updatedInput !== undefined) {
                         editArgs = recheck.updatedInput;
+                        editRewrittenSinceHuman = true;
+                    }
                     const orgTightensBefore = orgTightenCount;
                     recheck = await applyOrgLayer(recheck, editArgs);
                     const orgRaisedThisRound = orgTightenCount > orgTightensBefore;
@@ -707,12 +749,16 @@ export async function runToolGate(input) {
                         break;
                     }
                     if (recheck.action === "allow") {
-                        if (recheck.updatedInput !== undefined)
+                        if (recheck.updatedInput !== undefined) {
                             editArgs = recheck.updatedInput;
+                            editRewrittenSinceHuman = true;
+                        }
                         break;
                     }
-                    if (recheck.updatedInput !== undefined)
+                    if (recheck.updatedInput !== undefined) {
                         editArgs = recheck.updatedInput;
+                        editRewrittenSinceHuman = true;
+                    }
                     const rr = await resolveAsk({ ...recheck, ruleEvidence: mintRuleEvidence({ dotsAbsent: "not_adjudicated" }) }, { toolName, args: editArgs, toolCallId });
                     resolvedApprover = rr.action !== "ask" ? rr.approver : undefined;
                     if (rr.action !== "allow") {
@@ -724,9 +770,21 @@ export async function runToolGate(input) {
                     if (rr.updatedInput === undefined) {
                         if (rr.presentedInput !== undefined)
                             editArgs = rr.presentedInput;
+                        editRewrittenSinceHuman = false;
                         break;
                     }
                     editArgs = rr.updatedInput;
+                    editRewrittenSinceHuman = false;
+                }
+                if (editDenied === undefined && editRewrittenSinceHuman && input.writeProtectionCheck !== undefined) {
+                    const editHit = input.writeProtectionCheck(toolName, editArgs);
+                    if (editHit !== null) {
+                        editDenied = {
+                            action: "deny",
+                            message: `the approved edit for "${toolName}" was rewritten by the restriction chain onto a write-protected path (table entry "${editHit.name}") that no approval covers — denied fail-closed; re-submit the edited action directly`,
+                        };
+                        denySource = "safety";
+                    }
                 }
                 decision = editDenied ?? { ...decision, updatedInput: editArgs };
             }
@@ -741,7 +799,7 @@ export async function runToolGate(input) {
             currentInput = decision.updatedInput;
         }
         if (input.permissionDenied) {
-            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource }), "toolGate.permissionDenied");
+            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
         }
         const denySettledBy = decision.settledBy;
         const denyApprover = denySettledBy !== undefined ? resolvedApprover : undefined;

package/dist/core/mailbox-store.d.ts

@@ -13,6 +13,28 @@ export interface MailboxMessage {
      *  cross-engine records sit outside the guard's promise domain by ruling. */
     hopChain?: string[];
 }
+/** The enqueue refusal code of the pre-delete clause (see {@link MailboxStore} and
+ *  {@link MailboxStoreError}) — the ONE place it is spelled, so an out-of-repo store twin imports it
+ *  instead of value-copying the string (same posture as `STALE_RUNNING_REAP_ATTRIBUTION`: a shared
+ *  symbol makes drift impossible rather than merely caught). */
+export declare const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tombstoned";
+/**
+ * Typed store error so callers branch on `code` (mirrors `BackgroundAgentStoreError`).
+ *
+ * `recipient_tombstoned` is the ENQUEUE refusal a backend raises when the recipient it addresses is
+ * in a deployment's PRE-DELETE state — the window a retention/deletion cascade opens when it has
+ * decided a session (and every row hanging off it) is going away but has not finished removing the
+ * rows. An `append` accepted in that window returns a seq to the sender — a durable receipt — for a
+ * message the cascade then deletes before any consumer could ever lease it. The refusal is what
+ * turns that into a fact the sender can act on.
+ *
+ * A backend may raise the same code with a plain `Error` carrying `.code`; consumers branch on the
+ * string, not on this class (a cross-process/out-of-repo store cannot hand back an instance).
+ */
+export declare class MailboxStoreError extends Error {
+    readonly code: typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE;
+    constructor(code: typeof MAILBOX_TOMBSTONED_RECIPIENT_CODE, message: string);
+}
 /** A leased batch: the messages a claim winner owns for delivery, plus the ack cursor. */
 export interface MailboxLease {
     messages: MailboxMessage[];
@@ -55,8 +77,25 @@ export interface MailboxAppendMessage {
  *   is ADVISORY: a drop fault never blocks the reap, and a box orphaned that way still ages out here.
  *   `drop` therefore has a real caller — an implementation that stubs it strands mailboxes until the
  *   age policy catches them.
+ * - PRE-DELETE STATE (optional capability, additive contract extension): a backend that can SEE its
+ *   recipient's lifecycle — one whose rows live alongside the session rows a retention/deletion
+ *   cascade removes — must refuse `append` for a recipient the cascade has already tombstoned,
+ *   CODED: an `Error` whose `code` is `"mailbox.recipient_tombstoned"` ({@link MailboxStoreError} is
+ *   the bundled shape; consumers branch on the string). Accepting is the failure this clause names:
+ *   `append` is durable-first, so the returned seq is a receipt for a message the cascade deletes
+ *   before any consumer can lease it — a delivery promised to the sender and kept to nobody, which
+ *   no other face reports. The refusal is per RECIPIENT and enqueue-only: a tombstone belongs to one
+ *   `(scope, handle)` — the same two-part identity every other method here is keyed by, so it says
+ *   nothing about a sibling handle NOR about the same handle under another scope — and it is not a
+ *   wipe (whatever is already parked stays under the same lease/ack rules until the cascade removes
+ *   the box). A backend with NO view of that
+ *   lifecycle (the two bundled ones, the CC inbox adapter) has nothing to refuse and keeps accepting
+ *   — the clause fixes the SPELLING of the refusal, so a deployment reads one code instead of a
+ *   per-backend dialect. Acceptance kit: `mailboxTombstonedRecipientContract`.
  */
 export interface MailboxStore {
+    /** Durably park one message. Refuses `"mailbox.recipient_tombstoned"` when the backend can see
+     *  that its recipient is in the deployment's pre-delete state (see the interface notes above). */
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;

package/dist/core/mailbox-store.js

@@ -1,4 +1,13 @@
 import { assertRetentionPolicy } from "./retention-policy.js";
+export const MAILBOX_TOMBSTONED_RECIPIENT_CODE = "mailbox.recipient_tombstoned";
+export class MailboxStoreError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "MailboxStoreError";
+    }
+}
 export function newestSentAt(messages) {
     let newest;
     for (const m of messages) {

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

@@ -285,9 +285,9 @@ export interface CcImportLayer {
 /**
  * What the import WOULD do, shown before anyone confirms.
  *
- * `uncovered` is a two-key record, not a list: the two layers this version does not read are named in the
+ * `uncovered` is a fixed-key record, not a list: everything this version does not import is named in the
  * TYPE, so an empty list, a missing member or a duplicate is not expressible. A preview that reported only
- * the layers it read would be claiming completeness it does not have.
+ * what it read would be claiming completeness it does not have.
  */
 export interface ImportPreview {
     candidates: RuleCandidate[];
@@ -303,6 +303,26 @@ export interface ImportPreview {
     uncovered: {
         flagSettings: "not-imported-v1";
         policySettings: "not-imported-v1";
+        /**
+         * The deny/ask buckets of the layers actually read: how many entries are SITTING THERE, across all
+         * layers, that this import deliberately leaves in place (they are the tightening direction and have
+         * their own channel — importing them through a loosening lane would be the wrong door).
+         *
+         * Always present, zero when the buckets are absent or empty: "this settings file has 14 deny entries
+         * we did not touch" and "there was nothing there" are different facts, and a key that appears only in
+         * the first case makes them indistinguishable for a reader who sees one preview. The count is of
+         * ENTRIES IN PLACE, not of a decision — nothing here is skipped-and-lost; `skipped` stays the list of
+         * allow-bucket entries that did not become candidates.
+         *
+         * A bucket that is PRESENT but not an array cannot be counted; it contributes 0 and is disclosed in
+         * `skipped` under the layer's path, so a zero is never the report for something unreadable. Same for
+         * a layer whose whole `permissions` member is not an object — every bucket in it reads as absent,
+         * which is exactly the shape that would otherwise report two clean zeros.
+         */
+        denyAskBuckets: {
+            deny: number;
+            ask: number;
+        };
     };
 }
 /** What the import ACTUALLY did — a different moment and a different contract from the preview, because
@@ -320,8 +340,11 @@ export interface ImportResult {
  * Read the allow buckets of the user-editable settings layers and produce a preview plus a PENDING
  * approval record. Nothing is stored until someone confirms that record and the batch is redeemed.
  *
- * Only the allow bucket is read. The deny/ask buckets are the tightening direction and have their own
- * channel; importing them through a loosening lane would be the wrong door.
+ * Only the allow bucket is IMPORTED. The deny/ask buckets are the tightening direction and have their own
+ * channel; importing them through a loosening lane would be the wrong door. They are still COUNTED and
+ * reported (`preview.uncovered.denyAskBuckets`): by-design-not-imported and unnoticed look identical to
+ * the person confirming the batch, and only one of them is true here — the same reason the non-Bash allow
+ * entries are disclosed rather than dropped silently.
  */
 export declare function prepareCcImport(opts: {
     layers: CcImportLayer[];

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

@@ -337,12 +337,13 @@ async function applyRedemption(args) {
 function originOfRecordKind(kind) {
     return kind === "import" ? "imported-cc" : kind === "starter" ? "starter" : "user";
 }
-const IMPORT_UNCOVERED = { flagSettings: "not-imported-v1", policySettings: "not-imported-v1" };
+const IMPORT_UNCOVERED_LAYERS = { flagSettings: "not-imported-v1", policySettings: "not-imported-v1" };
 export async function prepareCcImport(opts) {
     const owner = resolveCallerOwner(opts.principal, opts.owner, "prepareCcImport");
     const candidates = [];
     const skipped = [];
     const layers = [];
+    const denyAskBuckets = { deny: 0, ask: 0 };
     for (const layer of opts.layers) {
         let raw;
         try {
@@ -356,14 +357,38 @@ export async function prepareCcImport(opts) {
             continue;
         }
         layers.push({ path: layer.path, layer: layer.layer, found: true });
-        let allow;
+        let container;
         try {
-            allow = JSON.parse(raw)?.permissions?.allow;
+            container = JSON.parse(raw)?.permissions;
         }
         catch (err) {
             skipped.push({ rule: layer.path, reason: `settings file is not valid JSON (${errText(err)})` });
             continue;
         }
+        let permissions;
+        if (container === undefined || container === null)
+            permissions = undefined;
+        else if (typeof container === "object" && !Array.isArray(container))
+            permissions = container;
+        else {
+            skipped.push({
+                rule: layer.path,
+                reason: `settings "permissions" is not an object — no bucket in this layer could be read, so it is reported as unread rather than as empty (it stays in the settings file either way)`,
+            });
+            continue;
+        }
+        for (const bucket of ["deny", "ask"]) {
+            const entries = permissions?.[bucket];
+            if (Array.isArray(entries))
+                denyAskBuckets[bucket] += entries.length;
+            else if (entries !== undefined && entries !== null) {
+                skipped.push({
+                    rule: layer.path,
+                    reason: `settings ${bucket} bucket is not an array — its entries could not be counted for the not-imported report (it stays in the settings file either way)`,
+                });
+            }
+        }
+        const allow = permissions?.allow;
         if (!Array.isArray(allow))
             continue;
         const scope = layer.layer === "userSettings" ? { kind: "global" } : { kind: "project", root: layer.root };
@@ -401,7 +426,7 @@ export async function prepareCcImport(opts) {
         createdAt: nowIso(opts.deps),
     };
     await opts.deps.approvals.create(record);
-    return { preview: { candidates, skipped, layers, uncovered: IMPORT_UNCOVERED }, approvalId: record.id };
+    return { preview: { candidates, skipped, layers, uncovered: { ...IMPORT_UNCOVERED_LAYERS, denyAskBuckets } }, approvalId: record.id };
 }
 export const STARTER_RULES = [
     "Bash(ls)",

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

@@ -29,7 +29,13 @@
  * here) and no leading-env-assignment stripping (`FOO=1 git status` simply does not match
  * `Bash(git status:*)`) — the last two are strict-side divergences from upstream, registered as such.
  */
-/** The one tool the v1 rule lane speaks for. The field exists on the rule so v2 can widen without a shape change. */
+/** The one tool the v1 rule lane speaks for. The field exists on the rule so v2 can widen without a shape change.
+ *
+ *  design/276 §3.3 (doctrine, for whoever widens this set): a future `SendMessage(…)`-form rule MAY
+ *  clear the peer-referral ask — that ask is classifier hesitation by construction (#144: allow rules
+ *  silence the classifier's questions, never a mandated one), so a recorded human yes is exactly what
+ *  clears it. The org/hook/matchedAskRule immunities stay: those conjuncts live in the gate's
+ *  persisted-rule lane and do not loosen with this set. */
 export type PersistedRuleTool = "Bash";
 /** v1 match forms. `"wildcard"` is reserved for v2 and is not a value this version ever produces. */
 export type PersistedRuleMatch = "exact" | "prefix";

package/dist/core/runner/prepare-config-doors.d.ts

@@ -107,6 +107,10 @@ export interface PrepareConfigDoorsResult {
         exclude: readonly string[] | undefined;
         defer: readonly string[] | undefined;
         alwaysLoad: readonly string[] | undefined;
+        /** design/277 — the model-gate restore selector ({@link TaskSpec.restoreGatedTools}), fourth
+         *  seat of the same frozen task-start snapshot: the gate decision and the delegation carrier
+         *  read THIS, never the live spec. */
+        restoreGated: readonly string[] | true | undefined;
     };
     /** owned — the profile half of the RB-50 single decision point (model-independent by contract). */
     promptProfile: "simple" | "classic";
@@ -127,6 +131,19 @@ export interface PrepareConfigDoorsResult {
     compModel: Model | undefined;
     /** owned — the mitigations half of the RB-50 decision point (model-family fact). */
     fableMitigations: boolean;
+    /** owned, frozen — design/277 model-gate DISCLOSURE data (the application itself already
+     *  happened on {@link spec}: its `tools` is the survivor rebind when anything was removed).
+     *  prepareTask emits the notices from this after the doors return (the onNotice station);
+     *  the doors stay side-effect-free on the announcement axis. */
+    modelGate: {
+        /** gate-class → removed wire names (sorted, unique); empty map = nothing removed. */
+        removedByClass: ReadonlyMap<string, readonly string[]>;
+        /** stamped classes with no merged-table row (inert tags, fail-open — announce material). */
+        unknownClasses: readonly string[];
+        /** a not-in-force `SEMA_TOOL_MODEL_GATE` value outside the closed set (discard-announce
+         *  material; the in-force arm never lands here — it throws at the door). */
+        discardedEnvRaw: string | undefined;
+    };
     /** owned — validated deployment governance windows (undefined = ungoverned). */
     usageWindows: readonly UsageWindow[] | undefined;
     /** owned, out-param cell — created EMPTY here; the brain-call wiring later installs into