@sema-agent/core 2.3.0 → 2.5.0

package/dist/brain/stream-engine.js

@@ -1,5 +1,5 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
-import { BrainError, classifyHttp } from "./errors.js";
+import { BrainError, classifyHttp, describeNetworkError } from "./errors.js";
 import { retryBackoffMs } from "./retry.js";
 import { emitBrainStatus, emitBrainTelemetry } from "./status-sink.js";
 import { createConnectController } from "./timeout.js";
@@ -139,7 +139,7 @@ export function runStreamingBrain(args) {
                     continue;
                 }
                 if (netErr)
-                    throw new BrainError("network", netErr instanceof Error ? netErr.message : String(netErr));
+                    throw new BrainError("network", describeNetworkError(netErr));
                 const detail = r ? await r.text().catch(() => "") : "";
                 const status = r?.status ?? 0;
                 throw new BrainError(classifyHttp(status), `${httpLabel} HTTP ${status || "ERR"}: ${detail.slice(0, 500)}`, status);
@@ -250,7 +250,7 @@ export function runStreamingBrain(args) {
                         throw e;
                     failure = {
                         kind: "connection",
-                        err: new BrainError("network", `mid-stream read failed: ${e instanceof Error ? e.message : String(e)}`),
+                        err: new BrainError("network", `mid-stream read failed: ${describeNetworkError(e)}`),
                     };
                     break readLoop;
                 }

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

@@ -96,11 +96,13 @@ export interface MaybeCompactOptions {
         droppedChars: number;
         keptChars: number;
     }) => void;
