@sema-agent/core 7.51.2 → 7.53.0

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -1,6 +1,8 @@
 import { strict as assert } from "node:assert";
 import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
+import { PRINCIPAL_INBOX_HANDLE } from "../../agents/cross-session-ref.js";
+import { mintCrossPrincipalRecord } from "../../agents/org-delivery-gate.js";
 export const MAILBOX_CONTRACT_SCOPE = "default";
 const msg = (content, sentAt = 1000) => ({ content, sentAt });
 async function withStores(mk, fn) {
@@ -259,6 +261,17 @@ export async function mailboxBundledOnlyContract(mk, runAssertion) {
         await s.drop("tenant-b", "shared-handle");
         assert.equal(await s.peekCount("tenant-b", "shared-handle"), 0);
     });
+    run("第四条消费链(principal 收件箱):投递门铸的信落收件人 scope 的 principal.inbox,两只信任锚逐字节回读,发信方 scope 零残留", async (make) => {
+        const s = make();
+        const letter = mintCrossPrincipalRecord({ from: { scope: "principal-a", name: "alice" }, body: { content: "letter" }, receiptId: "gr-1", sentAt: 10_000, consumer: { kind: "terminals" } });
+        assert.equal(await s.append("principal-b", PRINCIPAL_INBOX_HANDLE, letter), 1);
+        assert.equal(await s.peekCount("principal-a", PRINCIPAL_INBOX_HANDLE), 0, "发信方 scope 的同名箱不得出现这封信");
+        const lease = await s.claimLease("principal-b", PRINCIPAL_INBOX_HANDLE, "drain:r1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.peerMeta), [{ kind: "peer_message", fromScope: "principal-a", gateReceiptId: "gr-1" }]);
+        assert.equal(lease.messages[0].from, "alice");
+        assert.deepEqual(await s.ack("principal-b", PRINCIPAL_INBOX_HANDLE, "drain:r1", lease.maxSeq), { acked: true });
+        assert.equal(await s.peekCount("principal-b", PRINCIPAL_INBOX_HANDLE), 0);
+    });
     await settle();
 }
 export async function mailboxCrossProcessContract(hooks) {

package/dist/core/task-event.d.ts

@@ -547,7 +547,14 @@ export type TaskEvent = ({
     /**
      * @contract tool_end.notExecuted — `true` when the engine has POSITIVE evidence this call never executed:
      * the loop closed it without running it (a sibling settled by a halted batch, a call a turn interrupt
-     * reached before it started) or an interrupted run's reconcile closed a call this run never started.
+     * reached before it started), an interrupted run's reconcile closed a call this run never started, or the
+     * engine's own judgment REFUSED the call and never let it go to its executor (a person's refusal, the host's
+     * SLA sweep, a policy or hook or plan-mode deny, a post-approval veto before the run — read off the call's
+     * occurrence: the latest {@link gate} record is `denied` and the life never reached the release). A refusal
+     * recorded AFTER the release (a station inside the execution, such as the shell read admission) is not
+     * evidence. The persisted `toolResult` row repeats the frame's mark as `details.notExecuted: true` (a live
+     * leg's rows, the resumed leg's and the reconcile's appended close) — the engine's key alone: a tool's own
+     * value under that name is dropped from the row.
      * ABSENT means only that no such evidence exists — never "it ran": a call closed with its outcome unknown
      * (a reconcile at the next process start, a call interrupted mid-execution) carries no mark, because
      * telling a consumer it did not run could invite a replay of a write that already took effect.
@@ -670,6 +677,10 @@ export type TaskEvent = ({
      *  pre-compaction context size. CC parity = `SDKCompactBoundary{trigger, pre_tokens, preserved_segment}`. */
     type: "compacted";
     trigger: "auto" | "manual" | "forced";
+    /** The pass this frame CONCLUDES — the value the pass's `compaction_started` frame carried. A landing is
+     *  always preceded by its start, so the engine sets it on every `compacted` frame; it is optional in the
+     *  type only so a literal a host builds by hand stays valid. */
+    pass?: string;
     tokensBefore: number;
     /** How much context this compaction FREED, as the engine measured it: one structural sum over
      *  the pre-messages minus the same sum over the post-messages, inside the pass. **The only
@@ -753,8 +764,12 @@ export type TaskEvent = ({
      *   or the rapid-refill breaker disabled compaction mid-task (`reason` says which). A spec
      *   that statically disables compaction does NOT produce one of these per boundary (that
      *   would be per-boundary noise about a static configuration, not a state change).
-     * - `"mooted"` — a manual request was processed but no boundary could serve it (dying loop /
-     *   caller cancel).
+     * - `"mooted"` — the pass did not run to its end: a manual request no boundary could serve
+     *   (`trigger:"manual"`, `reason:"task_ending"`), or a request withdrawn / a pass cut in flight by its
+     *   caller — a `compact({ signal })` withdrawal, `halt()`, `interrupt()`, `destroy()` or the task's own
+     *   `signal` (`reason:"cancelled"`), on any trigger: `"auto"`, `"manual"` or `"forced"`, or a turn-boundary
+     *   pass in flight that the task's own end cut — a limit, a timeout (`reason:"task_ending"`, with the
+     *   `pass` the start announced). Read `"mooted"` with its `trigger` — it is not a manual-only outcome.
      */
     type: "compaction_outcome";
     outcome: Exclude<CompactOutcome, "compacted"> | "suppressed";
@@ -762,6 +777,37 @@ export type TaskEvent = ({
     trigger: "auto" | "manual" | "forced";
     /** Optional human-readable detail (mirrors the trace frame's reason where one exists). */
     reason?: string;
+    /** The pass this frame CONCLUDES — the value its `compaction_started` frame carried. Present exactly when a
+     *  start was announced for the pass this frame ends, which makes it `failed` or `mooted` (a pass that ran its
+     *  summary call and did not land, or was cut while it ran). Absent on every outcome of a pass that never
+     *  started — `blocked`, `suppressed`, `disabled`, `noop`, a `mooted` request no boundary served — and on the
+     *  rapid-refill `disabled` frame, which reports a state the landing before it caused, not that pass's end. */
+    pass?: string;
+} & TaskEventIdentity) | ({
+    /**
+     * A compaction pass is under way: the engine has committed to it and is about to produce its summary.
+     * Until now compaction was announced only when it ended (`compacted`, or `compaction_outcome` for a pass
+     * that did not land), so a consumer watching a summary call wait out a provider's retries had nothing to
+     * show for the minutes in between.
+     *
+     * Minted at the one place a pass commits — after the trigger gate, a valid cut point and the
+     * `preCompact` hook (a blocking hook ends the pass before it starts), before the summary provider is
+     * consulted or the model is called — by every lane that compacts: the turn boundary (`"auto"`, `"manual"`,
+     * and `"forced"` under trim pressure), the prompt-too-long recovery and guard-chain arm B (`"forced"`), and
+     * the end-of-task summary (`"auto"`). Retries inside the pass's model call never mint a second one.
+     *
+     * Pairing: exactly one frame concludes each started pass, carrying the same `pass` — `compacted` when it
+     * lands, `compaction_outcome{failed | mooted}` when it does not. A pass that never reaches this point
+     * (`blocked`, `suppressed`, `disabled`, `noop`) announces nothing here and its outcome carries no `pass`.
+     * `pass` is unique across runs, so a consumer multiplexing several tasks on one stream pairs on `pass` alone.
+     */
+    type: "compaction_started";
+    /** Same three-state vocabulary (and the same value) the pass hands the `preCompact` hook and its concluding frame. */
+    trigger: "auto" | "manual" | "forced";
+    /** The pass's identity: an opaque engine-minted id (uuidv7), carried by the frame that concludes the pass. */
+    pass: string;
+    /** The engine clock (epoch ms) at the moment the pass committed. */
+    startedAt: number;
 } & TaskEventIdentity) | ({
     /**
      * TB telemetry B3: the engine injected a SYSTEM steering message (a deadline nudge

package/dist/core/task-notification.js

@@ -2,7 +2,7 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { escapeEnvelopeTag, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { egressText } from "./untrusted-egress.js";
 import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
-import { buildCrossSessionEnvelope, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
+import { buildCrossSessionEnvelope, CROSS_PRINCIPAL_MESSAGE_NOTICE, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
 export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(["completed", "failed", "killed", "cancelled"]);
 export const NOTIFICATION_INJECTION_OUTCOMES = Object.freeze(["queued", "parked", "parked_durably", "dropped_duplicate"]);
 export function isNotificationInjectionOutcome(value) {
@@ -88,7 +88,7 @@ export function renderAgentMessageFrame(frame) {
 }
 export function renderCrossSessionMessageFrame(frame) {
     const { body, ...fields } = frame;
-    return `${buildCrossSessionEnvelope(fields, body)}\n\n${CROSS_SESSION_MESSAGE_NOTICE}`;
+    return `${buildCrossSessionEnvelope(fields, body)}\n\n${fields.fromScope !== undefined ? CROSS_PRINCIPAL_MESSAGE_NOTICE : CROSS_SESSION_MESSAGE_NOTICE}`;
 }
 export function renderCrossSessionNoticeLine(notice) {
     return sanitizeUntrustedText(notice.text);

package/dist/core/task-result.d.ts

@@ -881,6 +881,14 @@ export interface TaskResult {
             /** Within-task compaction LLM cost (micro-USD) — part of `costMicroUsd`, so subtracted from root.
              *  ⚠️ See {@link llmRootMicroUsd}: under-reports prior slices' compaction on a multi-slice resource resume. */
             compactionMicroUsd: number;
+            /** The model calls made beside the main loop — the permission classifier's and mods' `$.model.complete` — in
+             *  micro-USD. An **"of which" line**, not a partition member: this cost is part of `costMicroUsd` and stays INSIDE
+             *  {@link llmRootMicroUsd}, so `llmRootMicroUsd + compactionMicroUsd === costMicroUsd` keeps holding. Present once
+             *  at least one such call was booked this leg (absent ⇒ none; a result with no such call is unchanged). A call
+             *  whose reply carried no usage marks `stats.usageMissing` instead of adding here.
+             *  ⚠️ Like {@link compactionMicroUsd}, per-leg on a multi-slice `resource_limit` RESUME: the prior slices' side-call
+             *  spend is inside the exact `costMicroUsd` and `llmRootMicroUsd` but not in this line. */
+            sideCallMicroUsd?: number;
         };
     };
 }

package/dist/core/task-spec.d.ts

@@ -296,11 +296,22 @@ export interface TaskSpec {
     compactionModel?: ModelRef;
     /** Thinking level. If omitted, a default from the resolved role's `RoleSpec.thinking` applies. */
     thinking?: ThinkingLevel;
-    /** Preset system prompt for this task. */
+    /** This task's role text: it replaces the selected role base (`promptRole`). Text carrying a locked section verbatim
+     *  (an already-assembled prompt) is refused by name (`prompt.assembled_role_refused`). */
     systemPrompt?: string;
+    /** The role base `core/role.base` selects: `"general"` (absent), `"code"`, `"coordinator"`, `"cowork"` (rendered from the
+     *  mounted tools and the working directory); `systemPrompt` replaces whichever is selected. Not inherited (a child gets
+     *  the sub-agent persona). A value outside the closed set is refused at prepare. */
+    promptRole?: "general" | "code" | "coordinator" | "cowork";
+    /** `"minimal"` leaves the core-behavior band out; the locked sections (mode sections in play among them) and
+     *  `appendSystemPrompt` stay. Absent ⇒ standard. Rides the parent spec seat to every engine-built child (a clamp-table
+     *  row: no child authors the standard form back). A value outside the closed set is refused at prepare. */
+    promptForm?: "minimal";
+    /** The deployment's binding (a scenario name): a prompt selector value, read by every overlay's `when.binding` (center, deploy and task alike); rides the parent spec seat; out of grammar (non-blank, ≤ 128 Unicode code points — `PROMPT_BINDING_MAX_CHARS`, counted `[...s].length`, not UTF-16 units) ⇒ `config.prompt_selector_invalid`. */
+    promptBinding?: string;
     /**
      * APPEND a caller block to the assembled system prompt, keeping the engine's base + harness/safety blocks
-     * (unlike `systemPrompt`, which REPLACES the base, and `promptProvider`, which rewrites the whole assembly).
+     * (unlike `systemPrompt`, which REPLACES the role base).
      * The lightweight user/scenario-extension seam (≈ CC `--append-system-prompt`): add task-specific rules,
      * domain context, or a persona tweak without losing the neutral base, cyber/url safety, harness context, or
      * memory discipline. CALLER-TRUSTED (same trust level as `systemPrompt`/`skills` — NOT user input). Composed
@@ -330,17 +341,6 @@ export interface TaskSpec {
         name: string;
         turnReminder?: string;
     };
-    /**
-     * Per-task ROLE-LAYER prompt provider (overrides `RunnerDeps.promptProvider`). Lets one Runner serve
-     * different scenarios with different role prompts. 提示词主权批: `stableSystem` supplies the role base
-     * only — core appends the constitution (harness/safety/mode/memory blocks) structurally, so a provider
-     * cannot drop it by accident; `replaceAll: true` is the explicit full-replacement escape hatch.
-     * TRUST BOUNDARY: a provider is function-valued and therefore CODE — it can only be set by in-process
-     * deployment code, never by a wire-level (JSON) task submission; untrusted self-orchestration specs
-     * additionally have this field stripped by workflow governance. The `prompt.assembled` trace records
-     * which mode ran, so a `replaceAll` is always observable.
-     */
-    promptProvider?: import("../prompts/default.js").PromptProvider;
     /**
      * Enable long-term memory for this task. **design/138 S4 (BREAKING): requires `RunnerDeps.memoryBackend`**
      * (the injection-first memory engine — materialize → file ops → harvest). With a backend configured the
@@ -614,8 +614,8 @@ export interface TaskSpec {
      * and a name nothing answers never fails the run): both lists are judged once, here and for the
      * delegation tool's own lists alike; a `denyTools` entry is read as the reference reads it
      * (`Tool(content)` hides the whole `Tool`, with a host notice); an entry whose spelling no tool name
-     * can have is REJECTED at task start (`config.agent.unknown_tool`); an entry naming a tool that does
-     * not exist (a server this deployment does not declare, a stale or misspelt name) is kept as written
+     * can have, or is another spelling of a tool the child is handed (a tool of the pool the delegation tool declares, or the engine's catalog: a case twin, a retired name with a successor: `"near_miss"`, while that pool can be listed), is REJECTED at task start (`config.agent.unknown_tool`); an entry naming a tool that does
+     * not exist (a server this deployment does not declare, a misspelt name) is kept as written
      * — it denies, or admits, a tool of that name if one is mounted later — and told to the host once
      * via `RunnerDeps.onError` phase `"config"` (zero model-facing warning); and
      * providing this field with NO delegation tool mounted is rejected too
@@ -656,10 +656,11 @@ export interface TaskSpec {
      * write-capable fs tools (CC's same gate); zero cost/behavior change otherwise. `false` opts out.
      */
     lspDiagnostics?: boolean;
-    /** In-process hooks for this task — the full `Hooks` lifecycle seam (tool pre/post/failure/batch
-     *  interception, prompt gating, stop pushback, compaction taps, permission-denied observation; each
-     *  member's contract is on the interface). Overrides `RunnerDeps.hooks`. */
-    hooks?: import("./hooks.js").Hooks;
+    /** The task seat of the mods bus — `user` tier only, beside `RunnerDeps.mods` (never instead); INTEGRATION §10. Its
+     *  registrations hang handlers on the `classic.*` events the engine's stations raise (tool pre/post/failure/batch,
+     *  prompt submit, stop, compaction, permission denied). A delegated child dispatches its parent's task seat as its own
+     *  (the parent spec seat fills an unset one). */
+    mods?: readonly import("./mods/kernel/index.js").ModRegistration<import("./mods/dollar.js").EngineDollar>[];
     /**
      * The session's SELF-REPORTED presence for the peer directory (`agent` = what it is, `intent` = what
      * it is doing; each ≤ 120 chars). The engine never writes a directory row: the same object goes out

package/dist/core/task-stream.d.ts

@@ -326,8 +326,12 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
     /**
      * Hard-**interrupt** the running task — a real abort (not a best-effort hint), equivalent to firing the
      * task's `signal` (design/47). Refused typed (`steering.not_running`, the steer-family liveness code —
-     * `cannot interrupt: …`) once the task has finished (the loop's end included: the teardown window
-     * refuses like `halt`/`steer` do), never silently dropped. **A run that has already given its answer
+     * `cannot interrupt: …`) once the task's result is out, never silently dropped. Until then it is
+     * answered — the teardown window after the loop's end included, where the consumer still sees a running
+     * task: the run's ONE caller-stop gate (this verb, {@link halt}, {@link destroy}, the task's `signal`)
+     * cuts any compaction pass still in flight — end-of-task, turn-boundary or prompt-too-long recovery,
+     * reported `compaction_outcome{outcome:"mooted", reason:"cancelled"}` with that pass's own `trigger` — and
+     * no further pass starts; a stop after the loop's end changes nothing else. **A run that has already given its answer
      * is not cancellable**: once its last turn ended `stopReason:"stop"` with no queued steer / follow-up
      * left to serve (a continuation the person had already asked for makes that "stop" work in progress,
      * not an answer), a stop landing on the run's
@@ -402,8 +406,12 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * naturally — nothing is cut and no boundary stops for it, so the result reports the natural
      * completion WITHOUT the `haltedByUser` seat and the engine mints `task.halt_unconsumed` (the
      * verb receipt and that notice are the halt's whole trace; the seat is signed from consumption,
-     * never from acceptance — see {@link TaskResult.haltedByUser}). Typed refusals: the
-     * steer-family `steering.not_running` once the task has finished (teardown included); a halt
+     * never from acceptance — see {@link TaskResult.haltedByUser}). A halt after the loop's end but before
+     * the result is out finds nothing to cut or stop and is answered the same way (`{turnCut:false}` +
+     * `task.halt_unconsumed`). Every answered halt trips the run's caller-stop gate: no compaction pass
+     * starts after it (the halted boundary's and the end-of-task pass included — the session's next run
+     * compacts at its own boundary) and a pass in flight is cut (see {@link interrupt}). Typed refusals: the
+     * steer-family `steering.not_running` once the task's result is out; a halt
      * issued BEFORE the run's first prompt polls the same bounded birth window as {@link steer} and
      * then stops the run before its first model turn (an empty, cleanly-halted completed run).
      *
@@ -428,6 +436,8 @@ export interface TaskStream extends AsyncIterable<TaskEvent> {
      * `AbortController.abort()` then `Promise.all(streams.map((s) => s.destroy()))`.
      *
      *  - **still running** → hard-interrupts it; the run's own `finish()` tears down its execution env.
+     *    It is a caller stop like {@link interrupt}: a compaction pass in flight (the run's tail included)
+     *    is cut, so the reap never waits out a summary call's retry schedule.
      *  - **suspended** (`status:"suspended"`) → `finish()` SKIPPED env teardown (the remote env was
      *    `suspendVM`-paused for a durable resume) and the checkpoint is committed → `destroy()` reaps BOTH:
      *    it CAS-**expires** the checkpoint (`CheckpointStore.expire`, fencing any concurrent resume) and —

package/dist/core/tighten-task-spec.d.ts

@@ -12,7 +12,7 @@ export declare class TaskSpecTightenError extends Error {
  *    the override can only ADD denials/asks). Either alone ⇒ that one. This is the central fix: a blind spread
  *    would drop the base policy entirely.
  *  - **every row of the clamp table** (`CLAMP_SET`: `handsReadOnly`, `interactiveTools`, `approvalReach`, the two
- *    containment faces, `readDenyPatterns`, `oneShot`, `memoryPersistenceCapable`, `fileHistory`) — a base carrying the
+ *    containment faces, `readDenyPatterns`, `oneShot`, `memoryPersistenceCapable`, `fileHistory`, `promptForm`) — a base carrying the
  *    row's restricting value meeting an override that states a different one ⇒ **throw** (loosening); otherwise the
  *    restricting value wins if either side carries it, an add-only list unions, and an override writing `undefined`
  *    erases nothing.
@@ -20,8 +20,9 @@ export declare class TaskSpecTightenError extends Error {
  *    be loosened because absence is the only other state and an override cannot unset a base value.
  *  - **`onAsk`** — no safe automatic merge (the approver and the policy must be coordinated). Both set to
  *    DIFFERENT values ⇒ **throw**; equal ⇒ keep; one set ⇒ that one.
- *  - **`hooks`** — no standard composition (stacking hook results is caller-specific). Both set ⇒ **throw**;
- *    one set ⇒ that one.
+ *  - **`mods`** — both set ⇒ both ride, base first then override (the task seat is a list and the bus composes it:
+ *    a registration only ever adds a handler to the chain; names stay unique, refused at admission otherwise).
+ *    One set ⇒ that one.
  *
  * @throws {TaskSpecTightenError} when an override would loosen a stricter base safety field, or when two
  * incompatible safety values are both set and cannot be merged automatically.

package/dist/core/tighten-task-spec.js

@@ -63,10 +63,8 @@ export function tightenTaskSpec(base, overrides) {
             "(the approver must be coordinated with the policy); set it in exactly one of base/overrides");
     }
     merged.onAsk = base.onAsk ?? overrides.onAsk;
-    if (base.hooks !== undefined && overrides.hooks !== undefined) {
-        throw new TaskSpecTightenError("tightenTaskSpec: hooks set on both base and overrides cannot be merged automatically " +
-            "(hook stacking is caller-specific); set hooks in exactly one of base/overrides, or compose them yourself");
+    if (base.mods !== undefined || overrides.mods !== undefined) {
+        merged.mods = [...(base.mods ?? []), ...(overrides.mods ?? [])];
     }
-    merged.hooks = base.hooks ?? overrides.hooks;
     return merged;
 }

package/dist/core/tool-check-reading.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The gate's reading of `tool.check`: the ONE comparison of an answer with the verdict standing where it was raised, and the
+ * raise over every chain a leg's gate is constrained by (its own bus, then each inherited installation), read by that one
+ * comparison. The lanes own the raise points and what each reading does to the pass; this module owns what an answer means.
+ */
+import type { PermissionResult, ToolCallRequest } from "./tool-policy.js";
+import type { AllowRuleShadow } from "./allow-rule-shadow.js";
+import { type InstallationAskSettlement, type ToolCheckOutcome, type ToolCheckProjection } from "./mods/stations.js";
+/** A verdict `tool.check` is raised over — never a deny (a standing refusal raises nothing). */
+export type ToolCheckStanding = Exclude<PermissionResult, {
+    action: "deny";
+}>;
+/** What a reading came to. `minted` on an ask: the reading minted it over an allow (the ask carries no stamp of the round yet).
+ *  `approved`: a person an inherited installation's question went to approved an edit of the call — the gate's approved-edit
+ *  pass takes it, as it takes an edit approved at this leg's own question. */
+export type ToolCheckReading = {
+    readonly kind: "stands";
+} | {
+    readonly kind: "denied";
+    readonly deny: PermissionResult;
+} | {
+    readonly kind: "asked";
+    readonly ask: Extract<PermissionResult, {
+        action: "ask";
+    }>;
+    readonly minted: boolean;
+    readonly marked?: true;
+} | {
+    readonly kind: "cleared";
+    readonly allow: Extract<PermissionResult, {
+        action: "allow";
+    }>;
+} | {
+    readonly kind: "shadowed";
+    readonly shadows: readonly AllowRuleShadow[];
+} | {
+    readonly kind: "approved";
+    readonly allow: Extract<PermissionResult, {
+        action: "allow";
+    }> & {
+        readonly updatedInput: unknown;
+    };
+    readonly outstanding?: Extract<PermissionResult, {
+        action: "ask";
+    }>;
+};
+/** The call a reading is about: its wire name, the args the check judged, the policy's rewrite riding a minted verdict, and the
+ *  request an inherited installation's question is settled over (the judged args). */
+export interface ToolCheckCall {
+    readonly toolName: string;
+    readonly judged: unknown;
+    readonly rewrite: unknown;
+    readonly request: ToolCallRequest;
+    readonly signal: AbortSignal | undefined;
+}
+/** One chain a gate raises `tool.check` on: its raise over a projection; for the leg's own bus only, the allow layer's
+ *  predicate under which its `allow` may clear an ask; for an inherited installation only, the settlement its question takes. */
+export interface ToolCheckChain {
+    readonly raise: (projection: ToolCheckProjection) => Promise<ToolCheckOutcome | undefined>;
+    readonly mayClear?: () => boolean;
+    readonly settle?: InstallationAskSettlement;
+}
+/**
+ * The raise over every chain the leg's gate is constrained by, read by the one comparison: the leg's own bus first (its `allow`
+ * may clear an ask where the allow layer may), then each inherited installation in order (its `allow` clears nothing — a
+ * constraint only tightens). Each chain is raised over the verdict the previous left standing (`project`); a refusal ends it.
+ * An inherited installation's `ask` is its own question, settled where its installation froze (`settle`, the settlement its
+ * `classic.PreToolUse` ask takes in the fold): refused ⇒ refused; approved ⇒ the verdict standing before it stands (this leg's
+ * own question, if any, is still this leg's); approved with an edit ⇒ `approved`, for the gate's approved-edit pass; floated
+ * (the call marked for the park) ⇒ asked. The reading of the whole is the last verdict the chains moved the call to — an ask
+ * keeps the disclosures any later `allow` made over it — else the disclosures alone, else it stands. Undefined when no chain
+ * raised (nothing hangs on the event).
+ */
+export declare function readToolChecks(chains: readonly ToolCheckChain[], standing: ToolCheckStanding, call: ToolCheckCall, project: (current: ToolCheckStanding, mayClear: (() => boolean) | undefined) => ToolCheckProjection): Promise<ToolCheckReading | undefined>;

package/dist/core/tool-check-reading.js

@@ -0,0 +1,80 @@
+import { refusalOf } from "./tool-policy.js";
+import { allowRuleShadowOf } from "./allow-entry.js";
+import { inlineUntrusted } from "./untrusted-text.js";
+import { failedHandlerClause } from "./mods/stations.js";
+const STANDS = Object.freeze({ kind: "stands" });
+function readToolCheck(heard, standing, call, mayClear) {
+    const { toolName } = call;
+    const refused = (message) => ({ kind: "denied", deny: refusalOf({ action: "deny", message, decisionReason: "hook" }, call.judged) });
+    if (heard.kind === "aborted")
+        return refused(`the task was cancelled while a tool.check handler was still checking this call to "${toolName}"; the call was NOT executed (fail-closed)`);
+    if (heard.kind === "failed")
+        return refused(`a tool.check handler ${failedHandlerClause(heard)} while checking this call to "${toolName}"; the call was NOT executed (fail-closed)`);
+    if (heard.by === undefined && heard.decision === standing.action)
+        return STANDS;
+    const { who, why } = speakerOf(heard);
+    const rewritten = call.rewrite !== undefined ? { updatedInput: call.rewrite } : {};
+    if (heard.decision === "deny")
+        return refused(`tool "${toolName}" denied by ${who}${why}`);
+    if (heard.decision === "ask") {
+        return standing.action === "ask"
+            ? { kind: "asked", ask: { ...standing, decisionReason: "hook", ...(heard.reason !== undefined ? { message: heard.reason } : {}) }, minted: false }
+            : { kind: "asked", ask: { ...questionOf(heard, toolName), ...rewritten }, minted: true };
+    }
+    if (standing.action === "allow")
+        return STANDS;
+    if (mayClear?.() === true)
+        return { kind: "cleared", allow: { action: "allow", message: `${who} allowed this call`, decisionReason: "hook", ...rewritten } };
+    return { kind: "shadowed", shadows: [allowRuleShadowOf("hook", heard.by !== undefined ? [heard.by] : [])] };
+}
+function speakerOf(heard) {
+    return { who: heard.by !== undefined ? `extension "${inlineUntrusted(heard.by, 80)}"` : "an extension", why: heard.reason !== undefined ? `: ${inlineUntrusted(heard.reason, 500)}` : "" };
+}
+function questionOf(heard, toolName) {
+    const { who, why } = speakerOf(heard);
+    return { action: "ask", message: `tool "${toolName}" needs approval (asked by ${who}${why})`, decisionReason: "hook" };
+}
+export async function readToolChecks(chains, standing, call, project) {
+    let raised = false;
+    let current = standing;
+    let moved;
+    const shadows = [];
+    for (const chain of chains) {
+        const heard = await chain.raise(project(current, chain.mayClear));
+        if (heard === undefined)
+            continue;
+        raised = true;
+        const reading = readToolCheck(heard, current, call, chain.mayClear);
+        if (reading.kind === "denied")
+            return reading;
+        if (reading.kind === "asked" && chain.settle !== undefined && heard.kind === "answered") {
+            const settled = await chain.settle(questionOf(heard, call.toolName), call.request, call.signal);
+            if (settled.action === "deny")
+                return { kind: "denied", deny: refusalOf(settled, call.judged) };
+            if (settled.action === "allow") {
+                if (settled.updatedInput !== undefined)
+                    return { kind: "approved", allow: { ...settled, updatedInput: settled.updatedInput }, ...(moved?.kind === "asked" ? { outstanding: moved.ask } : {}) };
+                continue;
+            }
+            const ask = current.action === "ask" ? current : settled;
+            moved = { kind: "asked", ask, minted: current.action !== "ask" || (moved?.kind === "asked" && moved.minted), marked: true };
+            current = ask;
+            continue;
+        }
+        if (reading.kind === "shadowed")
+            shadows.push(...reading.shadows);
+        if (reading.kind === "asked") {
+            moved = { ...reading, minted: reading.minted || (moved?.kind === "asked" && moved.minted), ...(moved?.kind === "asked" && moved.marked === true ? { marked: true } : {}) };
+            current = reading.ask;
+        }
+        if (reading.kind === "cleared") {
+            moved = reading;
+            current = reading.allow;
+        }
+    }
+    if (!raised)
+        return undefined;
+    if (moved?.kind === "asked" && shadows.length > 0)
+        return { ...moved, ask: { ...moved.ask, allowRuleShadowed: [...(moved.ask.allowRuleShadowed ?? []), ...shadows] } };
+    return moved ?? (shadows.length > 0 ? { kind: "shadowed", shadows } : STANDS);
+}

package/dist/core/tool-policy.d.ts

@@ -340,7 +340,7 @@ export type AskGuard = "dangerous_delete" | "unverifiable_delete" | "unverifiabl
  *    REPLACE the model's args before execution (re-validated against the tool schema first).
  *    `deny` may ALSO carry `updatedInput` (1.256 复审 MED-2): it never executes anything, but a
  *    combined-policy deny reports the ACCUMULATED pre-deny rewrite (policy A redacted → policy B
- *    denied) so a deny OBSERVER (`Hooks.permissionDenied`) sees the final post-rewrite args, not the
+ *    denied) so a deny OBSERVER (`classic.PermissionDenied`) sees the final post-rewrite args, not the
  *    stale un-redacted ones.
  *  - `ask` requests human confirmation; with no approver wired it resolves deterministically to deny
  *    (headless auto-deny, see `RunnerDeps.onAsk`). `requiresRealApproval: true` (RB-203
@@ -755,12 +755,23 @@ export declare function namespacedCoveringEntries(entries: readonly string[] | u
  *  `nameListHolds` (a covering entry and an exact entry in one list are one rule: it reaches the call iff its name is on the
  *  list)? See {@link namespacedCoveringEntries}. */
 export declare function namespacedCoveringHit(covering: readonly string[], call: Pick<ToolCallRequest, "toolName" | "face">): boolean;
+/**
+ * The tool names a projection component is keyed on, and the member that holds them: a `tool_deny` / `tool_allowlist`'s
+ * `names`, a `shell_command`'s `tools` (its `deny` / `allow` are command names, not tool names). A frozen chain holds them only
+ * in the one spelling a checkpoint row records a tool name in; the resume screen reads them back by it before anything replays.
+ */
+export declare function projectionToolNames(c: ToolPolicyProjectionComponent): {
+    readonly member: "names" | "tools";
+    readonly list: unknown;
+};
 /**
  * Execute a persisted {@link ToolPolicyProjection} against a call (F-012 L1): returns the first
  * component's deny, or `undefined` when the projection has no opinion (it is deny-only by
  * construction — never an allow, never an ask). This is what a durable RESUME runs instead of
  * trusting a re-supplied policy's execution half for the frozen deny data: the projection persisted
  * at suspend is the authority for what the chain refused, whatever a re-supplied closure claims.
+ * A tool name is matched as recorded, which is the rule syntax's reading only for a name in its canonical spelling: the resume
+ * screen refuses a frozen chain holding any other ({@link projectionToolNames}) before this runs on it.
  */
 export declare function checkToolPolicyProjection(projection: Pick<ToolPolicyProjection, "components">, req: Pick<ToolCallRequest, "toolName" | "args" | "face">): Extract<PermissionResult, {
     action: "deny";
@@ -920,20 +931,6 @@ export declare const DECISION_MEMBERS: readonly DecisionMember[];
 export declare function refuseOutOfContractDecision(d: PermissionResult, opts?: {
     reasonIsNonInput?: boolean;
 }): PermissionResult;
-/**
- * The PreToolUse hook seat's receipt under its public name — what a host that composes several hooks into the one the
- * engine takes runs on EACH slot's result before folding it, so it reads the result the way the engine will. It is
- * {@link refuseOutOfContractDecision} at the hook seam (`reasonIsNonInput`), the same function the engine's seat calls (hooks.ts
- * `screenPreToolUseResult`): no second statement of the contract.
- *
- * What comes back, for an object: the engine's own refusal (a `deny` for which {@link isEngineRefusal} is true — return it as the
- * composed hook's answer and the engine takes it as its own fail-closed deny), or the engine's frozen, detached copy of the
- * result (fold the copy, never the original). `undefined`, `null` and `false` are no opinion and come back as themselves. The
- * caller's object is not changed and none of its code runs; an answer handed back to this function returns as itself.
- */
-export declare function receiveHookResult(result: unknown): (PermissionResult & {
-    additionalContext?: string;
-}) | null | undefined | false;
 /** The raw tool-name lists a name-keyed policy was built from (audit feed, see block note above). */
 export interface ToolPolicyNameSets {
     readonly allow?: readonly string[];
@@ -953,15 +950,20 @@ export type NamedToolPolicy = ToolPolicy & {
 export declare function toolPolicyNameSets(p: ToolPolicy | undefined): readonly ToolPolicyNameSets[];
 /**
  * Name-based allow/deny. `deny` always wins. If `allow` is provided, only those tools are permitted
- * (everything else denied). Without `allow`, everything not in `deny` is permitted.
- * Carries {@link NamedToolPolicy.nameSets} so the host can audit the raw lists against the mounted
+ * (everything else denied). Without `allow`, everything not in `deny` is permitted. Each entry is read by the rule
+ * syntax (`ruleSpellingOf`): a name, or `Tool()` / `Tool(*)` — the bare `Tool`, as every list reader reads them, once however
+ * many spellings write it; any other spelling is not a tool name (`onInvalidName`), and neither is the wildcard `*` (`*`,
+ * `*()`, `*(*)`) in `deny`: it names no tool, and the entry would be kept and never match. In `allow` it is one entry no tool
+ * carries — the list admits what else it names, and nothing for it.
+ * Carries {@link NamedToolPolicy.nameSets} (the names as read) so the host can audit the lists against the mounted
  * pool ([c209-E] advisory); enforcement semantics are unchanged.
  */
 export declare function createAllowDenyPolicy(opts: {
     allow?: string[];
     deny?: string[];
     /**
-     * What to do with an entry that is not a tool NAME but a rule CONTENT form (`Bash(ps:*)`, `Edit(src/**)`).
+     * What to do with an entry that is not a tool NAME: a rule CONTENT form (`Bash(ps:*)`, `Edit(src/**)`), a spelling
+     * the rule syntax reads no tool name in (`" Bash"`, `Bash\t(*)`, `-deploy`), or the wildcard `*` in the deny list.
      * `"throw"` (default, matching {@link createPermissionRulePolicy}'s posture toward a rule it cannot
      * compile) refuses at construction; `"skip"` drops the entry and reports it. Under BOTH, the entry never
      * silently narrows the allowlist.
@@ -1838,6 +1840,48 @@ export declare function tryCloneArgs<T>(v: T): {
     reason: string;
     cause?: unknown;
 };
+/** The ONE mint of a refusal's reported args: the deny carrying the args its refusing station or layer JUDGED, which the gate's
+ *  exit reports (`finalInput`, the deny observer's `input`); a deny already carrying the args its own layers judged (a composed
+ *  chain's, nested ones included) keeps them. Read by the gate's lanes and by {@link combinePolicies}. Only a deny is changed. */
+export declare function refusalOf<D extends PermissionResult>(deny: D, judged: unknown): D;
+/**
+ * A PreToolUse hook's `ask` folded over a verdict by `deny > ask > allow` — the ONE law for the gate's first screening and for
+ * an approved edit's re-screen. A deny stands. Over an allow, the hook's own ask, RECONSTRUCTED rather than spread (its message,
+ * its real-approval demand, its rewrite) under the hook provenance the engine stamps. Over an ask, that ask keeps every member,
+ * takes the hook provenance and the hook's real-approval demand, and its message carries the hook's beside its own — a person
+ * clearing one ask that stands for two gates sees both reasons.
+ */
+export declare function foldHookAsk(verdict: Exclude<PermissionResult, {
+    action: "deny";
+}>, hookAsk: Extract<PermissionResult, {
+    action: "ask";
+}>): Extract<PermissionResult, {
+    action: "ask";
+}>;
+export declare function foldHookAsk(verdict: PermissionResult, hookAsk: Extract<PermissionResult, {
+    action: "ask";
+}>): PermissionResult;
+/**
+ * THE args of one tool-gate pass — what every judge of the call reads and what the call runs with: ONE engine-owned
+ * value, the {@link tryCloneArgs} snapshot of what was handed in, deep-frozen. The gate mints it at its entry from the
+ * model's args, and every value that replaces it comes through here too (a hook's or a policy's rewrite at the decision
+ * receipt, a person's edit at the approver's answer), so the args of a pass are always such a value. Because it cannot
+ * change, it is handed to every judge as it is — a policy, the org and stored-rule lanes, the classifier, an extension's
+ * check, the person's card — and none of them can make what runs differ from what was judged: an in-place write throws
+ * (a rewrite is an answer's `updatedInput`). An owned value handed back is itself; a primitive is immutable as it is.
+ * A value the snapshot refuses is refused the same way (exotic args are a refusal, never a shared reference).
+ */
+export declare function ownArgs<T>(v: T, root?: string): {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    reason: string;
+    cause?: unknown;
+};
+/** A call's argument reading (the loop's: the tool's preparation, the schema's coercions) whose every value is engine-owned
+ *  like a pass's args ({@link ownArgs}) — the gate's face seat and the resumed call's belt seat read through this one. */
+export declare function ownedReading(read: (args: unknown) => unknown): (args: unknown) => unknown;
 /**
  * A label for a value that was THROWN at us, safe to put in a fail-closed refusal. Never coerces: `String(x)`
  * throws on a null-prototype object or a untrusted `toString`/`Symbol.toPrimitive`, and the thrower here is