@oh-my-pi/pi-coding-agent 14.9.9 → 15.0.1

package/src/modes/acp/acp-agent.ts

@@ -4,7 +4,9 @@ import {
 	type AgentSideConnection,
 	type AuthenticateRequest,
 	type AuthenticateResponse,
+	type AuthMethod,
 	type AvailableCommand,
+	type ClientCapabilities,
 	type CloseSessionRequest,
 	type CloseSessionResponse,
 	type ForkSessionRequest,
@@ -37,32 +39,49 @@ import {
 	type SetSessionModeResponse,
 	type Usage,
 } from "@agentclientprotocol/sdk";
-import type { Model } from "@oh-my-pi/pi-ai";
+import type { AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import { logger, VERSION } from "@oh-my-pi/pi-utils";
-import { disableProvider, enableProvider } from "../../capability";
+import { disableProvider, enableProvider, reset as resetCapabilities } from "../../capability";
 import { Settings } from "../../config/settings";
+import { clearPluginRootsAndCaches, resolveActiveProjectRegistryPath } from "../../discovery/helpers";
 import type { ExtensionUIContext } from "../../extensibility/extensions";
 import { runExtensionCompact } from "../../extensibility/extensions/compact-handler";
+import { buildSkillPromptMessage, getSkillSlashCommandName } from "../../extensibility/skills";
 import { loadSlashCommands } from "../../extensibility/slash-commands";
 import { MCPManager } from "../../mcp/manager";
 import type { MCPServerConfig } from "../../mcp/types";
 import { loadAllExtensions } from "../../modes/components/extensions/state-manager";
 import { theme } from "../../modes/theme/theme";
 import type { AgentSession, AgentSessionEvent } from "../../session/agent-session";
+import { isSilentAbort, SKILL_PROMPT_MESSAGE_TYPE } from "../../session/messages";
 import {
 	SessionManager,
 	type SessionInfo as StoredSessionInfo,
 	type UsageStatistics,
 } from "../../session/session-manager";
+import { ACP_BUILTIN_SLASH_COMMANDS, executeAcpBuiltinSlashCommand } from "../../slash-commands/acp-builtins";
 import { parseThinkingLevel } from "../../thinking";
+import { createAcpClientBridge } from "./acp-client-bridge";
 import { mapAgentSessionEventToAcpSessionUpdates, mapToolKind } from "./acp-event-mapper";
+import { ACP_TERMINAL_AUTH_FLAG } from "./terminal-auth";
 
-const ACP_MODE_ID = "default";
+const ACP_DEFAULT_MODE_ID = "default";
+const ACP_PLAN_MODE_ID = "plan";
+const DEFAULT_PLAN_FILE_URL = "local://PLAN.md";
 const MODE_CONFIG_ID = "mode";
 const MODEL_CONFIG_ID = "model";
 const THINKING_CONFIG_ID = "thinking";
 const THINKING_OFF = "off";
 const SESSION_PAGE_SIZE = 50;
+/**
+ * Delay between `session/new` (or `session/load` / `session/resume` /
+ * `unstable_session/fork`) returning and the agent firing the first
+ * notifications against the new session id. Mitigates Zed's
+ * `Received session notification for unknown session` race — see
+ * `#scheduleBootstrapUpdates`. Exported so the ACP test harness can
+ * wait past this guard without hard-coding the literal.
+ */
+export const ACP_BOOTSTRAP_RACE_GUARD_MS = 50;
 
 type AgentImageContent = {
 	type: "image";
@@ -84,8 +103,12 @@ type ManagedSessionRecord = {
 	session: AgentSession;
 	mcpManager: MCPManager | undefined;
 	promptTurn: PromptTurnState | undefined;
-	liveMessageIds: WeakMap<object, string>;
+	liveMessageId: string | undefined;
+	liveMessageProgress: { textEmitted: boolean; thoughtEmitted: boolean } | undefined;
 	extensionsConfigured: boolean;
+	// Installed inside `#scheduleBootstrapUpdates` (post-race-guard); released
+	// in `#disposeSessionRecord`. Lives independent of any prompt turn.
+	lifetimeUnsubscribe: (() => void) | undefined;
 };
 
 type ReplayableMessage = {
@@ -152,6 +175,7 @@ export class AcpAgent implements Agent {
 	#sessions = new Map<string, ManagedSessionRecord>();
 	#disposePromise: Promise<void> | undefined;
 	#cleanupRegistered = false;
+	#clientCapabilities: ClientCapabilities | undefined;
 
 	constructor(connection: AgentSideConnection, initialSession: AgentSession, createSession: CreateAcpSession) {
 		this.#connection = connection;
@@ -159,8 +183,25 @@ export class AcpAgent implements Agent {
 		this.#createSession = createSession;
 	}
 
-	async initialize(_params: InitializeRequest): Promise<InitializeResponse> {
+	async initialize(params: InitializeRequest): Promise<InitializeResponse> {
 		this.#registerConnectionCleanup();
+		this.#clientCapabilities = params.clientCapabilities;
+		const authMethods: AuthMethod[] = [
+			{
+				id: "agent",
+				name: "Use existing local credentials",
+				description: "Authenticate via the provider keys/OAuth state already configured under ~/.omp.",
+			},
+		];
+		if (params.clientCapabilities?.auth?.terminal === true) {
+			authMethods.push({
+				type: "terminal",
+				id: "terminal",
+				name: "Set up Oh My Pi in terminal",
+				description: "Launch the omp TUI to add provider keys and select models.",
+				args: [ACP_TERMINAL_AUTH_FLAG],
+			});
+		}
 		return {
 			protocolVersion: PROTOCOL_VERSION,
 			agentInfo: {
@@ -168,13 +209,7 @@ export class AcpAgent implements Agent {
 				title: "Oh My Pi",
 				version: VERSION,
 			},
-			authMethods: [
-				{
-					id: "agent",
-					name: "Agent-managed authentication",
-					description: "Oh My Pi uses its existing local authentication and provider configuration.",
-				},
-			],
+			authMethods,
 			agentCapabilities: {
 				loadSession: true,
 				mcpCapabilities: {
@@ -195,7 +230,15 @@ export class AcpAgent implements Agent {
 		};
 	}
 
-	async authenticate(_params: AuthenticateRequest): Promise<AuthenticateResponse> {
+	async authenticate(params: AuthenticateRequest): Promise<AuthenticateResponse> {
+		// ACP spec: `methodId` must be one of the methods advertised by `initialize`.
+		// Reject anything else so malformed clients fail fast rather than appearing
+		// authenticated and surfacing a downstream model failure later.
+		const supportsTerminalAuth = this.#clientCapabilities?.auth?.terminal === true;
+		const validMethods = supportsTerminalAuth ? ["agent", "terminal"] : ["agent"];
+		if (!validMethods.includes(params.methodId)) {
+			throw new Error(`Unknown ACP auth method: ${params.methodId}`);
+		}
 		return {};
 	}
 
@@ -206,7 +249,7 @@ export class AcpAgent implements Agent {
 			sessionId: record.session.sessionId,
 			configOptions: this.#buildConfigOptions(record.session),
 			models: this.#buildModelState(record.session),
-			modes: this.#buildModeState(),
+			modes: this.#buildModeState(record.session),
 		};
 		this.#scheduleBootstrapUpdates(record.session.sessionId);
 		return response;
@@ -219,7 +262,7 @@ export class AcpAgent implements Agent {
 		const response: LoadSessionResponse = {
 			configOptions: this.#buildConfigOptions(record.session),
 			models: this.#buildModelState(record.session),
-			modes: this.#buildModeState(),
+			modes: this.#buildModeState(record.session),
 		};
 		this.#scheduleBootstrapUpdates(record.session.sessionId);
 		return response;
@@ -242,13 +285,13 @@ export class AcpAgent implements Agent {
 		};
 	}
 
-	async unstable_resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
+	async resumeSession(params: ResumeSessionRequest): Promise<ResumeSessionResponse> {
 		this.#assertAbsoluteCwd(params.cwd);
 		const record = await this.#resumeManagedSession(params.sessionId, params.cwd, params.mcpServers ?? []);
 		const response: ResumeSessionResponse = {
 			configOptions: this.#buildConfigOptions(record.session),
 			models: this.#buildModelState(record.session),
-			modes: this.#buildModeState(),
+			modes: this.#buildModeState(record.session),
 		};
 		this.#scheduleBootstrapUpdates(record.session.sessionId);
 		return response;
@@ -261,13 +304,13 @@ export class AcpAgent implements Agent {
 			sessionId: record.session.sessionId,
 			configOptions: this.#buildConfigOptions(record.session),
 			models: this.#buildModelState(record.session),
-			modes: this.#buildModeState(),
+			modes: this.#buildModeState(record.session),
 		};
 		this.#scheduleBootstrapUpdates(record.session.sessionId);
 		return response;
 	}
 
-	async unstable_closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
+	async closeSession(params: CloseSessionRequest): Promise<CloseSessionResponse> {
 		const record = this.#sessions.get(params.sessionId);
 		if (!record) {
 			return {};
@@ -278,13 +321,12 @@ export class AcpAgent implements Agent {
 
 	async setSessionMode(params: SetSessionModeRequest): Promise<SetSessionModeResponse> {
 		const record = this.#getSessionRecord(params.sessionId);
-		if (params.modeId !== ACP_MODE_ID) {
-			throw new Error(`Unsupported ACP mode: ${params.modeId}`);
-		}
+		this.#applyModeChange(record.session, params.modeId);
 		await this.#connection.sessionUpdate({
 			sessionId: record.session.sessionId,
-			update: this.#buildCurrentModeUpdate(),
+			update: this.#buildCurrentModeUpdate(record.session),
 		});
+		await this.#pushConfigOptionUpdate(record);
 		return {};
 	}
 
@@ -296,9 +338,7 @@ export class AcpAgent implements Agent {
 
 		switch (params.configId) {
 			case MODE_CONFIG_ID:
-				if (params.value !== ACP_MODE_ID) {
-					throw new Error(`Unsupported ACP mode config value: ${params.value}`);
-				}
+				this.#applyModeChange(record.session, params.value);
 				break;
 			case MODEL_CONFIG_ID:
 				await this.#setModelById(record.session, params.value);
@@ -310,27 +350,31 @@ export class AcpAgent implements Agent {
 				throw new Error(`Unknown ACP config option: ${params.configId}`);
 		}
 
-		const configOptions = this.#buildConfigOptions(record.session);
-		await this.#connection.sessionUpdate({
-			sessionId: record.session.sessionId,
-			update: {
-				sessionUpdate: "config_option_update",
-				configOptions,
-			},
-		});
-		return { configOptions };
+		// When mode is changed via the generic config-option API, mirror the
+		// `current_mode_update` notification that `setSessionMode` emits so
+		// ACP clients tracking session-mode state see a consistent transition.
+		if (params.configId === MODE_CONFIG_ID) {
+			await this.#connection.sessionUpdate({
+				sessionId: record.session.sessionId,
+				update: this.#buildCurrentModeUpdate(record.session),
+			});
+		}
+
+		// For `thinking` the lifetime subscription pushes post-bootstrap; only
+		// push here when it's not yet installed so pre-bootstrap callers still
+		// see the change without a post-bootstrap duplicate.
+		const thinkingHandledBySubscription =
+			params.configId === THINKING_CONFIG_ID && record.lifetimeUnsubscribe !== undefined;
+		if (!thinkingHandledBySubscription) {
+			await this.#pushConfigOptionUpdate(record);
+		}
+		return { configOptions: this.#buildConfigOptions(record.session) };
 	}
 
 	async unstable_setSessionModel(params: SetSessionModelRequest): Promise<SetSessionModelResponse> {
 		const record = this.#getSessionRecord(params.sessionId);
 		await this.#setModelById(record.session, params.modelId);
-		await this.#connection.sessionUpdate({
-			sessionId: record.session.sessionId,
-			update: {
-				sessionUpdate: "config_option_update",
-				configOptions: this.#buildConfigOptions(record.session),
-			},
-		});
+		await this.#pushConfigOptionUpdate(record);
 		return {};
 	}
 
@@ -356,13 +400,88 @@ export class AcpAgent implements Agent {
 			void this.#handlePromptEvent(record, event);
 		});
 
-		record.session.prompt(converted.text, { images: converted.images }).catch((error: unknown) => {
+		this.#runPromptOrCommand(record, converted.text, converted.images).catch((error: unknown) => {
 			this.#finishPrompt(record, undefined, error);
 		});
 
 		return await pendingPrompt.promise;
 	}
 
+	async #runPromptOrCommand(record: ManagedSessionRecord, text: string, images: AgentImageContent[]): Promise<void> {
+		const skillResult = await this.#tryRunSkillCommand(record, text);
+		if (skillResult) {
+			return;
+		}
+
+		const builtinResult = await executeAcpBuiltinSlashCommand(text, {
+			session: record.session,
+			sessionManager: record.session.sessionManager,
+			settings: Settings.instance,
+			cwd: record.session.sessionManager.getCwd(),
+			output: output => this.#emitCommandOutput(record, output),
+			refreshCommands: () => this.#emitAvailableCommandsUpdate(record),
+			reloadPlugins: () => this.#reloadPluginState(record),
+			notifyTitleChanged: async () => {
+				await this.#connection.sessionUpdate({
+					sessionId: record.session.sessionId,
+					update: {
+						sessionUpdate: "session_info_update",
+						title: record.session.sessionName,
+						updatedAt: new Date().toISOString(),
+					},
+				});
+			},
+			notifyConfigChanged: async () => {
+				await this.#pushConfigOptionUpdate(record);
+			},
+		});
+		if (builtinResult !== false) {
+			if ("prompt" in builtinResult) {
+				await record.session.prompt(builtinResult.prompt, { images });
+				return;
+			}
+			const promptTurn = record.promptTurn;
+			this.#finishPrompt(record, {
+				stopReason: "end_turn",
+				usage: this.#buildTurnUsage(
+					promptTurn?.usageBaseline ??
+						this.#cloneUsageStatistics(record.session.sessionManager.getUsageStatistics()),
+					record.session.sessionManager.getUsageStatistics(),
+				),
+				userMessageId: promptTurn?.userMessageId,
+			});
+			return;
+		}
+
+		await record.session.prompt(text, { images });
+	}
+
+	async #tryRunSkillCommand(record: ManagedSessionRecord, text: string): Promise<boolean> {
+		if (!text.startsWith("/skill:")) {
+			return false;
+		}
+		if (!record.session.skillsSettings?.enableSkillCommands) {
+			return false;
+		}
+		const spaceIndex = text.indexOf(" ");
+		const commandName = spaceIndex === -1 ? text.slice(1) : text.slice(1, spaceIndex);
+		const args = spaceIndex === -1 ? "" : text.slice(spaceIndex + 1).trim();
+		const skillName = commandName.slice("skill:".length);
+		const skill = record.session.skills.find(candidate => candidate.name === skillName);
+		if (!skill) {
+			return false;
+		}
+		const built = await buildSkillPromptMessage(skill, args);
+		await record.session.promptCustomMessage({
+			customType: SKILL_PROMPT_MESSAGE_TYPE,
+			content: built.message,
+			display: true,
+			details: built.details,
+			attribution: "user",
+		});
+		return true;
+	}
+
 	async cancel(params: { sessionId: string }): Promise<void> {
 		const record = this.#getSessionRecord(params.sessionId);
 		const promptTurn = record.promptTurn;
@@ -384,7 +503,7 @@ export class AcpAgent implements Agent {
 
 	async extMethod(method: string, params: { [key: string]: unknown }): Promise<{ [key: string]: unknown }> {
 		switch (method) {
-			case "omp/sessions/listAll": {
+			case "_omp/sessions/listAll": {
 				const limit = typeof params.limit === "number" ? Math.max(1, Math.min(5000, params.limit as number)) : 1000;
 				const sessions = await SessionManager.listAll();
 				const sorted = sessions.sort((l, r) => r.modified.getTime() - l.modified.getTime()).slice(0, limit);
@@ -393,7 +512,7 @@ export class AcpAgent implements Agent {
 					total: sessions.length,
 				};
 			}
-			case "omp/projects/list": {
+			case "_omp/projects/list": {
 				const sessions = await SessionManager.listAll();
 				const buckets = new Map<
 					string,
@@ -421,7 +540,7 @@ export class AcpAgent implements Agent {
 				const projects = Array.from(buckets.values()).sort((a, b) => b.lastActivityAt - a.lastActivityAt);
 				return { projects, totalSessions: sessions.length };
 			}
-			case "omp/chats/byCwd": {
+			case "_omp/chats/byCwd": {
 				const cwd = typeof params.cwd === "string" ? (params.cwd as string) : undefined;
 				if (!cwd) throw new Error("cwd required");
 				const limit = typeof params.limit === "number" ? Math.max(1, Math.min(500, params.limit as number)) : 100;
@@ -429,20 +548,20 @@ export class AcpAgent implements Agent {
 				const sorted = sessions.sort((l, r) => r.modified.getTime() - l.modified.getTime()).slice(0, limit);
 				return { sessions: sorted.map(s => this.#toSessionInfo(s)) };
 			}
-			case "omp/usage": {
+			case "_omp/usage": {
 				const [firstRecord] = this.#sessions.values();
 				const target = firstRecord?.session ?? this.#initialSession;
 				const reports = await target.fetchUsageReports();
 				return { reports: reports ?? [] };
 			}
-			case "omp/extensions": {
+			case "_omp/extensions": {
 				const cwd = typeof params.cwd === "string" ? (params.cwd as string) : undefined;
 				const sm = await Settings.init();
 				const disabledIds = (sm.get("disabledExtensions") as string[] | undefined) ?? [];
 				const extensions = await loadAllExtensions(cwd, disabledIds);
 				return { extensions: extensions as unknown as Array<{ [key: string]: unknown }> };
 			}
-			case "omp/extensions/toggle": {
+			case "_omp/extensions/toggle": {
 				const providerId = params.providerId;
 				if (typeof providerId !== "string") throw new Error("providerId required");
 				if (params.enabled === false) {
@@ -562,6 +681,9 @@ export class AcpAgent implements Agent {
 
 	async #registerPreparedSession(session: AgentSession, mcpServers: McpServer[]): Promise<ManagedSessionRecord> {
 		const record = this.#createManagedSessionRecord(session);
+		session.setClientBridge(createAcpClientBridge(this.#connection, session.sessionId, this.#clientCapabilities));
+		// `record.lifetimeUnsubscribe` is installed in `#scheduleBootstrapUpdates`
+		// so it shares the bootstrap race guard — see that comment for why.
 		try {
 			await this.#configureExtensions(record);
 			await this.#configureMcpServers(record, mcpServers);
@@ -578,11 +700,27 @@ export class AcpAgent implements Agent {
 			session,
 			mcpManager: undefined,
 			promptTurn: undefined,
-			liveMessageIds: new WeakMap<object, string>(),
+			liveMessageId: undefined,
+			liveMessageProgress: undefined,
 			extensionsConfigured: false,
+			lifetimeUnsubscribe: undefined,
 		};
 	}
 
+	async #handleLifetimeEvent(record: ManagedSessionRecord, event: AgentSessionEvent): Promise<void> {
+		if (event.type !== "thinking_level_changed") {
+			return;
+		}
+		try {
+			await this.#pushConfigOptionUpdate(record);
+		} catch (error) {
+			logger.warn("Failed to push thinking-level config_option_update", {
+				sessionId: record.session.sessionId,
+				error,
+			});
+		}
+	}
+
 	#getSessionRecord(sessionId: string): ManagedSessionRecord {
 		const record = this.#sessions.get(sessionId);
 		if (!record) {
@@ -627,33 +765,61 @@ export class AcpAgent implements Agent {
 			return;
 		}
 
+		this.#prepareLiveAssistantMessage(record, event);
 		for (const notification of mapAgentSessionEventToAcpSessionUpdates(event, record.session.sessionId, {
 			getMessageId: message => this.#getLiveMessageId(record, message),
+			getMessageProgress: message => this.#getLiveMessageProgress(record, message),
+			cwd: record.session.sessionManager.getCwd(),
 		})) {
 			await this.#connection.sessionUpdate(notification);
 		}
+		this.#clearLiveAssistantMessageAfterEvent(record, event);
 
 		if (event.type === "agent_end") {
 			await this.#emitEndOfTurnUpdates(record);
 			this.#finishPrompt(record, {
-				stopReason: promptTurn.cancelRequested ? "cancelled" : "end_turn",
+				stopReason: this.#resolveStopReason(event, promptTurn.cancelRequested),
 				usage: this.#buildTurnUsage(promptTurn.usageBaseline, record.session.sessionManager.getUsageStatistics()),
 				userMessageId: promptTurn.userMessageId,
 			});
 		}
 	}
 
+	#prepareLiveAssistantMessage(record: ManagedSessionRecord, event: AgentSessionEvent): void {
+		if (
+			(event.type === "message_start" || event.type === "message_update" || event.type === "message_end") &&
+			event.message.role === "assistant" &&
+			(event.type === "message_start" || !record.liveMessageId || !record.liveMessageProgress)
+		) {
+			record.liveMessageId = crypto.randomUUID();
+			record.liveMessageProgress = { textEmitted: false, thoughtEmitted: false };
+		}
+	}
+
+	#clearLiveAssistantMessageAfterEvent(record: ManagedSessionRecord, event: AgentSessionEvent): void {
+		if ((event.type === "message_end" && event.message.role === "assistant") || event.type === "agent_end") {
+			record.liveMessageId = undefined;
+			record.liveMessageProgress = undefined;
+		}
+	}
+
 	#getLiveMessageId(record: ManagedSessionRecord, message: unknown): string | undefined {
 		if (typeof message !== "object" || message === null) {
 			return undefined;
 		}
-		const existing = record.liveMessageIds.get(message);
-		if (existing) {
-			return existing;
+		record.liveMessageId ??= crypto.randomUUID();
+		return record.liveMessageId;
+	}
+
+	#getLiveMessageProgress(
+		record: ManagedSessionRecord,
+		message: unknown,
+	): { textEmitted: boolean; thoughtEmitted: boolean } | undefined {
+		if (typeof message !== "object" || message === null) {
+			return undefined;
 		}
-		const nextMessageId = crypto.randomUUID();
-		record.liveMessageIds.set(message, nextMessageId);
-		return nextMessageId;
+		record.liveMessageProgress ??= { textEmitted: false, thoughtEmitted: false };
+		return record.liveMessageProgress;
 	}
 
 	#finishPrompt(record: ManagedSessionRecord, response?: PromptResponse, error?: unknown): void {
@@ -671,6 +837,48 @@ export class AcpAgent implements Agent {
 		promptTurn.resolve(response ?? { stopReason: "end_turn" });
 	}
 
+	#resolveStopReason(
+		event: Extract<AgentSessionEvent, { type: "agent_end" }>,
+		cancelRequested: boolean,
+	): PromptResponse["stopReason"] {
+		if (cancelRequested) {
+			return "cancelled";
+		}
+		const lastAssistant = [...event.messages]
+			.reverse()
+			.find((message): message is AssistantMessage => message.role === "assistant");
+		const reason = lastAssistant?.stopReason;
+		switch (reason) {
+			case "aborted":
+				return "cancelled";
+			case "length":
+				return "max_tokens";
+			case "error": {
+				const errorMessage = lastAssistant?.errorMessage ?? "";
+				if (/content[_ ]?filter|refus(al|ed)/i.test(errorMessage)) {
+					return "refusal";
+				}
+				return "end_turn";
+			}
+			default:
+				return "end_turn";
+		}
+	}
+
+	async #emitCommandOutput(record: ManagedSessionRecord, text: string): Promise<void> {
+		if (!text) {
+			return;
+		}
+		await this.#connection.sessionUpdate({
+			sessionId: record.session.sessionId,
+			update: {
+				sessionUpdate: "agent_message_chunk",
+				content: { type: "text", text },
+				messageId: crypto.randomUUID(),
+			},
+		});
+	}
+
 	#assertAbsoluteCwd(cwd: string): void {
 		if (!path.isAbsolute(cwd)) {
 			throw new Error(`ACP cwd must be absolute: ${cwd}`);
@@ -691,6 +899,12 @@ export class AcpAgent implements Agent {
 				case "resource":
 					if ("text" in block.resource) {
 						textParts.push(block.resource.text);
+					} else if (typeof block.resource.mimeType === "string" && block.resource.mimeType.startsWith("image/")) {
+						// `embeddedContext: true` covers both text and blob resources, but
+						// blobs aren't directly consumable by the LLM. Route image blobs
+						// to the images array so the user's intent survives; everything
+						// else falls back to the URI placeholder below.
+						images.push({ type: "image", data: block.resource.blob, mimeType: block.resource.mimeType });
 					} else {
 						textParts.push(`[embedded resource: ${block.resource.uri}]`);
 					}
@@ -709,15 +923,31 @@ export class AcpAgent implements Agent {
 		};
 	}
 
+	async #pushConfigOptionUpdate(record: ManagedSessionRecord): Promise<void> {
+		await this.#connection.sessionUpdate({
+			sessionId: record.session.sessionId,
+			update: {
+				sessionUpdate: "config_option_update",
+				configOptions: this.#buildConfigOptions(record.session),
+			},
+		});
+	}
+
 	#buildConfigOptions(session: AgentSession): SessionConfigOption[] {
+		const currentModeId = this.#getCurrentModeId(session);
+		const modeOptions = this.#getAvailableModes(session).map(mode => ({
+			value: mode.id,
+			name: mode.name,
+			description: mode.description,
+		}));
 		const configOptions: SessionConfigOption[] = [
 			{
 				id: MODE_CONFIG_ID,
 				name: "Mode",
 				category: "mode",
 				type: "select",
-				currentValue: ACP_MODE_ID,
-				options: [{ value: ACP_MODE_ID, name: "Default", description: "Standard ACP headless mode" }],
+				currentValue: currentModeId,
+				options: modeOptions,
 			},
 		];
 
@@ -805,17 +1035,52 @@ export class AcpAgent implements Agent {
 		return `${model.provider}/${model.id}`;
 	}
 
-	#buildModeState(): SessionModeState {
+	#getAvailableModes(session: AgentSession): Array<{ id: string; name: string; description: string }> {
+		const modes = [{ id: ACP_DEFAULT_MODE_ID, name: "Default", description: "Standard ACP headless mode" }];
+		if (Settings.instance.get("plan.enabled")) {
+			modes.push({
+				id: ACP_PLAN_MODE_ID,
+				name: "Plan",
+				description: "Read-only planning mode that drafts a plan to a markdown file before any code changes",
+			});
+		}
+		void session;
+		return modes;
+	}
+
+	#getCurrentModeId(session: AgentSession): string {
+		return session.getPlanModeState()?.enabled ? ACP_PLAN_MODE_ID : ACP_DEFAULT_MODE_ID;
+	}
+
+	#applyModeChange(session: AgentSession, modeId: string): void {
+		const availableModes = this.#getAvailableModes(session);
+		if (!availableModes.some(mode => mode.id === modeId)) {
+			throw new Error(`Unsupported ACP mode: ${modeId}`);
+		}
+		if (modeId === ACP_PLAN_MODE_ID) {
+			const previous = session.getPlanModeState();
+			session.setPlanModeState({
+				enabled: true,
+				planFilePath: previous?.planFilePath ?? DEFAULT_PLAN_FILE_URL,
+				workflow: previous?.workflow ?? "parallel",
+				reentry: previous !== undefined,
+			});
+		} else {
+			session.setPlanModeState(undefined);
+		}
+	}
+
+	#buildModeState(session: AgentSession): SessionModeState {
 		return {
-			availableModes: [{ id: ACP_MODE_ID, name: "Default", description: "Standard ACP headless mode" }],
-			currentModeId: ACP_MODE_ID,
+			availableModes: this.#getAvailableModes(session),
+			currentModeId: this.#getCurrentModeId(session),
 		};
 	}
 
