@sema-agent/core 5.49.0 → 5.51.0

package/dist/brain/reasoning.d.ts

@@ -16,6 +16,29 @@ import type { ThinkingLevel } from "../internal/harness-types.js";
 export type ReasoningIntensity = ThinkingLevel;
 /** Type guard: is `v` one of the 7 {@link ThinkingLevel} tiers? (A legacy/unknown reasoning string is not.) */
 export declare function isThinkingLevel(v: unknown): v is ThinkingLevel;
+/**
+ * THE thinking-request ENTRY predicate — does this request enter an applier's emission path at all?
+ * One conjunction, three arms: the model declares reasoning (TRUTHINESS — the adapters' own
+ * judgment, see the r5 note in {@link resolveReasoning}), the requested value is a real
+ * {@link ThinkingLevel} (an out-of-contract value — a typo'd tier, a caller's own enum — reads as
+ * ABSENCE, never as a declared tier), and it is not the explicit `"off"`.
+ *
+ * ENTRY gate, deliberately NOT an emitted-a-key guarantee: past this gate the per-FORMAT arms still
+ * decide what (if anything) lands on the wire — `supportsReasoningEffort:false` on a format whose
+ * only carrier is the effort key, a `null` levelmap entry, the binary enable keys. Those arms have
+ * their own reporting shape (the `graded:false` intent-echo family, each pinned with its rationale
+ * where it lives); this predicate only closes the gate the three appliers used to re-spell.
+ *
+ * Single-sourced here because every wire applier (openai.ts `applyThinking`, anthropic.ts's thinking
+ * + effort arms, open-responses.ts `resolveWireEffort`) used to re-spell the same three conjuncts —
+ * and the REPORTING resolver ({@link resolveReasoning}) mirrored only ONE of them (`!model.reasoning`),
+ * so a garbage tier put ZERO parameters on the wire while the resolution claimed a clamped-to-minimal
+ * gradient (or echoed the garbage string as `effective` on binary formats). A predicate the appliers
+ * and the reporter both call cannot drift.
+ */
+export declare function reasoningRequestCarried(model: {
+    reasoning?: boolean;
+}, reasoning: unknown): reasoning is ThinkingLevel;
 /** Ordinal rank of a level (`off`=0 … `max`=6). */
 export declare function rankOf(level: ThinkingLevel): number;
 /**
@@ -65,6 +88,66 @@ export interface ReasoningResolution {
     /** True when {@link effective} differs from {@link requested} (the request couldn't be honored exactly). */
     clamped: boolean;
 }
