@oh-my-pi/pi-coding-agent 15.1.3 → 15.1.5

package/src/modes/components/tree-selector.ts

@@ -453,6 +453,16 @@ class TreeList implements Component {
 		);
 		const endIndex = Math.min(startIndex + this.maxVisibleLines, this.#filteredNodes.length);
 
+		// Cap the per-row gutter prefix so a content budget is always preserved.
+		// Each indent level renders as 3 cells; deep branching would otherwise eat the
+		// entire viewport (issue #1144). Reserve at least MIN_CONTENT_COLS for entry
+		// text — or half the viewport, whichever is larger — and compress older gutter
+		// levels off-screen behind a leading ellipsis when the row would exceed budget.
+		const MIN_CONTENT_COLS = 24;
+		const OVERHEAD_COLS = 4; // cursor (2) + a touch of breathing room
+		const contentReserve = Math.max(MIN_CONTENT_COLS, Math.floor(width / 2));
+		const maxIndentLevels = Math.max(1, Math.floor((width - contentReserve - OVERHEAD_COLS) / 3));
+
 		for (let i = startIndex; i < endIndex; i++) {
 			const flatNode = this.#filteredNodes[i];
 			const entry = flatNode.node.entry;
@@ -464,29 +474,34 @@ class TreeList implements Component {
 			// If multiple roots, shift display (roots at 0, not 1)
 			const displayIndent = this.#multipleRoots ? Math.max(0, flatNode.indent - 1) : flatNode.indent;
 
-			// Build prefix with gutters at their correct positions
-			// Each gutter has a position (displayIndent where its connector was shown)
+			// Build prefix with gutters at their correct positions, clamped to
+			// `maxIndentLevels` cells so the content always fits. When clamped, the
+			// leftmost cells represent the deepest visible ancestors and a `…` marker
+			// indicates older branch context has been compressed.
 			const hasConnector = flatNode.showConnector && !flatNode.isVirtualRootChild;
 			const connectorSymbol = hasConnector ? (flatNode.isLast ? theme.tree.last : theme.tree.branch) : "";
 			const connectorChars = hasConnector ? Array.from(connectorSymbol) : [];
-			const connectorPosition = hasConnector ? displayIndent - 1 : -1;
+			const renderedIndent = Math.min(displayIndent, maxIndentLevels);
+			const scrollOffset = displayIndent - renderedIndent;
+			const connectorPositionDisplay = hasConnector ? renderedIndent - 1 : -1;
 
 			// Build prefix char by char, placing gutters and connector at their positions
-			const totalChars = displayIndent * 3;
+			const totalChars = renderedIndent * 3;
 			const prefixChars: string[] = [];
 			for (let i = 0; i < totalChars; i++) {
 				const level = Math.floor(i / 3);
+				const originalLevel = level + scrollOffset;
 				const posInLevel = i % 3;
 
-				// Check if there's a gutter at this level
-				const gutter = flatNode.gutters.find(g => g.position === level);
+				// Check if there's a gutter at this level (translated to original tree depth)
+				const gutter = flatNode.gutters.find(g => g.position === originalLevel);
 				if (gutter) {
 					if (posInLevel === 0) {
 						prefixChars.push(gutter.show ? theme.tree.vertical : " ");
 					} else {
 						prefixChars.push(" ");
 					}
-				} else if (hasConnector && level === connectorPosition) {
+				} else if (hasConnector && level === connectorPositionDisplay) {
 					// Connector at this level
 					if (posInLevel === 0) {
 						prefixChars.push(connectorChars[0] ?? " ");
@@ -499,6 +514,10 @@ class TreeList implements Component {
 					prefixChars.push(" ");
 				}
 			}
+			// Mark the leftmost cell when ancestors were compressed off-screen.
+			if (scrollOffset > 0 && prefixChars.length > 0) {
+				prefixChars[0] = "…";
+			}
 			const prefix = prefixChars.join("");
 
 			// Active path marker - shown right before the entry text

package/src/plan-mode/approved-plan.ts

@@ -14,10 +14,12 @@ export interface PlanApprovalDetails {
 	planExists: boolean;
 }
 
-/** Validate the agent-supplied plan title and derive the destination filename.
- *  Filename uses the title with a `.md` suffix; characters are restricted to
- *  letters, numbers, underscores, and hyphens so the value is safe to splice
- *  into a `local://` URL without escaping. */
+/** Validate and normalize the agent-supplied plan title into a safe filename stem.
+ *  Spaces and other URL-safe punctuation are replaced with hyphens so models that
+ *  produce natural-language titles (e.g. "My feature plan") still succeed.
+ *  Characters that cannot be safely represented after replacement are dropped.
+ *  The result is restricted to letters, numbers, underscores, and hyphens so it
+ *  is safe to splice into a `local://` URL without escaping. */
 export function normalizePlanTitle(title: string): { title: string; fileName: string } {
 	const trimmed = title.trim();
 	if (!trimmed) {
@@ -28,13 +30,23 @@ export function normalizePlanTitle(title: string): { title: string; fileName: st
 		throw new ToolError("Plan title must not contain path separators or '..'.");
 	}
 
-	const withExtension = trimmed.toLowerCase().endsWith(".md") ? trimmed : `${trimmed}.md`;
-	if (!/^[A-Za-z0-9_-]+\.md$/.test(withExtension)) {
-		throw new ToolError("Plan title may only contain letters, numbers, underscores, or hyphens.");
+	// Strip a trailing `.md` if the model included it, then sanitize:
+	// spaces → hyphens, any remaining invalid char → dropped.
+	const withoutExt = trimmed.replace(/\.md$/i, "");
+	const sanitized = withoutExt
+		.replace(/\s+/g, "-")
+		.replace(/[^A-Za-z0-9_-]/g, "")
+		.replace(/-{2,}/g, "-")
+		.replace(/^-+|-+$/g, "");
+
+	if (!sanitized) {
+		throw new ToolError(
+			"Plan title must contain at least one letter, number, underscore, or hyphen after sanitization.",
+		);
 	}
 
-	const normalizedTitle = withExtension.slice(0, -3);
-	return { title: normalizedTitle, fileName: withExtension };
+	const fileName = `${sanitized}.md`;
+	return { title: sanitized, fileName };
 }
 
 /** Humanize a normalized plan title for use as a session display name.

package/src/prompts/agents/oracle.md

@@ -0,0 +1,56 @@
+---
+name: oracle
+description: Deep reasoning advisor for debugging dead ends, architecture decisions, and second opinions. Read-only.
+spawns: explore
+model: pi/slow
+thinking-level: xhigh
+blocking: true
+---
+
+You are a senior diagnostician and strategic technical advisor. You receive problems other agents are stuck on — doom loops, mysterious failures, architectural tradeoffs, subtle bugs — and return clear, actionable analysis.
+
+You diagnose, explain, and recommend. You do not implement. Others act on your findings.
+
+<critical>
+You MUST operate as read-only. You NEVER write, edit, or modify files, nor execute any state-changing commands.
+</critical>
+
+<directives>
+- You MUST reason from first principles. The caller already tried the obvious.
+- You MUST use tools to verify claims. You NEVER speculate about code behavior — read it.
+- You MUST identify root causes, not symptoms. If the caller says "X is broken", determine *why* X is broken.
+- You MUST surface hidden assumptions — in the code, in the caller's framing, in the environment.
+- You SHOULD consider at least two hypotheses before converging on one.
+- You SHOULD invoke tools in parallel when investigating multiple hypotheses.
+- When the problem is architectural, you MUST weigh tradeoffs explicitly: what does each option cost, what does it buy, what does it foreclose.
+</directives>
+
+<decision-framework>
+Apply pragmatic minimalism:
+- **Bias toward simplicity**: The right solution is the least complex one that fulfills actual requirements. Resist hypothetical future needs.
+- **Leverage what exists**: Favor modifications to current code and established patterns over introducing new components. New dependencies or infrastructure require explicit justification.
+- **One clear path**: Present a single primary recommendation. Mention alternatives only when they offer substantially different tradeoffs worth considering.
+- **Match depth to complexity**: Quick questions get quick answers. Reserve thorough analysis for genuinely complex problems.
+- **Signal the investment**: Tag recommendations with estimated effort — Quick (<1h), Short (1-4h), Medium (1-2d), Large (3d+).
+</decision-framework>
+
+<procedure>
+1. Read the problem statement carefully. Identify what was already tried and why it failed.
+2. Form 2-3 hypotheses for the root cause.
+3. Use tools to gather evidence — read relevant code, trace data flow, check types, grep for related patterns. Parallelize independent reads.
+4. Eliminate hypotheses based on evidence. Narrow to the most likely cause.
+5. If the problem is a decision (not a bug), lay out options with concrete tradeoffs.
+6. Deliver a clear verdict with supporting evidence.
+</procedure>
+<scope-discipline>
+- Recommend ONLY what was asked. No unsolicited improvements.
+- If you notice other issues, list at most 2 as "Optional future considerations" at the end.
+- You NEVER expand the problem surface beyond the original request.
+- Exhaust provided context before reaching for tools. External lookups fill genuine gaps, not curiosity.
+</scope-discipline>
+
+<critical>
+You MUST keep going until you have a clear answer or have exhausted available evidence.
+Before finalizing: re-scan for unstated assumptions, verify claims are grounded in code not invented, check for overly strong language not justified by evidence.
+This matters. The caller is stuck. Get it right.
+</critical>

package/src/prompts/tools/ask.md

@@ -22,7 +22,8 @@ Asks user when you need clarification or input during task execution.
 
 <examples>
 # Single question
-question: "Which authentication method should this API use?"
-options: [{"label": "JWT"}, {"label": "OAuth2"}, {"label": "Session cookies"}]
-recommended: 0
+questions: [{"id": "auth_method", "question": "Which authentication method should this API use?", "options": [{"label": "JWT"}, {"label": "OAuth2"}, {"label": "Session cookies"}], "recommended": 0}]
+
+# Multiple questions
+questions: [{"id": "storage_type", "question": "Which storage backend?", "options": [{"label": "SQLite"}, {"label": "PostgreSQL"}]}, {"id": "auth_method", "question": "Which auth method?", "options": [{"label": "JWT"}, {"label": "Session cookies"}]}]
 </examples>

package/src/sdk.ts

@@ -1070,7 +1070,9 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			return undefined;
 		};
 		const toolSession: ToolSession = {
-			cwd,
+			get cwd() {
+				return sessionManager.getCwd();
+			},
 			hasUI: options.hasUI ?? false,
 			enableLsp,
 			get hasEditTool() {

package/src/session/agent-session.ts

@@ -81,7 +81,7 @@ import {
 	prompt,
 	Snowflake,
 } from "@oh-my-pi/pi-utils";
-import { type AsyncJob, AsyncJobManager } from "../async";
+import { type AsyncJob, type AsyncJobDeliveryState, AsyncJobManager } from "../async";
 import { reset as resetCapabilities } from "../capability";
 import type { Rule } from "../capability/rule";
 import { MODEL_ROLE_IDS, type ModelRegistry } from "../config/model-registry";
@@ -97,7 +97,7 @@ import { expandPromptTemplate, type PromptTemplate } from "../config/prompt-temp
 import type { Settings, SkillsSettings } from "../config/settings";
 import { RawSseDebugBuffer } from "../debug/raw-sse-buffer";
 import { loadCapability } from "../discovery";
-import { normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../edit";
+import { expandApplyPatchToEntries, normalizeDiff, normalizeToLF, ParseError, previewPatch, stripBom } from "../edit";
 import {
 	disposeKernelSessionsByOwner,
 	executePython as executePythonCommand,
@@ -236,6 +236,7 @@ export type AsyncJobSnapshotItem = Pick<AsyncJob, "id" | "type" | "status" | "la
 export interface AsyncJobSnapshot {
 	running: AsyncJobSnapshotItem[];
 	recent: AsyncJobSnapshotItem[];
+	delivery: AsyncJobDeliveryState;
 }
 
 // ============================================================================
@@ -534,7 +535,7 @@ function createHandoffFileName(date = new Date()): string {
 // ============================================================================
 
 /** 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"]);
+const PERMISSION_REQUIRED_TOOLS = new Set(["bash", "edit", "delete", "move"]);
 
 /** Permission options presented to the client on each gated tool call. */
 const PERMISSION_OPTIONS: ClientBridgePermissionOption[] = [
@@ -546,46 +547,106 @@ const PERMISSION_OPTIONS: ClientBridgePermissionOption[] = [
 
 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>) : {};
+function getStringProperty(value: Record<string, unknown>, key: string): string | undefined {
+	const candidate = value[key];
+	return typeof candidate === "string" ? candidate : undefined;
+}
+
+function collectStringPaths(value: unknown): string[] {
+	return Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+}
+
+function getEditDestructiveIntent(args: unknown): { kind: "delete" | "move"; paths: string[] } | undefined {
+	if (!args || typeof args !== "object" || Array.isArray(args)) return undefined;
+	const a = args as Record<string, unknown>;
+
+	const edits = Array.isArray(a.edits) ? a.edits : undefined;
+	if (edits) {
+		const path = getStringProperty(a, "path");
+		if (path) {
+			for (const edit of edits) {
+				if (!edit || typeof edit !== "object" || Array.isArray(edit)) continue;
+				const op = getStringProperty(edit as Record<string, unknown>, "op");
+				if (op === "delete") return { kind: "delete", paths: [path] };
+			}
+		}
+		for (const edit of edits) {
+			if (!edit || typeof edit !== "object" || Array.isArray(edit)) continue;
+			const entry = edit as Record<string, unknown>;
+			const op = getStringProperty(entry, "op");
+			const rename = getStringProperty(entry, "rename");
+			if (op !== "create" && rename) return { kind: "move", paths: path ? [path, rename] : [rename] };
+		}
+	}
+
+	const input = getStringProperty(a, "input");
+	if (input) {
+		try {
+			const entries = expandApplyPatchToEntries({ input });
+			const deleteEntry = entries.find(entry => entry.op === "delete");
+			if (deleteEntry) return { kind: "delete", paths: [deleteEntry.path] };
+			const moveEntry = entries.find(entry => entry.rename);
+			if (moveEntry?.rename) return { kind: "move", paths: [moveEntry.path, moveEntry.rename] };
+		} catch {
+			// If the edit input is not an apply_patch envelope, it is not a delete/move operation.
+		}
+	}
+
+	return undefined;
+}
+
+function getPermissionIntent(
+	toolName: string,
+	args: unknown,
+): { toolName: string; title: string; paths?: string[]; cacheKey: string } | undefined {
+	const a = args && typeof args === "object" && !Array.isArray(args) ? (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}`;
+		const cmd = getStringProperty(a, "command")?.slice(0, 80);
+		return { toolName, title: cmd || toolName, cacheKey: toolName };
+	}
+	if (toolName === "delete") {
+		const p = getStringProperty(a, "path");
+		return { toolName, title: p ? `Delete ${p}` : toolName, paths: p ? [p] : undefined, cacheKey: toolName };
+	}
+	if (toolName === "move") {
+		const from = getStringProperty(a, "oldPath") ?? getStringProperty(a, "path") ?? getStringProperty(a, "from");
+		const to = getStringProperty(a, "newPath") ?? getStringProperty(a, "to") ?? getStringProperty(a, "destination");
+		if (from && to) return { toolName, title: `Move ${from} to ${to}`, paths: [from, to], cacheKey: toolName };
+		return {
+			toolName,
+			title: from ? `Move ${from}` : toolName,
+			paths: from ? [from] : undefined,
+			cacheKey: toolName,
+		};
+	}
+	if (toolName === "edit") {
+		const intent = getEditDestructiveIntent(args);
+		if (!intent) return undefined;
+		if (intent.kind === "delete") {
+			return {
+				toolName,
+				title: `Delete ${intent.paths[0] ?? "edit target"}`,
+				paths: intent.paths,
+				cacheKey: "edit:delete",
+			};
+		}
+		const from = intent.paths[0];
+		const to = intent.paths[1];
+		return {
+			toolName,
+			title: from && to ? `Move ${from} to ${to}` : `Move ${from ?? to ?? "edit target"}`,
+			paths: intent.paths,
+			cacheKey: "edit:move",
+		};
 	}
-	return toolName;
+	return undefined;
 }
 
-function extractPermissionLocations(args: unknown, cwd: string): { path: string; line?: number }[] {
+function extractPermissionLocations(
+	args: unknown,
+	cwd: string,
+	explicitPaths?: string[],
+): { path: string; line?: number }[] {
 	if (!args || typeof args !== "object") return [];
 	const a = args as Record<string, unknown>;
 	const out: { path: string; line?: number }[] = [];
@@ -603,12 +664,16 @@ function extractPermissionLocations(args: unknown, cwd: string): { path: string;
 		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) {
+	if (explicitPaths) {
+		for (const p of explicitPaths) {
 			pushPath(p);
 		}
+		return out;
+	}
+	pushPath(a.path);
+	pushPath(a.file);
+	for (const p of collectStringPaths(a.paths)) {
+		pushPath(p);
 	}
 	pushPath(a.oldPath);
 	pushPath(a.newPath);
@@ -667,6 +732,7 @@ export class AgentSession {
 	#planReferenceSent = false;
 	#planReferencePath = "local://PLAN.md";
 	#clientBridge: ClientBridge | undefined;
+	#allowAcpAgentInitiatedTurns = false;
 	/** Per-session memory of allow_always / reject_always decisions for gated tools. */
 	#acpPermissionDecisions: Map<string, "allow_always" | "reject_always"> = new Map();
 
@@ -804,6 +870,15 @@ export class AgentSession {
 
 	#streamingEditFileCache = new Map<string, string>();
 	#promptInFlightCount = 0;
+	// Wire-level agent_end emission deferred until #promptInFlightCount drops to 0.
+	// Internal extension hooks and post-emit work (auto-retry, auto-compaction, todo
+	// checks in #handleAgentEvent) still fire on the original schedule — only the
+	// `#emit(event)` that reaches external subscribers (rpc-mode stdout, ACP bridge,
+	// Cursor exec, TUI listeners) is held back. Without this, a client that resumes
+	// on `agent_end` can fire its next `prompt` before #promptWithMessage's finally
+	// has decremented #promptInFlightCount, hitting AgentBusyError. Flushed from
+	// both #endInFlight (normal) and #resetInFlight (abort).
+	#pendingAgentEndEmit: AgentSessionEvent | undefined;
 	#obfuscator: SecretObfuscator | undefined;
 	#checkpointState: CheckpointState | undefined = undefined;
 	#pendingRewindReport: string | undefined = undefined;
@@ -857,12 +932,21 @@ export class AgentSession {
 		this.#promptInFlightCount = Math.max(0, this.#promptInFlightCount - 1);
 		if (this.#promptInFlightCount === 0) {
 			this.#releasePowerAssertion();
+			this.#flushPendingAgentEnd();
 		}
 	}
 
 	#resetInFlight(): void {
 		this.#promptInFlightCount = 0;
 		this.#releasePowerAssertion();
+		this.#flushPendingAgentEnd();
+	}
+
+	#flushPendingAgentEnd(): void {
+		const pending = this.#pendingAgentEndEmit;
+		if (!pending) return;
+		this.#pendingAgentEndEmit = undefined;
+		this.#emit(pending);
 	}
 
 	constructor(config: AgentSessionConfig) {
@@ -1126,21 +1210,23 @@ export class AgentSession {
 	getAsyncJobSnapshot(options?: { recentLimit?: number }): AsyncJobSnapshot | null {
 		const manager = AsyncJobManager.instance();
 		if (!manager) return null;
-		const running = manager.getRunningJobs().map(job => ({
+		const ownerFilter = this.#agentId ? { ownerId: this.#agentId } : undefined;
+		const running = manager.getRunningJobs(ownerFilter).map(job => ({
 			id: job.id,
 			type: job.type,
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
 		}));
-		const recent = manager.getRecentJobs(options?.recentLimit ?? 5).map(job => ({
+		const recent = manager.getRecentJobs(options?.recentLimit ?? 5, ownerFilter).map(job => ({
 			id: job.id,
 			type: job.type,
 			status: job.status,
 			label: job.label,
 			startTime: job.startTime,
 		}));
-		return { running, recent };
+		const delivery = manager.getDeliveryState(ownerFilter);
+		return { running, recent, delivery };
 	}
 
 	/**
@@ -1198,6 +1284,18 @@ export class AgentSession {
 			return;
 		}
 		await this.#emitExtensionEvent(event);
+		// Hold the wire-level agent_end until in-flight prompts unwind. Subscribers
+		// (rpc-mode, ACP, Cursor) treat agent_end as the "session is idle" signal;
+		// emitting while #promptInFlightCount > 0 lets a client fire its next
+		// `prompt` into a session that still reports isStreaming === true. Flush
+		// happens in #endInFlight / #resetInFlight. A later agent_end (e.g. from
+		// an auto-compaction turn that starts before the original prompt unwinds)
+		// supersedes the pending one, which is what subscribers want — they only
+		// care about the final settle.
+		if (event.type === "agent_end" && this.#promptInFlightCount > 0) {
+			this.#pendingAgentEndEmit = event;
+			return;
+		}
 		this.#emit(event);
 	}
 
@@ -2674,6 +2772,23 @@ export class AgentSession {
 		await this.#waitForPostPromptRecovery();
 	}
 
+	async drainAsyncJobDeliveriesForAcp(options?: { timeoutMs?: number }): Promise<boolean> {
+		const manager = AsyncJobManager.instance();
+		if (!manager) return false;
+		const ownerFilter = this.#agentId ? { ownerId: this.#agentId } : undefined;
+		const before = manager.getDeliveryState(ownerFilter);
+		if (before.queued === 0 && !before.delivering) return false;
+		const previousAllowAcpAgentInitiatedTurns = this.#allowAcpAgentInitiatedTurns;
+		this.#allowAcpAgentInitiatedTurns = true;
+		try {
+			const drained = await manager.drainDeliveries({ timeoutMs: options?.timeoutMs, filter: ownerFilter });
+			const after = manager.getDeliveryState(ownerFilter);
+			return drained && (before.queued !== after.queued || before.delivering !== after.delivering);
+		} finally {
+			this.#allowAcpAgentInitiatedTurns = previousAllowAcpAgentInitiatedTurns;
+		}
+	}
+
 	/** Most recent assistant message in agent state. */
 	getLastAssistantMessage(): AssistantMessage | undefined {
 		return this.#findLastAssistantMessage();
@@ -2973,8 +3088,8 @@ export class AgentSession {
 		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);
+			get: (target, prop) => {
+				if (prop !== "execute") return Reflect.get(target, prop, target);
 				return async (
 					toolCallId: string,
 					args: unknown,
@@ -2982,8 +3097,12 @@ export class AgentSession {
 					onUpdate: never,
 					ctx: never,
 				) => {
+					const permissionIntent = getPermissionIntent(target.name, args);
+					if (!permissionIntent) {
+						return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
+					}
 					// Short-circuit on persisted decisions.
-					const persisted = this.#acpPermissionDecisions.get(target.name);
+					const persisted = this.#acpPermissionDecisions.get(permissionIntent.cacheKey);
 					if (persisted === "allow_always") {
 						return await target.execute(toolCallId, args as never, signal, onUpdate, ctx);
 					}
@@ -3005,9 +3124,14 @@ export class AgentSession {
 							{
 								toolCallId,
 								toolName: target.name,
-								title: derivePermissionTitle(target.name, args),
+								title: permissionIntent.title,
+								status: "pending",
 								rawInput: args,
-								locations: extractPermissionLocations(args, this.sessionManager.getCwd()),
+								locations: extractPermissionLocations(
+									args,
+									this.sessionManager.getCwd(),
+									permissionIntent.paths,
+								),
 							},
 							PERMISSION_OPTIONS,
 							signal,
@@ -3028,9 +3152,9 @@ export class AgentSession {
 						throw new ToolError(`Tool permission response used unknown option ID: ${outcome.optionId}`);
 					}
 					if (selectedOption.kind === "allow_always") {
-						this.#acpPermissionDecisions.set(target.name, "allow_always");
+						this.#acpPermissionDecisions.set(permissionIntent.cacheKey, "allow_always");
 					} else if (selectedOption.kind === "reject_always") {
-						this.#acpPermissionDecisions.set(target.name, "reject_always");
+						this.#acpPermissionDecisions.set(permissionIntent.cacheKey, "reject_always");
 					}
 					if (selectedOption.kind === "reject_once" || selectedOption.kind === "reject_always") {
 						throw new ToolError(`Tool call rejected by user (${target.name})`);
@@ -4270,7 +4394,7 @@ export class AgentSession {
 	 *
 	 * Handles three cases:
 	 * - Streaming: queue as steer/follow-up or store for next turn
-	 * - Not streaming + triggerTurn: appends to state/session, starts new turn
+	 * - Not streaming + triggerTurn: appends to state/session, starts new turn unless the client cannot own it
 	 * - Not streaming + no trigger: appends to state/session, no turn
 	 */
 	async sendCustomMessage<T = unknown>(
@@ -4302,6 +4426,10 @@ export class AgentSession {
 
 		if (options?.deliverAs === "nextTurn") {
 			if (options?.triggerTurn) {
+				if (this.#clientBridge?.deferAgentInitiatedTurns && !this.#allowAcpAgentInitiatedTurns) {
+					this.#queueHiddenNextTurnMessage(appMessage, false);
+					return;
+				}
 				await this.agent.prompt(appMessage);
 				return;
 			}
@@ -4317,6 +4445,10 @@ export class AgentSession {
 		}
 
 		if (options?.triggerTurn) {
+			if (this.#clientBridge?.deferAgentInitiatedTurns && !this.#allowAcpAgentInitiatedTurns) {
+				this.#queueHiddenNextTurnMessage(appMessage, false);
+				return;
+			}
 			await this.agent.prompt(appMessage);
 			return;
 		}

package/src/session/client-bridge.ts

@@ -25,6 +25,7 @@ export interface ClientBridgePermissionToolCall {
 	toolName: string;
 	title: string;
 	kind?: string;
+	status?: "pending" | "in_progress" | "completed" | "failed";
 	rawInput?: unknown;
 	locations?: { path: string; line?: number }[];
 }
@@ -70,6 +71,8 @@ export interface ClientBridgeCreateTerminalParams {
 
 export interface ClientBridge {
 	readonly capabilities: ClientBridgeCapabilities;
+	/** ACP v1 clients cannot show server-initiated turns as busy after prompt response. */
+	readonly deferAgentInitiatedTurns?: boolean;
 	readTextFile?(params: { path: string; line?: number; limit?: number }): Promise<string>;
 	writeTextFile?(params: { path: string; content: string }): Promise<void>;
 	createTerminal?(params: ClientBridgeCreateTerminalParams): Promise<ClientBridgeTerminalHandle>;

package/src/task/agents.ts

@@ -11,6 +11,7 @@ import exploreMd from "../prompts/agents/explore.md" with { type: "text" };
 // Embed agent markdown files at build time
 import agentFrontmatterTemplate from "../prompts/agents/frontmatter.md" with { type: "text" };
 import librarianMd from "../prompts/agents/librarian.md" with { type: "text" };
+import oracleMd from "../prompts/agents/oracle.md" with { type: "text" };
 
 import planMd from "../prompts/agents/plan.md" with { type: "text" };
 import reviewerMd from "../prompts/agents/reviewer.md" with { type: "text" };
@@ -46,6 +47,7 @@ const EMBEDDED_AGENT_DEFS: EmbeddedAgentDef[] = [
 	{ fileName: "designer.md", template: designerMd },
 	{ fileName: "reviewer.md", template: reviewerMd },
 	{ fileName: "librarian.md", template: librarianMd },
+	{ fileName: "oracle.md", template: oracleMd },
 	{
 		fileName: "task.md",
 		frontmatter: {