@sema-agent/core 5.25.0 → 5.27.0

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

@@ -29,7 +29,7 @@ import { inlineUntrusted } from "../untrusted-text.js";
 import { policyAskClassOf } from "../ask-class.js";
 import { emitTrace } from "../trace.js";
 import { createSessionRulePolicy } from "./session-rule-policy.js";
-import { cloneObserverInput, createHookEnvCapabilities, createPreToolUseConstraintPolicy, formatHookFeedback, runToolGate } from "../hooks.js";
+import { cloneObserverInput, createHookEnvCapabilities, createPreToolUseConstraintPolicy, formatHookFeedback, persistedRuleMandateOf, runToolGate } from "../hooks.js";
 import { orgRuleVerdictFor } from "../permission-rule-org.js";
 import { reconcileInterruptedSession } from "../session-reconcile.js";
 import { CacheBreakDetector, toolsToFingerprintInputs } from "../cache-break-detector.js";
@@ -352,6 +352,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
         e.code = "config.tool_materialize_invalid";
         throw e;
     }
+    if (spec.memoryPersistenceCapable !== undefined && typeof spec.memoryPersistenceCapable !== "boolean") {
+        const e = new Error(`memoryPersistenceCapable must be a boolean when present (got ${JSON.stringify(spec.memoryPersistenceCapable)}) — a non-boolean would silently read as capable.`);
+        e.code = "config.memory_persistence_invalid";
+        throw e;
+    }
     if (spec.toolMaterializeStrategy === "static" && spec.deferSelfResolve === false) {
         const e = new Error(`toolMaterializeStrategy "static" cannot be combined with deferSelfResolve: false — with the direct-call ` +
             `lane disabled a placeholder is never swapped and never self-resolves, so no deferred tool could ever be ` +
@@ -1154,6 +1159,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
             ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
             ...(spec.envFacts !== undefined ? { envFacts: { ...spec.envFacts } } : {}),
+            ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
             getApiKeyAndHeaders: spec.getApiKeyAndHeaders,
             parentCwd: taskRootPath,
             ...(centerAdoption !== undefined ? { centerArtifactDigest: centerAdoption.artifact.artifactDigest } : {}),
@@ -1687,20 +1693,24 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
             }
             if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-                shellGatedBash = !egressTools.has("Bash") && !irreversibilityTier.has("Bash");
-                irreversibilityTier.set("Bash", shellGate === "always" ? "always" : "maybe");
+                const bashTierBefore = irreversibilityTier.get("Bash");
+                shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
+                const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
+                irreversibilityTier.set("Bash", bashEffectiveTier);
                 irreversibleTools.add("Bash");
                 const shellReadBoundary = () => ({
                     roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
                     ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
                 });
-                if (shellGate === "classify")
+                if (shellGate === "classify" && shellGatedBash)
                     reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
                 if (backgroundTaskToolsActive) {
-                    shellGatedMonitor = !egressTools.has("Monitor") && !irreversibilityTier.has("Monitor");
-                    irreversibilityTier.set("Monitor", shellGate === "always" ? "always" : "maybe");
+                    const monitorTierBefore = irreversibilityTier.get("Monitor");
+                    shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
+                    const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
+                    irreversibilityTier.set("Monitor", monitorEffectiveTier);
                     irreversibleTools.add("Monitor");
-                    if (shellGate === "classify")
+                    if (shellGate === "classify" && shellGatedMonitor)
                         reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
                 }
             }
@@ -1936,7 +1946,21 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             sessionId,
             taskRootPath,
             memoryWriteGateRef,