-	#buildCurrentModeUpdate(): SessionUpdate {
+	#buildCurrentModeUpdate(session: AgentSession): SessionUpdate {
 		return {
 			sessionUpdate: "current_mode_update",
-			currentModeId: ACP_MODE_ID,
+			currentModeId: this.#getCurrentModeId(session),
 		};
 	}
 
@@ -830,6 +1095,24 @@ export class AcpAgent implements Agent {
 			commands.push(command);
 		};
 
+		// Advertise in the order dispatch resolves them: ACP builtins first
+		// (so core commands like `/model`, `/mcp`, `/todo` cannot be shadowed),
+		// then skills, then custom/user commands, then file-based slash
+		// commands. `appendCommand` dedupes by name so earlier entries win.
+		for (const command of ACP_BUILTIN_SLASH_COMMANDS) {
+			appendCommand(command);
+		}
+
+		if (session.skillsSettings?.enableSkillCommands) {
+			for (const skill of session.skills) {
+				appendCommand({
+					name: getSkillSlashCommandName(skill),
+					description: skill.description || `Run ${skill.name} skill`,
+					input: { hint: "arguments" },
+				});
+			}
+		}
+
 		for (const command of session.customCommands) {
 			appendCommand({
 				name: command.command.name,
@@ -854,10 +1137,33 @@ export class AcpAgent implements Agent {
 			cwd: session.cwd,
 			title: session.title,
 			updatedAt: session.modified.toISOString(),
+			_meta: {
+				messageCount: session.messageCount,
+				size: session.size,
+			},
 		};
 	}
 
 	#scheduleBootstrapUpdates(sessionId: string): void {
+		// Defer first notifications until the response has reached the client.
+		// Zed's agent-client-protocol reader dispatches responses and
+		// notifications to different async tasks; sending the first
+		// `available_commands_update` from `setTimeout(0)` reliably loses the
+		// race against the response handler and Zed logs `Received session
+		// notification for unknown session` then drops the update — leaving
+		// the slash-command palette empty (#1015 follow-up; see
+		// zed-industries/zed#55965 for the same race biting other ACP agents).
+		// `ACP_BOOTSTRAP_RACE_GUARD_MS` is invisible to the operator and large
+		// enough that the response future has scheduled before our timer fires
+		// on stdio-only transports.
+		//
+		// The session-lifetime subscription is installed inside the same timer
+		// so it shares this guard — without it, an extension's `session_start`
+		// handler (or any async work it schedules) calling `setThinkingLevel`
+		// would push a `config_option_update` for a session id the client
+		// hasn't been told about yet. The pre-bootstrap thinking level is
+		// reported in the response's `configOptions`, so deferring the
+		// notification loses no state.
 		setTimeout(() => {
 			if (this.#connection.signal.aborted) {
 				return;
@@ -866,8 +1172,13 @@ export class AcpAgent implements Agent {
 			if (!record) {
 				return;
 			}
+			if (!record.lifetimeUnsubscribe) {
+				record.lifetimeUnsubscribe = record.session.subscribe(event => {
+					void this.#handleLifetimeEvent(record, event);
+				});
+			}
 			void this.#emitBootstrapUpdates(sessionId, record);
-		}, 0);
+		}, ACP_BOOTSTRAP_RACE_GUARD_MS);
 	}
 
 	async #emitBootstrapUpdates(sessionId: string, record: ManagedSessionRecord): Promise<void> {
@@ -891,6 +1202,33 @@ export class AcpAgent implements Agent {
 		});
 	}
 
