@sema-agent/core 5.25.0 → 5.26.0

package/dist/core/tool-result-store.d.ts

@@ -28,14 +28,89 @@ export interface ToolResultStore {
      * durable store still owns key hygiene for its storage layer). RB-266: the floor of that hygiene is
      * NOT per-backend — every implementation rejects the unsafe ref set via {@link assertSafeToolResultRef}
      * (a volatile backend silently accepting what a durable one rejects is the drift this closes).
+     *
+     * `provenance` (backlog #119, 2026-08-10) states WHO the stored bytes belong to, so a host-side read
+     * face can authorize a fetch without parsing the ref. Its rules, uniform on every backend:
+     *   - **the write-once election decides the owner too** — whoever wins the race to store the content
+     *     is the owner, and no later writer can change that. A backend that publishes content and owner
+     *     as two objects (the file one does) may, if it is interrupted between them, leave an entry
+     *     content-complete and UNOWNED; that is the fail-closed direction (a read face refuses it) and it
+     *     is never mis-attribution, but it does mean "unowned" is a reachable state, not only a
+     *     pre-provenance one. A single-row backend (memory/SQL) has no such window;
+     *   - a later `put` on the same ref carrying the **same** provenance (or none) is the usual idempotent
+     *     no-op — the stored owner is neither re-written nor erased;
+     *   - a later `put` carrying a **different** provenance is a typed refusal
+     *     ({@link ToolResultRefConflictError}, `code: "tool_result.ref_conflict"`), never a silent no-op:
+     *     `ref` is the storage PRIMARY KEY, and with a host-supplied `sessionId` two distinct owners can
+     *     land on one ref — under a silent write-once the second owner would read back the first owner's
+     *     bytes, which is an identity fault, not a caching detail;
+     *   - provenance must never be FINER-GRAINED than the ref's own key. A ref keyed on
+     *     (session, tool call) is legitimately written by two different tasks of one session — the
+     *     Runner shares one store across its tasks on purpose, and a BYOM brain may mint the same
+     *     tool-call id in both — so stamping a `taskId` there would turn a designed sharing case into a
+     *     refusal. Write sites whose ref carries the task (the background-agent and monitor spills key
+     *     on the handle id) state it; the offload/budget/projection sites state the session only;
+     *   - an entry stored **without** provenance (written by an older engine, or by a call site that has
+     *     none) stays UNOWNED: `put` never back-fills an owner onto it (that would be adoption by a party
+     *     that cannot prove it wrote it) and {@link ownerOf} keeps answering `undefined`, which a read face
+     *     reads fail-closed. Back-filling such rows is an explicit migration, never a side effect of a write.
      */
-    put(ref: string, content: string): Promise<void> | void;
+    put(ref: string, content: string, provenance?: ToolResultProvenance): Promise<void> | void;
     /** Read a slice of the stored content. Unknown `ref` → undefined. */
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined> | ToolResultSlice | undefined;
+    /**
+     * Backlog #119 — the READ-side half of provenance: who owns `ref`. `undefined` for an unknown ref AND
+     * for a stored-but-unowned one (a row whose write stated no owner), which a read face treats identically:
+     * fail-closed, nobody is authorized. Without this operation a `put`-only provenance parameter would be
+     * write-only bookkeeping — the read face would still have nothing to decide on.
+     *
+     * Typed OPTIONAL so an implementation compiled against an older engine still satisfies the interface;
+     * the published contract kit (`toolResultStoreContract`) nevertheless REQUIRES it, because a backend
+     * that cannot answer this cannot back a host read face at all.
+     */
+    ownerOf?(ref: string): Promise<ToolResultProvenance | undefined> | ToolResultProvenance | undefined;
+}
+/**
+ * Backlog #119 — WHO a stored tool result belongs to. Structured (not a single opaque string) because
+ * the read face authorizes by COMPARING fields it already knows; `taskId` is present when the write site
+ * has one (it is a narrowing of the session, never a substitute for it).
+ *
+ * Deliberately NOT part of it: `toolCallId`. It is a retention/addressing coordinate, not an ownership
+ * one — two different tool calls in one session are the same owner.
+ */
+export interface ToolResultProvenance {
+    readonly sessionId: string;
+    readonly taskId?: string;
 }
