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

package/dist/types/utils/inspect-image-mode.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Effective-state resolution for the `inspect_image` tool.
+ *
+ * The tool delegates image understanding to a (possibly different)
+ * vision-capable model. That indirection is only useful when the active model
+ * cannot consume images itself; when it can (`model.input` includes
+ * `"image"`), the tool is redundant and its presence actively degrades the
+ * `read` tool, which reduces image reads to metadata-only plus an
+ * inspect_image suggestion. `auto` mode therefore exposes the tool only for
+ * models without native image input. `on`/`off` force registration regardless
+ * of model capability. A session-scoped override (the `/vision` command)
+ * takes precedence over the persisted setting for the current session only.
+ */
+import type { Model } from "@oh-my-pi/pi-ai";
+import type { Settings } from "../config/settings.js";
+export type InspectImageMode = "auto" | "on" | "off";
+export declare const INSPECT_IMAGE_MODES: readonly ["auto", "on", "off"];
+/** Minimal session surface needed to resolve the effective inspect_image state. */
+export interface InspectImageModeContext {
+    settings: Pick<Settings, "get">;
+    getActiveModel?: () => Model | undefined;
+    getInspectImageModeOverride?: () => InspectImageMode | undefined;
+}
+/**
+ * Whether the `inspect_image` tool should be registered/active right now.
+ * `auto` registers it only when the active model lacks native image input;
+ * an unresolved model is treated as text-only so the tool stays available.
+ */
+export declare function isInspectImageToolActive(session: InspectImageModeContext): boolean;

package/dist/types/utils/profile-tree.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Shared display-tree machinery for profile summaries (macOS `sample` reports,
+ * V8 `.cpuprofile` files). Callers build {@link ProfileNode} trees with a
+ * domain-specific metric (on-CPU samples, self microseconds, …); this module
+ * merges same-key siblings, flattens direct recursion, collapses pass-through
+ * chains, and renders the pruned hot-path tree.
+ */
+/** Display node: merged, recursion-flattened mirror of a profile subtree. */
+export interface ProfileNode {
+    /** Merge/recursion identity (demangled symbol, function@call-site, …). */
+    key: string;
+    /** Human-readable label; recursion and truncation decorations are applied at render time. */
+    label: string;
+    /** Inclusive metric for this subtree (on-CPU samples, self µs, …); drives pruning and display. */
+    value: number;
+    /** Levels of direct recursion flattened into this node. */
+    recursion: number;
+    children: ProfileNode[];
+}
+/** Merge `b` into `a` (same key), combining values and child lists. */
+export declare function mergeInto(a: ProfileNode, b: ProfileNode): void;
+/**
+ * Flatten direct recursion: children carrying the node's own key are dissolved
+ * into it (their children promoted and merged), so a 15-deep recursive spine
+ * renders as one annotated node.
+ */
+export declare function flattenRecursion(node: ProfileNode): void;
+/** `n` as a percentage of `total`, one decimal (`"12.3%"`); `"0%"` when total is empty. */
+export declare function formatPct(n: number, total: number): string;
+/** Options for {@link renderProfileNode}. */
+export interface RenderTreeContext {
+    out: string[];
+    /** Denominator for percentage annotations. */
+    total: number;
+    /** Minimum subtree value a child needs to stay visible. */
+    minValue: number;
+    /** Format a metric value for the left column. */
+    formatValue: (value: number) => string;
+    /** Left-column width (characters) for formatted values. */
+    valueWidth: number;
+}
+/**
+ * Render one hot-path subtree: pass-through chains (single kept child, no own
+ * contribution above `minValue`) collapse into a single `a › b › c` line, and
+ * children below `minValue` are pruned.
+ */
+export declare function renderProfileNode(node: ProfileNode, indent: number, ctx: RenderTreeContext): void;