+/** Anthropic's hard floor for an extended-thinking budget. Lives HERE (not the anthropic brain) so
+ *  the cap-wins predicate below and the brain's budget-window math read ONE constant. */
+export declare const MIN_THINKING_TOKENS = 1024;
+/**
+ * The anthropic BUDGET path's cap-wins arm (#346, single-sourced; design/119 #2 review codex H4):
+ * a HARD per-request output cap (an engine-imposed override or the caller's explicit
+ * `options.maxTokens` — the two lanes the brain refuses to raise) too small to host a legal thinking
+ * budget (≥ {@link MIN_THINKING_TOKENS}) plus answer room means the CAP WINS and thinking is skipped
+ * for the request. Shared by the wire arm (anthropic.ts, which acts on it) and
+ * {@link resolveReasoning}'s budget arm (which mirrors it when the caller supplies the request
+ * facts), so the skip decision and its report are one predicate — the reporter's budget arm used to
+ * claim an unconditional `graded:true` gradient while this arm deleted the thinking block from the
+ * very request it described. A soft (model/config-sourced) cap never skips: the brain raises it to
+ * host the budget instead (`hardCap === false`).
+ */
+export declare function budgetCapSkipsThinking(outputCapTokens: number, hardCap: boolean): boolean;
+/**
+ * OPTIONAL per-request facts for {@link resolveReasoning} — what the wire's budget arm knows at
+ * request build that a per-leg eager resolution cannot: the resolved output cap and whether it is a
+ * HARD bound. Supplied ⇒ the anthropic budget arm mirrors the wire's cap-wins skip
+ * ({@link budgetCapSkipsThinking}); absent ⇒ the budget arm reports the cap-blind gradient it always
+ * did (the eager per-leg trace/result mint has no request facts — a capped request's per-attempt skip
+ * is visible only to a caller that passes them).
+ */
+export interface ReasoningWireFacts {
+    /** The request's resolved output cap (the wire `max_tokens` at the moment the thinking arm judges). */
+    outputCapTokens: number;
+    /** True when the cap is HARD (engine override / caller `options.maxTokens`) — the lanes the brain
+     *  refuses to raise; a soft model/config cap is raised to host the budget instead. */
+    hardOutputCap: boolean;
+}
+/**
+ * The anthropic-`effortLevels` PRESENCE/SHAPE gate, shared by the wire arm (anthropic.ts) and the
+ * reporting dispatch below so the two cannot disagree about which family a request rides (#335): the
+ * old twin predicates were `x && x.length > 0` on both sides, so a truthy NON-ARRAY (a string —
+ * `.length > 0` holds) entered the wire arm and threw a bare TypeError from its `.filter` pre-clean
+ * BEFORE {@link resolveEffort}'s centralized non-array fallback could read it as undeclared — while
+ * the reporter happily described an effort resolution for the same config. Only the container shape
+ * is judged here; MEMBER validity stays {@link resolveEffort}'s job (its element-level sanitization
+ * is the single bad-value seat, which is also why the returned array is not member-checked — the cast
+ * is checked at runtime by every consumer's `resolveEffort` call).
+ */
+export declare function declaredEffortLevels(v: unknown): readonly ThinkingLevel[] | undefined;
+/**
+ * The effort-lane WIRE-VALUE mint — clamp ({@link resolveEffort}) + the `Model.thinkingLevelMap`
+ * translation in ONE place, consumed by both completions-family appliers (openai.ts `applyThinking`,
+ * open-responses.ts `resolveWireEffort`) AND the reporting dispatch ({@link resolveReasoning}'s
+ * arms), so the value that reaches the wire and the resolution a trace/result face claims are two
+ * reads of one computation, never parallel re-derivations. Map semantics (the field's contract): a
+ * MISSING key ⇒ provider default (the clamped tier name as-is); a STRING ⇒ that provider-specific
+ * spelling (same tier, still honored); `null` ⇒ the tier is UNSUPPORTED on this model —
+ * `wireValue: undefined`, no effort value on the wire (thinking still enables via a format's own
+ * enable key where one exists), which is exactly the tier-not-honored shape the reporter must echo.
+ */
+export declare function mintEffortWireValue(requested: ThinkingLevel, model: {
+    thinkingLevelMap?: Readonly<Partial<Record<ThinkingLevel, string | null>>>;
+}, allowed: readonly ThinkingLevel[] | undefined): {
+    resolution: ReasoningResolution;
+    wireValue: string | undefined;
+};
 /**
  * A {@link ReasoningResolution} enriched with the endpoint discriminant, for observability (design/96 S6).
  * The brain consumes only the {@link ReasoningResolution} fields to shape the request; `format`/`endpoint`
@@ -77,9 +160,12 @@ export interface ResolvedReasoning extends ReasoningResolution {
     /** A coarse endpoint label for the trace (`model.api` — e.g. `openai-completions`, `anthropic-messages`). */
     endpoint: string;
     /**
-     * Present (true) only when the model declares NO reasoning capability (`Model.reasoning` falsy): every
-     * brain early-returns on that flag (openai.ts applyThinking / anthropic.ts / open-responses.ts
-     * resolveWireEffort), so NO thinking
+     * Present (true) only when the request never CARRIES at all: {@link reasoningRequestCarried} false
+     * on a non-"off" request — the model declares NO reasoning capability (`Model.reasoning` falsy),
+     * OR the requested value is not a valid {@link ThinkingLevel} (an out-of-contract tier every wire
+     * applier reads as ABSENCE — the same three-conjunct gate all of them share) — or, with
+     * {@link ReasoningWireFacts} supplied, the anthropic budget path's cap-wins skip
+     * ({@link budgetCapSkipsThinking}), so NO thinking
      * parameter reaches the wire at all — the requested tier is DROPPED entirely, not clamped or
      * downgraded-to-binary. `effective:"off"` here states the ENGINE side of that fact (nothing was
      * requested), NOT a measured gateway state: on the binary enable-only formats (qwen / zai /
@@ -101,7 +187,10 @@ export interface ResolvedReasoning extends ReasoningResolution {
  * brains keep calling {@link resolveEffort}/{@link resolveBinary}/{@link reasoningBudgetShare} on the hot path.
  *
  * - Anthropic (`api === "anthropic-messages"`) → budget-based: the tier sets a budget share, so it's a real
- *   gradient (`graded:true`) and never tier-clamped (`clamped:false`); reported as `format:"budget"`.
+ *   gradient (`graded:true`) and never tier-clamped (`clamped:false`); reported as `format:"budget"`. With
+ *   the optional {@link ReasoningWireFacts} the arm additionally mirrors the wire's cap-wins skip
+ *   ({@link budgetCapSkipsThinking}: a hard per-request output cap < 2·{@link MIN_THINKING_TOKENS} deletes
+ *   the thinking block) as the drop shape — facts absent keeps the historic cap-blind gradient.
  * - Binary enable-only formats (qwen / zai / qwen-chat-template) → `graded:false` (tier not honored).
  * - An effort endpoint with `supportsReasoningEffort:false` → `graded:false` (enable key only, no effort tier).
  * - Otherwise effort-based → clamp DOWN to the endpoint's `reasoningEffortLevels` (default minimal|low|medium|high).
@@ -111,11 +200,14 @@ export interface ResolvedReasoning extends ReasoningResolution {
  *   honored. Previously this resolver never read the map and reported such a request as exactly honored
  *   (`graded:true`, `clamped:false`) while the wire dropped the value — trace/result-face drift.
  *
- * - A model whose `reasoning` capability flag is FALSY drops the request ENTIRELY (neither brain emits any
- *   thinking parameter, whatever the format) → `effective:"off"`, `graded:false`, `clamped:true`,
+ * - A request that never CARRIES ({@link reasoningRequestCarried} false on a non-"off" value: the model's
+ *   `reasoning` capability flag is FALSY, or the requested value is not a valid tier — no brain emits any
+ *   thinking parameter for either, whatever the format) → `effective:"off"`, `graded:false`, `clamped:true`,
  *   `dropped:true` — the loud-drop arm. Previously this resolver described the capability dispatch for such
  *   a model (a resolution the request never carried), and the runner's trace guard skipped the frame — the
- *   one arm where the request evaporates was the one arm with no disclosure.
+ *   one arm where the request evaporates was the one arm with no disclosure; and an out-of-contract tier
+ *   was worse still — reported as a clamped-to-minimal gradient (or echoed verbatim as `effective` on the
+ *   binary formats) while the wire carried nothing.
  *
  * `off`/falsy never enables thinking, so it resolves trivially (no clamp, graded:true) — the caller decides
  * whether to emit at all.
@@ -125,7 +217,7 @@ export declare function resolveReasoning(requested: ThinkingLevel, model: {
     reasoning?: boolean;
     compat?: unknown;
     thinkingLevelMap?: Readonly<Partial<Record<ThinkingLevel, string | null>>>;
-}): ResolvedReasoning;
+}, facts?: ReasoningWireFacts): ResolvedReasoning;
 /**
  * Resolve a requested intensity for an effort-based endpoint (`reasoning_effort` / `reasoning.effort`). Picks
  * the requested tier when supported; otherwise the highest supported tier ≤ requested (clamp DOWN, never

package/dist/brain/reasoning.js

@@ -10,28 +10,52 @@ const RANK = {
 export function isThinkingLevel(v) {
     return typeof v === "string" && Object.prototype.hasOwnProperty.call(RANK, v);
 }
+export function reasoningRequestCarried(model, reasoning) {
+    return !!model.reasoning && isThinkingLevel(reasoning) && reasoning !== "off";
+}
 export function rankOf(level) {
     return RANK[level];
 }
 export const DEFAULT_EFFORT_LEVELS = ["minimal", "low", "medium", "high"];
 const BINARY_FORMATS = new Set(["qwen", "zai", "qwen-chat-template"]);
 export const RESPONSES_APIS = new Set(["openai-responses", "azure-openai-responses", "openai-chatgpt-responses"]);
-export function resolveReasoning(requested, model) {
-    const resolved = dispatchReasoning(requested, model);
-    if (requested !== "off" && !model.reasoning) {
+export const MIN_THINKING_TOKENS = 1024;
+export function budgetCapSkipsThinking(outputCapTokens, hardCap) {
+    return hardCap && outputCapTokens < MIN_THINKING_TOKENS * 2;
+}
+export function declaredEffortLevels(v) {
+    return Array.isArray(v) && v.length > 0 ? v : undefined;
+}
+export function mintEffortWireValue(requested, model, allowed) {
+    const resolution = resolveEffort(requested, allowed ?? DEFAULT_EFFORT_LEVELS);
+    let wireValue = resolution.effective;
+    const mapped = model.thinkingLevelMap?.[resolution.effective];
+    if (mapped === null)
+        wireValue = undefined;
+    else if (mapped !== undefined)
+        wireValue = mapped;
+    return { resolution, wireValue };
+}
+export function resolveReasoning(requested, model, facts) {
+    const resolved = dispatchReasoning(requested, model, facts);
+    if (requested !== "off" && !reasoningRequestCarried(model, requested)) {
         return { requested, effective: "off", graded: false, clamped: true, format: resolved.format, endpoint: resolved.endpoint, dropped: true };
     }
     return resolved;
 }
-function effortTierUnmapped(requested, effective, model) {
-    return requested !== "off" && model.thinkingLevelMap?.[effective] === null;
-}
-function dispatchReasoning(requested, model) {
+function dispatchReasoning(requested, model, facts) {
     const endpoint = model.api ?? "unknown";
     const compat = (model.compat ?? {});
     if (model.api === "anthropic-messages") {
-        if (compat.effortLevels && compat.effortLevels.length > 0) {
-            return { ...resolveEffort(requested, compat.effortLevels), format: "effort", endpoint };
+        const declaredAnthropic = declaredEffortLevels(compat.effortLevels);
+        if (declaredAnthropic !== undefined) {
+            return { ...resolveEffort(requested, declaredAnthropic), format: "effort", endpoint };
+        }
+        if (requested !== "off" &&
+            compat.thinkingMode !== "adaptive" &&
+            facts !== undefined &&
+            budgetCapSkipsThinking(facts.outputCapTokens, facts.hardOutputCap)) {
+            return { requested, effective: "off", graded: false, clamped: true, format: "budget", endpoint, dropped: true };
         }
         return { requested, effective: requested, graded: true, clamped: false, format: "budget", endpoint };
     }
@@ -39,11 +63,11 @@ function dispatchReasoning(requested, model) {
         if (compat.supportsReasoningEffort === false) {
             return { requested, effective: requested, graded: false, clamped: false, format: "responses", endpoint };
         }
-        const responsesResolved = resolveEffort(requested, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS);
-        if (effortTierUnmapped(requested, responsesResolved.effective, model)) {
+        const responsesMint = mintEffortWireValue(requested, model, compat.reasoningEffortLevels);
+        if (requested !== "off" && responsesMint.wireValue === undefined) {
             return { requested, effective: requested, graded: false, clamped: false, format: "responses", endpoint };
         }
-        return { ...responsesResolved, format: "responses", endpoint };
+        return { ...responsesMint.resolution, format: "responses", endpoint };
     }
     const format = compat.thinkingFormat ?? "openai";
     if (BINARY_FORMATS.has(format)) {
@@ -53,11 +77,11 @@ function dispatchReasoning(requested, model) {
     if (!supportsEffort && format !== "openrouter") {
         return { requested, effective: requested, graded: false, clamped: false, format, endpoint };
     }
-    const resolved = resolveEffort(requested, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS);
-    if (effortTierUnmapped(requested, resolved.effective, model)) {
+    const mint = mintEffortWireValue(requested, model, compat.reasoningEffortLevels);
+    if (requested !== "off" && mint.wireValue === undefined) {
         return { requested, effective: requested, graded: false, clamped: false, format, endpoint };
     }
-    return { ...resolved, format, endpoint };
+    return { ...mint.resolution, format, endpoint };
 }
 export function resolveEffort(requested, allowed = DEFAULT_EFFORT_LEVELS) {
     const declared = Array.isArray(allowed) ? allowed.filter((lvl) => isThinkingLevel(lvl) && lvl !== "off") : [];

package/dist/brain/request-params.d.ts

@@ -23,7 +23,7 @@ export declare function reservedFor(api: string): ReadonlySet<string>;
  */
 export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): Record<string, unknown>;
 /**
- * [1282] per-call auth REPLACES construction-time auth: drop every auth-bearing header
+ * Per-call auth REPLACES construction-time auth: drop every auth-bearing header
  * (case-insensitive `authorization` / `x-api-key`) from an already-merged header bag. Called by a
  * brain's buildRequest ONLY when a per-call `options.apiKey` is present — the brain then re-emits
  * the credential in its own wire posture (anthropic `x-api-key`, openai `Bearer`), making the
@@ -33,6 +33,42 @@ export declare function applyExtraBody(body: Record<string, unknown>, extraBody:
  * folds duplicates into one comma-joined value — broken auth both ways).
  */
 export declare function stripAuthHeaders(headers: Record<string, string>): void;
