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

package/src/prompts/tools/read.md

@@ -2,8 +2,8 @@ Reads the content at the specified path or URL.
 
 <instruction>
 The `read` tool is multi-purpose and more capable than it looks — inspects files, directories, archives, SQLite databases, images, documents (PDF/DOCX/PPTX/XLSX/RTF/EPUB/ipynb), **and URLs**.
-- You **MUST** parallelize reads when exploring related files
-- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You **SHOULD** reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
+- You MUST parallelize reads when exploring related files
+- For URLs, `read` fetches the page and returns clean extracted text/markdown by default (reader-mode). It handles HTML pages, GitHub issues/PRs, Stack Overflow, Wikipedia, Reddit, NPM, arXiv, RSS/Atom, JSON endpoints, PDFs, etc. You SHOULD reach for `read` — not a browser/puppeteer tool — for fetching and inspecting web content.
 
 ## Parameters
 - `path` — file path or URL (required). Append `:<sel>` for line ranges or raw mode (for example `src/foo.ts:50-200` or `src/foo.ts:raw`).
@@ -55,9 +55,9 @@ Extracts content from web pages, GitHub issues/PRs, Stack Overflow, Wikipedia, R
 </instruction>
 
 <critical>
-- You **MUST** use `read` for every file, directory, archive, and URL read. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, and `wget` are **FORBIDDEN** for inspection — any such Bash call is a bug, regardless of how short or convenient it looks.
-- You **MUST** prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser if `read` fails to deliver reasonable content.
-- You **MUST** always include the `path` parameter — never call `read` with an empty argument object `{}`.
-- For specific line ranges, append the selector to `path` (e.g. `path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`) — do **NOT** reach for `sed -n`, `awk NR`, or `head`/`tail` pipelines.
-- You **MAY** use path suffix selectors with URL reads; the tool paginates cached fetched output.
+- You MUST use `read` for every file, directory, archive, and URL read. `cat`, `head`, `tail`, `less`, `more`, `ls`, `tar`, `unzip`, `curl`, and `wget` are **FORBIDDEN** for inspection — any such Bash call is a bug, regardless of how short or convenient it looks.
+- You MUST prefer `read` over a browser/puppeteer tool for fetching URL content; only use a browser if `read` fails to deliver reasonable content.
+- You MUST always include the `path` parameter — never call `read` with an empty argument object `{}`.
+- For specific line ranges, append the selector to `path` (e.g. `path="src/foo.ts:50-200"`, `path="src/foo.ts:50+150"`) — NEVER reach for `sed -n`, `awk NR`, or `head`/`tail` pipelines.
+- You MAY use path suffix selectors with URL reads; the tool paginates cached fetched output.
 </critical>

package/src/prompts/tools/replace.md

@@ -1,10 +1,10 @@
 Performs string replacements in files with fuzzy whitespace matching.
 
 <instruction>
-- Params **MUST** be `{ path, edits }`; `path` is required at the top level and applies to every replacement
-- You **MUST** use the smallest `old_text` that uniquely identifies the change
-- If `old_text` is not unique, you **MUST** expand it with more context or use `all: true` to replace all occurrences
-- You **SHOULD** prefer editing existing files over creating new ones
+- Params MUST be `{ path, edits }`; `path` is required at the top level and applies to every replacement
+- You MUST use the smallest `old_text` that uniquely identifies the change
+- If `old_text` is not unique, you MUST expand it with more context or use `all: true` to replace all occurrences
+- You SHOULD prefer editing existing files over creating new ones
 </instruction>
 
 <output>
@@ -12,7 +12,7 @@ Returns success/failure status. On success, file modified in place with replacem
 </output>
 
 <critical>
-- You **MUST** read the file at least once in the conversation before editing. Tool errors if you attempt edit without reading file first.
+- You MUST read the file at least once in the conversation before editing. Tool errors if you attempt edit without reading file first.
 </critical>
 
 <bash-alternatives>

package/src/prompts/tools/retain.md

@@ -3,4 +3,4 @@ Store one or more facts in long-term memory for future sessions.
 Use for durable, reusable knowledge: user preferences, project decisions, architectural choices, anything that improves future responses.
 Ephemeral task state does not belong here.
 
-Each item **MUST** be specific and self-contained — include who, what, when, and why. Batch related facts in a single call; they are deduplicated and consolidated.
+Each item MUST be specific and self-contained — include who, what, when, and why. Batch related facts in a single call; they are deduplicated and consolidated.

package/src/prompts/tools/rewind.md

@@ -3,10 +3,10 @@ End an active checkpoint. Rewind context to it, replacing intermediate explorati
 Call immediately after `checkpoint`-started investigative work.
 
 Requirements:
-- `report` is **REQUIRED** and must be concise, factual, and actionable.
+- `report` is REQUIRED and must be concise, factual, and actionable.
 - Include key findings, decisions, and any unresolved risks.
 - Do not include raw scratch logs unless essential.
-- You **MUST** call this before yielding if a checkpoint is active.
+- You MUST call this before yielding if a checkpoint is active.
 
 Behavior:
 - If no checkpoint is active, this tool errors.

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(