@namzu/sdk 2.0.0 → 3.0.0

package/dist/runtime/query/executor.js

@@ -2,8 +2,55 @@ import { extractFromToolCall, extractFromToolResult } from '../../compaction/ext
 import { buildProbeContext } from '../../probe/context.js';
 import { ProbeVetoError } from '../../probe/errors.js';
 import { probe as defaultProbeRegistry } from '../../probe/registry.js';
-import { createToolMessage } from '../../types/message/index.js';
+import { renderToolSchema } from '../../registry/tool/schema.js';
+import { createToolMessage, } from '../../types/message/index.js';
+import { toErrorMessage } from '../../utils/error.js';
 import { compressShellOutput } from '../../utils/shell-compress.js';
+import { DEFAULT_MAX_TOOL_OUTPUT_CHARS, applyToolOutputBudget, describeDroppedContent, measureContentBytes, } from './tool-output-budget.js';
+/**
+ * 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.
+ * A tool that legitimately runs longer declares its own `timeoutMs`.
+ */
+export const DEFAULT_TOOL_TIMEOUT_MS = 120_000;
+/**
+ * Cap on tools executing at once within a single batch.
+ *
+ * `executeBatch` used to `Promise.all` an unbounded fan-out, so a model
+ * emitting fifty parallel reads opened fifty file handles and fifty
+ * activity records at once. The serial chain is unaffected — it is
+ * already one-at-a-time by construction.
+ */
+export const DEFAULT_TOOL_CONCURRENCY = 8;
+/**
+ * Re-runs granted to a `post_tool_use` hook that returns `{action:'retry'}`
+ * on a tool which did not opt into {@link ToolDefinition.maxRetries}.
+ *
+ * Small on purpose. The hook is host code reacting to one specific result,
+ * which is a more specific signal than the tool's blanket idempotency
+ * declaration — but the tool still never said it was safe to re-run, so
+ * this buys one correction, not a loop.
+ */
+export const HOOK_RETRY_BUDGET = 1;
+/**
+ * An empty arguments string means "no arguments", not "malformed" — the
+ * shape a no-parameter tool arrives in.
+ */
+function parseArguments(raw) {
+    return JSON.parse(raw || '{}');
+}
+/**
+ * Model-visible text for a tool call that was never executed.
+ *
+ * The reason travels INSIDE the `tool_result` rather than as a trailing
+ * user message: a `tool_use` block must be answered by a `tool_result`
+ * with the same id, and a denial is an answer, not an omission. Putting
+ * the reason here is also what makes rejection *steer* — the model reads
+ * it in the slot it already attends to for tool outcomes.
+ */
+export function deniedToolOutput(toolName, reason) {
+    return `Error: Tool "${toolName}" was not executed. ${reason}`;
+}
 export class ToolExecutor {
     config;
     activityStore;
@@ -11,6 +58,7 @@ export class ToolExecutor {
     log;
     workingStateManager;
     probes;
+    parentSpan;
     readPaths = new Set();
     fileReadTracker = {
         recordRead: (key) => {
@@ -31,7 +79,30 @@ export class ToolExecutor {
     setSandbox(sandbox) {
         this.config = { ...this.config, sandbox };
     }
-    async executeBatch(response) {
+    /**
+     * Span that this executor's tool spans should hang off — the current
+     * iteration. Re-set each turn by the orchestrator, because a tool span
+     * belongs under the iteration that requested it.
+     */
+    setParentSpan(span) {
+        this.parentSpan = span;
+    }
+    /**
+     * Answer every `tool_use` block in `response` with exactly one
+     * `tool_result`.
+     *
+     * `denials` marks ids that must NOT run: each is answered with a
+     * synthetic error result carrying the caller's reason instead of being
+     * executed. This is what makes the invariant hold by construction —
+     * a gate denial, a human rejection and a partial approval all leave
+     * the history valid, because there is exactly one place that turns a
+     * batch of tool calls into messages and it always covers all of them.
+     *
+     * Answering with `is_error` semantics rather than dropping the call is
+     * the universal contract across providers: an unanswered `tool_use`
+     * is a protocol violation, not a decline.
+     */
+    async executeBatch(response, denials, prior) {
         const toolCalls = response.message.toolCalls;
         if (!toolCalls) {
             return { messages: [], results: [] };
@@ -39,6 +110,8 @@ export class ToolExecutor {
         this.log.debug('Executing tool batch', {
             runId: this.config.runId,
             toolCount: toolCalls.length,
+            deniedCount: denials?.size ?? 0,
+            recoveredCount: prior?.size ?? 0,
             tools: toolCalls.map((tc) => tc.function.name),
         });
         // One context per call so each execution can see its own
@@ -55,11 +128,72 @@ export class ToolExecutor {
         const results = new Array(toolCalls.length);
         const parallel = [];
         let serial = Promise.resolve();
+        // Bounded fan-out. A model emitting fifty parallel reads used to open
+        // fifty file handles and fifty activity records simultaneously; the
+        // gate keeps that at a working-set size while preserving completion
+        // order independence.
+        const gate = new Semaphore(this.config.maxToolConcurrency ?? DEFAULT_TOOL_CONCURRENCY);
         toolCalls.forEach((toolCall, i) => {
-            const ctx = { ...baseContext, toolUseId: toolCall.id };
+            const recovered = prior?.get(toolCall.id);
+            if (recovered !== undefined) {
+                // This call already ran, in a process that died before the
+                // batch settled. Re-running it would be a second charge, a
+                // second email, a second row deleted — so the recorded result
+                // answers the `tool_use` block and the tool is not touched.
+                results[i] = {
+                    toolCallId: toolCall.id,
+                    toolName: toolCall.function.name,
+                    output: recovered.result,
+                    isError: recovered.isError,
+                };
+                return;
+            }
+            const denialReason = denials?.get(toolCall.id);
+            if (denialReason !== undefined) {
+                // Denied calls never touch the tool; they still get a result
+                // 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) => {
+                    results[i] = r;
+                }));
+                return;
+            }
+            // 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 ctx = {
+                ...baseContext,
+                toolUseId: toolCall.id,
+                // 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(() => { });
+                },
+            };
             const run = async () => {
                 results[i] = await this.executeSingle(toolCall, ctx);
             };
+            const gated = async () => {
+                await gate.acquire();
+                try {
+                    await run();
+                }
+                finally {
+                    gate.release();
+                }
+            };
             let input = {};
             try {
                 input = JSON.parse(toolCall.function.arguments || '{}');
@@ -69,12 +203,35 @@ export class ToolExecutor {
             }
             const safe = this.config.tools.get(toolCall.function.name)?.isConcurrencySafe?.(input) === true;
             if (safe)
-                parallel.push(run());
+                parallel.push(gated());
             else
                 serial = serial.then(run);
         });
         await Promise.all([...parallel, serial]);
-        const messages = results.map((r) => createToolMessage(r.output, r.toolCallId));
+        // Whatever failed above left a hole in `results`; fill every one, so
+        // the invariant holds by construction rather than by everything having
+        // gone well.
+        for (let i = 0; i < toolCalls.length; i++) {
+            if (results[i])
+                continue;
+            const toolCall = toolCalls[i];
+            const toolName = toolCall.function.name;
+            const message = `Error: Tool "${toolName}" did not complete — the batch failed before it produced a result.`;
+            results[i] = { toolCallId: toolCall.id, toolName, output: message, isError: true };
+            await this.emitEvent({
+                type: 'tool_completed',
+                runId: this.config.runId,
+                toolUseId: toolCall.id,
+                toolName,
+                result: message,
+                isError: true,
+            });
+        }
+        // isError and rich content were computed and then discarded here: the
+        // tuple narrowed to {toolCallId, output} BEFORE the message was built,
+        // so the failure signal and any image block were structurally lost at
+        // the last possible moment.
+        const messages = results.map((r) => createToolMessage(r.content ?? r.output, r.toolCallId, r.isError));
         return { messages, results };
     }
     buildToolContext() {
@@ -94,11 +251,20 @@ export class ToolExecutor {
             allowedTools: this.config.allowedTools,
             sandbox: this.config.sandbox,
             fileReadTracker: this.fileReadTracker,
+            ...(this.parentSpan ? { parentSpan: this.parentSpan } : {}),
         };
     }
     async executeSingle(toolCall, toolContext) {
-        const toolName = toolCall.function.name;
-        if (toolCall.metadata?.inputTruncated === true) {
+        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',
@@ -115,18 +281,30 @@ export class ToolExecutor {
                 result: message,
                 isError: true,
             });
-            return { toolCallId: toolCall.id, output: message };
-        }
-        let input;
-        try {
-            input = JSON.parse(toolCall.function.arguments);
+            return { toolCallId: toolCall.id, toolName, output: message, isError: true };
         }
-        catch {
-            // Codex M2: malformed JSON args used to return without ever
+        // 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 = `Error: Invalid JSON in tool arguments for "${toolName}"`;
+            const message = resolved.message;
             await this.emitEvent({
                 type: 'tool_executing',
                 runId: this.config.runId,
@@ -142,8 +320,9 @@ export class ToolExecutor {
                 result: message,
                 isError: true,
             });
-            return { toolCallId: toolCall.id, output: message };
+            return { toolCallId: toolCall.id, toolName, output: message, isError: true };
         }
+        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);
@@ -186,7 +365,7 @@ export class ToolExecutor {
             if (activity) {
                 this.activityStore.fail(activity.id, veto.message);
             }
-            // Codex M1: probe veto used to skip tool_completed entirely.
+            // probe veto used to skip tool_completed entirely.
             // Emit the terminal event with isError so UI cards finalize.
             await this.emitEvent({
                 type: 'tool_completed',
@@ -198,36 +377,113 @@ export class ToolExecutor {
             });
             return {
                 toolCallId: toolCall.id,
+                toolName,
                 output: `Error: ${veto.message}`,
+                // The event emitted just above says this failed; the RESULT
+                // has to say so too. This was the only result-producing
+                // branch in the file that left it off, and `isError` being
+                // optional meant the compiler could not notice.
+                //
+                // Four things degraded off the omission, not one. Two drivers
+                // emit their failure marker only when this is true, so the
+                // model read a SUCCESSFUL result whose body begins "Error: …"
+                // and the failure-recovery path it was trained on never
+                // fired. The persisted step recorded a literal
+                // `isError: false`, so the run record contradicted its own
+                // event stream. And compaction's guard against clearing error
+                // results silently excluded vetoed ones.
+                isError: true,
             };
         }
         if (this.workingStateManager) {
             extractFromToolCall(this.workingStateManager, toolName, JSON.stringify(input));
         }
         const startMs = Date.now();
-        // Codex M4: an unhandled throw from `tools.execute(...)` used to
+        // an unhandled throw from `tools.execute(...)` used to
         // propagate up to `result.ts` as `run_failed` without emitting a
         // terminal `tool_completed`, leaving UI cards stuck in `executing`.
         // Wrap so any throw materialises as an error result.
-        let result;
-        try {
-            result = await this.config.tools.execute(toolName, input, toolContext);
-        }
-        catch (err) {
-            const message = err instanceof Error ? err.message : String(err);
-            this.log.warn('Tool execution threw', {
+        // Typed as the full ToolResult, not a narrowed literal: the narrow
+        // 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 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
+        // decided (or didn't) to call again. Strictly opt-in per tool,
+        // because the SDK cannot know a tool is idempotent — silently
+        // re-running a write or a payment is worse than never retrying.
+        const maxRetries = Math.max(0, this.config.tools.get(toolName)?.maxRetries ?? 0);
+        for (let attempt = 1;; attempt++) {
+            // A missing file will not appear on the second attempt; burning
+            // the budget on it only delays the error the model needs to see.
+            const toolWants = !result.success && result.retryable === true;
+            // A `post_tool_use` hook asking for a retry gets its OWN budget.
+            // Bounding it by `maxRetries` made it a silent no-op at the
+            // shipped default of 0: the hook's answer was read and discarded
+            // on every tool that had not separately opted in. The hook is
+            // host code looking at this specific result — a more specific
+            // signal than the tool's blanket idempotency declaration — so it
+            // is honored, but still bounded so a plugin cannot spin the
+            // executor.
+            if (!toolWants && !post.retry)
+                break;
+            const budget = post.retry ? Math.max(maxRetries, HOOK_RETRY_BUDGET) : maxRetries;
+            if (attempt > budget)
+                break;
+            this.log.info('Retrying a failed tool call', {
                 runId: this.config.runId,
                 tool: toolName,
-                error: message,
+                attempt,
+                budget,
+                requestedByHook: post.retry,
+                error: result.error,
             });
-            result = { success: false, output: '', error: message };
+            result = await this.runOnce(toolName, input, toolContext);
+            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 = await this.runPostToolHook(toolName, input, result);
+        // 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.
+        const budgeted = applyToolOutputBudget({
+            toolName,
+            toolUseId: toolCall.id,
+            output,
+            maxChars: this.config.maxToolOutputChars ?? DEFAULT_MAX_TOOL_OUTPUT_CHARS,
+            spillDir: this.config.toolOutputDir,
+            onError: (message) => this.log.warn('Failed to spill oversized tool output', {
+                runId: this.config.runId,
+                tool: toolName,
+                error: message,
+            }),
+        });
+        if (budgeted.truncated) {
+            this.log.warn('Tool output exceeded the model-visible budget', {
+                runId: this.config.runId,
+                tool: toolName,
+                originalLength: budgeted.originalLength,
+                spillPath: budgeted.spillPath,
+            });
+        }
+        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;
         }
@@ -266,8 +522,114 @@ export class ToolExecutor {
             toolName,
             result: output,
             isError: effectiveIsError,
+            durationMs,
+            // Pre-truncation size, so a host can show "returned 2.1 MB" even
+            // though the model only ever saw a preview.
+            outputLength: budgeted.originalLength,
+            ...(budgeted.truncated ? { outputTruncated: true } : {}),
+            ...(budgeted.spillPath ? { outputSpillPath: budgeted.spillPath } : {}),
         });
-        return { toolCallId: toolCall.id, output };
+        return {
+            toolCallId: toolCall.id,
+            toolName,
+            output,
+            isError: effectiveIsError,
+            // A plugin override replaces what the model sees, and a spilled
+            // preview is no longer the tool's own payload — neither may carry
+            // rich content through.
+            ...(result.content !== undefined && postOverride === null && !budgeted.truncated
+                ? { content: this.budgetContent(result.content, toolName) }
+                : {}),
+        };
+    }
+    /**
+     * Run a tool under a deadline, with the run abort folded in.
+     *
+     * `ToolContext.abortSignal` existed but was produced and consumed by
+     * nothing: a Stop tore down the model stream and then parked inside
+     * `Promise.all` waiting for a tool that had no idea it should quit. A
+     * hung MCP stdio server or a `bash` with the old one-hour default
+     * could hold a turn open long after the user cancelled.
+     *
+     * Two mechanisms, because neither alone is enough:
+     *
+     * 1. The composed signal (run abort OR deadline) is handed to the tool
+     *    so a cooperative tool actually stops working.
+     * 2. The `race` bounds the *executor's* wait regardless, so an
+     *    uncooperative tool becomes detached rather than blocking.
+     *
+     * A timeout is reported as a normal failed result, not a throw: the
+     * 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) {
+        const timeoutMs = this.config.tools.get(toolName)?.timeoutMs ??
+            this.config.toolTimeoutMs ??
+            DEFAULT_TOOL_TIMEOUT_MS;
+        if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+            return this.config.tools.execute(toolName, input, toolContext);
+        }
+        const controller = new AbortController();
+        const runSignal = this.config.abortSignal;
+        const onRunAbort = () => controller.abort(runSignal.reason);
+        if (runSignal.aborted)
+            controller.abort(runSignal.reason);
+        else
+            runSignal.addEventListener('abort', onRunAbort, { once: true });
+        let timer;
+        let timedOut = false;
+        try {
+            const expired = new Promise((resolve) => {
+                timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort(new Error(`Tool "${toolName}" exceeded ${timeoutMs}ms`));
+                    resolve('timeout');
+                }, timeoutMs);
+            });
+            const aborted = new Promise((resolve) => {
+                if (controller.signal.aborted && !timedOut) {
+                    resolve('aborted');
+                    return;
+                }
+                controller.signal.addEventListener('abort', () => {
+                    if (!timedOut)
+                        resolve('aborted');
+                }, { once: true });
+            });
+            const execution = this.config.tools.execute(toolName, input, {
+                ...toolContext,
+                abortSignal: controller.signal,
+            });
+            // 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]);
+            if (outcome === 'timeout') {
+                this.log.warn('Tool timed out', {
+                    runId: this.config.runId,
+                    tool: toolName,
+                    timeoutMs,
+                });
+                return {
+                    success: false,
+                    output: '',
+                    error: `Tool "${toolName}" timed out after ${timeoutMs}ms and was abandoned. It may still be running. Try a narrower input, or a different approach.`,
+                };
+            }
+            if (outcome === 'aborted') {
+                return {
+                    success: false,
+                    output: '',
+                    error: `Tool "${toolName}" was cancelled.`,
+                };
+            }
+            return outcome;
+        }
+        finally {
+            if (timer !== undefined)
+                clearTimeout(timer);
+            runSignal.removeEventListener('abort', onRunAbort);
+        }
     }
     async runPreToolHook(toolName, input) {
         if (!this.config.pluginManager)
@@ -297,7 +659,6 @@ export class ToolExecutor {
                         output: `Error: ${result.message}`,
                     };
                 case 'retry':
-                case 'resume':
                     throw new Error(`Plugin hook pre_tool_use returned unsupported action '${result.action}' for tool ${toolName}`);
                 default: {
                     const _exhaustive = result;
@@ -307,11 +668,165 @@ export class ToolExecutor {
         }
         return { kind: 'continue', input: currentInput };
     }
+    /**
+     * Turn the call the model issued into a name and a parsed input, giving
+     * a configured repairer one chance to fix it first.
+     *
+     * Exactly one chance: a repairer that produces a call which is still
+     * broken will not do better on a second look, and an unbounded loop
+     * here is a hang rather than a degradation.
+     *
+     * `invalid_json` is the ONLY failure that stops the call here, and it
+     * stopped it before this function existed too. `unknown_tool` and
+     * `schema_validation` merely OFFER the repair and otherwise fall
+     * through to the registry, which reports both with better messages —
+     * its schema error already ships a "Required: <field>: <type>" hint the
+     * model can self-correct from. So with no repairer configured this is
+     * behaviorally identical to the bare `JSON.parse` it replaced.
+     */
+    async resolveCall(toolCall) {
+        let toolName = toolCall.function.name;
+        let raw = toolCall.function.arguments;
+        for (let attempt = 0;; attempt++) {
+            const failure = this.inspectCall(toolName, raw);
+            if (!failure)
+                return { ok: true, toolName, input: parseArguments(raw) };
+            const repair = attempt === 0 && this.config.repairToolCall
+                ? await this.requestRepair(toolCall, toolName, failure)
+                : null;
+            if (!repair) {
+                if (failure.reason === 'invalid_json') {
+                    return { ok: false, toolName, message: failure.message };
+                }
+                return { ok: true, toolName, input: parseArguments(raw) };
+            }
+            this.log.info('Repaired a malformed tool call', {
+                runId: this.config.runId,
+                tool: toolName,
+                reason: failure.reason,
+                ...(repair.toolName && repair.toolName !== toolName ? { repairedTo: repair.toolName } : {}),
+            });
+            toolName = repair.toolName ?? toolName;
+            raw = repair.arguments;
+        }
+    }
+    /**
+     * What is wrong with this call, or `null` if nothing is.
+     *
+     * JSON is checked before the tool is looked up: an unparseable argument
+     * string is broken regardless of which tool it was aimed at, and it is
+     * the one problem the executor itself has to answer.
+     */
+    async repairTruncatedCall(toolCall, toolName) {
+        if (!this.config.repairToolCall)
+            return null;
+        // Present the PARTIAL buffer, not the normalized `"{}"` — a repairer
+        // handed an empty object has nothing to work from.
+        const partial = toolCall.metadata?.partialArguments ?? '';
+        const repair = await this.requestRepair({ ...toolCall, function: { ...toolCall.function, arguments: partial } }, toolName, { reason: 'invalid_json', message: truncatedToolInputMessage(toolName) });
+        if (repair) {
+            this.log.info('Repaired a tool call whose input stream was truncated', {
+                runId: this.config.runId,
+                tool: toolName,
+                partialLength: partial.length,
+            });
+        }
+        return repair;
+    }
+    inspectCall(toolName, raw) {
+        let parsed;
+        try {
+            parsed = parseArguments(raw);
+        }
+        catch {
+            return {
+                reason: 'invalid_json',
+                message: `Error: Invalid JSON in tool arguments for "${toolName}"`,
+            };
+        }
+        const tool = this.config.tools.get?.(toolName);
+        if (!tool) {
+            // Either the model named a tool that does not exist, or this
+            // registry does not implement `get`. Both are the registry's to
+            // answer; a repairer still gets offered the `unknown_tool` case.
+            return { reason: 'unknown_tool', message: `Error: Unknown tool "${toolName}"` };
+        }
+        // A registry that hands back a tool with no schema has nothing to
+        // validate against; that is not a repairable condition, just an
+        // unvalidatable one.
+        const validation = tool.inputSchema?.safeParse(parsed);
+        if (validation && !validation.success) {
+            return {
+                reason: 'schema_validation',
+                message: `Error: Invalid arguments for "${toolName}": ${validation.error.issues
+                    .map((issue) => `${issue.path.join('.') || '(root)'}: ${issue.message}`)
+                    .join('; ')}`,
+            };
+        }
+        return null;
+    }
+    async requestRepair(toolCall, toolName, failure) {
+        const repairToolCall = this.config.repairToolCall;
+        if (!repairToolCall)
+            return null;
+        const tool = this.config.tools.get(toolName);
+        try {
+            return await repairToolCall({
+                toolCall,
+                reason: failure.reason,
+                message: failure.message,
+                ...(tool ? { tool, jsonSchema: renderToolSchema(tool.inputSchema) } : {}),
+                availableTools: this.config.tools.listNames(),
+            });
+        }
+        catch (err) {
+            // A broken repairer must not turn a recoverable tool error into a
+            // failed run: the original error is still a perfectly good answer
+            // to give the model.
+            this.log.error('repairToolCall threw — falling back to the original error', {
+                runId: this.config.runId,
+                tool: toolName,
+                error: toErrorMessage(err),
+            });
+            return null;
+        }
+    }
+    /**
+     * One execution attempt, with a throw materialized as an error result.
+     *
+     * an unhandled throw from `tools.execute(...)` used to
+     * propagate up to `result.ts` as `run_failed` without emitting a
+     * terminal `tool_completed`, leaving UI cards stuck in `executing`.
+     *
+     * The return is the full `ToolResult`, not a narrowed literal: the
+     * narrow version silently DROPPED `content`, so a tool returning an
+     * image block had it discarded here — before the wire mapper built to
+     * carry it ever saw it.
+     */
+    async runOnce(toolName, input, toolContext) {
+        try {
+            return await this.executeWithDeadline(toolName, input, toolContext);
+        }
+        catch (err) {
+            const message = toErrorMessage(err);
+            this.log.warn('Tool execution threw', {
+                runId: this.config.runId,
+                tool: toolName,
+                error: message,
+            });
+            return { success: false, output: '', error: message };
+        }
+    }
+    /**
+     * @returns `override` — text replacing the tool's output, or `null`.
+     *   `retry` — the hook asked for the tool to run again.
+     */
     async runPostToolHook(toolName, input, toolResult) {
         if (!this.config.pluginManager)
-            return null;
+            return { override: null, retry: false };
         const results = await this.config.pluginManager.executeHooks('post_tool_use', { runId: this.config.runId, toolName, toolInput: input, toolResult }, this.emitEvent);
         let override = null;
+        let retry = false;
         for (const result of results) {
             switch (result.action) {
                 case 'continue':
@@ -319,10 +834,16 @@ export class ToolExecutor {
                 case 'error':
                     override = `Error: ${result.message}`;
                     continue;
+                // `retry` was a declared variant with no implementation: every
+                // site that consumed it threw. Here it finally means something
+                // — the hook saw the result and wants the tool run again —
+                // and it is bounded by the same per-tool retry budget, so a
+                // plugin cannot spin the executor.
+                case 'retry':
+                    retry = true;
+                    continue;
                 case 'skip':
                 case 'modify':
-                case 'retry':
-                case 'resume':
                     throw new Error(`Plugin hook post_tool_use returned unsupported action '${result.action}' for tool ${toolName}`);
                 default: {
                     const _exhaustive = result;
@@ -330,7 +851,57 @@ export class ToolExecutor {
                 }
             }
         }
-        return override;
+        return { override, retry };
+    }
+    /**
+     * Answer a tool call that policy or a human refused, without executing
+     * it. Emits the same `tool_executing` → `tool_completed` pair as a real
+     * 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;
+        }
+        const output = deniedToolOutput(toolName, reason);
+        this.log.info('Tool call denied — synthesizing tool_result', {
+            runId: this.config.runId,
+            tool: toolName,
+            toolUseId: toolCall.id,
+            reason,
+        });
+        const activity = this.activityStore.create({
+            type: 'tool_call',
+            description: toolName,
+            input,
+            toolName,
+            toolCallId: toolCall.id,
+        });
+        if (activity) {
+            this.activityStore.start(activity.id);
+            this.activityStore.fail(activity.id, output);
+        }
+        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: output,
+            isError: true,
+        });
+        return { toolCallId: toolCall.id, toolName, output, isError: true };
     }
     async recordSyntheticHookOutcome(toolCallId, toolName, input, outcome) {
         const activity = this.activityStore.create({
@@ -364,7 +935,39 @@ export class ToolExecutor {
             result: outcome.output,
             isError: outcome.kind === 'error',
         });
-        return { toolCallId, output: outcome.output };
+        return { toolCallId, toolName, output: outcome.output, isError: outcome.kind === 'error' };
+    }
+    /**
+     * Bound the rich channel, or leave it alone when no cap is configured.
+     *
+     * Refused whole rather than trimmed: half a base64 payload is not a
+     * smaller image, it is a corrupt one, and a driver handed it would
+     * either fail the request or show the model noise. The text half stays
+     * untouched, so the result still says what happened — and the
+     * replacement names what was withheld and how big it was, which is what
+     * lets the agent ask for a smaller region instead of retrying the same
+     * call.
+     */
+    budgetContent(content, toolName) {
+        const cap = this.config.maxToolContentBytes ?? 0;
+        if (cap <= 0)
+            return content;
+        const size = measureContentBytes(content);
+        if (size <= cap)
+            return content;
+        this.log.warn('Tool result content exceeded the rich-content budget', {
+            runId: this.config.runId,
+            tool: toolName,
+            contentBytes: size,
+            cap,
+        });
+        const described = describeDroppedContent(content);
+        return [
+            {
+                type: 'text',
+                text: `[rich content withheld: ${size} base64 chars exceeds this run's ${cap} cap${described ? ` — ${described}` : ''}]`,
+            },
+        ];
     }
     maybeCompress(toolName, output) {
         const tool = this.config.tools.get(toolName);
@@ -383,6 +986,30 @@ export class ToolExecutor {
         return compressed;
     }
 }
+/** Minimal counting semaphore. FIFO, no timeout — the deadline is per-tool. */
+class Semaphore {
+    available;
+    waiters = [];
+    constructor(permits) {
+        this.available = Math.max(1, permits);
+    }
+    acquire() {
+        if (this.available > 0) {
+            this.available--;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    release() {
+        const next = this.waiters.shift();
+        if (next)
+            next();
+        else
+            this.available++;
+    }
+}
 function formatFailedToolOutput(output, error) {
     const errorText = `Error: ${error ?? 'Tool execution failed'}`;
     if (!output || output.trim().length === 0)