+/**
+ * #343 — the shared USER-HEADER merge layer (`model.headers` → construction `config.headers` →
+ * per-call `options.headers`, later bag wins), CASE-FOLD deduplicated: HTTP header field names are
+ * case-insensitive (RFC 9110), but the plain-object spread the three brains used
+ * (`{...model.headers, ...config.headers, ...options.headers}`) keyed by exact spelling — a
+ * `X-Tenant` in one bag and `x-tenant` in another BOTH survived and both went on the wire, where
+ * fetch's Headers folds them into one comma-joined value ("a, b"): neither writer's value, and the
+ * later layer's documented override silently defeated. Now a later bag's entry replaces an earlier
+ * case-variant; the WINNER'S spelling and value survive (a single-spelling config — every existing
+ * deployment — is byte-identical on the wire).
+ *
+ * EXEMPT: the auth carriers (`authorization` / `x-api-key`, any case) pass through with the exact
+ * legacy spread semantics (same-spelling override only, no case-fold dedup) — their case handling is
+ * {@link stripAuthHeaders}' pinned jurisdiction (the per-call-replaces flow and the
+ * header-only ANTHROPIC_AUTH_TOKEN shape, which must survive under its own capital-A spelling), and
+ * this layer must not become a second, subtly different auth authority.
+ */
+/**
+ * #343 (review r4) — assign a STRUCTURAL locked header under its canonical lowercase name, deleting
+ * every case-variant spelling first. The brains hard-lock `content-type` / `anthropic-version` AFTER
+ * the user-bag merge precisely so they "can NEVER be overridden" (council design/40) — but a valid
+ * user bag carrying `Content-Type: text/plain` survived BESIDE the lowercase lock, and the platform
+ * `Headers` fold turns the pair into `text/plain, application/json` on the wire: the lock decided
+ * nothing. Auth carriers are deliberately NOT routed through here (per-call replacement + the
+ * header-only boot flow are {@link stripAuthHeaders}' pinned jurisdiction).
+ */
+export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
+/**
+ * #343 (review r4) — case-fold READ-AND-CLAIM for an AUGMENTABLE structural header (`anthropic-beta`):
+ * returns the current value under whatever spelling the user bag carried and deletes that spelling,
+ * so the caller's canonical lowercase write REPLACES it instead of duplicating beside it (the
+ * read-modify-write used to key the read by the exact lowercase name and miss `Anthropic-Beta`,
+ * losing the user's betas from the merge AND double-sending the header).
+ */
+export declare function takeHeaderCasefold(headers: Record<string, string>, lowerName: string): string | undefined;
+export declare function mergeHeaders(...bags: Array<Record<string, string> | undefined>): Record<string, string>;
 /**
  * The output-cap key(s) each lane's wire form uses. A lane's set is exactly the keys THAT lane's
  * endpoint reads — a stray cap key belonging to another wire form is inert there and must not be

package/dist/brain/request-params.js

@@ -54,13 +54,51 @@ export function applyExtraBody(body, extraBody, reserved) {
     }
     return { ...passthrough, ...body };
 }
+const AUTH_CARRIER_NAMES = new Set(["authorization", "x-api-key"]);
 export function stripAuthHeaders(headers) {
     for (const k of Object.keys(headers)) {
-        const lower = k.toLowerCase();
-        if (lower === "authorization" || lower === "x-api-key")
+        if (AUTH_CARRIER_NAMES.has(k.toLowerCase()))
             delete headers[k];
     }
 }
+export function lockHeader(headers, lowerName, value) {
+    for (const k of Object.keys(headers)) {
+        if (k !== lowerName && k.toLowerCase() === lowerName)
+            delete headers[k];
+    }
+    headers[lowerName] = value;
+}
+export function takeHeaderCasefold(headers, lowerName) {
+    for (const k of Object.keys(headers)) {
+        if (k.toLowerCase() === lowerName) {
+            const v = headers[k];
+            delete headers[k];
+            return v;
+        }
+    }
+    return undefined;
+}
+export function mergeHeaders(...bags) {
+    const out = {};
+    const spellingByFold = new Map();
+    for (const bag of bags) {
+        if (!bag)
+            continue;
+        for (const [name, value] of Object.entries(bag)) {
+            const fold = name.toLowerCase();
+            if (AUTH_CARRIER_NAMES.has(fold)) {
+                out[name] = value;
+                continue;
+            }
+            const prior = spellingByFold.get(fold);
+            if (prior !== undefined && prior !== name)
+                delete out[prior];
+            spellingByFold.set(fold, name);
+            out[name] = value;
+        }
+    }
+    return out;
+}
 export const OUTPUT_CAP_KEYS = {
     openai: ["max_tokens", "max_completion_tokens"],
     anthropic: ["max_tokens"],

package/dist/core/auto-mode-prompt.js

@@ -49,6 +49,14 @@ function excerpt(text, cap) {
         return text;
     return `${text.slice(0, cap)} [… ${text.length - cap} chars truncated]`;
 }
+function excerptTailInclusive(text, cap) {
+    if (text.length <= cap)
+        return text;
+    const half = Math.floor(cap / 2);
+    const marker = ` [… ${text.length - 2 * half} chars not shown …] `;
+    const out = `${text.slice(0, half)}${marker}${text.slice(text.length - half)}`;
+    return out.length >= text.length ? text : out;
+}
 function renderEntry(m, cap) {
     if (m.role === "user") {
         const raw = typeof m.content === "string" ? m.content : m.content.map((c) => (c.type === "text" ? c.text : `[${c.type}]`)).join("\n");
@@ -102,5 +110,5 @@ export function renderAutoModeWindow(messages, options) {
 export function renderAutoModeAction(input) {
     const ask = input.askMessage ? `\npermission gate: ${input.askMessage}` : "";
     return (`\n## New action to classify (the agent's most recent action — evaluate THIS)\n\n` +
-        `[tool_call] ${input.req.toolName} ${excerpt(JSON.stringify(input.req.args ?? {}), 48_000)}${ask}\n`);
+        `[tool_call] ${input.req.toolName} ${excerptTailInclusive(JSON.stringify(input.req.args ?? {}), 48_000)}${ask}\n`);
 }

package/dist/core/hooks.d.ts

@@ -198,6 +198,13 @@ export interface PermissionDeniedPayload {
     reason: string;
     /** Which gate source produced the deny (our `decision_reason_type` analog). */
     source: PermissionDeniedSource;
