@kuralle-agents/core 0.15.0 → 0.17.0

package/dist/flow/runFlow.js

@@ -1,6 +1,6 @@
 import { popFlowPark, runCollectDigression } from './collectDigression.js';
 import { parseConfirmation } from './confirmParse.js';
-import { inferRequiredFields } from './extraction.js';
+import { inferRequiredFields, resetCollect } from './extraction.js';
 import { hasPendingUserInput, setPendingUserInput } from '../runtime/channels/inputBuffer.js';
 import { userInputToText } from '../runtime/userInput.js';
 import { collectUntilComplete } from './collectUntilComplete.js';
@@ -12,7 +12,7 @@ import { evaluateReplyControl } from './controlEvaluator.js';
 import { runNodeVerify, VerifyBlockedError } from './verify.js';
 import { loadRecordedSteps } from '../runtime/durable/replay.js';
 import { persistTurnUsageFromTurn } from '../runtime/turnTokenUsage.js';
-import { isApprovalDenial, isControlFlowSignal } from '../runtime/controlFlowSignal.js';
+import { isApprovalDenial, isControlFlowSignal, isRecoverableToolError } from '../runtime/controlFlowSignal.js';
 import { emitInteractiveOnNodeEnter } from './emitInteractive.js';
 import { appendConversationAudit } from '../audit/record.js';
 import { appendSafeAssistantMessage, degradeFlowError, findEscalateNode, } from './degrade.js';
@@ -304,7 +304,15 @@ export async function runFlow(flow, run, driver, ctx, agent) {
     }
     const edgeCounts = new Map();
     const maxOscillations = flow.maxOscillations ?? 2;