-            writeToolsMounted: tools.some((t) => t.name === "Write") && !(toolFaceSnapshot.exclude?.includes("Write") ?? false),
+            writeToolsMounted: tools.some((t) => t.name === "Write") &&
+                !(toolFaceSnapshot.exclude?.includes("Write") ?? false) &&
+                !(handsEnabled && isRemoteExecutionEnv(executionEnv) && spec.memoryPersistenceCapable !== true),
+            memoryPersistenceDeclared: spec.memoryPersistenceCapable,
+            rosterCanPersist: spec.memoryPersistenceCapable ??
+                tools.some((t) => {
+                    if (toolFaceSnapshot.exclude?.includes(t.name) ?? false)
+                        return false;
+                    const effect = (t.effect ?? toolEffects.get(t.name) ?? "write");
+                    if (effect === "read")
+                        return false;
+                    if (t.name !== "Write" && t.name !== "Edit" && t.name !== "NotebookEdit" && t.name !== "Bash")
+                        return false;
+                    return !(handsEnabled && isRemoteExecutionEnv(executionEnv));
+                }),
             memorySearchToolsPlanned,
             admissionCtx: {
                 orgMemoryDenied: complianceDenies.has("org_memory_mount"),
@@ -3236,9 +3260,25 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 },
             };
         })();
-        const ruleSuggestionsOf = (toolName, args) => {
+        const ruleSuggestionsOf = (toolName, args, ask) => {
             if (permissionRuleLane === undefined || toolName !== PERSISTED_RULE_TOOL)
                 return {};
+            if ((spec.principal === undefined || spec.principal === "") && deps.localOwnerRules !== true)
+                return {};
+            if (ask?.requiresRealApproval === true ||
+                ask?.persistedRuleShadowed !== undefined ||
+                ask?.decisionReason === "hook" ||
+                ask?.inheritedUnresolved === true ||
+                ask?.ancestorResolved === true) {
+                return {};
+            }
+            if (persistedRuleMandateOf({
+                egress: egressTools.has(toolName),
+                irreversibility: irreversibilityTier.get(toolName),
+                shellGated: shellGatedBash,
+            }) !== undefined) {
+                return {};
+            }
             const command = args?.command;
             if (typeof command !== "string")
                 return {};
@@ -3291,7 +3331,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     toolName: creq.toolName,
                     toolCallId: creq.toolCallId,
                     args: editArgs,
-                    ...ruleSuggestionsOf(creq.toolName, editArgs),
+                    ...ruleSuggestionsOf(creq.toolName, editArgs, { ...(re ?? {}), ancestorResolved: true }),
                     message: re.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                     ...askSourceIdentity(),
                     ...riskAxesOf(creq.toolName),
@@ -3376,7 +3416,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: creq.toolName,
                             toolCallId: creq.toolCallId,
                             args: presentedArgs,
-                            ...ruleSuggestionsOf(creq.toolName, presentedArgs),
+                            ...ruleSuggestionsOf(creq.toolName, presentedArgs, { ...(first.action === "ask" ? first : {}), ancestorResolved: true }),
                             message: first.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
@@ -3463,7 +3503,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                             toolName: creq.toolName,
                             toolCallId: creq.toolCallId,
                             args: presentedArgs,
-                            ...ruleSuggestionsOf(creq.toolName, presentedArgs),
+                            ...ruleSuggestionsOf(creq.toolName, presentedArgs, { ...(decision.action === "ask" ? decision : {}), ancestorResolved: true }),
                             message: decision.message ?? `approval required for "${creq.toolName}" (inherited parent policy)`,
                             ...askSourceIdentity(),
                             ...riskAxesOf(creq.toolName),
@@ -3776,7 +3816,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         const preview = approvalPreviewOf(req.toolName, req.args);
                         return preview !== undefined ? { preview } : {};
                     })(),
-                    ...ruleSuggestionsOf(req.toolName, req.args),
+                    ...ruleSuggestionsOf(req.toolName, req.args, decision.action === "ask" ? decision : undefined),
                     message: decision.message ?? `approval required for "${req.toolName}"`,
                     ...askSourceIdentity(),
                     ...riskAxesOf(req.toolName),
@@ -4263,7 +4303,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
             };
             const suspendAsk = parkLaneArmed && checkpointStore !== undefined
