@namzu/sdk 31.1.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.
@@ -29,6 +38,97 @@ export const DEFAULT_TOOL_TIMEOUT_MS = 120_000;
  * already one-at-a-time by construction.
  */
 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) {
+    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 {
+    emitEvent;
+    base;
+    pending;
+    draining = null;
+    accepting = true;
+    constructor(emitEvent, base) {
+        this.emitEvent = emitEvent;
+        this.base = base;
+    }
+    report(message, fraction) {
+        if (!this.accepting)
+            return;
+        this.pending = {
+            message,
+            ...(fraction !== undefined ? { fraction: Math.min(1, Math.max(0, fraction)) } : {}),
+        };
+        this.startDrain();
+    }
+    async close() {
+        this.accepting = false;
+        this.startDrain();
+        while (this.draining)
+            await this.draining;
+    }
+    startDrain() {
+        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();
+        });
+    }
+    async drain() {
+        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}.
@@ -92,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();
@@ -228,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
@@ -246,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,
@@ -278,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
@@ -298,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;
@@ -306,33 +463,33 @@ 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,
+                toolName: toolCall.function.name,
+            });
             const ctx = {
                 ...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, fraction) => {
-                    // 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,
-                        toolName: toolCall.function.name,
-                        message,
-                        ...(fraction !== undefined ? { fraction: Math.min(1, Math.max(0, fraction)) } : {}),
-                    }).catch(() => { });
-                },
+                report: (message, fraction) => 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();
@@ -343,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
@@ -402,43 +564,219 @@ export class ToolExecutor {
      * rendering a timeline draws eleven siblings where there is one call with
      * eleven children.
      */
-    async dispatchNested(name, input, context, recordObservation) {
+    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 ? { tool: name, toolUseId: parent } : undefined;
+        const via = parent && parentToolName
+            ? {
+                tool: parentToolName,
+                toolUseId: parent,
+                ...(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();
         const startedAt = Date.now();
+        const source = parent
+            ? options?.runtimeToolCallId
+                ? {
+                    kind: 'code',
+                    parentToolUseId: parent,
+                    runtimeToolCallId: options.runtimeToolCallId,
+                }
+                : { kind: 'nested', parentToolUseId: parent }
+            : { kind: 'direct' };
+        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 = {
+            ...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, fraction) => progress.report(message, fraction),
+        };
         await this.emitEvent({
             type: 'tool_executing',
             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, 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 result = await this.config.tools.execute(name, input, context);
+        const visibleResult = 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;
     }
     buildToolContext(recordObservation = () => { }) {
         const context = {
@@ -463,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
@@ -473,7 +812,7 @@ 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
@@ -498,90 +837,101 @@ export class ToolExecutor {
         };
         return context;
     }
-    async executeSingle(toolCall, toolContext, recordObservation) {
-        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,
@@ -661,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
@@ -728,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,
@@ -760,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
@@ -807,6 +1158,11 @@ export class ToolExecutor {
                 this.activityStore.complete(activity.id, output);
             }
         }
+        // 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,
@@ -829,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,
@@ -876,30 +1227,31 @@ 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 runSignal = this.config.abortSignal;
-        const onRunAbort = () => controller.abort(runSignal.reason);
-        if (runSignal.aborted)
-            controller.abort(runSignal.reason);
+        const parentSignal = toolContext.abortSignal;
+        const onParentAbort = () => controller.abort(parentSignal.reason);
+        if (parentSignal.aborted)
+            controller.abort(parentSignal.reason);
         else
-            runSignal.addEventListener('abort', onRunAbort, { once: true });
+            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');
@@ -910,14 +1262,47 @@ export class ToolExecutor {
                         resolve('aborted');
                 }, { once: true });
             });
-            const execution = this.config.tools.execute(toolName, input, {
+            const inheritedDispatch = toolContext.dispatchTool;
+            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,
-            });
+                ...(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,
@@ -949,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);
-            runSignal.removeEventListener('abort', onRunAbort);
+            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 {
@@ -999,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
@@ -1114,7 +1753,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(),
             });
@@ -1143,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);
@@ -1216,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', {
@@ -1299,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.
      *