+    activeTools?: ReadonlyArray<string>;
 }
 export declare function maybeCompact(opts: MaybeCompactOptions): Promise<{
     compacted: boolean;
     blocked?: boolean;
     disabled?: boolean;
+    noop?: true;
     tokensBefore?: number;
     freedTokens?: number;
     triggerTokens?: number;

package/dist/core/auto-compaction.js

@@ -86,7 +86,7 @@ export async function maybeCompact(opts) {
         throw prep.error;
     }
     if (!prep.value) {
-        return { contextUsage, compacted: false };
+        return { contextUsage, compacted: false, noop: true };
     }
     const trigger = opts.trigger ?? "auto";
     let hookInstructions;
@@ -454,6 +454,7 @@ export async function maybeCompact(opts) {
         ...(details ?? {}),
         promptEpoch: restatedEpoch,
         ...(restatedListings !== undefined ? { announcedListings: restatedListings } : {}),
+        ...(opts.activeTools !== undefined && opts.activeTools.length > 0 ? { activeTools: [...opts.activeTools] } : {}),
     }, false);
     try {
         opts.onApplied?.(attachedComplete, excludedReadStatePreserveKeys);

package/dist/core/context-edit.js

@@ -1,7 +1,8 @@
 import { DEFAULT_CHARS_PER_TOKEN, estimateContextTokens, estimateTokens } from "../internal/harness.js";
 import { isToolResult } from "./message-utils.js";
+import { offloadPagebackHint } from "./tool-result-store.js";
 const CLEARED_MARKER = "[tool result cleared to save context]";
-const refNote = (ref) => `full text persisted; call ReadToolResult with ref "${ref}" to read it back`;
+const refNote = (ref) => offloadPagebackHint(ref, "cleared");
 const mediaNote = (blocks) => {
     const byType = new Map();
     for (const b of blocks) {

package/dist/core/mcp.js

@@ -1039,13 +1039,16 @@ function intakeListedTools(listed, spec, client, health, imageResizer) {
         if (axis)
             serverAxes.push(axis);
         const writeEffect = (axis?.effect ?? "write") === "write";
-        const mcpMaxResultSizeChars = resolveMcpDeclaredResultSize(t._meta);
+        const mcpToolMeta = t._meta;
+        const mcpMaxResultSizeChars = resolveMcpDeclaredResultSize(mcpToolMeta);
+        const mcpAlwaysLoad = mcpToolMeta?.["anthropic/alwaysLoad"] === true;
         serverTools.push({
             name: namespacedName,
             description: effectiveDescription ?? `MCP tool ${remoteName} from ${spec.name}`,
             label: `${spec.name}:${remoteName}`,
             parameters: (effectiveInputSchema ?? { type: "object" }),
             ...(mcpMaxResultSizeChars !== undefined ? { mcpMaxResultSizeChars } : {}),
+            ...(mcpAlwaysLoad ? { mcpAlwaysLoad: true } : {}),
             execute: async (_toolCallId, params, signal) => {
                 const what = `The call to tool ${inlineUntrusted(remoteName)}`;
                 if (health.dead)

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

@@ -327,6 +327,11 @@ export interface RunInternals {
     requestedCwd?: string;
     onSubagentSpawn?: (handle: import("../../agents/subagent.js").SubagentSteerHandle) => void;
     onActivity?: (activity: ToolActivity) => void;
+    onWorkspaceResolved?: (workspace: ResolvedWorkspace) => void;
+}
+export interface ResolvedWorkspace {
+    cwd: string;
+    isolated: boolean;
 }
 export declare function batchContextAt(messages: AgentMessage[], currentId: string): {
     batchToolCallIds: string[];

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

@@ -1,7 +1,7 @@
 import { createHash, randomBytes } from "node:crypto";
 import { realpathSync } from "node:fs";
 import { resolve as resolveFsPath } from "node:path";
-import { AgentHarness, DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, summaryOutputBudgetTokens } from "../../internal/harness.js";
+import { AgentHarness, DEFAULT_CHARS_PER_TOKEN, DEFAULT_CLAMP_TOLERANCE, DEFAULT_COMPACTION_SETTINGS, estimateContextTokens, readCompactionActiveTools, summaryOutputBudgetTokens } from "../../internal/harness.js";
 const PROMPT_HASH_SALT = randomBytes(16);
 import { sanitizeCompactionSettings } from "../auto-compaction.js";
 import { createAutoModeDecider } from "../auto-mode.js";
@@ -177,6 +177,7 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const toolFaceSnapshot = {
         exclude: spec.excludeTools ? Object.freeze([...spec.excludeTools]) : undefined,
         defer: spec.deferTools ? Object.freeze([...spec.deferTools]) : undefined,
+        alwaysLoad: spec.alwaysLoadTools ? Object.freeze([...spec.alwaysLoadTools]) : undefined,
     };
     const promptProfile = resolveModelPromptTraits({ id: "" }, spec, internals).promptProfile;
     if (spec.resumeAt !== undefined) {
@@ -435,10 +436,11 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
     const offloadStore = rawOffloadStore instanceof RunnerSharedToolResultStore
         ? new ScopedToolResultStore(rawOffloadStore, taskScope)
         : rawOffloadStore;
+    const offloadReachableToolsRef = {};
     const maybeOffload = (tool, perTool) => {
         if (!offloadStore || perTool?.offload === false)
             return tool;
-        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId);
+        return withToolResultOffload(tool, offloadStore, perTool?.offloadThresholdChars ?? offloadThreshold, sessionId, () => offloadReachableToolsRef.current?.());
     };
     const firstPartyOffload = (tool) => {
         const policy = firstPartyOffloadPolicy(tool.name);
@@ -607,6 +609,13 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 }
             }
         }
+        if (internals?.onWorkspaceResolved !== undefined) {
+            try {
+                internals.onWorkspaceResolved({ cwd: taskRootPath, isolated: internals.isolation === "worktree" });
+            }
+            catch {
+            }
+        }
         let rewindTarget = spec.resumeAt !== undefined ? (spec.rewindFiles ? spec.resumeAt : undefined) : spec.rewindFilesTo;
         const rewindBefore = rewindTarget !== undefined && spec.resumeAt !== undefined && spec.resumeAtMode === "before";
         if (rewindTarget !== undefined && deps.fileSnapshotStore && handsEnabled) {
@@ -1123,6 +1132,14 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                         phase: "config",
                         sessionId,
                     });
+                    emitTrace(deps.tracer, () => ({
+                        kind: "config.additional_directory_skipped",
+                        version: 1,
+                        taskId: hostTaskId,
+                        entry: dir,
+                        reason: `${c.error.code}: ${c.error.message}`,
+                        ts: Date.now(),
+                    }));
                 }
             }
             if (spec.envFacts?.scratchpadDir) {
@@ -1255,6 +1272,8 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                     ...(internals?.parentNotify !== undefined ? { uplink: internals.parentNotify } : {}),
                     ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
                     ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
+                    ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
+                    ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),
                     ...(deps.rosterStore !== undefined ? { roster: deps.rosterStore } : {}),
                     ...(deps.onBackgroundChildEvent ? { onBackgroundChildEvent: deps.onBackgroundChildEvent } : {}),
                     ...(deps.backgroundAgentStore !== undefined ? { agentStore: deps.backgroundAgentStore } : {}),
@@ -1770,6 +1789,10 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
             deferMode: deps.deferMode,
             model,
             deferNames: (toolFaceSnapshot.defer ?? []).filter((n) => tools.some((t) => t.name === n)),
+            alwaysLoadNames: [
+                ...(toolFaceSnapshot.alwaysLoad ?? []),
+                ...mcp.tools.filter((t) => t.mcpAlwaysLoad === true).map((t) => t.name),
+            ],
         });
         for (const n of [...deferred]) {
             if (!tools.some((t) => t.name === n))
@@ -1809,11 +1832,27 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 if (deferred.has(n))
                     activeTools.add(n);
             }
+            for (const entry of await session.getBranch()) {
+                if (entry.type !== "compaction" || entry.fromHook === true)
+                    continue;
+                for (const n of readCompactionActiveTools(entry.details)) {
+                    if (deferred.has(n))
+                        activeTools.add(n);
+                }
+            }
             if (resume) {
                 for (const n of resume.seed.activeTools)
                     if (deferred.has(n))
                         activeTools.add(n);
             }
+            offloadReachableToolsRef.current = () => {
+                const s = new Set(tools.map((t) => t.name));
+                for (const n of deferred)
+                    if (!activeTools.has(n))
+                        s.delete(n);
+                s.add(TOOL_SEARCH_NAME);
+                return s;
+            };
             let toolSearch;
             const buildToolList = (active) => {
                 const list = tools.map((t) => (deferred.has(t.name) && !active.has(t.name) ? placeholders.get(t.name) : t));

package/dist/core/runner/runtask.js

@@ -538,6 +538,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
             prepared.reviewRef.token !== undefined) {
             if (forceManual) {
                 emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.mooted", version: 1, taskId: rs.telemetry.taskId, reason: "task_ending", ts: Date.now() }));
+                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: "manual", reason: "task_ending", ...ident() });
                 drainManualCompact("mooted");
             }
             return undefined;
