@namzu/sdk 32.0.0 → 33.0.0

package/dist/runtime/query/executor.js

@@ -14,6 +14,15 @@ import { generateToolCallId } from '../../utils/id.js';
 import { compressShellOutput } from '../../utils/shell-compress.js';
 import { bindOwner } from '../jobs/registry.js';
 import { DEFAULT_MAX_TOOL_OUTPUT_CHARS, applyToolOutputBudget, describeDroppedContent, measureContentBytes, } from './tool-output-budget.js';
+function assertUniqueToolCallIds(toolCalls) {
+    const seen = new Set();
+    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);
+    }
+}
 /**
  * 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.
@@ -183,6 +192,7 @@ export class ToolExecutor {
     workingStateManager;
     probes;
     parentSpan;
+    preparedBatches = new WeakSet();
     /** Set per turn by the orchestrator; see {@link setStepAllowedTools}. */
     stepAllowedTools;
     readPaths = new Set();
@@ -319,17 +329,72 @@ export class ToolExecutor {
         const configured = this.config.permissionMode;
         return typeof configured === 'function' ? configured() : configured;
     }
-    async executeBatch(response, denials, prior) {
+    /** Evaluate the run's operator policy against one already-prepared value. */
+    evaluatePreparedAuthorization(toolName, input) {
+        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) {
+        assertUniqueToolCallIds(response.message.toolCalls ?? []);
+        const calls = new Map();
+        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, previous, changedCallIds) {
+        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.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);
+    }
+    publishPreparedBatch(calls) {
+        const reviewCalls = [...calls.values()]
+            .filter((call) => call.kind !== 'synthetic')
+            .map((call) => ({
+            id: call.toolCall.id,
+            name: call.toolName,
+            input: call.input,
+        }));
+        const batch = Object.freeze({
+            reviewCalls: Object.freeze(reviewCalls),
+            calls: new Map(calls),
+        });
+        this.preparedBatches.add(batch);
+        return batch;
+    }
+    async executeBatch(response, denials, prior, preparedBatch) {
         const toolCalls = response.message.toolCalls;
         if (!toolCalls) {
             return { messages: [], results: [], observations: [] };
         }
+        assertUniqueToolCallIds(toolCalls);
         this.batchCounter += 1;
         // Sampled here, once, and held for every call below. See the note on
         // `permissionMode` in the config type.
         this.batchMode = this.resolvePermissionMode();
         try {
-            return await this.runBatch(toolCalls, denials, prior);
+            const owned = preparedBatch;
+            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
@@ -337,7 +402,7 @@ export class ToolExecutor {
             this.batchMode = undefined;
         }
     }
-    async runBatch(toolCalls, denials, prior) {
+    async runBatch(toolCalls, denials, prior, preparedBatch) {
         this.log.debug('Executing tool batch', {
             [NAMZU.RUN_ID]: this.config.runId,
             'namzu.runtime.tool_count': toolCalls.length,
@@ -369,6 +434,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
@@ -389,7 +455,7 @@ export class ToolExecutor {
                 // message so the assistant turn stays fully answered. Run them
                 // on the parallel branch — they perform no side effects, so
                 // serialization would only add latency.
-                parallel.push(this.recordDenial(toolCall, denialReason).then((r) => {
+                parallel.push(this.recordDenial(toolCall, denialReason, preparedCall).then((r) => {
                     results[i] = r;
                 }));
                 return;
@@ -419,7 +485,7 @@ 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();
@@ -434,14 +500,19 @@ export class ToolExecutor {
                     gate.release();
                 }
             };
-            let input = {};
+            let input = 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 safe = this.config.tools.get(toolCall.function.name)?.isConcurrencySafe?.(input) === true;
+            const preparedToolName = preparedCall?.toolName;
+            const safe = this.config.tools
+                .get(preparedToolName ?? toolCall.function.name)
+                ?.isConcurrencySafe?.(input) === true;
             if (safe)
                 parallel.push(gated());
             else
@@ -494,6 +565,16 @@ export class ToolExecutor {
      * eleven children.
      */
     async dispatchNested(name, input, context, recordObservation, parentToolName, options) {
+        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
             ? {
@@ -508,9 +589,6 @@ export class ToolExecutor {
         // it rather than to itself.
         const nestedId = generateToolCallId();
         const startedAt = Date.now();
-        const signal = options?.signal
-            ? AbortSignal.any([context.abortSignal, options.signal])
-            : context.abortSignal;
         const source = parent
             ? options?.runtimeToolCallId
                 ? {
@@ -526,6 +604,74 @@ 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 = {
             ...context,
             abortSignal: signal,
@@ -545,15 +691,41 @@ 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;
         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();
@@ -600,7 +772,7 @@ export class ToolExecutor {
             runId: this.config.runId,
             toolUseId: nestedId,
             toolName: name,
-            input,
+            input: preparedInput,
             result,
             ...(parent ? { parentToolUseId: parent } : {}),
         });
@@ -629,6 +801,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
@@ -664,90 +837,101 @@ export class ToolExecutor {
         };
         return context;
     }
-    async executeSingle(toolCall, toolContext, recordObservation, settleProgress) {
-        let toolName = toolCall.function.name;
-        // 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,
-            };
+    async executeSingle(toolCall, toolContext, recordObservation, settleProgress, preparedCall) {
+        if (preparedCall?.kind === 'synthetic') {
+            return this.recordSyntheticPreparation(preparedCall);
         }
-        // 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 toolName = preparedCall?.toolName ?? toolCall.function.name;
+        let input;
+        let prepared;
+        if (preparedCall?.kind === 'ready' || preparedCall?.kind === 'legacy') {
+            input = preparedCall.input;
+            prepared = preparedCall.kind === 'ready' ? preparedCall.prepared : undefined;
         }
-        let 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);
+        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,
+                };
+            }
+            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);
+            }
+            input = preOutcome.input;
         }
-        input = preOutcome.input;
         const activity = this.activityStore.create({
             type: 'tool_call',
             description: toolName,
@@ -827,7 +1011,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 = await this.runOnce(toolName, input, toolContext);
+        let result = 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
         // trip: the error went back as a `tool_result`, the model read it and
@@ -894,22 +1078,38 @@ export class ToolExecutor {
                 // resume to trip over.
                 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;
         const rawOutput = result.success
             ? 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', {
                 [NAMZU.RUN_ID]: this.config.runId,
@@ -926,21 +1126,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
@@ -1000,14 +1185,9 @@ export class ToolExecutor {
             result,
         });
         const resolveContent = () => {
-            if (postOverride?.content !== undefined) {
-                return { content: this.budgetContent(postOverride.content, toolName) };
-            }
-            if (postOverride?.isError)
+            if (budgeted.truncated || selectedContent === undefined)
                 return {};
-            if (budgeted.truncated || result.content === undefined)
-                return {};
-            return { content: this.budgetContent(result.content, toolName) };
+            return { content: this.budgetContent(selectedContent, toolName) };
         };
         return {
             toolCallId: toolCall.id,
@@ -1047,13 +1227,10 @@ export class ToolExecutor {
      * model sees "this timed out" as a `tool_result` and can route around
      * it. A throw would end the run over one slow tool.
      */
-    async executeWithDeadline(toolName, input, toolContext) {
+    async executeWithDeadline(toolName, input, toolContext, prepared) {
         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);
@@ -1063,14 +1240,18 @@ export class ToolExecutor {
             parentSignal.addEventListener('abort', onParentAbort, { once: true });
         let timer;
         let timedOut = false;
+        let invocationOpen = true;
+        const nestedDispatches = new Set();
         try {
-            const expired = new Promise((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((resolve) => {
+                    timer = setTimeout(() => {
+                        timedOut = true;
+                        controller.abort(new Error(`Tool "${toolName}" exceeded ${timeoutMs}ms`));
+                        resolve('timeout');
+                    }, timeoutMs);
+                })
+                : undefined;
             const aborted = new Promise((resolve) => {
                 if (controller.signal.aborted && !timedOut) {
                     resolve('aborted');
@@ -1082,24 +1263,46 @@ export class ToolExecutor {
                 }, { once: true });
             });
             const inheritedDispatch = toolContext.dispatchTool;
-            const execution = this.config.tools.execute(toolName, input, {
+            const scopedDispatch = inheritedDispatch
+                ? (name, nestedInput, options) => {
+                    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, nestedInput, options) => 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', {
                     [NAMZU.RUN_ID]: this.config.runId,
@@ -1131,30 +1334,284 @@ 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);
         }
     }
-    async runPreToolHook(toolName, input) {
+    async runPreToolHook(toolName, input, signal = this.config.abortSignal) {
         if (!this.config.pluginManager)
-            return { kind: 'continue', input };
+            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);
     }
+    async prepareNestedCall(toolName, input, signal) {
+        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;
+        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 };
+    }
+    async prepareDirectCall(toolCall) {
+        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;
+        for (;;) {
+            let parsed;
+            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,
+        };
+    }
     interpretPreToolResults(toolName, initialInput, results) {
         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 {
@@ -1181,7 +1638,7 @@ export class ToolExecutor {
                 }
             }
         }
-        return { kind: 'continue', input: currentInput };
+        return { kind: 'continue', input: currentInput, modified };
     }
     /**
      * Turn the call the model issued into a name and a parsed input, giving
@@ -1328,9 +1785,9 @@ export class ToolExecutor {
      * image block had it discarded here — before the wire mapper built to
      * carry it ever saw it.
      */
-    async runOnce(toolName, input, toolContext) {
+    async runOnce(toolName, input, toolContext, prepared) {
         try {
-            return await this.executeWithDeadline(toolName, input, toolContext);
+            return await this.executeWithDeadline(toolName, input, toolContext, prepared);
         }
         catch (err) {
             const message = toErrorMessage(err);
@@ -1401,14 +1858,16 @@ export class ToolExecutor {
      * execution so UI cards reach a terminal state instead of hanging in
      * `executing`, and records a failed activity for the trace.
      */
-    async recordDenial(toolCall, reason) {
-        const toolName = toolCall.function.name;
-        let input = {};
-        try {
-            input = JSON.parse(toolCall.function.arguments || '{}');
-        }
-        catch {
-            input = toolCall.function.arguments;
+    async recordDenial(toolCall, reason, preparedCall) {
+        const toolName = preparedCall?.toolName ?? toolCall.function.name;
+        let input = preparedCall?.input ?? {};
+        if (!preparedCall) {
+            try {
+                input = JSON.parse(toolCall.function.arguments || '{}');
+            }
+            catch {
+                input = toolCall.function.arguments;
+            }
         }
         const output = deniedToolOutput(toolName, reason);
         this.log.info('Tool call denied — synthesizing tool_result', {
@@ -1484,6 +1943,12 @@ export class ToolExecutor {
             isError: outcome.kind === 'error',
         };
     }
+    recordSyntheticPreparation(call) {
+        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.
      *