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

package/src/prompts/tools/search.md

@@ -17,8 +17,8 @@ Searches files using powerful regex matching.
 </output>
 
 <critical>
-- You **MUST** use the built-in `search` tool for any content search. Do **NOT** shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
+- You MUST use the built-in `search` tool for any content search. NEVER shell out to `grep`, `rg`, `ripgrep`, `ag`, `ack`, `git grep`, `awk`, `sed`-for-search, or any other CLI search via Bash — even for a single match, even "just to check quickly", even piped through other commands.
 - Bash `grep`/`rg` loses `.gitignore` semantics, bypasses result limits, and wastes tokens. The `search` tool is faster, structured, and already wired into the workspace — there is no scenario where Bash search is preferable.
 - If you catch yourself typing `grep`, `rg`, or `| grep` in a Bash command, stop and re-issue the lookup through the `search` tool instead.
-- If the search is open-ended, requiring multiple rounds, you **MUST** use the Task tool with the explore subagent instead of chaining `search` calls yourself.
+- If the search is open-ended, requiring multiple rounds, you MUST use the Task tool with the explore subagent instead of chaining `search` calls yourself.
 </critical>

package/src/prompts/tools/ssh.md

@@ -1,7 +1,7 @@
 Runs commands on remote hosts.
 
 <instruction>
-You **MUST** build commands from the reference below
+You MUST build commands from the reference below
 </instruction>
 
 <commands>
@@ -22,7 +22,7 @@ You **MUST** build commands from the reference below
 </commands>
 
 <critical>
-You **MUST** verify the shell type from "Available hosts" and use matching commands.
+You MUST verify the shell type from "Available hosts" and use matching commands.
 </critical>
 
 <examples>

package/src/prompts/tools/task.md