@@ -552,6 +553,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     reason: "compaction circuit breaker open (3 consecutive failures this task) — manual request drained without an attempt",
                     ts: Date.now(),
                 }));
+                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "manual", reason: "compaction circuit breaker open (3 consecutive failures this task) — manual request drained without an attempt", ...ident() });
                 drainManualCompact("failed");
             }
             return undefined;
@@ -590,6 +592,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
         if (trimPressureArmed)
             prepared.trimPressureRef.droppedMessages = false;
         const trimPressure = trimPressureArmed && !rs.counters.trimForceBackoff;
+        const passTrigger = trimPressure ? "forced" : forceManual ? "manual" : "auto";
         let manualOutcome = "failed";
         if (rs.counters.finalizeInjected && forceManual) {
             emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.manual_in_finalize", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
@@ -617,6 +620,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 onInputTruncated: (info) => emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.input_truncated", version: 1, taskId: rs.telemetry.taskId, label: info.label, droppedChars: info.droppedChars, keptChars: info.keptChars, ts: Date.now() })),
                 forceUnderThreshold: trimPressure,
                 overheadTokens: prepared.promptOverheadTokens,
+                ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
                 workingFileAttachments: spec.compaction?.attachWorkingFiles !== false && prepared.readTaskFile
                     ? {
                         readFile: prepared.readTaskFile,
@@ -632,7 +636,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                 ...(prepared.onCompactionApplied ? { onApplied: prepared.onCompactionApplied } : {}),
                 ...runnerHooks.seamCCompactionOptions(prepared),
                 ...windowSafetyOptions(event.model),
-                ...runnerHooks.compactionHookOptions(spec, prepared.sessionId, trimPressure ? "forced" : forceManual ? "manual" : "auto"),
+                ...runnerHooks.compactionHookOptions(spec, prepared.sessionId, passTrigger),
             });
             if (comp.blocked) {
                 emitTrace(rs.telemetry.tracer, () => ({
@@ -670,17 +674,32 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.noop", version: 1, taskId: rs.telemetry.taskId, ts: Date.now() }));
                 }
             }
+            if (!comp.compacted) {
+                const outcome = comp.blocked
+                    ? "blocked"
+                    : comp.disabled
+                        ? (forceManual || trimPressure ? "disabled" : undefined)
+                        : comp.suppressedByFloor
+                            ? "suppressed"
+                            : comp.noop || forceManual
+                                ? "noop"
+                                : undefined;
+                if (outcome !== undefined) {
+                    queue.push({ type: "compaction_outcome", outcome, trigger: passTrigger, ...ident() });
+                }
+            }
             if (comp.compacted && !forceManual) {
                 if (recordCompactionAndCheckRapidRefill(rapidRefill, stats.turns)) {
                     compactionBreaker.failures = MAX_CONSECUTIVE_COMPACTION_FAILURES;
                     runnerHooks.onError?.(new Error("compaction.rapid_refill: the context refilled within <3 turns of compaction 3 times in a row — compaction disabled for the rest of this task (thrash spiral; the transcript is dominated by incompressible content)"), { phase: "compaction", sessionId: prepared.sessionId });
+                    queue.push({ type: "compaction_outcome", outcome: "disabled", trigger: passTrigger, reason: "rapid_refill: compaction disabled for the rest of this task", ...ident() });
                 }
             }
             runnerHooks.recordCompactionReuse(prepared, comp);
             if (comp.compacted) {
                 queue.push({
                     type: "compacted",
-                    trigger: forceManual ? "manual" : "auto",
+                    trigger: passTrigger,
                     tokensBefore: comp.tokensBefore ?? 0,
                     ...(comp.postTriggerTokens !== undefined ? { tokensAfter: comp.postTriggerTokens } : {}),
                     ...(comp.triggerTokens !== undefined ? { triggerTokensBefore: comp.triggerTokens } : {}),
@@ -692,6 +711,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     ...(comp.fallbackReason !== undefined ? { fallbackReason: comp.fallbackReason } : {}),
                     ...(comp.clampedRatio !== undefined ? { clampedRatio: comp.clampedRatio } : {}),
                     ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
+                    ...ident(),
                 });
                 if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
                     const pd = comp.phaseDurations;
@@ -713,6 +733,7 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
             const manualCancelAbort = !prepared.abortController.signal.aborted && isCompactionManualCancel(err);
             if (manualCancelAbort) {
                 emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.mooted", version: 1, taskId: rs.telemetry.taskId, reason: "cancelled", ts: Date.now() }));
+                queue.push({ type: "compaction_outcome", outcome: "mooted", trigger: passTrigger, reason: "cancelled", ...ident() });
                 manualOutcome = "mooted";
             }
             else if (!prepared.abortController.signal.aborted) {
@@ -721,18 +742,20 @@ function makeTurnBoundary(prepared, stats, rs, deps) {
                     compactionBreaker.failures += 1;
                 runnerHooks.onError?.(err, { phase: "compaction", sessionId: prepared.sessionId });
                 const msg = String(err instanceof Error ? err.message : err);
+                const failReason = walltimeAbort
+                    ? "walltime soft-deadline abort (engine-initiated write-out protection; not counted toward the breaker)"
+                    : msg.length > 512
+                        ? `${msg.slice(0, 512)}…`
+                        : msg;
                 emitTrace(rs.telemetry.tracer, () => ({
                     kind: "compaction.failed",
                     version: 1,
                     taskId: rs.telemetry.taskId,
-                    trigger: trimPressure ? "forced" : forceManual ? "manual" : "auto",
-                    reason: walltimeAbort
-                        ? "walltime soft-deadline abort (engine-initiated write-out protection; not counted toward the breaker)"
-                        : msg.length > 512
-                            ? `${msg.slice(0, 512)}…`
-                            : msg,
+                    trigger: passTrigger,
+                    reason: failReason,
                     ts: Date.now(),
                 }));
+                queue.push({ type: "compaction_outcome", outcome: "failed", trigger: passTrigger, reason: failReason, ...ident() });
                 manualOutcome = "failed";
             }
             else {
@@ -2319,6 +2342,7 @@ export class Runner {
                             minTokens: 0,
                             force: true,
                             overheadTokens: prepared.promptOverheadTokens,
+                            ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
                             onInputTruncated: (info) => emitTrace(rs.telemetry.tracer, () => ({ kind: "compaction.input_truncated", version: 1, taskId: rs.telemetry.taskId, label: info.label, droppedChars: info.droppedChars, keptChars: info.keptChars, ts: Date.now() })),
                             workingFileAttachments: spec.compaction?.attachWorkingFiles !== false && prepared.readTaskFile
                                 ? {
@@ -2346,7 +2370,7 @@ export class Runner {
                             }
                             queue.push({
                                 type: "compacted",
-                                trigger: "auto",
+                                trigger: "forced",
                                 tokensBefore: comp.tokensBefore ?? 0,
                                 ...(comp.postTriggerTokens !== undefined ? { tokensAfter: comp.postTriggerTokens } : {}),
                                 ...(comp.triggerTokens !== undefined ? { triggerTokensBefore: comp.triggerTokens } : {}),
@@ -2358,6 +2382,7 @@ export class Runner {
                                 ...(comp.fallbackReason !== undefined ? { fallbackReason: comp.fallbackReason } : {}),
                                 ...(comp.clampedRatio !== undefined ? { clampedRatio: comp.clampedRatio } : {}),
                                 ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
+                                ...ident(),
                             });
                             if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
                                 const pd = comp.phaseDurations;
@@ -2372,12 +2397,15 @@ export class Runner {
                         }
                         else {
                             compactionBreaker.failures += 1;
+                            queue.push({ type: "compaction_outcome", outcome: comp.noop ? "noop" : "failed", trigger: "forced", reason: "prompt-too-long recovery pass did not land", ...ident() });
                         }
                         return comp.compacted === true;
                     }
                     catch (err) {
                         if (!isCompactionWalltimeAbort(err))
                             compactionBreaker.failures += 1;
+                        const msg = String(err instanceof Error ? err.message : err);
+                        queue.push({ type: "compaction_outcome", outcome: "failed", trigger: "forced", reason: msg.length > 512 ? `${msg.slice(0, 512)}…` : msg, ...ident() });
                         return false;
                     }
                 },
@@ -2661,6 +2689,7 @@ export class Runner {
                     ...(comp.fallbackReason !== undefined ? { fallbackReason: comp.fallbackReason } : {}),
                     ...(comp.clampedRatio !== undefined ? { clampedRatio: comp.clampedRatio } : {}),
                     ...(comp.clampReason !== undefined ? { clampReason: comp.clampReason } : {}),
+                    ...ident(),
                 });
                 if (comp.phaseDurations !== undefined && comp.durationMs !== undefined) {
                     const pd = comp.phaseDurations;
@@ -3453,6 +3482,7 @@ export class Runner {
                     customInstructions: spec.compaction?.instructions ?? DEFAULT_COMPACTION_INSTRUCTIONS,
                     minTokens: opts?.minTokens,
                     overheadTokens: prepared.promptOverheadTokens,
+                    ...(prepared.activeTools.size > 0 ? { activeTools: [...prepared.activeTools] } : {}),
                     onInputTruncated: (info) => emitTrace(spec.tracer ?? this.deps.tracer, () => ({
                         kind: "compaction.input_truncated",
                         version: 1,

package/dist/core/runner/tool-disclosure.d.ts

@@ -21,6 +21,7 @@ export declare function classifyDeferred(opts: {
     deferMode?: "auto";
     model: Model;
     deferNames?: ReadonlyArray<string>;
+    alwaysLoadNames?: ReadonlyArray<string>;
 }): Set<string>;
 export declare function buildDeferredRegistry(deferred: ReadonlySet<string>, tools: ReadonlyArray<{
     name: string;

package/dist/core/runner/tool-disclosure.js

@@ -24,17 +24,24 @@ function inlinedChars(t) {
     return t.description.length + schema.length;
 }
 export function classifyDeferred(opts) {
+    const pinned = new Set(opts.alwaysLoadNames ?? []);
+    for (const s of opts.specs) {
+        if (s.alwaysLoad === true)
+            pinned.add(s.name);
+    }
     const deferred = new Set();
     for (const s of opts.specs) {
-        if (s.defer === true)
+        if (s.defer === true && !pinned.has(s.name))
             deferred.add(s.name);
     }
     for (const name of opts.mcpToolNames)
-        deferred.add(name);
+        if (!pinned.has(name))
+            deferred.add(name);
     for (const name of opts.deferNames ?? [])
-        deferred.add(name);
+        if (!pinned.has(name))
+            deferred.add(name);
     if (opts.deferMode === "auto") {
-        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name));
+        const candidates = opts.fullTools.filter((t) => !deferred.has(t.name) && !pinned.has(t.name));
         const total = candidates.reduce((n, t) => n + inlinedChars(t), 0);
         const window = (opts.model.contextTokens ?? opts.model.contextWindow ?? 0) * CHARS_PER_TOKEN;
         if (window > 0 && total > DEFER_AUTO_FRACTION * window) {
@@ -159,10 +166,14 @@ export function createToolSearchTool(opts) {
         name: TOOL_SEARCH_NAME,
         contract: { contractId: "core.tool_search@1", implementationRevision: "1" },
         description: "Discover and activate deferred tools. Most tools start as name-only placeholders to keep requests " +
-            "small; to USE one you must activate it here first. Query forms: " +
+            "small; to USE one you must activate it here first. When any instruction, reminder, or another " +
+            'tool\'s description names a deferred tool, activate it with query "select:<name>" before calling it. ' +
+            "Query forms: " +
             '"select:ToolA,ToolB" — activate these exact tools by name; ' +
             '"notebook jupyter" — keyword search, up to max_results best matches; ' +
             "a bare tool name — activates that tool directly. " +
+            "Activate every tool you expect to need in one call (select accepts a comma-separated list) " +
+            "rather than one at a time. " +
             "Activated tools become callable with their full parameters on your next turn.",
         parameters: Type.Object({
             query: Type.Optional(Type.String({

package/dist/core/runner/tool-output-projection.js

@@ -57,10 +57,11 @@ export const toolOutputFrom = (result) => {
     return { output: raw, truncated: true, totalChars };
 };
 const CC_DETAIL_TYPES = new Set([
-    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "text", "grep", "glob", "mcp",
+    "edit", "multiedit", "create", "update", "bash", "notebook-edit", "notebook", "file_unchanged", "worktree", "text", "grep", "glob", "mcp",
     "agent", "task", "task-list", "task-output", "memory-saved", "workflow-run",
     "web-fetch", "web-search", "todo", "cron-create", "cron-delete", "cron-list", "image",
     "task-stop", "tool-search", "memory-recall", "repo-map", "fork", "enter-plan-mode", "exit-plan-mode",
+    "monitor-start", "path_not_in_root",
 ]);
 export const structuredFrom = (result) => {
     const details = result !== null && typeof result === "object" ? result.details : undefined;

package/dist/core/session-reconcile.d.ts

@@ -4,6 +4,7 @@ import type { ToolEffect } from "./types.js";
 export interface OrphanToolCall {
     toolCallId: string;
     toolName: string;
+    kind?: "result";
 }
 export interface ReconcileReport {
     recovered: Array<OrphanToolCall & {

package/dist/core/session-reconcile.js

@@ -13,6 +13,7 @@ const INTERRUPTED_NEVER_STARTED = "[INTERRUPTED] The run was aborted before this
     "no side effects — it is safe to re-issue this call if you still need it.";
 export function findOrphanToolCalls(messages, suspendedBatch) {
     const resolvedAt = new Map();
+    const callSitesAt = new Map();
     messages.forEach((m, i) => {
         if (m.role === "toolResult") {
             const at = resolvedAt.get(m.toolCallId);
@@ -21,35 +22,54 @@ export function findOrphanToolCalls(messages, suspendedBatch) {
             else
                 at.push(i);
         }
-    });
-    const nextReuseAfter = (id, from) => {
-        for (let i = from + 1; i < messages.length; i++) {
-            const m = messages[i];
-            if (m?.role !== "assistant")
-                continue;
-            if (m.content.some((p) => p.type === "toolCall" && p.id === id))
-                return i;
+        else if (m.role === "assistant") {
+            for (const part of m.content) {
+                if (part.type !== "toolCall")
+                    continue;
+                const at = callSitesAt.get(part.id);
+                if (at === undefined)
+                    callSitesAt.set(part.id, [i]);
+                else
+                    at.push(i);
+            }
         }
-        return Number.POSITIVE_INFINITY;
-    };
+    });
+    const nextReuseAfter = (id, from) => callSitesAt.get(id)?.find((j) => j > from) ?? Number.POSITIVE_INFINITY;
     const orphans = [];
     messages.forEach((m, i) => {
-        if (m.role !== "assistant")
-            return;
-        for (const part of m.content) {
-            if (part.type !== "toolCall" || suspendedBatch?.has(part.id))
-                continue;
-            const bound = nextReuseAfter(part.id, i);
-            const closed = (resolvedAt.get(part.id) ?? []).some((at) => at > i && at < bound);
-            if (!closed)
-                orphans.push({ toolCallId: part.id, toolName: part.name });
+        if (m.role === "assistant") {
+            for (const part of m.content) {
+                if (part.type !== "toolCall" || suspendedBatch?.has(part.id))
+                    continue;
+                const bound = nextReuseAfter(part.id, i);
+                const closed = (resolvedAt.get(part.id) ?? []).some((at) => at > i && at < bound);
+                if (!closed)
+                    orphans.push({ toolCallId: part.id, toolName: part.name });
+            }
+        }
+        else if (m.role === "toolResult") {
+            if (suspendedBatch?.has(m.toolCallId))
+                return;
+            const sites = callSitesAt.get(m.toolCallId) ?? [];
+            const results = resolvedAt.get(m.toolCallId) ?? [];
+            let paired = false;
+            for (const j of sites) {
+                if (j >= i)
+                    break;
+                if (!results.some((at) => at > j && at < i)) {
+                    paired = true;
+                    break;
+                }
+            }
+            if (!paired)
+                orphans.push({ toolCallId: m.toolCallId, toolName: m.toolName, kind: "result" });
         }
     });
     return orphans;
 }
 export async function reconcileInterruptedSession(session, toolEffects, suspendedBatch, startedToolCallIds) {
     const { messages } = await session.buildContext();
-    const orphans = findOrphanToolCalls(messages, suspendedBatch);
+    const orphans = findOrphanToolCalls(messages, suspendedBatch).filter((o) => o.kind !== "result");
     const recovered = [];
     for (const orphan of orphans) {
         const effect = toolEffects?.get(canonicalToolName(orphan.toolName)) ?? "write";

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

@@ -0,0 +1,37 @@
+import { type Checkpoint, type CheckpointStore, type ResumeOutcome } from "../checkpoint-store.js";
+import { type ContractAssertionRunner } from "./contract-harness.js";
+export declare function createCheckpointFixture(over?: Partial<Checkpoint>): Checkpoint;
+export declare const ALLOW: Extract<ResumeOutcome, {
+    gate: "policy_ask";
+}>;
+export declare function checkpointStoreContract(make: () => CheckpointStore, runAssertion?: ContractAssertionRunner): Promise<void>;
+export declare function checkpointListByScopeSummaries(store: CheckpointStore): Promise<import("../checkpoint-store.js").CheckpointSummary[]>;
+export declare const EXPECTED_LISTBYSCOPE_SUMMARIES: ({
+    token: string;
+    sessionId: string;
+    scope: string;
+    gateKind: string;
+    severity: number;
+    deadline: number;
+    createdAt: number;
+    sourceTaskId: string;
+    principal: string;
+    toolCallId: string;
+    toolName: string;
+    toolInput: string;
+    spentMicroUsd?: undefined;
+} | {
+    token: string;
+    sessionId: string;
+    scope: string;
+    gateKind: string;
+    spentMicroUsd: number;
+    createdAt: number;
+    severity?: undefined;
+    deadline?: undefined;
+    sourceTaskId?: undefined;
+    principal?: undefined;
+    toolCallId?: undefined;
+    toolName?: undefined;
+    toolInput?: undefined;
+})[];