-                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule) => {
+                ? async (req, postHookArgs, safety, liveFaceUnavailable, realApproval, shadowedRule, askDecisionReason) => {
                     const syncFirstEligible = req.toolName === ASK_USER_QUESTION_TOOL_NAME ? contentAskRoutable(req.toolCallId) : isLiveApproverSeat(onAsk);
                     if (syncFirstEligible &&
                         runtimeCaps?.forceDurableGate !== true &&
@@ -4418,7 +4458,12 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                                     const preview = approvalPreviewOf(req.toolName, parkedArgs);
                                     return preview !== undefined ? { preview } : {};
                                 })(),
-                                ...ruleSuggestionsOf(req.toolName, parkedArgs),
+                                ...ruleSuggestionsOf(req.toolName, parkedArgs, {
+                                    ...(realApproval !== undefined ? { requiresRealApproval: true } : {}),
+                                    ...(shadowedRule !== undefined ? { persistedRuleShadowed: shadowedRule } : {}),
+                                    ...(askDecisionReason !== undefined ? { decisionReason: askDecisionReason } : {}),
+                                    ...(inheritedUnavailableAsks.has(req.toolCallId) ? { inheritedUnresolved: true } : {}),
+                                }),
                                 boundInputHash: boundInputHashOf(parkedArgs),
                                 batchToolCallIds,
                                 completedCallIds,

package/dist/core/runner/runtask.d.ts

@@ -250,7 +250,14 @@ export declare class Runner {
      *   env_failed re-resume supplied a decision ≠ the persisted winner), `reopened_concurrently` (the
      *   optimistic-concurrency `rev` changed under a concurrent resolve/reopen — re-resume against current
      *   state), `unsupported_version` (checkpoint newer than this worker / remote handle with no factory),
-     *   `already_resolved` (lost the CAS — idempotent no-op).
+     *   `already_resolved` (lost the CAS — idempotent no-op), `walltime_axis_retired` (pre-CAS: the
+     *   persisted ledger carries the retired wall-clock budget axis — a worker of the previous release can
+     *   still finish it), `resume_aborted` (the caller's signal was already aborted at entry, or aborted
+     *   during the resume — pre-CAS/edit-re-adjudication legs leave the checkpoint pending and resumable,
+     *   the post-claim leg leaves it consumed; the message says which), `reopen_failed` (an aborted resume
+     *   needed to reopen the checkpoint and the store refused, or the reopen failed in flight — the message
+     *   distinguishes terminally-consumed from state-unprovable). Each code's full contract is on
+     *   {@link CheckpointError.code}.
      */
     resume(token: CheckpointToken, outcome: ResumeOutcome, taskConfig: ResumeTaskConfig, 
     /** RB-48② (1.404): same TRUSTED run-internals seam as {@link resumeStream} — the convenience wrapper

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

@@ -12,5 +12,11 @@ import { type ContractAssertionRunner } from "./contract-harness.js";
  * with a narrower native key space owns an injective encoding, not a rejection). Before 2.1.0 the
  * bundled backends genuinely diverged on both halves (dev-green / deployment-red), so running this
  * kit against a pre-2.1.0-modeled backend is expected to go red on those two entries.
+ *
+ * Backlog #119 adds the provenance leg: `put`'s third argument and the `ownerOf` read face. `ownerOf`
+ * is typed OPTIONAL on the interface (source compatibility for a backend written against an older
+ * engine), but this kit REQUIRES it — a backend that cannot say who owns a ref cannot authorize a
+ * host-side read face, and an optional parameter one store honors while another drops it silently is
+ * exactly the divergence the two legs above exist to prevent.
  */
 export declare function toolResultStoreContract(make: () => ToolResultStore, runAssertion?: ContractAssertionRunner): Promise<void>;

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

@@ -31,5 +31,29 @@ export async function toolResultStoreContract(make, runAssertion) {
         }
         assert.equal((await store.get("tr_sess_call:1")).content, "payload-tr_sess_call:1");
     });
