@caupulican/pi-agent-core 0.86.11 → 0.86.17

package/dist/agent-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAyB7D,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAEZ,aAAa,EAGb,uBAAuB,EACvB,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAIzC;AAuBD,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAWzB;AAyFD;;;;GAIG;AACH,wBAAsB,gCAAgC,CAAC,OAAO,EAAE;IAC/D,gBAAgB,CAAC,EAAE,CAClB,OAAO,EAAE,uBAAuB,EAChC,MAAM,CAAC,EAAE,WAAW,KAChB,sBAAsB,GAAG,SAAS,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IACtF,KAAK,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB9B;AAmLD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CA8CxC;AA47BD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAO7F"}
+{"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAmC7D,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EAEZ,aAAa,EAEb,uBAAuB,EACvB,sBAAsB,EACtB,QAAQ,EACR,kBAAkB,EAClB,MAAM,YAAY,CAAC;AAIpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAEzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAIzC;AAuBD,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAgBzB;AAED,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,YAAY,EAAE,CAAC,CAWzB;AAyFD;;;;GAIG;AACH,wBAAsB,gCAAgC,CAAC,OAAO,EAAE;IAC/D,gBAAgB,CAAC,EAAE,CAClB,OAAO,EAAE,uBAAuB,EAChC,MAAM,CAAC,EAAE,WAAW,KAChB,sBAAsB,GAAG,SAAS,GAAG,OAAO,CAAC,sBAAsB,GAAG,SAAS,CAAC,CAAC;IACtF,KAAK,EAAE,uBAAuB,CAAC,OAAO,CAAC,CAAC;IACxC,OAAO,EAAE,uBAAuB,CAAC,SAAS,CAAC,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAmB9B;AAqLD;;;;;;GAMG;AACH,wBAAsB,yBAAyB,CAC9C,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,CAAC,EAAE,QAAQ,GACjB,OAAO,CAAC,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC,CA8CxC;AA+hCD,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,aAAa,GAAG,kBAAkB,GAAG,SAAS,CAO7F"}

package/dist/agent-loop.js

@@ -6,7 +6,8 @@ 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 { assessToolFailure, clearToolFailure, createRepeatedToolFailureResult, createToolFailureMemoryTracker, createToolFailureRecoveryExhaustedResult, createToolFailureResult, getUnresolvedToolFailure, normalizeToolSignature, rememberToolFailure, sanitizeToolFailureContext, toolFailureCorrection, } from "./tool-failure-memory.js";
+import { TOOL_FAILURE_RECOVERY_ACCOUNTING_WAVE_SIZE, ToolFailureRecoveryGate, } from "./tool-failure-recovery-gate.js";
 import { DEFAULT_MAX_STALL_TURNS } from "./types.js";
 import { createEmptyUsage } from "./usage.js";
 /**
@@ -189,6 +190,7 @@ 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 lastSuccessfulTextProtocolBatch;
     // Check for steering messages at start (user may have typed while waiting)
     let pendingMessages = (await config.getSteeringMessages?.()) || [];
@@ -233,7 +235,7 @@ 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;
                 for (const result of toolResults) {
@@ -426,82 +428,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 +578,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 +684,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 +709,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 +728,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 +758,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 +770,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 +803,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 +868,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 +883,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 +920,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 +931,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 +1006,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 +1043,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 +1073,7 @@ async function finalizeExecutedToolCall(currentContext, assistantMessage, prepar
         toolCall: prepared.toolCall,
         result: repaired.result,
         isError,
+        executionGateEffect,
     };
 }
 function createErrorToolResult(message) {