@@ -2,14 +2,20 @@ Launches subagents to parallelize workflows.
 
 {{#if asyncEnabled}}
 - Results are delivered automatically when complete.
-- If genuinely blocked on task completion, wait with `job` using `poll`; otherwise continue with another task when possible.
-- Call `job` with `list: true` to snapshot manager state; pass `poll: [id]` to wait or `cancel: [id]` to stop \u2014 only when inspection or intervention is useful.
+- The tool result lists the assigned task ids (e.g. `0-AuthLoader`) — those are the live agent ids.
+{{#if ircEnabled}}
+- Coordinate with running tasks via `irc` using those ids. `job cancel` terminates a task and **cannot carry a message** — only use it for stalled/abandoned work.
+- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
+{{else}}
+- If genuinely blocked on completion, wait with `job poll`; otherwise keep working.
+- Use `job list` to snapshot manager state; `cancel: [id]` only to actually stop a stuck task.
+{{/if}}
 {{/if}}
 
 {{#if ircEnabled}}
 Subagents have no conversation history, but they can reach you and their siblings live via the `irc` tool. Front-load every fact, file path, and direction they need in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
 {{else}}
-Subagents have no conversation history. Every fact, file path, and direction they need **MUST** be explicit in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
+Subagents have no conversation history. Every fact, file path, and direction they need MUST be explicit in {{#if contextEnabled}}`context` or `assignment`{{else}}each `assignment`{{/if}}.
 {{/if}}
 
 <parameters>
@@ -24,8 +30,8 @@ Subagents have no conversation history. Every fact, file path, and direction the
 </parameters>
 
 <rules>
-- **MUST NOT** assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
-- **Subagents do not verify, lint, or format.** Every assignment **MUST** instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
+- NEVER assign tasks to run project-wide build/test/lint. Caller verifies after the batch.
+- **Subagents do not verify, lint, or format.** Every assignment MUST instruct the subagent to skip all gates and formatters. You run them once at the end across the union of changed files — avoids redundant runs and racing formatter passes.
 {{#if ircEnabled}}
 - Each task: ≤3–5 explicit files. Overlapping file sets are tolerable when peers can coordinate via `irc`, but still fan out to a cluster when the scopes are cleanly separable.
 - No globs, no "update all", no package-wide scope.
@@ -52,7 +58,7 @@ Parallel when tasks touch disjoint files or are independent refactors/tests.
 {{#if contextEnabled}}
 <context-fmt>
 # Goal         ← one sentence: what the batch accomplishes
-# Constraints  ← **MUST**/**MUST NOT** rules and session decisions
+# Constraints  ← MUST/NEVER rules and session decisions
 # Contract     ← exact types/signatures if tasks share an interface
 </context-fmt>
 {{/if}}

package/src/prompts/tools/web-search.md

@@ -1,8 +1,8 @@
 Searches the web for up-to-date information beyond Claude's knowledge cutoff.
 
 <instruction>
-- You **SHOULD** prefer primary sources (papers, official docs) and corroborate key claims with multiple sources
-- You **MUST** include links for cited sources in the final response
+- You SHOULD prefer primary sources (papers, official docs) and corroborate key claims with multiple sources
+- You MUST include links for cited sources in the final response
 </instruction>
 
 <caution>

package/src/prompts/tools/write.md

@@ -8,7 +8,7 @@ Creates or overwrites file at specified path.
 </conditions>
 
 <critical>
-- You **SHOULD** use Edit tool for modifying existing files (more precise, preserves formatting)
-- You **MUST NOT** create documentation files (*.md, README) unless explicitly requested
-- You **MUST NOT** use emojis unless requested
+- You SHOULD use Edit tool for modifying existing files (more precise, preserves formatting)
+- You NEVER create documentation files (*.md, README) unless explicitly requested
+- You NEVER use emojis unless requested
 </critical>

package/src/sdk.ts

@@ -6,7 +6,7 @@ import {
 	INTENT_FIELD,
 	type ThinkingLevel,
 } from "@oh-my-pi/pi-agent-core";
-import type { Message, Model, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
+import type { CredentialDisabledEvent, Message, Model, SimpleStreamOptions } from "@oh-my-pi/pi-ai";
 import {
 	getOpenAICodexTransportDetails,
 	prewarmOpenAICodexResponses,
@@ -29,7 +29,13 @@ import { createAutoresearchExtension } from "./autoresearch";
 import { loadCapability } from "./capability";
 import { type Rule, ruleCapability, setActiveRules } from "./capability/rule";
 import { ModelRegistry } from "./config/model-registry";
-import { formatModelString, parseModelPattern, parseModelString, resolveModelRoleValue } from "./config/model-resolver";
+import {
+	formatModelString,
+	parseModelPattern,
+	parseModelString,
+	resolveAllowedModels,
+	resolveModelRoleValue,
+} from "./config/model-resolver";
 import { loadPromptTemplates as loadPromptTemplatesInternal, type PromptTemplate } from "./config/prompt-templates";
 import { Settings, type SkillsSettings } from "./config/settings";
 import { CursorExecHandlers } from "./cursor";
@@ -670,10 +676,32 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	registerSshCleanup();
 	registerPythonCleanup();
 
-	// Use provided or create AuthStorage and ModelRegistry
-	const authStorage = options.authStorage ?? (await logger.time("discoverModels", discoverAuthStorage, agentDir));
-	const modelRegistry = options.modelRegistry ?? new ModelRegistry(authStorage);
-
+	// Pin authStorage to modelRegistry.authStorage: ModelRegistry.getApiKey() routes refresh
+	// failures through that instance, so any divergent storage handed to the bridge / mcpManager
+	// / session would silently miss credential_disabled events.
+	const modelRegistry =
+		options.modelRegistry ??
+		new ModelRegistry(options.authStorage ?? (await logger.time("discoverModels", discoverAuthStorage, agentDir)));
+	const authStorage = modelRegistry.authStorage;
+	if (options.authStorage && options.authStorage !== authStorage) {
+		throw new Error(
+			"options.authStorage and options.modelRegistry.authStorage must be the same instance when both are provided",
+		);
+	}
+	// Subscribe before any getApiKey() call so startup model probes can't fire a
+	// credential_disabled event past us. An embedder's constructor handler makes the
+	// listener set non-empty from construction, which defeats AuthStorage's no-listener
+	// buffer — so we can't rely on it to catch startup events for the extension runner.
+	const startupCredentialDisabledEvents: CredentialDisabledEvent[] = [];
+	let credentialDisabledTarget: ExtensionRunner | undefined;
+	let unsubscribeCredentialDisabled: (() => void) | undefined = authStorage.onCredentialDisabled(event => {
+		if (credentialDisabledTarget) {
+			// Discard return: any handler error is routed through runner.onError listeners.
+			void credentialDisabledTarget.emitCredentialDisabled(event);
+		} else {
+			startupCredentialDisabledEvents.push(event);
+		}
+	});
 	const settings = options.settings ?? (await logger.time("settings", Settings.init, { cwd, agentDir }));
 	logger.time("initializeWithSettings", initializeWithSettings, settings);
 	if (!options.modelRegistry) {
@@ -778,8 +806,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 	const modelMatchPreferences = {
 		usageOrder: settings.getStorage()?.getModelUsageOrder(),
 	};
+	const allowedModels = await logger.time("resolveAllowedModels", () =>
+		resolveAllowedModels(modelRegistry, settings, modelMatchPreferences),
+	);
 	const defaultRoleSpec = logger.time("resolveDefaultModelRole", () =>
-		resolveModelRoleValue(settings.getModelRole("default"), modelRegistry.getAvailable(), {
+		resolveModelRoleValue(settings.getModelRole("default"), allowedModels, {
 			settings,
 			matchPreferences: modelMatchPreferences,
 			modelRegistry,
@@ -1014,6 +1045,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			getModelString: () => (hasExplicitModel && model ? formatModelString(model) : undefined),
 			getActiveModelString,
 			getPlanModeState: () => session.getPlanModeState(),
+			getClientBridge: () => session?.clientBridge,
 			getCompactContext: () => session.formatCompactContext(),
 			getTodoPhases: () => session.getTodoPhases(),
 			setTodoPhases: phases => session.setTodoPhases(phases),
@@ -1236,11 +1268,14 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			}
 		}
 
-		// Fall back to first available model with a valid API key.
-		// Skip fallback if the user explicitly requested a model via --model that wasn't found.
+		// Fall back to first available model with a valid API key, honoring the
+		// path-scoped `enabledModels` allow-list when configured. Skip when the
+		// user explicitly requested a model via --model that wasn't found.
 		if (!model && !options.modelPattern) {
-			const allModels = modelRegistry.getAll();
-			for (const candidate of allModels) {
+			// Re-resolve the allowed set: extension factories above may have
+			// registered providers/models that weren't visible at startup.
+			const fallbackCandidates = await resolveAllowedModels(modelRegistry, settings, modelMatchPreferences);
+			for (const candidate of fallbackCandidates) {
 				if (await hasModelApiKey(candidate)) {
 					model = candidate;
 					break;
@@ -1251,8 +1286,11 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					modelFallbackMessage += `. Using ${model.provider}/${model.id}`;
 				}
 			} else {
+				const patterns = settings.get("enabledModels");
 				modelFallbackMessage =
-					"No models available. Use /login or set an API key environment variable. Then use /model to select a model.";
+					patterns && patterns.length > 0
+						? `No model available matching enabledModels (${patterns.join(", ")}) with usable credentials. Configure auth for an allowed provider or adjust enabledModels.`
+						: "No models available. Use /login or set an API key environment variable. Then use /model to select a model.";
 			}
 		}
 
@@ -1277,6 +1315,20 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			);
 		}
 
+		if (extensionRunner) {
+			credentialDisabledTarget = extensionRunner;
+			for (const event of startupCredentialDisabledEvents.splice(0)) {
+				// Discard return: any handler error is routed through runner.onError listeners.
+				void extensionRunner.emitCredentialDisabled(event);
+			}
+		} else {
+			// No runner to forward to; release our subscription. The embedder's own
+			// onCredentialDisabled (if any) keeps firing through its own subscription.
+			startupCredentialDisabledEvents.length = 0;
+			unsubscribeCredentialDisabled?.();
+			unsubscribeCredentialDisabled = undefined;
+		}
+
 		const getSessionContext = () => ({
 			sessionManager,
 			modelRegistry,
@@ -1766,6 +1818,7 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 					await originalDispose();
 				} finally {
 					agentRegistry.unregister(resolvedAgentId);
+					unsubscribeCredentialDisabled?.();
 				}
 			};
 		}
@@ -1901,6 +1954,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			eventBus,
 		};
 	} catch (error) {
+		// Release the subscription if the throw happened after install but before the
+		// dispose-wrap took ownership. Idempotent with dispose() — Set.delete is a no-op
+		// for already-removed listeners.
+		unsubscribeCredentialDisabled?.();
 		try {
 			if (hasSession) {
 				await session.dispose();

package/src/session/agent-session.ts

@@ -143,7 +143,7 @@ import { outputMeta } from "../tools/output-meta";
 import { normalizeLocalScheme, resolveToCwd } from "../tools/path-utils";
 import { isAutoQaEnabled } from "../tools/report-tool-issue";
 import { getLatestTodoPhasesFromEntries, type TodoItem, type TodoPhase } from "../tools/todo-write";
-import { ToolError } from "../tools/tool-errors";
+import { ToolAbortError, ToolError } from "../tools/tool-errors";
 import { clampTimeout } from "../tools/tool-timeouts";
 import { parseCommandArgs } from "../utils/command-args";
 import { type EditMode, resolveEditMode } from "../utils/edit-mode";
@@ -151,7 +151,9 @@ import { resolveFileDisplayMode } from "../utils/file-display-mode";
 import { extractFileMentions, generateFileMentionMessages } from "../utils/file-mentions";
 import { buildNamedToolChoice } from "../utils/tool-choice";
 import type { AuthStorage } from "./auth-storage";
+import type { ClientBridge, ClientBridgePermissionOption, ClientBridgePermissionOutcome } from "./client-bridge";
 import {
+	CompactionCancelledError,
 	type CompactionPreparation,
 	type CompactionResult,
 	calculateContextTokens,
@@ -498,6 +500,96 @@ const noOpUIContext: ExtensionUIContext = {
 	setToolsExpanded: () => {},
 };
 
+// ============================================================================
+// ACP Permission Gate
+// ============================================================================
+
+/** Tools that require user permission before execution when an ACP client is connected. */
+const PERMISSION_REQUIRED_TOOLS = new Set(["bash", "edit", "write", "ast_edit", "delete", "move"]);
+
+/** Permission options presented to the client on each gated tool call. */
+const PERMISSION_OPTIONS: ClientBridgePermissionOption[] = [
+	{ optionId: "allow_once", name: "Allow once", kind: "allow_once" },
+	{ optionId: "allow_always", name: "Always allow", kind: "allow_always" },
+	{ optionId: "reject_once", name: "Reject", kind: "reject_once" },
+	{ optionId: "reject_always", name: "Always reject", kind: "reject_always" },
+];
+
+const PERMISSION_OPTIONS_BY_ID = new Map(PERMISSION_OPTIONS.map(option => [option.optionId, option]));
+
+function derivePermissionTitle(toolName: string, args: unknown): string {
+	const a = args && typeof args === "object" ? (args as Record<string, unknown>) : {};
+	if (toolName === "bash") {
+		const cmd = typeof a.command === "string" ? a.command.slice(0, 80) : undefined;
+		if (cmd) return cmd;
+	} else if (toolName === "edit" || toolName === "write" || toolName === "delete") {
+		const p = typeof a.path === "string" ? a.path : undefined;
+		if (p) {
+			const verb = toolName === "edit" ? "Edit" : toolName === "write" ? "Write" : "Delete";
+			return `${verb} ${p}`;
+		}
+	} else if (toolName === "move") {
+		const from =
+			typeof a.oldPath === "string"
+				? a.oldPath
+				: typeof a.path === "string"
+					? a.path
+					: typeof a.from === "string"
+						? a.from
+						: undefined;
+		const to =
+			typeof a.newPath === "string"
+				? a.newPath
+				: typeof a.to === "string"
+					? a.to
+					: typeof a.destination === "string"
+						? a.destination
+						: undefined;
+		if (from && to) return `Move ${from} to ${to}`;
+		if (from) return `Move ${from}`;
+	} else if (toolName === "ast_edit") {
+		const paths = Array.isArray(a.paths)
+			? (a.paths as unknown[]).filter(x => typeof x === "string").join(", ")
+			: undefined;
+		if (paths) return `AST edit ${paths}`;
+	}
+	return toolName;
+}
+
+function extractPermissionLocations(args: unknown, cwd: string): { path: string; line?: number }[] {
+	if (!args || typeof args !== "object") return [];
+	const a = args as Record<string, unknown>;
+	const out: { path: string; line?: number }[] = [];
+	const pushPath = (value: unknown) => {
+		if (typeof value !== "string" || value.length === 0) return;
+		// ACP locations carry file paths that the editor host will open or focus;
+		// they must be absolute or the client cannot resolve them. Resolve raw
+		// tool args (often cwd-relative) against the session cwd before sending.
+		let resolved: string;
+		try {
+			resolved = resolveToCwd(value, cwd);
+		} catch {
+			return;
+		}
+		if (out.some(location => location.path === resolved)) return;
+		out.push({ path: resolved });
+	};
+	pushPath(a.path);
+	pushPath(a.file);
+	if (Array.isArray(a.paths)) {
+		for (const p of a.paths) {
+			pushPath(p);
+		}
+	}
+	pushPath(a.oldPath);
+	pushPath(a.newPath);
+	pushPath(a.from);
+	pushPath(a.to);
+	pushPath(a.source);
+	pushPath(a.destination);
+	return out;
+}
+
 // ============================================================================
 // AgentSession Class
 // ============================================================================
@@ -530,6 +622,9 @@ export class AgentSession {
 	#planModeState: PlanModeState | undefined;
 	#planReferenceSent = false;
 	#planReferencePath = "local://PLAN.md";
+	#clientBridge: ClientBridge | undefined;
+	/** Per-session memory of allow_always / reject_always decisions for gated tools. */
+	#acpPermissionDecisions: Map<string, "allow_always" | "reject_always"> = new Map();
 
 	// Compaction state
 	#compactionAbortController: AbortController | undefined = undefined;
@@ -2547,6 +2642,85 @@ export class AgentSession {
 		return [...new Set(activated)];
 	}
 
+	/**
+	 * Wrap a tool with a permission-gate proxy when an ACP client is connected.
+	 * Only wraps tools whose name is in PERMISSION_REQUIRED_TOOLS and only when
+	 * the bridge exposes `requestPermission`. No-ops for all other cases.
+	 */
+	#wrapToolForAcpPermission<T extends AgentTool>(tool: T): T {
+		const bridge = this.#clientBridge;
+		// Match the capability+method gating pattern used by read/write/bash.
+		if (!bridge?.capabilities.requestPermission || !bridge.requestPermission) return tool;
+		if (!PERMISSION_REQUIRED_TOOLS.has(tool.name)) return tool;
+		return new Proxy(tool, {
+			get: (target, prop, receiver) => {
+				if (prop !== "execute") return Reflect.get(target, prop, receiver);
+				return async (
+					toolCallId: string,
+					args: unknown,
+					signal: AbortSignal | undefined,
+					onUpdate: never,
+					ctx: never,
+				) => {
+					// Short-circuit on persisted decisions.
+					const persisted = this.#acpPermissionDecisions.get(target.name);
+					if (persisted === "allow_always") {
+						return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
+					}
+					if (persisted === "reject_always") {
+						throw new ToolError(`Tool call rejected by user (preference)`);
+					}
+					if (signal?.aborted) {
+						throw new ToolAbortError("Permission request cancelled");
+					}
+					type PermissionRaceResult =
+						| { kind: "permission"; outcome: ClientBridgePermissionOutcome }
+						| { kind: "aborted" };
+					const { promise: abortPromise, resolve: resolveAbort } = Promise.withResolvers<PermissionRaceResult>();
+					const onAbort = () => resolveAbort({ kind: "aborted" });
+					signal?.addEventListener("abort", onAbort, { once: true });
+					let raced: PermissionRaceResult;
+					try {
+						const permissionPromise = bridge.requestPermission!(
+							{
+								toolCallId,
+								toolName: target.name,
+								title: derivePermissionTitle(target.name, args),
+								rawInput: args,
+								locations: extractPermissionLocations(args, this.sessionManager.getCwd()),
+							},
+							PERMISSION_OPTIONS,
+							signal,
+						).then(outcome => ({ kind: "permission" as const, outcome }));
+						raced = await Promise.race([permissionPromise, abortPromise]);
+					} finally {
+						signal?.removeEventListener("abort", onAbort);
+					}
+					if (raced.kind === "aborted" || signal?.aborted) {
+						throw new ToolAbortError("Permission request cancelled");
+					}
+					const outcome = raced.outcome;
+					if (outcome.outcome === "cancelled") {
+						throw new ToolAbortError("Permission request cancelled");
+					}
+					const selectedOption = PERMISSION_OPTIONS_BY_ID.get(outcome.optionId);
+					if (!selectedOption) {
+						throw new ToolError(`Tool permission response used unknown option ID: ${outcome.optionId}`);
+					}
+					if (selectedOption.kind === "allow_always") {
+						this.#acpPermissionDecisions.set(target.name, "allow_always");
+					} else if (selectedOption.kind === "reject_always") {
+						this.#acpPermissionDecisions.set(target.name, "reject_always");
+					}
+					if (selectedOption.kind === "reject_once" || selectedOption.kind === "reject_always") {
+						throw new ToolError(`Tool call rejected by user (${target.name})`);
+					}
+					return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
+				};
+			},
+		}) as T;
+	}
+
 	async #applyActiveToolsByName(
 		toolNames: string[],
 		options?: { persistMCPSelection?: boolean; previousSelectedMCPToolNames?: string[] },
@@ -2558,7 +2732,7 @@ export class AgentSession {
 		for (const name of toolNames) {
 			const tool = this.#toolRegistry.get(name);
 			if (tool) {
-				tools.push(tool);
+				tools.push(this.#wrapToolForAcpPermission(tool));
 				validToolNames.push(name);
 			}
 		}
@@ -2566,7 +2740,7 @@ export class AgentSession {
 		if (isAutoQaEnabled(this.settings) && !validToolNames.includes("report_tool_issue")) {
 			const qaTool = this.#toolRegistry.get("report_tool_issue");
 			if (qaTool) {
-				tools.push(qaTool);
+				tools.push(this.#wrapToolForAcpPermission(qaTool));
 				validToolNames.push("report_tool_issue");
 			}
 		}
@@ -2974,6 +3148,21 @@ export class AgentSession {
 		this.#planReferencePath = path;
 	}
 
+	get clientBridge(): ClientBridge | undefined {
+		return this.#clientBridge;
+	}
+
+	setClientBridge(bridge: ClientBridge | undefined): void {
+		this.#clientBridge = bridge;
+		this.#acpPermissionDecisions.clear();
+		const activeToolNames = this.getActiveToolNames();
+		const activeTools = activeToolNames
+			.map(name => this.#toolRegistry.get(name))
+			.filter((tool): tool is AgentTool => tool !== undefined)
+			.map(tool => this.#wrapToolForAcpPermission(tool));
+		this.agent.setTools(activeTools);
+	}
+
 	getCheckpointState(): CheckpointState | undefined {
 		return this.#checkpointState;
 	}
@@ -4503,7 +4692,7 @@ export class AgentSession {
 				})) as SessionBeforeCompactResult | undefined;
 
 				if (result?.cancel) {
-					throw new Error("Compaction cancelled");
+					throw new CompactionCancelledError();
 				}
 
 				if (result?.compaction) {
@@ -4545,27 +4734,47 @@ export class AgentSession {
 				details = hookCompaction.details;
 				preserveData ??= hookCompaction.preserveData;
 			} else {
-				// Generate compaction result
-				const result = await this.#compactWithFallbackModel(
-					preparation,
-					customInstructions,
-					compactionAbortController.signal,
-					{
-						promptOverride: hookPrompt,
-						extraContext: hookContext,
-						remoteInstructions: this.#baseSystemPrompt.join("\n\n"),
-					},
-				);
-				summary = result.summary;
-				shortSummary = result.shortSummary;
-				firstKeptEntryId = result.firstKeptEntryId;
-				tokensBefore = result.tokensBefore;
-				details = result.details;
-				preserveData = { ...(preserveData ?? {}), ...(result.preserveData ?? {}) };
+				// Generate compaction result. Only convert known abort-shaped
+				// rejections (AbortError raised while the abort signal is set,
+				// or an already-typed sentinel) into `CompactionCancelledError`
+				// so downstream callers can discriminate cancel from generic
+				// failure via `instanceof` without inspecting message strings.
+				// Real compaction bugs (network, server, parsing, etc.) keep
+				// their original shape — they must not be silently relabeled
+				// as cancellations even if the signal happens to be aborted
+				// for an unrelated reason. Assignments live inside the try
+				// block because every catch path throws — the post-try reads
+				// of the result-derived locals are reachable only on success.
+				try {
+					const result = await this.#compactWithFallbackModel(
+						preparation,
+						customInstructions,
+						compactionAbortController.signal,
+						{
+							promptOverride: hookPrompt,
+							extraContext: hookContext,
+							remoteInstructions: this.#baseSystemPrompt.join("\n\n"),
+						},
+					);
+					summary = result.summary;
+					shortSummary = result.shortSummary;
+					firstKeptEntryId = result.firstKeptEntryId;
+					tokensBefore = result.tokensBefore;
+					details = result.details;
+					preserveData = { ...(preserveData ?? {}), ...(result.preserveData ?? {}) };
+				} catch (err) {
+					if (err instanceof CompactionCancelledError) {
+						throw err;
+					}
+					if (compactionAbortController.signal.aborted && err instanceof Error && err.name === "AbortError") {
+						throw new CompactionCancelledError();
+					}
+					throw err;
+				}
 			}
 
 			if (compactionAbortController.signal.aborted) {
-				throw new Error("Compaction cancelled");
+				throw new CompactionCancelledError();
 			}
 
 			this.sessionManager.appendCompaction(

package/src/session/client-bridge.ts

@@ -0,0 +1,81 @@
+/**
+ * ClientBridge — abstraction over capabilities provided by an external client
+ * (e.g. ACP editor host) that the agent can route through instead of operating
+ * directly on the local filesystem / spawning local subprocesses.
+ *
+ * When `undefined`, tools fall back to local IO. When populated (currently
+ * only by `AcpAgent`), tools route requests through the client so it can
+ * surface unsaved buffer state, render terminals in the IDE, or gate
+ * destructive operations behind user permission prompts.
+ */
+
+export interface ClientBridgeCapabilities {
+	/** Client implements `fs/read_text_file`. */
+	readTextFile?: boolean;
+	/** Client implements `fs/write_text_file`. */
+	writeTextFile?: boolean;
+	/** Client implements the `terminal/*` family. */
+	terminal?: boolean;
+	/** Client implements `session/request_permission`. */
+	requestPermission?: boolean;
+}
+
+export interface ClientBridgePermissionToolCall {
+	toolCallId: string;
+	toolName: string;
+	title: string;
+	kind?: string;
+	rawInput?: unknown;
+	locations?: { path: string; line?: number }[];
+}
+
+export type ClientBridgePermissionOptionKind = "allow_once" | "allow_always" | "reject_once" | "reject_always";
+
+export interface ClientBridgePermissionOption {
+	optionId: string;
+	name: string;
+	kind: ClientBridgePermissionOptionKind;
+}
+
+export type ClientBridgePermissionOutcome =
+	| { outcome: "cancelled" }
+	| { outcome: "selected"; optionId: string; kind?: ClientBridgePermissionOptionKind };
+
+export interface ClientBridgeTerminalExitStatus {
+	exitCode?: number | null;
+	signal?: string | null;
+}
+
+export interface ClientBridgeTerminalOutput {
+	output: string;
+	truncated: boolean;
+	exitStatus?: ClientBridgeTerminalExitStatus | null;
+}
+
+export interface ClientBridgeTerminalHandle {
+	terminalId: string;
+	waitForExit(): Promise<ClientBridgeTerminalExitStatus>;
+	currentOutput(): Promise<ClientBridgeTerminalOutput>;
+	kill(): Promise<void>;
+	release(): Promise<void>;
+}
+
+export interface ClientBridgeCreateTerminalParams {
+	command: string;
+	args?: string[];
+	env?: Array<{ name: string; value: string }>;
+	cwd?: string;
+	outputByteLimit?: number;
+}
+
+export interface ClientBridge {
+	readonly capabilities: ClientBridgeCapabilities;
+	readTextFile?(params: { path: string; line?: number; limit?: number }): Promise<string>;
+	writeTextFile?(params: { path: string; content: string }): Promise<void>;
+	createTerminal?(params: ClientBridgeCreateTerminalParams): Promise<ClientBridgeTerminalHandle>;
+	requestPermission?(
+		toolCall: ClientBridgePermissionToolCall,
+		options: ClientBridgePermissionOption[],
+		signal?: AbortSignal,
+	): Promise<ClientBridgePermissionOutcome>;
+}