@namzu/sdk 32.0.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,10 +23,12 @@ 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,
@@ -55,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.
@@ -319,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>
 }
 
 /**
@@ -336,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 }
 
@@ -399,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()
@@ -553,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
 
@@ -569,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.
@@ -581,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,
@@ -615,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
@@ -637,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
 					}),
 				)
@@ -669,8 +821,12 @@ export class ToolExecutor {
 			}
 			const run = async () => {
 				try {
-					results[i] = await this.executeSingle(toolCall, ctx, recordObservation, () =>
-						progress.close(),
+					results[i] = await this.executeSingle(
+						toolCall,
+						ctx,
+						recordObservation,
+						() => progress.close(),
+						preparedCall,
 					)
 				} finally {
 					await progress.close()
@@ -684,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)
 		})
@@ -754,6 +915,17 @@ export class ToolExecutor {
 		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 && parentToolName
@@ -769,9 +941,6 @@ export class ToolExecutor {
 		// it rather than to itself.
 		const nestedId = generateToolCallId() as unknown as ToolUseId
 		const startedAt = Date.now()
-		const signal = options?.signal
-			? AbortSignal.any([context.abortSignal, options.signal])
-			: context.abortSignal
 		const source = parent
 			? options?.runtimeToolCallId
 				? {
@@ -787,6 +956,79 @@ export class ToolExecutor {
 			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,
@@ -815,16 +1057,51 @@ export class ToolExecutor {
 			runId: this.config.runId,
 			toolUseId: nestedId,
 			toolName: name,
-			input,
+			input: preparedInput,
 			...(via ? { via } : {}),
 		})
 
+		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, input, childContext)
+			result = await this.runOnce(
+				name,
+				preparedInput,
+				childContext,
+				preparedCall.kind === 'ready' ? preparedCall.prepared : undefined,
+			)
 		} finally {
 			await progress.close()
 		}
@@ -873,7 +1150,7 @@ export class ToolExecutor {
 			runId: this.config.runId,
 			toolUseId: nestedId,
 			toolName: name,
-			input,
+			input: preparedInput,
 			result,
 			...(parent ? { parentToolUseId: parent } : {}),
 		})
@@ -906,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
@@ -948,99 +1226,111 @@ export class ToolExecutor {
 		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',
@@ -1128,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
@@ -1197,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
@@ -1206,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', {
@@ -1234,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
@@ -1312,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 {
@@ -1363,16 +1652,13 @@ 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 parentSignal = toolContext.abortSignal
 		const onParentAbort = () => controller.abort(parentSignal.reason)
@@ -1381,15 +1667,20 @@ export class ToolExecutor {
 
 		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) {
@@ -1406,26 +1697,53 @@ export class ToolExecutor {
 			})
 
 			const inheritedDispatch = toolContext.dispatchTool
-			const execution = this.config.tools.execute(toolName, input, {
+			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,
-				...(inheritedDispatch
-					? {
-							dispatchTool: (name: string, nestedInput: unknown, options?: ToolDispatchOptions) =>
-								inheritedDispatch(name, nestedInput, {
-									...options,
-									signal: options?.signal
-										? AbortSignal.any([controller.signal, options.signal])
-										: 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', {
@@ -1459,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)
 			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 {
@@ -1519,7 +2111,7 @@ export class ToolExecutor {
 				}
 			}
 		}
-		return { kind: 'continue', input: currentInput }
+		return { kind: 'continue', input: currentInput, modified }
 	}
 
 	/**
@@ -1699,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', {
@@ -1782,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)
@@ -1875,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.
 	 *