package/dist/types/utils/sample-profile.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Parser and renderer for macOS `/usr/bin/sample` call-tree reports
+ * (conventionally saved as `*.sample.txt`).
+ *
+ * The raw report is a 10k+ line ASCII call tree with mangled symbols —
+ * expensive for an agent to digest. `renderSampleProfile` converts it into a
+ * compact bottleneck summary:
+ *
+ * - per-thread hot paths, pruned to frames with meaningful on-CPU samples,
+ *   with pass-through chains collapsed and direct recursion flattened
+ * - blocked/idle threads reduced to a one-line classification
+ * - a process-wide "top functions by self samples" table
+ * - Rust v0 and legacy symbols demangled (best-effort, path extraction)
+ *
+ * Consumed by the read tool: `*.sample.txt` reads show the summary, `:raw`
+ * returns the original bytes.
+ */
+/** Matches paths the read tool should treat as macOS sample reports. */
+export declare function isSampleProfilePath(filePath: string): boolean;
+/** One frame in the sampled call tree. Counts are sample hits (subtree total). */
+export interface SampleFrame {
+    count: number;
+    symbol: string;
+    module?: string;
+    children: SampleFrame[];
+}
+/** One sampled thread: `Thread_<id>` root plus its call tree. */
+export interface SampleThread {
+    id: string;
+    name?: string;
+    total: number;
+    roots: SampleFrame[];
+}
+/** Metadata from the report preamble (everything before `Call graph:`). */
+export interface SampleProfileHeader {
+    process: string;
+    pid: number;
+    intervalMs: number;
+    path?: string;
+    codeType?: string;
+    osVersion?: string;
+    footprint?: string;
+    footprintPeak?: string;
+}
+/** Parsed macOS sample report. */
+export interface SampleProfile {
+    header: SampleProfileHeader;
+    threads: SampleThread[];
+}
+/**
+ * Parse a macOS `sample` report. Returns null when the text does not look
+ * like sample output (missing analysis preamble or `Call graph:` section).
+ */
+export declare function parseSampleProfile(text: string): SampleProfile | null;
+/**
+ * Best-effort demangle of Rust symbols (v0 `_R…` and legacy `_ZN…E`).
+ * For v0 this is a path extractor, not a full demangler: identifiers are
+ * pulled out in order and joined with `::`, so generic arguments appear as
+ * extra path segments. Non-Rust symbols pass through unchanged.
+ */
+export declare function demangleSymbol(raw: string): string;
+/**
+ * Render a macOS sample report as an agent-friendly bottleneck summary.
+ * Returns null when `text` is not sample output (caller falls back to the
+ * plain-text path).
+ */
+export declare function renderSampleProfile(text: string): string | null;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@oh-my-pi/pi-coding-agent",
-	"version": "17.1.6",
+	"version": "17.1.7",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://omp.sh",
 	"author": "Can Boluk",
@@ -52,17 +52,17 @@
 		"@agentclientprotocol/sdk": "1.2.1",
 		"@babel/parser": "^7.29.7",
 		"@mozilla/readability": "^0.6.0",
-		"@oh-my-pi/hashline": "17.1.6",
-		"@oh-my-pi/omp-stats": "17.1.6",
-		"@oh-my-pi/pi-agent-core": "17.1.6",
-		"@oh-my-pi/pi-ai": "17.1.6",
-		"@oh-my-pi/pi-catalog": "17.1.6",
-		"@oh-my-pi/pi-mnemopi": "17.1.6",
-		"@oh-my-pi/pi-natives": "17.1.6",
-		"@oh-my-pi/pi-tui": "17.1.6",
-		"@oh-my-pi/pi-utils": "17.1.6",
-		"@oh-my-pi/pi-wire": "17.1.6",
-		"@oh-my-pi/snapcompact": "17.1.6",
+		"@oh-my-pi/hashline": "17.1.7",
+		"@oh-my-pi/omp-stats": "17.1.7",
+		"@oh-my-pi/pi-agent-core": "17.1.7",
+		"@oh-my-pi/pi-ai": "17.1.7",
+		"@oh-my-pi/pi-catalog": "17.1.7",
+		"@oh-my-pi/pi-mnemopi": "17.1.7",
+		"@oh-my-pi/pi-natives": "17.1.7",
+		"@oh-my-pi/pi-tui": "17.1.7",
+		"@oh-my-pi/pi-utils": "17.1.7",
+		"@oh-my-pi/pi-wire": "17.1.7",
+		"@oh-my-pi/snapcompact": "17.1.7",
 		"@opentelemetry/api": "^1.9.1",
 		"@opentelemetry/api-logs": "^0.220.0",
 		"@opentelemetry/context-async-hooks": "^2.9.0",

package/src/config/settings-schema.ts

@@ -3835,14 +3835,28 @@ export const SETTINGS_SCHEMA = {
 		},
 	},
 