+/** Backlog #119 — the `code` on {@link ToolResultRefConflictError}, so callers branch on a constant. */
+export declare const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
+/**
+ * Backlog #119 — a `put` whose provenance disagrees with the stored one. Typed (a `code`, like
+ * `CheckpointError`/`WorkflowRunStoreError`) rather than a silent no-op: this is the one write-once
+ * outcome where "keep what is there" would hand the second caller a reference to somebody else's bytes.
+ */
+export declare class ToolResultRefConflictError extends Error {
+    readonly ref: string;
+    readonly stored: ToolResultProvenance;
+    readonly incoming: ToolResultProvenance;
+    readonly code = "tool_result.ref_conflict";
+    constructor(ref: string, stored: ToolResultProvenance, incoming: ToolResultProvenance);
+}
+/**
+ * Backlog #119 — the ONE comparison every backend uses, so "same owner" cannot mean two things in two
+ * stores. A missing PROVENANCE on either side ⇒ no verdict (an unowned entry is never adopted, and a
+ * put with no provenance never disturbs a stored owner). Both present ⇒ every field must agree,
+ * including `taskId`: a missing task id is a DIFFERENT owner from a stated one, not a wildcard that
+ * matches it — two writers that disagree about how narrowly they own a key have not proven they are
+ * the same writer. Unequal ⇒ {@link ToolResultRefConflictError}.
+ */
+export declare function assertToolResultProvenanceMatch(ref: string, stored: ToolResultProvenance | undefined, incoming: ToolResultProvenance | undefined): void;
+/** Normalize to the stored shape: an ABSENT `taskId` and an explicit `undefined` one are one value, so
+ *  round-tripping through a durable backend (NULL column, missing JSON key) compares equal. */
+export declare function normalizeToolResultProvenance(p: ToolResultProvenance): ToolResultProvenance;
 /**
  * RB-266 — the ref-safety half of the {@link ToolResultStore} contract, shared by every backend.
  *
@@ -64,7 +139,7 @@ export interface ToolResultStore {
 export declare function assertSafeToolResultRef(ref: string): void;
 /**
  * RB-273 — the SINGLE mint point for a tool-result `ref`. Three call sites compose the same
- * `tr_<sessionId>_<toolCallId>` string (`withToolResultOffload` here, the aggregate budget's preview
+ * `tr_<sessionId>~<toolCallId>` string (`withToolResultOffload` here, the aggregate budget's preview
  * pass, and the runner's clear-with-offload persist); this is that string's one definition.
  *
  * Why it must sanitize: `sessionId` is engine-minted, but **`toolCallId` is PROVIDER-minted** — it is
@@ -87,8 +162,76 @@ export declare function assertSafeToolResultRef(ref: string): void;
  * and an unsafe one only ever lived in a memory/pg deployment, where the ref the model reads back comes
  * from the `<persisted-output ref="…">` text already in its context — the read path does not re-mint,
  * and `get` is keyed on that literal string.
+ *
+ * ── Backlog #119 (2026-08-10): the composition is now INJECTIVE ───────────────────────────────────
+ * It was not. With `_` between the segments — a character legal INSIDE both — `tr_team_blue_x`
+ * decomposed as ("team","blue_x") and as ("team_blue","x"), i.e. two distinct (session, tool call)
+ * pairs minted one ref. `ref` is the store's PRIMARY KEY under a write-once contract, so the second
+ * pair did not get an error, it got the FIRST pair's bytes back — and `sessionId` is host-supplied in a
+ * BYOM deployment, so the two pairs need not be the same tenant. (Measured on the published artifact:
+ * ("s","1_a_b") and ("s_1","a_b") produced the same ref.)
+ *
+ * The separator is now {@link REF_SEGMENT_SEPARATOR} — a character OUTSIDE {@link NATIVE_REF_CHARSET}.
+ * `refSegment` emits only characters from that charset (identity branch by test; fold branch by
+ * construction: a readable base with every out-of-charset char replaced, plus hex), so the separator
+ * can never occur inside a segment and `tr_<seg>~<seg>` decomposes exactly one way. Injectivity of the
+ * whole map then follows from `refSegment`'s own injectivity per segment.
+ *
+ * Why this is NOT a breaking change, spelled out because it looks like one:
+ *   - refs are OPAQUE HANDLES. A ref reaches the model inside the preview text and comes back verbatim
+ *     to `ReadToolResult`; `get` is keyed on that literal string and no read path re-mints;
+ *   - so an entry written under the old form stays readable forever: an old ref in an old context reads
+ *     back byte-for-byte, on every backend (the file backend's filename encoding is likewise keyed on
+ *     the literal ref, and is identity for the old form);
+ *   - the mint is deterministic per process, so a ref MINTED here is also RESOLVED here — there is no
+ *     window in which one process writes `~` and another expects `_` for the same pair. The upgrade
+ *     boundary is a process restart, and it needs no double-read window;
+ *   - the only observable change is the ref STRING for newly offloaded results, which no wire contract
+ *     pins (it is generated text, and the length ceiling downstream validators apply is unchanged).
+ * The store-key charset is unchanged as far as the shared rule is concerned ({@link assertSafeToolResultRef}
+ * accepts `~`: it is not empty/dot/separator/control). A backend whose NATIVE key space excludes `~`
+ * (the file one's filename charset) already owns an injective encoding into it — the RB-273 rule — so
+ * for that backend this simply moves engine refs from the identity branch to the digest branch.
+ *
+ * `extraSegments` (also #119) is how a call site that addresses something FINER than one tool call —
+ * a `details` member's JSON path, a stale-projection content digest — keeps that coordinate in its own
+ * segment instead of splicing it into the `toolCallId` one. Splicing was the ticket's other residue:
+ * a ref built from the compound `"<callId> <path>"` is exactly the ref another call would mint if its
+ * provider-assigned toolCallId happened to BE that whole string. With the coordinate in its own
+ * segment the two can no longer coincide — the separator cannot occur inside a segment, so refs with
+ * different segment COUNTS are always distinct, and same-count refs are distinct unless every segment
+ * matches.
+ */
+export declare function buildToolResultRef(sessionId: string, toolCallId: string, ...extraSegments: string[]): string;
+/**
+ * Backlog #119 — the ceiling on a ref this module can mint, so a durable backend can size its key
+ * column from a stated invariant instead of a guess (TiDB's was `VARCHAR(191)`, which a long
+ * three-segment ref overruns — a truncating key aliases distinct refs).
+ *
+ * Derivation: `"tr_"` (3) + four segments at their own ceiling + three separators. A segment is either
+ * an identity one (≤ {@link MAX_REF_SEGMENT_CHARS}) or a folded one (marker + ≤32 base + `-` + 64 hex
+ * = 102), so {@link MAX_REF_SEGMENT_CHARS} is the larger. Four segments is the engine's own widest
+ * shape (session + tool call + a `details` path + the content coordinate); `buildToolResultRef` is
+ * variadic, so a caller that passes more owns the wider bound.
+ */
+export declare const MAX_MINTED_TOOL_RESULT_REF_CHARS: number;
+/**
+ * Backlog #119 (adversarial review, round 2) — the CONTENT coordinate of an offload ref.
+ *
+ * A tool-call id carries no cross-turn uniqueness contract: a BYOM brain legitimately mints recurring
+ * ids like `call-1`, and the Runner shares one store across a session's tasks on purpose. Keyed on
+ * (session, tool call) alone, the second result under a recurring id hits a write-once no-op — a
+ * SUCCESSFUL put that stored nothing — while its own preview goes out naming that ref, so paging it
+ * back returns the FIRST result's bytes. Provenance cannot see this (both writers are the same
+ * session, and they legitimately are), so the ref itself has to carry content identity.
+ *
+ * 128 bits, the same width and the same reasoning as the stale-result projection that closed this in
+ * its own lane earlier: tool results are untrusted text (web content rides them), and a 48-bit
+ * truncation is birthday-collidable at ~2^24 work — a deliberate collision plus a recurring id would
+ * re-open exactly the cross-serving this closes. Deterministic, so a re-derived ref for identical
+ * content is byte-identical and the preview stays prompt-cache stable.
  */
