@oh-my-pi/pi-coding-agent 17.1.6 → 17.1.8

package/src/discovery/claude-plugins.ts

@@ -41,6 +41,20 @@ interface ResolvedPluginDir {
 	warnings: string[];
 }
 
+interface ResolvedMCPConfig {
+	/** On-disk config file to read, or null when servers are inline or nothing applies. */
+	path: string | null;
+	/** Server map declared inline in the plugin manifest, or null when the source is a file. */
+	inlineServers: Record<string, unknown> | null;
+	/** Path recorded as each discovered server's capability source. */
+	sourcePath: string;
+	/** Directory that relative stdio `command`/`cwd` values resolve against. */
+	baseDir: string;
+	/** True when a plugin manifest named this source, false for the conventional fallback. */
+	declared: boolean;
+	warnings: string[];
+}
+
 async function readPluginManifest(root: ClaudePluginRoot): Promise<ClaudePluginManifest | null> {
 	const manifestPath = path.join(root.path, ".claude-plugin", "plugin.json");
 	const raw = await readFile(manifestPath);
@@ -375,50 +389,144 @@ async function loadTools(ctx: LoadContext): Promise<LoadResult<CustomTool>> {
 // MCP Servers
 // =============================================================================
 
-async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
-	const items: MCPServer[] = [];
-	const warnings: string[] = [];
-
-	const { roots, warnings: rootWarnings } = await listClaudePluginRoots(ctx.home, ctx.cwd);
-	warnings.push(...rootWarnings);
+/**
+ * Unwrap a parsed MCP config file to its server map. Supports the nested
+ * `{ mcpServers: { … } }` project shape and the flat `{ name: cfg, … }`
+ * marketplace-plugin shape. Returns null when a `mcpServers` field is present
+ * but not an object map (malformed) so the caller skips the file.
+ */
+function extractServerMap(obj: Record<string, unknown>): Record<string, unknown> | null {
+	if (isRecord(obj.mcpServers)) return obj.mcpServers;
+	if (!("mcpServers" in obj)) return obj;
+	return null;
+}
 
-	for (const root of roots) {
-		const mcpPath = path.join(root.path, ".mcp.json");
-		const raw = await readFile(mcpPath);
-		if (raw === null) continue; // file absent — skip silently
+/**
+ * Resolve where a plugin's MCP servers come from, honoring the manifest's
+ * `mcpServers` field before the conventional root `.mcp.json`.
+ *
+ * `.omp-plugin/plugin.json` takes precedence over `.claude-plugin/plugin.json`.
+ * The field may be an inline object (the server map itself) or a string path to
+ * a config file within the plugin root; a path escaping the root is rejected
+ * with a warning. When no manifest declares the field, `<root>/.mcp.json` is the
+ * fallback source.
+ */
+async function resolvePluginMCPConfig(root: ClaudePluginRoot): Promise<ResolvedMCPConfig> {
+	const fallback = path.join(root.path, ".mcp.json");
+	for (const manifestDir of [".omp-plugin", ".claude-plugin"]) {
+		const manifestPath = path.join(root.path, manifestDir, "plugin.json");
+		const raw = await readFile(manifestPath);
+		if (raw === null) continue;
 
 		let parsed: unknown;
 		try {
 			parsed = JSON.parse(raw);
 		} catch {
-			warnings.push(`[claude-plugins] Invalid JSON in ${mcpPath}`);
-			logger.warn(`[claude-plugins] Invalid JSON in ${mcpPath}`);
 			continue;
 		}
+		if (!isRecord(parsed)) continue;
+		const pointer = parsed.mcpServers;
+
+		// Inline object form: the manifest value is the server map itself, rooted
+		// at the plugin directory (Claude's ${CLAUDE_PLUGIN_ROOT} base).
+		if (isRecord(pointer)) {
+			return {
+				path: null,
+				inlineServers: pointer,
+				sourcePath: manifestPath,
+				baseDir: root.path,
+				declared: true,
+				warnings: [],
+			};
+		}
+
+		// File-pointer form: resolve the named config file within the plugin root.
+		if (typeof pointer === "string") {
+			const configured = pointer.trim();
+			if (configured.length === 0) continue;
+			const resolved = path.resolve(root.path, configured);
+			if (!isWithinPluginRoot(root.path, resolved)) {
+				return {
+					path: null,
+					inlineServers: null,
+					sourcePath: manifestPath,
+					baseDir: root.path,
+					declared: true,
+					warnings: [
+						`[claude-plugins] Ignoring mcpServers path outside plugin root for ${root.id}: ${configured}`,
+					],
+				};
+			}
+			return {
+				path: resolved,
+				inlineServers: null,
+				sourcePath: resolved,
+				baseDir: path.dirname(resolved),
+				declared: true,
+				warnings: [],
+			};
+		}
+	}
+
+	return {
+		path: fallback,
+		inlineServers: null,
+		sourcePath: fallback,
+		baseDir: path.dirname(fallback),
+		declared: false,
+		warnings: [],
+	};
+}
+
+async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>> {
+	const items: MCPServer[] = [];
+	const warnings: string[] = [];
 
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) continue;
-		const obj = parsed as Record<string, unknown>;
-
-		// Two shapes are supported:
-		//   nested: { "mcpServers": { name: cfg, ... } }   (OMP/Claude Code project shape)
-		//   flat:   { name: cfg, ... }                      (Claude marketplace plugin shape)
-		// If "mcpServers" is present and an object, treat it as the canonical map.
-		// Otherwise, treat the whole object as the server map.
-		let servers: Record<string, unknown>;
-		if (
-			obj.mcpServers !== undefined &&
-			obj.mcpServers !== null &&
-			typeof obj.mcpServers === "object" &&
-			!Array.isArray(obj.mcpServers)
-		) {
-			servers = obj.mcpServers as Record<string, unknown>;
-		} else if (!("mcpServers" in obj)) {
-			servers = obj;
+	const { roots, warnings: rootWarnings } = await listClaudePluginRoots(ctx.home, ctx.cwd);
+	warnings.push(...rootWarnings);
+
+	for (const root of roots) {
+		const resolved = await resolvePluginMCPConfig(root);
+		warnings.push(...resolved.warnings);
+
+		let servers: Record<string, unknown> | null;
+		if (resolved.inlineServers) {
+			servers = resolved.inlineServers;
+		} else if (resolved.path !== null) {
+			const raw = await readFile(resolved.path);
+			if (raw === null) {
+				// The conventional fallback is optional, but a manifest that names a
+				// missing file is an authoring error that would otherwise register
+				// zero servers with no explanation.
+				if (resolved.declared) {
+					const warning = `[claude-plugins] Missing mcpServers file declared by ${root.id}: ${resolved.path}`;
+					warnings.push(warning);
+					logger.warn(warning);
+				}
+				continue;
+			}
+
+			let parsed: unknown;
+			try {
+				parsed = JSON.parse(raw);
+			} catch {
+				warnings.push(`[claude-plugins] Invalid JSON in ${resolved.path}`);
+				logger.warn(`[claude-plugins] Invalid JSON in ${resolved.path}`);
+				continue;
+			}
+			// Two file shapes are supported:
+			//   nested: { "mcpServers": { name: cfg, ... } }   (OMP/Claude Code project shape)
+			//   flat:   { name: cfg, ... }                      (Claude marketplace plugin shape)
+			if (!isRecord(parsed)) continue;
+			servers = extractServerMap(parsed);
 		} else {
 			continue;
 		}
+		if (servers === null) continue;
 
-		for (const [serverName, serverCfg] of Object.entries(servers)) {
+		const { sourcePath, baseDir } = resolved;
+		for (const serverName in servers) {
+			const serverCfg = servers[serverName];
 			if (!serverCfg || typeof serverCfg !== "object" || Array.isArray(serverCfg)) continue;
 			const raw = serverCfg as {
 				enabled?: boolean;
@@ -437,7 +545,9 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 			// occasionally ship .mcp.json entries with neither, which would register a useless
 			// server and surface as a connection error at runtime.
 			if (typeof raw.command !== "string" && typeof raw.url !== "string") {
-				warnings.push(`[claude-plugins] Skipping MCP server "${serverName}" in ${mcpPath}: missing command or url`);
+				warnings.push(
+					`[claude-plugins] Skipping MCP server "${serverName}" in ${sourcePath}: missing command or url`,
+				);
 				continue;
 			}
 			const namespacedName = root.plugin ? `${root.plugin}:${serverName}` : serverName;
@@ -446,7 +556,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 			const substitutedCwd = raw.cwd !== undefined ? substitutePluginRoot(raw.cwd, root.path) : undefined;
 			// Root relative command/cwd at the plugin's config directory, not the
 			// session cwd (MCP stdio spawning resolves relative values there).
-			const rooted = resolvePluginStdioPaths({ command: substitutedCommand, cwd: substitutedCwd }, root.path);
+			const rooted = resolvePluginStdioPaths({ command: substitutedCommand, cwd: substitutedCwd }, baseDir);
 			const server: MCPServer = {
 				name: namespacedName,
 				...(raw.enabled !== undefined && { enabled: raw.enabled }),
@@ -460,7 +570,7 @@ async function loadMCPServers(ctx: LoadContext): Promise<LoadResult<MCPServer>>
 				...(raw.auth !== undefined && { auth: raw.auth }),
 				...(raw.oauth !== undefined && { oauth: raw.oauth }),
 				...(raw.type !== undefined && { transport: raw.type as MCPServer["transport"] }),
-				_source: createSourceMeta(PROVIDER_ID, mcpPath, root.scope),
+				_source: createSourceMeta(PROVIDER_ID, sourcePath, root.scope),
 			};
 			items.push(server);
 		}

package/src/export/html/index.ts

@@ -1,4 +1,4 @@
-import * as fs from "node:fs/promises";
+import * as fs from "node:fs";
 import * as path from "node:path";
 import type { AgentState } from "@oh-my-pi/pi-agent-core";
 import { APP_NAME, isEnoent } from "@oh-my-pi/pi-utils";
@@ -7,31 +7,38 @@ import type { SessionEntry, SessionHeader } from "../../session/session-entries"
 import { loadEntriesFromFile } from "../../session/session-loader";
 import { SessionManager } from "../../session/session-manager";
 import type { ExportThemeNames } from "./args";
-import templateCss from "./template.css" with { type: "text" };
-import templateHtml from "./template.html" with { type: "text" };
-import templateJs from "./template.js" with { type: "text" };
+import templateCssPath from "./template.css" with { type: "file" };
+import templateHtmlPath from "./template.html" with { type: "file" };
+import templateJsPath from "./template.js" with { type: "file" };
 // Pre-built React tool renderers: built by `gen:tool-views` (`bun run gen:tool-views`),
 // run automatically by root `prepare` on install and by `prepack` at publish.
-import toolViewsJs from "./tool-views.generated.js" with { type: "text" };
+import toolViewsJsPath from "./tool-views.generated.js" with { type: "file" };
 import { webExportThemeVars } from "./web-palette";
 
 export { type ExportThemeNames, parseExportArgs } from "./args";
 
 let cachedTemplate: string | undefined;
+/** Resolve a Bun file-loader value without parsing Windows drive letters as URL schemes. */
+export function resolveBundledHtmlAssetPath(assetPath: string, moduleDir: string = import.meta.dir): string {
+	if (path.isAbsolute(assetPath) || path.win32.isAbsolute(assetPath)) return assetPath;
+	return path.resolve(moduleDir, assetPath);
+}
 
 /** Compose the standalone export template: minified CSS, tool renderers, and viewer JS inlined. */
 export function getTemplate(): string {
 	if (cachedTemplate) return cachedTemplate;
+	const templateCss = fs.readFileSync(resolveBundledHtmlAssetPath(templateCssPath), "utf8");
+	const templateHtml = fs.readFileSync(resolveBundledHtmlAssetPath(templateHtmlPath as unknown as string), "utf8");
+	const templateJs = fs.readFileSync(resolveBundledHtmlAssetPath(templateJsPath), "utf8");
+	const toolViewsJs = fs.readFileSync(resolveBundledHtmlAssetPath(toolViewsJsPath), "utf8");
 	const minifiedCss = templateCss
 		.replace(/\/\*[\s\S]*?\*\//g, "")
 		.replace(/\s+/g, " ")
 		.replace(/\s*([{}:;,])\s*/g, "$1")
 		.trim();
 	// Function replacements so `$'`, `$&`, `$$`, etc. inside the embedded
-	// CSS/JS are not interpreted as substitution patterns. The cast is safe:
-	// `with { type: "text" }` yields a string at runtime; bun-types just types
-	// every *.html import as HTMLBundle (TS can't vary types by import attribute).
-	cachedTemplate = (templateHtml as unknown as string)
+	// CSS/JS are not interpreted as substitution patterns.
+	cachedTemplate = templateHtml
 		.replace("<template-css/>", () => `<style>${minifiedCss}</style>`)
 		.replace("<template-tool-views/>", () => `<script>${toolViewsJs}</script>`)
 		.replace("<template-js/>", () => `<script>${templateJs}</script>`);
@@ -207,7 +214,7 @@ async function collectSubSessionsFromDir(
 ): Promise<void> {
 	let names: string[];
 	try {
-		names = await fs.readdir(dir);
+		names = await fs.promises.readdir(dir);
 	} catch (err) {
 		if (isEnoent(err)) return;
 		throw err;

package/src/extensibility/extensions/runner.ts

@@ -356,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[],

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/legacy-pi-ai-shim.ts

@@ -19,7 +19,7 @@
  * `types.ts` via the `export *` below — pi-ai still exports both as types,
  * only the runtime `Type` builder and `StringEnum()` helper were removed.
  */
-import type { Api, Model } from "@oh-my-pi/pi-ai";
+import type { Api, AssistantMessage, Model } from "@oh-my-pi/pi-ai";
 import type { Effort } from "@oh-my-pi/pi-catalog/effort";
 import { clampThinkingLevelForModel } from "@oh-my-pi/pi-catalog/model-thinking";
 import {
@@ -80,6 +80,33 @@ export function clampThinkingLevel<TApi extends Api>(model: Model<TApi>, level:
 	return clampThinkingLevelForModel(model, level) ?? "off";
 }
 
+/**
+ * Provider-error classification patterns ported verbatim from historical pi-ai
+ * (`@earendil-works/pi-ai` `utils/retry.ts`). Legacy extensions call
+ * {@link isRetryableAssistantError} to decide whether to restart a failed
+ * assistant turn, so the wording tables must match the upstream semantics they
+ * were authored against rather than OMP's own `Error`-based classifiers.
+ */
+const NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN =
+	/GoUsageLimitError|FreeUsageLimitError|Monthly usage limit reached|available balance|insufficient_quota|out of budget|quota exceeded|billing/i;
+const RETRYABLE_PROVIDER_ERROR_PATTERN =
+	/overloaded|rate.?limit|too many requests|429|500|502|503|504|524|service.?unavailable|server.?error|internal.?error|provider.?returned.?error|network.?error|connection.?error|connection.?refused|connection.?lost|other side closed|fetch failed|getaddrinfo|ENOTFOUND|EAI_AGAIN|upstream.?connect|reset before headers|socket hang up|socket connection was closed|timed? out|timeout|terminated|websocket.?closed|websocket.?error|ended without|stream ended before message_stop|stream ended before a terminal response event|http2 request did not get a response|retry delay|you can retry your request|try your request again|please retry your request|ResourceExhausted/i;
+
+/**
+ * Compatibility implementation of historical pi-ai's `isRetryableAssistantError`.
+ *
+ * Classifies whether a failed assistant message looks like a transient provider
+ * or transport error so legacy extensions can decide if the last assistant turn
+ * should be restarted. Account/quota limits are treated as non-retryable. This
+ * does not implement any retry policy; callers own budget, backoff, and reporting.
+ */
+export function isRetryableAssistantError(message: AssistantMessage): boolean {
+	if (message.stopReason !== "error" || !message.errorMessage) return false;
+	const errorMessage = message.errorMessage;
+	if (NON_RETRYABLE_PROVIDER_LIMIT_ERROR_PATTERN.test(errorMessage)) return false;
+	return RETRYABLE_PROVIDER_ERROR_PATTERN.test(errorMessage);
+}
+
 export * from "@oh-my-pi/pi-ai";
 /**
  * Compatibility re-exports for catalog symbols that pi-ai historically exposed
@@ -93,3 +120,21 @@ export * from "@oh-my-pi/pi-ai";
 export { calculateCost, getBundledModel, getBundledModels, getBundledProviders, modelsAreEqual, Type };
 export const getModel = getBundledModel;
 export const getModels = getBundledModels;
+
+/**
+ * Compatibility re-exports for runtime helpers that upstream
+ * `@earendil-works/pi-ai` exposed from its package root but omp's
+ * `@oh-my-pi/pi-ai` barrel no longer forwards. Each symbol still exists in the
+ * host graph — only its root re-export was dropped — so bridging it here keeps
+ * legacy extensions importing it from the pi-ai root resolving through Bun's
+ * static named-export check (e.g. `omp plugin install pi-blackhole`).
+ *
+ * This is the full set derived from an audit of the upstream root surface: the
+ * error-classification predicate `isContextOverflow` (now under
+ * `@oh-my-pi/pi-ai/error`) and the JSON-repair helpers that omp relocated to
+ * `@oh-my-pi/pi-utils`. Upstream root symbols with no omp equivalent are
+ * intentionally not shimmed — the package has diverged and there is nothing to
+ * forward.
+ */
+export { isContextOverflow } from "@oh-my-pi/pi-ai/error";
+export { parseJsonWithRepair, parseStreamingJson, repairJson } from "@oh-my-pi/pi-utils";

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>;
 }
 
 /**