@sema-agent/core 2.4.0 → 2.5.0

package/dist/agents/subagent.js

@@ -221,6 +221,9 @@ export function classifySubagentError(child) {
                     : "logic";
     return { errorKind, retryable: errorKind !== "logic" };
 }
+function errorKindClause(c) {
+    return c !== undefined ? ` (error_kind: ${c.errorKind}, retryable: ${c.retryable})` : "";
+}
 const FAILED_SESSION_RETAIN_TTL_MS = 15 * 60 * 1000;
 const PARTIAL_FINDINGS_MAX_CHARS = 1200;
 const BG_NOTIFY_DRAIN_WINDOW_MS = 2_000;
@@ -427,7 +430,7 @@ export function createSubagentResume(deps) {
                             ...resultSettleFields(child.result),
                             ...(status !== "completed" ? { error: (child.errorMessage ?? `resumed run ${status}`).slice(0, 500) } : {}),
                             ...(errCodeRevive !== undefined ? { errorCode: errCodeRevive } : {}),
-                            ...(errClassRevive !== undefined ? { retryable: errClassRevive.retryable } : {}),
+                            ...(errClassRevive !== undefined ? { retryable: errClassRevive.retryable, errorKind: errClassRevive.errorKind } : {}),
                         });
                         if (winner !== undefined)
                             status = winner;
@@ -440,7 +443,7 @@ export function createSubagentResume(deps) {
                 const reviveName = deps.rowDescription ?? `sub-agent ${marker}`;
                 const failReasonRevive = status === "failed" ? child.errorMessage : undefined;
                 const reviveTerminalSummary = failReasonRevive !== undefined
-                    ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300)
+                    ? `Agent "${reviveName}" (resumed) failed: ${failReasonRevive}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + errorKindClause(errClassRevive)
                     : `Agent "${reviveName}" (resumed) ${status === "killed" ? "stopped" : child.status === "completed" ? "finished" : String(child.status)}${ccElapsedTag(Date.now() - reviveStartedAt)}`;
                 const ownsTerminalFacesRevive = deps.registry !== undefined && deps.taskId !== undefined ? deps.registry.claimAgentTerminalNotify(deps.taskId) : true;
                 if (ownsTerminalFacesRevive)
@@ -509,7 +512,7 @@ export function createSubagentResume(deps) {
                             status: abort.signal.aborted ? "killed" : "failed",
                             error: msgRevive.slice(0, 500),
                             ...(errCodeReviveReject !== undefined ? { errorCode: errCodeReviveReject } : {}),
-                            ...(errClassReviveReject !== undefined ? { retryable: errClassReviveReject.retryable } : {}),
+                            ...(errClassReviveReject !== undefined ? { retryable: errClassReviveReject.retryable, errorKind: errClassReviveReject.errorKind } : {}),
                         });
                     }
                     catch {
@@ -530,7 +533,7 @@ export function createSubagentResume(deps) {
                         status: abort.signal.aborted ? "killed" : "failed",
                         seq: entry.cycleSeq,
                         ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
-                        summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : "failed"}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300),
+                        summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : "failed"}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + (abort.signal.aborted ? "" : errorKindClause(errClassReviveReject)),
                         ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
                     });
                 try {
@@ -543,7 +546,7 @@ export function createSubagentResume(deps) {
                             status: abort.signal.aborted ? "killed" : "failed",
                             seq: entry.cycleSeq,
                             ...(stoppedByReject !== undefined ? { stoppedBy: stoppedByReject } : {}),
-                            summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : `failed: ${msgRevive}`}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300),
+                            summary: `Agent "${rejectName}" (resumed) ${abort.signal.aborted ? "stopped" : `failed: ${msgRevive}`}${ccElapsedTag(Date.now() - reviveStartedAt)}`.slice(0, 300) + (abort.signal.aborted ? "" : errorKindClause(errClassReviveReject)),
                             ...(abort.signal.aborted ? {} : { error: msgRevive.slice(0, REPORT_FIELD_MAX) }),
                             ...(!abort.signal.aborted && errCodeReviveReject !== undefined ? { errorCode: errCodeReviveReject } : {}),
                             ...(completionIdRejectRevive !== undefined ? { completionId: completionIdRejectRevive } : {}),
@@ -1753,7 +1756,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             ...resultSettleFields(child.result),
                             ...(!okBg ? { error: reapedBg ? (collateralBg ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
                             ...(errCodeFork !== undefined ? { errorCode: errCodeFork } : {}),
-                            ...(errClassFork !== undefined ? { retryable: errClassFork.retryable } : {}),
+                            ...(errClassFork !== undefined ? { retryable: errClassFork.retryable, errorKind: errClassFork.errorKind } : {}),
                         }) ?? (abort.signal.aborted ? "killed" : okBg ? "completed" : "failed");
                         const stoppedByBg = settledBg === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
                         const completionIdFork = bg.registry.getCompletionId(taskId);
@@ -1770,7 +1773,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         const forkTranscriptId = child.sessionId ?? forkedId;
                         const failReasonFork = settledBg === "failed" ? child.errorMessage : undefined;
                         const forkTerminalSummary = failReasonFork !== undefined
-                            ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(Date.now() - forkBgStartedAt)}`.slice(0, 300)
+                            ? `Agent "${shortDesc}" failed: ${failReasonFork}${ccElapsedTag(Date.now() - forkBgStartedAt)}`.slice(0, 300) + errorKindClause(errClassFork)
                             : `${ccCompletionText(shortDesc, settledBg, String(child.status), Date.now() - forkBgStartedAt)}`;
                         const ownsTerminalFacesFork = bg.registry.claimAgentTerminalNotify(taskId);
                         if (ownsTerminalFacesFork)
