@oh-my-pi/pi-coding-agent 17.1.5 → 17.1.7

package/src/extensibility/extensions/runner.ts

@@ -37,6 +37,7 @@ import type {
 	ExtensionRuntime,
 	ExtensionShortcut,
 	ExtensionUIContext,
+	ExtensionUIDialogOptions,
 	InputEvent,
 	InputEventResult,
 	MessageRenderer,
@@ -105,6 +106,66 @@ function handlerTimeoutForEvent(eventType: string): number {
 const EXTENSION_HANDLER_TIMEOUT = Symbol("extensionHandlerTimeout");
 const EXTENSION_HANDLER_ABORTED = Symbol("extensionHandlerAborted");
 
+function attachHandlerSignal(
+	dialogOptions: ExtensionUIDialogOptions | undefined,
+	handlerSignal: AbortSignal,
+): ExtensionUIDialogOptions {
+	if (!dialogOptions) return { signal: handlerSignal };
+	if (!dialogOptions.signal) return { ...dialogOptions, signal: handlerSignal };
+	if (dialogOptions.signal === handlerSignal) return dialogOptions;
+	return { ...dialogOptions, signal: AbortSignal.any([dialogOptions.signal, handlerSignal]) };
+}
+
+function createHandlerUIContext(ui: ExtensionUIContext, handlerSignal: AbortSignal): ExtensionUIContext {
+	const askDialog = ui.askDialog;
+	const dialogMethods = {
+		select: (title, options, dialogOptions) =>
+			ui.select(title, options, attachHandlerSignal(dialogOptions, handlerSignal)),
+		confirm: (title, message, dialogOptions) =>
+			ui.confirm(title, message, attachHandlerSignal(dialogOptions, handlerSignal)),
+		input: (title, placeholder, dialogOptions) =>
+			ui.input(title, placeholder, attachHandlerSignal(dialogOptions, handlerSignal)),
+		askDialog: askDialog
+			? (questions, dialogOptions) =>
+					askDialog.call(ui, questions, attachHandlerSignal(dialogOptions, handlerSignal))
+			: undefined,
+		editor: (title, prefill, dialogOptions, editorOptions) =>
+			ui.editor(title, prefill, attachHandlerSignal(dialogOptions, handlerSignal), editorOptions),
+	} satisfies Pick<ExtensionUIContext, "select" | "confirm" | "input" | "askDialog" | "editor">;
+	const delegatedMethods = new Map<PropertyKey, unknown>();
+
+	return new Proxy(ui, {
+		get(target, property) {
+			if (Object.hasOwn(dialogMethods, property)) {
+				return Reflect.get(dialogMethods, property, dialogMethods);
+			}
+			const cached = delegatedMethods.get(property);
+			if (cached) return cached;
+			const value: unknown = Reflect.get(target, property, target);
+			if (typeof value !== "function") return value;
+			const delegated: unknown = value.bind(target);
+			delegatedMethods.set(property, delegated);
+			return delegated;
+		},
+	});
+}
+
+/**
+ * Scope `ctx` to a single handler run without spreading it: `{ ...ctx }` would
+ * snapshot live accessors (notably the `model` getter), so a handler calling
+ * `pi.setModel()` and then reading `ctx.model` would see a stale model.
+ * Prototype delegation keeps every getter live while overriding `ui`.
+ */
+function createHandlerContext(ctx: ExtensionContext, handlerSignal: AbortSignal): ExtensionContext {
+	const scoped: ExtensionContext = Object.create(ctx);
+	Object.defineProperty(scoped, "ui", {
+		value: createHandlerUIContext(ctx.ui, handlerSignal),
+		enumerable: true,
+		configurable: true,
+	});
+	return scoped;
+}
+
 /**
  * Race `work` against a `timeoutMs` budget and optional cancellation signal,
  * clearing the timer and abort listener as soon as one branch settles.
@@ -118,19 +179,37 @@ const EXTENSION_HANDLER_ABORTED = Symbol("extensionHandlerAborted");
  * can `clearTimeout` on the winning branch.
  */
 async function raceHandlerWithTimeout<T>(
-	work: Promise<T>,
+	work: (handlerSignal: AbortSignal) => Promise<T> | T,
 	timeoutMs: number,
 	signal?: AbortSignal,
 ): Promise<T | typeof EXTENSION_HANDLER_TIMEOUT | typeof EXTENSION_HANDLER_ABORTED> {
 	if (signal?.aborted) return EXTENSION_HANDLER_ABORTED;
+
+	const timeoutController = new AbortController();
+	const handlerSignal = signal ? AbortSignal.any([signal, timeoutController.signal]) : timeoutController.signal;
 	const { promise: interruptPromise, resolve: resolveInterrupt } = Promise.withResolvers<
 		typeof EXTENSION_HANDLER_TIMEOUT | typeof EXTENSION_HANDLER_ABORTED
 	>();
-	const timer = setTimeout(() => resolveInterrupt(EXTENSION_HANDLER_TIMEOUT), timeoutMs);
 	const onAbort = () => resolveInterrupt(EXTENSION_HANDLER_ABORTED);
 	signal?.addEventListener("abort", onAbort, { once: true });
+	const timer = setTimeout(() => {
+		timeoutController.abort(new DOMException(`Handler timed out after ${timeoutMs}ms`, "TimeoutError"));
+		resolveInterrupt(EXTENSION_HANDLER_TIMEOUT);
+	}, timeoutMs);
 	try {
-		return await Promise.race([work, interruptPromise]);
+		if (signal?.aborted) return EXTENSION_HANDLER_ABORTED;
+		const workPromise = Promise.resolve(work(handlerSignal));
+		const result = await Promise.race([workPromise, interruptPromise]);
+		if (result === EXTENSION_HANDLER_TIMEOUT) {
+			await Promise.race([
+				workPromise.then(
+					() => undefined,
+					() => undefined,
+				),
+				Bun.sleep(0),
+			]);
+		}
+		return result;
 	} finally {
 		clearTimeout(timer);
 		signal?.removeEventListener("abort", onAbort);
@@ -277,6 +356,32 @@ export class ExtensionRunner {
 	#managedTimers = new ManagedTimers((event, error, stack) =>
 		this.emitError({ extensionPath: "<timer>", event, error, stack }),
 	);
+	/**
+	 * Dedup markers for `tool_call` emission, keyed `${toolCallId}:${toolName}`.
+	 * The agent loop emits `tool_call` at arg-prep time (before scheduling and
+	 * `tool_execution_start`) via the session's `beforeToolCall` wiring; the
+	 * marker tells `ExtensionToolWrapper.execute` not to emit a second event for
+	 * the same dispatch. Keyed by call id + tool name because a nested xd://
+	 * device dispatch reuses the model's toolCallId under a different tool name
+	 * and must still emit its own event. Bounded: markers for calls whose
+	 * execute path never runs (policy deny, validation failure) would otherwise
+	 * accumulate for the session's lifetime.
+	 */
+	#emittedToolCalls = new Set<string>();
+
+	/** Records that the loop already emitted `tool_call` for this dispatch. */
+	markToolCallEmitted(toolCallId: string, toolName: string): void {
+		if (this.#emittedToolCalls.size >= 512) {
+			const oldest = this.#emittedToolCalls.values().next().value;
+			if (oldest !== undefined) this.#emittedToolCalls.delete(oldest);
+		}
+		this.#emittedToolCalls.add(`${toolCallId}:${toolName}`);
+	}
+
+	/** Consumes a {@link markToolCallEmitted} marker; true when the loop already emitted. */
+	consumeToolCallEmitted(toolCallId: string, toolName: string): boolean {
+		return this.#emittedToolCalls.delete(`${toolCallId}:${toolName}`);
+	}
 
 	constructor(
 		private readonly extensions: Extension[],
@@ -637,7 +742,11 @@ export class ExtensionRunner {
 				: undefined;
 		if (signal?.aborted) return undefined;
 		try {
-			const handlerResult = await raceHandlerWithTimeout(Promise.resolve(handler(event, ctx)), timeoutMs, signal);
+			const handlerResult = await raceHandlerWithTimeout(
+				handlerSignal => handler(event, createHandlerContext(ctx, handlerSignal)),
+				timeoutMs,
+				signal,
+			);
 			if (handlerResult === EXTENSION_HANDLER_ABORTED) return undefined;
 			if (handlerResult === EXTENSION_HANDLER_TIMEOUT) {
 				const error = `handler timed out after ${timeoutMs}ms`;
@@ -799,7 +908,10 @@ export class ExtensionRunner {
 
 			for (const handler of handlers) {
 				try {
-					const handlerResult = await raceHandlerWithTimeout(Promise.resolve(handler(event, ctx)), timeoutMs);
+					const handlerResult = await raceHandlerWithTimeout(
+						handlerSignal => handler(event, createHandlerContext(ctx, handlerSignal)),
+						timeoutMs,
+					);
 
 					if (handlerResult === EXTENSION_HANDLER_TIMEOUT) {
 						const error = `handler timed out after ${timeoutMs}ms`;

package/src/extensibility/extensions/types.ts

@@ -1044,7 +1044,6 @@ export interface RegisteredCommand {
 // ============================================================================
 
 /** Handler function type for events */
-// biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statements
 export type ExtensionHandler<E, R = undefined> = (event: E, ctx: ExtensionContext) => Promise<R | void> | R | void;
 
 /** Service tiers accepted by each provider family. */

package/src/extensibility/extensions/wrapper.ts

@@ -157,15 +157,70 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>,
 		context?: AgentToolContext,
 	): Promise<AgentToolResult<TDetails, TParameters>> {
-		// 1. Check approval policy (before extension handlers).
-		// CLI `--auto-approve` / `--yolo` sets approval mode to yolo.
-		// User `tools.approval.<tool>` policies are still applied in all modes.
+		// The agent loop emits `tool_call` at arg-prep time (session
+		// `beforeToolCall` wiring) so a handler revision lands before concurrency
+		// scheduling and `tool_execution_start`. Consume the marker
+		// unconditionally so it cannot go stale; emit here only for dispatches
+		// the loop never saw — nested xd:// device dispatches and direct
+		// (non-loop) execution such as Cursor exec handlers.
+		const loopEmittedToolCall = this.runner.consumeToolCallEmitted(toolCallId, this.tool.name);
+		// Resolve approval settings up front. A `deny` on the original input short-circuits before the
+		// runner is touched — an already-denied tool never emits `tool_call` — while the full gate below
+		// re-resolves against the (possibly revised) input so a handler cannot rewrite into a denied or
+		// newly prompt-gated command and have it run unapproved.
 		const cliAutoApprove = context?.autoApprove === true;
 		const settings: Settings | undefined = context?.settings;
 		const configuredMode = (settings?.get("tools.approvalMode") ?? "yolo") as ApprovalMode;
 		const approvalMode: ApprovalMode = cliAutoApprove ? "yolo" : configuredMode;
 		const userPolicies = (settings?.get("tools.approval") ?? {}) as Record<string, unknown>;
-		const resolvedArgs = approvalArgs(params, context);
+		if (resolveApproval(this.tool, approvalArgs(params, context), approvalMode, userPolicies).policy === "deny") {
+			throw new Error(
+				`Tool "${this.tool.name}" is blocked by user policy.\n` +
+					`To allow: remove "tools.approval.${this.tool.name}: deny" from config.`,
+			);
+		}
+
+		// 1. Emit tool_call event first - extensions can block execution or revise the input the tool
+		// runs with. Doing this BEFORE the approval gate means approval (below) resolves against the
+		// input that actually executes, closing the "approve one thing, run another" gap: the prompt
+		// text, policy resolution, and provider safety checks all see `effectiveParams`.
+		let effectiveParams = params;
+		if (!loopEmittedToolCall && this.runner.hasHandlers("tool_call")) {
+			try {
+				const callResult = (await this.runner.emitToolCall({
+					type: "tool_call",
+					toolName: this.tool.name,
+					toolCallId,
+					input: normalizeToolEventInput(
+						this.tool.name,
+						resolveToolEventInput(this.tool, toolEventArgs(params, context)),
+					),
+				})) as ToolCallEventResult | undefined;
+
+				if (callResult?.block) {
+					const reason = callResult.reason || "Tool execution was blocked by an extension";
+					throw new Error(reason);
+				}
+				// A non-blocking handler may replace the execution input. The returned object is the raw
+				// input passed to `execute` (handler-owned; not re-normalized). Skipped for `computer`
+				// tool calls, whose event input is a synthetic {actions,pendingSafetyChecks} view
+				// (see toolEventArgs) rather than the real execution params.
+				if (callResult?.input !== undefined && context?.toolCall?.providerMetadata?.type !== "computer") {
+					effectiveParams = callResult.input as typeof params;
+				}
+			} catch (err) {
+				if (err instanceof Error) {
+					throw err;
+				}
+				throw new Error(`Extension failed, blocking execution: ${String(err)}`);
+			}
+		}
+
+		// 2. Full approval gate against the (possibly revised) input that will actually run — resolves
+		// policy and prompts on `effectiveParams`, so the user approves exactly what executes. A revised
+		// input that newly resolves to `deny` is caught here even though the original passed the
+		// short-circuit above.
+		const resolvedArgs = approvalArgs(effectiveParams, context);
 		const resolved = resolveApproval(this.tool, resolvedArgs, approvalMode, userPolicies);
 		if (resolved.policy === "deny") {
 			throw new Error(
@@ -175,15 +230,17 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 		}
 		const pendingSafetyChecks = computerSafetyChecks(context);
 		// An xd:// device dispatch already cleared the write tool's outer gate at
-		// this tool's tier — re-prompting would double-ask for one action. Explicit
-		// per-tool "prompt" policies and tool-demanded overrides still prompt.
-		// Provider safety checks are stronger: yolo, per-tool allow, and xdev approval
-		// never acknowledge them on the user's behalf.
+		// this tool's tier — re-prompting would double-ask for one action. The
+		// bypass only holds while the input is exactly what that outer gate
+		// approved: a handler revision here may have raised the tier, so revised
+		// input always faces the full gate. Explicit per-tool "prompt" policies
+		// and tool-demanded overrides still prompt. Provider safety checks are
+		// stronger: yolo, per-tool allow, and xdev approval never acknowledge
+		// them on the user's behalf.
 		const explicitPrompt = resolved.override || Object.hasOwn(userPolicies, this.tool.name);
+		const xdevBypass = context?.xdevApproved === true && effectiveParams === params;
 		const approvalCheck = {
-			required:
-				pendingSafetyChecks.length > 0 ||
-				(resolved.policy === "prompt" && (explicitPrompt || context?.xdevApproved !== true)),
+			required: pendingSafetyChecks.length > 0 || (resolved.policy === "prompt" && (explicitPrompt || !xdevBypass)),
 			reason: resolved.reason,
 		};
 
@@ -202,7 +259,7 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 				});
 			}
 
-			const resolveApproval = async (approved: boolean, reason?: string) => {
+			const emitApprovalResolved = async (approved: boolean, reason?: string) => {
 				if (!hasApprovalHandlers) return;
 				await this.runner.emit({
 					type: "tool_approval_resolved",
@@ -218,7 +275,7 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 			// ordinary tier approval, no setting or yolo mode may bypass this gate.
 			if (!this.runner.hasUI()) {
 				const reason = "no interactive UI available";
-				await resolveApproval(false, reason);
+				await emitApprovalResolved(false, reason);
 				if (pendingSafetyChecks.length > 0) {
 					throw new Error(
 						`Tool "${this.tool.name}" has pending provider safety checks but no interactive UI is available.`,
@@ -243,11 +300,11 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 			try {
 				choice = await uiContext.select(safetyPrompt, ["Approve", "Deny"]);
 			} catch (err) {
-				await resolveApproval(false, err instanceof Error ? err.message : "approval aborted");
+				await emitApprovalResolved(false, err instanceof Error ? err.message : "approval aborted");
 				throw err;
 			}
 			const approved = choice === "Approve";
-			await resolveApproval(approved, approved ? undefined : "denied by user");
+			await emitApprovalResolved(approved, approved ? undefined : "denied by user");
 			if (!approved) {
 				throw new Error(`Tool call denied by user: ${this.tool.name}`);
 			}
@@ -257,37 +314,12 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 			}
 		}
 
-		// 2. Emit tool_call event - extensions can block execution
-		if (this.runner.hasHandlers("tool_call")) {
-			try {
-				const callResult = (await this.runner.emitToolCall({
-					type: "tool_call",
-					toolName: this.tool.name,
-					toolCallId,
-					input: normalizeToolEventInput(
-						this.tool.name,
-						resolveToolEventInput(this.tool, toolEventArgs(params, context)),
-					),
-				})) as ToolCallEventResult | undefined;
-
-				if (callResult?.block) {
-					const reason = callResult.reason || "Tool execution was blocked by an extension";
-					throw new Error(reason);
-				}
-			} catch (err) {
-				if (err instanceof Error) {
-					throw err;
-				}
-				throw new Error(`Extension failed, blocking execution: ${String(err)}`);
-			}
-		}
-
 		// Execute the actual tool
 		let result: AgentToolResult<TDetails, TParameters>;
 		let executionError: Error | undefined;
 
 		try {
-			result = await this.tool.execute(toolCallId, params, signal, onUpdate, context);
+			result = await this.tool.execute(toolCallId, effectiveParams, signal, onUpdate, context);
 		} catch (err) {
 			executionError = err instanceof Error ? err : new Error(String(err));
 			result = {
@@ -304,7 +336,7 @@ export class ExtensionToolWrapper<TParameters extends TSchema = TSchema, TDetail
 				toolCallId,
 				input: normalizeToolEventInput(
 					this.tool.name,
-					resolveToolEventInput(this.tool, toolEventArgs(params, context)),
+					resolveToolEventInput(this.tool, toolEventArgs(effectiveParams, context)),
 				),
 				content: result.content,
 				details: result.details,

package/src/extensibility/hooks/tool-wrapper.ts

@@ -39,8 +39,9 @@ export class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = u
 		onUpdate?: AgentToolUpdateCallback<TDetails, TParameters>,
 		context?: AgentToolContext,
 	) {
-		// Emit tool_call event - hooks can block execution
+		// Emit tool_call event - hooks can block execution or revise the input the tool runs with.
 		// If hook errors/times out, block by default (fail-safe)
+		let effectiveParams = params;
 		if (this.hookRunner.hasHandlers("tool_call")) {
 			try {
 				const callResult = (await this.hookRunner.emitToolCall({
@@ -57,6 +58,12 @@ export class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = u
 					const reason = callResult.reason || "Tool execution was blocked by a hook";
 					throw new Error(reason);
 				}
+				// A non-blocking handler may replace the execution input. The returned object is the raw
+				// input the tool runs with (handler-owned); it is not re-normalized. Skipped for `computer`
+				// tool calls, whose real parameters are not represented by the event input.
+				if (callResult?.input !== undefined && context?.toolCall?.providerMetadata?.type !== "computer") {
+					effectiveParams = callResult.input as Static<TParameters>;
+				}
 			} catch (err) {
 				// Hook error or block - throw to mark as error
 				if (err instanceof Error) {
@@ -68,7 +75,7 @@ export class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = u
 
 		// Execute the actual tool, forwarding onUpdate for progress streaming
 		try {
-			const result = await this.tool.execute(toolCallId, params, signal, onUpdate, context);
+			const result = await this.tool.execute(toolCallId, effectiveParams, signal, onUpdate, context);
 
 			// Emit tool_result event - hooks can modify the result
 			if (this.hookRunner.hasHandlers("tool_result")) {
@@ -78,7 +85,7 @@ export class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = u
 					toolCallId,
 					input: normalizeToolEventInput(
 						this.tool.name,
-						resolveToolEventInput(this.tool, params as Record<string, unknown>),
+						resolveToolEventInput(this.tool, effectiveParams as Record<string, unknown>),
 					),
 					content: result.content,
 					details: result.details,
@@ -104,7 +111,7 @@ export class HookToolWrapper<TParameters extends TSchema = TSchema, TDetails = u
 					toolCallId,
 					input: normalizeToolEventInput(
 						this.tool.name,
-						resolveToolEventInput(this.tool, params as Record<string, unknown>),
+						resolveToolEventInput(this.tool, effectiveParams as Record<string, unknown>),
 					),
 					content: [{ type: "text", text: err instanceof Error ? err.message : String(err) }],
 					details: undefined,

package/src/extensibility/hooks/types.ts

@@ -444,7 +444,6 @@ export type {
  * Handler function type for each event.
  * Handlers can return R, undefined, or void (bare return statements).
  */
-// biome-ignore lint/suspicious/noConfusingVoidType: void allows bare return statements in handlers
 export type HookHandler<E, R = undefined> = (event: E, ctx: HookContext) => Promise<R | void> | R | void;
 
 export interface HookMessageRenderOptions {

package/src/extensibility/shared-events.ts

@@ -289,13 +289,30 @@ export interface TodoReminderEvent {
 
 /**
  * Return type for `tool_call` handlers.
- * Allows handlers to block tool execution.
+ * Allows handlers to block tool execution or revise the input the tool runs with.
  */
 export interface ToolCallEventResult {
 	/** If true, block the tool from executing */
 	block?: boolean;
 	/** Reason for blocking (returned to LLM as error) */
 	reason?: string;
+	/**
+	 * Replacement input the tool executes with, instead of the original arguments. Ignored when
+	 * `block` is true. This is the raw execution input passed to the tool's `execute` (the handler
+	 * owns its correctness) — not the normalized `event.input` view, which may carry derived
+	 * gate-only fields (e.g. hashline `edit` `path`/`paths`) that are not real parameters. When
+	 * multiple handlers set `input`, the last one wins; handlers do not observe each other's
+	 * revisions (each sees the original `event.input`). Not applied to `computer` tool calls.
+	 *
+	 * For model-issued tool calls the event fires at arg-prep time in the agent loop, before
+	 * concurrency scheduling, `tool_execution_start`, and the approval gate: the revision is
+	 * revalidated against the tool schema and becomes what the loop schedules, displays, persists,
+	 * and executes — the user always approves what actually runs. For dispatches the loop never
+	 * sees (nested `write xd://` device calls, Cursor direct execution) the tool wrapper applies
+	 * the revision before its own approval gate; a revised nested xd:// input forfeits the outer
+	 * write gate's approval and faces the full prompt again.
+	 */
+	input?: Record<string, unknown>;
 }
 
 /**

package/src/internal-urls/mcp-protocol.ts

@@ -21,6 +21,15 @@ function getUriTemplateMatchScore(
 }
 
 function extractResourceUri(url: InternalUrl): string {
+	const scheme = url.protocol.replace(/:$/, "").toLowerCase();
+	if (scheme !== "mcp") {
+		// Server-advertised native URI (hierarchical or opaque). Preserve the
+		// input byte-for-byte: `resolveTargetServer` matches by exact string
+		// equality, so e.g. `catalog://root/` must keep its trailing slash.
+		return url.rawHref ?? url.href;
+	}
+	// Legacy `mcp://<resource-uri>` wrapper: reconstruct the wrapped URI and
+	// elide a bare trailing `/` that URL parsing adds to host-only forms.
 	const host = url.rawHost || url.hostname;
 	const rawPathname = url.rawPathname ?? url.pathname;
 	const hasPath = rawPathname && rawPathname !== "/";
@@ -95,10 +104,11 @@ function formatAvailableResources(mcpManager: MCPManager): string {
 }
 
 /**
- * Protocol handler for mcp:// URLs.
+ * Protocol handler for MCP resources.
  *
- * URL form:
+ * URL forms:
  * - mcp://<resource-uri> (e.g. mcp://test://notes, mcp://ibkr://portfolio/positions)
+ * - A resource's native URI when its scheme has no OMP handler (e.g. ags://capabilities/current-host)
  */
 export class McpProtocolHandler implements ProtocolHandler {
 	readonly scheme = "mcp";
@@ -111,7 +121,11 @@ export class McpProtocolHandler implements ProtocolHandler {
 		}
 
 		const uri = extractResourceUri(url);
-		const targetServer = resolveTargetServer(mcpManager, uri);
+		let targetServer = resolveTargetServer(mcpManager, uri);
+		if (!targetServer) {
+			await Promise.allSettled(mcpManager.getConnectedServers().map(name => mcpManager.ensureServerResources(name)));
+			targetServer = resolveTargetServer(mcpManager, uri);
+		}
 		if (!targetServer) {
 			throw new Error(
 				`No MCP server has resource "${uri}".\n\nAvailable resources:\n${formatAvailableResources(mcpManager)}`,

package/src/internal-urls/parse.ts

@@ -13,6 +13,36 @@ import type { InternalUrl } from "./types";
 
 const SCHEME_HOST_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)/i;
 const PATHNAME_RE = /^[a-z][a-z0-9+.-]*:\/\/[^/?#]*(\/[^?#]*)?/i;
+// Opaque URI form (`urn:example:document`, `custom:item`) — an RFC 3986 scheme
+// followed by `:` without `//`. Guarded separately in `extractUriScheme`.
+const OPAQUE_URI_RE = /^([a-z][a-z0-9+.-]*):(.+)$/is;
+// A read-tool selector chain (`12`, `1-20,30+5`, `raw`, `raw:2-4`, `conflicts`)
+// so `Makefile:12` or `notes:raw` is not mistaken for an opaque URI.
+const SELECTOR_CHUNK_SRC = String.raw`(?:raw|conflicts|-?\d+(?:[-+]\d+)?(?:,\d+(?:[-+]\d+)?)*)`;
+const SELECTOR_CHAIN_RE = new RegExp(`^${SELECTOR_CHUNK_SRC}(?::${SELECTOR_CHUNK_SRC})*$`, "i");
+
+/**
+ * Extract the lowercased scheme from a URI-shaped input, or `undefined` when
+ * the input does not look like a URI.
+ *
+ * Accepts both hierarchical (`scheme://…`) and opaque (`scheme:rest`) forms —
+ * MCP resource URIs may be opaque (`urn:example:document`, `custom:item`).
+ * The opaque form is guarded against path-like false positives:
+ * - Windows drive paths (`C:\…`, `C:/…`, `C:foo`) — single-letter scheme.
+ * - Filenames with extensions (`foo.ts:50`) — dot in the scheme segment.
+ * - Read-tool selector tails (`Makefile:12`, `README:raw:1-20`).
+ */
+export function extractUriScheme(input: string): string | undefined {
+	const hierarchical = input.match(SCHEME_HOST_RE);
+	if (hierarchical) return hierarchical[1].toLowerCase();
+	const opaque = input.match(OPAQUE_URI_RE);
+	if (!opaque) return undefined;
+	const [, scheme, rest] = opaque;
+	if (scheme.length === 1) return undefined;
+	if (scheme.includes(".")) return undefined;
+	if (SELECTOR_CHAIN_RE.test(rest)) return undefined;
+	return scheme.toLowerCase();
+}
 
 /**
  * Parse an internal URL into an InternalUrl.
@@ -68,5 +98,6 @@ export function parseInternalUrl(input: string): InternalUrl {
 	const result = parsed as InternalUrl;
 	result.rawHost = rawHost;
 	result.rawPathname = pathMatch?.[1] ?? parsed.pathname;
+	result.rawHref = input;
 	return result;
 }

package/src/internal-urls/router.ts

@@ -13,7 +13,7 @@ import { LocalProtocolHandler } from "./local-protocol";
 import { McpProtocolHandler } from "./mcp-protocol";
 import { MemoryProtocolHandler } from "./memory-protocol";
 import { OmpProtocolHandler } from "./omp-protocol";
-import { parseInternalUrl } from "./parse";
+import { extractUriScheme, parseInternalUrl } from "./parse";
 import { RuleProtocolHandler } from "./rule-protocol";
 import { SkillProtocolHandler } from "./skill-protocol";
 import { SshProtocolHandler } from "./ssh-protocol";
@@ -79,6 +79,20 @@ export class InternalUrlRouter {
 		return this.#handlers.has(match[1].toLowerCase());
 	}
 
+	/**
+	 * Whether read can resolve this URL through either a native handler or the
+	 * MCP resource fallback. MCP resources may use arbitrary custom schemes and
+	 * may be opaque (`urn:example:document`) rather than hierarchical.
+	 */
+	canResolve(input: string): boolean {
+		const scheme = extractUriScheme(input);
+		if (!scheme) return false;
+		// Registered handlers only accept the hierarchical `scheme://` form;
+		// opaque inputs reach the MCP resource fallback alone.
+		if (this.#handlers.has(scheme)) return this.canHandle(input);
+		return this.#isMcpResourceScheme(scheme);
+	}
+
 	/** Schemes whose handler supports host/path autocomplete. */
 	completionSchemes(): string[] {
 		const schemes: string[] = [];
@@ -98,10 +112,16 @@ export class InternalUrlRouter {
 		return handler.complete(query, context);
 	}
 
-	#route(input: string): { parsed: InternalUrl; handler: ProtocolHandler } {
+	#isMcpResourceScheme(scheme: string): boolean {
+		return !["file", "http", "https"].includes(scheme) && this.#handlers.has("mcp");
+	}
+
+	#route(input: string, allowMcpResource = false): { parsed: InternalUrl; handler: ProtocolHandler } {
 		const parsed = parseInternalUrl(input);
 		const scheme = parsed.protocol.replace(/:$/, "").toLowerCase();
-		const handler = this.#handlers.get(scheme);
+		const handler =
+			this.#handlers.get(scheme) ??
+			(allowMcpResource && this.#isMcpResourceScheme(scheme) ? this.#handlers.get("mcp") : undefined);
 		if (!handler) {
 			const available = Array.from(this.#handlers.keys())
 				.map(candidate => `${candidate}://`)
@@ -113,7 +133,7 @@ export class InternalUrlRouter {
 
 	/** Resolve an internal URL through its registered protocol handler. */
 	async resolve(input: string, context?: ResolveContext): Promise<InternalResource> {
-		const { parsed, handler } = this.#route(input);
+		const { parsed, handler } = this.#route(input, true);
 		const resource = await handler.resolve(parsed, context);
 		return { ...resource, immutable: resource.immutable ?? handler.immutable };
 	}

package/src/internal-urls/types.ts

@@ -70,6 +70,12 @@ export interface InternalUrl extends URL {
 	 * Raw pathname extracted from input, preserving traversal markers before URL normalization.
 	 */
 	rawPathname?: string;
+	/**
+	 * Exact input string this URL was parsed from, before any normalization.
+	 * Set by `parseInternalUrl`; used where byte-exact URI matching matters
+	 * (e.g. MCP resource URIs compared by string equality).
+	 */
+	rawHref?: string;
 }
 
 /**

package/src/live/transport.ts

@@ -1,5 +1,5 @@
 import { type AuthStorage, isAuthRetryableError, type OAuthAccess, withOAuthAccess } from "@oh-my-pi/pi-ai";
-import { getProxyForProvider, wrapFetchForProxy } from "@oh-my-pi/pi-ai/utils/proxy";
+import { getProxyForUrl, wrapFetchForProxy } from "@oh-my-pi/pi-ai/utils/proxy";
 import {
 	CODEX_BASE_URL,
 	CODEX_CLIENT_VERSION,
@@ -252,7 +252,7 @@ export class CodexLiveTransport {
 		const url = buildLiveSidebandUrl(callId);
 		const options = {
 			headers: liveSessionHeaders(access, this.#options.sessionId, this.#realtimeSessionId, attestation),
-			proxy: getProxyForProvider(LIVE_PROVIDER),
+			proxy: getProxyForUrl(LIVE_PROVIDER, new URL(url)),
 		} satisfies Bun.WebSocketOptions;
 		const socket: Bun.WebSocket = Reflect.construct(WebSocket, [url, options]);
 		socket.binaryType = "nodebuffer";

package/src/lsp/client.ts

@@ -918,7 +918,7 @@ export async function ensureFileOpen(client: LspClient, filePath: string, signal
 			if (isEnoent(err)) return;
 			throw err;
 		}
-		const languageId = detectLanguageId(filePath);
+		const languageId = client.config.languageId ?? detectLanguageId(filePath);
 		throwIfAborted(signal);
 
 		await sendNotification(
@@ -992,7 +992,7 @@ export async function syncContent(
 
 		if (!info) {
 			// Open file with provided content instead of reading from disk
-			const languageId = detectLanguageId(filePath);
+			const languageId = client.config.languageId ?? detectLanguageId(filePath);
 			throwIfAborted(signal);
 			await sendNotification(
 				client,