@namzu/sdk 31.1.0 → 33.0.0

package/src/runtime/query/executor.ts

@@ -1,4 +1,5 @@
 import type { Span } from '@opentelemetry/api'
+import type { AuthorizationGate } from '../../authorization/gate.js'
 import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
 import type { WorkingStateManager } from '../../compaction/manager.js'
 import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
@@ -22,13 +23,16 @@ import {
 import type { PermissionMode } from '../../types/permission/index.js'
 import type { PluginHookResult } from '../../types/plugin/index.js'
 import type { ChatCompletionResponse } from '../../types/provider/index.js'
+import type { AuditEventInput } from '../../types/run/audit.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { Sandbox } from '../../types/sandbox/index.js'
 import type {
 	FileReadTracker,
+	PreparedToolExecution,
 	RequestToolPause,
 	SkillRegistryRef,
 	ToolContext,
+	ToolDispatchOptions,
 	ToolRegistryContract,
 	ToolResult,
 } from '../../types/tool/index.js'
@@ -54,6 +58,74 @@ import {
 
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
+type PreparedDirectCall =
+	| {
+			readonly kind: 'ready'
+			readonly toolCall: ToolCall
+			readonly toolName: string
+			readonly input: unknown
+			readonly prepared: PreparedToolExecution
+	  }
+	| {
+			readonly kind: 'legacy'
+			readonly toolCall: ToolCall
+			readonly toolName: string
+			readonly input: unknown
+	  }
+	| {
+			readonly kind: 'synthetic'
+			readonly toolCall: ToolCall
+			readonly toolName: string
+			readonly input: unknown
+			readonly message: string
+			readonly isError: boolean
+	  }
+
+/**
+ * Executor-owned, single-use preparation of one provider tool-call batch.
+ *
+ * Consumers may inspect `reviewCalls`; only the creating executor can consume
+ * the opaque call preparations. This keeps schema transforms, plugin rewrites,
+ * authorization and execution on one value instead of reparsing between them.
+ */
+export interface PreparedToolBatch {
+	readonly reviewCalls: readonly {
+		readonly id: string
+		readonly name: string
+		readonly input: unknown
+	}[]
+}
+
+interface OwnedPreparedToolBatch extends PreparedToolBatch {
+	readonly calls: ReadonlyMap<string, PreparedDirectCall>
+}
+
+function assertUniqueToolCallIds(toolCalls: readonly ToolCall[]): void {
+	const seen = new Set<string>()
+	for (const [index, toolCall] of toolCalls.entries()) {
+		if (seen.has(toolCall.id)) {
+			throw new Error(
+				`Provider returned duplicate tool call id "${toolCall.id}" at batch index ${index}; the batch is refused because review, denial and result ownership require one unique id per call.`,
+			)
+		}
+		seen.add(toolCall.id)
+	}
+}
+
+type PreparedNestedCall =
+	| {
+			readonly kind: 'ready'
+			readonly input: unknown
+			readonly prepared: PreparedToolExecution
+	  }
+	| { readonly kind: 'legacy'; readonly input: unknown }
+	| {
+			readonly kind: 'synthetic'
+			readonly input: unknown
+			readonly message: string
+			readonly isError: boolean
+	  }
+
 /**
  * Default per-tool deadline. Long enough for a real build or test run,
  * short enough that a wedged tool does not hold a turn open indefinitely.
@@ -71,6 +143,103 @@ export const DEFAULT_TOOL_TIMEOUT_MS = 120_000
  */
 export const DEFAULT_TOOL_CONCURRENCY = 8
 
+/** Maximum UTF-8 size of one ephemeral tool-progress update. */
+const MAX_TOOL_PROGRESS_BYTES = 8 * 1024
+
+/** A visible marker: this event is a display projection, not durable output. */
+const TOOL_PROGRESS_OMISSION = '… '
+
+function boundedToolProgress(message: string): string {
+	if (Buffer.byteLength(message, 'utf8') <= MAX_TOOL_PROGRESS_BYTES) return message
+
+	const tailBudget = MAX_TOOL_PROGRESS_BYTES - Buffer.byteLength(TOOL_PROGRESS_OMISSION, 'utf8')
+	let low = 0
+	let high = message.length
+	while (low < high) {
+		const middle = Math.floor((low + high) / 2)
+		if (Buffer.byteLength(message.slice(middle), 'utf8') > tailBudget) low = middle + 1
+		else high = middle
+	}
+	// Do not turn the low half of a retained surrogate pair into U+FFFD.
+	if (
+		low > 0 &&
+		low < message.length &&
+		message.charCodeAt(low) >= 0xdc00 &&
+		message.charCodeAt(low) <= 0xdfff &&
+		message.charCodeAt(low - 1) >= 0xd800 &&
+		message.charCodeAt(low - 1) <= 0xdbff
+	) {
+		low += 1
+	}
+	return `${TOOL_PROGRESS_OMISSION}${message.slice(low)}`
+}
+
+/**
+ * Latest-state publisher for one tool call.
+ *
+ * `ToolContext.report()` is synchronous by contract, while host event
+ * listeners may be arbitrarily slow. Starting one promise per report makes a
+ * chatty tool an unbounded allocation source. Progress is state rather than a
+ * transcript, so one in-flight update plus the latest pending update is the
+ * complete useful working set; intermediate states may be replaced.
+ */
+class ToolProgressPublisher {
+	private pending: { readonly message: string; readonly fraction?: number } | undefined
+	private draining: Promise<void> | null = null
+	private accepting = true
+
+	constructor(
+		private readonly emitEvent: EmitEvent,
+		private readonly base: Omit<
+			Extract<RunEvent, { type: 'tool_progress' }>,
+			'message' | 'fraction'
+		>,
+	) {}
+
+	report(message: string, fraction?: number): void {
+		if (!this.accepting) return
+		this.pending = {
+			message,
+			...(fraction !== undefined ? { fraction: Math.min(1, Math.max(0, fraction)) } : {}),
+		}
+		this.startDrain()
+	}
+
+	async close(): Promise<void> {
+		this.accepting = false
+		this.startDrain()
+		while (this.draining) await this.draining
+	}
+
+	private startDrain(): void {
+		if (this.draining || !this.pending) return
+		const current = this.drain()
+		this.draining = current
+		void current.finally(() => {
+			if (this.draining !== current) return
+			this.draining = null
+			// A report can land after the final loop check but before this
+			// settlement callback. It is still an accepted update and must be
+			// drained even when close() has since stopped new reports.
+			this.startDrain()
+		})
+	}
+
+	private async drain(): Promise<void> {
+		while (this.pending) {
+			const update = this.pending
+			this.pending = undefined
+			// A progress observer is diagnostic. Its failure cannot become a tool
+			// failure, and report() never hands a rejection back to the tool.
+			await this.emitEvent({
+				...this.base,
+				message: boundedToolProgress(update.message),
+				...(update.fraction !== undefined ? { fraction: update.fraction } : {}),
+			}).catch(() => {})
+		}
+	}
+}
+
 /**
  * Re-runs granted to a `post_tool_use` hook that returns `{action:'retry'}`
  * on a tool which did not opt into {@link ToolDefinition.maxRetries}.
@@ -221,6 +390,17 @@ export interface ToolExecutorConfig {
 	 * reaches it. See {@link RepairToolCall}.
 	 */
 	repairToolCall?: RepairToolCall
+	/**
+	 * Operator policy applied to calls dispatched by another tool.
+	 *
+	 * Model-issued calls are reviewed by the iteration orchestrator. Nested
+	 * calls cannot open a second durable review while their parent is already
+	 * executing, so only an explicit `allow` may proceed; `deny` and `review`
+	 * both fail closed before the registry is touched.
+	 */
+	authorizationGate?: AuthorizationGate
+	/** Durable refusal sink paired with {@link authorizationGate}. */
+	recordAudit?: (input: AuditEventInput) => Promise<unknown>
 }
 
 /**
@@ -238,7 +418,7 @@ interface PostToolOverride {
 }
 
 type PreToolHookOutcome =
-	| { kind: 'continue'; input: unknown }
+	| { kind: 'continue'; input: unknown; modified: boolean }
 	| { kind: 'skip'; input: unknown; output: string }
 	| { kind: 'error'; input: unknown; output: string }
 
@@ -301,6 +481,7 @@ export class ToolExecutor {
 	private workingStateManager?: WorkingStateManager
 	private probes: ProbeEnforcement
 	private parentSpan?: Span
+	private readonly preparedBatches = new WeakSet<PreparedToolBatch>()
 	/** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
 	private stepAllowedTools?: readonly string[]
 	private readonly readPaths: Set<string> = new Set()
@@ -455,15 +636,78 @@ export class ToolExecutor {
 		return typeof configured === 'function' ? configured() : configured
 	}
 
+	/** Evaluate the run's operator policy against one already-prepared value. */
+	evaluatePreparedAuthorization(toolName: string, input: unknown) {
+		return this.config.authorizationGate?.evaluate({
+			toolName,
+			toolInput: input,
+			toolDef: this.config.tools.get(toolName),
+		})
+	}
+
+	/**
+	 * Resolve repairs and pre-tool hooks, then decode each call exactly once.
+	 * The returned projection is what policy and a human review; execution later
+	 * consumes the registry-owned preparations rather than parsing again.
+	 */
+	async prepareBatchForReview(response: ChatCompletionResponse): Promise<PreparedToolBatch> {
+		assertUniqueToolCallIds(response.message.toolCalls ?? [])
+		const calls = new Map<string, PreparedDirectCall>()
+		for (const toolCall of response.message.toolCalls ?? []) {
+			calls.set(toolCall.id, await this.prepareDirectCall(toolCall))
+		}
+		return this.publishPreparedBatch(calls)
+	}
+
+	/** Re-prepare only calls whose raw input a reviewer actually changed. */
+	async reprepareBatchForReview(
+		response: ChatCompletionResponse,
+		previous: PreparedToolBatch,
+		changedCallIds: ReadonlySet<string>,
+	): Promise<PreparedToolBatch> {
+		assertUniqueToolCallIds(response.message.toolCalls ?? [])
+		if (!this.preparedBatches.has(previous)) {
+			throw new Error('Prepared tool batch is not owned by this executor.')
+		}
+		const calls = new Map((previous as OwnedPreparedToolBatch).calls)
+		for (const toolCall of response.message.toolCalls ?? []) {
+			if (changedCallIds.has(toolCall.id)) {
+				calls.set(toolCall.id, await this.prepareDirectCall(toolCall))
+			}
+		}
+		return this.publishPreparedBatch(calls)
+	}
+
+	private publishPreparedBatch(calls: ReadonlyMap<string, PreparedDirectCall>): PreparedToolBatch {
+		const reviewCalls = [...calls.values()]
+			.filter(
+				(call): call is Exclude<PreparedDirectCall, { kind: 'synthetic' }> =>
+					call.kind !== 'synthetic',
+			)
+			.map((call) => ({
+				id: call.toolCall.id,
+				name: call.toolName,
+				input: call.input,
+			}))
+		const batch: OwnedPreparedToolBatch = Object.freeze({
+			reviewCalls: Object.freeze(reviewCalls),
+			calls: new Map(calls),
+		})
+		this.preparedBatches.add(batch)
+		return batch
+	}
+
 	async executeBatch(
 		response: ChatCompletionResponse,
 		denials?: ToolCallDenials,
 		prior?: PriorToolResults,
+		preparedBatch?: PreparedToolBatch,
 	): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
 			return { messages: [], results: [], observations: [] }
 		}
