@sema-agent/core 5.14.0 → 5.15.0

package/CHANGELOG.md

@@ -1,7 +1,129 @@
 # Changelog
 
+## 5.15.0 — 2026-08-06
+
+### BREAKING
+
+- **`TaskSpec.toolMaterializeStrategy` defaults to `"swap"` again** (it defaulted to `"static"` for one
+  release window). Under `"static"` a deferred tool's placeholder never swaps: the tools block keeps
+  advertising `{"type":"object","properties":{}}` and the real schema reaches the model only as text in
+  the `ToolSearch` result. That is fine for a model whose tool arguments are free-form JSON, and
+  structurally unusable for one served with **constrained decoding**, where the advertised wire schema is
+  enforced at the sampler. On the mainstream implementations — grammar compiled from the declared
+  `properties` — `{}` becomes the only argument object the model can emit, so the engine's corrective
+  invalid-arguments rejection cannot be acted on and the run burns turns without converging. (A strictly
+  draft-faithful decoder would read the absent `additionalProperties` as permissive; the model still has
+  no schema to form other keys from, so that path degrades to guessing rather than converging.)
+  The condition for `"static"` is also a property of the WHOLE serving route rather than of one model —
+  the degrading brain can fall back across providers mid-run and `limits.degrade` can hand the run to a
+  different model outright, and neither rebuilds the disclosure strategy — so it is now a strict explicit
+  opt-in: set it only if every model the run can reach, fallback targets included, has been verified to
+  read schemas from result text. **Who is affected:** a deployment that relied on the default to keep its
+  provider prompt cache intact across activations now sees the pre-`"static"` behavior (activation calls
+  `setTools`, invalidating the cache suffix) unless it sets `toolMaterializeStrategy: "static"` itself.
+  **Pinned faces that move with the default:** the `tools_delta` attachment says "now available … Their
+  full schemas are loaded" (not "now active"), the `ToolSearch` description says activation "loads its
+  full parameter schema" (not "returns … in the result"), the `ToolSearch` result no longer inlines
+  `parameters:` per matched tool, and the post-activation tools block carries the real schema again — a
+  consumer pinning any of these under the default must re-pin. `SEMA_TOOL_MATERIALIZE_STRATEGY` still
+  fills an absent spec value, and an env-sourced `"static"` on a `deferSelfResolve: false` task still
+  degrades to `"swap"` (the explicit spec pairing stays refused with `config.tool_materialize_unreachable`).
+
+### Added
+
+- **`prompt.assembled` reports the resolved deferred-tool disclosure strategy** —
+  `toolDisclosure: {deferredTools, strategy, source}` (new exported type `ToolDisclosureManifest`;
+  absent when the leg deferred nothing). `strategy` is the EFFECTIVE value after the direct-call-lane
+  interlock, and `source` names the seat that chose it: `"spec"` / `"env"` / `"default"` /
+  `"degraded_no_direct_lane"` (the interlock narrowed a `"static"` request to `"swap"`; that value
+  implies an env-sourced request, since the spec pairing is refused at prepare and the default is not
+  `"static"`). "Which strategy did this leg run under, and who chose it" was previously answerable only
+  by re-deriving spec > env > release default by hand.
+
+### Fixed
+
+- **Model-visible text stops teaching retired tool names** (#181 census F batch). Three faces taught
+  names a model cannot call (RB-476-A retired alias resolution — a retired name is a loud roster
+  miss): the selective-recall manifest affordance said "call Recall" (a name core registers as
+  removed; the affordance's tool name is now caller-supplied via `composeSelectiveBody`'s new
+  optional `recallToolName` parameter, name-free when omitted); both `ORCHESTRATION_GUIDANCE`
+  blocks said `run_workflow` — on the deferred short form a complete dead link, since `ToolSearch`'s
+  `select:` arm matches exact wire names — and now interpolate `RUN_WORKFLOW_TOOL_NAME`
+  (`"Workflow"`); TaskOutput's lanes description and `task_id` parameter said `RunWorkflow` and now
+  say `Workflow`. A consumer pinning any of these strings must re-pin. A new gate
+  (`test/tool-name-literal-gate.test.ts`) scans every src string literal against the whole
+  `RETIRED_TOOL_NAMES` table with a frozen per-bucket ratchet, so this class cannot regrow silently.
+- **The `# Memory` write instruction requires the Write tool on the roster** (behavior face). The
+  memory engine's injection gated the CC-verbatim write instruction on a writable scope alone;
+  a `handsReadOnly` (or hands-less) run with a memory `writeScope` was instructed to write with a
+  tool its roster does not carry. `MemoryEngine.inject` takes an optional `writeToolMounted`
+  (omitted ⇒ historic behavior for engine-direct hosts; the Runner passes the real hands-write-half
+  predicate), and the RB-276 index seed follows the same gate. **Who is affected:** a deployment
+  running memory-enabled tasks with `handsReadOnly: true` (or no execution env) no longer receives
+  the `# Memory` instruction or the index read-seed on those runs — the fenced index still injects.
+- **The gh rate-limit hint's Monitor clause follows the real Monitor mount.** The SR-2 reminder
+  unconditionally closed with "use the Monitor tool"; Monitor mounts only when background task tools
+  do. `ghRateLimitHint` (and `HandsToolkitOptions`/`createBashTool` `monitorToolActive`) drop exactly
+  that clause when the caller declares Monitor unmounted; omitted keeps the byte-identical historic
+  wording.
+- **`ToolSearch` no longer activates a name the roster has withdrawn.** The deferred registry is frozen
+  at prepare; the roster is not — an MCP refresh can take a deferred name off the mount. An exact
+  `select:` still resolved through the stale registry, added the name to the active set, "succeeded" at
+  a rematerialize that mounted nothing, and announced a tool that could not be called. Withdrawn names
+  are now reported as `No longer available: <names> — withdrawn by its provider and cannot be activated
+  or called`, ride the result's `details.missing`, and never enter the active set.
+- **The deferred placeholder's corrective round is now bounded.** A shape-invalid direct call is answered
+  with the real declared schema so the corrected call is one turn away — which assumes the caller can act
+  on a schema once it has one. A caller whose arguments are constrained to the ADVERTISED schema cannot,
+  and re-sent the identical rejected arguments for as many turns as the budget allowed. After
+  `DEFERRED_NO_PROGRESS_LIMIT` (3) consecutive rejections of the IDENTICAL failure shape on one
+  placeholder, the lane stops re-teaching: it returns a terminal rejection that names the condition with
+  the stable token `tool.deferred_schema_incompatible` (in the model-facing text and on the tool result's
+  `details.noProgress`) and votes the tool batch terminated. Any other outcome — a different validation
+  error, or a successful call — resets the count, so the bound tracks being STUCK, not being wrong.
+  `TaskResult.errorCode` is unchanged: this terminal is reported on the tool result, not as a task
+  failure code.
+- **The invalid-arguments rejection no longer overstates where its schema lives.** It used to say "use it
+  for this and later calls" under both strategies; under `"static"` the schema is carried by that one
+  result and is gone with the next compaction. The text now says either "the next request's tools list
+  will advertise it too" (swap) or "carried by THIS result only" plus the `ToolSearch` re-select spelling
+  (static). A declaration too large to inline is called an "ABRIDGED copy" instead of "full" — past the
+  model-facing bound the serialization comes back with its middle spliced out and is not valid JSON.
+- **A declaration the static face cannot carry in text is exempted from the static face per tool.** Under
+  `"static"` the only in-context schema carrier is result text; a declaration that does not serialize, or
+  that the model-facing bound truncates, has no carrier there, and the tool was announced as activated
+  with a schema the model never received in usable form. Such a tool now materializes into the tools block
+  on activation (the rest of the run stays static), the `ToolSearch` line says where its declaration is,
+  and the result head stops promising schemas it did not print. The `tools_delta` boundary frame carries
+  the same exception (one `Exception: <names> — too large to inline…` line) instead of asserting compact
+  placeholders for a name whose full schema is visibly on the wire; with no exemptions in play the frame
+  is byte-identical to before. The exemption is read from the LIVE roster on every call, so an MCP
+  refresh that changes a declaration's size cannot leave the lane describing the old carrier — and the
+  exemption is MONOTONE within a leg: a declaration that shrinks back under the bound does not put the
+  compact placeholder back on a tool whose schema was only ever delivered through the tools block.
+
+### Fixed (receive-time additions)
+
+- Ruled at receive: the deferred no-progress terminal stays a TOOL-RESULT face (`tool.deferred_schema_incompatible`
+  marker + `details.noProgress`) and does NOT mint a `TaskResult.errorCode` — the run can continue on other
+  tools, so a run-level code would misclassify a per-tool condition.
+- Ruled at receive: a malformed `SEMA_TOOL_MATERIALIZE_STRATEGY` still refuses the task loudly even when a
+  valid spec value is present — a deployment running with a broken env var must hear about it before the
+  first task that omits the spec value inherits the typo.
+
 ## 5.14.0 — 2026-08-06
 
+> **Post-release addendum (2026-08-06, disclosure gap reported by a consumer):** the fail-open survey
+> (shipped in 5.13.0's window, but its consequence surfaced against 5.14.0 pickups) hardened
+> `canonicalizeTarget`'s existence probe — an ERRORED `exists` no longer reads as "does not exist yet"
+> and instead reports `{ok:false, unresolvedSymlink:true}`. Combined with `createSensitivePathPolicy`'s
+> deny on `unresolvedSymlink`, an execution env whose `exists` always throws (a stub/lexical env with
+> no real filesystem) now sees every write target denied — the gate degrades from "guarded" to
+> "closed". That is the intended fail-closed direction for a PROBE FAILURE, but such an env should
+> answer honestly instead of throwing: return `ok(false)` ("this env cannot see a filesystem") and the
+> gate resolves normally. Also: `DelegationTaskType` was named in the ship note but missed the package
+> root; the export lands in the next release — type the `taskType` key as an open `string` until then.
+
 ### BREAKING
 
 - **`CheckpointStore.setPendingSteer` APPENDS to a bounded ordered queue instead of overwriting a single seat**

package/dist/brain/errors.js

@@ -42,6 +42,25 @@ export function extractErrorCode(errorMessage) {
 export function stripErrorCodePrefix(errorMessage) {
     return errorMessage.replace(CODE_PREFIX_RE, "");
 }
+const STALE_CONNECTION_CODES = new Set([
+    "ECONNRESET",
+    "EPIPE",
+    "ConnectionClosed",
+    "ETIMEDOUT",
+    "ECONNABORTED",
+    "ERR_SOCKET_CLOSED",
+    "StreamSuspended",
+]);
+function hasStaleConnectionCode(e) {
+    let cur = e;
+    for (let depth = 0; depth < 5 && cur !== undefined && cur !== null; depth++) {
+        const code = typeof cur.code === "string" ? cur.code : undefined;
+        if (code !== undefined && STALE_CONNECTION_CODES.has(code))
+            return true;
+        cur = cur instanceof Error ? cur.cause : undefined;
+    }
+    return false;
+}
 export function describeNetworkError(e) {
     const top = e instanceof Error ? e.message : String(e);
     const parts = [];
@@ -54,5 +73,6 @@ export function describeNetworkError(e) {
             parts.push(piece);
         cur = cur instanceof Error ? cur.cause : undefined;
     }
-    return parts.length > 0 ? `${top} (${parts.join(" ← ")})` : top;
+    const body = parts.length > 0 ? `${top} (${parts.join(" ← ")})` : top;
+    return hasStaleConnectionCode(e) ? `${body} — possibly a stale connection; a fresh one may succeed` : body;
 }

package/dist/brain/retry.d.ts

@@ -1,3 +1,8 @@
 export declare function parseRetryAfter(res: Response | undefined): number | undefined;
 export declare function parseRateLimitReset(res: Response | undefined): number | undefined;
+export interface ProviderWaitHint {
+    readonly ms: number;
+    readonly rawMs?: number;
+}
+export declare function providerWaitHint(res: Response | undefined): ProviderWaitHint | undefined;
 export declare function retryBackoffMs(baseDelayMs: number, attempt: number, res?: Response, rand?: () => number): number;

package/dist/brain/retry.js

@@ -24,17 +24,29 @@ export function parseRateLimitReset(res) {
     const ms = Math.round(epochSecs * 1000 - Date.now());
     return ms > 0 ? ms : undefined;
 }
-function providerWaitHintMs(res) {
+function clampHint(rawMs) {
+    return rawMs > MAX_HEADER_WAIT_MS ? { ms: MAX_HEADER_WAIT_MS, rawMs } : { ms: rawMs };
+}
+export function providerWaitHint(res) {
     const hints = [];
     const retryAfter = parseRetryAfter(res);
     if (retryAfter !== undefined)
-        hints.push(Math.min(MAX_HEADER_WAIT_MS, retryAfter));
+        hints.push(clampHint(retryAfter));
     if (res?.status === RATE_LIMIT_STATUS) {
         const reset = parseRateLimitReset(res);
         if (reset !== undefined)
-            hints.push(Math.min(MAX_HEADER_WAIT_MS, reset));
+            hints.push(clampHint(reset));
     }
-    return hints.length === 0 ? undefined : Math.max(...hints);
+    if (hints.length === 0)
+        return undefined;
+    return hints.reduce((largest, next) => {
+        if (next.ms !== largest.ms)
+            return next.ms > largest.ms ? next : largest;
+        return (next.rawMs ?? next.ms) > (largest.rawMs ?? largest.ms) ? next : largest;
+    });
+}
+function providerWaitHintMs(res) {
+    return providerWaitHint(res)?.ms;
 }
 export function retryBackoffMs(baseDelayMs, attempt, res, rand = Math.random) {
     const exp = Math.min(MAX_BACKOFF_MS, baseDelayMs * 2 ** attempt);

package/dist/brain/stream-engine.js

@@ -1,7 +1,7 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
 import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
-import { retryBackoffMs } from "./retry.js";
+import { providerWaitHint, retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController, resolveStallTimeoutMs } from "./timeout.js";
 const DEFAULT_MAX_RETRIES = 10;
@@ -372,6 +372,10 @@ export function runStreamingBrain(args) {
                     const retryable = shouldRetryHeaderVerdict(r) ?? retryableByStatus;
                     if (retryable && attempt < maxRetries) {
                         const delayMs = retryBackoffMs(baseDelay, attempt, r);
+                        const waitHint = providerWaitHint(r);
+                        const truncationNote = waitHint?.rawMs !== undefined
+                            ? ` (the requested wait was longer than the cap; honoring ${Math.ceil(waitHint.ms / 1000)}s instead of ${Math.ceil(waitHint.rawMs / 1000)}s)`
+                            : "";
                         const statusPhase = r?.status === 429 ? "rate_limited" : netErr !== undefined ? "reconnecting" : "retrying";
                         emitBrainTelemetry({ kind: "retry", attempt: attempt + 1, phase: "connect" });
                         announcedRetry = true;
@@ -381,10 +385,10 @@ export function runStreamingBrain(args) {
                         await sleepAnnouncingRetry(delayMs, signal, (remainingMs) => ({
                             phase: statusPhase,
                             detail: statusPhase === "rate_limited"
-                                ? "rate limited, backing off"
+                                ? `rate limited, backing off${truncationNote}`
                                 : statusPhase === "reconnecting"
                                     ? "connection lost, reconnecting"
-                                    : "transient error, retrying",
+                                    : `transient error, retrying${truncationNote}`,
                             retryInSec: Math.ceil(remainingMs / 1000),
                             retryInMs: remainingMs,
                             attempt: attempt + 1,

package/dist/core/checkpoint-store.js

@@ -243,6 +243,9 @@ export function winnerFromOutcome(outcome) {
 }
 const CHECKPOINT_CONTROL_CHARS_RE = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/;
 export function validatePendingSteer(steer) {
+    if (steer === null || typeof steer !== "object") {
+        throw new CheckpointError("steering.invalid_content", `steering entry must be an object carrying text/trusted (got ${steer === null ? "null" : typeof steer})`);
+    }
     const allowed = new Set(PENDING_STEER_FROZEN_FIELDS.filter((f) => f !== "seq"));
     for (const key of Object.keys(steer)) {
         if (!allowed.has(key)) {
@@ -250,53 +253,76 @@ export function validatePendingSteer(steer) {
                 `a field this worker does not know would be dropped silently on the parked leg`);
         }
     }
-    if (steer.actor !== undefined)
-        validateActorAssertion(steer.actor);
-    if (steer.inputId !== undefined && (steer.inputId === "" || steer.inputId.length > MAX_STEER_INPUT_ID_CHARS)) {
+    const text = steer.text;
+    const trusted = steer.trusted;
+    const actor = steer.actor;
+    const inputId = steer.inputId;
+    const priority = steer.priority;
+    if (typeof text !== "string") {
+        throw new CheckpointError("steering.invalid_content", "steering text must be a string");
+    }
+    if (typeof trusted !== "boolean") {
+        throw new CheckpointError("steering.invalid_content", "steering trusted must be a boolean stated by the caller");
+    }
+    if (inputId !== undefined && typeof inputId !== "string") {
+        throw new CheckpointError("steering.invalid_content", "steering inputId must be a string when supplied");
+    }
+    if (priority !== undefined && priority !== "now" && priority !== "next" && priority !== "later") {
+        throw new CheckpointError("steering.invalid_content", `steering priority "${typeof priority === "string" ? priority : priority === null ? "null" : typeof priority}" is outside the injection-priority domain ("now", "next", "later")`);
+    }
+    const actorTwin = actor === undefined ? undefined : captureActorAssertion(actor);
+    if (inputId !== undefined && (inputId === "" || inputId.length > MAX_STEER_INPUT_ID_CHARS)) {
         throw new CheckpointError("steering.invalid_content", `steering inputId must be a non-empty string of at most ${MAX_STEER_INPUT_ID_CHARS} characters`);
     }
-    if (steer.inputId === LEGACY_PENDING_STEER_INPUT_ID) {
+    if (inputId === LEGACY_PENDING_STEER_INPUT_ID) {
         throw new CheckpointError("steering.invalid_content", `steering inputId "${LEGACY_PENDING_STEER_INPUT_ID}" is reserved for a pre-queue parked steer and cannot be supplied by a caller`);
     }
-    if (sanitizeUntrustedText(steer.text) !== steer.text) {
+    if (sanitizeUntrustedText(text) !== text) {
         throw new CheckpointError("steering.invalid_content", "steering text must not contain a system-reminder break-out tag");
     }
-    if (CHECKPOINT_CONTROL_CHARS_RE.test(steer.text)) {
+    if (CHECKPOINT_CONTROL_CHARS_RE.test(text)) {
         throw new CheckpointError("steering.invalid_content", "steering text must not contain control characters");
     }
-    if (steer.text.length > MAX_PENDING_STEER_CHARS) {
-        throw new CheckpointError("steering.invalid_content", `steering text must be at most ${MAX_PENDING_STEER_CHARS} characters (got ${steer.text.length})`);
+    if (text.length > MAX_PENDING_STEER_CHARS) {
+        throw new CheckpointError("steering.invalid_content", `steering text must be at most ${MAX_PENDING_STEER_CHARS} characters (got ${text.length})`);
     }
     return {
-        text: steer.text,
-        trusted: steer.trusted,
-        ...(steer.actor !== undefined ? { actor: freezeActorAssertion(steer.actor) } : {}),
-        inputId: steer.inputId ?? uuidv7(),
-        ...(steer.priority !== undefined ? { priority: steer.priority } : {}),
+        text,
+        trusted,
+        ...(actorTwin !== undefined ? { actor: actorTwin } : {}),
+        inputId: inputId ?? uuidv7(),
+        ...(priority !== undefined ? { priority: priority } : {}),
     };
 }
 export const MAX_ACTOR_FIELD_CHARS = 256;
 export const MAX_STEER_INPUT_ID_CHARS = 128;
 export const ACTOR_ASSERTION_FROZEN_FIELDS = ["id", "hostAsserted", "issuer"];
-function validateActorAssertion(actor) {
+function captureActorAssertion(actor) {
+    if (actor === null || typeof actor !== "object") {
+        throw new CheckpointError("steering.invalid_content", `actor must be an object carrying the attribution fields (got ${actor === null ? "null" : typeof actor})`);
+    }
+    const supplied = actor;
     const allowed = new Set(ACTOR_ASSERTION_FROZEN_FIELDS);
     for (const key of Object.keys(actor)) {
         if (!allowed.has(key)) {
             throw new CheckpointError("steering.invalid_content", `unknown actor field "${key}" — the persisted actor shape is frozen (${[...allowed].join(", ")})`);
         }
     }
-    if (typeof actor.id !== "string" || actor.id === "" || actor.id.length > MAX_ACTOR_FIELD_CHARS) {
+    const id = supplied.id;
+    const hostAsserted = supplied.hostAsserted;
+    const issuer = supplied.issuer;
+    if (typeof id !== "string" || id === "" || id.length > MAX_ACTOR_FIELD_CHARS) {
         throw new CheckpointError("steering.invalid_content", `actor.id must be a non-empty namespaced string of at most ${MAX_ACTOR_FIELD_CHARS} characters (e.g. "slack:U123")`);
     }
-    if (typeof actor.hostAsserted !== "boolean") {
+    if (typeof hostAsserted !== "boolean") {
         throw new CheckpointError("steering.invalid_content", "actor.hostAsserted must be a boolean stated by the host");
     }
-    if (actor.issuer !== undefined && (actor.issuer === "" || actor.issuer.length > MAX_ACTOR_FIELD_CHARS)) {
+    if (issuer !== undefined && (typeof issuer !== "string" || issuer === "" || issuer.length > MAX_ACTOR_FIELD_CHARS)) {
         throw new CheckpointError("steering.invalid_content", `actor.issuer must be a non-empty string of at most ${MAX_ACTOR_FIELD_CHARS} characters`);
     }
     for (const [field, value] of [
-        ["id", actor.id],
-        ["issuer", actor.issuer],
+        ["id", id],
+        ["issuer", issuer],
     ]) {
         if (value === undefined)
             continue;
@@ -304,13 +330,7 @@ function validateActorAssertion(actor) {
             throw new CheckpointError("steering.invalid_content", `actor.${field} must not contain control characters or a system-reminder break-out tag`);
         }
     }
-}
-function freezeActorAssertion(actor) {
-    return {
-        id: actor.id,
-        hostAsserted: actor.hostAsserted,
-        ...(actor.issuer !== undefined ? { issuer: actor.issuer } : {}),
-    };
+    return { id, hostAsserted, ...(issuer !== undefined ? { issuer } : {}) };
 }
 export function readPendingSteerQueue(state) {
     const legacy = state.pendingSteer === undefined

package/dist/core/memory-engine/engine.d.ts

@@ -49,7 +49,9 @@ export declare class MemoryEngine {
     constructor(opts: MemoryEngineOptions);
     private discloseAnnounceFailure;
     materialize(scopes: readonly string[], writeScope: string | null): Promise<MemorySessionHandle>;
-    inject(handle: MemorySessionHandle): MemoryInjection;
+    inject(handle: MemorySessionHandle, opts?: {
+        writeToolMounted?: boolean;
+    }): MemoryInjection;
     gateWrite(handle: MemorySessionHandle, canonicalPath: string, content: string): {
         ok: true;
     } | {

package/dist/core/memory-engine/engine.js

@@ -188,14 +188,15 @@ export class MemoryEngine {
         }
         return handle;
     }
-    inject(handle) {
-        const instruction = handle.writeScope !== null ? buildMemoryInstruction(handle.writableRoot) : "";
+    inject(handle, opts) {
+        const writeChannel = handle.writeScope !== null && opts?.writeToolMounted !== false;
+        const instruction = writeChannel ? buildMemoryInstruction(handle.writableRoot) : "";
         const indexPath = join(handle.writableRoot, MEMORY_INDEX_FILENAME);
         const onDisk = readSafe(indexPath);
         const indexText = onDisk !== undefined && onDisk.trim() !== "" ? onDisk : handle.indexText;
         const truncated = truncateIndex(indexText);
         const index = composeMemoryBlock(truncated, handle.writeScope ?? handle.scopes[0] ?? "memory");
-        const indexSeed = handle.writeScope !== null && onDisk !== undefined && (onDisk.trim() === "" || truncated === onDisk)
+        const indexSeed = writeChannel && onDisk !== undefined && (onDisk.trim() === "" || truncated === onDisk)
             ? { path: indexPath, content: onDisk }
             : undefined;
         let announcements;

package/dist/core/memory-recall.d.ts

@@ -36,7 +36,7 @@ export type SelectiveRecallResult = {
 export declare function resolveLinkedIds(headers: MemoryNoteHeader[], selected: MemoryNoteRecord[], max: number): string[];
 export declare function buildManifestText(headers: MemoryNoteHeader[]): string;
 export declare function validateSelectedIds(headers: MemoryNoteHeader[], ids: string[], max: number): string[];
-export declare function composeSelectiveBody(manifestText: string, selected: MemoryNoteRecord[], nowMs: number, linked?: MemoryNoteRecord[], recallable?: boolean): string;
+export declare function composeSelectiveBody(manifestText: string, selected: MemoryNoteRecord[], nowMs: number, linked?: MemoryNoteRecord[], recallable?: boolean, recallToolName?: string): string;
 export declare function encodeSurfacedKey(scope: string, id: string): string;
 export interface ScopedNoteHeader extends MemoryNoteHeader {
     scope: string;

package/dist/core/memory-recall.js

@@ -102,7 +102,7 @@ export function validateSelectedIds(headers, ids, max) {
     }
     return out;
 }
-export function composeSelectiveBody(manifestText, selected, nowMs, linked = [], recallable = true) {
+export function composeSelectiveBody(manifestText, selected, nowMs, linked = [], recallable = true, recallToolName) {
     const renderNote = (r, label) => {
         const ageMs = nowMs - r.mtimeMs;
         const verify = r.timestampMissing || ageMs > ONE_DAY_MS ? " — verify it's still current" : "";
@@ -124,8 +124,9 @@ export function composeSelectiveBody(manifestText, selected, nowMs, linked = [],
         body = `${buf.subarray(0, cut).toString("utf8")}\n<selected notes truncated to ${SELECTED_BODY_MAX_BYTES} bytes>`;
     }
     const selectedSection = selected.length > 0 ? `\n\nRelevant notes:\n${body}` : "\n\n(no notes selected as relevant to this task)";
+    const recallCall = recallToolName !== undefined ? `call ${recallToolName}` : `search the memory-recall tool bound to this scope`;
     const manifestSection = recallable
-        ? `Memory index — to load a note in full, call Recall with keywords from its description:\n${sanitizeUntrustedText(manifestText, ["user_memory"])}`
+        ? `Memory index — to load a note in full, ${recallCall} with keywords from its description:\n${sanitizeUntrustedText(manifestText, ["user_memory"])}`
         : "";
     return `${manifestSection}${selectedSection}`;
 }

package/dist/core/runner/prepare-memory.d.ts

@@ -8,6 +8,7 @@ export interface PrepareMemoryInput {
     memoryWriteGateRef: {
         current?: BeforeWriteHook;
     };
+    writeToolsMounted: boolean;
     admissionCtx: {
         orgMemoryDenied: boolean;
         complianceDegraded: boolean;

package/dist/core/runner/prepare-memory.js

@@ -135,7 +135,7 @@ export async function prepareMemory(input) {
                 const writeIsPersonal = p.writePlane === "personal";
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
-                injectFn = () => mergeInjections(projectEngine.inject(projectHandle), personalEngine.inject(personalHandle));
+                injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted }));
                 harvestBoth = async () => {
                     const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
                     const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
@@ -159,7 +159,7 @@ export async function prepareMemory(input) {
                 const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = personalEngine;
                 writeHandle = handle;
-                injectFn = () => personalEngine.inject(handle);
+                injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
                 harvestBoth = () => personalEngine.harvest(handle);
             }
             else {
@@ -171,7 +171,7 @@ export async function prepareMemory(input) {
                 const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = engine;
                 writeHandle = handle;
-                injectFn = () => engine.inject(handle);
+                injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
                 harvestBoth = () => engine.harvest(handle);
             }
             memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);

package/dist/core/runner/prepare-task.d.ts

@@ -16,6 +16,7 @@ import { type BrainCallGuardrailRef } from "../../brain/timeout.js";
 import { type OutputRef, type BlockedRef, type SkillListingEntry } from "./synthetic-tools.js";
 import type { MemoryEngine } from "../memory-engine/engine.js";
 import { type ToolManifestRow } from "../../prompt-assembly/tool-catalog.js";
+import type { ToolDisclosureManifest } from "../trace.js";
 import type { TaskNotificationPayload } from "../task-notification.js";
 import { type CwdRef } from "../../tools/fs/index.js";
 import { type WorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
@@ -111,6 +112,7 @@ export interface Prepared {
             elements: import("../../prompt-assembly/turn-snapshot.js").CacheIdentityElements;
         };
         lowering?: import("../../prompt-assembly/turn-snapshot.js").LoweringRecord;
+        toolDisclosure?: ToolDisclosureManifest;
     };
     epochDeclaredSections: import("../../prompt-assembly/epoch.js").EpochDeclaredSections;
     turnSnapshot?: import("../../prompt-assembly/turn-snapshot.js").TurnPromptSnapshot;
@@ -125,6 +127,7 @@ export interface Prepared {
     activeTools: Set<string>;
     deferredToolNames?: ReadonlySet<string>;
     toolMaterializeStatic: boolean;
+    staticFaceFor?: (name: string) => boolean;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;

package/dist/core/runner/prepare-task.js

@@ -38,7 +38,7 @@ import { pathToUri } from "../lsp-protocol.js";
 import { DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, createOffloadPersist, firstPartyOffloadPolicy, InMemoryToolResultStore, RunnerSharedToolResultStore, ScopedToolResultStore, isVolatileOffloadStore, OFFLOAD_TOOL_NAME, createReadToolResultTool, withToolResultOffload, } from "../tool-result-store.js";
 import { OUTPUT_TOOL_NAME, REPORT_FINDINGS_TOOL_NAME, SKILL_CONTENT_MAX_CHARS, SKILL_TOOL_NAME, createOutputTool, createReportBlockedTool, createReportFindingsTool, createSkillTool, normalizeSkills } from "./synthetic-tools.js";
 import { compileOutputSchema } from "./strict-output-schema.js";
-import { TOOL_SEARCH_NAME, buildDeferredRegistry, classifyDeferred, extractDiscoveredToolNames, createPlaceholderTool, createToolSearchTool, } from "./tool-disclosure.js";
+import { TOOL_SEARCH_NAME, buildDeferredRegistry, classifyDeferred, extractDiscoveredToolNames, createPlaceholderTool, createToolSearchTool, staticSchemaRenderable, } from "./tool-disclosure.js";
 import { composeMemoryBlock } from "../memory.js";
 import { preflightLockedConfig } from "../locked-config.js";
 import { COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, complianceCallDenial, resolveComplianceDenies } from "../compliance.js";
@@ -629,6 +629,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     if (extraBodyCollisions.length > 0) {
         deps.onError?.(new Error(`model.extraBody contains reserved key(s) [${extraBodyCollisions.join(", ")}] that core owns and sets itself — they are ignored. Remove them from extraBody.`), { phase: "config", sessionId });
     }
+    if (model.extraBody !== undefined && Object.prototype.hasOwnProperty.call(model.extraBody, "max_completion_tokens")) {
+        const e = new Error(`model.extraBody supplies "max_completion_tokens" — this spelling is engine-owned (the overflow retry ` +
+            `adjusts the per-request output cap, and a constant extraBody value would override that adjustment on ` +
+            `every retry). Set the cap via limits.maxOutputTokens (per request) or model.maxTokens instead.`);
+        e.code = "config.extra_body_output_cap";
+        throw e;
+    }
     const nestedStats = { tokens: 0, turns: 0, tasks: 0, costMicroUsd: 0, anyUnpriced: false };
     if (resume) {
         nestedStats.tokens = resume.seed.nestedStats.tokens;
@@ -1592,6 +1599,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     return memoryWriteGateRef.current?.(w);
                 },
                 mountBackgroundTaskTools: false,
+                monitorToolActive: backgroundTaskToolsActive && !(toolFaceSnapshot.exclude?.includes("Monitor") ?? false),
             });
             {
                 const bandNames = new Set(band.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
@@ -1844,6 +1852,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             sessionId,
             taskRootPath,
             memoryWriteGateRef,
+            writeToolsMounted: handsEnabled && spec.handsReadOnly !== true && !(toolFaceSnapshot.exclude?.includes("Write") ?? false),
             admissionCtx: {
                 orgMemoryDenied: complianceDenies.has("org_memory_mount"),
                 complianceDegraded,
@@ -2282,6 +2291,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             .map((s) => ({ name: inlineUntrusted(s.name, 160), ...(s.error !== undefined ? { error: inlineUntrusted(s.error, 240) } : {}) }));
         let toolsDeltaRef;
         let toolMaterializeStatic = false;
+        const staticFaceForRef = {};
         if (deferred.size > 0 || failedMcpServers.length > 0) {
             toolsDeltaRef = { pending: [], pendingRemoved: [], pendingReadded: [], pendingFailed: failedMcpServers };
         }
@@ -2293,6 +2303,33 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
+            const envStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
+            if (envStrategy !== undefined && envStrategy !== "swap" && envStrategy !== "static") {
+                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(envStrategy)}).`);
+                e.code = "config.tool_materialize_invalid";
+                throw e;
+            }
+            const requestedStrategy = spec.toolMaterializeStrategy ?? envStrategy ?? "swap";
+            const laneDegrade = requestedStrategy === "static" && spec.deferSelfResolve === false;
+            const materializeStatic = requestedStrategy === "static" && !laneDegrade;
+            toolMaterializeStatic = materializeStatic;
+            promptManifest.toolDisclosure = {
+                deferredTools: deferred.size,
+                strategy: materializeStatic ? "static" : "swap",
+                source: laneDegrade ? "degraded_no_direct_lane" : spec.toolMaterializeStrategy !== undefined ? "spec" : envStrategy !== undefined ? "env" : "default",
+            };
+            const everExempt = new Set();
+            const staticFaceFor = (name) => {
+                if (!materializeStatic)
+                    return false;
+                if (everExempt.has(name))
+                    return false;
+                if (staticSchemaRenderable(tools.find((t) => t.name === name)?.parameters))
+                    return true;
+                everExempt.add(name);
+                return false;
+            };
+            staticFaceForRef.current = staticFaceFor;
             let activationChain = Promise.resolve();
             const serializeActivation = (section) => {
                 const p = activationChain.then(section);
@@ -2314,6 +2351,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         };
                     },
                     ...(executionMode !== undefined ? { executionMode } : {}),
+                    staticFace: () => staticFaceFor(name),
                     activate: async () => serializeActivation(async () => {
                         if (activeTools.has(name))
                             return undefined;
@@ -2358,16 +2396,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             };
             offloadReachableToolsRef.current = callableToolNames;
             let toolSearch;
-            const envStrategy = process.env.SEMA_TOOL_MATERIALIZE_STRATEGY;
-            if (envStrategy !== undefined && envStrategy !== "swap" && envStrategy !== "static") {
-                const e = new Error(`SEMA_TOOL_MATERIALIZE_STRATEGY must be "swap" or "static" (got ${JSON.stringify(envStrategy)}).`);
-                e.code = "config.tool_materialize_invalid";
-                throw e;
-            }
-            const materializeStatic = (spec.toolMaterializeStrategy ?? envStrategy ?? "static") === "static" && spec.deferSelfResolve !== false;
-            toolMaterializeStatic = materializeStatic;
             const buildToolList = (active) => {
-                const list = tools.map((t) => (deferred.has(t.name) && (materializeStatic || !active.has(t.name)) ? placeholders.get(t.name) : t));
+                const list = tools.map((t) => (deferred.has(t.name) && (staticFaceFor(t.name) || !active.has(t.name)) ? placeholders.get(t.name) : t));
                 list.push(toolSearch);
                 return list;
             };
@@ -2408,8 +2438,9 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 listingRide: (newly) => listingRideRef.current?.(newly),
                 mountedNames: callableToolNames,
                 directCallEnabled: spec.deferSelfResolve !== false,
+                isMounted: (name) => tools.some((t) => t.name === name),
                 ...(materializeStatic
-                    ? { staticSchemaFor: (name) => tools.find((t) => t.name === name)?.parameters }
+                    ? { staticSchemaFor: (name) => (staticFaceFor(name) ? tools.find((t) => t.name === name)?.parameters : undefined) }
                     : {}),
                 serializeActivation,
             });
@@ -4108,7 +4139,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             : undefined;
         overheadState.promptChars = systemPrompt.length;
         const preparedHolder = {};
-        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
+        const buildPrepared = () => ({ harness, session, sessionId, taskRootPath, model, thinking, compModel, mcp: mcp, ...(a2a !== undefined && a2a.tools.length > 0 ? { a2a } : {}), blockedRef, outputRef, abortController, conflictRef, blockedToolCalls, nestedStats, ...(rewindNotes.length > 0 ? { rewindNotes } : {}), cwdRef: handsCwdRef, ...(worktreeSessionRef !== undefined ? { worktreeSessionRef } : {}), ...(workspaceStateSettle !== undefined ? { workspaceStateSettle } : {}), denyNarrowingPolicy, ...(basePolicyForResumeEdit !== undefined ? { basePolicyForResumeEdit } : {}), releaseSignal, settleContentAskBindings, cacheBreakDetector, cacheFingerprint, wiringManifest, promptManifest, epochDeclaredSections, activeTools, ...(deferred.size > 0 ? { deferredToolNames: deferred } : {}), toolMaterializeStatic, ...(staticFaceForRef.current !== undefined ? { staticFaceFor: staticFaceForRef.current } : {}), ownedEnv, suspendRef, suspendProgressRef, reviewRef, remoteEnvFailures, reviewRequestRef, suspendLoopRef, suspendForResource, ...(suspendForPlatformLimit !== undefined ? { suspendForPlatformLimit } : {}), ...(envLifetimeSuspendAt !== undefined ? { envLifetimeSuspendAt } : {}), ...(usageGovernance !== undefined ? { usageGovernance } : {}), callIssuedAtRef, brainCallGuardrailRef, suspendForReview, resourceLedger: priorLedger, liveSpendRef, humanReviewRef, now, tools, toolEffects, wakeRecovered, promptOverheadTokens, lastBrainContext, readTaskFile, recentlyReadFiles, normalizeAttachmentPath, isDedupStubResult, ...(onCompactionApplied ? { onCompactionApplied } : {}), compactionReuseRef, trimPressureRef, ...(memoryEngineSession ? { memoryEngineSession } : {}), ...(subagentRetain ? { subagentRetain } : {}), ...(lspDiagnostics && nudgeLspOnEdit ? { lspDiagnostics: { registry: lspDiagnostics, nudge: nudgeLspOnEdit, runIdent: lspRunIdent } } : {}), planModeRef, ...(dateChange ? { dateChange } : {}), ...(instructionSources ? { instructionSources } : {}), ...(workflowSizeGuideline ? { workflowSizeGuideline } : {}), ...(detectExternalChanges ? { detectExternalChanges } : {}), ...(toolsDeltaRef ? { toolsDeltaRef } : {}), ...(agentListing ? { agentListing } : {}), ...(skillsListing ? { skillsListing } : {}), announcedListingsRef, listBackgroundTasks, ...(turnSnapshotRef.current !== undefined ? { turnSnapshot: turnSnapshotRef.current } : {}), ...(centerCompactionCandidate !== undefined ? { centerCompactionCandidate } : {}) });
         const prepared = buildPrepared();
         preparedHolder.current = prepared;
         return prepared;