@caupulican/pi-agent-core 0.86.14 → 0.90.0

package/dist/agent-loop.js

@@ -3,12 +3,15 @@
  * Transforms to Message[] only at the LLM call boundary.
  */
 import { EventStream } from "@caupulican/pi-ai/event-stream";
-import { streamSimple } from "@caupulican/pi-ai/stream";
 import { formatToolRepairStandingRule, REPEATED_SUCCESSFUL_TOOL_CALL_FAILURE, } from "@caupulican/pi-ai/tool-repair-registry";
 import { ToolArgumentValidationError, validateToolArguments, } from "@caupulican/pi-ai/validation";
-import { assessToolFailure, clearToolFailure, createToolFailureMemoryTracker, createToolFailureResult, normalizeToolSignature, rememberToolFailure, sanitizeToolFailureContext, toolFailureCorrection, } from "./tool-failure-memory.js";
+import { startPlannedAgentProviderRequest } from "./provider-request-planner.js";
+import { assessToolFailure, clearToolFailure, createRepeatedToolFailureResult, createToolFailureMemoryTracker, createToolFailureRecoveryExhaustedResult, createToolFailureResult, getUnresolvedToolFailure, normalizeToolSignature, rememberToolFailure, toolFailureCorrection, } from "./tool-failure-memory.js";
+import { TOOL_FAILURE_RECOVERY_ACCOUNTING_WAVE_SIZE, ToolFailureRecoveryGate, } from "./tool-failure-recovery-gate.js";
+import { appendMandatoryToolFailureDeliveryPrompt } from "./tool-failure-recovery-protocol.js";
 import { DEFAULT_MAX_STALL_TURNS } from "./types.js";
 import { createEmptyUsage } from "./usage.js";
+export { resolveRequestPreflightMaxTokens } from "./provider-request-planner.js";
 /**
  * Start an agent loop with a new prompt message.
  * The prompt is added to the context and events are emitted for it.
@@ -88,6 +91,24 @@ function createLoopFailureMessage(error, config, aborted) {
         timestamp: Date.now(),
     };
 }
+function createMandatoryRecoveryDeliveryFallback(halt, config) {
+    const diagnostic = halt.record.diagnostic ?? halt.diagnostic;
+    return {
+        role: "assistant",
+        content: [
+            {
+                type: "text",
+                text: `Tool recovery stopped for ${halt.record.tool}: ${diagnostic} Required recovery: ${halt.record.correction}`,
+            },
+        ],
+        api: config.model.api,
+        provider: config.model.provider,
+        model: config.model.id,
+        usage: createEmptyUsage(),
+        stopReason: "stop",
+        timestamp: Date.now(),
+    };
+}
 function createAgentStream() {
     return new EventStream((event) => event.type === "agent_end", (event) => (event.type === "agent_end" ? event.messages : []));
 }
@@ -143,31 +164,6 @@ function repeatsSuccessfulTextProtocolBatch(incomingSignature, toolCalls, previo
         return phase === "edited" && toolCall.name === "edit" && previousCall.name === "edit";
     });
 }
-/**
- * Apply one request-local preflight without mutating persistent loop configuration.
- * Shared with isolated tool-free provider calls so every transport boundary has identical
- * validation and non-widening semantics.
- */
-export async function resolveRequestPreflightMaxTokens(options) {
-    if (!options.requestPreflight)
-        return options.maxTokens;
-    if (options.maxTokens !== undefined && (!Number.isSafeInteger(options.maxTokens) || options.maxTokens <= 0)) {
-        throw new TypeError("request maxTokens must be a positive safe integer");
-    }
-    const preflight = await options.requestPreflight({ model: options.model, context: options.context, maxTokens: options.maxTokens }, options.signal);
-    if (preflight?.maxTokens === undefined)
-        return options.maxTokens;
-    if (!Number.isSafeInteger(preflight.maxTokens) || preflight.maxTokens <= 0) {
-        throw new TypeError("requestPreflight.maxTokens must be a positive safe integer");
-    }
-    const ceilings = [preflight.maxTokens];
-    if (options.maxTokens !== undefined)
-        ceilings.push(options.maxTokens);
-    if (Number.isSafeInteger(options.model.maxTokens) && options.model.maxTokens > 0) {
-        ceilings.push(options.model.maxTokens);
-    }
-    return Math.min(...ceilings);
-}
 /**
  * Main loop logic shared by agentLoop and agentLoopContinue.
  */