+    // The node to re-collect from when an action throws a recoverable error (bad referent,
+    // missing precondition). Tracked as the most recent collect node visited in THIS flow
+    // invocation. If an action runs before any collect (no node can re-collect), a
+    // recoverable error degrades exactly as a fatal one would.
+    let lastCollectNode;
     for (;;) {
+        if (isCollectNode(node)) {
+            lastCollectNode = node;
+        }
         let transition;
         try {
             transition = await dispatchNode(node, run, driver, ctx, agent, flow);
@@ -316,6 +324,25 @@ export async function runFlow(flow, run, driver, ctx, agent) {
             if (isControlFlowSignal(error) || isApprovalDenial(error)) {
                 throw error;
             }
+            if (isRecoverableToolError(error) && lastCollectNode) {
+                // The action node called a tool imperatively, so there is no model tool-call to
+                // attach a result to. Carry the message to the model as a system note (the next
+                // extraction/reply turn reads it from history), clear the offending collect's cache
+                // so re-entry genuinely re-collects instead of re-completing with the bad value, and
+                // return to that node. With the cache cleared and the turn's input already consumed
+                // by the collect that fed this action, collectUntilComplete emits its `ask` and
+                // parks on awaitingUser — a real re-ask, not an end.
+                resetCollect(run.state, lastCollectNode.id);
+                const note = {
+                    role: 'system',
+                    content: `Action "${node.id}" could not complete: ${error.message}. Re-collect the affected input from the user before retrying.`,
+                };
+                run.messages = [...run.messages, note];
+                node = lastCollectNode;
+                run.activeNode = node.id;
+                await ctx.runStore.putRunState(run);
+                continue;
+            }
             const message = error instanceof Error ? error.message : String(error);
             ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
             return degradeFlowError(flow, registry, run, driver, ctx, (n, r, d, c) => dispatchNode(n, r, d, c, agent, flow));

package/dist/runtime/Runtime.d.ts

@@ -27,6 +27,13 @@ import { type TraceSink, type TraceStore } from '../tracing/TraceStore.js';
  * that emits no text is indistinguishable from the agent having crashed.
  */
 export declare const HANDOFF_TO_HUMAN_MESSAGE = "I'm bringing a colleague into this \u2014 they'll pick it up from here.";
+/**
+ * What the user is told on any turn that arrives WHILE a run is already held for a human.
+ * The agent does not re-run for these turns — without a live `kuralle resume` the session
+ * would otherwise re-escalate every message regardless of topic. Distinct from
+ * `HANDOFF_TO_HUMAN_MESSAGE`, which is the one-time notice emitted on the escalating turn.
+ */
+export declare const HELD_FOR_HUMAN_MESSAGE = "A colleague is already handling this \u2014 I'll pick it back up as soon as they're done.";
 export interface TracingConfig {
     enabled?: boolean;
     store?: TraceStore;

package/dist/runtime/Runtime.js

@@ -41,6 +41,13 @@ import { runHookSafely } from './runHookSafely.js';
  * that emits no text is indistinguishable from the agent having crashed.
  */
 export const HANDOFF_TO_HUMAN_MESSAGE = "I'm bringing a colleague into this — they'll pick it up from here.";
+/**
+ * What the user is told on any turn that arrives WHILE a run is already held for a human.
+ * The agent does not re-run for these turns — without a live `kuralle resume` the session
+ * would otherwise re-escalate every message regardless of topic. Distinct from
+ * `HANDOFF_TO_HUMAN_MESSAGE`, which is the one-time notice emitted on the escalating turn.
+ */
+export const HELD_FOR_HUMAN_MESSAGE = "A colleague is already handling this — I'll pick it back up as soon as they're done.";
 export class Runtime {
     config;
     agentsById;
@@ -97,9 +104,18 @@ export class Runtime {
             // were observed producing empty output while silently firing transfer_to_agent, which
             // is indistinguishable from an outage.
             let sawUserText = false;
+            // Handoff targets already announced this turn. `hostLoop` emits a handoff part when
+            // the transfer control tool fires, and the terminal branch below emits one too —
+            // but only SOME terminal handoffs come through hostLoop's control path (a validator
+            // escalate does not), so neither emitter can be deleted. Deduplicate instead: the
+            // double emit produced a spurious `human -> human` self-edge in the trace, because
+            // by the second emit the recorder's current agent was already the target.
+            const announcedHandoffs = new Set();
             const emit = (part) => {
                 if (part.type === 'text-delta' && part.payload.delta)
                     sawUserText = true;
+                if (part.type === 'handoff')
+                    announcedHandoffs.add(part.payload.targetAgent);
                 recorder?.record(part);
                 if (part.type === 'done')
                     this.flushTraceSinks();
@@ -155,6 +171,13 @@ export class Runtime {
             // THIS turn's consumption (delta), not the running session total (see the
             // per-turn scope requirement in the observability guide).
             const usageBaseline = readCumulativeUsage(freshRunState.state);
+            // A run parked on a terminal-handoff escalation (status 'paused' with NO `waitingFor`)
+            // is held for a human until `resumeFromEscalation`. It must not re-run the agent —
+            // without this gate every later turn re-escalated, recycling the prior escalation's
+            // reason even for unrelated messages. `waitingFor` is the discriminator: suspend and
+            // approval waits also set status 'paused' but DO set `waitingFor` and resume by
+            // signal; gating those would hang every approval and every suspended tool.
+            const heldForHuman = freshRunState.status === 'paused' && !freshRunState.waitingFor;
             const model = opened.agent.model ?? this.defaultModel;
             if (!model) {
                 throw new Error('Runtime requires agent.model or config.defaultModel');
@@ -204,178 +227,213 @@ export class Runtime {
             let terminalOutcome;
             let overflowRetried = false;
             try {
-                turnLoop: for (;;) {
-                    try {
-                        loopResult = await hostLoop({
-                            agent: activeAgent,
-                            run: runCtx.runState,
-                            driver,
-                            ctx: runCtx,
-                            classify: this.config.hostClassify ??
-                                (this.config.hostSelect ? adaptHostSelect(this.config.hostSelect) : undefined),
-                        });
-                    }
-                    catch (error) {
-                        if (!overflowRetried && this.config.compaction && isContextOverflowError(error)) {
-                            overflowRetried = true;
-                            await this.recoverFromOverflow(runCtx, activeAgent, emit);
-                            continue turnLoop;
+                if (heldForHuman) {
+                    // Mirror the degraded-turn shape so TurnHandle consumers see a normal text +
+                    // `done` and do not hang: the hold message streams once, the turn is persisted,
+                    // and the existing `finally` emits `done` and runs closeRun. The agent never runs.
+                    const heldId = crypto.randomUUID();
+                    emit({ channel: 'client', type: 'text-start', payload: { id: heldId } });
+                    emit({ channel: 'client', type: 'text-delta', payload: { id: heldId, delta: HELD_FOR_HUMAN_MESSAGE } });
+                    emit({ channel: 'client', type: 'text-end', payload: { id: heldId } });
+                    runCtx.runState.messages = [
+                        ...runCtx.runState.messages,
+                        { role: 'assistant', content: HELD_FOR_HUMAN_MESSAGE },
+                    ];
+                    await runCtx.runStore.putRunState(runCtx.runState);
+                    // NOT a terminal outcome: the run stays `paused` (closeRun only flips to
+                    // `finished` when terminalOutcome is set). Setting it would both break the
+                    // hold — the next turn would no longer see `paused` — and trip a stale-version
+                    // outcome mark across multi-turn sessions.
+                    loopResult = { kind: 'ended', reason: 'held_for_human' };
+                }
+                else {
+                    turnLoop: for (;;) {
+                        try {
+                            loopResult = await hostLoop({
+                                agent: activeAgent,
+                                run: runCtx.runState,
+                                driver,
+                                ctx: runCtx,
+                                classify: this.config.hostClassify ??
+                                    (this.config.hostSelect ? adaptHostSelect(this.config.hostSelect) : undefined),
+                            });
                         }
-                        throw error;
-                    }
-                    if (loopResult.kind === 'handoff') {
-                        if (this.terminalHandoffTargets.has(loopResult.to)) {
-                            // This emit is load-bearing for TERMINAL targets specifically. A terminal
-                            // handoff breaks out of the loop here, before hostLoop's own emit and before
-                            // handoffHistory is appended — so this is the only handoff part a client ever
-                            // sees for an escalation. Removing it as "redundant" silently produced zero
-                            // handoff parts for every escalation; escalation.test.ts catches it.
-                            //
-                            // The self-edge seen live (handoff human->human, two spans on one turn) is a
-                            // real but SEPARATE defect on the non-terminal path — fix it there, not by
-                            // deleting this.
-                            emit({
-                                channel: 'internal',
-                                type: 'handoff',
-                                payload: { targetAgent: loopResult.to, reason: loopResult.reason },
+                        catch (error) {
+                            if (!overflowRetried && this.config.compaction && isContextOverflowError(error)) {
+                                overflowRetried = true;
+                                await this.recoverFromOverflow(runCtx, activeAgent, emit);
+                                continue turnLoop;
+                            }
+                            throw error;
+                        }
+                        if (loopResult.kind === 'handoff') {
+                            if (this.terminalHandoffTargets.has(loopResult.to)) {
+                                // This emit is load-bearing for TERMINAL targets specifically. A terminal
+                                // handoff breaks out of the loop here, before hostLoop's own emit and before
+                                // handoffHistory is appended — so this is the only handoff part a client ever
+                                // sees for an escalation. Removing it as "redundant" silently produced zero
+                                // handoff parts for every escalation; escalation.test.ts catches it.
+                                //
+                                // The self-edge seen live (handoff human->human, two spans on one turn) is a
+                                // real but SEPARATE defect on the non-terminal path — fix it there, not by
+                                // deleting this.
+                                if (!announcedHandoffs.has(loopResult.to)) {
+                                    emit({
+                                        channel: 'internal',
+                                        type: 'handoff',
+                                        payload: { targetAgent: loopResult.to, reason: loopResult.reason },
+                                    });
+                                }
+                                // Record the terminal handoff in handoffHistory. This branch used to `break`
+                                // before the non-terminal push below, so the array stayed empty and
+                                // isHandoffOscillating could never see repeated escalations. The oscillation
+                                // check only runs on the non-terminal branch and only counts consecutive
+                                // same-pair hops, so appending `agent -> human` here cannot trip a false
+                                // oscillation on a later legitimate handoff to a different target.
+                                opened.session.handoffHistory.push({
+                                    from: runCtx.runState.activeAgentId,
+                                    to: loopResult.to,
+                                    reason: loopResult.reason ?? 'handoff',
+                                    timestamp: new Date(),
+                                });
+                                runCtx.runState.status = 'paused';
+                                // Never hand off in silence. dispatchEscalation returns immediately when no
+                                // escalation handler is configured, so without this the turn ends with no
+                                // assistant text at all and the user cannot tell an escalation from a crash.
+                                if (!sawUserText) {
+                                    const handoffId = crypto.randomUUID();
+                                    emit({ channel: 'client', type: 'text-start', payload: { id: handoffId } });
+                                    emit({
+                                        channel: 'client',
+                                        type: 'text-delta',
+                                        payload: { id: handoffId, delta: HANDOFF_TO_HUMAN_MESSAGE },
+                                    });
+                                    emit({ channel: 'client', type: 'text-end', payload: { id: handoffId } });
+                                    runCtx.runState.messages = [
+                                        ...runCtx.runState.messages,
+                                        { role: 'assistant', content: HANDOFF_TO_HUMAN_MESSAGE },
+                                    ];
+                                }
+                                await runCtx.runStore.putRunState(runCtx.runState);
+                                await this.dispatchEscalation(runCtx, activeAgent, { reason: loopResult.reason ?? 'handoff_to_human', category: loopResult.category }, emit, { setLatch: false });
+                                break;
+                            }
+                            handoffCount += 1;
+                            if (handoffCount > this.maxHandoffs) {
+                                throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);
+                            }
+                            // Cross-turn ping-pong safeguard (handoffCount resets each turn, so it
+                            // can't catch A↔B oscillation spread across turns). This is a bound
+                            // ABOVE maxHandoffs: within-run runaway is caught by the maxHandoffs
+                            // check above; oscillation only fires for same-pair accumulation in the
+                            // persisted handoffHistory beyond that, so it never pre-empts maxHandoffs.
+                            if (isHandoffOscillating(opened.session.handoffHistory, runCtx.runState.activeAgentId, loopResult.to, this.maxHandoffs + 1)) {
+                                throw new Error(`Handoff oscillation detected between "${runCtx.runState.activeAgentId}" and "${loopResult.to}"`);
+                            }
+                            const target = this.agentsById.get(loopResult.to);
+                            if (!target) {
+                                throw new Error(`Handoff target agent not found: ${loopResult.to}`);
+                            }
+                            opened.session.handoffHistory.push({
+                                from: runCtx.runState.activeAgentId,
+                                to: loopResult.to,
+                                reason: loopResult.reason ?? 'handoff',
+                                timestamp: new Date(),
                             });
-                            runCtx.runState.status = 'paused';
-                            // Never hand off in silence. dispatchEscalation returns immediately when no
-                            // escalation handler is configured, so without this the turn ends with no
-                            // assistant text at all and the user cannot tell an escalation from a crash.
-                            if (!sawUserText) {
-                                const handoffId = crypto.randomUUID();
-                                emit({ channel: 'client', type: 'text-start', payload: { id: handoffId } });
-                                emit({
-                                    channel: 'client',
-                                    type: 'text-delta',
-                                    payload: { id: handoffId, delta: HANDOFF_TO_HUMAN_MESSAGE },
+                            const handoffTarget = loopResult.to;
+                            const routeFilter = activeAgent.routes?.find((r) => r.agent === handoffTarget)?.filter;
+                            const inputFilter = routeFilter ?? this.config.handoffInputFilter;
+                            if (inputFilter) {
+                                const filtered = await inputFilter({
+                                    messages: runCtx.runState.messages,
+                                    workingMemory: runCtx.session.workingMemory,
+                                    sourceAgentId: runCtx.runState.activeAgentId,
+                                    targetAgentId: handoffTarget,
+                                    reason: loopResult.reason,
                                 });
-                                emit({ channel: 'client', type: 'text-end', payload: { id: handoffId } });
-                                runCtx.runState.messages = [
-                                    ...runCtx.runState.messages,
-                                    { role: 'assistant', content: HANDOFF_TO_HUMAN_MESSAGE },
-                                ];
+                                runCtx.runState.messages = filtered.messages;
+                                runCtx.session.workingMemory = filtered.workingMemory;
                             }
-                            await runCtx.runStore.putRunState(runCtx.runState);
-                            await this.dispatchEscalation(runCtx, activeAgent, { reason: loopResult.reason ?? 'handoff_to_human', category: loopResult.category }, emit, { setLatch: false });
-                            break;
-                        }
-                        handoffCount += 1;
-                        if (handoffCount > this.maxHandoffs) {
-                            throw new Error(`maxHandoffs exceeded (${this.maxHandoffs})`);
-                        }
-                        // Cross-turn ping-pong safeguard (handoffCount resets each turn, so it
-                        // can't catch A↔B oscillation spread across turns). This is a bound
-                        // ABOVE maxHandoffs: within-run runaway is caught by the maxHandoffs
-                        // check above; oscillation only fires for same-pair accumulation in the
-                        // persisted handoffHistory beyond that, so it never pre-empts maxHandoffs.
-                        if (isHandoffOscillating(opened.session.handoffHistory, runCtx.runState.activeAgentId, loopResult.to, this.maxHandoffs + 1)) {
-                            throw new Error(`Handoff oscillation detected between "${runCtx.runState.activeAgentId}" and "${loopResult.to}"`);
-                        }
-                        const target = this.agentsById.get(loopResult.to);
-                        if (!target) {
-                            throw new Error(`Handoff target agent not found: ${loopResult.to}`);
-                        }
-                        opened.session.handoffHistory.push({
-                            from: runCtx.runState.activeAgentId,
-                            to: loopResult.to,
-                            reason: loopResult.reason ?? 'handoff',
-                            timestamp: new Date(),
-                        });
-                        const handoffTarget = loopResult.to;
-                        const routeFilter = activeAgent.routes?.find((r) => r.agent === handoffTarget)?.filter;
-                        const inputFilter = routeFilter ?? this.config.handoffInputFilter;
-                        if (inputFilter) {
-                            const filtered = await inputFilter({
-                                messages: runCtx.runState.messages,
-                                workingMemory: runCtx.session.workingMemory,
-                                sourceAgentId: runCtx.runState.activeAgentId,
-                                targetAgentId: handoffTarget,
-                                reason: loopResult.reason,
+                            runCtx.runState.activeAgentId = loopResult.to;
+                            activeAgent = target;
+                            const targetSurface = await buildAgentToolSurface(target, opened.session, {
+                                configTools: this.config.tools,
+                                knowledgeProvider,
+                                defaultWorkingMemoryStore: this.config.defaultWorkingMemoryStore,
+                            });
+                            runCtx.autoRetrieve = knowledgeProvider
+                                ? buildAutoRetrieveProvider(knowledgeProvider, target)
+                                : undefined;
+                            runCtx.globalTools = targetSurface.globalTools;
+                            runCtx.skillPrompt = targetSurface.skillPrompt;
+                            runCtx.workingMemoryPrompt = appendGoalsPrompt(targetSurface.workingMemoryPrompt, runCtx.session.workingMemory);
+                            runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
+                            runCtx.fs = targetSurface.resolvedWorkspace?.fs;
+                            runCtx.memoryService = this.config.memoryService
+                                ? buildMemoryService(this.config.memoryService, target)
+                                : undefined;
+                            const targetPolicies = resolveAgentPolicies(target);
+                            const targetModel = target.model ?? this.defaultModel;
+                            if (!targetModel) {
+                                throw new Error('Runtime requires agent.model or config.defaultModel');
+                            }
+                            runCtx.baseInstructions =
+                                (this.config.silentHandoff ?? true)
+                                    ? applyHandoffContinuation(target.instructions)
+                                    : target.instructions;
+                            runCtx.model = targetModel;
+                            runCtx.controlModel = target.controlModel ?? targetModel;
+                            runCtx.outOfBandControl = resolveOutOfBandControl(target);
+                            runCtx.limits = targetPolicies.limits;
+                            runCtx.refinementPolicies = targetPolicies.refinementPolicies;
+                            runCtx.validationPolicies = targetPolicies.validationPolicies;
+                            runCtx.inputProcessors = targetPolicies.inputProcessors;
+                            runCtx.outputProcessors = targetPolicies.outputProcessors;
+                            runCtx.toolExecutor = new CoreToolExecutor({
+                                tools: targetSurface.executorTools,
+                                enforcer: targetPolicies.enforcer,
+                                agentId: target.id,
+                                onInterim: (message) => {
+                                    const id = crypto.randomUUID();
+                                    emit({ channel: 'client', type: 'text-start', payload: { id } });
+                                    emit({
+                                        channel: 'client',
+                                        type: 'text-delta',
+                                        payload: { id, delta: message },
+                                    });
+                                    emit({ channel: 'client', type: 'text-end', payload: { id } });
+                                },
+                                onChunk: (chunk, toolName, toolCallId) => {
+                                    emit({
+                                        channel: 'internal',
+                                        type: 'tool-result',
+                                        payload: { toolName, result: chunk, toolCallId, preliminary: true },
+                                    });
+                                },
                             });
-                            runCtx.runState.messages = filtered.messages;
-                            runCtx.session.workingMemory = filtered.workingMemory;
+                            await runCtx.runStore.putRunState(runCtx.runState);
+                            continue;
                         }
-                        runCtx.runState.activeAgentId = loopResult.to;
-                        activeAgent = target;
-                        const targetSurface = await buildAgentToolSurface(target, opened.session, {
-                            configTools: this.config.tools,
-                            knowledgeProvider,
-                            defaultWorkingMemoryStore: this.config.defaultWorkingMemoryStore,
-                        });
-                        runCtx.autoRetrieve = knowledgeProvider
-                            ? buildAutoRetrieveProvider(knowledgeProvider, target)
-                            : undefined;
-                        runCtx.globalTools = targetSurface.globalTools;
-                        runCtx.skillPrompt = targetSurface.skillPrompt;
-                        runCtx.workingMemoryPrompt = appendGoalsPrompt(targetSurface.workingMemoryPrompt, runCtx.session.workingMemory);
-                        runCtx.workingMemoryTools = targetSurface.workingMemoryTools;
-                        runCtx.fs = targetSurface.resolvedWorkspace?.fs;
-                        runCtx.memoryService = this.config.memoryService
-                            ? buildMemoryService(this.config.memoryService, target)
-                            : undefined;
-                        const targetPolicies = resolveAgentPolicies(target);
-                        const targetModel = target.model ?? this.defaultModel;
-                        if (!targetModel) {
-                            throw new Error('Runtime requires agent.model or config.defaultModel');
+                        if (loopResult.kind === 'ended') {
+                            terminalOutcome = 'resolved';
+                            break;
                         }
-                        runCtx.baseInstructions =
-                            (this.config.silentHandoff ?? true)
-                                ? applyHandoffContinuation(target.instructions)
-                                : target.instructions;
-                        runCtx.model = targetModel;
-                        runCtx.controlModel = target.controlModel ?? targetModel;
-                        runCtx.outOfBandControl = resolveOutOfBandControl(target);
-                        runCtx.limits = targetPolicies.limits;
-                        runCtx.refinementPolicies = targetPolicies.refinementPolicies;
-                        runCtx.validationPolicies = targetPolicies.validationPolicies;
-                        runCtx.inputProcessors = targetPolicies.inputProcessors;
-                        runCtx.outputProcessors = targetPolicies.outputProcessors;
-                        runCtx.toolExecutor = new CoreToolExecutor({
-                            tools: targetSurface.executorTools,
-                            enforcer: targetPolicies.enforcer,
-                            agentId: target.id,
-                            onInterim: (message) => {
-                                const id = crypto.randomUUID();
-                                emit({ channel: 'client', type: 'text-start', payload: { id } });
-                                emit({
-                                    channel: 'client',
-                                    type: 'text-delta',
-                                    payload: { id, delta: message },
-                                });
-                                emit({ channel: 'client', type: 'text-end', payload: { id } });
-                            },
-                            onChunk: (chunk, toolName, toolCallId) => {
-                                emit({
-                                    channel: 'internal',
-                                    type: 'tool-result',
-                                    payload: { toolName, result: chunk, toolCallId, preliminary: true },
-                                });
-                            },
-                        });
-                        await runCtx.runStore.putRunState(runCtx.runState);
-                        continue;
-                    }
-                    if (loopResult.kind === 'ended') {
-                        terminalOutcome = 'resolved';
-                        break;
-                    }
-                    if (loopResult.kind === 'paused') {
-                        if (runCtx.runState.waitingFor?.signalName === '__escalate') {
-                            // Flow escalate() parks on the durable signal — notify the human
-                            // side now; the latch keeps the post-resume terminal handoff from
-                            // notifying a second time.
-                            const meta = runCtx.runState.waitingFor.meta;
-                            await this.dispatchEscalation(runCtx, activeAgent, { reason: String(meta?.reason ?? 'flow_escalation') }, emit, { setLatch: true });
+                        if (loopResult.kind === 'paused') {
+                            if (runCtx.runState.waitingFor?.signalName === '__escalate') {
+                                // Flow escalate() parks on the durable signal — notify the human
+                                // side now; the latch keeps the post-resume terminal handoff from
+                                // notifying a second time.
+                                const meta = runCtx.runState.waitingFor.meta;
+                                await this.dispatchEscalation(runCtx, activeAgent, { reason: String(meta?.reason ?? 'flow_escalation') }, emit, { setLatch: true });
+                            }
+                            break;
                         }
                         break;
                     }
-                    break;
+                    // Post-turn maintenance: text already streamed, so the summarizer call
+                    // is off the user's latency path; the NEXT turn starts compact.
+                    await this.applyCompaction(runCtx, activeAgent, emit, false);
                 }
-                // Post-turn maintenance: text already streamed, so the summarizer call
-                // is off the user's latency path; the NEXT turn starts compact.
-                await this.applyCompaction(runCtx, activeAgent, emit, false);
             }
             catch (error) {
                 await runHookSafely('onError', () => this.hooks?.onError?.(runCtx, error));

package/dist/runtime/channels/executeModelTool.js

@@ -2,7 +2,7 @@ import { classifyControl } from '../../flow/classifyControl.js';
 import { toolDeniedResult, toolErrorResult } from '../../tools/controlResults.js';
 import { idempotencyKey, logicalRunId } from '../durable/idempotency.js';
 import { findStepByKey } from '../durable/replay.js';
-import { isApprovalDenial, isControlFlowSignal } from '../controlFlowSignal.js';
+import { isApprovalDenial, isControlFlowSignal, isRecoverableToolError } from '../controlFlowSignal.js';
 export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
     try {
         const localTool = localTools?.[call.toolName];
@@ -36,6 +36,12 @@ export async function executeModelToolCall(ctx, call, localTools, durableOpts) {
             // the turn dies and the user never hears why. No client error part: nothing broke.
             return { result: toolDeniedResult(error.toolName, error.by), failed: true };
         }
+        if (isRecoverableToolError(error)) {
+            // The model can correct this (bad referent, missing precondition): return the message
+            // as a tool result so it can retry. Not a malfunction, so no client error part —
+            // same posture as an approval denial.
+            return { result: toolErrorResult(error), failed: true };
+        }
         const message = error instanceof Error ? error.message : String(error);
         ctx.emit({ channel: 'client', type: 'error', payload: { error: message } });
         return { result: toolErrorResult(error), failed: true };

package/dist/runtime/closeRun.js

@@ -29,6 +29,12 @@ export async function closeRun(options) {
         // otherwise lacks assistant turns and keeps pre-guardrail (unredacted)
         // user input written at openRun.
         latest.messages = [...runState.messages];
+        // Persist handoff history accumulated on the run's working session this turn
+        // (terminal + non-terminal handoffs alike). Without this the in-memory pushes
+        // were silently dropped: stores that clone on get/save (e.g. MemoryStore) hand
+        // back a fresh snapshot here, and the previous mutator never copied handoffHistory
+        // across — so isHandoffOscillating's cross-turn safeguard never saw prior turns.
+        latest.handoffHistory = session.handoffHistory;
         syncPendingUserInput(ctx.session, latest);
     });
 }

package/dist/runtime/controlFlowSignal.d.ts

@@ -1,4 +1,4 @@
-import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+import { RecoverableToolError, ToolApprovalDeniedError } from '../tools/effect/errors.js';
 /**
  * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
  * It unwinds the stack like an error but is not a failure, so it must never be reported to
@@ -22,3 +22,9 @@ export declare function isControlFlowSignal(error: unknown): boolean;
  *   call the tool and can catch it or branch on `ctx.approve()` instead.
  */
 export declare function isApprovalDenial(error: unknown): error is ToolApprovalDeniedError;
+/**
+ * A tool failed in a way the model can correct (bad referent, missing precondition). Not a
+ * control-flow signal and not a fatal fault: on the flow path it routes back to re-collecting
+ * the offending input rather than degrading the turn.
+ */
+export declare function isRecoverableToolError(error: unknown): error is RecoverableToolError;

package/dist/runtime/controlFlowSignal.js

@@ -1,5 +1,5 @@
 import { SuspendError } from './durable/RunStore.js';
-import { ToolApprovalDeniedError } from '../tools/effect/errors.js';
+import { RecoverableToolError, ToolApprovalDeniedError } from '../tools/effect/errors.js';
 /**
  * The run is not finished: stop the turn, keep the journal, resume when a signal arrives.
  * It unwinds the stack like an error but is not a failure, so it must never be reported to
@@ -27,3 +27,11 @@ export function isControlFlowSignal(error) {
 export function isApprovalDenial(error) {
     return error instanceof ToolApprovalDeniedError;
 }
+/**
+ * A tool failed in a way the model can correct (bad referent, missing precondition). Not a
+ * control-flow signal and not a fatal fault: on the flow path it routes back to re-collecting
+ * the offending input rather than degrading the turn.
+ */
+export function isRecoverableToolError(error) {
+    return error instanceof RecoverableToolError;
+}

package/dist/tools/effect/errors.d.ts

@@ -4,6 +4,21 @@ export declare class ToolTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(toolName: string, timeoutMs: number);
 }
+/**
+ * Thrown by a tool's `execute` (or a guard wrapping it) when the call failed for a
+ * reason the model can correct: a referent that does not exist ("Unknown unit '12B'"),
+ * a value out of range, a missing precondition the user can supply. Distinct from a
+ * fatal fault (network down, schema broken) in that the model should see the message
+ * and retry — not be told "something went wrong on my side".
+ *
+ * On the model path it is returned to the model as a tool result (the model self-corrects).
+ * On the flow path it is the signal to re-collect the offending input instead of
+ * degrading the flow — see `runFlow`. Detected by type (`isRecoverableToolError`), never
+ * by string-matching the message.
+ */
+export declare class RecoverableToolError extends Error {
+    constructor(message: string);
+}
 /** Thrown when a human denies a tool call that requires approval. */
 export declare class ToolApprovalDeniedError extends Error {
     readonly toolName: string;

package/dist/tools/effect/errors.js

@@ -9,6 +9,24 @@ export class ToolTimeoutError extends Error {
         this.timeoutMs = timeoutMs;
     }
 }
+/**
+ * Thrown by a tool's `execute` (or a guard wrapping it) when the call failed for a
+ * reason the model can correct: a referent that does not exist ("Unknown unit '12B'"),
+ * a value out of range, a missing precondition the user can supply. Distinct from a
+ * fatal fault (network down, schema broken) in that the model should see the message
+ * and retry — not be told "something went wrong on my side".
+ *
+ * On the model path it is returned to the model as a tool result (the model self-corrects).
+ * On the flow path it is the signal to re-collect the offending input instead of
+ * degrading the flow — see `runFlow`. Detected by type (`isRecoverableToolError`), never
+ * by string-matching the message.
+ */
+export class RecoverableToolError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RecoverableToolError';
+    }
+}
 /** Thrown when a human denies a tool call that requires approval. */
 export class ToolApprovalDeniedError extends Error {
     toolName;

package/package.json

@@ -6,7 +6,7 @@
     "url": "git+https://github.com/kuralle/kuralle-agents.git",
     "directory": "packages/core"
   },
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "A framework for structured conversational AI agents",
   "publishConfig": {
     "access": "public"
@@ -103,7 +103,7 @@
     "typescript": "^5.3.0",
     "vitest": "^3.2.4",
     "zod": "^4.0.0",
-    "@kuralle-agents/fs": "0.14.1"
+    "@kuralle-agents/fs": "0.17.0"
   },
   "dependencies": {
     "chrono-node": "^2.6.0"