@sema-agent/core 2.4.0 → 2.6.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.d.ts

@@ -68,6 +68,7 @@ export declare function mcpToolTotalTimeoutMs(perCallMs: number): number;
 export declare const MCP_IDLE_TIMEOUT_STDIO_DEFAULT_MS: number;
 export declare const MCP_IDLE_TIMEOUT_HTTP_DEFAULT_MS: number;
 export declare function mcpIdleTimeoutMs(kind: "stdio" | "http"): number;
+export declare function describeMcpSpecErrorCode(code: unknown): string | undefined;
 export declare function normalizeMcpName(name: string): string;
 export declare function clampNameSegment(seg: string, max?: number): string;
 export * from "./image-downsample.js";
@@ -106,3 +107,11 @@ export type McpSchemaNormalizeResult = {
 export declare function normalizeMcpToolSchema(schema: unknown): McpSchemaNormalizeResult;
 export declare function mcpToolSchemaProblem(schema: unknown): string | undefined;
 export declare function materializeMcpTools(specs: McpServerSpec[], principal?: string, onElicit?: OnElicit, imageResizer?: McpImageResizer): Promise<MaterializedMcp>;
+export declare function classifyDirReadInvalidParams(message: string): "not_found" | "not_directory";
+export declare function parseCallToolResultLenient(data: unknown): {
+    success: true;
+    data: unknown;
+} | {
+    success: false;
+    error: unknown;
+};

package/dist/core/mcp.js

@@ -5,7 +5,7 @@ import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/
 import { lstat, mkdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { ElicitRequestSchema, ErrorCode, ListResourcesResultSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
+import { CallToolResultSchema, ElicitRequestSchema, ErrorCode, ListResourcesResultSchema, McpError } from "@modelcontextprotocol/sdk/types.js";
 import { MCP_IMAGE_MAX_BASE64, sharpImageResizer } from "./image-downsample.js";
 import { truncateError } from "./tool-errors.js";
 import { delimitUntrusted, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
@@ -137,6 +137,14 @@ function armMcpIdleWatchdog(health, idleMs, outerSignal) {
 function mcpStartupTimeoutMs() {
     return parseEnvMs("MCP_TIMEOUT");
 }
+const MCP_SPEC_ERROR_CODE_NAMES = new Map([
+    [-32020, "header mismatch (the server saw an HTTP header that disagreed with the tool parameter mapped onto it)"],
+    [-32021, "missing required client capability (the server requires a capability this client does not declare)"],
+    [-32022, "unsupported protocol version (the server implements no protocol revision this client offers)"],
+]);
+export function describeMcpSpecErrorCode(code) {
+    return typeof code === "number" ? MCP_SPEC_ERROR_CODE_NAMES.get(code) : undefined;
+}
 function isTransportLost(err) {
     if (err instanceof McpError && err.code === ErrorCode.ConnectionClosed)
         return true;
@@ -180,6 +188,15 @@ function rethrowHonestMcpError(err, ctx) {
         e.details = { transportLost: true, server: ctx.server };
         throw e;
     }
+    if (err instanceof McpError) {
+        const condition = describeMcpSpecErrorCode(err.code);
+        if (condition !== undefined) {
+            const e = new Error(`${ctx.what} on MCP server "${serverLabel}" was rejected with MCP protocol error ${err.code} — ${condition}. The server's error text follows as external/untrusted data:\n${delimitUntrusted(`${ctx.server} error`, truncateMcpErrorText(err.message))}`, { cause: err });
+            e.errorKind = "protocol_error";
+            e.details = { server: ctx.server, specErrorCode: err.code };
+            throw e;
+        }
+    }
     if (ctx.attributeServer) {
         const msg = err instanceof Error ? err.message : String(err);
         throw new Error(`${ctx.what} on MCP server "${serverLabel}" failed. The server's error text follows as external/untrusted data:\n${delimitUntrusted(`${ctx.server} error`, truncateMcpErrorText(msg))}`, { cause: err });
@@ -653,6 +670,15 @@ const LEGACY_READ_MCP_RESOURCE = "ReadMcpResource";
 const LEGACY_READ_MCP_RESOURCE_DIR = "ReadMcpResourceDir";
 const MCP_SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
 const MAX_DIR_READ_PAGES = 20;
+const DIR_READ_NOT_A_DIRECTORY_RE = /not a directory|isn'?t a directory|not a folder/i;
+const DIR_READ_NOT_FOUND_RE = /not found|no such|does not exist|doesn'?t exist|unknown (?:resource|uri)/i;
+export function classifyDirReadInvalidParams(message) {
+    if (DIR_READ_NOT_A_DIRECTORY_RE.test(message))
+        return "not_directory";
+    if (DIR_READ_NOT_FOUND_RE.test(message))
+        return "not_found";
+    return "not_directory";
+}
 function resourceLine(r) {
     return `${r.uri}${r.name ? ` — ${r.name}` : ""}${r.mimeType ? ` (${r.mimeType})` : ""}${r.description ? `: ${r.description}` : ""}`;
 }
@@ -672,7 +698,7 @@ async function readDirViaExtension(rs, uri, signal, timeoutMs, watchdog) {
             if (err instanceof McpError && err.code === ErrorCode.InvalidParams) {
                 if (pages > 0)
                     return { kind: "ok", resources, cursorInvalid: true };
-                return { kind: "not_directory" };
+                return { kind: classifyDirReadInvalidParams(err.message), detail: err.message };
             }
             if (err instanceof McpError && err.code === ErrorCode.MethodNotFound)
                 return { kind: "unsupported" };
@@ -866,9 +892,22 @@ function buildResourceTools(resourceServers) {
                     const ext = rs.client.getServerCapabilities()?.extensions?.[MCP_SKILLS_EXTENSION];
                     if (ext?.directoryRead === true) {
                         const r = await readDirViaExtension(rs, uri, signal, timeoutMs, watchdog).catch((err) => rethrowHonestMcpError(err, { server, what, timeoutMs, writeEffect: false, signal, attributeServer: true, idle: { signal: watchdog.idleSignal, idleMs } }));
+                        const serverSaid = (detail) => `\nThe server's error text follows as external/untrusted data:\n${delimitUntrusted(`${server} error`, truncateMcpErrorText(detail))}`;
+                        if (r.kind === "not_found") {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `Resource not found: ${inlineUntrusted(uri)} — the server reports no such resource, so re-reading it will not help either. Use ${LIST_MCP_RESOURCES} to see what this server exposes.${serverSaid(r.detail)}`,
+                                    },
+                                ],
+                                details: { resources: [], notFound: true },
+                                terminate: false,
+                            };
+                        }
                         if (r.kind === "not_directory") {
                             return {
-                                content: [{ type: "text", text: `Not a directory resource: ${inlineUntrusted(uri)}. If it is a file resource, use ${READ_MCP_RESOURCE} instead.` }],
+                                content: [{ type: "text", text: `Not a directory resource: ${inlineUntrusted(uri)}. If it is a file resource, use ${READ_MCP_RESOURCE} instead.${serverSaid(r.detail)}` }],
                                 details: { resources: [] },
                                 terminate: false,
                             };
@@ -929,6 +968,17 @@ const LenientListToolsResultSchema = {
         return { success: true, data: { tools, ...(typeof nextCursor === "string" ? { nextCursor } : {}) } };
     },
 };
+export function parseCallToolResultLenient(data) {
+    if (typeof data !== "object" || data === null || Array.isArray(data) || !("structuredContent" in data)) {
+        return CallToolResultSchema.safeParse(data);
+    }
+    const { structuredContent, ...rest } = data;
+    const parsed = CallToolResultSchema.safeParse(rest);
+    if (!parsed.success)
+        return parsed;
+    return { success: true, data: { ...parsed.data, structuredContent } };
+}
+const LENIENT_CALL_TOOL_RESULT_SCHEMA = { safeParse: parseCallToolResultLenient };
 async function listToolsLenient(client, options) {
     return client.request({ method: "tools/list", params: {} }, LenientListToolsResultSchema, options);
 }
@@ -1039,13 +1089,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)
@@ -1056,7 +1109,7 @@ function intakeListedTools(listed, spec, client, health, imageResizer) {
                 let res;
                 try {
                     res = await client
-                        .callTool({ name: remoteName, arguments: (params ?? {}) }, undefined, {
+                        .callTool({ name: remoteName, arguments: (params ?? {}) }, LENIENT_CALL_TOOL_RESULT_SCHEMA, {
                         signal: watchdog.combinedSignal,
                         timeout: timeoutMs,
                         resetTimeoutOnProgress: true,
@@ -1103,7 +1156,8 @@ function intakeListedTools(listed, spec, client, health, imageResizer) {
 }
 function asServerWarning(spec, err) {
     const detail = err instanceof Error ? err.message : String(err);
-    const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${detail})`, { cause: err });
+    const condition = err instanceof McpError ? describeMcpSpecErrorCode(err.code) : undefined;
+    const warning = new Error(`mcp: server "${spec.name}" failed to connect — skipped (${condition !== undefined ? `${condition}: ` : ""}${detail})`, { cause: err });
     warning.code = "mcp.server_unavailable";
     return warning;
 }

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))
@@ -1814,12 +1826,38 @@ export async function prepareTask(spec, deps, sessions, resume, internals, runne
                 throw e;
             }
             const registry = buildDeferredRegistry(deferred, tools);
-            const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i)]));
+            const realByName = new Map(tools.map((t) => [t.name, t]));
+            const directCallFor = (name) => {
+                if (spec.deferSelfResolve === false)
+                    return undefined;
+                const real = realByName.get(name);
+                if (real === undefined)
+                    return undefined;
+                return {
+                    parameters: real.parameters,
+                    invoke: (toolCallId, params, signal) => real.execute(toolCallId, params, signal),
+                    activate: async () => {
+                        if (activeTools.has(name))
+                            return;
+                        activeTools.add(name);
+                        await rematerialize(activeTools);
+                    },
+                };
+            };
+            const placeholders = new Map([...registry.values()].map((i) => [i.name, createPlaceholderTool(i, directCallFor(i.name))]));
             const { messages } = await session.buildContext();
             for (const n of extractDiscoveredToolNames(messages, registry)) {
                 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 {
@@ -821,6 +844,7 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
                 taskId: rs.telemetry.taskId,
                 model: m.model,
                 provider: m.provider,
+                turn: stats.turns + 1,
                 promptTokens: turnInput,
                 completionTokens: u.output || 0,
                 cacheRead: u.cacheRead || 0,
@@ -988,6 +1012,8 @@ function makeHarnessHandlers(prepared, stats, rs, deps) {
             version: 1,
             taskId: rs.telemetry.taskId,
             name: event.toolName,
+            toolCallId: event.toolCallId,
+            turn: stats.turns + 1,
             durationMs: toolStarted !== undefined ? toolNow - toolStarted : 0,
             ok: !event.isError,
             ts: toolNow,
@@ -2319,6 +2345,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 +2373,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 +2385,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 +2400,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 +2692,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 +3485,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

@@ -1,4 +1,5 @@
-import type { AgentMessage, AgentTool } from "../../internal/harness-types.js";
+import { type TSchema } from "typebox";
+import type { AgentMessage, AgentTool, AgentToolResult } from "../../internal/harness-types.js";
 import type { Model } from "../../internal/llm.js";
 import type { ToolSpec } from "../types.js";
 export declare const TOOL_SEARCH_NAME = "ToolSearch";
@@ -21,12 +22,18 @@ 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;
     description: string;
 }>): Map<string, DeferredToolInfo>;
-export declare function createPlaceholderTool(info: DeferredToolInfo): AgentTool;
+export interface PlaceholderDirectCall {
+    parameters: TSchema;
+    invoke: (toolCallId: string, params: unknown, signal?: AbortSignal) => Promise<AgentToolResult<unknown>>;
+    activate: () => Promise<void>;
+}
+export declare function createPlaceholderTool(info: DeferredToolInfo, direct?: PlaceholderDirectCall): AgentTool;
 export declare function scoreToolMatch(query: string, info: DeferredToolInfo): number;
 export interface ToolSearchArgs {
     query?: string;