@@ -1823,11 +1826,11 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             status: killed ? "killed" : "failed",
                             error: killed ? BG_AGENT_REAP_STOP_ERROR : msgFork,
                             ...(errCodeForkReject !== undefined ? { errorCode: errCodeForkReject } : {}),
-                            ...(errClassForkReject !== undefined ? { retryable: errClassForkReject.retryable } : {}),
+                            ...(errClassForkReject !== undefined ? { retryable: errClassForkReject.retryable, errorKind: errClassForkReject.errorKind } : {}),
                         }) ?? (killed ? "killed" : "failed");
                         const stoppedByBg = settledBg === "killed" ? bg.registry.getStopAttribution(taskId) ?? "system" : undefined;
                         const completionIdForkReject = bg.registry.getCompletionId(taskId);
-                        const summaryBg = `${shortDesc} — ${settledBg === "failed" ? `failed: ${msgFork}` : settledBg}`.slice(0, 300);
+                        const summaryBg = `${shortDesc} — ${settledBg === "failed" ? `failed: ${msgFork}` : settledBg}`.slice(0, 300) + (settledBg === "failed" ? errorKindClause(errClassForkReject) : "");
                         const ownsTerminalFacesForkReject = bg.registry.claimAgentTerminalNotify(taskId);
                         if (ownsTerminalFacesForkReject)
                             sinkEmit({
@@ -2390,7 +2393,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         ...resultSettleFields(child.result),
                         ...(!ok ? { error: reaped ? (collateral ? BG_AGENT_COLLATERAL_REAP_REASON : BG_AGENT_REAP_STOP_ERROR) : child.errorMessage ?? String(child.status) } : {}),
                         ...(errCodeBg !== undefined ? { errorCode: errCodeBg } : {}),
-                        ...(errClassBg !== undefined ? { retryable: errClassBg.retryable } : {}),
+                        ...(errClassBg !== undefined ? { retryable: errClassBg.retryable, errorKind: errClassBg.errorKind } : {}),
                     }) ??
                         (abort.signal.aborted ? "killed" : ok ? "completed" : "failed");
                     if (!bgRetain && reviveRow === undefined && !(await bgRowConfirmed())) {
@@ -2408,7 +2411,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                     const resumableBg = bgRetain !== undefined && settled !== "killed";
                     const failReasonBg = settled === "failed" ? child.errorMessage : undefined;
                     const bgTerminalSummary = failReasonBg !== undefined
-                        ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300)
+                        ? `Agent "${shortDesc}" failed: ${failReasonBg}${ccElapsedTag(Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + errorKindClause(errClassBg)
                         : `${ccCompletionText(shortDesc, settled, String(child.status), Date.now() - bgStartedAt)}${observerNote}`;
                     const ownsTerminalFaces = bg.registry.claimAgentTerminalNotify(taskId);
                     if (ownsTerminalFaces)
@@ -2485,7 +2488,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                         error: msg,
                         seq: seqAtSettle ?? 1,
                         ...(errCodeBgReject !== undefined ? { errorCode: errCodeBgReject } : {}),
-                        ...(errClassBgReject !== undefined ? { retryable: errClassBgReject.retryable } : {}),
+                        ...(errClassBgReject !== undefined ? { retryable: errClassBgReject.retryable, errorKind: errClassBgReject.errorKind } : {}),
                     }) ?? (killed ? "killed" : "failed");
                     if (!bgRetain && reviveRow === undefined && !(await bgRowConfirmed())) {
                         try {
@@ -2510,7 +2513,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                             status: settled,
                             ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
                             ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                            summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300),
+                            summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + (settled === "failed" ? errorKindClause(errClassBgReject) : ""),
                             ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),
                         });
                     try {
@@ -2523,7 +2526,7 @@ function createSubagentToolNode(opts, depth, excluded, extraToolsBudget) {
                                 sessionId: bgChildSessionId,
                                 ...(seqAtSettle !== undefined ? { seq: seqAtSettle } : {}),
                                 ...(stoppedBy !== undefined ? { stoppedBy } : {}),
-                                summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300),
+                                summary: `${settled === "failed" ? `Agent "${shortDesc}" failed: ${msg}${ccElapsedTag(Date.now() - bgStartedAt)}` : ccCompletionText(shortDesc, settled, settled, Date.now() - bgStartedAt)}${observerNote}`.slice(0, 300) + (settled === "failed" ? errorKindClause(errClassBgReject) : ""),
                                 ...(settled === "failed" ? { error: msg.slice(0, REPORT_FIELD_MAX) } : {}),
                                 ...(settled === "failed" && errCodeBgReject !== undefined ? { errorCode: errCodeBgReject } : {}),
                                 ...(completionIdBgReject !== undefined ? { completionId: completionIdBgReject } : {}),

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/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) {
@@ -608,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) {
@@ -1781,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))
@@ -1820,6 +1832,14 @@ 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))

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/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/task-registry-agent.d.ts

@@ -68,6 +68,7 @@ export declare function settleBackgroundAgentLane(core: DurableAgentCore, id: st
     error?: string;
     errorCode?: string;
     retryable?: boolean;
+    errorKind?: string;
     stoppedBy?: StopSource;
     seq?: number;
 }): "completed" | "failed" | "killed" | undefined;
@@ -102,6 +103,7 @@ export declare function settleRevivedAgentLane(core: DurableAgentCore, id: strin
     error?: string;
     errorCode?: string;
     retryable?: boolean;
+    errorKind?: string;
 }): "completed" | "failed" | "killed" | undefined;
 export declare function unmarkRetainedContinuationLane(core: DurableAgentCore, id: string): void;
 export declare function attachAgentNotifyLane(core: DurableAgentCore, id: string, notify: NonNullable<BackgroundAgentTaskHandle["notify"]>, cycle?: number): void;