@@ -189,6 +185,8 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
     const validationFailureTracker = { repeats: 0 };
     const repairTeachTracker = new Map();
     let toolFailureMemory = createToolFailureMemoryTracker(currentContext.messages);
+    const toolFailureRecoveryGate = new ToolFailureRecoveryGate();
+    let mandatoryRecoveryDeliveryPending = false;
     let lastSuccessfulTextProtocolBatch;
     // Check for steering messages at start (user may have typed while waiting)
     let pendingMessages = (await config.getSteeringMessages?.()) || [];
@@ -214,8 +212,26 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                 }
                 pendingMessages = [];
             }
-            // Stream assistant response
-            const message = await streamAssistantResponse(currentContext, config, signal, emit, streamFn);
+            // Recovery exhaustion receives exactly one provider turn without tools so the mandatory
+            // diagnostic can reach the user instead of terminating on an undelivered tool result.
+            const recoveryDeliveryTurn = mandatoryRecoveryDeliveryPending;
+            const recoveryDeliveryHalt = recoveryDeliveryTurn ? toolFailureRecoveryGate.getHalt() : undefined;
+            if (recoveryDeliveryTurn && !recoveryDeliveryHalt) {
+                throw new Error("Mandatory recovery delivery started without a recovery halt");
+            }
+            const responseContext = recoveryDeliveryHalt
+                ? {
+                    ...currentContext,
+                    systemPrompt: appendMandatoryToolFailureDeliveryPrompt(currentContext.systemPrompt, {
+                        tool: recoveryDeliveryHalt.record.tool,
+                        failureCode: recoveryDeliveryHalt.record.failureCode,
+                        diagnostic: recoveryDeliveryHalt.record.diagnostic ?? recoveryDeliveryHalt.diagnostic,
+                        requiredAction: recoveryDeliveryHalt.record.correction,
+                    }),
+                    tools: [],
+                }
+                : currentContext;
+            const message = await streamAssistantResponse(responseContext, config, signal, emit, streamFn);
             newMessages.push(message);
             if (message.stopReason === "error" || message.stopReason === "aborted") {
                 await emit({ type: "turn_end", message, toolResults: [] });
@@ -225,6 +241,30 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             // Check for tool calls
             const toolCalls = message.content.filter((c) => c.type === "toolCall");
             const toolResults = [];
+            if (recoveryDeliveryTurn) {
+                if (!recoveryDeliveryHalt) {
+                    throw new Error("Mandatory recovery delivery continued without a recovery halt");
+                }
+                if (toolCalls.length > 0) {
+                    toolResults.push(...(await rejectRecoveryDeliveryToolCalls(toolCalls, recoveryDeliveryHalt, emit)));
+                    for (const result of toolResults) {
+                        currentContext.messages.push(result);
+                        newMessages.push(result);
+                    }
+                }
+                await emit({ type: "turn_end", message, toolResults });
+                if (toolCalls.length > 0) {
+                    const fallback = createMandatoryRecoveryDeliveryFallback(recoveryDeliveryHalt, config);
+                    currentContext.messages.push(fallback);
+                    newMessages.push(fallback);
+                    await emit({ type: "turn_start" });
+                    await emit({ type: "message_start", message: fallback });
+                    await emit({ type: "message_end", message: fallback });
+                    await emit({ type: "turn_end", message: fallback, toolResults: [] });
+                }
+                await emit({ type: "agent_end", messages: newMessages });
+                return;
+            }
             hasMoreToolCalls = false;
             if (toolCalls.length > 0) {
                 const textProtocolBatch = toolCalls.every((toolCall) => toolCall.source === "text-protocol");
@@ -233,9 +273,15 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     repeatsSuccessfulTextProtocolBatch(incomingBatchSignature, toolCalls, lastSuccessfulTextProtocolBatch)
                     ? lastSuccessfulTextProtocolBatch?.messages
                     : undefined;
-                const executedToolBatch = await executeToolCalls(currentContext, message, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit);
+                const executedToolBatch = await executeToolCalls(currentContext, message, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, previousSuccessfulTextProtocolResults, signal, emit);
                 toolResults.push(...executedToolBatch.messages);
-                hasMoreToolCalls = !executedToolBatch.terminate;
+                if (toolFailureRecoveryGate.isHalted()) {
+                    mandatoryRecoveryDeliveryPending = true;
+                    hasMoreToolCalls = true;
+                }
+                else {
+                    hasMoreToolCalls = !executedToolBatch.terminate;
+                }
                 for (const result of toolResults) {
                     currentContext.messages.push(result);
                     newMessages.push(result);
@@ -258,7 +304,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
             }
             await emit({ type: "turn_end", message, toolResults });
             // Runaway-loop backstop (cost guard): detect a model stuck repeating one action.
-            if (stallLimit > 0 && toolCalls.length > 0) {
+            if (!mandatoryRecoveryDeliveryPending && stallLimit > 0 && toolCalls.length > 0) {
                 const signature = normalizeToolSignature(toolCalls.map((c) => [c.name, c.arguments ?? null]));
                 stallWindow.push(signature);
                 if (stallWindow.length > stallLimit * STALL_WINDOW_PERIODS)
@@ -288,12 +334,13 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
                     reasoning: nextTurnSnapshot.thinkingLevel ?? config.reasoning,
                 };
             }
-            if (await config.shouldStopAfterTurn?.({
-                message,
-                toolResults,
-                context: currentContext,
-                newMessages,
-            })) {
+            if (!mandatoryRecoveryDeliveryPending &&
+                (await config.shouldStopAfterTurn?.({
+                    message,
+                    toolResults,
+                    context: currentContext,
+                    newMessages,
+                }))) {
                 await emit({ type: "agent_end", messages: newMessages });
                 return;
             }
@@ -319,46 +366,7 @@ async function runLoop(initialContext, newMessages, initialConfig, signal, emit,
  * and request preflight immediately before transport.
  */
 export async function startAgentProviderRequest(context, config, signal, streamFn) {
-    // Failed protocol turns never reach host transforms or provider conversion. Their bounded,
-    // unresolved state is carried separately in the system prompt until the same operation succeeds.
-    const sanitized = sanitizeToolFailureContext(context.messages, context.systemPrompt);
-    let messages = sanitized.messages;
-    if (config.transformContext) {
-        messages = await config.transformContext(messages, signal);
-    }
-    // Convert to LLM-compatible messages (AgentMessage[] → Message[])
-    const llmMessages = await config.convertToLlm(messages);
-    // Build LLM context
-    const llmContext = {
-        systemPrompt: sanitized.systemPrompt,
-        messages: llmMessages,
-        tools: context.tools,
-    };
-    const streamFunction = streamFn || streamSimple;
-    const requestMaxTokens = await resolveRequestPreflightMaxTokens({
-        requestPreflight: config.requestPreflight,
-        model: config.model,
-        context: llmContext,
-        maxTokens: config.maxTokens,
-        signal,
-    });
-    // Resolve credentials only after the request-local authority/budget gate accepts the request.
-    // This prevents an already-exhausted background lane from refreshing OAuth/SSO credentials.
-    const resolvedApiKey = (config.getApiKey ? await config.getApiKey(config.model.provider) : undefined) || config.apiKey;
-    const requestReasoning = config.resolveRequestReasoning
-        ? config.resolveRequestReasoning(config.reasoning, {
-            model: config.model,
-            context: llmContext,
-            maxTokens: requestMaxTokens,
-        })
-        : config.reasoning;
-    return await streamFunction(config.model, llmContext, {
-        ...config,
-        apiKey: resolvedApiKey,
-        maxTokens: requestMaxTokens,
-        reasoning: requestReasoning,
-        signal,
-    });
+    return startPlannedAgentProviderRequest(context, config, signal, streamFn);
 }
 /**
  * Stream an assistant response from the LLM.
@@ -426,82 +434,131 @@ async function streamAssistantResponse(context, config, signal, emit, streamFn)
 /**
  * Execute tool calls from an assistant message.
  */
-async function executeToolCalls(currentContext, assistantMessage, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit) {
+async function executeToolCalls(currentContext, assistantMessage, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, previousSuccessfulTextProtocolResults, signal, emit) {
     const toolCalls = assistantMessage.content.filter((c) => c.type === "toolCall");
     const hasSequentialToolCall = toolCalls.some((tc) => currentContext.tools?.find((t) => t.name === tc.name)?.executionMode === "sequential");
+    const execCtx = {
+        context: currentContext,
+        assistantMessage,
+        config,
+        validationFailureTracker,
+        repairTeachTracker,
+        toolFailureMemory,
+        toolFailureRecoveryGate,
+        previousSuccessfulResults: previousSuccessfulTextProtocolResults,
+        signal,
+        emit,
+    };
     if (config.toolExecution === "sequential" || hasSequentialToolCall) {
-        return executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit);
+        return executeToolCallsSequential(execCtx, toolCalls);
     }
-    return executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit);
+    return executeToolCallsParallel(execCtx, toolCalls);
 }
-async function prepareAndStartToolCall(currentContext, assistantMessage, toolCall, index, config, validationFailureTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit) {
-    const preparation = previousSuccessfulTextProtocolResults
-        ? createRepeatedSuccessfulToolCallOutcome(previousSuccessfulTextProtocolResults[index])
-        : await prepareToolCall(currentContext, assistantMessage, toolCall, config, validationFailureTracker, signal);
-    await emitToolExecutionStart(toolCall, emit);
+async function prepareAndStartToolCall(execCtx, toolCall, index) {
+    const preparation = execCtx.previousSuccessfulResults
+        ? createRepeatedSuccessfulToolCallOutcome(execCtx.previousSuccessfulResults[index])
+        : await prepareToolCall(execCtx.context, execCtx.assistantMessage, toolCall, execCtx.config, execCtx.validationFailureTracker, execCtx.toolFailureMemory, execCtx.toolFailureRecoveryGate, execCtx.signal);
+    await emitToolExecutionStart(toolCall, execCtx.emit);
     if (preparation.kind === "immediate") {
-        emitToolArgumentValidationTelemetry(config, preparation.validationEvent, "not_run", "none");
-        return { kind: "finalized", finalized: finalizeRejectedToolCall(toolCall, preparation, toolFailureMemory) };
+        emitToolArgumentValidationTelemetry(execCtx.config, preparation.validationEvent, "not_run", "none");
+        return {
+            kind: "finalized",
+            finalized: finalizeRejectedToolCall(toolCall, preparation, execCtx.toolFailureMemory, execCtx.toolFailureRecoveryGate),
+        };
     }
     return { kind: "prepared", preparation };
 }
-async function executeToolCallsSequential(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit) {
+async function finalizeStartedToolCall(execCtx, started) {
+    if (started.kind === "finalized")
+        return started.finalized;
+    return executeAndFinalizePreparedToolCall(execCtx.context, execCtx.assistantMessage, started.preparation, execCtx.config, execCtx.repairTeachTracker, execCtx.toolFailureMemory, execCtx.toolFailureRecoveryGate, execCtx.signal, execCtx.emit);
+}
+async function executeToolCallsSequential(execCtx, toolCalls) {
     const finalizedCalls = [];
     const messages = [];
     for (const [index, toolCall] of toolCalls.entries()) {
-        const started = await prepareAndStartToolCall(currentContext, assistantMessage, toolCall, index, config, validationFailureTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit);
-        let finalized;
-        if (started.kind === "finalized") {
-            finalized = started.finalized;
-        }
-        else {
-            finalized = await executeAndFinalizePreparedToolCall(currentContext, assistantMessage, started.preparation, config, repairTeachTracker, toolFailureMemory, signal, emit);
-        }
-        await emitToolExecutionEnd(finalized, emit);
+        const started = await prepareAndStartToolCall(execCtx, toolCall, index);
+        const finalized = applyToolFailureRecoveryEffect(execCtx.toolFailureRecoveryGate, await finalizeStartedToolCall(execCtx, started));
+        await emitToolExecutionEnd(finalized, execCtx.emit);
         const toolResultMessage = createToolResultMessage(finalized);
-        await emitToolResultMessage(toolResultMessage, emit);
+        await emitToolResultMessage(toolResultMessage, execCtx.emit);
         finalizedCalls.push(finalized);
         messages.push(toolResultMessage);
-        if (signal?.aborted) {
+        if (execCtx.signal?.aborted) {
             break;
         }
     }
     return {
         messages,
-        terminate: shouldTerminateToolBatch(finalizedCalls),
+        terminate: execCtx.toolFailureRecoveryGate.isHalted() || shouldTerminateToolBatch(finalizedCalls),
     };
 }
-async function executeToolCallsParallel(currentContext, assistantMessage, toolCalls, config, validationFailureTracker, repairTeachTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit) {
-    const finalizedCalls = [];
-    for (const [index, toolCall] of toolCalls.entries()) {
-        const started = await prepareAndStartToolCall(currentContext, assistantMessage, toolCall, index, config, validationFailureTracker, toolFailureMemory, previousSuccessfulTextProtocolResults, signal, emit);
-        if (started.kind === "finalized") {
-            await emitToolExecutionEnd(started.finalized, emit);
-            finalizedCalls.push(started.finalized);
-            if (signal?.aborted) {
+async function executeToolCallsParallel(execCtx, toolCalls) {
+    const orderedFinalizedCalls = [];
+    let nextIndex = 0;
+    // Account each bounded concurrent wave before launching more calls. Otherwise a single
+    // assistant batch could start an unbounded number of failures before the circuit observes one.
+    while (nextIndex < toolCalls.length && !execCtx.signal?.aborted) {
+        const waveEnd = Math.min(nextIndex + TOOL_FAILURE_RECOVERY_ACCOUNTING_WAVE_SIZE, toolCalls.length);
+        const wave = [];
+        const completionOrder = [];
+        for (; nextIndex < waveEnd; nextIndex++) {
+            const toolCall = toolCalls[nextIndex];
+            const started = await prepareAndStartToolCall(execCtx, toolCall, nextIndex);
+            if (started.kind === "finalized") {
+                await emitToolExecutionEnd(started.finalized, execCtx.emit);
+                wave.push(started.finalized);
+            }
+            else {
+                wave.push(async () => {
+                    const finalized = await finalizeStartedToolCall(execCtx, started);
+                    completionOrder.push(finalized);
+                    return finalized;
+                });
+            }
+            if (execCtx.signal?.aborted) {
+                nextIndex++;
                 break;
             }
-            continue;
         }
-        finalizedCalls.push(async () => {
-            const finalized = await executeAndFinalizePreparedToolCall(currentContext, assistantMessage, started.preparation, config, repairTeachTracker, toolFailureMemory, signal, emit);
-            await emitToolExecutionEnd(finalized, emit);
-            return finalized;
+        const unappliedWave = await Promise.all(wave.map((entry) => (typeof entry === "function" ? entry() : Promise.resolve(entry))));
+        const appliedByOriginal = new Map();
+        const finalizedWave = unappliedWave.map((finalized) => {
+            const applied = applyToolFailureRecoveryEffect(execCtx.toolFailureRecoveryGate, finalized);
+            appliedByOriginal.set(finalized, applied);
+            return applied;
         });
-        if (signal?.aborted) {
-            break;
+        for (const finalized of completionOrder) {
+            await emitToolExecutionEnd(appliedByOriginal.get(finalized) ?? finalized, execCtx.emit);
         }
+        orderedFinalizedCalls.push(...finalizedWave);
     }
-    const orderedFinalizedCalls = await Promise.all(finalizedCalls.map((entry) => (typeof entry === "function" ? entry() : Promise.resolve(entry))));
     const messages = [];
     for (const finalized of orderedFinalizedCalls) {
         const toolResultMessage = createToolResultMessage(finalized);
-        await emitToolResultMessage(toolResultMessage, emit);
+        await emitToolResultMessage(toolResultMessage, execCtx.emit);
         messages.push(toolResultMessage);
     }
     return {
         messages,
-        terminate: shouldTerminateToolBatch(orderedFinalizedCalls),
+        terminate: execCtx.toolFailureRecoveryGate.isHalted() || shouldTerminateToolBatch(orderedFinalizedCalls),
+    };
+}
+function applyToolFailureRecoveryEffect(gate, finalized) {
+    const halt = gate.apply(finalized.executionGateEffect);
+    if (!halt)
+        return finalized;
+    return createRecoveryExhaustedToolCallOutcome(finalized, halt);
+}
+function createRecoveryExhaustedToolCallOutcome(finalized, halt) {
+    const exhaustedResult = createToolFailureRecoveryExhaustedResult(halt.record, halt.diagnostic);
+    return {
+        ...finalized,
+        result: {
+            ...exhaustedResult,
+            ...(finalized.result.usage ? { usage: finalized.result.usage } : {}),
+        },
+        isError: true,
     };
 }
 const DEFAULT_TOOL_VALIDATION_ESCALATION_THRESHOLD = 3;
@@ -527,6 +584,18 @@ function createRepeatedSuccessfulToolCallOutcome(previousResult) {
         ...(previousResult ? { repeatedSuccessfulCall: { previousToolCallId: previousResult.toolCallId } } : {}),
     };
 }
+function createAbortedToolCallOutcome(validationEvent, executionGateReservation) {
+    return {
+        kind: "immediate",
+        result: createErrorToolResult("Operation aborted"),
+        isError: true,
+        phase: "cancelled",
+        failureCode: "aborted",
+        correction: "Retry only if the operation is still required.",
+        ...(executionGateReservation ? { executionGateReservation } : {}),
+        validationEvent,
+    };
+}
 function shouldTerminateToolBatch(finalizedCalls) {
     return finalizedCalls.length > 0 && finalizedCalls.every((finalized) => finalized.result.terminate === true);
 }
@@ -621,7 +690,7 @@ function handleValidationFailure(error, config, tracker) {
     });
     return `${error.message}\n\nRepeated validation failure (${tracker.repeats} identical attempts). Use this full schema and example before retrying:\n${error.enrichment}`;
 }
-async function prepareToolCall(currentContext, assistantMessage, toolCall, config, validationFailureTracker, signal) {
+async function prepareToolCall(currentContext, assistantMessage, toolCall, config, validationFailureTracker, toolFailureMemory, toolFailureRecoveryGate, signal) {
     const tool = currentContext.tools?.find((candidate) => candidate.name === toolCall.name);
     if (!tool) {
         return {
@@ -646,6 +715,7 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
         };
     }
     let validationEvent;
+    let executionGateReservation;
     try {
         const preparedToolCall = prepareToolCallArguments(tool, toolCall);
         const validatedArgs = validateToolArguments(tool, preparedToolCall, {
@@ -664,6 +734,28 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
             toolCall.rawArguments ??= toolCall.arguments;
             toolCall.arguments = validatedArgs;
         }
+        const unresolvedRecord = getUnresolvedToolFailure(toolFailureMemory, toolCall.name, validatedArgs);
+        const admission = toolFailureRecoveryGate.admit(tool, validatedArgs, unresolvedRecord);
+        if (admission.kind === "blocked") {
+            const failureCode = admission.exhausted ? "recovery_exhausted" : "repeated_failed_operation";
+            const result = admission.exhausted
+                ? createToolFailureRecoveryExhaustedResult(admission.record, admission.diagnostic ?? "Tool failure recovery budget exhausted.")
+                : createRepeatedToolFailureResult(admission.record);
+            const memoryRecord = result.details.piToolFailureMemory;
+            toolFailureMemory.set(admission.record.failureKey, memoryRecord);
+            return {
+                kind: "immediate",
+                result,
+                isError: true,
+                phase: admission.record.phase,
+                failureCode,
+                correction: memoryRecord.correction,
+                diagnostic: memoryRecord.diagnostic,
+                repeatedToolFailure: true,
+                validationEvent: createValidationBounceTelemetry(config, toolCall, failureCode),
+            };
+        }
+        executionGateReservation = admission.reservation;
         if (config.beforeToolCall) {
             const beforeResult = await config.beforeToolCall({
                 assistantMessage,
@@ -672,15 +764,7 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                 context: currentContext,
             }, signal);
             if (signal?.aborted) {
-                return {
-                    kind: "immediate",
-                    result: createErrorToolResult("Operation aborted"),
-                    isError: true,
-                    phase: "cancelled",
-                    failureCode: "aborted",
-                    correction: "Retry only if the operation is still required.",
-                    validationEvent,
-                };
+                return createAbortedToolCallOutcome(validationEvent, executionGateReservation);
             }
             if (beforeResult?.block) {
                 const reason = beforeResult.reason || "Tool execution was blocked";
@@ -692,26 +776,20 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                     failureCode: "blocked",
                     correction: "Choose an allowed approach or request the required authority before retrying.",
                     diagnostic: reason,
+                    ...(executionGateReservation ? { executionGateReservation } : {}),
                     validationEvent,
                 };
             }
         }
         if (signal?.aborted) {
-            return {
-                kind: "immediate",
-                result: createErrorToolResult("Operation aborted"),
-                isError: true,
-                phase: "cancelled",
-                failureCode: "aborted",
-                correction: "Retry only if the operation is still required.",
-                validationEvent,
-            };
+            return createAbortedToolCallOutcome(validationEvent, executionGateReservation);
         }
         return {
             kind: "prepared",
             toolCall,
             tool,
             args: validatedArgs,
+            ...(executionGateReservation ? { executionGateReservation } : {}),
             validationEvent,
         };
     }
@@ -731,13 +809,29 @@ async function prepareToolCall(currentContext, assistantMessage, toolCall, confi
                 ? validationFailureCorrection(validationEvent, toolCall.name)
                 : toolFailureCorrection(message, "rejected", "preflight"),
             diagnostic: isToolArgumentValidationError(error) ? undefined : message,
+            ...(executionGateReservation ? { executionGateReservation } : {}),
             validationEvent,
         };
     }
 }
-function finalizeRejectedToolCall(toolCall, outcome, tracker) {
+function finalizeRejectedToolCall(toolCall, outcome, tracker, toolFailureRecoveryGate) {
+    if (outcome.repeatedToolFailure) {
+        return {
+            toolCall,
+            result: outcome.result,
+            isError: true,
+        };
+    }
     const record = rememberToolFailure(tracker, toolCall.name, toolCall.arguments, "rejected", outcome.failureCode, outcome.correction, outcome.diagnostic, outcome.phase);
-    const failureResult = createToolFailureResult(record, outcome.result.terminate);
+    const halt = toolFailureRecoveryGate.apply({
+        kind: "failure",
+        record,
+        args: toolCall.arguments,
+        ...(outcome.executionGateReservation ? { reservation: outcome.executionGateReservation } : {}),
+    });
+    const failureResult = halt
+        ? createToolFailureRecoveryExhaustedResult(halt.record, halt.diagnostic)
+        : createToolFailureResult(record, outcome.result.terminate);
     return {
         toolCall,
         result: outcome.repeatedSuccessfulCall
@@ -780,12 +874,12 @@ function getBackgroundToolCallDelay(config) {
         return undefined;
     return delay;
 }
-async function executeAndFinalizePreparedToolCall(currentContext, assistantMessage, prepared, config, repairTeachTracker, toolFailureMemory, foregroundSignal, emit) {
+async function executeAndFinalizePreparedToolCall(currentContext, assistantMessage, prepared, config, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, foregroundSignal, emit) {
     const backgroundDelay = getBackgroundToolCallDelay(config);
     if (!config.handoffToolCall ||
         (backgroundDelay === undefined && config.subscribeToolCallHandoffRequest === undefined)) {
         const executed = await executePreparedToolCall(prepared, foregroundSignal, emit);
-        return finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, foregroundSignal);
+        return finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, foregroundSignal);
     }
     const executionAbort = createLinkedToolAbort(foregroundSignal);
     const startedAt = Date.now();
@@ -795,7 +889,8 @@ async function executeAndFinalizePreparedToolCall(currentContext, assistantMessa
             if (emitForegroundUpdates)
                 return emit(event);
         });
-        return finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, executionAbort.signal);
+        const finalized = await finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, executionAbort.signal);
+        return finalized;
     })();
     completion.then(executionAbort.detachForeground, executionAbort.detachForeground);
     let deadlineTimer;
@@ -831,6 +926,9 @@ async function executeAndFinalizePreparedToolCall(currentContext, assistantMessa
         return outcome.value;
     if (executionAbort.signal.aborted)
         return completion;
+    let handoffAccepted = false;
+    const handedOffCompletion = completion.then((finalized) => handoffAccepted ? applyToolFailureRecoveryEffect(toolFailureRecoveryGate, finalized) : finalized);
+    void handedOffCompletion.catch(() => undefined);
     let handoff;
     try {
         handoff = config.handoffToolCall({
@@ -839,13 +937,14 @@ async function executeAndFinalizePreparedToolCall(currentContext, assistantMessa
             args: prepared.args,
             context: currentContext,
             elapsedMs: Math.max(0, Date.now() - startedAt),
-            completion,
+            completion: handedOffCompletion,
             cancel: executionAbort.cancel,
         });
     }
     catch {
         return completion;
     }
+    handoffAccepted = handoff !== undefined;
     if (!handoff)
         return completion;
     emitForegroundUpdates = false;
@@ -913,11 +1012,12 @@ function appendRepairTeachNotes(result, toolCall, tracker, config) {
         taught: true,
     };
 }
-async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, signal) {
+async function finalizeExecutedToolCall(currentContext, assistantMessage, prepared, executed, config, repairTeachTracker, toolFailureMemory, toolFailureRecoveryGate, signal) {
     let result = executed.result;
     let isError = executed.isError;
     let failureMessage = executed.failureMessage ?? "";
     let errorClass = executed.errorClass;
+    let executionGateEffect;
     if (config.afterToolCall) {
         try {
             const afterResult = await config.afterToolCall({
@@ -949,11 +1049,27 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
         const usage = result.usage;
         const effectiveFailureMessage = failureMessage || result.content.find((block) => block.type === "text")?.text || "Tool execution failed";
         const assessment = assessToolFailure(effectiveFailureMessage, "failed", errorClass);
-        const record = rememberToolFailure(toolFailureMemory, prepared.toolCall.name, prepared.args, "failed", assessment.failureCode, assessment.guidance, assessment.diagnostic, assessment.phase);
+        const recoveryPlan = toolFailureRecoveryGate.planFailure(prepared.tool, prepared.args, assessment.failureCode, currentContext.tools ?? [], prepared.executionGateReservation);
+        const record = rememberToolFailure(toolFailureMemory, prepared.toolCall.name, prepared.args, "failed", assessment.failureCode, recoveryPlan.guidance, assessment.diagnostic, assessment.phase);
+        executionGateEffect = {
+            kind: "failure",
+            record,
+            args: prepared.args,
+            targets: recoveryPlan.targets,
+            ...(prepared.executionGateReservation ? { reservation: prepared.executionGateReservation } : {}),
+        };
         result = { ...createToolFailureResult(record, result.terminate), usage };
     }
     else {
         clearToolFailure(toolFailureMemory, prepared.toolCall.name, prepared.args);
+        if (!executed.isError) {
+            executionGateEffect = {
+                kind: "success",
+                tool: prepared.tool,
+                args: prepared.args,
+                evidenceResult: executed.result,
+            };
+        }
     }
     const repaired = isError
         ? { result, taught: false }
@@ -963,6 +1079,7 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
         toolCall: prepared.toolCall,
         result: repaired.result,
         isError,
+        executionGateEffect,
     };
 }
 function createErrorToolResult(message) {
@@ -1015,4 +1132,20 @@ async function emitToolResultMessage(toolResultMessage, emit) {
     await emit({ type: "message_start", message: toolResultMessage });
     await emit({ type: "message_end", message: toolResultMessage });
 }
+async function rejectRecoveryDeliveryToolCalls(toolCalls, halt, emit) {
+    const messages = [];
+    for (const toolCall of toolCalls) {
+        await emitToolExecutionStart(toolCall, emit);
+        const finalized = {
+            toolCall,
+            result: createToolFailureRecoveryExhaustedResult(halt.record, "Tool execution is disabled during the mandatory recovery delivery turn."),
+            isError: true,
+        };
+        await emitToolExecutionEnd(finalized, emit);
+        const message = createToolResultMessage(finalized);
+        await emitToolResultMessage(message, emit);
+        messages.push(message);
+    }
+    return messages;
+}
 //# sourceMappingURL=agent-loop.js.map