@sayknow-cli/coding-agent 0.3.15 → 0.4.0

package/src/task/index.ts

@@ -19,11 +19,10 @@ import type { AgentTool, AgentToolResult, AgentToolUpdateCallback } from "@saykn
 import type { Model, Usage } from "@sayknow-cli/ai";
 import { $env, prompt, Snowflake } from "@sayknow-cli/utils";
 import type { ToolSession } from "..";
-import { AsyncJobManager } from "../async";
+import { AsyncJobManager, OwnerSubagentShutdownError, type ResumeRunner } from "../async";
 import { resolveAgentModelPatterns } from "../config/model-resolver";
 import type { Theme } from "../modes/theme/theme";
 import planModeSubagentPrompt from "../prompts/system/plan-mode-subagent.md" with { type: "text" };
-import subagentUserPromptTemplate from "../prompts/system/subagent-user-prompt.md" with { type: "text" };
 import taskDescriptionTemplate from "../prompts/tools/task.md" with { type: "text" };
 import taskSummaryTemplate from "../prompts/tools/task-summary.md" with { type: "text" };
 import type { ForkContextSeed } from "../session/agent-session";
@@ -44,11 +43,11 @@ import {
 
 // Import review tools for side effects (registers subagent tool handlers)
 import "../tools/review";
-import type { LocalProtocolOptions } from "../internal-urls";
+import { initializeLocalRoot, type LocalProtocolOptions, resolveLocalUrlToPath } from "../internal-urls";
 import { generateCommitMessage } from "../utils/commit-message-generator";
 import * as git from "../utils/git";
 import { discoverAgents, filterVisibleAgents, getAgent } from "./discovery";
-import { runSubprocess } from "./executor";
+import { createManagedTaskPersistence, renderSubagentUserPrompt, runSubprocess } from "./executor";
 import { adviseForkContextMode } from "./fork-context-advisory";
 import { FORK_CONTEXT_TOKEN_BUDGET_BY_MODE } from "./fork-context-budget";
 import { getTaskIdValidationError, validateAllocatedTaskId } from "./id";
@@ -87,11 +86,8 @@ interface TaskResumeDescriptor {
 function isTaskResumeDescriptor(value: unknown): value is TaskResumeDescriptor {
 	return typeof value === "object" && value !== null && "task" in value && "params" in value;
 }
-function renderSubagentUserPrompt(assignment: string, simpleMode: TaskSimpleMode): string {
-	return prompt.render(subagentUserPromptTemplate, {
-		assignment: assignment.trim(),
-		independentMode: simpleMode === "independent",
-	});
+function renderTaskAssignment(assignment: string, simpleMode: TaskSimpleMode): string {
+	return renderSubagentUserPrompt(assignment, simpleMode === "independent");
 }
 function createUsageTotals(): Usage {
 	return {
@@ -293,23 +289,30 @@ function requestsForkContext(
 	return FORK_CONTEXT_REQUEST_MODE_SET.has(task.inheritContext);
 }
 
+function normalizeForkContextCap(value: number | undefined, fallback: number, maximum: number): number {
+	if (value === undefined || !Number.isFinite(value) || value <= 0) return fallback;
+	return Math.min(maximum, Math.max(1, Math.trunc(value)));
+}
+
 function resolveForkSeedParamsForMode(
 	mode: ForkContextMode,
 	configuredMaxMessages: number | undefined,
 	configuredMaxTokens: number,
 	model: Model | undefined,
-): { maxMessages: number; maxTokens: number } | undefined {
+): { maxMessages: number; maxTokens: number; preserveLatestUser?: boolean } | undefined {
 	const capMessages = (defaultMaxMessages: number): number =>
-		configuredMaxMessages === undefined
-			? defaultMaxMessages
-			: Math.min(defaultMaxMessages, Math.max(0, Math.trunc(configuredMaxMessages)));
+		normalizeForkContextCap(configuredMaxMessages, defaultMaxMessages, defaultMaxMessages);
 	switch (mode) {
 		case "none":
 			return undefined;
 		case "receipt":
 			return { maxMessages: 1, maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE.receipt };
 		case "last-turn":
-			return { maxMessages: 2, maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE["last-turn"] };
+			return {
+				maxMessages: 2,
+				maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE["last-turn"],
+				preserveLatestUser: true,
+			};
 		case "bounded":
 			return { maxMessages: capMessages(50), maxTokens: FORK_CONTEXT_TOKEN_BUDGET_BY_MODE.bounded };
 		case "full":
@@ -343,9 +346,12 @@ function validateForkContextRequests(
 }
 
 export function resolveForkContextMaxTokens(configured: number, model: Model | undefined): number {
-	if (configured > 0) return Math.trunc(configured);
-	const contextWindow = model?.contextWindow ?? 0;
-	return contextWindow > 0 ? Math.max(1, Math.floor(contextWindow * 0.15)) : 15_000;
+	const contextWindow = model?.contextWindow;
+	const fallback =
+		contextWindow && Number.isFinite(contextWindow) && contextWindow > 0
+			? Math.max(1, Math.floor(contextWindow * 0.15))
+			: 15_000;
+	return normalizeForkContextCap(configured, fallback, Number.MAX_SAFE_INTEGER);
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -507,7 +513,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				agent: params.agent,
 				agentSource: fallbackAgentSource,
 				status: "pending",
-				task: renderSubagentUserPrompt(assignment, simpleMode),
+				task: renderTaskAssignment(assignment, simpleMode),
 				assignment,
 				description: taskItem.description,
 				recentTools: [],
@@ -547,8 +553,9 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		};
 
 		const maxConcurrency = this.session.settings.get("task.maxConcurrency");
+		let resumeRunner: ResumeRunner | undefined;
 		if (typeof manager.setResumeRunner === "function") {
-			manager.setResumeRunner((_subagentId, message, resumeDescriptor) => {
+			resumeRunner = (_subagentId, message, resumeDescriptor) => {
 				const descriptor = isTaskResumeDescriptor(resumeDescriptor?.data) ? resumeDescriptor.data : undefined;
 				if (!descriptor) return undefined;
 				const forkSeeds = descriptor.forkContextSeed
@@ -574,7 +581,15 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						);
 						const finalText = result.content.find(part => part.type === "text")?.text ?? "(no output)";
 						const singleResult = result.details?.results[0];
-						return singleResult?.paused ? { kind: "paused" } : finalText;
+						if (singleResult?.paused) return { kind: "paused" };
+						// A resumed subprocess that aborted or exited non-zero is a failed
+						// resume, not a completed one. Throw the rendered failure summary
+						// (finalText) so the leg is reported failed instead of being
+						// returned as successful continuation.
+						if (singleResult && ((singleResult.aborted ?? false) || singleResult.exitCode !== 0)) {
+							throw new Error(finalText);
+						}
+						return finalText;
 					},
 					{
 						id: `${descriptor.task.id}-resume-${Snowflake.next()}`,
@@ -590,7 +605,8 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						},
 					},
 				);
-			});
+			};
+			manager.setResumeRunner(resumeRunner);
 		}
 		const semaphore = new Semaphore(maxConcurrency);
 		const buildForkContextSeedForTask = async (task: TaskItem): Promise<ForkContextSeed | undefined> => {
@@ -615,8 +631,20 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 			});
 		};
 		const frozenForkSeeds = new Map<string, ForkContextSeed>();
+		const asyncParentArtifactManager = this.session.getArtifactManager?.() ?? undefined;
 		const parentSessionFileForBatch = this.session.getSessionFile();
 		const batchArtifactsDir = parentSessionFileForBatch ? parentSessionFileForBatch.slice(0, -6) : null;
+		let externalTaskSessionsDir: string | undefined;
+		if (!batchArtifactsDir) {
+			const asyncLocalOptions: LocalProtocolOptions = {
+				getArtifactsDir: this.session.getArtifactsDir ?? (() => null),
+				isManagedDestination: this.session.isManagedSessionDestination,
+				getSessionId: this.session.getSessionId ?? (() => null),
+			};
+			await initializeLocalRoot(asyncLocalOptions);
+			externalTaskSessionsDir = resolveLocalUrlToPath("local://subagents/sessions", asyncLocalOptions);
+			await fs.mkdir(externalTaskSessionsDir, { recursive: true, mode: 0o700 });
+		}
 
 		for (let i = 0; i < taskItems.length; i++) {
 			const taskItem = taskItems[i];
@@ -631,11 +659,25 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 
 			const uniqueId = validateAllocatedTaskId(uniqueIds[i] ?? "");
 			const frozenForkSeed = await buildForkContextSeedForTask(taskItem);
+			if (signal?.aborted) {
+				for (let skippedIndex = i; skippedIndex < taskItems.length; skippedIndex++) {
+					const skippedTask = taskItems[skippedIndex]!;
+					failedSchedules.push(`${skippedTask.id}: cancelled before scheduling`);
+					const skippedProgress = progressByTaskId.get(skippedTask.id);
+					if (skippedProgress) skippedProgress.status = "aborted";
+				}
+				break;
+			}
 			if (frozenForkSeed) frozenForkSeeds.set(uniqueId, frozenForkSeed);
 			const singleParams: TaskParams = { ...params, tasks: [taskItem] };
 			const label = uniqueId;
 			try {
-				const subtaskSessionFile = batchArtifactsDir ? path.join(batchArtifactsDir, `${uniqueId}.jsonl`) : null;
+				const managedPersistence = asyncParentArtifactManager?.getManagedStore()
+					? createManagedTaskPersistence(asyncParentArtifactManager, uniqueId)
+					: undefined;
+				const subtaskSessionFile = managedPersistence
+					? null
+					: path.join(batchArtifactsDir ?? externalTaskSessionsDir!, `${uniqueId}.jsonl`);
 				const jobId = manager.register(
 					"task",
 					label,
@@ -770,18 +812,21 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				);
 				startedJobs.push({ jobId, taskId: taskItem.id });
 				if (typeof manager.registerResumeDescriptor === "function") {
-					manager.registerResumeDescriptor({
-						subagentId: uniqueId,
-						ownerId: this.session.getAgentId?.() ?? undefined,
-						data: {
-							toolCallId: _toolCallId,
-							params,
-							task: { ...taskItem, id: uniqueId },
-							sessionFile: subtaskSessionFile,
-							forkContextSeed: frozenForkSeed,
-							agentSource: fallbackAgentSource,
-						} satisfies TaskResumeDescriptor,
-					});
+					manager.registerResumeDescriptor(
+						{
+							subagentId: uniqueId,
+							ownerId: this.session.getAgentId?.() ?? undefined,
+							data: {
+								toolCallId: _toolCallId,
+								params,
+								task: { ...taskItem, id: uniqueId },
+								sessionFile: subtaskSessionFile,
+								forkContextSeed: frozenForkSeed,
+								agentSource: fallbackAgentSource,
+							} satisfies TaskResumeDescriptor,
+						},
+						resumeRunner,
+					);
 				}
 				if (typeof manager.registerSubagentRecord === "function") {
 					manager.registerSubagentRecord({
@@ -790,12 +835,17 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						currentJobId: jobId,
 						historicalJobIds: [],
 						status: manager.getJob(jobId)?.status ?? "running",
-						sessionFile: subtaskSessionFile,
-						resumable: !!batchArtifactsDir,
+						sessionFile: null,
+						resumable: true,
 					});
 				}
 			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
+				const message =
+					error instanceof OwnerSubagentShutdownError
+						? error.message
+						: error instanceof Error
+							? error.message
+							: String(error);
 				failedSchedules.push(`${taskItem.id}: ${message}`);
 				const progress = progressByTaskId.get(taskItem.id);
 				if (progress) {
@@ -1107,6 +1157,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 		// Share the parent session's local:// root with subagents so they read/write the same scratch space
 		const localProtocolOptions: LocalProtocolOptions = {
 			getArtifactsDir: this.session.getArtifactsDir ?? (() => null),
+			isManagedDestination: this.session.isManagedSessionDestination,
 			getSessionId: this.session.getSessionId ?? (() => null),
 		};
 
@@ -1116,6 +1167,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 
 		// Initialize progress tracking
 		const progressMap = new Map<number, AgentProgress>();
+		const isolatedPatchBytes = new Map<string, Buffer>();
 
 		// Update callback
 		const emitProgress = () => {
@@ -1176,14 +1228,16 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 				};
 			}
 
-			// Write parent conversation context for subagents. When IRC is available,
-			// subagents should ask live peers instead of reading a stale markdown dump.
-			await fs.mkdir(effectiveArtifactsDir, { recursive: true });
+			// Place fork-context handoff material in the session-scoped external local
+			// root. Subagent prompts may expose this path to subprocesses, so it must
+			// never carry managed transcript/artifact authority.
 			const shouldWriteConversationContext = !hasAvailableIrcTool(this.session);
 			const compactContext = shouldWriteConversationContext ? this.session.getCompactContext?.() : undefined;
 			let contextFilePath: string | undefined;
 			if (compactContext) {
-				contextFilePath = path.join(effectiveArtifactsDir, "context.md");
+				await initializeLocalRoot(localProtocolOptions);
+				contextFilePath = resolveLocalUrlToPath("local://subagents/context.md", localProtocolOptions);
+				await fs.mkdir(path.dirname(contextFilePath), { recursive: true, mode: 0o700 });
 				await Bun.write(contextFilePath, compactContext);
 			}
 
@@ -1222,7 +1276,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					agent: agentName,
 					agentSource: agent.source,
 					status: "pending",
-					task: renderSubagentUserPrompt(assignment, simpleMode),
+					task: renderTaskAssignment(assignment, simpleMode),
 					assignment,
 					recentTools: [],
 					recentOutput: [],
@@ -1282,12 +1336,17 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					recommendedMode: advisory.recommendedMode,
 					reasons: advisory.reasons,
 				};
-				const taskSessionFile = overrides?.sessionFile ?? executionOverrides?.sessionFiles?.get(task.id) ?? null;
+				const managedPersistence = parentArtifactManager?.getManagedStore()
+					? createManagedTaskPersistence(parentArtifactManager, task.id)
+					: undefined;
+				const taskSessionFile = managedPersistence
+					? null
+					: (overrides?.sessionFile ?? executionOverrides?.sessionFiles?.get(task.id) ?? null);
 				if (!isIsolated) {
 					const result = await runSubprocess({
 						cwd: this.session.cwd,
 						agent: effectiveAgent,
-						task: renderSubagentUserPrompt(task.assignment, simpleMode),
+						task: renderTaskAssignment(task.assignment, simpleMode),
 						assignment: task.assignment.trim(),
 						context: sharedContext,
 						description: task.description,
@@ -1305,6 +1364,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						sessionFile: taskSessionFile,
 						persistArtifacts: !!artifactsDir,
 						artifactsDir: effectiveArtifactsDir,
+						managedPersistence,
 						contextFile: contextFilePath,
 						ircAvailable: hasAvailableIrcTool(this.session),
 						enableLsp: subagentLspEnabled,
@@ -1351,7 +1411,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						cwd: this.session.cwd,
 						worktree: isolationDir,
 						agent: effectiveAgent,
-						task: renderSubagentUserPrompt(task.assignment, simpleMode),
+						task: renderTaskAssignment(task.assignment, simpleMode),
 						assignment: task.assignment.trim(),
 						context: sharedContext,
 						description: task.description,
@@ -1369,6 +1429,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						sessionFile: taskSessionFile,
 						persistArtifacts: !!artifactsDir,
 						artifactsDir: effectiveArtifactsDir,
+						managedPersistence,
 						contextFile: contextFilePath,
 						ircAvailable: hasAvailableIrcTool(this.session),
 						enableLsp: subagentLspEnabled,
@@ -1440,9 +1501,15 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					if (resultWithForkContext.exitCode === 0) {
 						try {
 							const delta = await captureDeltaPatch(isolationDir, taskBaseline);
+							await initializeLocalRoot(localProtocolOptions);
 							const artifactId = validateAllocatedTaskId(task.id);
-							const patchPath = path.join(effectiveArtifactsDir, `${artifactId}.patch`);
+							const patchPath = resolveLocalUrlToPath(
+								`local://subagents/${artifactId}.patch`,
+								localProtocolOptions,
+							);
+							await fs.mkdir(path.dirname(patchPath), { recursive: true, mode: 0o700 });
 							await Bun.write(patchPath, delta.rootPatch);
+							isolatedPatchBytes.set(patchPath, Buffer.from(delta.rootPatch, "utf8"));
 							const producedChanges = Boolean(delta.rootPatch.trim() || delta.nestedPatches.length);
 							return {
 								...resultWithForkContext,
@@ -1464,7 +1531,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 						id: task.id,
 						agent: agent.name,
 						agentSource: agent.source,
-						task: renderSubagentUserPrompt(assignment, simpleMode),
+						task: renderTaskAssignment(assignment, simpleMode),
 						assignment,
 						description: task.description,
 						exitCode: 1,
@@ -1504,7 +1571,7 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 					id: task.id,
 					agent: agentName,
 					agentSource: agent.source,
-					task: renderSubagentUserPrompt(assignment, simpleMode),
+					task: renderTaskAssignment(assignment, simpleMode),
 					assignment,
 					description: task.description,
 					exitCode: 1,
@@ -1597,19 +1664,20 @@ export class TaskTool implements AgentTool<TaskToolSchemaInstance, TaskToolDetai
 							changesApplied = false;
 							hadAnyChanges = false;
 						} else {
-							const patchStats = await Promise.all(
-								patchesInOrder.map(async patchPath => ({
-									patchPath,
-									size: (await fs.stat(patchPath)).size,
-								})),
-							);
+							const patchStats = patchesInOrder.map(patchPath => ({
+								patchPath,
+								size: isolatedPatchBytes.get(patchPath)?.byteLength ?? -1,
+							}));
+							if (patchStats.some(patch => patch.size < 0)) {
+								throw new Error("Captured isolated patch bytes are unavailable");
+							}
 							const nonEmptyPatches = patchStats.filter(patch => patch.size > 0).map(patch => patch.patchPath);
 							if (nonEmptyPatches.length === 0) {
 								changesApplied = true;
 								hadAnyChanges = false;
 							} else {
-								const patchTexts = await Promise.all(
-									nonEmptyPatches.map(async patchPath => Bun.file(patchPath).text()),
+								const patchTexts = nonEmptyPatches.map(patchPath =>
+									isolatedPatchBytes.get(patchPath)!.toString("utf8"),
 								);
 								const combinedPatch = patchTexts
 									.map(text => (text.endsWith("\n") ? text : `${text}\n`))

package/src/thinking.ts

@@ -57,17 +57,32 @@ export function clampExplicitThinkingLevelForModel(
 	return clampThinkingLevelForModel(model, level);
 }
 
+export interface SelectorThinkingSuffix {
+	selector: string;
+	thinkingLevel?: ThinkingLevel;
+	invalidSuffix?: string;
+}
+
+/** Split the final selector suffix once, preserving colons in model IDs. */
+export function splitSelectorThinkingSuffix(selector: string): SelectorThinkingSuffix {
+	const colonIndex = selector.lastIndexOf(":");
+	if (colonIndex === -1) return { selector };
+
+	const suffix = selector.slice(colonIndex + 1);
+	const thinkingLevel = parseThinkingLevel(suffix);
+	return thinkingLevel
+		? { selector: selector.slice(0, colonIndex), thinkingLevel }
+		: { selector: selector.slice(0, colonIndex), invalidSuffix: suffix };
+}
+
 export function formatClampedModelSelector(selector: string, model: Model | undefined): string {
 	const slashIdx = selector.indexOf("/");
 	if (slashIdx <= 0) return selector;
 	const id = selector.slice(slashIdx + 1);
-	const colonIdx = id.lastIndexOf(":");
-	if (colonIdx === -1) return selector;
-	const suffix = id.slice(colonIdx + 1);
-	const thinkingLevel = parseThinkingLevel(suffix);
+	const { selector: baseId, thinkingLevel } = splitSelectorThinkingSuffix(id);
 	if (!thinkingLevel) return selector;
 	const clamped = clampExplicitThinkingLevelForModel(model, thinkingLevel);
 	return clamped && clamped !== ThinkingLevel.Inherit
-		? `${selector.slice(0, slashIdx + 1)}${id.slice(0, colonIdx)}:${clamped}`
-		: selector.slice(0, slashIdx + 1) + id.slice(0, colonIdx);
+		? `${selector.slice(0, slashIdx + 1)}${baseId}:${clamped}`
+		: selector.slice(0, slashIdx + 1) + baseId;
 }

package/src/tool-discovery/tool-index.ts

@@ -7,6 +7,7 @@ export type DiscoverableToolSource = "builtin" | "mcp" | "extension" | "custom";
 export interface DiscoverableTool {
 	name: string;
 	label: string;
+	description: string;
 	/** Short BM25 corpus entry; falls back to description first 200 chars */
 	summary: string;
 	source: DiscoverableToolSource;
@@ -44,47 +45,6 @@ export interface DiscoverableToolSearchResult {
 	score: number;
 }
 
-// ─── Legacy MCP-typed aliases (back-compat) ──────────────────────────────────
-
-/** @deprecated Use DiscoverableTool with source === "mcp" */
-export type DiscoverableMCPTool = Pick<
-	DiscoverableTool,
-	"name" | "label" | "schemaKeys" | "serverName" | "mcpToolName"
-> & { description: string };
-
-/** @deprecated Use DiscoverableToolServerSummary */
-export type DiscoverableMCPToolServerSummary = DiscoverableToolServerSummary;
-
-/** @deprecated Use DiscoverableToolSummary */
-export type DiscoverableMCPToolSummary = DiscoverableToolSummary;
-
-/** Tool object stored on legacy MCP index documents. Carries both legacy `description` and the
- *  generic `summary`/`source` so the legacy index is structurally assignable to
- *  DiscoverableToolSearchIndex (search functions read termFrequencies, not the tool fields). */
-export type DiscoverableMCPSearchTool = DiscoverableTool & { description: string };
-
-/** @deprecated Use DiscoverableToolSearchDocument */
-export interface DiscoverableMCPSearchDocument {
-	tool: DiscoverableMCPSearchTool;
-	termFrequencies: Map<string, number>;
-	length: number;
-}
-
-/** @deprecated Use DiscoverableToolSearchIndex.
- *  Documents on this index expose `tool.description` (legacy MCP shape) while still being
- *  searchable via `searchDiscoverableTools`. */
-export interface DiscoverableMCPSearchIndex {
-	documents: DiscoverableMCPSearchDocument[];
-	averageLength: number;
-	documentFrequencies: Map<string, number>;
-}
-
-/** @deprecated Use DiscoverableToolSearchResult */
-export interface DiscoverableMCPSearchResult {
-	tool: DiscoverableMCPSearchTool;
-	score: number;
-}
-
 // ─── BM25 Constants ───────────────────────────────────────────────────────────
 
 const BM25_K1 = 1.2;
@@ -105,6 +65,24 @@ export function isMCPToolName(name: string): boolean {
 	return name.startsWith("mcp__");
 }
 
+/** Select persisted built-in discoveries that remain eligible in the current registry, allowlist, and baseline policy. */
+export function selectRestorableDiscoveredBuiltinToolNames(
+	toolNames: Iterable<string>,
+	toolRegistry: ReadonlyMap<string, AgentTool>,
+	allowedNames?: ReadonlySet<string>,
+	excludedNames?: ReadonlySet<string>,
+): string[] {
+	const selected: string[] = [];
+	for (const name of toolNames) {
+		const tool = toolRegistry.get(name);
+		if (tool?.loadMode !== "discoverable") continue;
+		if (allowedNames && !allowedNames.has(name)) continue;
+		if (excludedNames?.has(name)) continue;
+		if (!selected.includes(name)) selected.push(name);
+	}
+	return selected;
+}
+
 export function isMCPBridgeTool(tool: { name: string; mcpServerName?: unknown; mcpToolName?: unknown }): boolean {
 	return (
 		isMCPToolName(tool.name) &&
@@ -194,6 +172,7 @@ export function getDiscoverableTool(
 	return {
 		name: tool.name,
 		label: typeof toolRecord.label === "string" ? toolRecord.label : tool.name,
+		description: rawDescription,
 		summary,
 		source,
 		serverName: typeof toolRecord.mcpServerName === "string" ? toolRecord.mcpServerName : undefined,
@@ -305,96 +284,3 @@ export function searchDiscoverableTools(
 		.sort((left, right) => right.score - left.score || left.tool.name.localeCompare(right.tool.name))
 		.slice(0, limit);
 }
-
-// ─── Legacy MCP-specific shims (back-compat wrappers) ────────────────────────
-
-/** @deprecated Use getDiscoverableTool */
-export function getDiscoverableMCPTool(tool: AgentTool): DiscoverableMCPTool | null {
-	const toolRecord = tool as AgentTool & {
-		label?: string;
-		description?: string;
-		mcpServerName?: string;
-		mcpToolName?: string;
-		parameters?: unknown;
-	};
-	if (!isMCPBridgeTool(toolRecord)) return null;
-	return {
-		name: tool.name,
-		label: typeof toolRecord.label === "string" ? toolRecord.label : tool.name,
-		description: typeof toolRecord.description === "string" ? toolRecord.description : "",
-		serverName: typeof toolRecord.mcpServerName === "string" ? toolRecord.mcpServerName : undefined,
-		mcpToolName: typeof toolRecord.mcpToolName === "string" ? toolRecord.mcpToolName : undefined,
-		schemaKeys: getSchemaPropertyKeys(toolRecord.parameters),
-	};
-}
-
-/** @deprecated Use collectDiscoverableTools with source filter */
-export function collectDiscoverableMCPTools(tools: Iterable<AgentTool>): DiscoverableMCPTool[] {
-	const discoverable: DiscoverableMCPTool[] = [];
-	for (const tool of tools) {
-		const metadata = getDiscoverableMCPTool(tool);
-		if (metadata) {
-			discoverable.push(metadata);
-		}
-	}
-	return discoverable;
-}
-
-/** @deprecated Use selectDiscoverableToolNamesByServer */
-export function selectDiscoverableMCPToolNamesByServer(
-	tools: Iterable<DiscoverableMCPTool>,
-	serverNames: ReadonlySet<string>,
-): string[] {
-	if (serverNames.size === 0) return [];
-	return Array.from(tools)
-		.filter(tool => tool.serverName !== undefined && serverNames.has(tool.serverName))
-		.map(tool => tool.name);
-}
-
-/** @deprecated Use summarizeDiscoverableTools */
-export function summarizeDiscoverableMCPTools(tools: DiscoverableMCPTool[]): DiscoverableMCPToolSummary {
-	const serverToolCounts = new Map<string, number>();
-	for (const tool of tools) {
-		if (!tool.serverName) continue;
-		serverToolCounts.set(tool.serverName, (serverToolCounts.get(tool.serverName) ?? 0) + 1);
-	}
-	const servers = Array.from(serverToolCounts.entries())
-		.sort(([left], [right]) => left.localeCompare(right))
-		.map(([name, toolCount]) => ({ name, toolCount }));
-	return {
-		servers,
-		toolCount: tools.length,
-	};
-}
-
-/** @deprecated Use buildDiscoverableToolSearchIndex.
- *  Builds an index whose documents preserve the legacy `description` field on each tool while
- *  also carrying the generic `summary` (set from `description`) so the index remains usable
- *  with `searchDiscoverableTools`. */
-export function buildDiscoverableMCPSearchIndex(tools: Iterable<DiscoverableMCPTool>): DiscoverableMCPSearchIndex {
-	const adapted: DiscoverableMCPSearchTool[] = Array.from(tools).map(t => ({
-		name: t.name,
-		label: t.label,
-		description: t.description,
-		summary: t.description,
-		source: "mcp" as DiscoverableToolSource,
-		serverName: t.serverName,
-		mcpToolName: t.mcpToolName,
-		schemaKeys: t.schemaKeys,
-	}));
-	const generic = buildDiscoverableToolSearchIndex(adapted);
-	// Documents reference `adapted` tools (with `description`), so the cast is sound.
-	return generic as unknown as DiscoverableMCPSearchIndex;
-}
-
-/** @deprecated Use searchDiscoverableTools */
-export function searchDiscoverableMCPTools(
-	index: DiscoverableMCPSearchIndex | DiscoverableToolSearchIndex,
-	query: string,
-	limit: number,
-): DiscoverableMCPSearchResult[] {
-	return searchDiscoverableTools(index as DiscoverableToolSearchIndex, query, limit) as DiscoverableMCPSearchResult[];
-}
-
-/** @deprecated Use formatDiscoverableToolServerSummary */
-export const formatDiscoverableMCPToolServerSummary = formatDiscoverableToolServerSummary;

package/src/tools/ask-answer-registry.ts

@@ -7,7 +7,8 @@
  * source; registering returns a disposer.
  */
 
-import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/unattended-session";
+import { logger } from "@sayknow-cli/utils";
+import type { WorkflowGateEmitter } from "../modes/shared/agent-wire/workflow-gate-broker";
 import type { AskAnswerSource } from "./index";
 
 const sources = new Map<string, AskAnswerSource>();
@@ -31,7 +32,20 @@ export function getAskAnswerSource(sessionId: string): AskAnswerSource | undefin
 export function notifyWorkflowGateEmitterChanged(sessionId: string, emitter: WorkflowGateEmitter | undefined): void {
 	if (emitter) workflowGateEmitters.set(sessionId, emitter);
 	else workflowGateEmitters.delete(sessionId);
-	for (const listener of workflowGateListeners.get(sessionId) ?? []) listener(emitter);
+	for (const listener of workflowGateListeners.get(sessionId) ?? []) {
+		// Isolate each listener: a throwing observer must never escape into an
+		// emitter suspend/bind/restore step, which runs inside session-transition
+		// transactions (e.g. handoff) whose rollback/commit correctness depends on
+		// this notification being no-throw.
+		try {
+			listener(emitter);
+		} catch (error) {
+			logger.warn("Workflow-gate emitter listener threw during notification", {
+				sessionId,
+				error: error instanceof Error ? error.message : String(error),
+			});
+		}
+	}
 }
 
 /** Observe workflow-gate emitter installation even when it occurs after session_start. */

package/src/tools/ast-edit.ts

@@ -9,7 +9,7 @@ import type { RenderResultOptions } from "../extensibility/custom-tools/types";
 import { computeLineHash, HL_BODY_SEP } from "../hashline/hash";
 import type { Theme } from "../modes/theme/theme";
 import astEditDescription from "../prompts/tools/ast-edit.md" with { type: "text" };
-import { assertWorkflowMutationRawPathsAllowed } from "../skill-state/deep-interview-mutation-guard";
+import { assertWorkflowMutationRawPathsAllowed } from "../skill-state/workflow-mutation-guard";
 import { Ellipsis, fileHyperlink, renderStatusLine, renderTreeList, truncateToWidth } from "../tui";
 import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import type { ToolSession } from ".";