@qduc/term2 0.11.0 → 0.12.0

package/dist/services/conversation/conversation-orchestrator.js

@@ -1,12 +1,12 @@
 import { describeError, isAbortLikeError } from '../../utils/error-helpers.js';
-import { ASK_USER_DECLINE_RESULT } from '../../tools/agent/ask-user-constants.js';
 import { createMessageIdFactory } from '../../utils/message-id-factory.js';
 import { isUserMessage } from '../../types/message.js';
 import { isDeniedReadApproveAnswer } from '../../contracts/conversation.js';
 import { createStreamingSession } from '../../utils/streaming/streaming-session-factory.js';
 import { enhanceApiKeyError, isMaxTurnsError } from '../../utils/conversation/conversation-utils.js';
 import { clearStreamingBotMessage, computeNextMessages } from '../../utils/conversation/apply-conversation-result.js';
-import { countUndoableUserTurnsFrom, findLastUndoableUserMessage, trimTrailingAssistantMessages, } from '../../utils/conversation/message-utils.js';
+import { trimTrailingAssistantMessages } from '../../utils/conversation/message-utils.js';
+import { ASK_USER_NO_ANSWER_RESULT } from '../../tools/agent/ask-user-constants.js';
 import { annotateApprovedCommandMessage, filterPendingCommandMessagesForApproval, } from '../approval/approval-presentation-policy.js';
 import { formatUserTurnForDisplay, hasUserTurnContent, injectSkillIntoTurn, normalizeUserTurn, } from '../../types/user-turn.js';
 const REASONING_RESPONSE_THROTTLE_MS = 200;
