@sema-agent/core 5.49.0 → 5.51.0

package/CHANGELOG.md

@@ -1,5 +1,117 @@
 # Changelog
 
+## 5.51.0 — 2026-08-21
+
+### Added
+- **A parent-thread BARE human rejection is a control-flow boundary** (#210; CC 223 anchor
+  `$Vo`/`cancelAndAbort`): after the person rejects a tool call with no note, the same assistant
+  batch's later side-effecting siblings no longer execute — never-started calls settle as coded
+  results (`details.{error,code}: "gate.batch_halted"`, known-not-executed wording,
+  `rejectedToolCallId`/`rejectedToolName` attached), already-executing calls finish and settle
+  honestly, and the run ends awaiting user input. Sequential, partitioned-preflight and in-stream
+  pipelines all consume ONE judgment seat; delegated children (forks included), reject-WITH-note,
+  and every non-human deny keep today's posture byte-for-byte. Engine continuation lanes
+  (stop-gate pushback, final-verify, attachment/batch-context steer, limit-approach, LSP
+  diagnostics, task notifications — the last parks losslessly) cannot revive a halted run; user
+  steer/followUp can — they ARE the awaited input. Additive faces: `TaskResult.haltedOnUserRejection`,
+  `tool_execution_end.notExecuted`, `BeforeToolCallResult.haltRemaining`. Containment form (no
+  abort teardown) is a registered cc-parity divergence.
+- **Every ask-resolution deny names its arm** (#127): `AskDenyResolution` nine-code closed set
+  (human_refused/window_expired/no_approver/blanket_allow_refused/approver_unavailable/
+  task_aborted/presentation_failed/approver_error/approver_contract) minted where each arm
+  states its own fact, carried as `PermissionDeniedPayload.resolution` (distinct from `source`)
+  onto the `tool_end` frame. Existing deny wording byte-unchanged; the gate captures only at its
+  own ask-resolution seats, so a policy cannot forge a code.
+- **`defineTool` carries the declared safety axes onto its product** (#126):
+  egress/irreversibility/reversibilityProbe/offload/offloadThresholdChars now survive into a
+  product-form `TaskSpec.tools` entry — a declared egress/irreversible tool fed as a finished
+  product previously auto-allowed with no door sounding. Declaration-takes-effect (behavior
+  narrowing): such declarations now really gate, and a product-form `egress:true+effect:"read"`
+  contradiction refuses prepare loudly. A ToolSpec-key completeness table makes the next
+  silently-dropped key a compile error.
+- **Review sampling is tail-inclusive** (#287): the spawn review reads objective+systemPrompt
+  through the layered head/interior/tail sample (12k budget, gap markers), and the auto-mode
+  classifier's 48k action block reads head-half + declared-middle + tail-half — a two-stage
+  payload (benign head, real instructions past the cut) no longer evades review. Bounds unchanged.
+- **The reversibilityProbe wait is always finite** (#128): absent `approvalTimeoutMs` falls to a
+  30s default (elapse takes the existing fail-closed tighten-to-ask arm), garbage values refuse
+  loudly to the same default, explicit 0 stays honored; a throwing/timed-out probe now reaches
+  `onHookError`/`onError(phase:"hook")` instead of being swallowed.
+- **`details.code` twins for the SendMessage admission and stop/poll families**: the five
+  admission codes (rate_limited/duplicate/hop_loop/hop_runaway/queue_full) and the stop family
+  (not_local/parked_pending_approval/park_resume_won/park_arbiter_unreachable) carry the machine
+  twin beside `error` at all nine mint sites; `UnifiedTaskOutput` grows the additive `code` seat.
+- **`mcp.revocation_probe_failed` forwarding guidance**: the seat contract and notice directory
+  now state the dedup unit precisely (once per MATERIALIZATION — a resume re-materializes and may
+  re-announce), no session attribution, operator audience by the `NOTICE_AUDIENCE` default; plus
+  an in-flight-not-chased pin (a revocation racing an already-dispatched call never retracts it).
+
+### Changed
+- Behavior narrowing (named): post-rejection siblings from "executed as usual" to "settle
+  un-executed"; a bare human rejection no longer re-invokes the model to narrate it
+  (`TaskResult.result` may be empty text); product-form tool declarations now really gate (#126).
+
+### Notes
+- Residuals ticketed, not shipped silently: a pre-rejection harness-accepted engine steer still
+  drains past the boundary (#370, single-choke harness steer entry proposed); delegated-child
+  denies fold through policy without a resolution code (observed on #370).
+- Pre-release merged-code scan dispositions (three confirmed, fixed in-tree before publish):
+  a human-halted boundary no longer DRAINS the LSP diagnostics registry (drain is a consuming
+  read — pending now survives for the continuation, the frame defers with it); `defineTool` also
+  carries `defer`/`alwaysLoad` (the defer classification reads them off spec.tools entries — a
+  product's declared deferral silently inlined its schema, and a declared inline pin lost to
+  `TaskSpec.deferTools`); the probe-deadline guard refuses values above setTimeout's 2^31-1
+  ceiling loudly (the silent ~1ms clamp it claimed to close).
+
+## 5.50.0 — 2026-08-21
+
+### Added
+- **`RunnerDeps.mcpRevocations`** (design/338, the #322 batch-3 hook — mid-turn MCP revocation):
+  the host's revocation ledger, probed synchronously at every MCP dispatch (tool call + the three
+  resource tools) BEFORE the transport. A revoked server's call settles as the coded refusal
+  `mcp.server_revoked` with known-not-executed wording; the ledger is live (revoke/un-revoke take
+  effect on the very next call, no engine-side caching); a throwing probe fails OPEN with a
+  once-per-run `mcp.revocation_probe_failed` notice. Absent seat = pre-338 semantics.
+- **Machine-readable refusal codes on the wire**: `delegation.concurrency_cap`,
+  `delegation.session_cap` and `mcp.server_revoked` now carry a `details.code` twin beside
+  `details.error` (same value; the wire errorCode lift reads `code`) — tool_end frames for these
+  refusals become classifiable. `HarvestRejectionCode` gains `"deferred"` (additive).
+- Conformance clauses **31 → 34**: the hold×applyPatches protocol (hold-unaware plain write /
+  release-replay CAS conflict carrying currentRev / snapshot faces tracking the post-UPDATE tuple)
+  and the whitewash-precedence UPDATE spelling. `MemorySessionHandle` gains a keyset gate
+  (machine face for consumer obligations).
+
+### Fixed
+- **Workflow mount batch** (merged-scan FAM-3): a generic own-nullish merger
+  (`overlayWorktreeBaseline`) replaces the per-key drop list — an overlay's own-undefined keys no
+  longer erase base governance (excludeTools/deferTools/toolPolicy/shellGate/…); new keys are safe
+  by construction (`checkpointStore: null` is the one registered exception). Host tighten-only
+  clamps (`handsReadOnly:true` / `interactiveTools:false`) now ride into workflow children at the
+  same injection point as the read-face clamp — a clamped host's workflow child can no longer
+  unclamp itself.
+- **Brain effort batch** (FAM-4): the effective-reasoning verdict is minted at the single point
+  that writes the wire and echoed back (three single-sources: the carried predicate, the wire
+  value mint, the declared-levels shape gate) — a garbled tier (`thinking:"hgih"`) now reports the
+  same fact the wire shows instead of a clamped-to-minimal or echo-garbage lie; the anthropic
+  budget arm reports its cap-wins drop; truthy non-array effortLevels no longer throw at request
+  construction. Per-call headers are case-fold deduplicated (`X-Tenant` + `x-tenant` no longer
+  ride the wire as two entries; auth carriers exempt as pinned).
+- **Memory projection write-back debt** (#366 root fix): a committed entry whose id write-back to
+  the projection file failed is now a durable DEBT row (`projection-debts.json`, write-ahead
+  staged across all four mint lanes) — the next harvest validates and re-binds the id-less file to
+  its committed identity instead of re-adopting it as a duplicate; stale rows drop, unvalidatable
+  rows defer fail-closed. The old silent swallow is loud in both directions.
+- The durable reap drops the stale terminal in-process handle after a winning row delete (#361) —
+  inside the reap-to-restart window a same-process SendMessage answered the pre-deletion "not
+  retained" text while a fresh process answered the honest no-transcript form.
+- Delegation entry ledgers get a lifecycle (reap anchor + amortized sweep) — one Map entry per
+  (scope, rootSessionId) no longer accumulates for the life of the process.
+
+### Notes
+- Conformance 31→34 is a tightening for backend implementers (a hold-unaware backend fails the
+  new cases; upgrade-order duty as before). Everything else is additive or a narrowing inside
+  existing coded families; no BREAKING changes.
+
 ## 5.49.0 — 2026-08-20
 
 ### Added

package/dist/agents/roster-store.js

@@ -110,7 +110,10 @@ export class FileRosterStore {
         if (text.trim() === "")
             return [];
         try {
-            const raw = JSON.parse(text);
+            const rawU = JSON.parse(text);
+            if (typeof rawU !== "object" || rawU === null)
+                throw new Error("roster file: not a JSON object");
+            const raw = rawU;
             if (!Array.isArray(raw.entries))
                 throw new Error("roster file: entries is not an array");
             const kept = raw.entries.filter((e) => typeof e === "object" && e !== null && typeof e.name === "string" && typeof e.agentId === "string" && typeof e.createdAt === "number");

package/dist/agents/send-message-tool.js

@@ -132,7 +132,7 @@ export function createSendMessageTool(opts) {
                         : reason === "hop_loop"
                             ? `this message has already passed through ${whoLabel} too many times (a forwarding loop) — stop relaying it; act on it or drop it.`
                             : `this message's forwarding chain is too long (runaway relay) — stop relaying it; act on it or drop it.`;
-                return { content: `Message not sent: ${text}`, details: { error: reason, to }, isError: true };
+                return { content: `Message not sent: ${text}`, details: { error: reason, code: reason, to }, isError: true };
             };
             if (normalizeAgentName(to) === "main") {
                 if (opts.uplink && senderId !== undefined) {
@@ -217,7 +217,7 @@ export function createSendMessageTool(opts) {
                 if (row.status === "parked") {
                     return {
                         content: `Message not sent: ${whoT3} is parked on a pending approval — it resumes when the approval is decided (durable approval inbox), not by message delivery. Send again after it resumes.`,
-                        details: { error: "parked_pending_approval", to },
+                        details: { error: "parked_pending_approval", code: "parked_pending_approval", to },
                         isError: true,
                     };
                 }
@@ -257,7 +257,7 @@ export function createSendMessageTool(opts) {
                 if (boxFull) {
                     const queueFullReceipt = (guidance) => ({
                         content: `Message not sent: ${whoT3}'s mailbox is at its queued-message limit (${admissionConfig.maxQueuedPeerMessages}) — the message was NOT queued. ${guidance} ${DEDUP_RETRY_NOTE}`,
-                        details: { error: "queue_full", to },
+                        details: { error: "queue_full", code: "queue_full", to },
                         isError: true,
                     });
                     if (!opts.registry.beginDurableClaim(handle)) {
@@ -601,7 +601,7 @@ export function createSendMessageTool(opts) {
                     if (delivered.reason === "queue_full") {
                         return {
                             content: `Message not sent: ${who} is still starting up and its startup message buffer is full — resend in a moment. ${DEDUP_RETRY_NOTE}`,
-                            details: { error: "queue_full", to },
+                            details: { error: "queue_full", code: "queue_full", to },
                             isError: true,
                         };
                     }
@@ -609,7 +609,7 @@ export function createSendMessageTool(opts) {
                     if (nowRow?.status === "parked") {
                         return {
                             content: `Message not sent: ${who} is parked on a pending approval — it resumes when the approval is decided, not by message delivery. Send again after it resumes. ${DEDUP_RETRY_NOTE}`,
-                            details: { error: "parked_pending_approval", to },
+                            details: { error: "parked_pending_approval", code: "parked_pending_approval", to },
                             isError: true,
                         };
                     }

package/dist/agents/subagent.d.ts

@@ -484,6 +484,12 @@ export declare function resolveDelegationEntryCaps(caps: {
     maxConcurrent?: number;
     maxCumulativePerSession?: number;
 } | undefined): ResolvedDelegationEntryCaps;
+/** @internal — observability seam for the lifecycle pins (tests only; never a public surface):
+ *  the ledger footprint of one registry. */
+export declare function delegationEntryLedgerFootprint(registry: object): {
+    keys: number;
+    handles: number;
+};
 /**
  * Options for {@link createSubagentTool}.
  *

package/dist/agents/subagent.js

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { isAbsolute } from "node:path";
 import { withDelegationProvenance } from "../core/tool-policy.js";
+import { errorResult } from "../core/tools.js";
 import { isHighSurrogate, isLowSurrogate } from "../core/surrogate-safe-slice.js";
 import { newDelegationProvenanceAggregate, reduceDelegationAttestation } from "../core/memory-engine/delegation-provenance.js";
 import { registerDelegationLaunch, replayExternalSettlementEffects, settleDelegation } from "../core/memory-engine/delegation-settlement.js";
@@ -109,14 +110,14 @@ export function layeredReviewSample(text, budget = HANDBACK_REVIEW_SAMPLE_BUDGET
         return { text, readChars: total, totalChars: total, sampled: false, gaps: 0 };
     return { text: out, readChars, totalChars: total, sampled: true, gaps };
 }
-function reviewCoverageNote(fields) {
+function reviewCoverageNote(fields, author = "the child's own writing") {
     const sampled = fields.filter((f) => f.sample.sampled);
     if (sampled.length === 0)
         return undefined;
     return (sampled
         .map((f) => `${f.field}: the classifier was shown ${f.sample.readChars} of ${f.sample.totalChars} characters (UTF-16 code units) ` +
         `(layered head/middle/tail sample; the ${f.sample.gaps} skipped span(s) are marked in place as ` +
-        `"[… N chars not shown …]" — any further such marker in the text is the child's own writing, not this sampler's)`)
+        `"[… N chars not shown …]" — any further such marker in the text is ${author}, not this sampler's)`)
         .join("; ") + " — the unshown spans were NOT reviewed; treat them as unknown, not as benign.");
 }
 const HANDBACK_ASK_MESSAGE = "Subagent has finished and is handing back control to the main agent. Review the subagent's work and flag if any action may violate security policy.";
@@ -912,6 +913,125 @@ function delegationEntryLedger(registry, key) {
     }
     return set;
 }
+const delegationLedgerLifecycles = new WeakMap();
+const delegationLedgerKeyStores = new WeakMap();
+function bindDelegationLedgerKeyStore(registry, key, store) {
+    let byKey = delegationLedgerKeyStores.get(registry);
+    if (byKey === undefined) {
+        byKey = new Map();
+        delegationLedgerKeyStores.set(registry, byKey);
+    }
+    if (byKey.get(key) === null)
+        return;
+    byKey.set(key, store ?? null);
+}
+async function sweepDelegationEntryLedgerKeys(registry, keys) {
+    const byKey = delegationEntryLedgers.get(registry);
+    if (byKey === undefined)
+        return;
+    const keyStores = delegationLedgerKeyStores.get(registry);
+    const activeFace = registry.activeDelegationHandles;
+    if (typeof activeFace !== "function")
+        return;
+    for (const key of keys) {
+        const set = byKey.get(key);
+        if (set === undefined)
+            continue;
+        const store = keyStores?.get(key);
+        if (store === undefined || store === null)
+            continue;
+        let scopeK;
+        let rootK;
+        try {
+            const parsed = JSON.parse(key);
+            if (!Array.isArray(parsed) || typeof parsed[0] !== "string" || typeof parsed[1] !== "string")
+                continue;
+            scopeK = parsed[0];
+            rootK = parsed[1];
+        }
+        catch {
+            continue;
+        }
+        if (activeFace.call(registry, scopeK, rootK).length > 0)
+            continue;
+        const sizeBefore = set.size;
+        let stored;
+        try {
+            stored = (await store.listBySession(scopeK, rootK)).map((r) => r.handle);
+        }
+        catch {
+            continue;
+        }
+        if (byKey.get(key) !== set || set.size !== sizeBefore || activeFace.call(registry, scopeK, rootK).length > 0)
+            continue;
+        if (stored.length === 0) {
+            byKey.delete(key);
+            keyStores?.delete(key);
+            continue;
+        }
+        const keep = new Set(stored);
+        for (const h of [...set])
+            if (!keep.has(h))
+                set.delete(h);
+        if (set.size === 0) {
+            byKey.delete(key);
+            keyStores?.delete(key);
+        }
+    }
+}
+function armDelegationLedgerLifecycle(registry) {
+    let life = delegationLedgerLifecycles.get(registry);
+    if (life === undefined) {
+        life = { cursor: 0, subscribed: false };
+        delegationLedgerLifecycles.set(registry, life);
+    }
+    if (life.subscribed)
+        return;
+    const reapFace = registry.onSessionReap;
+    if (typeof reapFace !== "function")
+        return;
+    life.subscribed = true;
+    reapFace.call(registry, (sessionId, scope) => {
+        const byKey = delegationEntryLedgers.get(registry);
+        if (byKey === undefined)
+            return;
+        const keys = [...byKey.keys()].filter((k) => {
+            try {
+                const parsed = JSON.parse(k);
+                if (!Array.isArray(parsed) || typeof parsed[0] !== "string" || typeof parsed[1] !== "string")
+                    return false;
+                return parsed[1] === sessionId && (scope === undefined || parsed[0] === scope);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (keys.length > 0)
+            void sweepDelegationEntryLedgerKeys(registry, keys).catch(() => undefined);
+    });
+}
+function sweepDelegationLedgerRound(registry, n) {
+    const life = delegationLedgerLifecycles.get(registry);
+    const byKey = delegationEntryLedgers.get(registry);
+    if (life === undefined || byKey === undefined || byKey.size === 0)
+        return;
+    const keys = [...byKey.keys()];
+    const start = life.cursor % keys.length;
+    const slice = [];
+    for (let i = 0; i < Math.min(n, keys.length); i++)
+        slice.push(keys[(start + i) % keys.length]);
+    life.cursor = (start + slice.length) % keys.length;
+    void sweepDelegationEntryLedgerKeys(registry, slice).catch(() => undefined);
+}
+export function delegationEntryLedgerFootprint(registry) {
+    const byKey = delegationEntryLedgers.get(registry);
+    if (byKey === undefined)
+        return { keys: 0, handles: 0 };
+    let handles = 0;
+    for (const s of byKey.values())
+        handles += s.size;
+    return { keys: byKey.size, handles };
+}
 export function normalizeSubagentType(value) {
     return value.normalize("NFKC").toLowerCase().replace(/[\p{White_Space}\p{Pd}_]+/gu, "");
 }
@@ -1908,14 +2028,26 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 const spawnToolsNote = spawnToolNames.length > 0
                     ? spawnToolNames.join(", ")
                     : "(none explicitly listed — but if this deployment gave the child a real execution environment, it likely also has the standard file/shell tools: Read/Edit/Write/Bash/Grep/Glob)";
+                const objectiveSample = layeredReviewSample(prompt);
+                const systemPromptSample = childSystemPrompt != null ? layeredReviewSample(childSystemPrompt) : undefined;
+                const spawnCoverage = reviewCoverageNote([
+                    { field: "objective", sample: objectiveSample },
+                    ...(systemPromptSample ? [{ field: "systemPrompt", sample: systemPromptSample }] : []),
+                ], "the delegating agent's own writing");
+                const objectiveDisplay = layeredReviewSample(prompt, 2_000, 2);
                 const spawnVerdict = await ctx.autoModeReview.decider
                     .decide({
                     req: {
                         toolName: wantsFork ? "Agent(fork)" : "Agent",
-                        args: { objective: prompt.slice(0, 2_000), tools: spawnToolNames, systemPrompt: childSystemPrompt?.slice(0, 2_000) },
+                        args: {
+                            objective: objectiveSample.text,
+                            tools: spawnToolNames,
+                            systemPrompt: systemPromptSample?.text,
+                            ...(spawnCoverage ? { reviewCoverage: spawnCoverage } : {}),
+                        },
                         toolCallId: ctx.toolCallId,
                     },
-                    askMessage: `Reviewing a sub-agent about to be spawned. Objective: ${prompt.slice(0, 2000)}${prompt.length > 2000 ? "…" : ""}\nTools available to it: ${spawnToolsNote}`,
+                    askMessage: `Reviewing a sub-agent about to be spawned. Objective: ${objectiveDisplay.text}\nTools available to it: ${spawnToolsNote}`,
                 }, ctx.signal)
                     .catch(() => ({ kind: "unavailable", cause: "error" }));
                 if (ctx.signal?.aborted) {
@@ -2491,7 +2623,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         dropHostAbortListener();
                         await cancelObserver();
                         const wt = await finishWorktree();
-                        return { isError: true, content: `Sub-agent not started in background: ${text}${wt ? `\n${wt}` : ""}`, details: { error: code } };
+                        return errorResult(`Sub-agent not started in background: ${text}${wt ? `\n${wt}` : ""}`, { error: code, code });
                     };
                     const activeFace = bg.registry.activeDelegationHandles;
                     const active = typeof activeFace === "function" ? activeFace.call(bg.registry, capScope, capRoot) : [];
@@ -2640,6 +2772,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 }
                 if (capLedgerKey !== undefined && reviveRow === undefined)
                     delegationEntryLedger(bg.registry, capLedgerKey).add(taskId);
+                if (capLedgerKey !== undefined) {
+                    bindDelegationLedgerKeyStore(bg.registry, capLedgerKey, bg.agentStore);
+                    armDelegationLedgerLifecycle(bg.registry);
+                    sweepDelegationLedgerRound(bg.registry, 3);
+                }
                 childInternals.peerSelfRef?.addAxis("h", taskId);
                 if (agentName !== undefined) {
                     recordRosterSpawn(ctx.roster, { name: agentName, agentId: taskId, toolUseId: ctx.toolCallId, owner: bgOwner, scope: bgScope, ...((typeof childModel === "string" ? resolveModelDisplayLabel(childModel) : childModel?.id) !== undefined ? { model: typeof childModel === "string" ? childModel : childModel?.id } : {}), ...(reviveRow !== undefined ? ((reviveRow.rootSessionId ?? reviveRow.parentSessionId) !== undefined ? { rootSessionId: reviveRow.rootSessionId ?? reviveRow.parentSessionId } : {}) : (ctx.rootSessionId ?? ctx.sessionId) !== undefined ? { rootSessionId: ctx.rootSessionId ?? ctx.sessionId } : {}), ...(sessionScopedBg ? { sessionScoped: true } : {}), createdAt: reviveRow?.spawnedAt ?? Date.now() }, (err) => opts.onObserverError?.(err, { site: "roster.recordSpawn" }));

package/dist/agents/teacher.js

@@ -31,7 +31,10 @@ export function parseTeacherAdvice(text) {
     const end = text.lastIndexOf("}");
     if (start !== -1 && end > start) {
         try {
-            const o = JSON.parse(text.slice(start, end + 1));
+            const oU = JSON.parse(text.slice(start, end + 1));
+            if (typeof oU !== "object" || oU === null)
+                throw new Error("not an object");
+            const o = oU;
             return {
                 strategy: typeof o.strategy === "string" ? o.strategy : undefined,
                 correction: typeof o.correction === "string" ? o.correction : undefined,

package/dist/brain/anthropic.js

@@ -5,10 +5,9 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
-import { isThinkingLevel, reasoningBudgetShare, resolveEffort } from "./reasoning.js";
+import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders, takeHeaderCasefold } from "./request-params.js";
+import { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
-const MIN_THINKING_TOKENS = 1024;
 function thinkingBudget(maxTokens, share, fixed, hardCap = false) {
     const max = hardCap ? maxTokens : Math.max(maxTokens, MIN_THINKING_TOKENS * 2);
     const want = fixed ?? Math.floor(max * share);
@@ -261,13 +260,13 @@ export function createAnthropicBrain(config = {}) {
                 if (options?.temperature !== undefined && anthCompat.supportsTemperature !== false) {
                     body.temperature = options.temperature;
                 }
-                if (model.reasoning && isThinkingLevel(options?.reasoning) && options.reasoning !== "off") {
+                if (reasoningRequestCarried(model, options?.reasoning)) {
                     if (anthCompat.thinkingMode === "adaptive") {
                         body.thinking = { type: "adaptive" };
                     }
                     else {
                         const hardCap = overrides?.maxOutputTokens !== undefined || options?.maxTokens !== undefined;
-                        if (hardCap && body.max_tokens < MIN_THINKING_TOKENS * 2) {
+                        if (budgetCapSkipsThinking(body.max_tokens, hardCap)) {
                             body.thinking = undefined;
                             delete body.thinking;
                         }
@@ -283,13 +282,9 @@ export function createAnthropicBrain(config = {}) {
                 }
                 const betas = [];
                 let sendEffortBeta = false;
-                if (anthCompat.effortLevels &&
-                    anthCompat.effortLevels.length > 0 &&
-                    model.reasoning &&
-                    options?.reasoning &&
-                    options.reasoning !== "off" &&
-                    isThinkingLevel(options.reasoning)) {
-                    const { effective } = resolveEffort(options.reasoning, anthCompat.effortLevels.filter(isThinkingLevel));
+                const declaredEffort = declaredEffortLevels(anthCompat.effortLevels);
+                if (declaredEffort !== undefined && reasoningRequestCarried(model, options?.reasoning)) {
+                    const { effective } = resolveEffort(options.reasoning, declaredEffort);
                     const wireEffort = effective === "minimal" ? "low" : effective;
                     body.output_config = { effort: wireEffort };
                     sendEffortBeta = true;
@@ -303,23 +298,19 @@ export function createAnthropicBrain(config = {}) {
                 if (anthCompat.interleavedThinking) {
                     betas.push("interleaved-thinking-2025-05-14");
                 }
-                const headers = {
-                    ...model.headers,
-                    ...config.headers,
-                    ...options?.headers,
-                };
+                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
                 if (options?.apiKey !== undefined)
                     stripAuthHeaders(headers);
                 if (betas.length > 0) {
-                    const existing = (headers["anthropic-beta"] ?? "").split(",").map((b) => b.trim()).filter(Boolean);
+                    const existing = (takeHeaderCasefold(headers, "anthropic-beta") ?? "").split(",").map((b) => b.trim()).filter(Boolean);
                     for (const beta of betas) {
                         if (!existing.includes(beta))
                             existing.push(beta);
                     }
                     headers["anthropic-beta"] = existing.join(",");
                 }
-                headers["content-type"] = "application/json";
-                headers["anthropic-version"] = config.version ?? "2023-06-01";
+                lockHeader(headers, "content-type", "application/json");
+                lockHeader(headers, "anthropic-version", config.version ?? "2023-06-01");
                 if (apiKey)
                     headers["x-api-key"] = apiKey;
                 const builtThinkingRequested = body.thinking !== undefined;

package/dist/brain/open-responses.js

@@ -5,8 +5,8 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
-import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
+import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
@@ -151,16 +151,12 @@ function toResponsesTools(ctx) {
     }));
 }
 function resolveWireEffort(model, reasoning) {
-    if (!model.reasoning || !isThinkingLevel(reasoning) || reasoning === "off")
+    if (!reasoningRequestCarried(model, reasoning))
         return undefined;
     const compat = responsesCompat(model);
     if (compat.supportsReasoningEffort === false)
         return undefined;
-    const effort = resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective;
-    const mapped = model.thinkingLevelMap?.[effort];
-    if (mapped === null)
-        return undefined;
-    return mapped ?? effort;
+    return mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
 }
 function computeUsage(model, raw) {
     const input = raw?.input_tokens ?? 0;
@@ -268,14 +264,10 @@ export function createOpenResponsesBrain(config = {}) {
                 }
                 if (effort !== undefined)
                     body.reasoning = { effort };
-                const headers = {
-                    ...model.headers,
-                    ...config.headers,
-                    ...options?.headers,
-                };
+                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
                 if (options?.apiKey !== undefined)
                     stripAuthHeaders(headers);
-                headers["content-type"] = "application/json";
+                lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
                 const wire = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);

package/dist/brain/openai.js

@@ -5,8 +5,8 @@ import { createRepetitionPoll, parseStreamedToolArgs } from "./stream-shared.js"
 import { mintFallbackToolCallId } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, stripAuthHeaders } from "./request-params.js";
-import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, stripAuthHeaders } from "./request-params.js";
+import { mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 function closeToolCallAccum(acc) {
     if (acc.closedTc)
@@ -86,19 +86,11 @@ function applyThinking(body, model, reasoning) {
         }
         return;
     }
-    if (!model.reasoning || !isThinkingLevel(reasoning) || reasoning === "off")
+    if (!reasoningRequestCarried(model, reasoning))
         return;
     const compat = thinkingCompat(model);
     const supportsEffort = compat.supportsReasoningEffort ?? true;
-    const effort = resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective;
-    let effortWire = effort;
-    if (model.thinkingLevelMap) {
-        const mapped = model.thinkingLevelMap[effort];
-        if (mapped === null)
-            effortWire = undefined;
-        else if (mapped !== undefined)
-            effortWire = mapped;
-    }
+    const effortWire = mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
     const format = compat.thinkingFormat ?? "openai";
     switch (format) {
         case "openai":
@@ -311,14 +303,10 @@ export function createOpenAIBrain(config = {}) {
                 if (options?.stop)
                     body.stop = options.stop;
                 applyThinking(body, model, options?.reasoning);
-                const headers = {
-                    ...model.headers,
-                    ...config.headers,
-                    ...options?.headers,
-                };
+                const headers = mergeHeaders(model.headers, config.headers, options?.headers);
                 if (options?.apiKey !== undefined)
                     stripAuthHeaders(headers);
-                headers["content-type"] = "application/json";
+                lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
                 const wire = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);