+    /** The ask resolver's own deny-arm classification, carried BESIDE `source` (two different
+     *  questions: `source` names which LAYER raised the gate; this names HOW the ask resolution
+     *  refused — a person's no vs a timeout vs headless vs an approver contract violation …). Present
+     *  only on a deny that came through an ask resolution AND whose word passed the closed-vocabulary
+     *  screen; a policy's direct deny, a hook deny, and the crash/plan-mode/compliance emissions carry
+     *  none. See {@link import("./tool-policy.js").AskDenyResolution}. */
+    resolution?: import("./tool-policy.js").AskDenyResolution;
 }
 /**
  * 1.256 复审 MED-1 — observe-only payload isolation for {@link Hooks.permissionDenied}: clone the tool
@@ -606,6 +613,14 @@ export interface ToolGateResult {
      * and no post-tool hook can write.
      */
     settledBy?: import("./tool-policy.js").ApprovalSettledBy;
+    /**
+     * The ask resolver's deny-arm classification (see {@link import("./tool-policy.js").AskDenyResolution}),
+     * present only on a BLOCK whose deny came through an ask resolution and passed the closed-vocabulary
+     * screen at the deny exit (a self-declared word on a policy's own deny is dropped there, never
+     * forwarded). Rides beside {@link settledBy} to the caller's per-call sideband and the call's
+     * `tool_end` frame — the machine-readable "why was this refused" a consumer classifies on.
+     */
+    resolution?: import("./tool-policy.js").AskDenyResolution;
     /**
      * design/252 G-7 — WHOSE settlement that was: the identifier the approval channel reported, carried
      * out verbatim beside {@link settledBy}. This layer authenticates nothing and compares nothing; the
@@ -915,7 +930,10 @@ export interface ToolGateInput {
      * probe cannot widen anything through this member.
      */
     reversibilityProbe?: (args: unknown) => import("./types.js").ReversibilityVerdict | Promise<import("./types.js").ReversibilityVerdict>;
