@sema-agent/core 5.14.0 → 5.16.0

package/CHANGELOG.md

@@ -1,7 +1,181 @@
 # Changelog
 
+## 5.16.0 — 2026-08-07
+
+### BREAKING
+
+- **`TaskRegistry.reviveBackgroundAgent` is now async and CLAIMS the durable row before reviving.**
+  A retained revive and a foreign tier-3 claim now arbitrate in one domain: the winner takes clean
+  write authority (`writerEpoch` bump via guarded CAS, in-memory flip only after the claim), the
+  loser gets the existing `still_running`/`not_found` refusals. A revive the store cannot confirm is
+  refused instead of running with a silently lost persistent identity; a pre-poisoned write lane
+  re-establishes ownership through the store and hands off to a fresh lane. Closes a window where a
+  session's narrowed org-admission verdict was silently dropped and a later cross-process revival
+  seeded from the stale wider one (dropped write-backs are now also disclosed via
+  `process.emitWarning`).
+- **The memory engine's `# Memory` write instruction (and its index read-seed) require the `Write`
+  tool on the assembled roster.** `handsReadOnly: true`, hands-less runs, and
+  `excludeTools: ["Write"]` no longer receive the write instruction or seed files; the fenced index
+  still injects. Engine-direct hosts that manage their own mounts keep the historical behavior by
+  omitting the new `inject()` option. Downstream tests pinning the old always-on instruction must
+  re-pin under the new predicate.
+
+### Fixed
+
+- An `env_failed` replay binds the recorded deny/review note: `ResolvedOutcome` gains an optional
+  persisted `reason`, recorded on the approval and review lanes and compared on replay. Additive
+  compatibility: a row with no recorded note leaves that dimension unbound, so pre-existing rows
+  replay unchanged.
+- A resume presenting an already-consumed checkpoint token is answered honestly:
+  `checkpoint.already_resolved` (confirmed against the live row) or
+  `checkpoint.reopened_concurrently` (a resolve/reopen cycle raced the resume) — never a refusal
+  claiming the row is still pending. Terminal-state refusals name the observed status without
+  coercing store-supplied values.
+- The approval lane's `reason` is validated as plain text at capture; malformed decisions and
+  hostile text shapes get typed refusals instead of raising inside the refusal path.
+- Orchestration guidance, the TaskOutput tool card, and the selective-recall affordance stop
+  teaching retired tool names: the workflow tool is named by its wire name, and
+  `composeSelectiveBody` accepts an optional caller-supplied `recallToolName` (additive).
+- The gh rate-limit hint's Monitor clause follows the real Monitor mount (dropped when the Monitor
+  tool is not on the roster).
+- The exported `MEMORY_SAFETY`/`MEMORY_HYGIENE` prompt assets are reworded name-free (they taught
+  two retired tool names; semantics unchanged).
+
+### Added
+
+- `test/tool-name-literal-gate.test.ts`: every src string literal is checked against the retired
+  tool-name table on a per-directory ratchet (per-file ceilings under `src/prompts`).
+- Standing live release legs: a deferred tool with a required structured argument must converge to a
+  real schema-valid call after activation, and the search surface must answer a live hunt.
+
+## 5.15.0 — 2026-08-06
+
+> Post-release addendum (2026-08-06): the new `toolDisclosure` diagnostics keys ride
+> `prompt.assembled`. A service layer that projects that event through an allow-list must add the
+> new keys explicitly, or they are silently dropped from its stored/forwarded copy.
+
+### 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/agents/subagent.js

@@ -447,12 +447,13 @@ export function createSubagentResume(deps) {
                 signal: abort.signal,
             };
             if (deps.registry !== undefined && deps.taskId !== undefined && deps.taskAccess !== undefined) {
-                const revived = deps.registry.reviveBackgroundAgent(deps.taskId, deps.taskAccess, abort);
+                const revived = await deps.registry.reviveBackgroundAgent(deps.taskId, deps.taskAccess, abort);
                 if (!revived.ok) {
                     entry.resumeCount -= 1;
                     entry.cycleSeq -= 1;
                     throw configError(revived.reason === "still_running"
-                        ? "resume unavailable: the agent's registry row is still running (a concurrent resume already revived it) — wait for its completion notification."
+                        ?
+                            "resume unavailable: the agent's registry row is not available for a resume right now (it is running, or another revival claimed it) — wait for its completion notification and send again."
                         : "resume unavailable: the agent's registry row no longer exists (terminal GC) — relaunch a new agent instead.", revived.reason === "still_running" ? "steering.still_running" : "resume.row_gone");
                 }
                 reviveCycle = revived.cycle;

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.d.ts

@@ -214,6 +214,7 @@ export interface ResolvedOutcome {
     decision: "allow" | "deny" | "approve" | "reject" | "edit";
     updatedInput?: unknown;
     answer?: QuestionAnswer;
+    reason?: string;
 }
 export type ReopenReason = "env_failed" | "tool_unavailable";
 export interface ResolveExpectation {

package/dist/core/checkpoint-store.js

@@ -230,6 +230,7 @@ export function winnerFromOutcome(outcome) {
             boundCallId: `gate:${outcome.gate}`,
             decision: outcome.decision,
             ...(editedPlan !== undefined ? { updatedInput: editedPlan } : {}),
+            ...(outcome.reason !== undefined ? { reason: outcome.reason } : {}),
         };
     }
     if (outcome.gate !== "policy_ask")
@@ -239,10 +240,14 @@ export function winnerFromOutcome(outcome) {
         decision: outcome.decision,
         ...(outcome.updatedInput === undefined ? {} : { updatedInput: outcome.updatedInput }),
         ...(outcome.answer === undefined ? {} : { answer: outcome.answer }),
+        ...(outcome.reason === undefined ? {} : { reason: outcome.reason }),
     };
 }
 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 +255,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 +332,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;