+	// Legacy boolean kept only for back-compat migration to `inspect_image.mode`
+	// (see config/settings.ts). Hidden from UI.
 	"inspect_image.enabled": {
 		type: "boolean",
 		default: false,
+	},
+
+	"inspect_image.mode": {
+		type: "enum",
+		values: ["auto", "on", "off"] as const,
+		default: "auto",
 		ui: {
 			tab: "tools",
 			group: "Available Tools",
 			label: "Inspect Image",
-			description: "Enable the inspect_image tool, delegating image understanding to a vision-capable model",
+			description:
+				"Controls the inspect_image tool, which delegates image understanding to a vision-capable model. 'auto' exposes it only when the active model lacks native image input; 'on' always exposes it; 'off' never does.",
+			options: [
+				{ value: "auto", label: "Auto (only for models without vision)" },
+				{ value: "on", label: "On" },
+				{ value: "off", label: "Off" },
+			],
 		},
 	},
 

package/src/config/settings.ts

@@ -39,6 +39,7 @@ import { isLightTheme, setAutoThemeMapping, setColorBlindMode, setSymbolPreset }
 import { AgentStorage } from "../session/agent-storage";
 import { AUTO_IMAGE_PROVIDER_ORDER, isImageProviderId } from "../tools/image-providers";
 import { type EditMode, normalizeEditMode } from "../utils/edit-mode";
+import { INSPECT_IMAGE_MODES } from "../utils/inspect-image-mode";
 import { isSearchProviderId, SEARCH_PROVIDER_ORDER } from "../web/search/types";
 import { withFileLock } from "./file-lock";
 import {
@@ -1366,6 +1367,40 @@ export class Settings {
 			}
 		}
 
+		// inspect_image.enabled (boolean) -> inspect_image.mode (enum). Explicit
+		// user choices are preserved: true -> "on", false -> "off". Configs with
+		// no legacy key get the new "auto" default, which hides the tool for
+		// models with native image input. Handles nested and quoted-dotted
+		// ("inspect_image.enabled") sources; the target is always the nested
+		// form, which is the only shape the resolver reads.
+		const inspectImageObj = isRecord(raw.inspect_image) ? (raw.inspect_image as Record<string, unknown>) : undefined;
+		const legacyEnabled =
+			typeof inspectImageObj?.enabled === "boolean"
+				? inspectImageObj.enabled
+				: typeof raw["inspect_image.enabled"] === "boolean"
+					? (raw["inspect_image.enabled"] as boolean)
+					: undefined;
+		if (legacyEnabled !== undefined) {
+			if (!inspectImageObj) {
+				raw.inspect_image = {};
+			}
+			const target = raw.inspect_image as Record<string, unknown>;
+			const flatMode = raw["inspect_image.mode"];
+			if (target.mode === undefined) {
+				// A quoted-dotted explicit mode wins over the legacy boolean but
+				// must be normalized into the nested form the resolver reads.
+				target.mode =
+					typeof flatMode === "string" && (INSPECT_IMAGE_MODES as readonly string[]).includes(flatMode)
+						? flatMode
+						: legacyEnabled
+							? "on"
+							: "off";
+			}
+			delete target.enabled;
+			delete raw["inspect_image.enabled"];
+			delete raw["inspect_image.mode"];
+		}
+
 		// task.isolation.enabled (boolean) -> task.isolation.mode (enum)
 		const taskObj = raw.task as Record<string, unknown> | undefined;
 		const isolationObj = taskObj?.isolation as Record<string, unknown> | undefined;

package/src/cursor.ts

