@aeye/core 0.3.8 → 0.4.0

package/dist/prompt.js

@@ -1,8 +1,13 @@
 import Handlebars from "handlebars";
 import { ZodString } from 'zod';
-import { accumulateReasoning, accumulateUsage, getChunksFromResponse, getInputTokens, getModel, getOutputTokens, getTotalTokens, resolve, resolveFn, yieldAll } from "./common";
+import { accumulateReasoning, accumulateUsage, extractJSONObject, getChunksFromResponse, getInputTokens, getModel, getOutputTokens, getTotalTokens, resolve, resolveFn, yieldAll } from "./common";
 import { ToolInterrupt, PromptSuspend } from "./tool";
-import { strictify, toJSONSchema } from "./schema";
+import { getDescriptorById, strictify, decodeWire } from "./schema";
+/** Default cap (chars) for validation error messages surfaced back to the
+ *  LLM. Read by `Prompt.truncateValidationError`; subclasses may override
+ *  the method to ignore this. Anything past `max` is replaced with a
+ *  `… (N more characters)` marker. */
+const DEFAULT_VALIDATION_ERROR_MAX_LENGTH = 4096;
 /**
  * A Prompt component that generates AI responses based on input, context, and available tools.
  * Prompts orchestrate interactions with AI models, handle tool calls, and manage streaming responses.
@@ -48,7 +53,12 @@ export class Prompt {
         }
         return Handlebars.compile(template, { noEscape: true });
     }
-    constructor(input, retool = resolveFn(input.retool), schema = resolveFn(input.schema, s => s && input.strict !== false ? strictify(s) : s), config = resolveFn(input.config), translate = resolveFn(input.input), content = Prompt.compileContent(input.content, !!input.tools?.length), metadataFn = resolveFn(input.metadataFn)) {
+    constructor(input, retool = resolveFn(input.retool), 
+    // Schema stays raw. The matching strictify is applied lazily at validation
+    // time using the descriptor pinned on `request.responseFormat.descriptor`
+    // by whichever provider built the request — so the validator always
+    // matches the wire shape the model actually saw.
+    schema = resolveFn(input.schema), config = resolveFn(input.config), translate = resolveFn(input.input), content = Prompt.compileContent(input.content, !!input.tools?.length), metadataFn = resolveFn(input.metadataFn)) {
         this.input = input;
         this.retool = retool;
         this.schema = schema;
@@ -265,9 +275,21 @@ export class Prompt {
         let forgetRetries = this.input.forgetRetries ?? ctx.forgetRetries ?? 1;
         let toolIterations = this.input.toolIterations ?? 3;
         let toolRetries = this.input.toolRetries ?? ctx.toolRetries ?? 2;
+        const toolsComplete = this.input.toolsComplete ?? true;
         let result = undefined;
         let lastError = undefined;
         let completeText = '';
+        // Runtime schema-delivery fallback guard. A model whose descriptor ALLOWS
+        // the schema (so the static `canExpress` check passes and structured output
+        // is sent) can still fail at runtime in two ways: it returns EMPTY or
+        // unparseable content (see the json-parsing branch below), or the request
+        // itself FAILS with an error (e.g. a provider `400` on a too-complex schema —
+        // see the request-error catch around the stream). Under `schemaDelivery:
+        // 'auto'` (and unless `runtimeSchemaFallback` is `false`) either case promotes
+        // delivery to prompt-text for the RETRY. This flag keeps the promotion
+        // idempotent within a single prompt run — we switch at most once and never
+        // loop. Per-run only; nothing is persisted across requests.
+        let promotedToPromptDelivery = false;
         let maxIterations = outputRetries + forgetRetries + toolIterations + toolRetries + 1;
         let requestUsageSent = false;
         let usage = undefined;
@@ -294,6 +316,16 @@ export class Prompt {
         };
         // Main execution loop!
         while (iterations < maxIterations) {
+            // Honor the caller's abort signal at iteration boundaries — if a
+            // tool dispatch already paired its tool_calls via the synthesis
+            // pass on the previous iteration, there's no reason to start
+            // another round-trip. Without this guard the loop would spin
+            // until `maxIterations` because each inner stream call would
+            // immediately observe `signal.aborted`, yield nothing, and fall
+            // through to "no tool calls" — wasting time and tokens for an
+            // already-cancelled request.
+            if (ctx.signal?.aborted)
+                break;
             const toolExecutors = [];
             const toolExecutorMap = new Map();
             const toolErrorsPrevious = (toolCallErrors + toolParseErrors);
@@ -311,341 +343,549 @@ export class Prompt {
                 ...(await this.metadataFn(input, ctx) || {}),
             };
             yield emit({ type: 'request', request, iterations });
-            const stream = streamer(request, ctx, metadata, streamController.signal);
-            for await (const chunk of stream) {
-                if (streamController.signal.aborted) {
-                    break;
-                }
-                if (chunk.usage) {
-                    usage = chunk.usage;
-                    if (!requestUsageSent) {
-                        yield emit({ type: 'requestUsage', usage: chunk.usage, request });
-                        requestUsageSent = true;
+            // Wrap request execution so a REQUEST-TIME failure can drive the runtime
+            // schema-delivery fallback (Mode 4). A provider that accepts a simple
+            // json_schema but 400s on our complex recursive one THROWS here rather
+            // than returning empty content, so the json-parsing fallback inside the
+            // loop never sees it. On such a failure — under `auto`, structured
+            // actually attempted, fallback enabled, not already promoted, retries
+            // left, and not aborted — promote to prompt-text and retry; else rethrow.
+            let requestFailedNeedsRetry = false;
+            try {
+                const stream = streamer(request, ctx, metadata, streamController.signal);
+                for await (const chunk of stream) {
+                    if (streamController.signal.aborted) {
+                        break;
                     }
-                    accumulateUsage(accumulatedUsage, chunk.usage);
-                }
-                if (chunk.content) {
-                    content += chunk.content;
-                    yield emit({ type: 'textPartial', content: chunk.content, request });
-                }
-                if (chunk.refusal) {
-                    refusal += chunk.refusal;
-                    yield emit({ type: 'textPartial', content: chunk.refusal, request });
-                }
-                if (chunk.reasoning) {
-                    reasoning = accumulateReasoning(reasoning, chunk.reasoning);
-                    yield emit({ type: 'reasonPartial', reasoning, request });
-                }
-                // Handle tool calls
-                if (chunk.toolCallNamed) {
-                    const toolExecutor = newToolExecution(ctx, chunk.toolCallNamed, toolMap.get(chunk.toolCallNamed.name));
-                    toolExecutors.push(toolExecutor);
-                    toolExecutorMap.set(chunk.toolCallNamed.id, toolExecutor);
-                    if (toolExecutor.tool) {
-                        yield emit({ type: 'toolParseName', tool: toolExecutor.tool, request });
+                    if (chunk.usage) {
+                        usage = chunk.usage;
+                        if (!requestUsageSent) {
+                            yield emit({ type: 'requestUsage', usage: chunk.usage, request });
+                            requestUsageSent = true;
+                        }
+                        accumulateUsage(accumulatedUsage, chunk.usage);
                     }
-                    else {
-                        streamController.abort(toolExecutor.error);
-                        break;
+                    if (chunk.content) {
+                        content += chunk.content;
+                        yield emit({ type: 'textPartial', content: chunk.content, request });
                     }
-                }
-                if (chunk.toolCallArguments) {
-                    const toolExecutor = toolExecutorMap.get(chunk.toolCallArguments.id);
-                    if (toolExecutor) {
-                        toolExecutor.toolCall = chunk.toolCallArguments;
-                        yield emit({ type: 'toolParseArguments', tool: toolExecutor.tool, args: chunk.toolCallArguments.arguments, request });
+                    if (chunk.refusal) {
+                        refusal += chunk.refusal;
+                        yield emit({ type: 'textPartial', content: chunk.refusal, request });
                     }
-                    else {
-                        console.error(`Received tool call arguments for unknown tool call ID ${chunk.toolCallArguments.id}`);
+                    if (chunk.reasoning) {
+                        reasoning = accumulateReasoning(reasoning, chunk.reasoning);
+                        yield emit({ type: 'reasonPartial', reasoning, request });
                     }
-                }
-                if (chunk.toolCall) {
-                    const toolExecutor = toolExecutorMap.get(chunk.toolCall.id);
-                    if (toolExecutor) {
-                        toolExecutor.toolCall = chunk.toolCall;
-                        if (toolMode === 'immediate') {
-                            // Start execution immediately
-                            setImmediate(toolExecutor.run);
+                    // Handle tool calls
+                    if (chunk.toolCallNamed) {
+                        const toolName = chunk.toolCallNamed.name;
+                        const toolInfo = toolMap.get(chunk.toolCallNamed.name);
+                        const onToolResult = this.input.onToolResult;
+                        const onToolIntercept = this.input.onToolIntercept;
+                        const toolExecutor = newToolExecution(ctx, chunk.toolCallNamed, toolInfo, this.input.validationErrorMaxLength, this.truncateValidationError.bind(this), 
+                        // Boundary: the streaming loop has erased the per-tool types, so
+                        // build the discriminated event from the runtime tool name +
+                        // parsed args/result and cast once to the public event type
+                        // (mirrors the `as PromptEvent<...>` boundary cast in `emitTool`).
+                        onToolResult
+                            ? (result, args) => onToolResult({
+                                tool: toolName,
+                                result,
+                                args,
+                                ctx,
+                                request,
+                            })
+                            : undefined, 
+                        // Pre-bind the interceptor with the matched Tool instance + ctx so
+                        // newToolExecution only feeds it the parsed args (mirrors the
+                        // `present` binding above). Only bound when the tool actually
+                        // resolved — an unknown tool errors out before run() and is never
+                        // intercepted. Runs inside run() BEFORE the handler; a returned
+                        // value short-circuits, false/undefined proceeds, a throw
+                        // propagates through run()'s existing catch (interrupt/suspend/error).
+                        onToolIntercept && toolInfo
+                            ? (args) => onToolIntercept(toolInfo.tool, args, ctx)
+                            : undefined);
+                        toolExecutors.push(toolExecutor);
+                        toolExecutorMap.set(chunk.toolCallNamed.id, toolExecutor);
+                        if (toolExecutor.tool) {
+                            yield emit({ type: 'toolParseName', tool: toolExecutor.tool, request });
+                        }
+                        else {
+                            streamController.abort(toolExecutor.error);
+                            break;
                         }
                     }
-                    else {
-                        console.error(`Received tool call for unknown tool call ID ${chunk.toolCall.id}`);
-                    }
-                }
-                if (chunk.finishReason) {
-                    finishReason = chunk.finishReason;
-                }
-                // In immediate mode we might be getting more chunks while executing, emit events as soon as possible.
-                if (toolMode === 'immediate') {
-                    for (const toolCall of toolExecutors) {
-                        if (toolCall.emitStart()) {
-                            yield emitTool({ type: 'toolStart', tool: toolCall.tool, args: toolCall.args, request });
+                    if (chunk.toolCallArguments) {
+                        const toolExecutor = toolExecutorMap.get(chunk.toolCallArguments.id);
+                        if (toolExecutor) {
+                            toolExecutor.toolCall = chunk.toolCallArguments;
+                            yield emit({ type: 'toolParseArguments', tool: toolExecutor.tool, args: chunk.toolCallArguments.arguments, request });
                         }
-                        if (toolCall.emitOutput()) {
-                            yield emitTool({ type: 'toolOutput', tool: toolCall.tool, args: toolCall.args, result: toolCall.result, request });
+                        else {
+                            console.error(`Received tool call arguments for unknown tool call ID ${chunk.toolCallArguments.id}`);
                         }
-                        if (toolCall.emitInterrupt()) {
-                            yield emitTool({ type: 'toolInterrupt', tool: toolCall.tool, args: toolCall.args, request });
+                    }
+                    if (chunk.toolCall) {
+                        const toolExecutor = toolExecutorMap.get(chunk.toolCall.id);
+                        if (toolExecutor) {
+                            toolExecutor.toolCall = chunk.toolCall;
+                            if (toolMode === 'immediate') {
+                                // Start execution immediately
+                                setImmediate(toolExecutor.run);
+                            }
                         }
-                        if (toolCall.emitSuspend()) {
-                            yield emitTool({ type: 'toolSuspend', tool: toolCall.tool, args: toolCall.args, request });
+                        else {
+                            console.error(`Received tool call for unknown tool call ID ${chunk.toolCall.id}`);
                         }
-                        if (toolCall.emitError()) {
-                            yield emitTool({ type: 'toolError', tool: toolCall.tool, args: toolCall.args, error: toolCall.error, request });
+                    }
+                    if (chunk.finishReason) {
+                        finishReason = chunk.finishReason;
+                    }
+                    // In immediate mode we might be getting more chunks while executing, emit events as soon as possible.
+                    if (toolMode === 'immediate') {
+                        for (const toolCall of toolExecutors) {
+                            if (toolCall.emitStart()) {
+                                yield emitTool({ type: 'toolStart', tool: toolCall.tool, args: toolCall.args, request });
+                            }
+                            if (toolCall.emitOutput()) {
+                                yield emitTool({ type: 'toolOutput', tool: toolCall.tool, args: toolCall.args, result: toolCall.result, toModel: toolCall.toModel, request });
+                            }
+                            if (toolCall.emitInterrupt()) {
+                                yield emitTool({ type: 'toolInterrupt', tool: toolCall.tool, args: toolCall.args, request });
+                            }
+                            if (toolCall.emitSuspend()) {
+                                yield emitTool({ type: 'toolSuspend', tool: toolCall.tool, args: toolCall.args, request });
+                            }
+                            if (toolCall.emitError()) {
+                                yield emitTool({ type: 'toolError', tool: toolCall.tool, args: toolCall.args, error: toolCall.error, rawArgs: toolCall.rawArgs, request });
+                            }
                         }
                     }
                 }
-            }
-            ctx.signal?.removeEventListener('abort', streamAbort);
-            // If the model reasoned, yield it
-            if (reasoning) {
-                yield emit({ type: 'reason', reasoning, request });
-            }
-            // If the model refused to answer and stop
-            if (finishReason === 'refusal' || refusal) {
-                yield emit({ type: 'refusal', content: refusal || 'unspecified', request });
-                lastError = refusal || 'Model refused to answer.';
-                break;
-            }
-            // If the model was stopped due to content filtering
-            if (finishReason === 'content_filter') {
-                yield emit({ type: 'refusal', content: 'Content filtered by AI model', request });
-                lastError = 'Model response was filtered due to content policy.';
-                break;
-            }
-            // If we sent too much, forget the past homie 
-            if (finishReason === 'length') {
-                if (usage && forgetRetries > 0) {
-                    request.messages = this.forget(request, ctx, usage);
-                    forgetRetries--;
-                    yield emit({ type: 'textReset', reason: 'length', request });
-                    // Lets retry immediately
-                    continue;
+                ctx.signal?.removeEventListener('abort', streamAbort);
+                // If the model reasoned, yield it
+                if (reasoning) {
+                    yield emit({ type: 'reason', reasoning, request });
                 }
-                else {
-                    // Stop iteration - we can't trim without usage info
-                    lastError = 'Model indicated length finish reason but no token usage was provided so context cannot be trimmed.';
+                // If the model refused to answer and stop
+                if (finishReason === 'refusal' || refusal) {
+                    yield emit({ type: 'refusal', content: refusal || 'unspecified', request });
+                    lastError = refusal || 'Model refused to answer.';
                     break;
                 }
-            }
-            // Yield text event if content exists before processing tool calls
-            if (content.length > 0) {
-                yield emit({ type: 'text', content, request });
-            }
-            // If we need to make some tool calls, lets do it! 
-            // We might not have a finish_reason if we got a bad tool name.
-            if (finishReason === 'tool_calls' || toolExecutors.length) {
-                // Add the assistant's response with tool calls to the conversation
-                yield emitMessage({
-                    role: 'assistant',
-                    content,
-                    toolCalls: toolExecutors.map(te => te.toolCall),
-                    reasoning,
-                });
-                // If there are any error/invalid - just stop and add their errors and retry
-                let skip = false;
-                for (const toolExecutor of toolExecutors) {
-                    if (toolExecutor.error) {
-                        skip = true;
+                // If the model was stopped due to content filtering
+                if (finishReason === 'content_filter') {
+                    yield emit({ type: 'refusal', content: 'Content filtered by AI model', request });
+                    lastError = 'Model response was filtered due to content policy.';
+                    break;
+                }
+                // If we sent too much, forget the past homie 
+                if (finishReason === 'length') {
+                    if (usage && forgetRetries > 0) {
+                        request.messages = this.forget(request, ctx, usage);
+                        forgetRetries--;
+                        yield emit({ type: 'textReset', reason: 'length', request });
+                        // Lets retry immediately
+                        continue;
                     }
                     else {
-                        // Non-blocking call, we don't want to hold up execution here. But if we can emit start or error early below this we will try.
-                        toolExecutor.parse();
-                    }
-                    if (toolExecutor.emitStart()) {
-                        yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                    }
-                    if (toolExecutor.emitError()) {
-                        yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, request });
+                        // Stop iteration - we can't trim without usage info
+                        lastError = 'Model indicated length finish reason but no token usage was provided so context cannot be trimmed.';
+                        break;
                     }
                 }
-                // The execution mode for this iteration.
-                const iterationMode = skip ? 'skip' : toolMode;
-                // All tool calls are valid, lets start this!
-                switch (iterationMode) {
-                    case 'sequential':
-                        for (const toolExecutor of toolExecutors) {
-                            await toolExecutor.parse();
-                            if (toolExecutor.emitStart()) {
-                                yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                            }
-                            await toolExecutor.run();
-                            if (toolExecutor.emitOutput()) {
-                                yield emitTool({ type: 'toolOutput', tool: toolExecutor.tool, args: toolExecutor.args, result: toolExecutor.result, request });
-                            }
-                            if (toolExecutor.emitInterrupt()) {
-                                yield emitTool({ type: 'toolInterrupt', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                            }
-                            if (toolExecutor.emitSuspend()) {
-                                yield emitTool({ type: 'toolSuspend', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                            }
-                            if (toolExecutor.emitError()) {
-                                yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, request });
-                            }
+                // Yield text event if content exists before processing tool calls
+                if (content.length > 0) {
+                    yield emit({ type: 'text', content, request });
+                }
+                // If we need to make some tool calls, lets do it! 
+                // We might not have a finish_reason if we got a bad tool name.
+                if (finishReason === 'tool_calls' || toolExecutors.length) {
+                    // Add the assistant's response with tool calls to the conversation
+                    yield emitMessage({
+                        role: 'assistant',
+                        content,
+                        toolCalls: toolExecutors.map(te => te.toolCall),
+                        reasoning,
+                    });
+                    // If there are any error/invalid - just stop and add their errors and retry
+                    let skip = false;
+                    for (const toolExecutor of toolExecutors) {
+                        if (toolExecutor.error) {
+                            skip = true;
                         }
-                        break;
-                    case 'parallel':
-                    case 'immediate':
-                        const parseRuns = toolExecutors.map(tc => [tc.parse(), tc.run()]).flat();
-                        for await (const { result: toolCallPromise } of yieldAll(parseRuns)) {
-                            const toolExecutor = await toolCallPromise;
-                            if (toolExecutor.emitStart()) {
-                                yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                            }
-                            if (toolExecutor.emitOutput()) {
-                                yield emitTool({ type: 'toolOutput', tool: toolExecutor.tool, args: toolExecutor.args, result: toolExecutor.result, request });
-                            }
-                            if (toolExecutor.emitInterrupt()) {
-                                yield emitTool({ type: 'toolInterrupt', tool: toolExecutor.tool, args: toolExecutor.args, request });
-                            }
-                            if (toolExecutor.emitSuspend()) {
-                                yield emitTool({ type: 'toolSuspend', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                        else {
+                            // Non-blocking call, we don't want to hold up execution here. But if we can emit start or error early below this we will try.
+                            toolExecutor.parse();
+                        }
+                        if (toolExecutor.emitRepairAttempt()) {
+                            yield emit({ type: 'toolArgRepairAttempt', tool: toolExecutor.tool, fields: toolExecutor.repairAttempt.fields, success: toolExecutor.repairAttempt.success, request });
+                        }
+                        if (toolExecutor.emitStart()) {
+                            yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                        }
+                        if (toolExecutor.emitError()) {
+                            yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, rawArgs: toolExecutor.rawArgs, request });
+                        }
+                    }
+                    // The execution mode for this iteration.
+                    const iterationMode = skip ? 'skip' : toolMode;
+                    // All tool calls are valid, lets start this!
+                    switch (iterationMode) {
+                        case 'sequential':
+                            for (const toolExecutor of toolExecutors) {
+                                // Abort-aware dispatch — once the caller's signal trips,
+                                // stop starting subsequent tools so Ctrl+C unwinds within
+                                // ~1 tool's duration instead of grinding through the rest
+                                // of the batch. The synthesis pass below pairs every
+                                // unstarted tool_call with an `[aborted]` placeholder.
+                                // We check `ctx.signal` directly (not the streamController
+                                // relay) because the relay's listener was already
+                                // removed by the time tool dispatch runs.
+                                if (ctx.signal?.aborted)
+                                    break;
+                                await toolExecutor.parse();
+                                if (toolExecutor.emitRepairAttempt()) {
+                                    yield emit({ type: 'toolArgRepairAttempt', tool: toolExecutor.tool, fields: toolExecutor.repairAttempt.fields, success: toolExecutor.repairAttempt.success, request });
+                                }
+                                if (toolExecutor.emitStart()) {
+                                    yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                                }
+                                await toolExecutor.run();
+                                if (toolExecutor.emitOutput()) {
+                                    yield emitTool({ type: 'toolOutput', tool: toolExecutor.tool, args: toolExecutor.args, result: toolExecutor.result, toModel: toolExecutor.toModel, request });
+                                }
+                                if (toolExecutor.emitInterrupt()) {
+                                    yield emitTool({ type: 'toolInterrupt', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                                }
+                                if (toolExecutor.emitSuspend()) {
+                                    yield emitTool({ type: 'toolSuspend', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                                }
+                                if (toolExecutor.emitError()) {
+                                    yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, rawArgs: toolExecutor.rawArgs, request });
+                                }
                             }
-                            if (toolExecutor.emitError()) {
-                                yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, request });
+                            break;
+                        case 'parallel':
+                        case 'immediate':
+                            const parseRuns = toolExecutors.map(tc => [tc.parse(), tc.run()]).flat();
+                            for await (const { result: toolCallPromise } of yieldAll(parseRuns)) {
+                                // The promises in `parseRuns` were started eagerly, so
+                                // tools already in flight will keep running in the
+                                // background (orphaned). What we control here is whether
+                                // we accumulate their results / emit their events. Bail
+                                // on abort so the caller doesn't have to wait for stragglers
+                                // to finish — synthesis below covers any unpaired tool_call.
+                                // (We check `ctx.signal` directly — streamController's
+                                // listener was already removed before tool dispatch.)
+                                if (ctx.signal?.aborted)
+                                    break;
+                                const toolExecutor = await toolCallPromise;
+                                if (toolExecutor.emitRepairAttempt()) {
+                                    yield emit({ type: 'toolArgRepairAttempt', tool: toolExecutor.tool, fields: toolExecutor.repairAttempt.fields, success: toolExecutor.repairAttempt.success, request });
+                                }
+                                if (toolExecutor.emitStart()) {
+                                    yield emitTool({ type: 'toolStart', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                                }
+                                if (toolExecutor.emitOutput()) {
+                                    yield emitTool({ type: 'toolOutput', tool: toolExecutor.tool, args: toolExecutor.args, result: toolExecutor.result, toModel: toolExecutor.toModel, request });
+                                }
+                                if (toolExecutor.emitInterrupt()) {
+                                    yield emitTool({ type: 'toolInterrupt', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                                }
+                                if (toolExecutor.emitSuspend()) {
+                                    yield emitTool({ type: 'toolSuspend', tool: toolExecutor.tool, args: toolExecutor.args, request });
+                                }
+                                if (toolExecutor.emitError()) {
+                                    yield emitTool({ type: 'toolError', tool: toolExecutor.tool, args: toolExecutor.args, error: toolExecutor.error, rawArgs: toolExecutor.rawArgs, request });
+                                }
                             }
+                            break;
+                    }
+                    // Emit tool results for every executor. The pairing guarantee:
+                    // every assistant `tool_calls[i]` pushed by this block must
+                    // have a matching `role: 'tool'` entry by the end of the loop,
+                    // otherwise the next round-trip 400s (OpenAI / Anthropic both
+                    // reject unpaired tool_calls).
+                    //
+                    // - `suspended`: skipped on purpose (suspend/resume relies on
+                    //   the missing slot to know which tool to resume).
+                    // - incomplete (`ready` / `parsed` / `executing` / `interrupted`
+                    //   without an error string): no real content. With
+                    //   `toolsComplete: true` (default) we synthesize a marker
+                    //   (`[aborted: …]`, `[interrupted]`) so the model knows WHY
+                    //   the slot is empty. With `toolsComplete: false` we omit
+                    //   the message entirely — the caller is on their own.
+                    // - complete (`success` / `error` / `invalid` / `interrupted`
+                    //   with an error string): emit the real result / error.
+                    let anySuspended = false;
+                    for (const toolExecutor of toolExecutors) {
+                        if (toolExecutor.status === 'suspended') {
+                            anySuspended = true;
+                            continue;
+                        }
+                        const hasError = !!toolExecutor.error;
+                        const hasResult = toolExecutor.result !== undefined && toolExecutor.result !== null;
+                        const isComplete = hasError || hasResult || toolExecutor.status === 'success';
+                        if (!isComplete && !toolsComplete) {
+                            // Opt-out — leave the unfinished tool_call without a
+                            // paired result. Caller has accepted responsibility for
+                            // handling the broken history shape (e.g. they're about
+                            // to discard the request entirely, or they have their
+                            // own retry logic).
+                            continue;
                         }
+                        // Model-facing value: on a real success we present `toModel`
+                        // (the raw result, or whatever `onToolResult` transformed it into
+                        // — set inside run() before success is marked). Any other slot
+                        // with a lingering result keeps the raw `result`. Serialized
+                        // exactly as before: strings verbatim, everything else JSON.
+                        const modelValue = toolExecutor.status === 'success' ? toolExecutor.toModel : toolExecutor.result;
+                        const content = hasError
+                            ? toolExecutor.error
+                            : hasResult
+                                ? typeof modelValue === 'string'
+                                    ? modelValue
+                                    : JSON.stringify(modelValue)
+                                : this.synthesizeUnpairedResult(toolExecutor);
+                        yield emitMessage({
+                            role: 'tool',
+                            content,
+                            toolCallId: toolExecutor.toolCall.id,
+                        });
+                        if (toolExecutor.status === 'invalid') {
+                            toolParseErrors++;
+                        }
+                        else if (toolExecutor.status === 'error') {
+                            toolCallErrors++;
+                        }
+                        else if (toolExecutor.status === 'success') {
+                            toolSuccesses++;
+                        }
+                    }
+                    if (anySuspended) {
+                        suspended = true;
                         break;
-                }
-                // Emit tool results for all completed tools. If any tool suspended, skip its result
-                // (the caller will supply it on resume) and break after processing the rest.
-                // request.messages ends with: [...history, assistantMsg(toolCalls), toolResult(completed)...]
-                let anySuspended = false;
-                for (const toolExecutor of toolExecutors) {
-                    if (toolExecutor.status === 'suspended') {
-                        anySuspended = true;
-                        continue; // Omit result — the pending result will be supplied on resume
                     }
-                    const content = toolExecutor.error
-                        ? toolExecutor.error
-                        : toolExecutor.result
-                            ? typeof toolExecutor.result === 'string'
-                                ? toolExecutor.result
-                                : JSON.stringify(toolExecutor.result)
-                            : '';
+                    if ((toolCallErrors + toolParseErrors) > toolErrorsPrevious) {
+                        if (toolRetries > 0) {
+                            toolRetries--;
+                        }
+                        else {
+                            disableTools = true;
+                        }
+                    }
+                }
+                else {
+                    // No tool calls, just add the assistant response
                     yield emitMessage({
-                        role: 'tool',
+                        role: 'assistant',
                         content,
-                        toolCallId: toolExecutor.toolCall.id,
+                        reasoning,
                     });
-                    if (toolExecutor.status === 'invalid') {
-                        toolParseErrors++;
-                    }
-                    else if (toolExecutor.status === 'error') {
-                        toolCallErrors++;
-                    }
-                    else if (toolExecutor.status === 'success') {
-                        toolSuccesses++;
-                    }
                 }
-                if (anySuspended) {
-                    suspended = true;
-                    break;
+                const hadToolErrors = toolParseErrorsPrevious !== toolParseErrors;
+                const hitMax = this.input.toolsMax && toolSuccesses >= this.input.toolsMax;
+                // If if there are only tool calls wanted...
+                if (onlyTools) {
+                    const noTools = toolExecutors.length === 0;
+                    // If we met our max tool calls, or had some successes with no new errors, or there are no more tools to call, end it.
+                    if (hitMax || noTools) {
+                        // got what we needed!
+                        lastError = undefined;
+                        break;
+                    }
                 }
-                if ((toolCallErrors + toolParseErrors) > toolErrorsPrevious) {
-                    if (toolRetries > 0) {
-                        toolRetries--;
+                else {
+                    // We don't only want tools, but if we had some successes and no new parse errors, remove tool requirement
+                    if (fixedToolChoice && toolSuccesses > 0 && !hadToolErrors) {
+                        delete request.toolChoice;
                     }
-                    else {
+                    // If we met our max tool calls, remove the tools from the request
+                    if (hitMax) {
+                        // No more tools for you!
                         disableTools = true;
                     }
                 }
-            }
-            else {
-                // No tool calls, just add the assistant response
-                yield emitMessage({
-                    role: 'assistant',
-                    content,
-                    reasoning,
-                });
-            }
-            const hadToolErrors = toolParseErrorsPrevious !== toolParseErrors;
-            const hitMax = this.input.toolsMax && toolSuccesses >= this.input.toolsMax;
-            // If if there are only tool calls wanted...
-            if (onlyTools) {
-                const noTools = toolExecutors.length === 0;
-                // If we met our max tool calls, or had some successes with no new errors, or there are no more tools to call, end it.
-                if (hitMax || noTools) {
-                    // got what we needed!
-                    lastError = undefined;
-                    break;
+                // Accumulate text content from this iteration
+                if (content.length > 0) {
+                    completeText += content;
                 }
-            }
-            else {
-                // We don't only want tools, but if we had some successes and no new parse errors, remove tool requirement
-                if (fixedToolChoice && toolSuccesses > 0 && !hadToolErrors) {
-                    delete request.toolChoice;
-                }
-                // If we met our max tool calls, remove the tools from the request
-                if (hitMax) {
-                    // No more tools for you!
-                    disableTools = true;
-                }
-            }
-            // Accumulate text content from this iteration
-            if (content.length > 0) {
-                completeText += content;
-            }
-            // Determine if we should stop
-            const stop = finishReason === 'stop' && toolExecutors.length === 0 ||
-                toolExecutors.some(toolExecutor => toolExecutor.status === 'interrupted');
-            // If we are finished, parse the output
-            if (stop) {
-                if (!schema || (schema instanceof ZodString)) {
-                    result = content;
-                    break; // All good!
-                }
-                else {
-                    // Grab the JSON part from the content just in case...
-                    const potentialJSON = content.substring(content.indexOf('{'), content.lastIndexOf('}') + 1);
-                    let errorMessage = '';
-                    let resetReason = '';
-                    try {
-                        const parsedJSON = JSON.parse(potentialJSON);
-                        const parsedSafe = await schema.safeParseAsync(parsedJSON);
-                        if (!parsedSafe.success) {
-                            const issueSummary = parsedSafe.error.issues
-                                .map(i => `- ${i.path.join('.')}: ${i.message}${['string', 'boolean', 'number'].includes(typeof i.input) ? ` (input: ${i.input})` : ''}`)
-                                .join('\n');
-                            errorMessage = `The output was an invalid format:\n${issueSummary}\n\nPlease adhere to the output schema:\n${toJSONSchema(schema, this.input.strict ?? true)}`;
-                            resetReason = 'schema-parsing';
-                        }
-                        else {
-                            result = parsedSafe.data;
-                            try {
-                                await this.input.validate?.(result, ctx);
+                // Determine if we should stop
+                const stop = finishReason === 'stop' && toolExecutors.length === 0 ||
+                    toolExecutors.some(toolExecutor => toolExecutor.status === 'interrupted');
+                // If we are finished, parse the output
+                if (stop) {
+                    if (!schema || (schema instanceof ZodString)) {
+                        result = content;
+                        break; // All good!
+                    }
+                    else {
+                        // Grab the JSON part from the content just in case. In the
+                        // schema-delivery prompt-text fallback the model replies with
+                        // freeform text (possibly fenced / prose-wrapped), so extract the
+                        // outermost balanced `{…}` (see `extractJSONObject`).
+                        const potentialJSON = extractJSONObject(content);
+                        let errorMessage = '';
+                        let resetReason = '';
+                        const errMax = this.input.validationErrorMaxLength;
+                        try {
+                            const parsedJSON = JSON.parse(potentialJSON);
+                            if (this.input.parse) {
+                                // Custom parser REPLACES Zod validation of the structured
+                                // output entirely. Mirrors Tool.parse's `parse` hook: the
+                                // JSON.parse-d value is first DECODEd back from the provider
+                                // wire shape to the CONCEPTUAL value via `decodeWire` (symmetric
+                                // with the strictify ENCODE the provider used to build the
+                                // request), so the caller's parser stays provider-agnostic — it
+                                // never sees array-of-pairs records, numeric-key tuples, or
+                                // null-for-optional. The parser returns the typed TOutput on
+                                // success or an Error (returned OR thrown) carrying rich,
+                                // compiler-style diagnostics. Zod's own validation is skipped. A
+                                // returned/thrown Error flows through the SAME output-retry
+                                // channel a Zod failure would, surfacing its own `.message`
+                                // (no Zod vocabulary — Zod never ran). Absent ⇒ unchanged.
+                                // Decode only when a descriptor was pinned; otherwise the wire
+                                // shape IS the conceptual shape and `parsedJSON` passes through.
+                                const customDescriptorId = typeof request.responseFormat === 'object'
+                                    ? request.responseFormat.descriptor
+                                    : undefined;
+                                const decoded = customDescriptorId
+                                    ? decodeWire(schema, parsedJSON, getDescriptorById(customDescriptorId))
+                                    : parsedJSON;
+                                let customResult;
+                                try {
+                                    customResult = await this.input.parse(decoded, ctx);
+                                }
+                                catch (customError) {
+                                    customResult = customError instanceof Error ? customError : new Error(String(customError));
+                                }
+                                if (customResult instanceof Error) {
+                                    errorMessage = this.truncateValidationError(customResult.message, errMax);
+                                    resetReason = 'schema-parsing';
+                                }
+                                else {
+                                    result = customResult;
+                                    try {
+                                        await this.input.validate?.(result, ctx);
+                                    }
+                                    catch (validationError) {
+                                        errorMessage = this.truncateValidationError(`The output failed validation:\n${validationError.message}`, errMax);
+                                        resetReason = 'validation';
+                                    }
+                                }
                             }
-                            catch (validationError) {
-                                errorMessage = `The output failed validation:\n${validationError.message}`;
-                                resetReason = 'validation';
+                            else {
+                                // Apply the same strictify rewrite the provider used for the wire
+                                // shape, so array-of-pairs records / numeric-key tuples / etc.
+                                // normalize back into the natural Zod shape before validation.
+                                // The descriptor was pinned on the response format when the
+                                // provider built the request. Fast cache lookup on retries.
+                                const responseDescriptorId = typeof request.responseFormat === 'object'
+                                    ? request.responseFormat.descriptor
+                                    : undefined;
+                                const validationSchema = responseDescriptorId
+                                    ? strictify(schema, getDescriptorById(responseDescriptorId))
+                                    : schema;
+                                const parsedSafe = await validationSchema.safeParseAsync(parsedJSON);
+                                if (!parsedSafe.success) {
+                                    const issueSummary = parsedSafe.error.issues
+                                        .map(i => `- ${i.path.join('.')}: ${i.message}${['string', 'boolean', 'number'].includes(typeof i.input) ? ` (input: ${i.input})` : ''}`)
+                                        .join('\n');
+                                    errorMessage = this.truncateValidationError(`The output was an invalid format:\n${issueSummary}`, errMax);
+                                    resetReason = 'schema-parsing';
+                                }
+                                else {
+                                    result = parsedSafe.data;
+                                    try {
+                                        await this.input.validate?.(result, ctx);
+                                    }
+                                    catch (validationError) {
+                                        errorMessage = this.truncateValidationError(`The output failed validation:\n${validationError.message}`, errMax);
+                                        resetReason = 'validation';
+                                    }
+                                }
                             }
                         }
-                    }
-                    catch (parseError) {
-                        errorMessage = `The output was not valid JSON:\n${parseError.message}`;
-                        resetReason = 'json-parsing';
-                    }
-                    if (errorMessage) {
-                        if (outputRetries > 0) {
-                            outputRetries--;
-                            yield emit({ type: 'textReset', reason: resetReason, request });
-                            yield emitMessage({
-                                role: 'user',
-                                content: errorMessage,
-                            });
+                        catch (parseError) {
+                            errorMessage = this.truncateValidationError(`The output was not valid JSON:\n${parseError.message}`, errMax);
+                            resetReason = 'json-parsing';
+                        }
+                        // Runtime schema-delivery fallback. The structured response was EMPTY
+                        // or its JSON was UNPARSEABLE (`json-parsing` reset — either the
+                        // content had no JSON object to extract or `JSON.parse` threw). Some
+                        // models (e.g. meta-llama/llama-4-maverick via OpenRouter) accept a
+                        // `response_format` json_schema whose descriptor CAN express the
+                        // schema yet reply with `finish: stop` and empty content, so the
+                        // static `canExpress` fallback in the ai layer never fires. Promote
+                        // this prompt's schema delivery to prompt-text for the RETRY: flip
+                        // the outgoing request's `responseFormat.schemaDelivery` to 'prompt'
+                        // so `applySchemaDeliveryFallback` (ai layer) drops `response_format`
+                        // and appends the schema as text + fallback instruction on the next
+                        // request build. Only when delivery is 'auto' and structured output
+                        // was actually attempted (`responseFormat` still an object), and only
+                        // once per run (`promotedToPromptDelivery` guard) so we never loop.
+                        // The switch is not remembered beyond this run. This reuses the
+                        // existing outputRetries re-prompt mechanism below to re-issue.
+                        if (this.input.runtimeSchemaFallback !== false &&
+                            resetReason === 'json-parsing' &&
+                            !promotedToPromptDelivery &&
+                            typeof request.responseFormat === 'object' &&
+                            (request.responseFormat.schemaDelivery ?? 'auto') === 'auto') {
+                            request.responseFormat.schemaDelivery = 'prompt';
+                            promotedToPromptDelivery = true;
+                        }
+                        if (errorMessage) {
+                            if (outputRetries > 0) {
+                                outputRetries--;
+                                yield emit({ type: 'textReset', reason: resetReason, request });
+                                yield emitMessage({
+                                    role: 'user',
+                                    content: errorMessage,
+                                });
+                            }
+                            else {
+                                lastError = errorMessage;
+                                break; // No more retries left
+                            }
                         }
                         else {
-                            lastError = errorMessage;
-                            break; // No more retries left
+                            // A result was successfully parsed and validated!
+                            lastError = undefined;
+                            break;
                         }
                     }
-                    else {
-                        // A result was successfully parsed and validated!
-                        lastError = undefined;
-                        break;
-                    }
                 }
             }
+            catch (requestError) {
+                if (!ctx.signal?.aborted &&
+                    !streamController.signal.aborted &&
+                    this.input.runtimeSchemaFallback !== false &&
+                    !promotedToPromptDelivery &&
+                    typeof request.responseFormat === 'object' &&
+                    (request.responseFormat.schemaDelivery ?? 'auto') === 'auto' &&
+                    outputRetries > 0) {
+                    // Mode-4 fallback: promote to prompt-text and retry (mirrors the
+                    // empty/unparseable json-parsing promotion above). Consumes one
+                    // `outputRetries`; the guard makes it fire at most once per run.
+                    request.responseFormat.schemaDelivery = 'prompt';
+                    promotedToPromptDelivery = true;
+                    outputRetries--;
+                    yield emit({ type: 'textReset', reason: 'request-error', request });
+                    requestFailedNeedsRetry = true;
+                }
+                else {
+                    throw requestError;
+                }
+            }
+            // A request-time failure was promoted to prompt-text delivery: skip the
+            // rest of this iteration (reconfig/dynamic/parse) and re-issue.
+            if (requestFailedNeedsRetry) {
+                iterations++;
+                continue;
+            }
             // Call reconfig if provided
             if (this.input.reconfig) {
                 const stats = {
@@ -739,6 +979,14 @@ export class Prompt {
         }
         // We don't emit complete without a valid result unless toolsOnly is set
         if (result === undefined && !onlyTools) {
+            // Abort is not an error — the caller asked us to stop. Exit
+            // silently with the partial `request.messages` they may want
+            // for resume/inspection, without emitting `complete` (no real
+            // output to surface) and without raising. Mirrors the suspend
+            // path's `return undefined` semantics.
+            if (ctx.signal?.aborted) {
+                return undefined;
+            }
             if (!lastError && iterations === maxIterations) {
                 lastError = `Maximum iterations (${maxIterations}) reached without a valid response.`;
             }
@@ -833,7 +1081,7 @@ export class Prompt {
         const content = this.content(contentInput);
         // Determine response format
         const responseFormat = schema && !(schema instanceof ZodString)
-            ? { type: schema, strict: this.input.strict ?? true }
+            ? { type: schema, strict: this.input.strict ?? 1, schemaDelivery: this.input.schemaDelivery ?? 'auto' }
             : 'text';
         return { config, content, tools, toolObjects, responseFormat, schema };
     }
@@ -853,6 +1101,65 @@ export class Prompt {
             return response;
         };
     }
+    /**
+     * Truncate a validation error so the corrective user message we send back
+     * to the LLM stays bounded. Lengthy zod errors against deep recursive
+     * schemas can run 100k+ characters — eating context and burning tokens
+     * on noise the model can't usefully act on. Anything past `max` is
+     * replaced with a `… (N more characters)` marker so the LLM both knows
+     * the message was clipped and roughly how much was lost.
+     *
+     * `protected` so a subclass can override — e.g. to emit a shorter
+     * marker, route errors through a custom formatter, or skip truncation
+     * entirely when targeting a model with a large context window.
+     */
+    truncateValidationError(message, max) {
+        const cap = max ?? DEFAULT_VALIDATION_ERROR_MAX_LENGTH;
+        if (cap <= 0 || message.length <= cap)
+            return message;
+        const dropped = message.length - cap;
+        return `${message.slice(0, cap)}… (${dropped} more characters)`;
+    }
+    /**
+     * Build a short, model-readable placeholder for a `tool_call` that
+     * never produced a real result. Used by the result-emit loop when
+     * `toolsComplete` is true to keep `request.messages` well-paired
+     * even when the dispatch loop short-circuited (signal abort or
+     * `ToolInterrupt` cutting a parallel batch short) or a tool errored
+     * before its content could be accumulated.
+     *
+     * The marker prefix (`[aborted: …]`, `[interrupted]`, `[error: …]`)
+     * gives the model a clear cue and lets callers detect synthesized
+     * replies by inspecting the message content if they need to
+     * differentiate. Suspended tools are intentionally NOT routed
+     * through here — the suspend/resume protocol depends on the
+     * missing result slot.
+     *
+     * `protected` so a subclass can override — e.g. to emit
+     * project-specific markers, log diagnostics for every synthesized
+     * result, or fall back to a model-specific instruction string.
+     */
+    synthesizeUnpairedResult(te) {
+        switch (te.status) {
+            case 'interrupted':
+                return te.error
+                    ? `[interrupted: ${te.error}]`
+                    : '[interrupted]';
+            case 'error':
+            case 'invalid':
+                return te.error
+                    ? `[error: ${te.error}]`
+                    : '[error]';
+            case 'ready':
+            case 'parsed':
+            case 'executing':
+                // Never reached a terminal status — the dispatch loop cut out
+                // mid-flight (abort or interrupt of a sibling).
+                return '[aborted: tool call did not complete before the request was cancelled]';
+            default:
+                return '[no result]';
+        }
+    }
     /**
      * Trims messages from the request to fit within token limits.
      *
@@ -989,12 +1296,38 @@ function emitter() {
     };
     return emitter;
 }
-function newToolExecution(ctx, toolCall, toolInfo) {
+function newToolExecution(ctx, toolCall, toolInfo, validationErrorMaxLength, 
+// Pluggable truncator — the owning Prompt instance forwards its
+// (overridable) `truncateValidationError` method here so a subclass
+// can change how tool-arg parse errors are formatted without having
+// to fork the whole prompt loop.
+truncate, 
+// Optional per-prompt result transformer (PromptInput.onToolResult),
+// pre-bound by the loop to build the discriminated event (tool name,
+// ctx, request) so this function only needs to feed it the raw result
+// and parsed args. Runs on the SUCCESS path only, INSIDE run() before
+// the tool is marked `success` / its output emitter is armed — so the
+// presented value lands on `toModel` and any throw converts the slot to
+// a normal tool error (correct events + preserved pairing). Absent ⇒
+// `toModel` is just the raw result.
+present, 
+// Optional per-prompt tool interceptor (PromptInput.onToolIntercept),
+// pre-bound by the loop with the matched Tool instance + ctx so this
+// function only needs the parsed args. Runs INSIDE run() BEFORE the tool's
+// own handler. A returned VALUE short-circuits and becomes `result` (the
+// handler is skipped, then the normal present/success path runs). Returning
+// `false`/`undefined` means "not intercepted" — the real handler runs. A
+// throw is NOT caught here: it propagates to run()'s catch and is routed
+// identically to a throw from the handler (PromptSuspend ⇒ suspended,
+// ToolInterrupt ⇒ interrupted, anything else ⇒ tool error). Absent ⇒ the
+// handler always runs.
+intercept) {
     const start = emitter();
     const output = emitter();
     const error = emitter();
     const interrupt = emitter();
     const suspend = emitter();
+    const repairAttempt = emitter();
     if (!toolInfo) {
         error.ready = true;
     }
@@ -1009,20 +1342,49 @@ function newToolExecution(ctx, toolCall, toolInfo) {
         emitError: error.emit,
         emitInterrupt: interrupt.emit,
         emitSuspend: suspend.emit,
+        emitRepairAttempt: repairAttempt.emit,
         parse: once(async () => {
             // Already ran or failed earlier?
             if (execution.status !== 'ready') {
                 return execution;
             }
-            const args = execution.toolCall.arguments || '{}';
+            const rawArgs = execution.toolCall.arguments;
+            const isEmpty = !rawArgs || rawArgs.trim() === '';
+            const args = isEmpty ? '{}' : rawArgs;
             try {
-                execution.args = await toolInfo.tool.parse(ctx, args, toolInfo.definition.parameters);
+                execution.args = await toolInfo.tool.parse(ctx, args, toolInfo.definition.parameters, toolInfo.definition.descriptor, (info) => {
+                    // String-encoded-field fallback ran a repair attempt
+                    // (success OR failure). Stash the outcome so the outer
+                    // loop can emit `toolArgRepairAttempt`. Keeping failures
+                    // visible matters as much as successes — they tell us the
+                    // model double-encoded AND the inner content was also
+                    // bad, which is a different bug than either alone.
+                    execution.repairAttempt = info;
+                    repairAttempt.ready = true;
+                });
                 execution.status = 'parsed';
                 start.ready = true;
             }
             catch (e) {
                 execution.status = 'invalid';
-                execution.error = `Error parsing tool arguments: ${e.message}, args: ${args}`;
+                // Preserve the untruncated raw args alongside the truncated
+                // model-facing error so the diagnostic log gets the full
+                // payload (post-mortem reproduction is impossible without it).
+                execution.rawArgs = args;
+                // Distinguish "model sent no arguments at all" from "model sent
+                // bad arguments". The former is usually a streaming-relay issue
+                // (OpenRouter/Anthropic) or a genuine model gaffe — calling it
+                // out by name in the error gives the model a clearer cue to
+                // fix itself on the retry turn instead of repeating the empty
+                // call. The latter (bad arguments) keeps its original Zod /
+                // JSON.parse message, which already names the offending field.
+                const reason = isEmpty
+                    ? `the tool was called with NO arguments. The schema requires arguments — re-call this tool with the required fields populated. Validation: ${e.message}`
+                    : `${e.message}, args: ${args}`;
+                const formatted = `Error parsing tool arguments: ${reason}`;
+                execution.error = truncate
+                    ? truncate(formatted, validationErrorMaxLength)
+                    : formatted;
                 error.ready = true;
             }
             return execution;
@@ -1034,7 +1396,34 @@ function newToolExecution(ctx, toolCall, toolInfo) {
             }
             try {
                 execution.status = 'executing';
-                execution.result = await resolve(toolInfo.tool.run(execution.args, { ...ctx, toolCallId: toolCall.id }));
+                // Optional per-prompt interceptor (PromptInput.onToolIntercept) runs
+                // BEFORE the tool's own handler. A returned value SHORT-CIRCUITS — it
+                // becomes the result and the handler never runs. `false`/`undefined`
+                // means "not intercepted": fall through to the real handler. A throw
+                // is intentionally NOT caught here — it flows to the catch below and
+                // is routed exactly like a throw from the handler (ToolInterrupt ⇒
+                // interrupted, PromptSuspend ⇒ suspended, else ⇒ tool error).
+                const intercepted = intercept ? await intercept(execution.args) : false;
+                execution.result = intercepted === false || intercepted === undefined
+                    ? await resolve(toolInfo.tool.run(execution.args, { ...ctx, toolCallId: toolCall.id }))
+                    : intercepted;
+                // Tool ran successfully. Apply the optional per-prompt result
+                // transformer BEFORE marking success / arming the output emitter,
+                // so the `toolOutput` event carries the presented `toModel` and the
+                // paired `role: 'tool'` content reflects it. A handler that THROWS
+                // is treated exactly like a tool error for this slot — the raw
+                // `result` stays on the executor (get('tools') / streamTools keep
+                // it) while the model-facing channel emits the error, preserving
+                // the tool_call ↔ role:'tool' pairing guarantee.
+                try {
+                    execution.toModel = present ? await present(execution.result, execution.args) : execution.result;
+                }
+                catch (e) {
+                    execution.status = 'error';
+                    execution.error = `Error transforming tool result: ${e.message}`;
+                    error.ready = true;
+                    return execution;
+                }
                 execution.status = 'success';
                 output.ready = true;
             }