@sema-agent/core 5.10.0 → 5.12.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Changelog
 
+## 5.12.0 — 2026-08-05
+
+### BREAKING
+
+- **The compaction summary request FORKS the main conversation (CC form).** When the summary model IS the main model (no `compactionModel`/`summarize` role) and the run's latest main request is a faithful (untrimmed) projection, the summary request is now that request byte-for-byte — same system prompt, same message prefix, same tools — plus ONE appended user-role instruction message, so the provider's prompt cache re-serves the already-paid prefix instead of re-prefilling an independent serialized-conversation request at full price every boundary. Degradations keep the independent form byte-identical: a direct `maybeCompact` caller without `forkContext`; an explicit `compactionModel`; the PTL-recovery lane; a lossy request projection (guard-trim drop, clearStale content blanking, aggregate tool-result/media caps, orphan sweep) clears the fork seam for that boundary; and a fork attempt that fails as prompt-too-long, the empty-summary class (e.g. the model answered the fork with a tool call), OR a non-conforming response (the fork instruction demands the summary inside a closed `<summary>` envelope; a response without one — e.g. an obedient refusal under a BYOM system prompt that forbids summaries — is discarded, never persisted as history) falls back ONCE inside `compact()` to the independent (clamp-capable) form — a generic summarizer failure stays terminal (one call per pass). The fork is also refused when the snapshot's served model differs from the summary model (mid-run budget degradation): the model is part of the provider cache key, so that fork would pay a full prefill for nothing. **Consumer flips**: probes pinning the OLD summary-request shape (independent `SUMMARIZATION_SYSTEM_PROMPT` + single serialized user message) red — detect a summary request as EITHER form (independent system prompt, OR main prefix + trailing user instruction mentioning the structured summary). `MaybeCompactOptions.forkContext` (accessor) and a trailing optional `compact(..., forkContext)` parameter are the additive seams.
+
+- **Default `keepRecentTokens` drops 20000 → 0 (full compaction, CC form).** With the knob unset, a landed compaction now keeps NO verbatim token budget — the summary replaces the compacted region entirely (the cut still lands on the nearest valid floor, so tool pairs and an in-progress turn's suffix stay intact; the turn-prefix leg summarizes the rest). Explicit `keepRecentTokens` values keep their exact meaning and are the opt-back. **Consumer flips**: probes pinning "pre-compaction verbatim text survives after a default-settings compaction" red.
+
+- **The post-compact background-task restatement is DEFAULT ON** (`attachments.backgroundTasks` becomes `boolean`; explicit `false` is the opt-out — same contract as the listing family). CC hard-codes this behavior; the opt-in default left every non-shell host with a window after a compaction where the model had no context evidence of an in-flight task — duplicate spawns and premature turn ends. Explicit `true`/`false` keep their exact meaning; only the absent case flips. The zero-config fast path (no attachment state at all) now applies only to runs that explicitly opt out — the residual cost on default runs is one cadence-clock pass per message (reducers stay type-gated no-ops). **Consumer flips**: a probe pinning "no `background_tasks` frame without opt-in" reds; the frame itself is byte-unchanged.
+
+### Added
+
+- **`compaction cannot help` — honest disclosure for an oversized fixed prefix.** When the fixed per-request prefix (system prompt + tool schemas) alone meets/exceeds the compaction trigger threshold, the run emits one `onError` frame (`phase:"config"`) naming the numbers, at trigger-geometry derivation time — compaction only shrinks conversation history, so such a run re-triggers or overflows no matter how well summaries land. One frame per run; geometry itself unchanged.
+
+- **`compaction.staleToolResultOffload` — opt-in stale tool-result offload (request-projection clear).** In the outgoing request, same-tool results older than the most recent `keepRecentPerTool` (default 3) are replaced by a short pointer (persisted under the design/30 tool-result store, readable back via `read_tool_result`) once the swap saves ≥ `minSavingsChars` (default 2000). Refs are content-digested (`<toolCallId>_s<sha256-128bit>`), so recurring tool-call ids — which carry no cross-turn uniqueness contract under BYOM — cannot make one pointer resolve to another result's content (collision-resistant at 128 bits; tool results are untrusted text, so the digest width is chosen adversarially, not for accidental collisions). Replacement decisions are deterministic and one-way (an already-replaced result renders the same pointer bytes on every later request — no flip-flop churn); the verbatim→pointer transition itself is a bounded once-per-result cache break, amortized by the `minSavingsChars` floor. The session transcript is never rewritten. Absent (default) = requests byte-identical to before; knob set while the offload store is disabled = one `config` onError and the knob stays inert.
+
+- **A PARKED child joins the post-compact restatement.** The snapshot filter (pending/running) gains `parked`, rendered as `parked awaiting an out-of-band approval — do NOT re-issue the gated call` — a child waiting at an approval gate is exactly the task a post-compact model must not re-issue.
+
+- **The walltime axis feeds the limit-approach frames.** A caller-armed hard deadline (`limits.maxWalltimeMs`) now contributes its fill ratio to the design/164 converge/deliver advisories alongside tokens/cost/turns — previously the deadline was the only armed ceiling that never warned, so the model learned it was out of time by being cut. Same thresholds (default 80%/95%), same caller-armed rule, same per-slice clock the enforcement reads; frames name the axis (`walltime budget`). Consumer note: a probe pinning "no `limit_approach` steering on a walltime-only run" reds.
+
+### Fixed
+
+- **The summarization instruction carries a fabricated-user-turn guard** (both prompt variants and the fork-form instruction): only real user-role messages count as user messages — a `"user: ..."`/`"Human: ..."` line quoted inside assistant output is the assistant's own text, never attribute it to the user.
+
+- **`summarize` role doc corrected**: the main model is the correct default baseline (fork form amortizes the prefix via prompt cache); a separate cheap model is an explicit quality-for-price tradeoff, not the recommended posture.
+
+- **The exec-gate's buffered leg keeps ran-then-cut partial output.** A timed-out/aborted setup step on a non-streaming env reported empty stdout/stderr even though the `ExecutionError` carried the captured partials — the streaming leg already kept its chunks. Partials now ride the step result, clamped at `maxOutputBytes`.
+
+## 5.11.0 — 2026-08-04
+
+### BREAKING
+
+- **The restart-loop suspend cap counts CONSECUTIVE NO-PROGRESS suspends, not total approvals.** The cap's stated purpose is catching a restart-prone model re-issuing the same gated call forever — yet it counted distinct approved-and-executed gates identically, so under a doctrine that asks per call (`shellGate:"classify"` + out-of-root reads) a fully cooperating approver was killed on the 6th legitimate Yes (`suspend.loop`, default `maxSuspends: 5`). The chain base now resets the moment the resume leg starts EXECUTING the approved pending call (an execution that then errors still consumed the approval — it reset the chain); a park whose approved call never ran keeps accumulating. **Consumer flips**: checkpoint `suspendCount` restarts at 1 after each executed approval — probes pinning a monotonically increasing `suspendCount` across approve-execute cycles red; `maxSuspends` now bounds no-progress chains, never the total number of approvals a run may receive.
+- **`SubagentErrorKind` closed set gains a sixth member: `"governance"`.** A FAILED child whose `errorCode` carries the `usage.*` prefix (deployment usage window refused/exhausted) now classifies as `governance` with `retryable: false` — it is DEFERRED-retryable: re-issuing NOW gets the same refusal, but the refusal lifts at the card's `retryAfterMs`. Previously these folded into `logic` ("re-delegating unchanged won't help"), which told a scheduler to abandon a subtask that merely needed to wait. The transient retry set (`rate_limit`/`overloaded`/`timeout`/`network` → `retryable: true`) is untouched. **Consumer flips**: switches over the closed five-member kind set add a `governance` arm; the completed agent card now pairs `error_kind: "governance"` with `retryAfterMs` on window-exhausted children.
+
+- **Deferred-tool activation no longer rewrites the provider tools block — `toolMaterializeStrategy` defaults to `"static"`.** Tools serialize FIRST in the provider prompt-cache hierarchy, so the old activation swap (placeholder → full schema via setTools) invalidated the entire conversation cache — 29% of benchmarked trials paid an average ~31k tokens per break. Under the new default the placeholder bytes persist for the whole run; the full schema reaches the model through the ToolSearch result text (existing carrier) and engine-side validation against the REAL schema is unchanged. Ruled GO by a live A/B on the weakest BYOM model (15/15 argument instances correct, three scenario classes incl. nested/optional params). `"swap"` is the explicit opt-back (spec or `SEMA_TOOL_MATERIALIZE_STRATEGY`, invalid env value refused loudly as `config.tool_materialize_invalid`). **Consumer flips**: probes pinning the post-activation full schema in the tools block red — the activation announcement frames and genuine roster changes (MCP refresh) are unchanged.
+
+### Added
+
+- **A shell-gated ask persists the live shellGate doctrine on its risk descriptor.** Field forensics could not answer "was `classify` or `always` live when this gate fired" from any persisted artifact. The mint now stamps `RiskDescriptor.shellGateDoctrine` (`"classify" | "always"`, present only on shell-gated asks — `"off"` never mints) so the checkpoint row self-reports its provenance. Additive optional field.
+- **`TaskSpec.additionalReadDirectories` — a read-only fence widening.** Extra directories the READ faces admit and nothing else: the `shellGate:"classify"` read boundary (a provably read-only command like `head <dir>/settings.json` auto-allows instead of consulting the approver on every call — the interactive kill shape this exists for), plus read_file/grep/glob/repo_map and `bash_readonly` containment. The write faces (edit_file/write_file/notebook_edit) refuse these directories exactly as before — a read grant never silently becomes a write grant (`additionalDirectories` remains the read+write widening). Same canonicalization/fail-closed-skip rules as `additionalDirectories` (the skip trace gains an optional `field` discriminator); announced in `# Environment` as `Additional read-only directories:`; inherited down the delegation tree on the same seat as `additionalDirectories`. Additive — absent ⇒ byte-identical behavior.
+
+### Fixed
+
+- **WebFetch stops laundering emptiness into authority (grounding contract).** A shell page (tiny extracted text, or near-zero text ratio) now gets a TRUSTED grounding verdict outside the untrusted fence, the full extracted text appended for verification, and additive `details.grounding{level,textChars,bytes,textRatio}`; an incomplete body is called a retrieved prefix. The summarizer input budget derives from the summary model's window (flat 100k retired; trimmed input disclosed structurally and in the rendered head; NaN model metadata refused loudly). Recovery prose names Bash/curl only when reachable in THIS run. The summary prompt gains a grounding clause (report absence rather than infer; a filename is only evidence about naming) ahead of the byte-fixed CC guidelines tail.
+- **A truncated-tool-arguments disclosure names the request output cap when one was armed** (`request output cap in effect: N tokens`) on both brain lanes — a cut mid-arguments at the cap read as a generic provider error with no budget clue.
+- **agentStream's birth window is steerable**: an immediate `steer()` after `agentStream()` waits (bounded) for the loop's first prompt and lands on turn 1; a finished run keeps the honest refusal.
+- **A long-window zero-byte Bash timeout names its two honest readings** (stalled before producing output / holding it in a block buffer); short windows and abort arms stay bare.
+- **The background faces carry the governance wait hint.** A `usage.window_exhausted` background child's settle dropped `retryAfterMs` — every bg face (poll text, poll details, notification-adjacent durable row) said `retryable:false` with no way to know when the refusal lifts, while the sync report card carried the hint. The classification family gains its fourth seat end-to-end: settle mint → registry row → durable archival row → poll `details.retryAfterMs` → the poll text clause (`(error_kind: governance, retryable: false, retry_after_ms: N)`); a revive clears it with its three siblings. Additive on every face.
+- **The `suspend.loop` terminal diagnoses the every-approval-was-Yes kill.** When every recorded gate decision on the run was ALLOW, the message now names the shape (a gate that keeps asking × an approver that keeps approving consumed the suspend allowance on legitimate work) and the remedies (a live `onAsk` parks nothing; keep benign commands inside the read boundary; raise `maxSuspends` for approval-heavy tasks) instead of reporting a bare restart-loop mystery.
+
 ## 5.10.0 — 2026-08-04
 
 ### Added

package/dist/agents/subagent.d.ts

@@ -34,7 +34,7 @@ export interface SubagentWorktreeIsolation {
 }
 export declare function createSubagentWorktreeHelper(baseEnv: ExecutionEnv, repoRoot: string): SubagentWorktreeIsolation;
 export declare const REPORT_FIELD_MAX = 300;
-export type SubagentErrorKind = "rate_limit" | "overloaded" | "timeout" | "network" | "logic";
+export type SubagentErrorKind = "rate_limit" | "overloaded" | "timeout" | "network" | "logic" | "governance";
 export declare function classifySubagentError(child: {
     status: string;
     errorCode?: string;

package/dist/agents/subagent.js

@@ -229,8 +229,10 @@ export function classifySubagentError(child) {
                 ? "timeout"
                 : code === "network" || code === "server"
                     ? "network"
-                    : "logic";
-    return { errorKind, retryable: errorKind !== "logic" };
+                    : code !== undefined && code.startsWith("usage.")
+                        ? "governance"
+                        : "logic";
+    return { errorKind, retryable: errorKind !== "logic" && errorKind !== "governance" };
 }
 export function completedAgentCard(child, extras) {
     return {
@@ -1502,6 +1504,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                 ...(ctx.alwaysLoadTools !== undefined ? { alwaysLoadTools: [...ctx.alwaysLoadTools] } : {}),
                 ...(ctx.promptProfile !== undefined ? { promptProfile: ctx.promptProfile } : {}),
                 ...(ctx.additionalDirectories !== undefined ? { additionalDirectories: [...ctx.additionalDirectories] } : {}),
+                ...(ctx.additionalReadDirectories !== undefined ? { additionalReadDirectories: [...ctx.additionalReadDirectories] } : {}),
                 ...(ctx.envFacts !== undefined ? { envFacts: { ...ctx.envFacts } } : {}),
                 ...(ctx.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: ctx.getApiKeyAndHeaders } : {}),
                 enableBlockedReport: true,
@@ -2567,6 +2570,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : unparkedPauseReason ?? child.errorMessage ?? String(child.status) } : {}),
                         ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
                         ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
+                        ...(failedBg && child.retryAfterMs !== undefined ? { retryAfterMs: child.retryAfterMs } : {}),
                     }) ??
                         (abort.signal.aborted ? "killed" : ok ? "completed" : "failed");
                     if (!bgRetain && reviveRow === undefined && !(await bgRowConfirmed())) {

package/dist/brain/anthropic.js

@@ -558,7 +558,7 @@ export function createAnthropicBrain(config = {}) {
                         const noUsableContent = toolCalls.length === 0 && !anyText;
                         const toolErrorParts = [];
                         if (malformed.length > 0) {
-                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, stop_reason="${stopReason ?? "?"}"): ${malformed.join("; ")}`);
+                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, stop_reason="${stopReason ?? "?"}"${sentMaxTokens !== undefined ? `; request output cap in effect: ${sentMaxTokens} tokens — a cut mid-arguments commonly means the cap was hit` : ""}): ${malformed.join("; ")}`);
                         }
                         if (unnamed.length > 0) {
                             toolErrorParts.push(`tool call(s) arrived with no tool name and cannot be executed (stop_reason="${stopReason ?? "?"}"): ${unnamed.join("; ")}`);

package/dist/brain/openai.js

@@ -526,7 +526,7 @@ export function createOpenAIBrain(config = {}) {
                         }
                         const toolErrorParts = [];
                         if (malformed.length > 0) {
-                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"): ${malformed.join("; ")}`);
+                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"${sentMaxTokens !== undefined ? `; request output cap in effect: ${sentMaxTokens} tokens — a cut mid-arguments commonly means the cap was hit` : ""}): ${malformed.join("; ")}`);
                         }
                         if (unnamed.length > 0) {
                             toolErrorParts.push(`tool call(s) arrived with no tool name and cannot be executed (finish_reason="${finishReason ?? "?"}"): ${unnamed.join("; ")}`);

package/dist/core/auto-compaction.d.ts

@@ -1,5 +1,5 @@
 import { type AgentMessage, type CompactionSettings, type Session, type ThinkingLevel } from "../internal/harness.js";
-import type { Model } from "../internal/llm.js";
+import type { Message, Model, Tool } from "../internal/llm.js";
 import type { Hooks } from "./hooks.js";
 import type { TraceEvent } from "./trace.js";
 import type { Brain } from "./types.js";
@@ -20,6 +20,16 @@ export interface CompactionWindowSafetyInfo {
 }
 export declare const STALE_ANCHOR_STRUCTURAL_MARGIN = 2;
 export declare function sanitizeCompactionSettings(settings: CompactionSettings, contextWindow: number | undefined): CompactionSettings;
+export interface CompactionForkContext {
+    systemPrompt?: string;
+    systemBlocks?: Array<{
+        text: string;
+        cacheControlBoundary: boolean;
+    }>;
+    messages: Message[];
+    tools?: Tool[];
+    modelId?: string;
+}
 export interface MaybeCompactOptions {
     onNotifyError?: (failure: import("./safe-notify.js").SafeNotifyFailure) => void;
     session: Session;
@@ -34,6 +44,7 @@ export interface MaybeCompactOptions {
     };
     model: Model;
     compactionModel?: Model;
+    forkContext?: () => CompactionForkContext | undefined;
     brain: Brain;
     getApiKeyAndHeaders?: (model: Model) => Promise<{
         apiKey: string;

package/dist/core/auto-compaction.js

@@ -234,12 +234,14 @@ export async function maybeCompact(opts) {
         const auth = await opts.getApiKeyAndHeaders?.(summaryModel);
         const summarySignal = opts.signal;
         const runtime = brainToRuntime(opts.brain);
+        const forkCandidate = opts.compactionModel === undefined ? opts.forkContext?.() : undefined;
+        const forkContext = forkCandidate !== undefined && (forkCandidate.modelId === undefined || forkCandidate.modelId === summaryModel.id) ? forkCandidate : undefined;
         let res;
         summaryStartAt = Date.now();
         try {
             res = await compact(prep.value, summaryModel, auth?.apiKey, auth?.headers, effectiveInstructions, summarySignal, opts.thinking, undefined, runtime, undefined, opts.onInputTruncated, () => {
                 ptlRetries += 1;
-            });
+            }, forkContext);
         }
         finally {
             summaryEndAt = Date.now();

package/dist/core/background-agent-store.d.ts

@@ -40,13 +40,14 @@ export interface BackgroundAgentRecord {
     errorCode?: string;
     errorRetryable?: boolean;
     errorKind?: string;
+    errorRetryAfterMs?: number;
     resultIsPartial?: boolean;
     recentSteps?: SubagentStep[];
     editedFiles?: SubagentEditedFile[];
     usage?: BackgroundAgentUsage;
     rev: number;
 }
-export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
+export declare const REVIVED_ROW_CLEARED_FIELDS: readonly ["settledAt", "stoppedBy", "completionId", "finalOutput", "finalOutputFull", "error", "errorCode", "errorRetryable", "errorKind", "errorRetryAfterMs", "resultIsPartial", "summary", "recentSteps", "editedFiles", "usage"];
 export declare function clearRevivedRowTerminalPayload(record: BackgroundAgentRecord): void;
 export interface BackgroundAgentRowSummary {
     handle: string;

package/dist/core/background-agent-store.js

@@ -9,6 +9,7 @@ export const REVIVED_ROW_CLEARED_FIELDS = [
     "errorCode",
     "errorRetryable",
     "errorKind",
+    "errorRetryAfterMs",
     "resultIsPartial",
     "summary",
     "recentSteps",

package/dist/core/checkpoint-store.d.ts

@@ -24,6 +24,7 @@ export interface RiskDescriptor {
         shell?: boolean;
     };
     toolName: string;
+    shellGateDoctrine?: "classify" | "always";
     summary?: string;
     touchedPaths?: string[];
 }
@@ -39,6 +40,7 @@ export declare function buildRiskDescriptor(input: {
     args: unknown;
     safety?: SafetyAxis;
     shellGated?: boolean;
+    shellGateDoctrine?: "classify" | "always";
 }): RiskDescriptor;
 export type CheckpointGate = {
     kind: "human";

package/dist/core/checkpoint-store.js

@@ -115,6 +115,7 @@ export function buildRiskDescriptor(input) {
             severity: riskSeverity(axes),
             axes,
             toolName,
+            ...(input.shellGated && input.shellGateDoctrine !== undefined ? { shellGateDoctrine: input.shellGateDoctrine } : {}),
             ...(summary !== undefined ? { summary } : {}),
             ...(touchedPaths !== undefined ? { touchedPaths } : {}),
         };

package/dist/core/exec-gate.js

@@ -65,7 +65,18 @@ async function runBufferedStep(env, step, options, maxOutputBytes) {
         abortSignal: options.signal,
     });
     if (!res.ok) {
-        return { label, command: step.command, exitCode: null, stdout: "", stderr: "", ok: false, errorCode: res.error.code };
+        const po = clampBytes(res.error.partialStdout ?? "", maxOutputBytes);
+        const pe = clampBytes(res.error.partialStderr ?? "", maxOutputBytes);
+        return {
+            label,
+            command: step.command,
+            exitCode: null,
+            stdout: po.text,
+            stderr: pe.text,
+            ok: false,
+            errorCode: res.error.code,
+            truncated: po.truncated || pe.truncated,
+        };
     }
     const so = clampBytes(res.value.stdout, maxOutputBytes);
     const se = clampBytes(res.value.stderr, maxOutputBytes);

package/dist/core/runner/assemble-result.js

@@ -86,6 +86,15 @@ export function assembleResult(spec, sessionId, final, stats, flags) {
         status = "failed";
         errorCode = "suspend.loop";
         errorMessage = "task suspended too many times (resume/restart loop) — exceeded the suspend limit";
+        const gates = stats.humanReview?.gates ?? [];
+        if (gates.length > 0 && gates.every((g) => g.decision === "allow")) {
+            errorMessage +=
+                `. Diagnosis: all ${gates.length} recorded gate decision(s) on this run were ALLOW — a gate that keeps ` +
+                    `asking combined with an approver that keeps approving consumes the suspend allowance on legitimate ` +
+                    `work. Remedies: answer asks at a LIVE onAsk (a synchronous allow parks nothing and consumes no ` +
+                    `suspend), keep provably-benign commands inside the read boundary so the classifier auto-allows them, ` +
+                    `or raise maxSuspends for genuinely approval-heavy tasks.`;
+        }
     }
     else if (flags.threw) {
         status = "failed";

package/dist/core/runner/compaction-call-options.d.ts

@@ -1,7 +1,19 @@
 import { type TracerHook } from "../trace.js";
 import type { MaybeCompactOptions } from "../auto-compaction.js";
-import type { TaskSpec } from "../types.js";
+import type { StaleToolResultOffloadOptions, TaskSpec } from "../types.js";
+import type { Context } from "../../internal/llm.js";
+import { type ToolResultStore } from "../tool-result-store.js";
 import type { Prepared } from "./prepare-task.js";
 export declare function buildWorkingFileAttachments(spec: TaskSpec, prepared: Prepared): MaybeCompactOptions["workingFileAttachments"];
+export declare function forkContextOption(prepared: Prepared, disable: boolean): Pick<MaybeCompactOptions, "forkContext">;
 export declare function centerAdoptionOption(prepared: Prepared): Partial<Pick<MaybeCompactOptions, "centerAdoption">>;
+export declare const STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL = 3;
+export declare const STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS = 2000;
+export interface ResolvedStaleToolResultOffload {
+    keepRecentPerTool: number;
+    minSavingsChars: number;
+}
+export declare function resolveStaleToolResultOffload(knob: StaleToolResultOffloadOptions | undefined): ResolvedStaleToolResultOffload | undefined;
+export declare function buildStaleOffloadPointer(toolName: string, ref: string, chars: number): string;
+export declare function projectStaleToolResults(context: Context, cfg: ResolvedStaleToolResultOffload, store: ToolResultStore, sessionId: string, writtenRefs: Set<string>): Promise<Context>;
 export declare function emitInputTruncated(tracer: TracerHook | undefined, taskId: string): NonNullable<MaybeCompactOptions["onInputTruncated"]>;

package/dist/core/runner/compaction-call-options.js

@@ -1,4 +1,6 @@
+import { createHash } from "node:crypto";
 import { emitTrace } from "../trace.js";
+import { buildToolResultRef, OFFLOAD_TOOL_NAME, PERSISTED_OUTPUT_PREFIX } from "../tool-result-store.js";
 export function buildWorkingFileAttachments(spec, prepared) {
     if (spec.compaction?.attachWorkingFiles === false || !prepared.readTaskFile)
         return undefined;
@@ -13,10 +15,93 @@ export function buildWorkingFileAttachments(spec, prepared) {
         ...(typeof spec.compaction?.attachWorkingFiles === "object" ? spec.compaction.attachWorkingFiles : undefined),
     };
 }
+export function forkContextOption(prepared, disable) {
+    return disable ? {} : { forkContext: prepared.lastBrainContext };
+}
 export function centerAdoptionOption(prepared) {
     const ca = prepared.centerCompactionCandidate?.();
     return ca !== undefined ? { centerAdoption: ca } : {};
 }
+export const STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL = 3;
+export const STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS = 2000;
+export function resolveStaleToolResultOffload(knob) {
+    if (knob === undefined)
+        return undefined;
+    const check = (name, v, fallback) => {
+        if (v === undefined)
+            return fallback;
+        if (!Number.isInteger(v) || v < 0) {
+            const e = new Error(`compaction.staleToolResultOffload.${name} must be a non-negative integer, got ${String(v)}`);
+            e.code = "config.stale_tool_result_offload_invalid";
+            throw e;
+        }
+        return v;
+    };
+    return {
+        keepRecentPerTool: check("keepRecentPerTool", knob.keepRecentPerTool, STALE_OFFLOAD_DEFAULT_KEEP_RECENT_PER_TOOL),
+        minSavingsChars: check("minSavingsChars", knob.minSavingsChars, STALE_OFFLOAD_DEFAULT_MIN_SAVINGS_CHARS),
+    };
+}
+export function buildStaleOffloadPointer(toolName, ref, chars) {
+    return (`[Stale tool result offloaded to save context: ${chars} chars from an earlier "${toolName}" call ` +
+        `saved to persisted output ref "${ref}". Newer results of this tool are still shown in full below; ` +
+        `use the ${OFFLOAD_TOOL_NAME} tool with this ref if you need the offloaded content again.]`);
+}
+function toolResultText(m) {
+    return m.content
+        .filter((b) => b.type === "text")
+        .map((b) => b.text)
+        .join("\n");
+}
+export async function projectStaleToolResults(context, cfg, store, sessionId, writtenRefs) {
+    const byTool = new Map();
+    context.messages.forEach((m, i) => {
+        if (m.role !== "toolResult" || m.isError)
+            return;
+        const list = byTool.get(m.toolName);
+        const row = { idx: i, msg: m };
+        if (list === undefined)
+            byTool.set(m.toolName, [row]);
+        else
+            list.push(row);
+    });
+    const replacements = new Map();
+    for (const [toolName, rows] of byTool) {
+        const staleCount = rows.length - cfg.keepRecentPerTool;
+        for (let k = 0; k < staleCount; k++) {
+            const { idx, msg } = rows[k];
+            const text = toolResultText(msg);
+            if (text.startsWith(PERSISTED_OUTPUT_PREFIX))
+                continue;
+            const ref = buildToolResultRef(sessionId, `${msg.toolCallId}_s${createHash("sha256").update(text, "utf8").digest("hex").slice(0, 32)}`);
+            const pointer = buildStaleOffloadPointer(toolName, ref, text.length);
+            if (text.length - pointer.length < cfg.minSavingsChars)
+                continue;
+            if (!writtenRefs.has(ref)) {
+                try {
+                    await store.put(ref, text);
+                    writtenRefs.add(ref);
+                }
+                catch {
+                    continue;
+                }
+            }
+            replacements.set(idx, { msg, pointer });
+        }
+    }
+    if (replacements.size === 0)
+        return context;
+    return {
+        ...context,
+        messages: context.messages.map((m, i) => {
+            const hit = replacements.get(i);
+            if (hit === undefined)
+                return m;
+            const rest = hit.msg.content.filter((b) => b.type !== "text");
+            return { ...hit.msg, content: [{ type: "text", text: hit.pointer }, ...rest] };
+        }),
+    };
+}
 export function emitInputTruncated(tracer, taskId) {
     return (info) => emitTrace(tracer, () => ({
         kind: "compaction.input_truncated",

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

@@ -1,5 +1,6 @@
 import { AgentHarness, type ThinkingLevel } from "../../internal/harness.js";
 import type { Model } from "../../internal/llm.js";
+import { type CompactionForkContext } from "../auto-compaction.js";
 import { type MaterializedMcp } from "../mcp.js";
 import { type MaterializedA2a } from "../a2a.js";
 import type { HarvestReport, MemorySessionHandle } from "../memory-engine/types.js";
@@ -121,6 +122,7 @@ export interface Prepared {
     } | undefined;
     activeTools: Set<string>;
     deferredToolNames?: ReadonlySet<string>;
+    toolMaterializeStatic: boolean;
     memoryEngineSession?: {
         engine: MemoryEngine;
         handle: MemorySessionHandle;
@@ -134,6 +136,9 @@ export interface Prepared {
         scope?: string;
         restoreMode?: "snapshot" | "park_only";
     };
+    suspendProgressRef: {
+        executedApproved: boolean;
+    };
     reviewRef: {
         token?: CheckpointToken;
         gate?: CheckpointGate;
@@ -195,6 +200,7 @@ export interface Prepared {
     toolEffects: Map<string, ToolEffect>;
     wakeRecovered: RecoveredOrphan[];
     promptOverheadTokens: number;
+    lastBrainContext: () => CompactionForkContext | undefined;
     readTaskFile?: (path: string) => Promise<string | null>;
     recentlyReadFiles?: () => string[];
     normalizeAttachmentPath?: (raw: string) => Promise<string>;