@@ -25,7 +25,8 @@ interface CursorExecBridgeOptions {
 	cwd: string;
 	getCwd?: () => string;
 	tools: Map<string, AgentTool>;
-	getTool?: (name: string) => AgentTool | undefined;
+	/** Resolves execution overrides (mounted-device permission wrappers) before the canonical map. */
+	getExecutableTool?: (name: string) => AgentTool | undefined;
 	getToolContext?: () => AgentToolContext | undefined;
 	emitEvent?: (event: AgentEvent) => void;
 	/**
@@ -81,7 +82,7 @@ async function executeTool(
 	toolCallId: string,
 	args: Record<string, unknown>,
 ): Promise<ToolResultMessage> {
-	const tool = options.tools.get(toolName) ?? options.getTool?.(toolName);
+	const tool = options.getExecutableTool?.(toolName) ?? options.tools.get(toolName);
 	if (!tool) {
 		const result = buildToolErrorResult(`Tool "${toolName}" not available`);
 		return createToolResultMessage(toolCallId, toolName, result, true);
@@ -497,7 +498,7 @@ export class CursorExecHandlers implements ICursorExecHandlers {
 	async mcp(call: CursorMcpCall) {
 		const toolName = call.toolName || call.name;
 		const toolCallId = decodeToolCallId(call.toolCallId);
-		const tool = this.options.tools.get(toolName) ?? this.options.getTool?.(toolName);
+		const tool = this.options.getExecutableTool?.(toolName) ?? this.options.tools.get(toolName);
 		if (!tool) {
 			const availableTools = Array.from(this.options.tools.keys()).filter(name => name.startsWith("mcp__"));
 			const message = formatMcpToolErrorMessage(toolName, availableTools);

package/src/discovery/builtin-rules/index.ts

@@ -28,6 +28,7 @@ import tsNoAny from "./ts-no-any.md" with { type: "text" };
 import tsNoDeprecatedLeftovers from "./ts-no-deprecated-leftovers.md" with { type: "text" };
 import tsNoDynamicImport from "./ts-no-dynamic-import.md" with { type: "text" };
 import tsNoInlineCastAccess from "./ts-no-inline-cast-access.md" with { type: "text" };
+import tsNoLocalIsRecord from "./ts-no-local-is-record.md" with { type: "text" };
 import tsNoReturnType from "./ts-no-return-type.md" with { type: "text" };
 import tsNoTestTimers from "./ts-no-test-timers.md" with { type: "text" };
 import tsNoTinyFunctions from "./ts-no-tiny-functions.md" with { type: "text" };
@@ -63,6 +64,7 @@ export const BUILTIN_RULE_SOURCES: readonly BuiltinRuleSource[] = [
 	{ name: "ts-no-deprecated-leftovers", content: tsNoDeprecatedLeftovers },
 	{ name: "ts-no-dynamic-import", content: tsNoDynamicImport },
 	{ name: "ts-no-inline-cast-access", content: tsNoInlineCastAccess },
+	{ name: "ts-no-local-is-record", content: tsNoLocalIsRecord },
 	{ name: "ts-no-return-type", content: tsNoReturnType },
 	{ name: "ts-no-test-timers", content: tsNoTestTimers },
 	{ name: "ts-no-tiny-functions", content: tsNoTinyFunctions },

package/src/discovery/builtin-rules/ts-no-local-is-record.md

@@ -0,0 +1,48 @@
+---
+description: "Never use isRecord"
+condition:
+  - "\\bfunction\\s+isRecord(?:\\s*<[^>]*>)?\\s*\\("
+  - "\\b(?:const|let|var)\\s+isRecord\\b\\s*(?::[\\s\\S]{0,300}?)?=\\s*(?:async\\s+)?(?:function\\b|(?:<[^>\\n]*>\\s*)?(?:\\([^)]*\\)|[A-Za-z_$][\\w$]*)\\s*(?::[\\s\\S]{0,300}?)?=>)"
+scope: "tool:edit(*.{ts,tsx,mts,cts}), tool:write(*.{ts,tsx,mts,cts})"
+interruptMode: never
+---
+
+## Why it's wrong
+
+- A `Record<string, unknown>` guard proves only an object, not its fields.
+- It's either unnecessarily complicated, or not strong enough.
+- Repeated guards hide the actual data contract from readers and TypeScript.
+
+## Use
+
+`isRecord` narrows values to `Record<string, unknown>`; each field remains `unknown`.
+
+For network, config, IPC, persisted, or reused data shapes, parse once at the boundary with the project's schema validator and consume its named output type:
+
+```typescript
+const Config = z.object({ retries: z.number().int().nonnegative() });
+type Config = z.infer<typeof Config>;
+
+const config = Config.parse(raw);
+```
+
+If the runtime shape is uncertain, check the properties you use with `typeof`, `Array.isArray`, `in`, or a discriminant. If an existing invariant guarantees the shape, assert the named type at that boundary instead of duplicating a guard:
+
+```typescript
+const config = value as Config;
+```
+
+## Avoid
+
+```typescript
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+	value !== null && typeof value === "object";
+```
+
+## Exceptions
+
+A standalone package without a shared type-guard module may define its single canonical guard. Export it from the package's type-guard module; never recreate it at individual call sites.

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