-export declare function buildToolResultRef(sessionId: string, toolCallId: string): string;
+export declare function toolResultContentSegment(text: string): string;
 export interface ToolResultSlice {
     content: string;
     /** Byte/char offset this slice starts at. */
@@ -108,12 +251,17 @@ export declare class InMemoryToolResultStore implements ToolResultStore {
     private readonly opts?;
     /** put/get only — no scheduled deletion contract: honestly `"none"` (retention.ts). */
     readonly retention: "none";
+    /** #119: the entry is content AND owner as ONE value — the write-once election that decides the
+     *  content decides the owner in the same step (no window where an entry exists ownerless). */
     private readonly map;
     private totalChars;
     constructor(opts?: {
         maxTotalChars?: number;
     } | undefined);
-    put(ref: string, content: string): void;
+    put(ref: string, content: string, provenance?: ToolResultProvenance): void;
+    /** #119 — the owner recorded at the winning write; `undefined` for unknown AND for unowned entries,
+     *  which a read face treats identically (fail-closed). */
+    ownerOf(ref: string): ToolResultProvenance | undefined;
     /** design/80 D-2: true when NOTHING has been offloaded — a durable suspend can then proceed safely even on
      *  this in-memory store, because a cross-replica resume has no offloaded result to deref to null. */
     isEmpty(): boolean;
@@ -147,15 +295,18 @@ export declare class ScopedToolResultStore implements ToolResultStore {
     readonly volatileBacking: boolean;
     constructor(inner: ToolResultStore, scope: string);
     /** Length-prefixed namespace — unambiguous for any scope string (no delimiter-injection ambiguity).
-     *  RB-266: the scope segment is percent-ENCODED (injective, and its output charset carries no path
-     *  separator or control character), so a deployment whose trust scope contains one cannot compose a
-     *  key the inner store must reject — the ref-safety rule then applies to the caller's ref alone. */
+     *  RB-266: the scope segment is ENCODED (injective, and its output charset carries no path separator
+     *  or control character), so a deployment whose trust scope contains one cannot compose a key the
+     *  inner store must reject — the ref-safety rule then applies to the caller's ref alone. */
     private key;
-    put(ref: string, content: string): Promise<void> | void;
+    put(ref: string, content: string, provenance?: ToolResultProvenance): Promise<void> | void;
     get(ref: string, opts?: {
         offset?: number;
         limit?: number;
     }): Promise<ToolResultSlice | undefined> | ToolResultSlice | undefined;
+    /** #119 — same namespacing as {@link get}. `undefined` when the inner store predates the operation
+     *  (an unowned answer, which the read face reads fail-closed — never a fabricated owner). */
+    ownerOf(ref: string): Promise<ToolResultProvenance | undefined> | ToolResultProvenance | undefined;
     /** THIS task's offload count only — the D-2 gate's per-task semantics (see class doc). */
     isEmpty(): boolean;
 }
@@ -171,6 +322,10 @@ export declare const OFFLOAD_TOOL_NAME = "ReadToolResult";
  * "expired" are different answers). If the marker write fails too, the generic miss remains.
  */
 export declare function createOffloadPersist(store: ToolResultStore, sessionId: string): (toolCallId: string, fullText: string) => string;
+/** Backlog #119 — build the provenance a write site records, from the two coordinates every write site
+ *  already has in hand. `taskId` is omitted (not `undefined`-valued) when the run declares none, so the
+ *  stored shape compares equal across a durable round-trip. */
+export declare function toolResultProvenanceOf(sessionId: string, taskId?: string): ToolResultProvenance;
 /**
  * RB-374① — the ONE source of the "page the offloaded text back" suggestion sentence, shared by
  * {@link buildPreview} (offload preview tail) and context-edit's cleared-marker refNote. The two
@@ -228,7 +383,7 @@ export declare function buildPreview(full: string, ref: string, sizes?: {
 }, reachableTools?: ReadonlySet<string>): string;
 /**
  * Wrap an {@link AgentTool} so that an oversized text result is offloaded to `store` and replaced with a
- * preview + `ref` before it ever reaches the session/model. `ref = tr_<toolCallId>` is stable and the
+ * preview + `ref` before it ever reaches the session/model. `ref = tr_<sessionId>~<toolCallId>` is stable and the
  * store is write-once: a **same-process** replay keeps an identical (cacheable) preview; a **cross-process**
  * wake needs a durable store (the default in-memory store loses the full text — the preview still stands).
  * Image blocks are left untouched; only text is offloaded. Forwards the `onUpdate` progress callback so a

package/dist/core/tool-result-store.js

@@ -2,6 +2,34 @@ import { createHash } from "node:crypto";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
 import { TOOL_SEARCH_NAME } from "./runner/tool-disclosure.js";
+export const TOOL_RESULT_REF_CONFLICT_CODE = "tool_result.ref_conflict";
+export class ToolResultRefConflictError extends Error {
+    ref;
+    stored;
+    incoming;
+    code = TOOL_RESULT_REF_CONFLICT_CODE;
+    constructor(ref, stored, incoming) {
+        super(`tool-result store: ref ${JSON.stringify(ref)} already belongs to a different origin ` +
+            `(stored ${describeProvenance(stored)}, offered ${describeProvenance(incoming)}) — refusing to store under it`);
+        this.ref = ref;
+        this.stored = stored;
+        this.incoming = incoming;
+        this.name = "ToolResultRefConflictError";
+    }
+}
+function describeProvenance(p) {
+    return p.taskId === undefined ? `session=${p.sessionId}` : `session=${p.sessionId} task=${p.taskId}`;
+}
+export function assertToolResultProvenanceMatch(ref, stored, incoming) {
+    if (stored === undefined || incoming === undefined)
+        return;
+    if (stored.sessionId === incoming.sessionId && stored.taskId === incoming.taskId)
+        return;
+    throw new ToolResultRefConflictError(ref, stored, incoming);
+}
+export function normalizeToolResultProvenance(p) {
+    return p.taskId === undefined ? { sessionId: p.sessionId } : { sessionId: p.sessionId, taskId: p.taskId };
+}
 export function assertSafeToolResultRef(ref) {
     const bad = ref === "" ||
         ref === "." ||
@@ -14,14 +42,23 @@ export function assertSafeToolResultRef(ref) {
 }
 const NATIVE_REF_CHARSET = /^[A-Za-z0-9_.-]+$/;
 const MAX_REF_SEGMENT_CHARS = 128;
-export function buildToolResultRef(sessionId, toolCallId) {
-    return `tr_${refSegment(sessionId)}_${refSegment(toolCallId)}`;
+const REF_SEGMENT_SEPARATOR = "~";
+const FOLDED_SEGMENT_PREFIX = "fold.";
+export function buildToolResultRef(sessionId, toolCallId, ...extraSegments) {
+    return [`tr_${refSegment(sessionId)}`, refSegment(toolCallId), ...extraSegments.map(refSegment)].join(REF_SEGMENT_SEPARATOR);
 }
 function refSegment(raw) {
-    if (raw.length <= MAX_REF_SEGMENT_CHARS && NATIVE_REF_CHARSET.test(raw))
+    if (raw.length <= MAX_REF_SEGMENT_CHARS && NATIVE_REF_CHARSET.test(raw) && !raw.startsWith(FOLDED_SEGMENT_PREFIX))
         return raw;
     const base = raw.replace(/[^A-Za-z0-9_.-]/g, "-").slice(0, 32);
-    return `${base || "x"}-${createHash("sha256").update(raw, "utf8").digest("hex")}`;
+    return `${FOLDED_SEGMENT_PREFIX}${base || "x"}-${digestOfString(raw)}`;
+}
+export const MAX_MINTED_TOOL_RESULT_REF_CHARS = 3 + 4 * MAX_REF_SEGMENT_CHARS + 3;
+export function toolResultContentSegment(text) {
+    return `s${digestOfString(text).slice(0, 32)}`;
+}
+function digestOfString(s) {
+    return createHash("sha256").update(Buffer.from(s, "utf16le")).digest("hex");
 }
 export class InMemoryToolResultStore {
     opts;
@@ -35,27 +72,33 @@ export class InMemoryToolResultStore {
             throw new Error("InMemoryToolResultStore: maxTotalChars must be a number (got NaN) — omit it for an unbounded store");
         }
     }
-    put(ref, content) {
+    put(ref, content, provenance) {
         assertSafeToolResultRef(ref);
-        if (this.map.has(ref))
+        const existing = this.map.get(ref);
+        if (existing !== undefined) {
+            assertToolResultProvenanceMatch(ref, existing.provenance, provenance);
             return;
-        this.map.set(ref, content);
+        }
+        this.map.set(ref, provenance === undefined ? { content } : { content, provenance: normalizeToolResultProvenance(provenance) });
         this.totalChars += content.length;
         const cap = this.opts?.maxTotalChars;
         if (cap !== undefined && Number.isFinite(cap)) {
-            for (const [oldRef, oldContent] of this.map) {
+            for (const [oldRef, oldEntry] of this.map) {
                 if (this.totalChars <= cap || oldRef === ref)
                     break;
                 this.map.delete(oldRef);
-                this.totalChars -= oldContent.length;
+                this.totalChars -= oldEntry.content.length;
             }
         }
     }
+    ownerOf(ref) {
+        return this.map.get(ref)?.provenance;
+    }
     isEmpty() {
         return this.map.size === 0;
     }
     get(ref, opts) {
-        const full = this.map.get(ref);
+        const full = this.map.get(ref)?.content;
         if (full === undefined)
             return undefined;
         const offset = Math.min(full.length, Math.max(0, intOr(opts?.offset, 0)));
@@ -77,21 +120,32 @@ export class ScopedToolResultStore {
         this.volatileBacking = inner instanceof InMemoryToolResultStore;
     }
     key(ref) {
-        const scope = encodeURIComponent(this.scope);
+        const scope = encodeScopeSegment(this.scope);
         return `${scope.length}:${scope}:${ref}`;
     }
-    put(ref, content) {
+    put(ref, content, provenance) {
         assertSafeToolResultRef(ref);
         this.localPuts++;
-        return this.inner.put(this.key(ref), content);
+        return this.inner.put(this.key(ref), content, provenance);
     }
     get(ref, opts) {
         return this.inner.get(this.key(ref), opts);
     }
+    ownerOf(ref) {
+        return this.inner.ownerOf?.(this.key(ref));
+    }
     isEmpty() {
         return this.localPuts === 0;
     }
 }
+function encodeScopeSegment(scope) {
+    let out = "";
+    for (let i = 0; i < scope.length; i++) {
+        const ch = scope[i];
+        out += /[A-Za-z0-9]/.test(ch) ? ch : `%${ch.charCodeAt(0).toString(16).padStart(4, "0")}`;
+    }
+    return out;
+}
 export function isVolatileOffloadStore(store) {
     if (store instanceof ScopedToolResultStore)
         return store.volatileBacking;
@@ -99,15 +153,19 @@ export function isVolatileOffloadStore(store) {
 }
 export const OFFLOAD_TOOL_NAME = "ReadToolResult";
 export function createOffloadPersist(store, sessionId) {
+    const provenance = toolResultProvenanceOf(sessionId);
     return (toolCallId, fullText) => {
-        const ref = buildToolResultRef(sessionId, toolCallId);
-        void Promise.resolve(store.put(ref, fullText)).catch((err) => {
+        const ref = buildToolResultRef(sessionId, toolCallId, toolResultContentSegment(fullText));
+        void Promise.resolve(store.put(ref, fullText, provenance)).catch((err) => {
             const cause = err instanceof Error ? err.message : String(err);
-            void Promise.resolve(store.put(ref, `[offload LOST at write time: ${cause} — the inline preview is all that survived]`)).catch(() => undefined);
+            void Promise.resolve(store.put(ref, `[offload LOST at write time: ${cause} — the inline preview is all that survived]`, provenance)).catch(() => undefined);
         });
         return ref;
     };
 }
+export function toolResultProvenanceOf(sessionId, taskId) {
+    return taskId === undefined ? { sessionId } : { sessionId, taskId };
+}
 export function offloadPagebackHint(ref, form, reachableTools) {
     const activate = reachableTools !== undefined && !reachableTools.has(OFFLOAD_TOOL_NAME)
         ? `${OFFLOAD_TOOL_NAME} is not active yet — call ${TOOL_SEARCH_NAME} with {"query":"select:${OFFLOAD_TOOL_NAME}"} to activate it, then `
@@ -164,9 +222,10 @@ export function buildPreview(full, ref, sizes, reachableTools) {
 export function withToolResultOffload(tool, store, thresholdChars, sessionId, reachableTools) {
     if (!(Number.isFinite(thresholdChars) && thresholdChars > 0))
         return tool;
+    const provenance = toolResultProvenanceOf(sessionId);
     const wrappedExecute = async (toolCallId, params, signal, onUpdate) => {
         const res = await tool.execute(toolCallId, params, signal, onUpdate);
-        const offloadedDetails = res.details === undefined ? undefined : await offloadOversizedDetailStrings(res.details, store, thresholdChars, sessionId, toolCallId);
+        const offloadedDetails = res.details === undefined ? undefined : await offloadOversizedDetailStrings(res.details, store, thresholdChars, sessionId, toolCallId, provenance);
         const withDetails = (r) => offloadedDetails === undefined || offloadedDetails.value === res.details ? r : { ...r, details: offloadedDetails.value };
         if (totalTextChars(res.content) <= thresholdChars)
             return withDetails(res);
@@ -176,20 +235,20 @@ export function withToolResultOffload(tool, store, thresholdChars, sessionId, re
             .join("\n");
         if (full.length <= PREVIEW_HEAD_CHARS + PREVIEW_TAIL_CHARS)
             return withDetails(res);
-        const ref = buildToolResultRef(sessionId, toolCallId);
-        await store.put(ref, full);
+        const ref = buildToolResultRef(sessionId, toolCallId, toolResultContentSegment(full));
+        await store.put(ref, full, provenance);
         const images = res.content.filter((b) => b.type !== "text");
         return withDetails({ ...res, content: [{ type: "text", text: buildPreview(full, ref, undefined, reachableTools?.()) }, ...images] });
     };
     return { ...tool, execute: wrappedExecute };
 }
 const OFFLOADED_DETAIL_HEAD_CHARS = 2_000;
-const OFFLOADED_DETAIL_NOTICE_ALLOWANCE_CHARS = 400;
+const OFFLOADED_DETAIL_NOTICE_ALLOWANCE_CHARS = MAX_MINTED_TOOL_RESULT_REF_CHARS + 200;
 export const OFFLOADED_DETAIL_NOTICE_PREFIX = "…[offloaded — ";
 export function isOffloadedDetailReplacement(s) {
     return s.includes(`\n${OFFLOADED_DETAIL_NOTICE_PREFIX}`);
 }
-async function offloadOversizedDetailStrings(details, store, thresholdChars, sessionId, toolCallId) {
+async function offloadOversizedDetailStrings(details, store, thresholdChars, sessionId, toolCallId, provenance) {
     const puts = [];
     const onStack = new Set();
     const isPlainObject = (v) => {
@@ -199,8 +258,8 @@ async function offloadOversizedDetailStrings(details, store, thresholdChars, ses
         return p === Object.prototype || p === null;
     };
     const replace = (full, path) => {
-        const detailRef = buildToolResultRef(sessionId, toolCallId + " " + path);
-        puts.push(Promise.resolve(store.put(detailRef, full)));
+        const detailRef = buildToolResultRef(sessionId, toolCallId, path, toolResultContentSegment(full));
+        puts.push(Promise.resolve(store.put(detailRef, full, provenance)));
         return (`${full.slice(0, OFFLOADED_DETAIL_HEAD_CHARS)}\n` +
             `${OFFLOADED_DETAIL_NOTICE_PREFIX}${full.length} chars total; ref "${detailRef}"; the remainder is retained in this run's tool-result store and reads back through the deployment's tool-results face]`);
     };

package/dist/core/types.d.ts

@@ -320,6 +320,12 @@ export interface ToolSpec<TParams extends TSchema = TSchema> {
      * text under `"static"`, where the placeholder is never swapped. Use for large/MCP tool sets where
      * inlining hundreds of schemas blows up turn-1 tokens and risks prefix-cache breakage. Default: not
      * deferred (full schema inlined). See {@link RunnerDeps.deferMode}.
+     *
+     * SCOPE: this flag reaches the classifier through CALLER specs (`TaskSpec.tools`) only — a
+     * built-in/injected tool's spec never enters that list, so setting `defer` on a spec that shadows a
+     * built-in name does nothing. To defer an already-mounted tool (built-ins included), list its wire
+     * name in {@link TaskSpec.deferTools}. Also inert when the tool ends up excluded (exclusion wins)
+     * or pinned ({@link alwaysLoad} / {@link TaskSpec.alwaysLoadTools}).
      */
     defer?: boolean;
     /**
@@ -705,6 +711,17 @@ export interface ToolExecuteContext {
      *  is a DEPLOYMENT property, not a per-task one — a child in the same sandbox needs the same facts
      *  (its env block renders the scratchpad section; its root fence admits the scratchpad dir). */
     envFacts?: TaskSpec["envFacts"];
+    /**
+     * The parent task's DECLARED {@link TaskSpec.memoryPersistenceCapable} — present ONLY when the spec
+     * set it (an inferred run's ctx gains no key), Runner-filled on the same trusted seat as
+     * {@link principal}: never a model/tool argument. A delegation tool (`createSubagentTool`) forwards
+     * it into every child spec it builds so the deployment's persistence statement survives delegation:
+     * `false` is a floor a chosen agent definition cannot loosen (the read-only-memory disclosure must
+     * hold tree-wide when the deployment says nothing durable is reachable), `true` is a default a
+     * definition may narrow back to `false`. Absent ⇒ nothing is forwarded and each child's own roster
+     * inference decides, exactly as before the seat existed.
+     */
+    memoryPersistenceCapable?: boolean;
     /**
      * [893]④a — the parent task's per-model auth hook ({@link TaskSpec.getApiKeyAndHeaders}), inherited
      * verbatim down the delegation tree like `principal`/`clientContext` (Runner-filled, read-only, NEVER
@@ -1058,6 +1075,19 @@ export interface AgentDefinition {
     maxTurns?: number;
     /** Long-term memory scope for this agent (same shape as {@link TaskSpec.memory}). */
     memory?: TaskSpec["memory"];
+    /**
+     * This agent's own {@link TaskSpec.memoryPersistenceCapable} declaration — the same three-state
+     * statement, made per definition: an agent whose closure tools persist memory declares `true`
+     * (suppressing the read-only-memory disclosure no roster inference can clear), one whose roster
+     * looks write-capable but reaches no durable store declares `false` (forcing the disclosure).
+     * Arbitration with the spawning run's declaration: a parent's explicit `false` is a FLOOR and wins
+     * over a definition `true` (the disclosure is about the deployment's storage, which choosing this
+     * agent does not change); otherwise a declared definition value wins over the parent's; absent
+     * both, the child spec carries no value and the child's own roster inference decides.
+     * On the workflow lane (`agent(…, {agentType})`) the definition value fills an ABSENT governed-spec
+     * value only — a base/spec declaration of either polarity wins (the lane's spec-pinned-fields rule).
+     */
+    memoryPersistenceCapable?: boolean;
     /**
      * Observer agents (CC 2.1.206 parity — 逐字锚 docs/CC206-OBSERVER-ANCHORS-2026-07-11.md, schema
      * 面 C @28385708): "Agent type auto-spawned as a background observer whenever this agent runs.
@@ -2016,6 +2046,39 @@ export interface TaskSpec {
      * modify the project. No effect unless an `executionEnv` is injected. Default false.
      */
     handsReadOnly?: boolean;
+    /**
+     * Whether this run can persist a user's "remember X" somewhere durable — the deployment's own
+     * statement, overriding the runner's inference. The runner mounts a read-only-memory disclosure
+     * (the model must decline to "remember" instead of receipting a save that never happens) when the
+     * session provably cannot persist; provability is inferred from KNOWN store paths only (a mounted
+     * file-write tool or a write-capable shell). A caller tool that persists through its own closure
+     * (a custom memory writer) is invisible to that inference and would be contradicted by the
+     * disclosure — set `true` to declare the channel and suppress it. Set `false` to force the
+     * disclosure even when write-capable tools mount (e.g. they cannot reach any durable store);
+     * a forced `false` also replaces the `# Memory` write instruction itself and drops the
+     * preference-writing discipline and index seed that serve it.
+     * Default: inferred. The inference also treats a REMOTE execution env's hand band as unable to
+     * reach the host-side memory root (sandbox filesystem); a deployment whose remote env shares a
+     * mount with the memory root declares `true` — on such a remote, `true` also restores the
+     * `# Memory` write instruction when a Write tool mounts (a declared-capable session must be told
+     * the path, not left silent). If your persistence channel is NOT the file face, do not mount a
+     * tool named `Write` alongside the declaration, or keep the default and teach your own channel.
+     * Delegation: a DECLARED value crosses the delegation boundary (sync / background / fork spawns and
+     * the retained-resume snapshot alike). An explicit `false` is a FLOOR — a chosen
+     * {@link AgentDefinition.memoryPersistenceCapable} `true` cannot loosen it (the disclosure is
+     * about the deployment's storage, which no agent selection changes); an explicit `true` is a
+     * DEFAULT the chosen definition may narrow back to `false`; absent = absent downstream too — each
+     * child runs its own inference over its own roster. A retained child woken by a DIFFERENT run
+     * additionally folds the waker's declared `false` on top of the spawn snapshot (tighten-only,
+     * like the other resume clamps).
+     * KNOWN GAPS (registered, whole-clamp-family shapes — `handsReadOnly`/`interactiveTools` share
+     * them): a TIER-3 durable revival rebuilds the child from the REVIVER's context (the durable row
+     * records lookup keys, never a serialized spec), so the spawn-time declaration does not survive
+     * that lane — the reviver's own declaration governs; and the workflow HOST lane does not forward
+     * the host TaskSpec's declaration into `agent()` children (an {@link AgentDefinition} on the
+     * workflow agent type does carry).
+     */
+    memoryPersistenceCapable?: boolean;
     /**
      * design/119 (CC --add-dir parity): extra directories the FILE tools may access in addition to the
      * containment root — each is canonicalized into the containment allowlist and listed in the
@@ -2090,6 +2153,11 @@ export interface TaskSpec {
      *    (writes, egress, pipes, unknown commands) tightens to ask. An egress command (e.g. `curl`) suspends under
      *    the IRREVERSIBLE axis (the shell mark is irreversibility, not egress) — the kind is non-budgetable either
      *    way, so the budget resolver still never auto-approves it; the axis label is informational.
+     *    NOT unconditional: a POSITIVE per-tool mark on the shell tool keeps its seat — an explicit
+     *    `irreversibility:"always"` is never downgraded (the tier combine is tighten-only) and an explicit
+     *    `"maybe"` keeps its own probe (a probe-less explicit `"maybe"` stays fail-closed ask; the doctrine's
+     *    generic probe installs only on doctrine-owned seats). An explicit `"never"` is NOT a mark — the
+     *    doctrine governs that seat as if unmarked.
      * No effect under `handsReadOnly` (that mounts `bash_readonly`, already allowlisted) or with no execution env.
      * **Re-supply on resume:** like `toolPolicy`/`tools`/`durableApproval`, `shellGate` is part of the resume
      * task config — a resume that omits it leaves the resumed run's SUBSEQUENT `bash` calls ungated (the approved

package/dist/core/untrusted-text.d.ts

@@ -170,8 +170,12 @@ export declare function defuseControlChars(text: string): string;
  * Make untrusted text safe to interpolate INLINE on a trusted prompt line (not inside a {@link delimitUntrusted}
  * fence) — e.g. design/80 D-F echoes a chosen option label into the "The user answered:" block. Folds EVERY
  * line/space separator to a single space so the text cannot forge a new line — `\s` (covers CR/LF/TAB/VT/FF and
- * U+2028/U+2029 + the Unicode spaces) PLUS U+0085 NEL, which `\s` does NOT match — caps the length, then applies
- * the same tag-neutralization (`</system-reminder>`) + fence-sentinel (`<<<`/`>>>`) defusing the fenced body gets.
+ * U+2028/U+2029 + the Unicode spaces) PLUS the whole C0 + DEL + C1 block (U+0000–U+001F, U+007F–U+009F), which
+ * `\s` does NOT fully match: the C1 half carries the 8-bit CSI/OSC/ST forms (U+009B/U+009D/U+009C) a
+ * C1-honoring terminal treats like their ESC-prefixed spellings, so leaving them through would let a
+ * 'sanitized' value repaint the trusted line it is interpolated onto (adversarial round finding) — caps the
+ * length, then applies the same tag-neutralization (`</system-reminder>`) + fence-sentinel (`<<<`/`>>>`)
+ * defusing the fenced body gets.
  * Defense-in-depth, NOT a guarantee (same posture as the rest of this module).
  */
 export declare function inlineUntrusted(text: string, maxLen?: number): string;

package/dist/core/untrusted-text.js

@@ -99,7 +99,7 @@ export function defuseControlChars(text) {
 }
 const LABEL_MAX = 160;
 export function inlineUntrusted(text, maxLen = LABEL_MAX) {
-    const oneLine = text.replace(/[\s\u0000-\u001f\u007f\u0085]+/g, " ").trim();
+    const oneLine = text.replace(/[\s\u0000-\u001f\u007f-\u009f]+/g, " ").trim();
     const cps = [...oneLine];
     const capped = cps.length > maxLen ? cps.slice(0, maxLen).join("") + "…" : oneLine;
     const out = defuseFenceMarkers(sanitizeUntrustedText(capped));

package/dist/engine/session/import-validate.js

@@ -3,12 +3,13 @@ import { leafIdAfterEntry } from "./storage-base.js";
 import { parseSessionTimestampMs } from "./timestamps.js";
 import { flattenableUserText, normalizeEngineSegments } from "../../core/untrusted-text.js";
 import { normalizePromptEpoch } from "../../prompt-assembly/epoch.js";
+import { MAX_MINTED_TOOL_RESULT_REF_CHARS } from "../../core/tool-result-store.js";
 import { PERSISTED_OUTPUT_REFS_MAX_ENTRIES, SKILL_RETENTION_PER_SKILL_MAX_CHARS, SKILL_RETENTION_TOTAL_MAX_CHARS, } from "../compaction/utils.js";
 const PATH_LIST_MAX_CHARS = 4096;
 const PATH_LIST_MAX_ENTRIES = 1000;
 const INVOKED_SKILLS_MAX_ENTRIES = 1000;
 const INVOKED_SKILL_NAME_MAX_CHARS = 1024;
-const PERSISTED_REF_MAX_CHARS = 256;
+const PERSISTED_REF_MAX_CHARS = MAX_MINTED_TOOL_RESULT_REF_CHARS;
 const ACTIVE_TOOL_NAME_MAX_CHARS = 1024;
 const ACTIVE_TOOLS_MAX_ENTRIES = 1000;
 export class StreamingImportValidator {