+	async #emitAvailableCommandsUpdate(record: ManagedSessionRecord): Promise<void> {
+		await this.#connection.sessionUpdate({
+			sessionId: record.session.sessionId,
+			update: {
+				sessionUpdate: "available_commands_update",
+				availableCommands: await this.#buildAvailableCommands(record.session),
+			},
+		});
+	}
+
+	/**
+	 * Reload plugin/registry state for an ACP session. Mirrors the interactive
+	 * `/reload-plugins` and `/move` flows: invalidates the plugin-roots cache,
+	 * resets the capability cache, refreshes the session's slash-command state,
+	 * then re-advertises commands so the client sees newly installed/disabled
+	 * plugins.
+	 */
+	async #reloadPluginState(record: ManagedSessionRecord): Promise<void> {
+		const cwd = record.session.sessionManager.getCwd();
+		const projectPath = await resolveActiveProjectRegistryPath(cwd);
+		clearPluginRootsAndCaches(projectPath ? [projectPath] : undefined);
+		resetCapabilities();
+		const fileCommands = await loadSlashCommands({ cwd });
+		record.session.setSlashCommands(fileCommands);
+		await this.#emitAvailableCommandsUpdate(record);
+	}
+
 	async #emitEndOfTurnUpdates(record: ManagedSessionRecord): Promise<void> {
 		const sessionId = record.session.sessionId;
 