-    /** design/77 §4: deadline (ms) for {@link reversibilityProbe}; on timeout the gate fails closed to `ask`. */
+    /** design/77 §4: deadline (ms) for {@link reversibilityProbe}; on timeout the gate fails closed to `ask`.
+     *  ABSENT ⇒ a bounded default applies (30s — the probe wait is never unbounded, even with no
+     *  {@link abortSignal}); a non-finite/negative value is refused loudly (via {@link onHookError}) to
+     *  that same default, never silently reinterpreted. `0` is honored as written (immediate deadline). */
     approvalTimeoutMs?: number;
     /** design/77 §4: the task abort signal — bounds {@link reversibilityProbe} by the task's real deadline
      *  (timeout/cancel) in addition to {@link approvalTimeoutMs}; an abort while probing fails closed to `ask`. */
@@ -937,6 +955,11 @@ export interface ToolGateInput {
      * this one carries the exception object itself to whoever runs the deployment, because a crashing hook is
      * a bug someone has to fix and the model-facing summary is bounded/sanitized. Never affects the outcome
      * (a throwing sink is swallowed).
+     *
+     * ALSO fired for a {@link reversibilityProbe} that threw or timed out (same species — a
+     * deployment-supplied callback failing while the gate holds the fail-closed line) and for a
+     * malformed {@link approvalTimeoutMs} refused to the bounded default. A task-abort rejection
+     * mid-probe is NOT reported (normal cancellation, not a defect).
      */
     onHookError?: (err: unknown) => void;
     /**

package/dist/core/hooks.js

@@ -1,4 +1,4 @@
-import { decisionText, describeThrown, refuseOutOfContractDecision } from "./tool-policy.js";
+import { decisionText, describeThrown, isAskDenyResolution, refuseOutOfContractDecision } from "./tool-policy.js";
 import { brandPolicyAskClass } from "./ask-class.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { mintSystemReminder } from "./reminder-mint.js";
@@ -269,6 +269,7 @@ function withProbeTimeout(p, ms, signal) {
         p.then((v) => done(resolve, v), (err) => done(reject, err));
     });
 }
+const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
 export function persistedRuleMandateOf(marks) {
     return marks.egress === true
         ? "tool_marks"
@@ -293,6 +294,7 @@ export async function runToolGate(input) {
     const preToolContext = [];
     let hookAsk;
     let parkFailed;
+    let askDenyResolution;
     const notifier = createSafeNotifier(input.onNotifyError !== undefined ? { onError: input.onNotifyError } : undefined);
     if (preToolUse) {
         let r;
@@ -373,8 +375,20 @@ export async function runToolGate(input) {
         if (input.irreversibility === "maybe" && input.reversibilityProbe) {
             let reversible = false;
             const probeArgs = policyRewrite !== undefined ? policyRewrite : currentInput;
+            const suppliedProbeMs = input.approvalTimeoutMs;
+            let probeTimeoutMs;
+            if (suppliedProbeMs === undefined) {
+                probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
+            }
+            else if (Number.isFinite(suppliedProbeMs) && suppliedProbeMs >= 0 && suppliedProbeMs <= 2_147_483_647) {
+                probeTimeoutMs = suppliedProbeMs;
+            }
+            else {
+                probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
+                traceHookCrash(input, new Error(`approvalTimeoutMs must be a non-negative finite number no greater than 2147483647 (got ${String(suppliedProbeMs)}) — the reversibilityProbe deadline falls back to the ${DEFAULT_PROBE_TIMEOUT_MS}ms default`), notifier);
+            }
             try {
-                const verdict = await withProbeTimeout(Promise.resolve(input.reversibilityProbe(probeArgs)), input.approvalTimeoutMs, input.abortSignal);
+                const verdict = await withProbeTimeout(Promise.resolve(input.reversibilityProbe(probeArgs)), probeTimeoutMs, input.abortSignal);
                 reversible = verdict?.reversible === true;
                 if (!reversible) {
                     const raw = verdict?.reason;
@@ -383,8 +397,10 @@ export async function runToolGate(input) {
                     probeCause = normalizeProbeCause(verdict?.cause);
                 }
             }
-            catch {
+            catch (err) {
                 reversible = false;
+                if (input.abortSignal?.aborted !== true)
+                    traceHookCrash(input, err, notifier);
             }
             tighten = !reversible;
         }
@@ -671,6 +687,8 @@ export async function runToolGate(input) {
             const resolved = await resolveAsk(decision, req);
             if (resolved.action !== "ask" && resolved.approver !== undefined)
                 resolvedApprover = resolved.approver;
+            if (resolved.action === "deny" && isAskDenyResolution(resolved.resolution))
+                askDenyResolution = resolved.resolution;
             decision = resolved;
             if (resolved.action === "deny" && resolved.approverUnavailable === true && suspendAsk && parkFailed === undefined) {
                 const suspended = await suspendAsk(req, currentInput, safety, true, realApprovalOf(askBeforeResolve), askBeforeResolve.action === "ask" ? askBeforeResolve.persistedRuleShadowed : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.decisionReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeReason : undefined, askBeforeResolve.action === "ask" ? askBeforeResolve.probeCause : undefined);
@@ -771,6 +789,8 @@ export async function runToolGate(input) {
                     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") {
+                        if (rr.action === "deny" && isAskDenyResolution(rr.resolution))
+                            askDenyResolution = rr.resolution;
                         editDenied = rr;
                         if (!orgRaisedThisRound)
                             denySource = "policy";
@@ -807,8 +827,9 @@ export async function runToolGate(input) {
         if (decision.updatedInput !== undefined) {
             currentInput = decision.updatedInput;
         }
+        const denyResolution = askDenyResolution;
         if (input.permissionDenied) {
-            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
+            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource, ...(denyResolution !== undefined ? { resolution: denyResolution } : {}), ...(input.identity !== undefined ? { identity: input.identity } : {}) }), "toolGate.permissionDenied");
         }
         const denySettledBy = decision.settledBy;
         const denyApprover = denySettledBy !== undefined ? resolvedApprover : undefined;
@@ -816,6 +837,7 @@ export async function runToolGate(input) {
             block: true,
             reason: formatHookFeedback(denyReason, input.reminderMark),
             ...(denySettledBy !== undefined ? { settledBy: denySettledBy } : {}),
+            ...(denyResolution !== undefined ? { resolution: denyResolution } : {}),
             ...(denyApprover !== undefined ? { approver: denyApprover } : {}),
             preToolContext,
         };

package/dist/core/mcp.d.ts

@@ -193,7 +193,10 @@ export interface McpRefreshResult {
      *  DOMAIN for the swap (review F4: a prefix domain is self-healing and decoupled from the diff
      *  baseline, which advances even when a consumer skips a swap). Present on every entry. */
     prefix: string;
-    status: "refreshed" | "not_connected" | "failed";
+    /** `"revoked"` (design/338): the host ledger marks this server revoked — the refresh did NOT
+     *  contact it (no tools/list round trip; the engine must not hand a severed server a request
+     *  channel or splice its post-revocation text into the model catalog). */
+    status: "refreshed" | "not_connected" | "failed" | "revoked";
     toolCount: number;
     added: string[];
     removed: string[];
@@ -467,6 +470,9 @@ export declare function materializeMcpTools(specs: McpServerSpec[], principal?:
 reminderDisclosure?: {
     reminderMark?: string;
     counts?: ReminderDisclosureCounts;
+}, mcpRevocations?: {
+    isRevoked(serverName: string): boolean;
+    onProbeFailure?: (error: unknown) => void;
 }): Promise<MaterializedMcp>;
 /**
  * Fold the caller's AUTHORITATIVE per-tool override (design F: caller = trust root) over the server-hint axis.