+    run("#119 provenance: content+owner are one write; ownerOf answers; a different owner is a TYPED refusal; unowned rows stay unowned", async () => {
+        const store = make();
+        assert.equal(typeof store.ownerOf, "function", "a backend must implement ownerOf — a store that cannot say who owns a ref cannot back a host read face");
+        const ownerOf = (ref) => Promise.resolve(store.ownerOf(ref));
+        const ref = "tr_s1~c1";
+        await store.put(ref, "0123456789", { sessionId: "sess-A", taskId: "task-1" });
+        assert.deepEqual(await ownerOf(ref), { sessionId: "sess-A", taskId: "task-1" }, "the winning write's owner round-trips");
+        await store.put(ref, "IGNORED", { sessionId: "sess-A", taskId: "task-1" });
+        assert.equal((await store.get(ref)).content, "0123456789");
+        assert.deepEqual(await ownerOf(ref), { sessionId: "sess-A", taskId: "task-1" });
+        await store.put(ref, "IGNORED");
+        assert.deepEqual(await ownerOf(ref), { sessionId: "sess-A", taskId: "task-1" }, "an ownerless put must not clear the owner");
+        for (const other of [{ sessionId: "sess-B" }, { sessionId: "sess-A", taskId: "task-2" }]) {
+            await assert.rejects((async () => store.put(ref, "other tenant's bytes", other))(), (err) => err.code === "tool_result.ref_conflict", `put(${JSON.stringify(other)}) on an occupied ref must reject with code tool_result.ref_conflict`);
+        }
+        assert.equal((await store.get(ref)).content, "0123456789", "a refused put must not have overwritten anything");
+        const unowned = "tr_no_owner~c";
+        await store.put(unowned, "bytes from a write site that stated no owner");
+        assert.equal(await ownerOf(unowned), undefined, "a row stored without provenance is UNOWNED");
+        await store.put(unowned, "bytes from a write site that stated no owner", { sessionId: "sess-A" });
+        assert.equal(await ownerOf(unowned), undefined, "put must not back-fill an owner onto an unowned row");
+        assert.equal((await store.get(unowned)).content, "bytes from a write site that stated no owner");
+        assert.equal(await ownerOf("tr_never~written"), undefined);
+    });
     await settle();
 }

package/dist/core/task-registry-agent.d.ts