@@ -981,14 +1319,15 @@ export class AcpAgent implements Agent {
 	}
 
 	async #replaySessionHistory(record: ManagedSessionRecord): Promise<void> {
+		const cwd = record.session.sessionManager.getCwd();
 		for (const message of record.session.sessionManager.buildSessionContext().messages as ReplayableMessage[]) {
-			for (const notification of this.#messageToReplayNotifications(record.session.sessionId, message)) {
+			for (const notification of this.#messageToReplayNotifications(record.session.sessionId, message, cwd)) {
 				await this.#connection.sessionUpdate(notification);
 			}
 		}
 	}
 
-	#messageToReplayNotifications(sessionId: string, message: ReplayableMessage): SessionNotification[] {
+	#messageToReplayNotifications(sessionId: string, message: ReplayableMessage, cwd: string): SessionNotification[] {
 		if (message.role === "assistant") {
 			return this.#replayAssistantMessage(sessionId, message);
 		}
@@ -1010,7 +1349,7 @@ export class AcpAgent implements Agent {
 			typeof message.toolCallId === "string" &&
 			typeof message.toolName === "string"
 		) {
-			return this.#replayToolResult(sessionId, {
+			return this.#replayToolResult(sessionId, cwd, {
 				...message,
 				toolCallId: message.toolCallId,
 				toolName: message.toolName,
@@ -1087,7 +1426,7 @@ export class AcpAgent implements Agent {
 				}
 			}
 		}