@@ -16,34 +16,161 @@ const REASONING_RESPONSE_THROTTLE_MS = 200;
  * by reference rather than inlined.
  */
 function formatBackgroundSubagentNotifications(notifications) {
-    const noun = notifications.length === 1 ? 'run' : 'runs';
-    const entries = notifications.map((notification) => {
+    const completions = notifications.filter((notification) => notification.kind === 'completion');
+    const questions = notifications.filter((notification) => notification.kind === 'question');
+    const shellCompletions = notifications.filter((notification) => notification.kind === 'shell_completion');
+    const userControls = notifications.filter((notification) => notification.kind === 'user_control');
+    const sections = [];
+    if (completions.length > 0) {
+        const noun = completions.length === 1 ? 'run' : 'runs';
+        const entries = completions.map((notification) => {
+            const lines = [
+                `- runId: ${notification.runId} | role: ${notification.role} | status: ${notification.status}`,
+                ...(notification.error ? [`  error: ${notification.error}`] : []),
+                '  result:',
+                notification.formattedResult
+                    .split('\n')
+                    .map((line) => `    ${line}`)
+                    .join('\n'),
+            ];
+            return lines.join('\n');
+        });
+        sections.push([
+            `Background subagent ${noun} finished (${completions.length}). This is an automatic system notification, not a user message.`,
+            '',
+            ...entries,
+            '',
+            'The full result is inlined above; you do not need to call get_subagent_result. Assess it against the task before you accept it, then continue through the next necessary steps yourself rather than stopping at the fact that a run finished. Tell the user concisely, in your own words, what you concluded — the report is input to your judgement, not a message to relay.',
+        ].join('\n'));
+    }
+    if (questions.length > 0) {
+        const entries = questions.map((notification) => {
+            const target = notification.name ?? notification.runId;
+            return [
+                `- messageId: ${notification.messageId} | target: ${target} | runId: ${notification.runId} | role: ${notification.role}`,
+                `  question: ${notification.question}`,
+            ].join('\n');
+        });
+        sections.push([
+            `Background subagent question${questions.length === 1 ? '' : 's'} pending (${questions.length}). This is an automatic system notification, not a user message.`,
+            '',
+            ...entries,
+            '',
+            'Decide the answer, investigate it yourself, or escalate to the user if needed. To answer a specific waiting subagent, call send_message({ target, reply_to: messageId, message }). The subagent has no direct user channel; an answer resumes only its waiting tool call.',
+        ].join('\n'));
+    }
+    if (shellCompletions.length > 0) {
+        const noun = shellCompletions.length === 1 ? 'job' : 'jobs';
+        const entries = shellCompletions.map((notification) => [
+            `- jobId: ${notification.jobId} | command: ${notification.command} | status: ${notification.status}`,
+            ...(notification.error ? [`  error: ${notification.error}`] : []),
+            '  output:',
+            notification.output
+                .split('\n')
+                .map((line) => `    ${line}`)
+                .join('\n'),
+        ].join('\n'));
+        sections.push([
+            `Background shell ${noun} finished (${shellCompletions.length}). This is an automatic system notification, not a user message.`,
+            '',
+            ...entries,
+            '',
+            'Assess the command result against the task and continue through the next necessary steps. Tell the user concisely, in your own words, what you concluded.',
+        ].join('\n'));
+    }
+    if (userControls.length > 0) {
+        const stopControls = userControls.filter((notification) => notification.action === 'stop');
+        const backgroundMoves = userControls.filter((notification) => notification.action === 'background');
+        const entriesFor = (notifications, verb) => notifications.map((notification) => {
+            const details = notification.details;
+            return details.kind === 'subagent'
+                ? `- ${verb} background subagent ${details.name ?? details.id} | runId: ${details.id} | role: ${details.role} | task: ${details.task}`
+                : `- ${verb} background shell | jobId: ${details.id} | command: ${details.command}`;
+        });
+        if (stopControls.length > 0) {
+            sections.push([
+                `The user requested that ${stopControls.length === 1 ? 'a background task be stopped' : 'background tasks be stopped'}. This is an automatic user control notification, not a user message.`,
+                '',
+                ...entriesFor(stopControls, 'stop requested for'),
+                '',
+                'Plan the next step around the requested stop. The task may settle later with a cancelled completion notification; do not assume its result is available yet.',
+            ].join('\n'));
+        }
+        if (backgroundMoves.length > 0) {
+            sections.push([
+                `The user moved ${backgroundMoves.length === 1
+                    ? 'a foreground shell into the background'
+                    : 'foreground shells into the background'}. This is an automatic user control notification, not a user message.`,
+                '',
+                ...entriesFor(backgroundMoves, 'moved to'),
+                '',
+                'The same execution continues running in the background. Plan the next step without waiting for it, and do not stop or relaunch it unless the task now requires that.',
+            ].join('\n'));
+        }
+    }
+    return sections.join('\n\n');
+}
+/** The user-facing companion to the model-only background notification instruction. */
+function formatBackgroundSubagentNotificationDisplay(notifications) {
+    return notifications
+        .map((notification) => {
+        if (notification.kind === 'question') {
+            const target = notification.name ?? notification.runId;
+            return [
+                `messageId: ${notification.messageId} | target: ${target} | runId: ${notification.runId} | role: ${notification.role}`,
+                `question: ${notification.question}`,
+            ].join('\n');
+        }
+        if (notification.kind === 'shell_completion') {
+            return [
+                `- jobId: ${notification.jobId} | command: ${notification.command} | status: ${notification.status}`,
+                ...(notification.error ? [`  error: ${notification.error}`] : []),
+                ...(notification.output ? [`  output: ${notification.output}`] : []),
+            ].join('\n');
+        }
+        if (notification.kind === 'user_control') {
+            const details = notification.details;
+            if (notification.action === 'background') {
+                return details.kind === 'subagent'
+                    ? `Moved to background: ${details.name ?? details.id} (${details.role})`
+                    : `Moved to background: shell ${details.command}`;
+            }
+            return details.kind === 'subagent'
+                ? `Stop requested: background ${details.name ?? details.id} (${details.role})`
+                : `Stop requested: shell ${details.command}`;
+        }
         const lines = [
             `- runId: ${notification.runId} | role: ${notification.role} | status: ${notification.status}`,
             ...(notification.error ? [`  error: ${notification.error}`] : []),
             ...(notification.preview ? [`  preview: ${notification.preview}`] : []),
         ];
         return lines.join('\n');
-    });
-    return [
-        `Background subagent ${noun} finished (${notifications.length}). This is an automatic system notification, not a user message.`,
-        '',
-        ...entries,
-        '',
-        'Call get_subagent_result(runId) for the full report, then give the user one concise completion notification.',
-    ].join('\n');
+    })
+        .join('\n\n');
 }
 export class ConversationOrchestrator {
     config;
-    pendingApproval = null;
-    askUserAnswers = [];
-    currentAskUserQuestionIndex = 0;
     createMessageId;
     #directlyAppendedMessageIds = new Set();
+    #displayedBackgroundNotificationMessageIds = new Set();
     /**
-     * Turns this orchestrator currently owns. `ui.onTurnStart` cannot be counted
-     * instead: the queue observer emits it unbalanced when a queued submission is
-     * popped after the preceding turn already ended.
+     * Deferred queue submissions register an activator here. The orchestrator does
+     * not count them as active turns until the queue actually starts executing
+     * them — remove/discard/reject must not require a matching `#endTurn`.
+     */
+    #deferredTurnActivators = new Map();
+    /**
+     * A pending steer retracted through the id-addressed mutation path. The
+     * adapter intentionally keeps the shared steer API boolean, so this marker
+     * distinguishes a deliberate retraction from an ordinary failed steer.
+     */
+    #retractedSteerIds = new Set();
+    /** Latest user turn for a pending steer edited before admission. */
+    #editedSteerTurns = new Map();
+    /**
+     * Turns this orchestrator currently owns. Count only executions that have
+     * actually started (direct submit or queue-start activation), never merely
+     * queued awaits.
      */
     #activeTurns = 0;
     /** True while {@link stopProcessing} is tearing the conversation down. */
@@ -63,11 +190,19 @@ export class ConversationOrchestrator {
         // indicator above the input box.
         if (typeof config.conversationService.setQueuedTurnStartObserver === 'function') {
             config.conversationService.setQueuedTurnStartObserver((execution) => {
+                if (execution.suppressUserMessageDisplay) {
+                    return;
+                }
+                // Deferred submissions activate their orchestrator turn here — the only
+                // moment a queued await becomes an owned execution.
+                const activateDeferred = this.#deferredTurnActivators.get(execution.requestId);
+                if (activateDeferred) {
+                    activateDeferred();
+                }
                 const wasAlreadyStarted = this.moveQueuedMessageIntoList(execution.requestId, execution.input);
-                if (!wasAlreadyStarted) {
-                    // A queued submission's original turn-start may have been balanced
-                    // by the preceding turn completing. Reassert processing when this
-                    // turn actually becomes the queue head.
+                if (!wasAlreadyStarted && !activateDeferred) {
+                    // Recovered or test-only starts without a deferred activator still need
+                    // the processing indicator when the message enters the transcript.
                     config.ui.onTurnStart();
                 }
             });
@@ -87,17 +222,14 @@ export class ConversationOrchestrator {
     getSubagentUsage() {
         return this.config.subagentUsageAccumulator?.get() ?? null;
     }
+    getCostSummary() {
+        return this.config.costAccumulator?.getSummary() ?? null;
+    }
     goToPreviousQuestion() {
-        if (this.currentAskUserQuestionIndex <= 0) {
-            return;
-        }
-        this.currentAskUserQuestionIndex -= 1;
-        this.askUserAnswers.pop();
-        this.config.ui.onAskUserGoBack(this.currentAskUserQuestionIndex, this.askUserAnswers.slice());
+        this.config.conversationService.goToPreviousPendingInteractionQuestion?.();
     }
     goToNextQuestion() {
-        this.currentAskUserQuestionIndex += 1;
-        this.config.ui.onAskUserAdvanceToNext(this.currentAskUserQuestionIndex);
+        this.config.conversationService.goToNextPendingInteractionQuestion?.();
     }
     async clearConversation() {
         if (this.config.onClear) {
@@ -108,12 +240,15 @@ export class ConversationOrchestrator {
         }
         this.config.messages.setMessages(() => []);
         this.config.approvedContext.current = null;
-        this.pendingApproval = null;
-        this.resetAskUserState();
+        this.config.conversationService.clearPendingInteraction?.();
         this.config.ui.onResetAll();
         this.config.usageAccumulator?.reset();
         this.config.subagentUsageAccumulator?.reset();
+        this.config.costAccumulator?.reset();
         this.#directlyAppendedMessageIds.clear();
+        this.#displayedBackgroundNotificationMessageIds.clear();
+        this.#retractedSteerIds.clear();
+        this.#editedSteerTurns.clear();
     }
     stopProcessing() {
         // The user asked everything to stop, so background subagent runs go too.
@@ -130,60 +265,68 @@ export class ConversationOrchestrator {
                 ? { ...message, status: 'aborted' }
                 : message));
             this.config.approvedContext.current = null;
-            this.pendingApproval = null;
-            this.resetAskUserState();
+            this.config.conversationService.clearPendingInteraction?.();
             this.config.ui.onResetTransient();
             this.#directlyAppendedMessageIds.clear();
+            this.#displayedBackgroundNotificationMessageIds.clear();
+            this.#retractedSteerIds.clear();
+            this.#editedSteerTurns.clear();
             this.config.conversationService.backgroundSubagentNotifications?.drain();
         }
         finally {
             this.#stoppingByUser = false;
         }
     }
-    undoLastUserMessage() {
-        const messages = this.config.messages.getMessages();
-        const lastUserIndex = findLastUndoableUserMessage(messages);
-        if (lastUserIndex === -1) {
+    /**
+     * Rewind through an opaque store target. `uiIndex` is used only to trim the
+     * rendered projection after the domain operation accepted the same target.
+     */
+    rewindToTarget(targetId, uiIndex) {
+        const restored = this.config.conversationService.rewindToTarget(targetId);
+        if (restored === null)
             return null;
-        }
-        const lastUserMessage = messages[lastUserIndex];
-        const uiText = isUserMessage(lastUserMessage) ? lastUserMessage.text : '';
+        // Keep rewind's historical foreground-only cancellation behavior, but do
+        // not abort an active turn for a stale picker target that the store rejects.
         this.config.conversationService.abort();
-        const removed = this.config.conversationService.undoLastUserTurn();
-        const restored = removed ?? { text: uiText };
-        this.config.messages.setMessages((prev) => prev.slice(0, lastUserIndex));
+        this.config.messages.setMessages((prev) => prev.slice(0, uiIndex));
         this.config.approvedContext.current = null;
-        this.pendingApproval = null;
-        this.resetAskUserState();
+        this.config.conversationService.clearPendingInteraction?.();
         this.config.ui.onResetTransient();
         this.#directlyAppendedMessageIds.clear();
+        this.#displayedBackgroundNotificationMessageIds.clear();
         return restored;
     }
-    /**
-     * Cancel the most recently queued message and return its text so the UI
-     * can move it back into the input box. Returns null when there are no
-     * pending queued messages, the service cannot cancel the tail item, or the
-     * service does not implement cancellation.
-     */
-    async removeLastQueuedPendingMessage() {
+    async retractPendingSubmission(id) {
         const service = this.config.conversationService;
-        if (typeof service.removeLastQueuedItem !== 'function') {
-            return null;
+        if (typeof service.retractSubmission !== 'function')
+            return { kind: 'unknown_id' };
+        const result = await service.retractSubmission(id);
+        if (result.kind === 'applied') {
+            if (result.stage === 'pending_steer') {
+                this.#retractedSteerIds.add(id);
+                this.#editedSteerTurns.delete(id);
+            }
+            this.config.ui.onQueuedMessageRemoved?.(id);
         }
-        const result = await service.removeLastQueuedItem();
-        if (!result)
-            return null;
-        // The pending indicator above the input box is managed by the UI. The
-        // adapter already removed the matching internal entry, but the UI state
-        // is still showing it until we tell it to drop the last entry.
-        this.config.ui.onRemoveLastPendingMessage?.();
-        return result.text;
+        return result;
+    }
+    async editPendingSubmission(id, turn) {
+        const service = this.config.conversationService;
+        if (typeof service.editSubmission !== 'function')
+            return { kind: 'unknown_id' };
+        const result = await service.editSubmission(id, turn);
+        if (result.kind === 'applied') {
+            if (result.stage === 'pending_steer') {
+                this.#editedSteerTurns.set(id, structuredClone(normalizeUserTurn(turn)));
+            }
+            this.config.ui.onQueuedMessageEdited?.(id, formatUserTurnForDisplay(normalizeUserTurn(turn)));
+        }
+        return result;
     }
     async retryLastToolOutput() {
         this.config.conversationService.abort();
         this.config.approvedContext.current = null;
-        this.pendingApproval = null;
-        this.resetAskUserState();
+        this.config.conversationService.clearPendingInteraction?.();
         this.config.ui.onResetTransient();
         if (!this.config.conversationService.peekLastToolOutput()) {
             return false;
@@ -210,7 +353,6 @@ export class ConversationOrchestrator {
             }
             const errorMessage = enhanceApiKeyError(describeError(error));
             this.appendBotError(errorMessage);
-            this.config.ui.onApprovalResolved();
             return true;
         }
         finally {
@@ -220,25 +362,6 @@ export class ConversationOrchestrator {
             this.#endTurn();
         }
     }
-    undoToUserMessage(uiIndex) {
-        const messages = this.config.messages.getMessages();
-        const undoCount = countUndoableUserTurnsFrom(messages, uiIndex);
-        if (undoCount === 0) {
-            return null;
-        }
-        const selectedMessage = messages[uiIndex];
-        const uiText = isUserMessage(selectedMessage) ? selectedMessage.text : '';
-        this.config.conversationService.abort();
-        const removed = this.config.conversationService.undoNUserTurns(undoCount);
-        const restored = removed?.text ?? uiText;
-        this.config.messages.setMessages((prev) => prev.slice(0, uiIndex));
-        this.config.approvedContext.current = null;
-        this.pendingApproval = null;
-        this.resetAskUserState();
-        this.config.ui.onResetTransient();
-        this.#directlyAppendedMessageIds.clear();
-        return restored;
-    }
     async sendUserMessage(input, options) {
         const turn = normalizeUserTurn(input);
         if (!hasUserTurnContent(turn)) {
@@ -256,12 +379,83 @@ export class ConversationOrchestrator {
         // second append. When a turn is already in flight, show the message
         // above the input box until the queue actually starts processing it; the
         // message list will be updated when the queue pops this turn.
-        const hasInflightTurn = this.config.conversationService.isQueueActive?.() ?? false;
-        if (hasInflightTurn) {
-            // A turn is already in flight. Show the message above the input box
-            // until the queue actually starts processing it; the message list will
-            // be updated when the queue pops this turn.
+        const queueOwnsSubmission = this.config.conversationService.isQueueOwningSubmissions?.() ??
+            this.config.conversationService.isQueueActive?.() ??
+            false;
+        // Logged before the branch below, not inside it. "Steer attempt resolved"
+        // only exists on the path that actually tries to steer, so a submission
+        // that never enters that path — because it arrived without busyMode
+        // 'steer', or because the queue did not claim it — is indistinguishable in
+        // the logs from one that was never submitted at all. That gap hid a real
+        // report of a steer silently queueing: the queue file held the message and
+        // the transcript held the user_message, and nothing recorded the decision
+        // in between. These four fields name that decision.
+        this.config.loggingService.info('Submission routing decided', {
+            busyMode: options?.busyMode ?? 'none',
+            queueOwnsSubmission,
+            queueStateKind: this.config.conversationService.queueStateKind?.() ?? 'unknown',
+            canSteer: Boolean(this.config.conversationService.steerActiveTurn),
+            messageId: userMessage.id,
+        });
+        if (queueOwnsSubmission) {
+            // A turn is already in flight or the queue is paused with retained work.
+            // Show the message above the input box until the queue actually starts
+            // processing it; the message list will be updated when the queue pops
+            // this turn.
             this.config.ui.onQueuedMessagePending?.(userMessage.id, userMessage.text);
+            // A steer belongs to the turn already running: hand it to that turn so
+            // the model reads it at its next request, rather than making the user
+            // wait for the whole turn to end. The message joins the transcript at the
+            // moment the turn takes it, which is when the model actually sees it.
+            if (options?.busyMode === 'steer' && this.config.conversationService.steerActiveTurn) {
+                // Diagnostics for "my steer just queued". The three fields below
+                // separate the ways delivery can fail, which otherwise look identical
+                // in the UI because the queued label is drawn before this even runs:
+                //   queueActive=false            → refused by the adapter's predicate;
+                //     the queue owns the submission but is not in a state that offers
+                //     steering (awaiting_preflight, paused, idle with retained work).
+                //   queueActive=true, waited≈0ms → refused synchronously downstream:
+                //     awaiting an approval, or no run in flight at the run loop.
+                //   queueActive=true, waited>0ms → held as pending and released when
+                //     the run ended: the turn never reached another request boundary.
+                //   steered=true                 → admitted; waitedMs is how long the
+                //     user waited for the turn to reach that boundary.
+                const queueActive = this.config.conversationService.isQueueActive?.() ?? false;
+                const queueStateKind = this.config.conversationService.queueStateKind?.() ?? 'unknown';
+                const steerStartedAt = Date.now();
+                const steered = await this.config.conversationService
+                    .steerActiveTurn(turn, { id: userMessage.id })
+                    .catch((error) => {
+                    this.logError('Error steering the active turn', error);
+                    return false;
+                });
+                this.config.loggingService.info('Steer attempt resolved', {
+                    steered,
+                    queueActive,
+                    queueStateKind,
+                    waitedMs: Date.now() - steerStartedAt,
+                    messageId: userMessage.id,
+                });
+                if (steered) {
+                    const admittedTurn = this.#editedSteerTurns.get(userMessage.id) ?? turn;
+                    this.#editedSteerTurns.delete(userMessage.id);
+                    const { skill: _originalSkill, ...messageWithoutSkill } = userMessage;
+                    const admittedMessage = {
+                        ...messageWithoutSkill,
+                        text: formatUserTurnForDisplay(admittedTurn),
+                        ...(admittedTurn.skill ? { skill: admittedTurn.skill } : {}),
+                    };
+                    this.config.ui.onQueuedMessageStarted?.(userMessage.id);
+                    this.config.messages.appendMessages([admittedMessage]);
+                    this.config.logWriter?.append({ type: 'user_message', message: { ...admittedMessage } });
+                    return;
+                }
+                if (this.#retractedSteerIds.delete(userMessage.id)) {
+                    this.#editedSteerTurns.delete(userMessage.id);
+                    return;
+                }
+                this.#editedSteerTurns.delete(userMessage.id);
+            }
         }
         else {
             // No turn is in flight — append directly. The queue observer will also
@@ -270,13 +464,29 @@ export class ConversationOrchestrator {
             this.config.messages.appendMessages([userMessage]);
             this.#directlyAppendedMessageIds.add(userMessage.id);
         }
-        this.config.logWriter?.append({ type: 'user_message', message: userMessage });
-        const { botResponseUpdater, reasoningUpdater, applyConversationEvent, streamingState } = this.#beginTurn('sendUserMessage');
+        this.config.logWriter?.append({ type: 'user_message', message: { ...userMessage } });
+        // Streaming callbacks are bound at submit time, but deferred submissions
+        // must not count as active turns until the queue starts them. Otherwise
+        // remove/discard would need a matching endTurn for work that never ran.
+        let turnActivated = !queueOwnsSubmission;
+        const { botResponseUpdater, reasoningUpdater, applyConversationEvent, streamingState } = queueOwnsSubmission
+            ? this.createTurnSession('sendUserMessage')
+            : this.#beginTurn('sendUserMessage');
+        if (queueOwnsSubmission) {
+            this.#deferredTurnActivators.set(userMessage.id, () => {
+                if (turnActivated)
+                    return;
+                turnActivated = true;
+                this.#activeTurns += 1;
+                this.config.ui.onTurnStart();
+            });
+        }
         try {
             const turnToSend = turn.skill ? injectSkillIntoTurn(turn) : turn;
             const result = await this.config.conversationService.sendMessage(turnToSend, {
                 onEvent: this.createOnEventHandler(applyConversationEvent),
                 bypassInputSurgeGuard: options?.bypassInputSurgeGuard,
+                busyMode: options?.busyMode,
                 preferredMessageId: userMessage.id,
             });
             applyConversationEvent({ type: 'final', finalText: '' });
@@ -285,10 +495,21 @@ export class ConversationOrchestrator {
         }
         catch (error) {
             this.logError('Error in sendUserMessage', error);
+            if (queueOwnsSubmission) {
+                this.config.ui.onQueuedMessageRemoved?.(userMessage.id);
+            }
             if (isAbortLikeError(error)) {
                 this.config.loggingService.debug('Suppressing abort error in sendUserMessage');
                 return;
             }
+            // A submission that never left the pending queue produced no turn to
+            // report on, but it also produced no answer: the pending indicator has
+            // just been cleared, so saying nothing would make the user's text vanish
+            // without explanation. Report the rejection and hand the text back.
+            if (queueOwnsSubmission && !turnActivated) {
+                this.appendBotError(`${enhanceApiKeyError(describeError(error))}\n\nThis message was not sent: ${userMessage.text}`);
+                return;
+            }
             const rawErrorMessage = describeError(error);
             const errorMessage = enhanceApiKeyError(rawErrorMessage);
             const dropped = error?.rawEvent?.droppedUserMessage;
@@ -311,71 +532,44 @@ export class ConversationOrchestrator {
                     rawInterruption: null,
                     isMaxTurnsPrompt: true,
                 };
-                this.pendingApproval = pendingApproval;
+                this.config.conversationService.presentPendingInteraction?.(pendingApproval);
                 this.config.ui.onApprovalRequested(pendingApproval);
             }
             else {
                 this.appendBotError(errorMessage);
-                this.config.ui.onApprovalResolved();
             }
         }
         finally {
             this.config.loggingService.debug('sendUserMessage finally block - resetting state');
+            this.#deferredTurnActivators.delete(userMessage.id);
             reasoningUpdater.flush();
             botResponseUpdater.cancel();
-            this.#endTurn();
+            if (turnActivated) {
+                this.#endTurn();
+            }
         }
     }
-    async handleApprovalDecision(answer, rejectionReason, approvalAnswer) {
-        const pendingApproval = this.pendingApproval;
-        if (!pendingApproval) {
+    async handleApprovalDecision(answer, rejectionReason, approvalAnswer, expectedInteractionId, options = {}) {
+        const resolution = this.config.conversationService.resolvePendingInteraction?.({
+            expectedInteractionId,
+            answer,
+            rejectionReason,
+            approvalAnswer,
+        });
+        if (!resolution || resolution.kind === 'none' || resolution.kind === 'stale_interaction') {
             return;
         }
+        if (resolution.kind === 'awaiting_next_question')
+            return;
+        const pendingApproval = resolution.approval;
         const isMaxTurnsPrompt = pendingApproval.isMaxTurnsPrompt;
-        const isAskUser = pendingApproval.toolName === 'ask_user';
-        if (isAskUser && answer === 'y' && approvalAnswer !== ASK_USER_DECLINE_RESULT) {
-            let questions = [];
-            try {
-                const parsed = JSON.parse(pendingApproval.argumentsText);
-                questions = parsed.questions || [];
-            }
-            catch {
-                // noop
-            }
-            let parsedAns = approvalAnswer ?? '';
-            const currentQuestion = questions[this.askUserAnswers.length];
-            if (currentQuestion?.is_multi_select) {
-                try {
-                    const maybeArray = JSON.parse(approvalAnswer ?? '');
-                    if (Array.isArray(maybeArray)) {
-                        parsedAns = maybeArray;
-                    }
-                }
-                catch {
-                    // keep plain string
-                }
-            }
-            const nextAnswers = [...this.askUserAnswers, parsedAns];
-            this.config.ui.onAskUserAnswerSubmitted(parsedAns);
-            if (nextAnswers.length < questions.length) {
-                this.askUserAnswers = nextAnswers;
-                this.currentAskUserQuestionIndex = nextAnswers.length;
-                this.config.ui.onAskUserAdvanceToNext(nextAnswers.length);
-                return;
-            }
-            this.askUserAnswers = nextAnswers;
-            this.currentAskUserQuestionIndex = nextAnswers.length;
-            approvalAnswer = JSON.stringify(nextAnswers);
-        }
+        this.config.ui.onApprovalResolved();
         if (answer === 'y' || isDeniedReadApproveAnswer(answer)) {
             this.config.approvedContext.current = {
                 callId: pendingApproval.callId,
                 toolName: pendingApproval.toolName,
             };
         }
-        this.config.ui.onApprovalResolved();
-        this.pendingApproval = null;
-        this.resetAskUserState();
         if (isMaxTurnsPrompt && answer === 'n') {
             this.#endTurn();
             return;
@@ -397,7 +591,6 @@ export class ConversationOrchestrator {
                 }
                 const errorMessage = error instanceof Error ? error.message : String(error);
                 this.appendBotError(errorMessage);
-                this.config.ui.onApprovalResolved();
             }
             finally {
                 reasoningUpdater.flush();
@@ -410,7 +603,8 @@ export class ConversationOrchestrator {
         try {
             const result = await this.config.conversationService.handleApprovalDecision(answer, rejectionReason, {
                 onEvent: this.createOnEventHandler(applyConversationEvent),
-                approvalAnswer,
+                approvalAnswer: resolution.approvalAnswer,
+                ...(options.stopAfterApprovalResolution ? { stopAfterApprovalResolution: true } : {}),
             });
             applyConversationEvent({ type: 'final', finalText: '' });
             botResponseUpdater.flush();
@@ -424,7 +618,6 @@ export class ConversationOrchestrator {
             }
             const errorMessage = error instanceof Error ? error.message : String(error);
             this.appendBotError(errorMessage);
-            this.config.ui.onApprovalResolved();
         }
         finally {
             this.config.loggingService.debug('handleApprovalDecision finally block - resetting state');
@@ -433,6 +626,18 @@ export class ConversationOrchestrator {
             this.#endTurn();
         }
     }
+    /**
+     * Escape on an `ask_user` prompt. The tool still returns
+     * {@link ASK_USER_NO_ANSWER_RESULT}, so the question and the fact that it
+     * went unanswered are committed to history and travel with the user's next
+     * message. The turn then ends instead of handing the model another turn:
+     * cancelling means the user speaks next.
+     */
+    async cancelAskUser(expectedInteractionId) {
+        return this.handleApprovalDecision('y', undefined, ASK_USER_NO_ANSWER_RESULT, expectedInteractionId, {
+            stopAfterApprovalResolution: true,
+        });
+    }
     /** Open a turn this orchestrator owns, and its streaming session. */
     #beginTurn(label) {
         this.#activeTurns += 1;
@@ -452,10 +657,115 @@ export class ConversationOrchestrator {
         }
     }
     /**
-     * Hand every settled background subagent run to the main agent as one
-     * system-initiated turn. Does nothing unless the conversation is idle: a
-     * running turn or a pending approval owns the agent, and the store keeps the
-     * notifications until the next terminal state re-attempts delivery.
+     * Announce settled runs in the transcript, once each.
+     *
+     * Display is deliberately not tied to the agent receiving them: the user
+     * should see a run land the moment it does, whether the report reaches the
+     * agent at the next request boundary or waits for a turn of its own.
+     */
+    #announceBackgroundSubagentNotifications(notifications) {
+        const newlyDisplayed = notifications.filter((notification) => !this.#displayedBackgroundNotificationMessageIds.has(notification.messageId));
+        if (newlyDisplayed.length === 0)
+            return;
+        for (const notification of newlyDisplayed) {
+            this.#displayedBackgroundNotificationMessageIds.add(notification.messageId);
+        }
+        const subagentNotifications = newlyDisplayed.filter((notification) => notification.kind === 'completion' || notification.kind === 'question');
+        const runs = subagentNotifications
+            .filter((notification) => notification.kind === 'completion')
+            .map(({ name, role, status, error }) => ({
+            ...(name !== undefined ? { name } : {}),
+            role,
+            status,
+            ...(error ? { error } : {}),
+        }));
+        const shellJobs = newlyDisplayed.filter((notification) => notification.kind === 'shell_completion');
+        const userControls = newlyDisplayed.filter((notification) => notification.kind === 'user_control');
+        this.config.messages.appendMessages([
+            ...(subagentNotifications.length > 0
+                ? [
+                    {
+                        id: this.createMessageId(),
+                        sender: 'command',
+                        status: 'completed',
+                        command: 'background_subagent_notification',
+                        output: formatBackgroundSubagentNotificationDisplay(subagentNotifications),
+                        success: true,
+                        toolName: 'background_subagent_notification',
+                        toolArgs: { runs },
+                    },
+                ]
+                : []),
+            ...(shellJobs.length > 0
+                ? [
+                    {
+                        id: this.createMessageId(),
+                        sender: 'command',
+                        status: 'completed',
+                        command: 'background_shell_notification',
+                        output: formatBackgroundSubagentNotificationDisplay(shellJobs),
+                        success: true,
+                        toolName: 'background_shell_notification',
+                        toolArgs: {
+                            jobs: shellJobs.map(({ jobId, command, status, error }) => ({
+                                jobId,
+                                command,
+                                status,
+                                ...(error ? { error } : {}),
+                            })),
+                        },
+                    },
+                ]
+                : []),
+            ...(userControls.length > 0
+                ? [
+                    {
+                        id: this.createMessageId(),
+                        sender: 'command',
+                        status: 'completed',
+                        command: 'background_task_control_notification',
+                        output: formatBackgroundSubagentNotificationDisplay(userControls),
+                        success: true,
+                        toolName: 'background_task_control_notification',
+                        toolArgs: {
+                            actions: userControls.map(({ action, target }) => ({ action, target })),
+                        },
+                    },
+                ]
+                : []),
+        ]);
+    }
+    /**
+     * Offer settled runs to the turn already in flight.
+     *
+     * Taken as one report at that turn's next request boundary. If the turn will
+     * not take them they go back to the store unchanged, so the idle path still
+     * delivers them and the agent never sees the same run twice.
+     */
+    async #injectBackgroundSubagentNotifications(pending) {
+        if (!this.config.conversationService.injectIntoActiveTurn)
+            return;
+        const notifications = pending.drain();
+        if (notifications.length === 0)
+            return;
+        this.#announceBackgroundSubagentNotifications(notifications);
+        const injected = await this.config.conversationService
+            .injectIntoActiveTurn([
+            { type: 'message', role: 'user', content: formatBackgroundSubagentNotifications(notifications) },
+        ])
+            .catch((error) => {
+            this.logError('Error delivering background subagent notifications', error);
+            return false;
+        });
+        if (!injected)
+            pending.retain(notifications);
+    }
+    /**
+     * Hand every settled background subagent run to the main agent.
+     *
+     * The agent that launched these runs is usually still working when they
+     * settle, so delivery goes into that turn at its next request boundary. Only
+     * when no turn will take them does this open one of its own.
      */
     async #deliverBackgroundSubagentNotifications() {
         const pending = this.config.conversationService.backgroundSubagentNotifications;
@@ -463,17 +773,24 @@ export class ConversationOrchestrator {
             return;
         if (this.#stoppingByUser)
             return;
-        if (this.#activeTurns > 0 || this.pendingApproval)
+        const turnIsRunning = this.#activeTurns > 0 || this.config.conversationService.isQueueActive?.() === true;
+        if (turnIsRunning) {
+            await this.#injectBackgroundSubagentNotifications(pending);
             return;
-        if (this.config.conversationService.isQueueActive?.())
+        }
+        if (this.config.conversationService.getPendingInteractionSnapshot?.())
             return;
         const notifications = pending.drain();
         if (notifications.length === 0)
             return;
+        this.#announceBackgroundSubagentNotifications(notifications);
         const { botResponseUpdater, reasoningUpdater, applyConversationEvent, streamingState } = this.#beginTurn('backgroundSubagentNotification');
         let delivered = false;
         try {
-            const result = await this.config.conversationService.sendMessage(formatBackgroundSubagentNotifications(notifications), { onEvent: this.createOnEventHandler(applyConversationEvent) });
+            const result = await this.config.conversationService.sendMessage(formatBackgroundSubagentNotifications(notifications), {
+                onEvent: this.createOnEventHandler(applyConversationEvent),
+                suppressUserMessageDisplay: true,
+            });
             // A turn the queue refused to admit resolves without a terminal, so the
             // notifications were never seen and must go back on the queue.
             delivered = Boolean(result);
@@ -488,7 +805,6 @@ export class ConversationOrchestrator {
                 return;
             }
             this.appendBotError(enhanceApiKeyError(describeError(error)));
-            this.config.ui.onApprovalResolved();
         }
         finally {
             reasoningUpdater.flush();
@@ -516,11 +832,11 @@ export class ConversationOrchestrator {
     }
     createOnEventHandler(baseOnEvent) {
         return (event) => {
-            const eventType = typeof event?.type === 'string' ? event.type : undefined;
+            const eventType = event.type;
             if (eventType === 'reasoning_delta') {
                 this.config.ui.onStreamingThinkingStarted((this.config.now ?? Date.now)());
             }
-            else if (eventType && this.clearsThinkingIndicator(eventType)) {
+            else if (this.clearsThinkingIndicator(eventType)) {
                 this.config.ui.onStreamingThinkingCleared();
             }
             if (eventType === 'tool_call_streaming_delta') {
@@ -529,7 +845,7 @@ export class ConversationOrchestrator {
             else if (eventType === 'tool_started' || eventType === 'text_delta' || eventType === 'final') {
                 this.config.ui.onStreamingToolInfo(null);
             }
-            if (event?.type === 'user_message_consumed_for_abort') {
+            if (eventType === 'user_message_consumed_for_abort') {
                 this.config.messages.setMessages((prev) => {
                     for (let i = prev.length - 1; i >= 0; i--) {
                         const msg = prev[i];
@@ -546,8 +862,11 @@ export class ConversationOrchestrator {
                 return;
             }
             baseOnEvent(event);
-            if (event?.type === 'subagent_completed' && event?.result?.usage) {
-                this.config.subagentUsageAccumulator?.add(event.result.usage);
+            if (eventType === 'subagent_completed') {
+                if (event.result.usage) {
+                    this.config.subagentUsageAccumulator?.add(event.result.usage);
+                }
+                this.config.costAccumulator?.addRecords(event.result.costRecords ?? []);
             }
         };
     }
@@ -559,13 +878,11 @@ export class ConversationOrchestrator {
             if (result.usage) {
                 this.config.ui.onUsageUpdate(latestStreamedUsage ?? result.usage);
             }
-            this.pendingApproval = result.approval;
             this.config.messages.setMessages((prev) => this.config.messages.trimMessages(filterPendingCommandMessagesForApproval(prev, result.approval)));
             this.config.ui.onApprovalRequested({ ...result.approval, llmAdvisory: result.approval.llmAdvisory });
             this.config.notifier?.approvalNeeded();
             return;
         }
-        this.pendingApproval = null;
         this.config.messages.setMessages((prev) => computeNextMessages({
             prev,
             result,
@@ -583,6 +900,7 @@ export class ConversationOrchestrator {
             this.config.usageAccumulator?.add(result.usage);
             this.config.ui.onUsageUpdate(latestStreamedUsage ?? result.usage);
         }
+        this.config.costAccumulator?.addRecords(result.costRecords ?? []);
     }
     /**
      * Append a previously-queued user message into the message list. Called by
@@ -637,10 +955,6 @@ export class ConversationOrchestrator {
             eventType === 'tool_call_streaming_delta' ||
             eventType === 'final');
     }
-    resetAskUserState() {
-        this.askUserAnswers = [];
-        this.currentAskUserQuestionIndex = 0;
-    }
     appendBotError(errorMessage) {
         const botErrorMessage = {
             id: this.createMessageId(),