@sema-agent/core 7.37.1 → 7.38.0

package/dist/core/session-reconcile.d.ts

@@ -16,9 +16,9 @@ import type { ToolEffect } from "./types.js";
  * Contract enforced here:
  *   - **Never auto-replay a tool.** Reconstruction (`buildSessionContext`) already does not re-run
  *     tools; this guarantees we also never synthesize a "success" that hides an unknown outcome.
- *   - For each orphan, append a synthetic `toolResult` (isError) that tells the model the call was
- *     interrupted and its outcome is unknown — making the transcript API-valid AND handing the
- *     decision to the model under its verification discipline.
+ *   - For each orphan an append can close (an id's last call site), append a synthetic `toolResult`
+ *     (isError) that tells the model the call was interrupted and its outcome is unknown — making the
+ *     transcript API-valid AND handing the decision to the model under its verification discipline.
  *   - Use the tool's {@link ToolEffect} to tune the message: `read` carries no risk at all; `idempotent`
  *     is replayable (re-issuing converges the state, but the interrupted attempt may have partially
  *     landed — RB-221); `write` (and unknown tools, conservatively) must be verified/confirmed
@@ -38,9 +38,9 @@ export interface OrphanToolCall {
      *   with a synthetic interrupted result).
      * - `"result"` = a **result-orphan**: a `toolResult` with no matching assistant `toolCall` — a
      *   protocol-invalid context every mainstream chat API rejects. The oracle used to walk only
-     *   assistant→result, so it reported a context in exactly this state as clean while the
-     *   request-time sweeper (`context-guard`'s `dropOrphanToolResults`) was silently deleting the
-     *   result. NOT reconcile-actionable (appending another result would not repair it); consumers
+     *   assistant→result, so it reported a context in exactly this state as clean while the request
+     *   builder dropped the result (the request view's tool-turn law leaves it out and announces it,
+     *   `orphan_result`). NOT reconcile-actionable (appending another result would not repair it); consumers
      *   deciding on repair must filter on this field.
      * Additive: absent = call-orphan, so pre-existing consumers and persisted expectations are
      * byte-identical for the historical direction.
@@ -153,7 +153,9 @@ export declare function interruptedResultMessage(result: InterruptedResult, time
 }>;
 /**
  * Reconcile a resumed session's active branch: close any orphan tool calls with a synthetic
- * interrupted `toolResult` (never re-running the tool). Returns what was recovered.
+ * interrupted `toolResult` (never re-running the tool) — the ones an append can close
+ * ({@link closableByAppend}), so a second reconcile of the same branch appends nothing. Returns what
+ * was recovered.
  *
  * @param toolEffects optional name→effect map (from the task's tools). Unknown names are treated as
  *   `write` — the conservative default, so an unrecognized interrupted call is never said to be safe.

package/dist/core/session-reconcile.js

@@ -124,9 +124,29 @@ export function interruptedResultMessage(result, timestamp) {
         timestamp,
     };
 }
+function closableByAppend(messages, suspendedBatch) {
+    const lastSite = new Map();
+    const lastResult = new Map();
+    let order = 0;
+    messages.forEach((m, i) => {
+        if (m.role === "assistant") {
+            for (const part of m.content) {
+                if (part.type === "toolCall" && !suspendedBatch?.has(part.id) && lastSite.get(part.id)?.at !== i)
+                    lastSite.set(part.id, { at: i, order: order++, toolName: part.name });
+            }
+        }
+        else if (m.role === "toolResult") {
+            lastResult.set(m.toolCallId, i);
+        }
+    });
+    return [...lastSite]
+        .filter(([id, site]) => (lastResult.get(id) ?? -1) < site.at)
+        .sort((a, b) => a[1].order - b[1].order)
+        .map(([toolCallId, site]) => ({ toolCallId, toolName: site.toolName }));
+}
 export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch, startedToolCallIds) {
     const { messages } = await session.buildContext();
-    const orphans = findOrphanToolCalls(messages, suspendedBatch).filter((o) => o.kind !== "result");
+    const orphans = closableByAppend(messages, suspendedBatch);
     const recovered = [];
     for (const result of interruptedResults(orphans, toolEffects, startedToolCallIds)) {
         const entryId = await session.appendMessage(interruptedResultMessage(result, Date.now()));

package/dist/core/shared-memory/types.js

@@ -1,6 +1,6 @@
 export const SHARED_MEMORY_LIST_TOOL_NAME = "memory_list";
 export const SHARED_MEMORY_READ_TOOL_NAME = "memory_read";
-export const SHARED_MEMORY_TOOL_NAMES = [SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_TOOL_NAME];
+export const SHARED_MEMORY_TOOL_NAMES = Object.freeze([SHARED_MEMORY_LIST_TOOL_NAME, SHARED_MEMORY_READ_TOOL_NAME]);
 export const SHARED_MEMORY_READ_CAP_BYTES = 102400;
 export const SHARED_MEMORY_LIST_PAGE_SIZE = 50;
 export const SHARED_MEMORY_MAX_STORES = 64;

package/dist/core/side-query.d.ts

@@ -47,7 +47,12 @@ export interface SideQuerySpec {
     modelRole?: ModelRole;
     thinking?: ThinkingLevel;
     systemPrompt?: string;
-    /** Full multi-turn message list (user/assistant/toolResult), passed to the brain UNFLATTENED. */
+    /** Full multi-turn message list (user/assistant/toolResult), passed to the brain UNFLATTENED — through the same
+     *  tool-turn law the harness applies to a session transcript (`ensureToolTurnInvariants`): an assistant's tool calls
+     *  become its trailing blocks, each call is followed by exactly one result, and a call this list leaves unanswered
+     *  (a trailing tool call, with the query's own prompt appended after it) is closed with a synthesized
+     *  "interrupted, outcome unknown" result and an operator notice. A caller that does not want that close answers or
+     *  drops the open call before handing the list over. The caller's array is not modified. */
     messages: SideQueryMessage[];
     /** Tool definitions the model may call in its reply. The engine NEVER executes them — any calls
      *  come back in `SideQueryResult.toolCalls` for the caller to interpret. */

package/dist/core/store-contracts/read-back-shape-contract.js

@@ -1,7 +1,7 @@
 import assert from "node:assert";
 import { thrownText } from "../thrown-value.js";
 import { beginContract } from "./contract-harness.js";
-export const CORRUPT_BODY_FORMS = ["not-an-object", "missing-required", "wrong-type", "torn-json"];
+export const CORRUPT_BODY_FORMS = Object.freeze(["not-an-object", "missing-required", "wrong-type", "torn-json"]);
 async function observe(subject) {
     try {
         const value = await subject.read();

package/dist/core/swappable-deps.js

@@ -1,6 +1,6 @@
 import { assertContainmentFaceValue } from "../tools/fs/containment-face.js";
 import { assertContextSettingsValue } from "./context-settings.js";
-export const SWAPPABLE_DEP_SEATS = ["models", "tiers", "readFace", "writeFace", "contextSettings"];
+export const SWAPPABLE_DEP_SEATS = Object.freeze(["models", "tiers", "readFace", "writeFace", "contextSettings"]);
 const SWAPPABLE_DEP_SEAT_SET = new Set(SWAPPABLE_DEP_SEATS);
 export function isSwappableDepSeat(k) {
     return SWAPPABLE_DEP_SEAT_SET.has(k);

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 { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
 import { buildCrossSessionEnvelope, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
-export const NOTIFICATION_INJECTION_OUTCOMES = ["queued", "parked", "parked_durably", "dropped_duplicate"];
+export const NOTIFICATION_INJECTION_OUTCOMES = Object.freeze(["queued", "parked", "parked_durably", "dropped_duplicate"]);
 export function isNotificationInjectionOutcome(value) {
     return typeof value === "string" && NOTIFICATION_INJECTION_OUTCOMES.includes(value);
 }
@@ -143,13 +143,13 @@ export const MAX_PENDING_EVENTS_PER_TASK = 50;
 export const MAX_PENDING_EVENTS_PER_SESSION = 200;
 export const MAX_PENDING_SESSIONS = 100;
 export const MAX_SESSION_BOX_BINDINGS = 4096;
-export const HANDBACK_STATES = ["send", "flagged", "withheld"];
+export const HANDBACK_STATES = Object.freeze(["send", "flagged", "withheld"]);
 export function handbackStateOf(facts) {
     if (facts.warning !== undefined)
         return "flagged";
     return facts.result || facts.partialText ? "send" : "withheld";
 }
-export const COMPACTION_KINDS = ["manual", "auto", "reactive"];
+export const COMPACTION_KINDS = Object.freeze(["manual", "auto", "reactive"]);
 export function compactionKindOf(trigger) {
     return trigger === "forced" ? "reactive" : trigger;
 }
@@ -161,7 +161,7 @@ export function terminalFrameFacets(facts) {
     };
 }
 export const ENGINE_FRAME_CODEC_VERSION = 1;
-export const ENGINE_FRAME_TASK_TYPES = ["background_agent", "monitor", "workflow"];
+export const ENGINE_FRAME_TASK_TYPES = Object.freeze(["background_agent", "monitor", "workflow"]);
 const SHELL_LESS_CARRIERS = ["agentMessage", "crossSessionMessage", "crossSessionNotice", "inboxNotice", "_sema_provenance"];
 export function isEngineFrameParkable(payload) {
     return ENGINE_FRAME_TASK_TYPES.includes(payload.task_type) && SHELL_LESS_CARRIERS.every((k) => payload[k] === undefined);

package/dist/core/task-registry-shared.js

@@ -101,7 +101,7 @@ export function spoolDropNote(acct) {
         return "[!] an unknown amount of earlier output was permanently dropped before this window (buffer evicted)\n";
     return "";
 }
-export const TASK_OUTPUT_REPLAY_KINDS = ["full", "cursor"];
+export const TASK_OUTPUT_REPLAY_KINDS = Object.freeze(["full", "cursor"]);
 export const REPLAY_FACE = {
     full: { stdout: "stdout (full, re-readable)", stdoutWhenGapped: "stdout (re-readable spool — INCOMPLETE, see note above)", stderr: "stderr" },
     cursor: { stdout: "new stdout", stdoutWhenGapped: undefined, stderr: "new stderr" },

package/dist/core/terminal-cause.d.ts

@@ -66,6 +66,17 @@ export type TerminalCause = {
     code?: string;
     /** Human-readable failure text. */
     message?: string;
+    /**
+     * A machine-readable account of the failure beside `code`, for the one shape a consumer offers its own way out
+     * of: `provider_rejected` — the provider REFUSED the request as sent (a 4xx answer) and that refusal named this
+     * result. `status` is the refusal's HTTP status (`TaskResult.apiFailure.status`, the same value);
+     * `code` the provider's own word for it from its error envelope (`AssistantMessage.apiErrorCode`), when it
+     * stated one. PRESENCE: only on that terminal — a run whose higher-ranked cause named the result, a 5xx, a
+     * connect / stream failure, an in-band error inside a 200 and every non-provider failure leave it absent.
+     * A 401 / 403 (credentials) and a 429 (rate limit) are refusals too: branch on `status` (or on `code` above)
+     * to tell a request a consumer may change and resend from one it may not.
+     */
+    detail?: TerminalFailureDetail;
     /**
      * The durable pause this failure STANDS IN FOR — set only by the nested hard boundary
      * (`mapNestedSuspend`): an orchestrator's nested leg paused on a durable gate, the orchestrator cannot
@@ -117,6 +128,14 @@ export type TerminalCause = {
      */
     restoreMode?: "snapshot" | "park_only";
 };
+/** The machine-readable account a `failed` cause may carry ({@link TerminalCause}). `kind` is closed; one member. */
+export interface TerminalFailureDetail {
+    kind: "provider_rejected";
+    /** The refusal's HTTP status, 400–499. */
+    status: number;
+    /** The provider's own word for the refusal (its error envelope's `error.code`, else `error.type`), when stated. */
+    code?: string;
+}
 /** The paused arm alone — the shape the run's committed-pause holder carries. */
 /**
  * The one disposition table over `TerminalCause["kind"]`: which causes a resume journal may REPLAY

package/dist/core/tool-face.js

@@ -1,9 +1,9 @@
-export const TOOL_FAMILIES = ["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"];
-export const TOOL_MOUNT_TAGS = ["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"];
-export const TOOL_APPROVAL_CARDS = ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"];
-export const TOOL_PATH_ACCESSES = ["read", "create", "edit"];
-export const TOOL_PATH_BASES = ["cwd", "root"];
-export const TOOL_PATH_ABSENCES = ["none", "base"];
+export const TOOL_FAMILIES = Object.freeze(["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"]);
+export const TOOL_MOUNT_TAGS = Object.freeze(["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"]);
+export const TOOL_APPROVAL_CARDS = Object.freeze(["file-edit", "file-write", "notebook-edit", "shell", "fetch", "plan", "question", "generic"]);
+export const TOOL_PATH_ACCESSES = Object.freeze(["read", "create", "edit"]);
+export const TOOL_PATH_BASES = Object.freeze(["cwd", "root"]);
+export const TOOL_PATH_ABSENCES = Object.freeze(["none", "base"]);
 export function pathTargetSlotOnly(pt) {
     return {
         param: pt.param,

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

@@ -1,6 +1,8 @@
 import { type AskOrigin, type AssertAllKeysHandled } from "./ask-origin.js";
 import { type ReadRootGrantScreen } from "./read-root-grant-screen.js";
 import { type Settlement } from "./gate-outcome.js";
+import { type DecisionReason } from "./decision-receipt.js";
+export { isEngineRefusal } from "./decision-receipt.js";
 /** A tool call presented to a policy before it executes. */
 /** design/388 B6 — the per-call face (see {@link ToolCallRequest.face}). */
 export interface ToolCallFace {
@@ -153,8 +155,9 @@ export declare function advertisedWritableRootsSeat(seat: {
 } | undefined): {
     advertisedWritableRoots?: readonly string[];
 };
-declare const DECISION_REASONS: readonly ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
-export type DecisionReason = (typeof DECISION_REASONS)[number];
+/** Declared beside the receipt's list (decision-receipt.ts) — a new member added to either side is a compile error rather
+ *  than a silent drift between the type and the screen; re-exported here, the module every consumer of the decision reads. */
+export type { DecisionReason };
 /** Carry every engine attestation from a decision onto a reconstruction of it — the
  *  seam for the engine's OWN clone sites outside this module (the inherited chain's final-form re-check carries the
  *  post-rewrite args on a spread of an ancestor's deny). Not re-exported from `src/index.ts`. */
@@ -621,8 +624,10 @@ export interface ToolPolicyProjection {
  * self-checks with those.
  */
 export declare function namespacedCoveringEntries(entries: readonly string[] | undefined): readonly string[];
-/** Does any covering entry reach `toolName`? See {@link namespacedCoveringEntries}. */
-export declare function namespacedCoveringHit(covering: readonly string[], toolName: string): boolean;
+/** Does any covering entry reach the call — under ANY name it answers to, the same reading the exact lists take through
+ *  `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;
 /**
  * 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
@@ -754,7 +759,7 @@ export declare const DECISION_MEMBERS: readonly DecisionMember[];
  * mode arbitration, the approval request, the rewrite that executes) reads the copy; a copy handed to the screen again
  * comes back as it is, unread. In order: (1) the CARRIER's type — a decision that is not an object (a string, a function
  * holding the members) has no `action`; (2) the ONE READ — ONE function ({@link receiveContract}) for the decision and for the
- * records it nests ({@link NESTED_CONTRACTS}), on an ORDINARY object (a Proxy, as the carrier or anywhere on its prototype
+ * records it nests (`receiveNestedRecords`, decision-receipt.ts), on an ORDINARY object (a Proxy, as the carrier or anywhere on its prototype
  * chain, is refused before a trap of its could run): each contract member absent or an own enumerable DATA property, its value
  * taken off the carrier's own descriptor (a member outside the contract is neither read nor carried — a policy's self-declared
  * record on another name finds no reader); any other spelling refused by name — an accessor (never invoked), a member the
@@ -762,7 +767,7 @@ export declare const DECISION_MEMBERS: readonly DecisionMember[];
  * descriptor, never read; (3) the retired `reason` field as an OWN property, judged without a read (authorship of the old
  * spelling: a prototype exposing it never wrote it; ignoring it silently dropped the policy's text); (4) the VALUES, off the engine's
  * one-read record, never a second read of the caller's object — the retired window absent, `action` in
- * {@link DECISION_ACTIONS} (a consumer ranks a decision by testing two of its words, so any other value used to rank as an
+ * its closed set (`screenContractValues`, decision-receipt.ts — every closed-set member is held to its set there; a consumer ranks a decision by testing two of its words, so any other value used to rank as an
  * allow; a `canUseTool` result outside its set is a failure in CC) and `decisionReason` in {@link DECISION_REASONS} when
  * present (absence stays legal); (5) the DETACH —
  * the contract members' values structured-cloned ({@link tryCloneArgs}; one that cannot be, a function inside a rewrite,
@@ -778,10 +783,12 @@ export declare const DECISION_MEMBERS: readonly DecisionMember[];
  * there is what is cloned and what runs — one read, consistent) and by a refusal's rendering of a foreign word (`String(v)` on an
  * out-of-set `action`, after the deny is decided). Same-process JavaScript has no trust boundary a function can enforce.
  *
- * `reasonIsNonInput` (the HOOK seam): a hook's `decisionReason` is DISCARDED there — every mint point downstream re-stamps
- * `"hook"`, and the seam maps a hook's deny and ask and reads anything else as no objection, the policy still adjudicating
- * the call — so that seam takes the two retired-field arms alone and its object back unchanged (`undefined` = no
- * opinion): refusing a value that cannot travel would fail-close a call over a field with no consumer.
+ * `reasonIsNonInput` (the HOOK seam): the same receipt, with the two differences the seam's consumers imply — a hook's
+ * `decisionReason` is DISCARDED there (every mint point downstream re-stamps `"hook"`) and so is not held to its set, and a
+ * hook result may leave `action` out (no opinion; the policy still adjudicates). `undefined`, `null` and `false` are no
+ * opinion (what a hook body yields when it has nothing to say). A refusal the receipt mints at this seam is the ENGINE's
+ * decision ({@link isEngineRefusal}) and exits through the engine's fail-closed arm (the deny observer), never as the hook's
+ * own deny.
  */
 export declare function refuseOutOfContractDecision(d: PermissionResult, opts?: {
     reasonIsNonInput?: boolean;
@@ -1780,4 +1787,3 @@ onLateSettlement?: (late: {
     kind: "error";
     error: unknown;
 }) => void): Promise<ResolvedAsk>;
-export {};

package/dist/core/tool-policy.js

@@ -13,7 +13,8 @@ import { boundInputHashOf } from "./canonical-json.js";
 import { delimitUntrusted, inlineUntrusted, REVIEWER_NOTE_MAX_BODY } from "./untrusted-text.js";
 import { describeRejectedValue } from "./tool-search-setting.js";
 import { thrownText } from "./thrown-value.js";
-import { receiveContract, refusedOutOfContract } from "./decision-receipt.js";
+import { nestedRecordsOf, receiveContract, receiveNestedRecords, refusedOutOfContract, screenContractValues } from "./decision-receipt.js";
+export { isEngineRefusal } from "./decision-receipt.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers, parsePermissionRule } from "./permission-rules.js";
 import { protocolOf } from "./protocol-table.js";
 import { isAbsoluteForFamily, isAbsolutePathForm, joinForFamily, normalizeAbsPathLexically, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
@@ -23,8 +24,6 @@ const shellToolsListHolds = (set, req) => heldBy("policy.shellToolsList", set, r
 export function advertisedWritableRootsSeat(seat) {
     return seat === undefined ? {} : { advertisedWritableRoots: Object.freeze([...seat.roots]) };
 }
-const DECISION_REASONS = ["rule", "mode", "hook", "safety", "classifier", "persisted_rule", "sandbox", "org_rule", "org_unavailable", "read_only"];
-const DECISION_REASON_SET = new Set(DECISION_REASONS);
 function settledByNobody(kind) {
     return { kind, who: { party: "none" }, when: Date.now() };
 }
@@ -164,20 +163,20 @@ export function toolPolicyWriteTargetGuard(policies) {
 export function namespacedCoveringEntries(entries) {
     return (entries ?? []).filter(isNamespacedCoveringRuleName);
 }
-export function namespacedCoveringHit(covering, toolName) {
-    return covering.length > 0 && covering.some((e) => namespacedRuleNameCovers(e, toolName));
+export function namespacedCoveringHit(covering, call) {
+    return covering.length > 0 && nameListHolds({ has: (name) => covering.some((e) => namespacedRuleNameCovers(e, name)) }, call);
 }
 export function checkToolPolicyProjection(projection, req) {
     const listed = (list) => heldBy("policy.projectionReplay", { has: (n) => list.includes(n) }, req);
     for (const c of projection.components) {
         if (c.kind === "tool_deny") {
-            if (listed(c.names) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
+            if (listed(c.names) || namespacedCoveringHit(namespacedCoveringEntries(c.names), req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by a frozen inherited policy projection` };
             }
             continue;
         }
         if (c.kind === "tool_allowlist") {
-            if (!listed(c.names) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req.toolName)) {
+            if (!listed(c.names) && !namespacedCoveringHit(namespacedCoveringEntries(c.names), req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in a frozen inherited policy projection's allowlist` };
             }
             continue;
@@ -247,87 +246,56 @@ export function constraintChainDigest(chain) {
 }
 const ALLOW = Object.freeze({ action: "allow" });
 const RETIRED_TEXT_FIELD = "reason";
-const RETIRED_WINDOW_MEMBER = "autoDenyAfterMs";
-const RETIRED_WINDOW_MEMBER_DENY_MESSAGE = `a permission decision's "denialLimitFallback" carries "${RETIRED_WINDOW_MEMBER}" — the decision names the counts only; ` +
-    `the auto-deny window is decided by the ask's route (a live approver arms it, every other route runs none) and cannot be ` +
-    `declared by a policy; denied fail-closed rather than silently replacing the declared number`;
-const carriesRetiredWindow = (fallback) => typeof fallback === "object" && fallback !== null && fallback[RETIRED_WINDOW_MEMBER] !== undefined;
-const DECISION_ACTIONS = Object.keys({ allow: 0, deny: 0, ask: 0 });
-const DECISION_ACTION_SET = new Set(DECISION_ACTIONS);
 export const DECISION_MEMBERS = Object.keys({
     action: 0, updatedInput: 0, message: 0, decisionReason: 0, requiresRealApproval: 0, denialLimitFallback: 0, persistedRuleShadowed: 0, probeReason: 0,
     probeCause: 0, probeMandated: 0, mandated: 0, mandate: 0, probeReadRootCandidate: 0, matchedAskRule: 0, ruleEvidence: 0, segmentCoverage: 0,
     origin: 0, askClass: 0, classes: 0, guard: 0, ruleUnreadable: 0, authoredBy: 0, foldedAskClasses: 0,
 });
-const OPERAND_MEMBERS = Object.keys({ shown: 0, total: 0 });
-const NESTED_CONTRACTS = [
-    ["", "denialLimitFallback", Object.keys({ consecutive: 0, total: 0, limit: 0, autoDenyAfterMs: 0 })],
-    ["", "probeCause", Object.keys({ code: 0, roots: 0, further: 0 })],
-    ["probeCause.", "roots", OPERAND_MEMBERS],
-    ["probeCause.", "further", OPERAND_MEMBERS],
-];
-const refusedAction = (what) => refusedOutOfContract(`a permission decision's "action" is ${what} — the closed set is ${DECISION_ACTIONS.join("/")}; denied fail-closed rather than reading a word outside it as an allow`);
-function renderForeignValue(v) {
-    try {
-        return JSON.stringify(String(v).slice(0, 64));
-    }
-    catch {
-        return `[unprintable ${typeof v}]`;
-    }
-}
+const HOOK_RESULT_MEMBERS = [...DECISION_MEMBERS, "additionalContext"];
+const HOOK_SEAM_UNREAD = new Set(["decisionReason"]);
+const HOOK_SEAM_OPTIONAL = new Set(["action"]);
+const HOOK_RECEIPTS = new WeakSet();
 const RETIRED_TEXT_FIELD_DENY_MESSAGE = `a permission decision carries the retired "${RETIRED_TEXT_FIELD}" field — rename it to "message" (the one text field ` +
     `a decision carries); denied fail-closed rather than executing a decision whose text this layer cannot read`;
 const ENGINE_RECEIPTS = new WeakSet();
 export function refuseOutOfContractDecision(d, opts) {
-    if (opts?.reasonIsNonInput === true) {
-        if (d === null || d === undefined)
-            return d;
-        if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD))
-            return refusedOutOfContract(RETIRED_TEXT_FIELD_DENY_MESSAGE);
-        return carriesRetiredWindow(d.denialLimitFallback) ? refusedOutOfContract(RETIRED_WINDOW_MEMBER_DENY_MESSAGE) : d;
+    const hookSeam = opts?.reasonIsNonInput === true;
+    if (hookSeam && (d === null || d === undefined || Object.is(d, false)))
+        return d;
+    if (typeof d !== "object" || d === null) {
+        return refusedOutOfContract(`a permission decision's "action" is absent (the decision is ${d === null || d === undefined ? String(d) : `a ${typeof d}`}, not an object) — the closed set is allow/deny/ask; denied fail-closed rather than reading a word outside it as an allow`);
     }
-    if (typeof d !== "object" || d === null)
-        return refusedAction(`absent (the decision is ${d === null || d === undefined ? String(d) : `a ${typeof d}`}, not an object)`);
-    if (ENGINE_RECEIPTS.has(d))
+    if ((hookSeam ? HOOK_RECEIPTS : ENGINE_RECEIPTS).has(d))
         return d;
-    const decision = receiveContract(d, DECISION_MEMBERS, "");
+    const decision = receiveContract(d, hookSeam ? HOOK_RESULT_MEMBERS : DECISION_MEMBERS, "");
     if (decision.kind === "refused")
         return decision.refused;
     if (Object.prototype.hasOwnProperty.call(d, RETIRED_TEXT_FIELD))
         return refusedOutOfContract(RETIRED_TEXT_FIELD_DENY_MESSAGE);
     const contract = decision.held;
-    const records = Object.assign(Object.create(null), { "": contract });
-    for (const [holder, member, members] of NESTED_CONTRACTS) {
-        const held = records[holder];
-        if (held === undefined || typeof held[member] !== "object" || held[member] === null)
-            continue;
-        const nested = receiveContract(held[member], members, `${holder}${member}.`);
-        if (nested.kind === "refused")
-            return nested.refused;
-        held[member] = records[`${holder}${member}.`] = nested.held;
-    }
-    if (carriesRetiredWindow(contract.denialLimitFallback))
-        return refusedOutOfContract(RETIRED_WINDOW_MEMBER_DENY_MESSAGE);
-    if (!DECISION_ACTION_SET.has(contract.action))
-        return refusedAction(contract.action === undefined ? "absent" : renderForeignValue(contract.action));
-    if (contract.decisionReason !== undefined && !DECISION_REASON_SET.has(contract.decisionReason)) {
-        return refusedOutOfContract(`a permission decision carries an unrecognized "decisionReason" value (${renderForeignValue(contract.decisionReason)}) — ` +
-            `the closed set is ${DECISION_REASONS.join("/")}; denied fail-closed rather than letting consumers branch on a value this layer cannot classify`);
+    const refused = receiveNestedRecords(contract) ?? screenContractValues(contract, hookSeam ? { skip: HOOK_SEAM_UNREAD, optional: HOOK_SEAM_OPTIONAL } : undefined);
+    if (refused !== undefined)
+        return refused;
+    if (hookSeam && contract.additionalContext !== undefined && typeof contract.additionalContext !== "string") {
+        return refusedOutOfContract(`a PreToolUse hook result's "additionalContext" is not a string — the member is the text appended for the model; denied fail-closed rather than rendering a value this layer cannot classify`);
     }
     const detached = tryCloneArgs(contract);
     if (!detached.ok) {
-        return refusedOutOfContract(`a permission decision's members could not be detached from the policy that returned them (${detached.reason}) — ` +
+        return refusedOutOfContract(`a permission decision's members could not be detached from the layer that returned them (${detached.reason}) — ` +
             `the engine keeps its own copy of what it read; denied fail-closed`);
     }
     const receipt = Object.freeze(detached.value);
-    const ownRecord = (o, k) => (typeof o === "object" && o !== null && Object.hasOwn(o, k) ? o[k] : undefined);
-    for (const [holder, member] of NESTED_CONTRACTS) {
-        const record = ownRecord(holder.split(".").filter(Boolean).reduce(ownRecord, receipt), member);
-        if (typeof record === "object" && record !== null)
-            Object.freeze(record);
+    for (const k of ["classes", "foldedAskClasses"])
+        if (Object.hasOwn(receipt, k) && Array.isArray(receipt[k]))
+            Object.freeze(receipt[k]);
+    for (const record of nestedRecordsOf(receipt)) {
+        for (const v of Object.values(record))
+            if (Array.isArray(v))
+                Object.freeze(v);
+        Object.freeze(record);
     }
     carryEngineAttestations(d, receipt);
-    ENGINE_RECEIPTS.add(receipt);
+    (hookSeam ? HOOK_RECEIPTS : ENGINE_RECEIPTS).add(receipt);
     return receipt;
 }
 const DEADLINE_ELAPSED = Symbol("approval.deadline_elapsed");
@@ -424,11 +392,10 @@ export function createAllowDenyPolicy(opts) {
         },
         nameSets: [{ ...(opts.allow ? { allow: [...opts.allow] } : {}), ...(opts.deny ? { deny: [...opts.deny] } : {}) }],
         check(req) {
-            const toolName = req.toolName;
-            if (nameListHolds(deny, req) || namespacedCoveringHit(denyCovering, toolName)) {
+            if (nameListHolds(deny, req) || namespacedCoveringHit(denyCovering, req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (allow && !nameListHolds(allow, req) && !namespacedCoveringHit(allowCovering, toolName)) {
+            if (allow && !nameListHolds(allow, req) && !namespacedCoveringHit(allowCovering, req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is not in the allowlist` };
             }
             return ALLOW;
@@ -464,11 +431,10 @@ export function createApprovalPolicy(opts) {
             },
         ],
         async check(req, signal) {
-            const toolName = req.toolName;
-            if (nameListHolds(deny, req) || namespacedCoveringHit(denyCovering, toolName)) {
+            if (nameListHolds(deny, req) || namespacedCoveringHit(denyCovering, req)) {
                 return { action: "deny", message: `tool "${req.toolName}" is denied by policy` };
             }
-            if (nameListHolds(need, req) || namespacedCoveringHit(needCovering, toolName)) {
+            if (nameListHolds(need, req) || namespacedCoveringHit(needCovering, req)) {
                 const attest = (d, settlement) => attestEngineSettlement(d, { settlement, origin: "policy" }, req);
                 if (signal?.aborted) {
                     return attest({ action: "deny", message: `approval aborted for "${req.toolName}" (run or turn interrupted)` }, settledByNobody("task_aborted"));
@@ -518,7 +484,7 @@ export function createApprovalPolicy(opts) {
                 }
                 return attest({ action: "deny", message: `approval denied for "${req.toolName}"` }, settledByPerson("human_refused", undefined));
             }
-            if (opts.denyByDefault && !nameListHolds(auto, req) && !namespacedCoveringHit(autoCovering, toolName)) {
+            if (opts.denyByDefault && !nameListHolds(auto, req) && !namespacedCoveringHit(autoCovering, req)) {
                 return { action: "deny", message: `tool "${req.toolName}" requires explicit allow` };
             }
             return ALLOW;
@@ -1051,7 +1017,7 @@ export function askApproverIdentity(onAsk) {
 export function isLiveApproverSeat(onAsk) {
     return typeof onAsk === "function";
 }
-export const DURABLE_MANDATE_SOURCES = ["force_durable_gate", "durable_approval"];
+export const DURABLE_MANDATE_SOURCES = Object.freeze(["force_durable_gate", "durable_approval"]);
 Object.freeze(DURABLE_MANDATE_SOURCES);
 export function durableMandateSourceOf(args) {
     if (args.forceDurableGate)

package/dist/core/tool-roster.js

@@ -11,7 +11,7 @@ const Name = Type.String({ minLength: 1, maxLength: TOOL_WIRE_NAME_MAX_CHARS });
 const Short = Type.String({ maxLength: TOOL_CONTRACT_MAX_CHARS });
 const Key = Type.String({ maxLength: TOOL_KEY_MAX_CHARS });
 const Digest16 = Type.String({ minLength: 16, maxLength: 16 });
-export const ROSTER_SOURCES = ["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"];
+export const ROSTER_SOURCES = Object.freeze(["builtin", "caller", "host", "mcp", "a2a", "external", "synthetic"]);
 export const ToolRosterRenderHints = Type.Object({
     userFacingName: Type.Optional(Type.String({ maxLength: RENDER_HINT_MAX_CHARS })),
     activity: Type.Optional(Type.String({ maxLength: RENDER_HINT_ACTIVITY_MAX_CHARS })),

package/dist/core/tool-search-setting.js

@@ -1,6 +1,6 @@
 export const TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT = 10;
 export const TOOL_SEARCH_INVALID_CODE = "config.tool_search_invalid";
-export const TOOL_SEARCH_POLICIES = ["always", "never", "auto"];
+export const TOOL_SEARCH_POLICIES = Object.freeze(["always", "never", "auto"]);
 export function resolveToolSearch(setting) {
     if (setting === undefined)
         return { policy: "auto", thresholdPercent: TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT, fraction: TOOL_SEARCH_DEFAULT_THRESHOLD_PERCENT / 100 };

package/dist/core/trace.d.ts

@@ -860,13 +860,14 @@ export type TraceEvent = {
 } | {
     /** A provider echo field was refused by {@link import("../brain/errors.js").PROVIDER_ECHO_SHAPE} (visible ASCII,
      *  1–128 characters) and dropped: the response's `request-id` / `x-request-id` header values (`field:
-     *  "requestId"`, read at connect — the id a failure would carry as `apiFailure.requestId`), or the model name
-     *  its frames report (`field: "responseModel"`). One frame per provider response per field; the value itself
-     *  is never carried (metadata-only). A count of these frames is this engine's drop count. */
+     *  "requestId"`, read at connect — the id a failure would carry as `apiFailure.requestId`), the model name
+     *  its frames report (`field: "responseModel"`), or the word a refusal's error envelope states (`field:
+     *  "apiErrorCode"`). One frame per provider response per field; the value itself is never carried
+     *  (metadata-only). A count of these frames is this engine's drop count. */
     kind: "brain.echo_dropped";
     version: 1;
     taskId: string;
-    field: "requestId" | "responseModel";
+    field: "requestId" | "responseModel" | "apiErrorCode";
     ts: number;
 } | {
     /** C10 — a `preemptSignal` fired on a task that is NOT resource-suspend-eligible: the preempt is a

package/dist/core/types.d.ts

@@ -29,6 +29,6 @@ export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js"
 export type { BackgroundChildEvent, DelegationLifecycleEvent } from "./delegation-frames.js";
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
 export type { ProjectMemoryLoad, ResumePreflightInfo, ResumePreflightVerdict, RunnerDeps } from "./runner-deps.js";
-export type { EngineNotice, OwedUserInputAccount } from "./engine-notice.js";
-export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, settleOwedUserInput, undrainedUserInputNotices } from "./engine-notice.js";
+export type { EngineNotice, OwedUserInputAccount, UserSteerUndrainedCause } from "./engine-notice.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, settleOwedUserInput, undrainedUserInputNotices, USER_STEER_UNDRAINED_CAUSES } from "./engine-notice.js";
 export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };

package/dist/core/types.js

@@ -1,4 +1,4 @@
 export { MODEL_ROLES } from "./model-seat.js";
 export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
 export { __resetMalformedDelegationSeatAnnouncement, deliverDelegationLifecycle } from "./delegation-frames.js";
-export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, settleOwedUserInput, undrainedUserInputNotices } from "./engine-notice.js";
+export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, settleOwedUserInput, undrainedUserInputNotices, USER_STEER_UNDRAINED_CAUSES } from "./engine-notice.js";

package/dist/core/wiring-manifest.js

@@ -5,8 +5,8 @@ import { canonicalize } from "./canonical-json.js";
 import { resolveCheckpointStore } from "./checkpoint-store.js";
 import { isLiveQuestionFace } from "./ask-question.js";
 import { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
-export const AUTO_MODE_ARM_REASONS = ["armed", "no_intent", "no_face", "denied", "resolver_fault"];
-export const LSP_LANES = ["tool", "diagnostics", "tool_and_diagnostics"];
+export const AUTO_MODE_ARM_REASONS = Object.freeze(["armed", "no_intent", "no_face", "denied", "resolver_fault"]);
+export const LSP_LANES = Object.freeze(["tool", "diagnostics", "tool_and_diagnostics"]);
 export function deriveHandsSeam(handsMounted) {
     return handsMounted ? { mounted: true } : { mounted: false, reason: "no_execution_env" };
 }

package/dist/core/write-protect.js

@@ -183,7 +183,7 @@ function relativeUnderDataRoot(path, roots) {
     }
     return null;
 }
-export const WRITE_PROTECTION_TARGET_VIEWS = ["spelling-only", "target"];
+export const WRITE_PROTECTION_TARGET_VIEWS = Object.freeze(["spelling-only", "target"]);
 export function compileWriteProtection(entries, opts) {
     const rows = resolveWriteProtectedTable(entries);
     if (rows.length === 0)