@@ -415,9 +415,10 @@ export declare function notFoundRunningAgentsTail(footer: {
  *  so a structured consumer lost the failure FACT at exactly the moment it could no longer reach the
  *  live handle, left to scrape the prose body's `error:` line.
  *
- *  The status GATES live here too (killed ⇒ stoppedBy, failed ⇒ error/errorCode/retryable) rather than
- *  at the call sites: which facts a given status may carry is part of the same contract, and a gate
- *  copied per face is the same drift with extra steps. `error` is model/provider-influenceable text, so
+ *  The fact gates live here too (failed ⇒ error/errorCode/retryable/retryAfterMs; `stoppedBy` rides
+ *  whenever the ROW carries it, on any status — a reaper-settled `failed` row keeps its attribution,
+ *  see the widening note in the builder) rather than at the call sites: which facts a given row may
+ *  carry is part of the same contract, and a gate copied per face is the same drift with extra steps. `error` is model/provider-influenceable text, so
  *  the fencing + bounding (RB-386②'s posture) happens once, here, for both faces.
  *  The parked projection is this builder with fewer facts, not a third literal. */
 export interface AgentPollDetailsInput {

package/dist/core/task-registry-agent.js

@@ -6,7 +6,7 @@ import { shutdownDebug } from "./shutdown-debug.js";
 import { delimitUntrusted } from "./untrusted-text.js";
 import { boundedRedactedSummary } from "./untrusted-egress.js";
 import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, closestName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
-import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 export function ensureDurableHeartbeatLane(core) {
     if (core.durableHeartbeatTimer !== undefined)
         return;
@@ -1232,8 +1232,8 @@ export async function spillClippedAgentResult(handle, full, clipped, store, sess
     if (store === undefined)
         return clipped;
     if (handle.spillRef === undefined) {
-        const ref = buildToolResultRef(sessionId ?? "no-session", `${handle.id}_c${handle.reviveCycle ?? 0}`);
-        await store.put(ref, full);
+        const ref = buildToolResultRef(sessionId ?? "no-session", handle.id, `c${handle.reviveCycle ?? 0}`);
+        await store.put(ref, full, sessionId === undefined ? undefined : toolResultProvenanceOf(sessionId, handle.id));
         handle.spillRef = ref;
     }
     return `${clipped}\n\n[full output persisted — call ${OFFLOAD_TOOL_NAME} with ref "${handle.spillRef}" to read it back.]`;

package/dist/core/task-registry-monitor.js

@@ -1,6 +1,6 @@
 import { delimitUntrusted } from "./untrusted-text.js";
 import { assertOwnership, defaultMonitorTimers, MONITOR_MAX_TIMEOUT_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_BATCH_WINDOW_MS, MONITOR_MAX_BATCHES_PER_MINUTE, MONITOR_STORM_BURST, MONITOR_STORM_KILL_AFTER_MS, MONITOR_LINE_BUF_CAP, MONITOR_SPILL_CAP_CHARS, TASK_OUTPUT_MAX_CHARS, mintCompletionId, clipMonitorEvent, clipMonitorLine, terminalTaskSummary, accountDroppedBytes, renderSpoolBody, rollSpoolText, statusFromBackground, droppedGapNote, firstDropNote, alreadyTerminalStopNote, clipTaskOutput, sleepPollStep, } from "./task-registry-shared.js";
-import { buildToolResultRef, OFFLOAD_TOOL_NAME } from "./tool-result-store.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, toolResultProvenanceOf } from "./tool-result-store.js";
 export function registerMonitorLane(core, input) {
     assertOwnership(input, "registerMonitor");
     const id = core.mintTaskId("monitor");
@@ -61,14 +61,15 @@ function spillRolledMonitorChunk(handle, stream, dropped) {
         return;
     }
     const n = stream === "out" ? (handle.spillSegCount ?? 0) : (handle.spillErrSegCount ?? 0);
-    const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", `${handle.id}_${stream}_seg${n}`);
+    const ref = buildToolResultRef(handle.spillSessionId ?? "no-session", handle.id, `${stream}_seg${n}`);
     handle.spillCharsUsed = used + dropped.length;
     if (stream === "out")
         handle.spillSegCount = n + 1;
     else
         handle.spillErrSegCount = n + 1;
     try {
-        void Promise.resolve(store.put(ref, dropped)).catch(() => {
+        const provenance = handle.spillSessionId === undefined ? undefined : toolResultProvenanceOf(handle.spillSessionId, handle.id);
+        void Promise.resolve(store.put(ref, dropped, provenance)).catch(() => {
             handle.spillFailed = true;
         });
     }
@@ -83,8 +84,8 @@ function monitorSpillNote(handle) {
         return "";
     const sid = handle.spillSessionId ?? "no-session";
     const segLabel = (stream, n) => {
-        const first = buildToolResultRef(sid, `${handle.id}_${stream}_seg0`);
-        return n <= 1 ? `ref "${first}"` : `refs "${first}" .. "${buildToolResultRef(sid, `${handle.id}_${stream}_seg${n - 1}`)}"`;
+        const first = buildToolResultRef(sid, handle.id, `${stream}_seg0`);
+        return n <= 1 ? `ref "${first}"` : `refs "${first}" .. "${buildToolResultRef(sid, handle.id, `${stream}_seg${n - 1}`)}"`;
     };
     const clauses = [];
     if (outN > 0)

package/dist/core/task-registry.d.ts

@@ -33,8 +33,10 @@ export interface RegisterBackgroundBashInput extends TaskAccess {
     /** CC 2.1.209 对齐批A A5: the task's OUTPUT FILE — the launch receipt advertises it and the watcher
      *  mirrors every polled increment into it (append-only, unbounded — unlike the rolling in-memory
      *  spool), so "Read the output file path" is a real alternative to TaskOutput. Terminal
-     *  task-notifications carry the same path (`output_file`). Only meaningful with `onTerminal` (the
-     *  watcher is the writer); callers create the file (empty) before registering. */
+     *  task-notifications carry the same path (`output_file`). Primarily meaningful with `onTerminal`
+     *  (only the watcher mirrors increments live); a watcher-less row still gets ONE final best-effort
+     *  append at TaskStop/run-teardown (the tail drain), so the file is written even without a watcher —
+     *  there is just no live mirror. Callers create the file (empty) before registering. */
     outputFile?: string;
 }
 export interface TaskPollOptions {
@@ -369,7 +371,8 @@ export declare class TaskRegistry {
      *  BEFORE the abort()/status flip — the ordering is load-bearing: the guard below refuses markers on a
      *  non-running handle, so a caller that flips first loses its claim and attribution falls back to
      *  "system". First-marker-wins: an earlier marker (e.g. a service-wire "user") is never overwritten.
-     *  Applies to background_agent AND background_bash (same class); workflow cancellation is out of scope. */
+     *  Applies to background_agent, background_bash AND monitor handles (the markable kinds — the monitor
+     *  watcher/stop lanes mark and read it too); workflow cancellation is out of scope. */
     markStopSource(id: string, source: StopSource): void;
     /**
      * [1712] / RB-164 — attribute an ENV-LEVEL blanket sweep before it runs.

package/dist/core/tool-policy.d.ts

@@ -632,9 +632,16 @@ export interface AskRequest {
     /**
      * design/179 §4 — the persistable allow-rule forms this exact call could be covered by, so a surface can
      * offer "allow, and stop asking me this" with something concrete behind it. Present only when a
-     * persisted allow-rule lane is armed AND the call is one the lane can speak for: a compound, a
+     * persisted allow-rule lane is armed AND the call is one the lane can speak for (a compound, a
      * redirection or a substitution yields NO suggestion, which is the honest answer rather than an option
-     * that would be refused on redemption.
+     * that would be refused on redemption) AND the ask is one a persisted rule could actually clear — a
+     * mandated ask (operator shellGate:"always", the tool's own egress/irreversibility marks, a
+     * `requiresRealApproval` demand) and an ask carrying {@link persistedRuleShadowed} offer none.
+     *
+     * CONTRACT — array order is display order, narrowest first: the EXACT form is always index 0, a
+     * broader reviewed PREFIX form (at most one) follows. Basis ≤ 2. Selection indices and redemption
+     * tickets are keyed against this order, and the durable park row carries the same array under the
+     * same contract.
      *
      * ADVISORY display metadata, never adjudication input, and never a rule by itself: minting one is a
      * separate act that goes through the approval-record protocol, so a surface that ignores this field

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

@@ -10,7 +10,7 @@ import { type ToolResultStore } from "./tool-result-store.js";
  * **Simpler than CC by construction (§24.2):** a request-only, non-destructive transform (returns a new
  * array; the durable session keeps full results) applied in the existing `harness.on("context")` hook —
  * the same per-query point as `clearStaleToolResults` (the mirror of CC's query.ts:379). It is DETERMINISTIC
- * (stable `ref = tr_<sessionId>_<toolCallId>` + deterministic {@link buildPreview}), so re-running it every
+ * (stable `ref = tr_<sessionId>~<toolCallId>` + deterministic {@link buildPreview}), so re-running it every
  * query yields byte-identical previews → prompt-cache safe **without** CC's ContentReplacementState freeze
  * machine (the determinism IS the freeze), and resume-free (the transcript holds originals; this re-applies
  * on replay). Reuses design/30's offload store + preview format; with no store it falls back to a

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

@@ -1,5 +1,5 @@
 import { isToolResult } from "./message-utils.js";
-import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "./tool-result-store.js";
+import { buildPreview, buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX, toolResultContentSegment, toolResultProvenanceOf, } from "./tool-result-store.js";
 export const AGGREGATE_TOOL_RESULT_BUDGET_CHARS = 200_000;
 const HEAD = 1_000;
 const TAIL = 1_000;
@@ -61,13 +61,13 @@ export async function capAggregateToolResults(messages, opts) {
             const previewOne = async (k, before, head, tail, fromOriginal) => {
                 const m = out[k];
                 const full = textOf((fromOriginal ? messages[k] : m).content);
-                const ref = buildToolResultRef(opts.sessionId, m.toolCallId ?? `idx${k}`);
+                const ref = buildToolResultRef(opts.sessionId, m.toolCallId ?? `idx${k}`, toolResultContentSegment(full));
                 const sizes = head === HEAD && tail === TAIL ? undefined : { head, tail };
                 let previewText;
                 let storeFallback;
                 if (opts.store) {
                     try {
-                        await opts.store.put(ref, full);
+                        await opts.store.put(ref, full, toolResultProvenanceOf(opts.sessionId));
                         previewText = buildPreview(full, ref, sizes);
                         storeFallback = false;
                     }

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