-		if (notifications.length === 0 && message.errorMessage) {
+		if (notifications.length === 0 && message.errorMessage && !isSilentAbort(message.errorMessage)) {
 			notifications.push({
 				sessionId,
 				update: {
@@ -1102,6 +1441,7 @@ export class AcpAgent implements Agent {
 
 	#replayToolResult(
 		sessionId: string,
+		cwd: string,
 		message: Required<Pick<ReplayableMessage, "toolCallId" | "toolName">> & ReplayableMessage,
 	): SessionNotification[] {
 		const args = this.#buildReplayToolArgs(message.details);
@@ -1123,8 +1463,8 @@ export class AcpAgent implements Agent {
 			},
 		};
 		return [
-			...mapAgentSessionEventToAcpSessionUpdates(startEvent, sessionId),
-			...mapAgentSessionEventToAcpSessionUpdates(endEvent, sessionId),
+			...mapAgentSessionEventToAcpSessionUpdates(startEvent, sessionId, { cwd }),
+			...mapAgentSessionEventToAcpSessionUpdates(endEvent, sessionId, { cwd }),
 		];
 	}
 
@@ -1367,6 +1707,7 @@ export class AcpAgent implements Agent {
 	}
 
 	async #disposeSessionRecord(record: ManagedSessionRecord): Promise<void> {
+		record.lifetimeUnsubscribe?.();
 		if (record.mcpManager) {
 			try {
 				await record.mcpManager.disconnectAll();