+		assertUniqueToolCallIds(toolCalls)
 
 		this.batchCounter += 1
 
@@ -471,7 +715,11 @@ export class ToolExecutor {
 		// `permissionMode` in the config type.
 		this.batchMode = this.resolvePermissionMode()
 		try {
-			return await this.runBatch(toolCalls, denials, prior)
+			const owned = preparedBatch as OwnedPreparedToolBatch | undefined
+			if (owned && !this.preparedBatches.has(owned)) {
+				throw new Error('Prepared tool batch is not owned by this executor.')
+			}
+			return await this.runBatch(toolCalls, denials, prior, owned)
 		} finally {
 			// Cleared so a later single execution outside a batch resolves
 			// live rather than inheriting the last batch's sample.
@@ -483,6 +731,7 @@ export class ToolExecutor {
 		toolCalls: readonly ToolCall[],
 		denials?: ToolCallDenials,
 		prior?: PriorToolResults,
+		preparedBatch?: OwnedPreparedToolBatch,
 	): Promise<ToolExecutionBatch> {
 		this.log.debug('Executing tool batch', {
 			[NAMZU.RUN_ID]: this.config.runId,
@@ -517,6 +766,7 @@ export class ToolExecutor {
 		// order independence.
 		const gate = new Semaphore(this.config.maxToolConcurrency ?? DEFAULT_TOOL_CONCURRENCY)
 		toolCalls.forEach((toolCall, i) => {
+			const preparedCall = preparedBatch?.calls.get(toolCall.id)
 			const recovered = prior?.get(toolCall.id)
 			if (recovered !== undefined) {
 				// This call already ran, in a process that died before the
@@ -539,7 +789,7 @@ export class ToolExecutor {
 				// on the parallel branch — they perform no side effects, so
 				// serialization would only add latency.
 				parallel.push(
-					this.recordDenial(toolCall, denialReason).then((r) => {
+					this.recordDenial(toolCall, denialReason, preparedCall).then((r) => {
 						results[i] = r
 					}),
 				)
@@ -548,33 +798,39 @@ export class ToolExecutor {
 			// Per-call, because the event has to name which call it is about:
 			// a batch can run several tools at once and a host rendering them
 			// side by side needs to know whose progress this is.
+			const progress = new ToolProgressPublisher(this.emitEvent, {
+				type: 'tool_progress',
+				runId: this.config.runId,
+				toolUseId: toolCall.id as ToolUseId,
+				toolName: toolCall.function.name,
+			})
 			const ctx: ToolContext = {
 				...baseContext,
 				toolUseId: toolCall.id,
+				source: { kind: 'direct' },
 				// Overridden per call, so a nested dispatch can name the call
 				// that made it. The base context has no `toolUseId`, and a
 				// closure built there would report every nested call as
 				// parentless.
-				dispatchTool: (name, input) => this.dispatchNested(name, input, ctx, recordObservation),
+				dispatchTool: (name, input, options) =>
+					this.dispatchNested(name, input, ctx, recordObservation, toolCall.function.name, options),
 				// Per-call for the same reason: a pause has to be routed back
 				// to the call that raised it, and a batch can raise several.
 				...(this.config.toolPause ? { requestPause: this.config.toolPause(toolCall.id) } : {}),
-				report: (message: string, fraction?: number) => {
-					// Fire-and-forget: a tool reporting progress must never be
-					// able to fail because the host's listener threw, and must
-					// never have to await the emit mid-work.
-					void this.emitEvent({
-						type: 'tool_progress',
-						runId: this.config.runId,
-						toolUseId: toolCall.id as ToolUseId,
-						toolName: toolCall.function.name,
-						message,
-						...(fraction !== undefined ? { fraction: Math.min(1, Math.max(0, fraction)) } : {}),
-					}).catch(() => {})
-				},
+				report: (message: string, fraction?: number) => progress.report(message, fraction),
 			}
 			const run = async () => {
-				results[i] = await this.executeSingle(toolCall, ctx, recordObservation)
+				try {
+					results[i] = await this.executeSingle(
+						toolCall,
+						ctx,
+						recordObservation,
+						() => progress.close(),
+						preparedCall,
+					)
+				} finally {
+					await progress.close()
+				}
 			}
 			const gated = async () => {
 				await gate.acquire()
@@ -584,14 +840,19 @@ export class ToolExecutor {
 					gate.release()
 				}
 			}
-			let input: unknown = {}
+			let input: unknown = preparedCall?.input ?? {}
 			try {
-				input = JSON.parse(toolCall.function.arguments || '{}')
+				if (!preparedBatch?.calls.has(toolCall.id)) {
+					input = JSON.parse(toolCall.function.arguments || '{}')
+				}
 			} catch {
 				// non-JSON args → treat as unsafe (serialize), the conservative path
 			}
+			const preparedToolName = preparedCall?.toolName
 			const safe =
-				this.config.tools.get(toolCall.function.name)?.isConcurrencySafe?.(input) === true
+				this.config.tools
+					.get(preparedToolName ?? toolCall.function.name)
+					?.isConcurrencySafe?.(input) === true
 			if (safe) parallel.push(gated())
 			else serial = serial.then(run)
 		})
@@ -651,47 +912,250 @@ export class ToolExecutor {
 		input: unknown,
 		context: ToolContext,
 		recordObservation: (observation: ToolResultObservation) => void,
+		parentToolName?: string,
+		options?: ToolDispatchOptions,
 	): Promise<ToolResult> {
+		const signal = options?.signal
+			? AbortSignal.any([context.abortSignal, options.signal])
+			: context.abortSignal
+		// Authority is checked before an id, activity or event is created. A
+		// retained closure must be observationally inert after its invocation
+		// ends, not merely unable to finish the registry call it already started.
+		signal.throwIfAborted()
+		const preparedCall = await this.prepareNestedCall(name, input, signal)
+		signal.throwIfAborted()
+		const preparedInput = preparedCall.input
+
 		const parent = context.toolUseId
-		const via = parent ? { tool: name, toolUseId: parent as ToolUseId } : undefined
+		const via =
+			parent && parentToolName
+				? {
+						tool: parentToolName,
+						toolUseId: parent as ToolUseId,
+						...(options?.runtimeToolCallId ? { runtimeToolCallId: options.runtimeToolCallId } : {}),
+					}
+				: undefined
 		// Its own id, minted here. Reusing the parent's would make two
 		// different calls indistinguishable in any log keyed by it, which is
 		// exactly how a nested write gets attributed to the program that ran
 		// it rather than to itself.
 		const nestedId = generateToolCallId() as unknown as ToolUseId
 		const startedAt = Date.now()
+		const source = parent
+			? options?.runtimeToolCallId
+				? {
+						kind: 'code' as const,
+						parentToolUseId: parent,
+						runtimeToolCallId: options.runtimeToolCallId,
+					}
+				: { kind: 'nested' as const, parentToolUseId: parent }
+			: { kind: 'direct' as const }
+		const progress = new ToolProgressPublisher(this.emitEvent, {
+			type: 'tool_progress',
+			runId: this.config.runId,
+			toolUseId: nestedId,
+			toolName: name,
+		})
+		if (preparedCall.kind === 'synthetic') {
+			await this.emitEvent({
+				type: 'tool_executing',
+				runId: this.config.runId,
+				toolUseId: nestedId,
+				toolName: name,
+				input: preparedInput,
+				...(via ? { via } : {}),
+			})
+			await progress.close()
+			await this.emitEvent({
+				type: 'tool_completed',
+				runId: this.config.runId,
+				toolUseId: nestedId,
+				toolName: name,
+				result: preparedCall.message,
+				isError: preparedCall.isError,
+				durationMs: Date.now() - startedAt,
+				outputLength: preparedCall.message.length,
+				...(via ? { via } : {}),
+			})
+			return preparedCall.isError
+				? { success: false, output: '', error: preparedCall.message }
+				: { success: true, output: preparedCall.message }
+		}
+
+		const gateResult = this.config.authorizationGate?.evaluate({
+			toolName: name,
+			toolInput: preparedInput,
+			toolDef: this.config.tools.get(name),
+		})
+		if (gateResult && gateResult.decision !== 'allow') {
+			const reason =
+				gateResult.decision === 'deny'
+					? `Blocked by the authorization gate: ${gateResult.reason}`
+					: `Blocked by the authorization gate: this nested call requires an explicit allow rule because an operator review cannot be opened from inside another tool. ${gateResult.reason}`
+			const output = deniedToolOutput(name, reason)
+			// Same fail-closed durability rule as a direct gate denial: if the
+			// configured run store cannot record the refusal, do not quietly carry
+			// on with an unaudited execution.
+			if (!this.config.recordAudit) {
+				throw new Error(
+					`Nested tool "${name}" was refused, but no durable audit recorder is configured.`,
+				)
+			}
+			await this.config.recordAudit({
+				what: { action: 'tool_call', tool: name },
+				outcome: 'refused',
+				reason,
+			})
+			await progress.close()
+			await this.emitEvent({
+				type: 'tool_executing',
+				runId: this.config.runId,
+				toolUseId: nestedId,
+				toolName: name,
+				input: preparedInput,
+				...(via ? { via } : {}),
+			})
+			await this.emitEvent({
+				type: 'tool_completed',
+				runId: this.config.runId,
+				toolUseId: nestedId,
+				toolName: name,
+				result: output,
+				isError: true,
+				durationMs: Date.now() - startedAt,
+				outputLength: output.length,
+				...(via ? { via } : {}),
+			})
+			return { success: false, output: '', error: reason }
+		}
+
+		const childContext: ToolContext = {
+			...context,
+			abortSignal: signal,
+			toolUseId: nestedId,
+			source,
+			dispatchTool: (childName, childInput, childOptions) =>
+				this.dispatchNested(
+					childName,
+					childInput,
+					childContext,
+					recordObservation,
+					name,
+					childOptions,
+				),
+			// A nested execution has its own event/progress identity, but its
+			// durable pause belongs to the nearest model-issued ancestor. The
+			// checkpoint transcript contains that ancestor call and not this
+			// ephemeral child id; minting a pause route for `nestedId` makes the
+			// answer impossible to match after process restart. `...context`
+			// intentionally preserves the ancestor route here.
+			report: (message: string, fraction?: number) => progress.report(message, fraction),
+		}
 
 		await this.emitEvent({
 			type: 'tool_executing',
 			runId: this.config.runId,
 			toolUseId: nestedId,
 			toolName: name,
-			input,
+			input: preparedInput,
 			...(via ? { via } : {}),
 		})
 
-		const result = await this.config.tools.execute(name, input, context)
+		const vetoOutcome = this.probes.queryVeto(
+			{
+				type: 'tool_executing',
+				runId: this.config.runId,
+				toolUseId: nestedId,
+				toolName: name,
+				input: preparedInput,
+				...(via ? { via } : {}),
+			},
+			buildProbeContext({ runId: this.config.runId }),
+		)
+		if (vetoOutcome.action === 'deny') {
+			const probeName = vetoOutcome.probeName ?? 'unnamed'
+			const reason = vetoOutcome.reason ?? 'no reason provided'
+			const message = new ProbeVetoError(probeName, reason, 'tool_executing').message
+			await progress.close()
+			await this.emitEvent({
+				type: 'tool_completed',
+				runId: this.config.runId,
+				toolUseId: nestedId,
+				toolName: name,
+				result: `Error: ${message}`,
+				isError: true,
+				durationMs: Date.now() - startedAt,
+				outputLength: message.length + 7,
+				...(via ? { via } : {}),
+			})
+			return { success: false, output: '', error: message }
+		}
+
+		let result: ToolResult
+		try {
+			// Use the same deadline layer as a model-issued call. Calling the
+			// registry directly made nested tools the only tools whose own
+			// `timeoutMs` declaration was ignored.
+			result = await this.runOnce(
+				name,
+				preparedInput,
+				childContext,
+				preparedCall.kind === 'ready' ? preparedCall.prepared : undefined,
+			)
+		} finally {
+			await progress.close()
+		}
+
+		const rawOutput = result.success
+			? result.output
+			: formatFailedToolOutput(result.output, result.error)
+		const budgeted = applyToolOutputBudget({
+			toolName: name,
+			toolUseId: nestedId,
+			output: rawOutput,
+			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+			spillDir: this.config.toolOutputDir,
+			onError: (message) =>
+				this.log.warn('Failed to spill oversized nested tool output', {
+					[NAMZU.RUN_ID]: this.config.runId,
+					[GENAI.TOOL_NAME]: name,
+					'exception.message': message,
+				}),
+		})
+		const visibleResult: ToolResult = result.success
+			? { ...result, output: budgeted.output }
+			: {
+					...result,
+					output: '',
+					// `run_code` sends `error`, not `output`, across the worker
+					// bridge on a failed host call. Leaving the raw error here would
+					// make the success path bounded and the failure path unbounded.
+					error: budgeted.output,
+				}
 
 		await this.emitEvent({
 			type: 'tool_completed',
 			runId: this.config.runId,
 			toolUseId: nestedId,
 			toolName: name,
-			result: result.success ? result.output : (result.error ?? 'failed'),
+			result: budgeted.output,
 			isError: !result.success,
 			durationMs: Date.now() - startedAt,
+			outputLength: budgeted.originalLength,
+			...(budgeted.truncated ? { outputTruncated: true } : {}),
+			...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
 			...(via ? { via } : {}),
 		})
 		recordObservation({
 			runId: this.config.runId,
 			toolUseId: nestedId,
 			toolName: name,
-			input,
+			input: preparedInput,
 			result,
 			...(parent ? { parentToolUseId: parent } : {}),
 		})
 
-		return result
+		return visibleResult
 	}
 
 	private buildToolContext(
@@ -719,6 +1183,7 @@ export class ToolExecutor {
 			adoptSkillScope: (scope) => {
 				this.skillScope = { ...scope, adoptedInBatch: this.batchCounter }
 			},
+			maxToolOutputChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
 			...(this.config.skills ? { skills: this.config.skills } : {}),
 			...(this.config.web ? { web: this.config.web } : {}),
 			// The SAME registry and the SAME context a model-issued call
@@ -729,7 +1194,8 @@ export class ToolExecutor {
 			// dispatching outside a batch has no parent call to name. The
 			// per-call context below overrides it with one that does; see
 			// `dispatchNested`.
-			dispatchTool: (name, input) => this.dispatchNested(name, input, context, recordObservation),
+			dispatchTool: (name, input, options) =>
+				this.dispatchNested(name, input, context, recordObservation, undefined, options),
 			sandbox: this.config.sandbox,
 			fileReadTracker: this.fileReadTracker,
 			// Bound to this run, once. Binding here rather than passing the
@@ -759,99 +1225,112 @@ export class ToolExecutor {
 		toolCall: ToolCall,
 		toolContext: ToolContext,
 		recordObservation: (observation: ToolResultObservation) => void,
+		settleProgress: () => Promise<void>,
+		preparedCall?: PreparedDirectCall,
 	): Promise<ToolCallOutcome> {
-		let toolName = toolCall.function.name
+		if (preparedCall?.kind === 'synthetic') {
+			return this.recordSyntheticPreparation(preparedCall)
+		}
 
-		// A stream that cut off mid-JSON is the case `repairToolCall` exists
-		// for, and it used to be the one case that never reached it: this
-		// branch returned before `resolveCall` ran, so the motivating failure
-		// was answered with a generic hint while the configured repairer sat
-		// unused. Offer it the partial buffer first.
-		const truncationRepair =
-			toolCall.metadata?.inputTruncated === true
-				? await this.repairTruncatedCall(toolCall, toolName)
-				: null
+		let toolName = preparedCall?.toolName ?? toolCall.function.name
+		let input: unknown
+		let prepared: PreparedToolExecution | undefined
 
-		if (toolCall.metadata?.inputTruncated === true && !truncationRepair) {
-			const message = truncatedToolInputMessage(toolName)
-			await this.emitEvent({
-				type: 'tool_executing',
-				runId: this.config.runId,
-				toolUseId: toolCall.id,
-				toolName,
-				input: {},
-			})
-			await this.emitEvent({
-				type: 'tool_completed',
-				runId: this.config.runId,
-				toolUseId: toolCall.id,
-				toolName,
-				result: message,
-				isError: true,
-			})
-			return {
-				toolCallId: toolCall.id,
-				toolName,
-				output: message,
-				isError: true,
+		if (preparedCall?.kind === 'ready' || preparedCall?.kind === 'legacy') {
+			input = preparedCall.input
+			prepared = preparedCall.kind === 'ready' ? preparedCall.prepared : undefined
+		} else {
+			// A stream that cut off mid-JSON is the case `repairToolCall` exists
+			// for, and it used to be the one case that never reached it: this
+			// branch returned before `resolveCall` ran, so the motivating failure
+			// was answered with a generic hint while the configured repairer sat
+			// unused. Offer it the partial buffer first.
+			const truncationRepair =
+				toolCall.metadata?.inputTruncated === true
+					? await this.repairTruncatedCall(toolCall, toolName)
+					: null
+
+			if (toolCall.metadata?.inputTruncated === true && !truncationRepair) {
+				const message = truncatedToolInputMessage(toolName)
+				await this.emitEvent({
+					type: 'tool_executing',
+					runId: this.config.runId,
+					toolUseId: toolCall.id,
+					toolName,
+					input: {},
+				})
+				await this.emitEvent({
+					type: 'tool_completed',
+					runId: this.config.runId,
+					toolUseId: toolCall.id,
+					toolName,
+					result: message,
+					isError: true,
+				})
+				return {
+					toolCallId: toolCall.id,
+					toolName,
+					output: message,
+					isError: true,
+				}
 			}
-		}
 
-		// A malformed call used to cost a full model round trip to fix: the
-		// error went back as a `tool_result`, the model re-read the whole
-		// context and tried again. A host that can repair it locally turns
-		// that into nothing. No-op when no repairer is configured.
-		const resolved = await this.resolveCall(
-			truncationRepair
-				? {
-						...toolCall,
-						function: {
-							...toolCall.function,
-							name: truncationRepair.toolName ?? toolName,
-							arguments: truncationRepair.arguments,
-						},
-						metadata: {},
-					}
-				: toolCall,
-		)
-		toolName = resolved.toolName
-
-		if (!resolved.ok) {
-			// malformed JSON args used to return without ever
-			// emitting tool_executing or tool_completed, leaving UI cards
-			// orphaned in `streaming_input`. Emit the executing→completed
-			// terminal pair so the card lifecycle closes.
-			const message = resolved.message
-			await this.emitEvent({
-				type: 'tool_executing',
-				runId: this.config.runId,
-				toolUseId: toolCall.id,
-				toolName,
-				input: {},
-			})
-			await this.emitEvent({
-				type: 'tool_completed',
-				runId: this.config.runId,
-				toolUseId: toolCall.id,
-				toolName,
-				result: message,
-				isError: true,
-			})
-			return {
-				toolCallId: toolCall.id,
-				toolName,
-				output: message,
-				isError: true,
+			// A malformed call used to cost a full model round trip to fix: the
+			// error went back as a `tool_result`, the model re-read the whole
+			// context and tried again. A host that can repair it locally turns
+			// that into nothing. No-op when no repairer is configured.
+			const resolved = await this.resolveCall(
+				truncationRepair
+					? {
+							...toolCall,
+							function: {
+								...toolCall.function,
+								name: truncationRepair.toolName ?? toolName,
+								arguments: truncationRepair.arguments,
+							},
+							metadata: {},
+						}
+					: toolCall,
+			)
+			toolName = resolved.toolName
+
+			if (!resolved.ok) {
+				// malformed JSON args used to return without ever
+				// emitting tool_executing or tool_completed, leaving UI cards
+				// orphaned in `streaming_input`. Emit the executing→completed
+				// terminal pair so the card lifecycle closes.
+				const message = resolved.message
+				await this.emitEvent({
+					type: 'tool_executing',
+					runId: this.config.runId,
+					toolUseId: toolCall.id,
+					toolName,
+					input: {},
+				})
+				await this.emitEvent({
+					type: 'tool_completed',
+					runId: this.config.runId,
+					toolUseId: toolCall.id,
+					toolName,
+					result: message,
+					isError: true,
+				})
+				return {
+					toolCallId: toolCall.id,
+					toolName,
+					output: message,
+					isError: true,
+				}
 			}
-		}
 
-		let input: unknown = resolved.input
+			input = resolved.input
 
-		const preOutcome = await this.runPreToolHook(toolName, input)
-		if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
-			return this.recordSyntheticHookOutcome(toolCall.id, toolName, preOutcome.input, preOutcome)
+			const preOutcome = await this.runPreToolHook(toolName, input)
+			if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
+				return this.recordSyntheticHookOutcome(toolCall.id, toolName, preOutcome.input, preOutcome)
+			}
+			input = preOutcome.input
 		}
-		input = preOutcome.input
 
 		const activity = this.activityStore.create({
 			type: 'tool_call',
@@ -939,7 +1418,7 @@ export class ToolExecutor {
 		// version silently DROPPED `content`, so a tool returning an image
 		// block had it discarded here — before the wire mapper that was
 		// built to carry it ever saw it.
-		let result: ToolResult = await this.runOnce(toolName, input, toolContext)
+		let result: ToolResult = await this.runOnce(toolName, input, toolContext, prepared)
 		let post = await this.runPostToolHook(toolName, input, result)
 
 		// In-loop retry. A transient failure used to cost a full model round
@@ -1008,7 +1487,7 @@ export class ToolExecutor {
 				break
 			}
 
-			result = await this.runOnce(toolName, input, toolContext)
+			result = await this.runOnce(toolName, input, toolContext, prepared)
 			post = await this.runPostToolHook(toolName, input, result)
 		}
 		const durationMs = Date.now() - startMs
@@ -1017,16 +1496,35 @@ export class ToolExecutor {
 			? result.output
 			: formatFailedToolOutput(result.output, result.error)
 
-		let output = result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput
+		const postOverride = post.override
+		let output =
+			postOverride?.output ?? (result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput)
+		const selectedContent = postOverride?.isError
+			? undefined
+			: (postOverride?.content ?? result.content)
+		const maxToolOutputChars = this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS
+
+		// If the text preview forces rich content out, say so inside the SAME
+		// budget. Appending this after truncation made the diagnostic itself a
+		// cap bypass; selecting a post-hook override after truncation was a
+		// larger bypass that could replace a bounded result with anything.
+		if (
+			maxToolOutputChars > 0 &&
+			output.length > maxToolOutputChars &&
+			selectedContent !== undefined
+		) {
+			const dropped = describeDroppedContent(selectedContent)
+			if (dropped) output = `${output}\n\n${dropped}`
+		}
 
 		// Compression is opportunistic and shell-only; the budget is the
-		// hard bound that applies to every tool. Runs after compression so
-		// a result that shrinks under the cap is never spilled needlessly.
+		// hard bound that applies to every final tool result, including a
+		// post-tool hook's replacement and the rich-content omission notice.
 		const budgeted = applyToolOutputBudget({
 			toolName,
 			toolUseId: toolCall.id,
 			output,
-			maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+			maxChars: maxToolOutputChars,
 			spillDir: this.config.toolOutputDir,
 			onError: (message) =>
 				this.log.warn('Failed to spill oversized tool output', {
@@ -1045,22 +1543,6 @@ export class ToolExecutor {
 		}
 		output = budgeted.output
 
-		// A truncated text half drops the rich half with it — the preview is
-		// no longer the tool's own payload, so an image alongside it would be
-		// illustrating something the model can no longer read. Dropping is
-		// right; doing it SILENTLY is not. The model saw a preview and had no
-		// way to know an image existed at all, so it reasoned as though the
-		// tool had returned text only.
-		if (budgeted.truncated && result.content !== undefined) {
-			const dropped = describeDroppedContent(result.content)
-			if (dropped) output = `${output}\n\n${dropped}`
-		}
-
-		const postOverride = post.override
-		if (postOverride !== null) {
-			output = postOverride.output
-		}
-
 		// A failed call, or an override that says the call failed. A `replace`
 		// says the opposite, and reading it as a failure is what made redaction
 		// unusable: the model was told a successful call had gone wrong, and
@@ -1095,6 +1577,11 @@ export class ToolExecutor {
 			}
 		}
 
+		// The terminal event closes the live row. Every accepted progress update
+		// must settle before it, otherwise a slow host can receive an update for a
+		// call it has already removed. Detached work reporting after a timeout is
+		// ignored because close() also revokes the publisher.
+		await settleProgress()
 		await this.emitEvent({
 			type: 'tool_completed',
 			runId: this.config.runId,
@@ -1118,12 +1605,8 @@ export class ToolExecutor {
 		})
 
 		const resolveContent = (): { content?: ToolResultContent } => {
-			if (postOverride?.content !== undefined) {
-				return { content: this.budgetContent(postOverride.content, toolName) }
-			}
-			if (postOverride?.isError) return {}
-			if (budgeted.truncated || result.content === undefined) return {}
-			return { content: this.budgetContent(result.content, toolName) }
+			if (budgeted.truncated || selectedContent === undefined) return {}
+			return { content: this.budgetContent(selectedContent, toolName) }
 		}
 
 		return {
@@ -1169,33 +1652,35 @@ export class ToolExecutor {
 		toolName: string,
 		input: unknown,
 		toolContext: ToolContext,
+		prepared?: PreparedToolExecution,
 	): Promise<ToolResult> {
 		const timeoutMs =
 			this.config.tools.get(toolName)?.timeoutMs ??
 			this.config.toolTimeoutMs ??
 			DEFAULT_TOOL_TIMEOUT_MS
 
-		if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
-			return this.config.tools.execute(toolName, input, toolContext)
-		}
-
 		const controller = new AbortController()
-		const runSignal = this.config.abortSignal
-		const onRunAbort = () => controller.abort(runSignal.reason)
-		if (runSignal.aborted) controller.abort(runSignal.reason)
-		else runSignal.addEventListener('abort', onRunAbort, { once: true })
+		const parentSignal = toolContext.abortSignal
+		const onParentAbort = () => controller.abort(parentSignal.reason)
+		if (parentSignal.aborted) controller.abort(parentSignal.reason)
+		else parentSignal.addEventListener('abort', onParentAbort, { once: true })
 
 		let timer: ReturnType<typeof setTimeout> | undefined
 		let timedOut = false
+		let invocationOpen = true
+		const nestedDispatches = new Set<Promise<ToolResult>>()
 
 		try {
-			const expired = new Promise<'timeout'>((resolve) => {
-				timer = setTimeout(() => {
-					timedOut = true
-					controller.abort(new Error(`Tool "${toolName}" exceeded ${timeoutMs}ms`))
-					resolve('timeout')
-				}, timeoutMs)
-			})
+			const expired =
+				Number.isFinite(timeoutMs) && timeoutMs > 0
+					? new Promise<'timeout'>((resolve) => {
+							timer = setTimeout(() => {
+								timedOut = true
+								controller.abort(new Error(`Tool "${toolName}" exceeded ${timeoutMs}ms`))
+								resolve('timeout')
+							}, timeoutMs)
+						})
+					: undefined
 
 			const aborted = new Promise<'aborted'>((resolve) => {
 				if (controller.signal.aborted && !timedOut) {
@@ -1211,15 +1696,54 @@ export class ToolExecutor {
 				)
 			})
 
-			const execution = this.config.tools.execute(toolName, input, {
+			const inheritedDispatch = toolContext.dispatchTool
+			const scopedDispatch = inheritedDispatch
+				? (name: string, nestedInput: unknown, options?: ToolDispatchOptions) => {
+						if (!invocationOpen) {
+							return Promise.reject(
+								new Error(`Tool "${toolName}" invocation has settled; nested dispatch is closed.`),
+							)
+						}
+						const nested = inheritedDispatch(name, nestedInput, {
+							...options,
+							signal: options?.signal
+								? AbortSignal.any([controller.signal, options.signal])
+								: controller.signal,
+						})
+						nestedDispatches.add(nested)
+						// `finally()` creates a second promise. Observe that promise too, or a
+						// rejected nested call which its owner intentionally awaits later would
+						// also create an unhandled cleanup rejection here.
+						void nested.finally(() => nestedDispatches.delete(nested)).catch(() => {})
+						return nested
+					}
+				: undefined
+
+			if (controller.signal.aborted) {
+				return {
+					success: false,
+					output: '',
+					error: abortReasonText(controller.signal.reason)
+						? `Tool "${toolName}" was cancelled: ${abortReasonText(controller.signal.reason)}`
+						: `Tool "${toolName}" was cancelled.`,
+				}
+			}
+
+			const context = {
 				...toolContext,
 				abortSignal: controller.signal,
-			})
+				...(scopedDispatch ? { dispatchTool: scopedDispatch } : {}),
+			}
+			const execution = prepared
+				? this.config.tools.executePrepared(prepared, context)
+				: this.config.tools.execute(toolName, input, context)
 			// The loser of the race may still reject later; neutralize it so
 			// it is never an unhandled rejection.
 			execution.catch(() => {})
 
-			const outcome = await Promise.race([execution, expired, aborted])
+			const outcome = await Promise.race(
+				expired ? [execution, expired, aborted] : [execution, aborted],
+			)
 
 			if (outcome === 'timeout') {
 				this.log.warn('Tool timed out', {
@@ -1253,38 +1777,312 @@ export class ToolExecutor {
 
 			return outcome
 		} finally {
+			// Revoke synchronously before awaiting anything. A retained closure
+			// called from another microtask is refused here; the aborted signal is
+			// the structural backstop inside dispatchNested itself.
+			invocationOpen = false
+			if (!controller.signal.aborted) {
+				controller.abort(new Error(`Tool "${toolName}" invocation has settled.`))
+			}
+			// Calls already admitted before closure own event rows and registry
+			// work. Their executor races observe the abort, emit a terminal result,
+			// and settle before the parent is allowed to report completion.
+			while (nestedDispatches.size > 0) {
+				await Promise.allSettled([...nestedDispatches])
+			}
 			if (timer !== undefined) clearTimeout(timer)
-			runSignal.removeEventListener('abort', onRunAbort)
+			parentSignal.removeEventListener('abort', onParentAbort)
 		}
 	}
 
-	private async runPreToolHook(toolName: string, input: unknown): Promise<PreToolHookOutcome> {
-		if (!this.config.pluginManager) return { kind: 'continue', input }
+	private async runPreToolHook(
+		toolName: string,
+		input: unknown,
+		signal: AbortSignal = this.config.abortSignal,
+	): Promise<PreToolHookOutcome> {
+		if (!this.config.pluginManager) return { kind: 'continue', input, modified: false }
 		const results = await this.config.pluginManager.executeHooks(
 			'pre_tool_use',
 			{
 				runId: this.config.runId,
 				toolName,
 				toolInput: input,
-				signal: this.config.abortSignal,
+				signal,
 			},
 			this.emitEvent,
 		)
 		return this.interpretPreToolResults(toolName, input, results)
 	}
 
+	private async prepareNestedCall(
+		toolName: string,
+		input: unknown,
+		signal: AbortSignal,
+	): Promise<PreparedNestedCall> {
+		const prepare = this.config.tools.prepareExecution
+		const executePrepared = this.config.tools.executePrepared
+		if (typeof prepare !== 'function' || typeof executePrepared !== 'function') {
+			if (this.config.authorizationGate) {
+				return {
+					kind: 'synthetic',
+					input,
+					message: `Tool "${toolName}" was not executed because its registry cannot bind authorization to one prepared input.`,
+					isError: true,
+				}
+			}
+			const preOutcome = await this.runPreToolHook(toolName, input, signal)
+			if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
+				return {
+					kind: 'synthetic',
+					input: preOutcome.input,
+					message: preOutcome.output,
+					isError: preOutcome.kind === 'error',
+				}
+			}
+			return { kind: 'legacy', input: preOutcome.input }
+		}
+
+		let preparation: ReturnType<typeof prepare>
+		try {
+			preparation = prepare.call(this.config.tools, toolName, input)
+		} catch (err) {
+			return {
+				kind: 'synthetic',
+				input,
+				message: `Tool "${toolName}" could not be prepared: ${toErrorMessage(err)}`,
+				isError: true,
+			}
+		}
+		if (!preparation.success) {
+			return {
+				kind: 'synthetic',
+				input,
+				message: formatFailedToolOutput(preparation.result.output, preparation.result.error),
+				isError: true,
+			}
+		}
+		const preOutcome = await this.runPreToolHook(toolName, preparation.prepared.input, signal)
+		if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
+			return {
+				kind: 'synthetic',
+				input: preOutcome.input,
+				message: preOutcome.output,
+				isError: preOutcome.kind === 'error',
+			}
+		}
+		if (!preOutcome.modified) {
+			return {
+				kind: 'ready',
+				input: preparation.prepared.input,
+				prepared: preparation.prepared,
+			}
+		}
+		const modified = prepare.call(this.config.tools, toolName, preOutcome.input)
+		if (!modified.success) {
+			return {
+				kind: 'synthetic',
+				input: preOutcome.input,
+				message: formatFailedToolOutput(modified.result.output, modified.result.error),
+				isError: true,
+			}
+		}
+		return { kind: 'ready', input: modified.prepared.input, prepared: modified.prepared }
+	}
+
+	private async prepareDirectCall(toolCall: ToolCall): Promise<PreparedDirectCall> {
+		let toolName = toolCall.function.name
+		const truncationRepair =
+			toolCall.metadata?.inputTruncated === true
+				? await this.repairTruncatedCall(toolCall, toolName)
+				: null
+		if (toolCall.metadata?.inputTruncated === true && !truncationRepair) {
+			return {
+				kind: 'synthetic',
+				toolCall,
+				toolName,
+				input: {},
+				message: truncatedToolInputMessage(toolName),
+				isError: true,
+			}
+		}
+
+		const prepare = this.config.tools.prepareExecution
+		const executePrepared = this.config.tools.executePrepared
+		if (typeof prepare !== 'function' || typeof executePrepared !== 'function') {
+			const resolved = await this.resolveCall(
+				truncationRepair
+					? {
+							...toolCall,
+							function: {
+								...toolCall.function,
+								name: truncationRepair.toolName ?? toolName,
+								arguments: truncationRepair.arguments,
+							},
+							metadata: {},
+						}
+					: toolCall,
+			)
+			toolName = resolved.toolName
+			if (!resolved.ok) {
+				return {
+					kind: 'synthetic',
+					toolCall,
+					toolName,
+					input: {},
+					message: resolved.message,
+					isError: true,
+				}
+			}
+			const preOutcome = await this.runPreToolHook(toolName, resolved.input)
+			if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
+				return {
+					kind: 'synthetic',
+					toolCall,
+					toolName,
+					input: preOutcome.input,
+					message: preOutcome.output,
+					isError: preOutcome.kind === 'error',
+				}
+			}
+			if (!this.config.authorizationGate) {
+				return {
+					kind: 'legacy',
+					toolCall,
+					toolName,
+					input: preOutcome.input,
+				}
+			}
+			return {
+				kind: 'synthetic',
+				toolCall,
+				toolName,
+				input: preOutcome.input,
+				message: `Tool "${toolName}" was not executed because its registry cannot bind authorization to one prepared input.`,
+				isError: true,
+			}
+		}
+
+		let raw = truncationRepair?.arguments ?? toolCall.function.arguments
+		toolName = truncationRepair?.toolName ?? toolName
+		let repairUsed = truncationRepair !== null
+		let preparation: ReturnType<typeof prepare>
+		for (;;) {
+			let parsed: unknown
+			try {
+				parsed = parseArguments(raw)
+			} catch {
+				const message = `Error: Invalid JSON in tool arguments for "${toolName}"`
+				const repair =
+					!repairUsed && this.config.repairToolCall
+						? await this.requestRepair(toolCall, toolName, {
+								reason: 'invalid_json',
+								message,
+							})
+						: null
+				if (repair) {
+					repairUsed = true
+					toolName = repair.toolName ?? toolName
+					raw = repair.arguments
+					continue
+				}
+				return { kind: 'synthetic', toolCall, toolName, input: {}, message, isError: true }
+			}
+
+			try {
+				preparation = prepare.call(this.config.tools, toolName, parsed)
+			} catch (err) {
+				const message = `Error: Unknown or unavailable tool "${toolName}": ${toErrorMessage(err)}`
+				const repair =
+					!repairUsed && this.config.repairToolCall
+						? await this.requestRepair(toolCall, toolName, {
+								reason: 'unknown_tool',
+								message,
+							})
+						: null
+				if (repair) {
+					repairUsed = true
+					toolName = repair.toolName ?? toolName
+					raw = repair.arguments
+					continue
+				}
+				return { kind: 'synthetic', toolCall, toolName, input: parsed, message, isError: true }
+			}
+
+			if (preparation.success) break
+			const message = formatFailedToolOutput(preparation.result.output, preparation.result.error)
+			const repair =
+				!repairUsed && this.config.repairToolCall
+					? await this.requestRepair(toolCall, toolName, {
+							reason: 'schema_validation',
+							message,
+						})
+					: null
+			if (repair) {
+				repairUsed = true
+				toolName = repair.toolName ?? toolName
+				raw = repair.arguments
+				continue
+			}
+			return {
+				kind: 'synthetic',
+				toolCall,
+				toolName,
+				input: parsed,
+				message,
+				isError: true,
+			}
+		}
+
+		const preOutcome = await this.runPreToolHook(toolName, preparation.prepared.input)
+		if (preOutcome.kind === 'skip' || preOutcome.kind === 'error') {
+			return {
+				kind: 'synthetic',
+				toolCall,
+				toolName,
+				input: preOutcome.input,
+				message: preOutcome.output,
+				isError: preOutcome.kind === 'error',
+			}
+		}
+
+		if (preOutcome.modified) {
+			const modified = prepare.call(this.config.tools, toolName, preOutcome.input)
+			if (!modified.success) {
+				return {
+					kind: 'synthetic',
+					toolCall,
+					toolName,
+					input: preOutcome.input,
+					message: formatFailedToolOutput(modified.result.output, modified.result.error),
+					isError: true,
+				}
+			}
+			preparation = modified
+		}
+
+		return {
+			kind: 'ready',
+			toolCall,
+			toolName,
+			input: preparation.prepared.input,
+			prepared: preparation.prepared,
+		}
+	}
+
 	private interpretPreToolResults(
 		toolName: string,
 		initialInput: unknown,
 		results: readonly PluginHookResult[],
 	): PreToolHookOutcome {
 		let currentInput = initialInput
+		let modified = false
 		for (const result of results) {
 			switch (result.action) {
 				case 'continue':
 					continue
 				case 'modify':
 					currentInput = result.input
+					modified = true
 					continue
 				case 'skip':
 					return {
@@ -1313,7 +2111,7 @@ export class ToolExecutor {
 				}
 			}
 		}
-		return { kind: 'continue', input: currentInput }
+		return { kind: 'continue', input: currentInput, modified }
 	}
 
 	/**
@@ -1457,7 +2255,10 @@ export class ToolExecutor {
 				reason: failure.reason,
 				message: failure.message,
 				...(tool
-					? { tool, jsonSchema: tool.modelInputSchema ?? renderToolSchema(tool.inputSchema) }
+					? {
+							tool,
+							jsonSchema: tool.modelInputSchema ?? renderToolSchema(tool.inputSchema),
+						}
 					: {}),
 				availableTools: this.config.tools.listNames(),
 			})
@@ -1490,9 +2291,10 @@ export class ToolExecutor {
 		toolName: string,
 		input: unknown,
 		toolContext: ToolContext,
+		prepared?: PreparedToolExecution,
 	): Promise<ToolResult> {
 		try {
-			return await this.executeWithDeadline(toolName, input, toolContext)
+			return await this.executeWithDeadline(toolName, input, toolContext, prepared)
 		} catch (err) {
 			const message = toErrorMessage(err)
 			this.log.warn('Tool execution threw', {
@@ -1573,13 +2375,19 @@ export class ToolExecutor {
 	 * execution so UI cards reach a terminal state instead of hanging in
 	 * `executing`, and records a failed activity for the trace.
 	 */
-	private async recordDenial(toolCall: ToolCall, reason: string): Promise<ToolCallOutcome> {
-		const toolName = toolCall.function.name
-		let input: unknown = {}
-		try {
-			input = JSON.parse(toolCall.function.arguments || '{}')
-		} catch {
-			input = toolCall.function.arguments
+	private async recordDenial(
+		toolCall: ToolCall,
+		reason: string,
+		preparedCall?: PreparedDirectCall,
+	): Promise<ToolCallOutcome> {
+		const toolName = preparedCall?.toolName ?? toolCall.function.name
+		let input: unknown = preparedCall?.input ?? {}
+		if (!preparedCall) {
+			try {
+				input = JSON.parse(toolCall.function.arguments || '{}')
+			} catch {
+				input = toolCall.function.arguments
+			}
 		}
 
 		const output = deniedToolOutput(toolName, reason)
@@ -1666,6 +2474,13 @@ export class ToolExecutor {
 		}
 	}
 
+	private recordSyntheticPreparation(call: Extract<PreparedDirectCall, { kind: 'synthetic' }>) {
+		return this.recordSyntheticHookOutcome(call.toolCall.id, call.toolName, call.input, {
+			kind: call.isError ? 'error' : 'skip',
+			output: call.message,
+		})
+	}
+
 	/**
 	 * Bound the rich channel, or leave it alone when no cap is configured.
 	 *