@zergai/ztc 0.3.0-beta.1 → 0.4.0-beta.1

package/dist/agent/tool_response_store.js

@@ -269,6 +269,7 @@ export class ToolResponseStore {
             timestamp: new Date().toISOString(),
             turn: this.turnCounter++,
             partial,
+            ...(context?.isError === undefined ? {} : { is_error: context.isError }),
             preview,
         };
         const sourcePath = context?.sourcePath ?? null;

package/dist/agent/tools/deferred.js

@@ -22,6 +22,8 @@ export const ALWAYS_LOADED_TOOL_NAMES = new Set([
     'list_directory',
     'search',
     'run_command',
+    'read_command',
+    'stop_command',
     'apply_patch',
     // Emulation compatibility aliases. They only appear in the request when
     // the active emulation adds matching tools to the runtime tool list.

package/dist/agent/tools/file.js

@@ -104,6 +104,7 @@ async function assertTemporaryWriteAllowed(path, context) {
 }
 // --- File Tools ---
 export const readFileTool = {
+    parallelSafe: true,
     capabilities: [ToolCapability.FILE_READ],
     definition: {
         name: 'read_file',
@@ -503,6 +504,7 @@ export const editFileTool = {
     },
 };
 export const listDirectoryTool = {
+    parallelSafe: true,
     capabilities: [ToolCapability.FILE_READ],
     definition: {
         name: 'list_directory',

package/dist/agent/tools/pane.js

@@ -5,9 +5,12 @@
  * and list terminal panes when running inside zmux.
  * They communicate with the zmux Rust binary via the IPC socket.
  */
+import { randomUUID } from 'node:crypto';
+import { ToolCapability } from '../runtime/capabilities.js';
 import { existsSync } from 'fs';
 import { basename, isAbsolute, resolve } from 'path';
 import { isRatatuiBinaryAvailable } from '../../ui/ratatui/process.js';
+import { CAPABILITY_PANE_DELIVERY_ACK } from '../../ui/ratatui/protocol.js';
 import { generateSessionId } from '../../session.js';
 import { isPaneProvider, resolveModelAndProvider } from '../../panes/model_catalog.js';
 import { buildZtcPaneLaunchCommand, createZtcLaunchSpec } from '../../panes/ztc_launch.js';
@@ -139,19 +142,30 @@ export function clearPaneToolsTuiProcess() {
 /**
  * Wait for a specific event type from the TUI process with a timeout.
  */
-function waitForEvent(tui, predicate, timeoutMs = 10000) {
+const PANE_WAIT_CANCELLED = 'Cancelled while waiting for pane response; inspect the pane before retrying because input may already have arrived.';
+function waitForEvent(tui, predicate, timeoutMs = 10000, signal) {
     return new Promise((resolve, reject) => {
-        const timeout = setTimeout(() => {
+        if (signal?.aborted) {
+            reject(new Error(PANE_WAIT_CANCELLED));
+            return;
+        }
+        const cleanup = () => {
+            clearTimeout(timeout);
             unsubscribe();
-            reject(new Error('Timed out waiting for pane response'));
+            signal?.removeEventListener('abort', abort);
+        };
+        const abort = () => { cleanup(); reject(new Error(PANE_WAIT_CANCELLED)); };
+        const timeout = setTimeout(() => {
+            cleanup();
+            reject(new Error('Timed out waiting for pane response; inspect the pane before retrying.'));
         }, timeoutMs);
         const unsubscribe = tui.on((event) => {
             if (predicate(event)) {
-                clearTimeout(timeout);
-                unsubscribe();
+                cleanup();
                 resolve(event);
             }
         });
+        signal?.addEventListener('abort', abort, { once: true });
     });
 }
 const SPLIT_DIRECTIONS = ['horizontal', 'vertical'];
@@ -757,68 +771,122 @@ export const createZtcPaneTool = {
         }
     },
 };
+// Legacy renderers omit request IDs. Only one tool read per pane may be in
+// flight; viewport events from mirror consumers are filtered separately.
+const legacyPaneReads = new WeakMap();
+async function serializeLegacyPaneRead(transport, paneId, signal, read) {
+    let panes = legacyPaneReads.get(transport);
+    if (!panes) {
+        panes = new Map();
+        legacyPaneReads.set(transport, panes);
+    }
+    const previous = panes.get(paneId) ?? Promise.resolve();
+    const result = previous.then(() => {
+        if (signal.aborted)
+            throw new Error(PANE_WAIT_CANCELLED);
+        return read();
+    });
+    const settled = result.then(() => { }, () => { });
+    panes.set(paneId, settled);
+    void settled.then(() => { if (panes.get(paneId) === settled)
+        panes.delete(paneId); });
+    // Cancellation while waiting for a slot is immediate, but does not unlock
+    // the preceding request or send a command for this cancelled read.
+    let onAbort;
+    const aborted = new Promise((_, reject) => {
+        onAbort = () => reject(new Error(PANE_WAIT_CANCELLED));
+        signal.addEventListener('abort', onAbort, { once: true });
+        if (signal.aborted)
+            onAbort();
+    });
+    try {
+        return await Promise.race([result, aborted]);
+    }
+    finally {
+        signal.removeEventListener('abort', onAbort);
+    }
+}
 export const readTerminalPaneTool = {
+    capabilities: [ToolCapability.FILE_READ],
     definition: {
         name: 'read_terminal_pane',
         description: `Read a pane's text output. Use viewport=true for exactly what is visible, ansi=true when terminal color/control state matters, or lines for recent scrollback.`,
         parameters: {
             type: 'object',
             properties: {
+                viewport: { type: 'boolean', description: 'Read visible viewport only.' },
+                ansi: { type: 'boolean', description: 'Keep ANSI color/control sequences.' },
                 pane_id: {
                     type: 'number',
                     description: 'The ID of the pane to read (from create_terminal_pane or list_terminal_panes)',
                 },
                 lines: {
                     type: 'number',
-                    description: 'Number of lines to read from the bottom of the buffer. Defaults to full screen.',
+                    description: 'Number of lines to read from the bottom of the buffer. Defaults to 200 lines; maximum 2000.',
                 },
             },
             required: ['pane_id'],
         },
     },
-    execute: async (args) => {
+    execute: async (args, context) => {
+        const waiting = new AbortController();
+        const signal = context?.signal ? AbortSignal.any([context.signal, waiting.signal]) : waiting.signal;
+        if (signal.aborted)
+            throw new Error(PANE_WAIT_CANCELLED);
         if (!tuiProcessRef || !tuiProcessRef.isMuxMode) {
-            return 'Error: Terminal panes are only available in zmux mode (--mux flag).';
+            throw new Error('Terminal panes require zmux (--mux). Use run_command for shell execution when available.');
         }
         const paneId = Number(args.pane_id);
-        if (isNaN(paneId)) {
-            return 'Error: pane_id must be a number.';
-        }
-        const lines = args.lines ? Number(args.lines) : undefined;
-        const eventPromise = waitForEvent(tuiProcessRef, (e) => e.type === 'pane_read' && e.pane_id === paneId && !e.viewport, 10000);
-        const sent = tuiProcessRef.send({
-            type: 'read_pane',
-            pane_id: paneId,
-            lines,
-            viewport: false,
-        });
-        if (!sent) {
-            eventPromise.catch(() => { }); // prevent unhandled rejection from dangling timeout
-            return 'Error: Failed to send command to zmux.';
-        }
-        try {
+        if (!Number.isSafeInteger(paneId) || paneId < 0) {
+            throw new Error('pane_id must be a non-negative integer.');
+        }
+        const lines = args.lines == null ? 200 : Number(args.lines);
+        if (!Number.isSafeInteger(lines) || lines < 1 || lines > 2000)
+            throw new Error('lines must be between 1 and 2000');
+        const viewport = args.viewport === true;
+        const requestId = randomUUID();
+        // Capture this transport and its protocol version for the entire request.
+        const transport = tuiProcessRef;
+        const correlated = transport.hasCapability?.(CAPABILITY_PANE_DELIVERY_ACK) === true;
+        const read = async () => {
+            const eventPromise = waitForEvent(transport, (e) => e.type === 'pane_read' && e.pane_id === paneId
+                && (correlated ? e.request_id === requestId
+                    : (!e.request_id || e.request_id === requestId) && (e.viewport === true) === viewport), 10000, signal);
+            const sent = transport.send({
+                type: 'read_pane',
+                request_id: requestId,
+                pane_id: paneId,
+                lines,
+                viewport,
+                ansi: args.ansi === true,
+            });
+            if (!sent) {
+                eventPromise.catch(() => { });
+                waiting.abort();
+                throw new Error('Failed to send command to zmux.');
+            }
             const event = await eventPromise;
             if (event.type === 'pane_read') {
-                if (!event.content || event.content.trim() === '') {
+                if (event.error)
+                    throw new Error(event.error);
+                if (!event.content || event.content.trim() === '')
                     return '(Terminal buffer is empty)';
-                }
                 return event.content;
             }
-            return 'Error: Unexpected response from zmux.';
-        }
-        catch (err) {
-            return `Error: ${err.message}`;
-        }
+            throw new Error('Unexpected response from zmux.');
+        };
+        return correlated ? read() : serializeLegacyPaneRead(transport, paneId, context?.signal ?? new AbortController().signal, read);
     },
 };
 export const writeTerminalPaneTool = {
+    capabilities: [ToolCapability.SHELL_EXEC],
     definition: {
         name: 'write_terminal_pane',
         description: `Write input to a pane's running process. For shells and editors this sends terminal input; for ZTC child panes prefer send_message or ask_ztc_pane unless you specifically need keystroke-level control.
 
 The input is automatically submitted (Enter/Return is appended). You do NOT need to add \\n yourself — just provide the text you want to send.
 
-If you need to send raw keystrokes WITHOUT auto-submitting (rare), set submit=false.`,
+For raw keystrokes set submit=false; input bytes are preserved and Enter is \\r (U+000D). To recover a stuck heredoc send the Ctrl+C character (U+0003) with submit=false. Delivery acknowledges terminal input only; inspect output to determine command success.`,
         parameters: {
             type: 'object',
             properties: {
@@ -838,17 +906,21 @@ If you need to send raw keystrokes WITHOUT auto-submitting (rare), set submit=fa
             required: ['pane_id', 'input'],
         },
     },
-    execute: async (args) => {
+    execute: async (args, context) => {
+        const waiting = new AbortController();
+        const signal = context?.signal ? AbortSignal.any([context.signal, waiting.signal]) : waiting.signal;
+        if (signal.aborted)
+            throw new Error(PANE_WAIT_CANCELLED);
         if (!tuiProcessRef || !tuiProcessRef.isMuxMode) {
-            return 'Error: Terminal panes are only available in zmux mode (--mux flag).';
+            throw new Error('Terminal panes require zmux (--mux). Use run_command for shell execution when available.');
         }
         const paneId = Number(args.pane_id);
-        if (isNaN(paneId)) {
-            return 'Error: pane_id must be a number.';
+        if (!Number.isSafeInteger(paneId) || paneId < 0) {
+            throw new Error('pane_id must be a non-negative integer.');
         }
         let input = String(args.input || '');
         if (!input) {
-            return 'Error: input is required.';
+            throw new Error('input is required.');
         }
         const shouldSubmit = args.submit !== false && args.submit !== 'false';
         // Normalize line endings to LF and PRESERVE interior newlines so multi-line
@@ -857,21 +929,41 @@ If you need to send raw keystrokes WITHOUT auto-submitting (rare), set submit=fa
         // prompt into one line. The headless paneChild receiver delivers this as a
         // single JSON-line message (see HeadlessPaneManager.handleWritePane), so
         // interior newlines no longer fragment into premature submissions.
-        input = input.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
         if (shouldSubmit) {
+            input = input.replace(/\r\n/g, '\n').replace(/\r/g, '\n');
             // Strip trailing newline(s); `submit` alone controls the final Enter.
             input = input.replace(/\n+$/, '');
         }
+        const requestId = randomUUID();
+        const confirmed = tuiProcessRef.hasCapability?.(CAPABILITY_PANE_DELIVERY_ACK) === true;
+        const eventPromise = confirmed ? waitForEvent(tuiProcessRef, event => event.type === 'pane_write_result' && event.request_id === requestId && event.pane_id === paneId, 10000, signal) : null;
         const sent = tuiProcessRef.send({
             type: 'write_pane',
+            request_id: requestId,
             pane_id: paneId,
             input,
             submit: shouldSubmit,
         });
         if (!sent) {
-            return 'Error: Failed to send command to zmux.';
-        }
-        return `Sent input to pane ${paneId}${shouldSubmit ? ' (submitted)' : ' (no submit)'}.`;
+            eventPromise?.catch(() => { });
+            waiting.abort();
+            throw new Error('Failed to send command to zmux.');
+        }
+        if (!eventPromise)
+            return `Input sent to pane ${paneId}, not confirmed: this renderer lacks delivery acknowledgements. Inspect the pane before retrying; the command may already have run.`;
+        const event = await eventPromise;
+        if (event.type !== 'pane_write_result')
+            throw new Error('Unexpected pane acknowledgement');
+        if (event.queued) {
+            const bytes = !event.encoding_pending && event.delivered_bytes !== undefined && event.total_bytes !== undefined
+                ? ` ${event.delivered_bytes} of ${event.total_bytes} bytes already delivered; the rest is queued.` : '';
+            return `Input queued for pane ${paneId}, not confirmed.${bytes} Do not resend blindly; read the pane to inspect progress.`;
+        }
+        if (!event.delivered) {
+            const bytes = event.partial && !event.cancelled ? `${event.delivered_bytes ?? 'Some'} of ${event.total_bytes ?? 'unknown'} bytes already delivered — do not resend blindly. ` : '';
+            throw new Error((event.error?.startsWith(bytes) ? '' : bytes) + (event.error || 'Pane input was not delivered'));
+        }
+        return `Input delivered to pane ${paneId}${shouldSubmit ? ' (submitted)' : ' (raw)'}. Delivery is not command completion; read the pane to inspect output.`;
     },
 };
 export const closeTerminalPaneTool = {
@@ -1630,4 +1722,9 @@ export const paneTools = [
     restartPaneTool,
     closeTerminalPaneTool,
     listTerminalPanesTool,
-];
+].map(tool => ({ ...tool,
+    // read_terminal_pane returns program output, which may itself begin with "Error:";
+    // its own failures are thrown, so only tool-authored messages are classified.
+    isErrorResult: tool === readTerminalPaneTool ? undefined : (content) => /^Error[: ]/i.test(content),
+    capabilities: tool.capabilities ?? ([createTerminalPaneTool, createZtcPaneTool, restartPaneTool, closeTerminalPaneTool].includes(tool)
+        ? [ToolCapability.SHELL_EXEC] : [ToolCapability.FILE_READ]), }));

package/dist/agent/tools/recall_tool_response.js

@@ -67,6 +67,7 @@ export const recallToolResponseTool = {
                 ok: true,
                 tool_use_id: id,
                 rehydrated: true,
+                meta: store.getMeta(id),
                 message: `Full content for tool_use_id=${id} is now visible in the original tool_result above. Read it from there.`,
             });
         }

package/dist/agent/tools/registry.js

@@ -4,7 +4,7 @@
  * Splitting this out of index.ts avoids circular imports.
  */
 import { readFileTool, writeFileTool, editFileTool, listDirectoryTool } from './file.js';
-import { runCommandTool } from './shell.js';
+import { runCommandTool, readCommandTool, stopCommandTool } from './shell.js';
 import { zergQueryTool, zergTaskStatusTool, zergListTool } from './zerg.js';
 import { zergWatchTool } from './zerg_watch.js';
 import { searchTool } from './search.js';
@@ -31,6 +31,8 @@ export const defaultTools = [
     listSkillsTool,
     invokeSkillTool,
     runCommandTool,
+    readCommandTool,
+    stopCommandTool,
     zergQueryTool,
     zergTaskStatusTool,
     zergListTool,

package/dist/agent/tools/search.js

@@ -93,6 +93,7 @@ function normalizePermissionErrors(result) {
     }
 }
 export const searchTool = {
+    parallelSafe: true,
     capabilities: [ToolCapability.FILE_READ],
     definition: {
         name: 'search',

package/dist/agent/tools/shell.d.ts

@@ -13,3 +13,5 @@ export declare function summarizeCommandFailure(output: string, limit?: number):
  */
 export declare function shellErrorHint(exitCode: number, stderr: string, hasStdout: boolean): string | null;
 export declare const runCommandTool: Tool;
+export declare const readCommandTool: Tool;
+export declare const stopCommandTool: Tool;

package/dist/agent/tools/shell.js

@@ -1,6 +1,8 @@
 import { resolve } from 'path';
 import { ToolCapability } from '../runtime/capabilities.js';
 import { runShellCommand } from '../../utils/shell.js';
+import { startCommandJob, readCommandJob, stopCommandJob } from '../runtime/command_jobs.js';
+import { resolveExecutionSettings } from '../../config/execution.js';
 import { configStore } from '../../config.js';
 import { assertTemporaryRootSafe, isPathWithinRoot } from '../../utils/temporary_write_root.js';
 export const FAILURE_OUTPUT_LIMIT = 2000;
@@ -46,8 +48,17 @@ export function shellErrorHint(exitCode, stderr, hasStdout) {
     }
     return null;
 }
+function failedCommandReceipt(content) {
+    try {
+        return ['failed', 'cancelled', 'timed_out', 'interrupted'].includes(JSON.parse(content).status);
+    }
+    catch {
+        return false;
+    }
+}
 // --- Shell Tool ---
 export const runCommandTool = {
+    isErrorResult: failedCommandReceipt,
     capabilities: [ToolCapability.SHELL_EXEC],
     definition: {
         name: 'run_command',
@@ -68,6 +79,8 @@ export const runCommandTool = {
                     type: 'string',
                     description: 'Timeout in milliseconds (default: 30000)'
                 },
+                background: { type: 'boolean', description: 'Start a managed background job. Use read_command and stop_command with its job_id; survives a turn interrupt by default.' },
+                yield_time_ms: { type: 'number', description: 'Initial background wait, 0–60000ms (default 1000).' },
                 stdin: {
                     type: 'string',
                     description: 'Optional text written to the command stdin. Prefer this over heredocs or nested quoting for multi-line payloads (e.g. git commit -F -).'
@@ -132,7 +145,7 @@ export const runCommandTool = {
         const stdin = typeof args.stdin === 'string'
             ? args.stdin
             : undefined;
-        const result = await runShellCommand(command, cwd, context?.signal, timeoutMs, {
+        const shellOptions = {
             profileId,
             profile,
             sandbox,
@@ -140,7 +153,22 @@ export const runCommandTool = {
             temporaryWriteRoot,
             stdin,
             env: context?.subprocessEnv,
-        });
+        };
+        if (args.background === true) {
+            if (temporaryWriteRoot)
+                throw new Error('Background commands are unavailable in temporary write-root workers. Run synchronously.');
+            if (!context?.sessionId)
+                throw new Error('Managed background commands require a session ID from the host.');
+            const wait = args.yield_time_ms === undefined ? 1000 : Number(args.yield_time_ms);
+            if (!Number.isSafeInteger(wait) || wait < 0 || wait > 60000)
+                throw new Error('yield_time_ms must be between 0 and 60000');
+            const settings = resolveExecutionSettings(config.execution);
+            const receipt = await startCommandJob({ sessionId: context.sessionId, command, cwd, timeoutMs,
+                shell: shellOptions, maxJobs: settings.maxBackgroundJobs,
+                signal: settings.interruptBackgroundJobs ? context.signal : undefined });
+            return JSON.stringify(await readCommandJob(context.sessionId, receipt.job_id, 0, wait, context.signal));
+        }
+        const result = await runShellCommand(command, cwd, context?.signal, timeoutMs, shellOptions);
         // Handle non-zero exit codes
         if (result.exitCode !== 0) {
             const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
@@ -160,3 +188,30 @@ export const runCommandTool = {
         });
     }
 };
+export const readCommandTool = {
+    isErrorResult: failedCommandReceipt,
+    capabilities: [ToolCapability.FILE_READ],
+    definition: {
+        name: 'read_command', description: 'Read a managed command receipt and up to 16KB of incremental output. Cursor is a byte offset returned by the previous receipt. Wait is bounded; status running does not mean success.',
+        parameters: { type: 'object', properties: {
+                job_id: { type: 'string', description: 'Session-owned job ID from run_command.' }, cursor: { type: 'number', description: 'Byte cursor from the previous read (default 0).' }, wait_ms: { type: 'number', description: '0–60000ms; waits for completion or deadline.' },
+            }, required: ['job_id'] },
+    },
+    execute: async (args, context) => {
+        if (!context?.sessionId)
+            throw new Error('Managed commands require a session ID.');
+        return JSON.stringify(await readCommandJob(context.sessionId, String(args.job_id), Number(args.cursor ?? 0), Number(args.wait_ms ?? 0), context.signal));
+    },
+};
+export const stopCommandTool = {
+    capabilities: [ToolCapability.SHELL_EXEC],
+    definition: {
+        name: 'stop_command', description: 'Stop an owned local command process group and return its final receipt. Remote jobs must provide their own cleanup.',
+        parameters: { type: 'object', properties: { job_id: { type: 'string', description: 'Session-owned job ID from run_command.' } }, required: ['job_id'] },
+    },
+    execute: async (args, context) => {
+        if (!context?.sessionId)
+            throw new Error('Managed commands require a session ID.');
+        return JSON.stringify(await stopCommandJob(context.sessionId, String(args.job_id)));
+    },
+};

package/dist/agent/tools/types.d.ts

@@ -6,6 +6,7 @@ export interface ToolContext {
     cwd: string;
     /** The model-provided tool-use id that originated this execution. */
     toolCallId?: string;
+    sessionId?: string;
     signal?: AbortSignal;
     temporaryWriteRoot?: string;
     /** Exact environment for shell-tool subprocesses; undefined inherits legacy ambient env. */
@@ -17,6 +18,9 @@ export interface ToolContext {
 }
 export interface Tool {
     definition: ToolDefinition;
+    /** Explicit scheduling opt-in; only read effects may run concurrently. */
+    parallelSafe?: boolean;
+    isErrorResult?: (content: string) => boolean;
     capabilities?: ToolCapability[];
     /** Host scheduling boundary. When omitted, capabilities are mapped
      * conservatively by `resolveToolEffect`. */

package/dist/app/agent_runner.js

@@ -151,7 +151,7 @@ export class AgentRunLifecycle {
         this.abortController = controller;
         const isActive = () => this.activeRunId === runId;
         const cleanup = agent.on((event) => {
-            if (!isActive())
+            if (!isActive() && (event.type !== 'history_checkpoint' || this.activeRunId !== null))
                 return;
             onEvent(event);
         });

package/dist/app/ordered_transcript.d.ts

@@ -0,0 +1,13 @@
+import type { Message } from '../types.js';
+export interface TranscriptIteration {
+    start: number;
+    toolStart?: number;
+}
+/** Reconcile model history with the live display, keeping each iteration's arrival order. */
+export declare function reconcileOrderedTranscript(options: {
+    live: readonly Message[];
+    ordered: readonly Message[];
+    iterations: readonly TranscriptIteration[];
+    toolIterations: ReadonlyMap<string, number>;
+    finalMessage?: Message;
+}): Message[];

package/dist/app/ordered_transcript.js

@@ -0,0 +1,55 @@
+import { isPersistableAssistantMessage } from '../utils/assistant_message.js';
+/** Reconcile model history with the live display, keeping each iteration's arrival order. */
+export function reconcileOrderedTranscript(options) {
+    const { live, ordered, iterations, toolIterations, finalMessage } = options;
+    if (!iterations.length)
+        return [...live];
+    const byIteration = iterations.map(() => []);
+    let current = 0;
+    for (const message of ordered) {
+        if (message.toolCalls?.length)
+            current = toolIterations.get(message.toolCalls[0].id) ?? current;
+        byIteration[current].push(message);
+    }
+    const consumed = new Set(ordered.filter(message => message.role === 'user').map(message => message.id));
+    const output = live.slice(0, iterations[0].start);
+    for (let index = 0; index < iterations.length; index++) {
+        const frame = iterations[index];
+        const end = iterations[index + 1]?.start ?? live.length;
+        const segment = live.slice(frame.start, end).filter(message => !consumed.has(message.id));
+        const canonical = byIteration[index].find(message => message.toolCalls?.length);
+        if (canonical) {
+            const calls = canonical.toolCalls.map(({ result: _result, error: _error, ...call }) => call);
+            const beforeTools = live.slice(frame.start, frame.toolStart ?? end);
+            const anchorId = beforeTools.filter(isPersistableAssistantMessage).at(-1)?.id;
+            const anchor = segment.findIndex(message => message.id === anchorId);
+            if (anchor >= 0) {
+                segment[anchor] = { ...segment[anchor], toolCalls: calls,
+                    metadata: { ...segment[anchor].metadata, ...canonical.metadata, toolCallsInTranscript: true } };
+            }
+            else {
+                // A tool-only response has no answer bubble to carry its API tool_use.
+                // Keep this record before the live trace without moving Thinking blocks.
+                const trace = segment.findIndex(message => message.role === 'tool');
+                const alreadyDisplayed = segment.filter(isPersistableAssistantMessage).map(message => message.content).join('') === canonical.content;
+                segment.splice(trace < 0 ? segment.length : trace, 0, { ...canonical,
+                    content: alreadyDisplayed ? '[Using tools...]' : canonical.content,
+                    toolCalls: calls, metadata: { ...canonical.metadata, toolCallsInTranscript: true } });
+            }
+        }
+        output.push(...segment, ...byIteration[index].filter(message => message !== canonical));
+    }
+    if (finalMessage) {
+        const finalFrame = iterations.length - 1;
+        const finalLive = live.slice(iterations[finalFrame].start).filter(isPersistableAssistantMessage);
+        const anchorId = finalLive.at(-1)?.id;
+        const anchor = output.findIndex(message => message.id === anchorId);
+        if (anchor >= 0) {
+            output[anchor] = { ...output[anchor], metadata: { ...output[anchor].metadata, ...finalMessage.metadata } };
+        }
+        else if (!byIteration[finalFrame].some(message => message.role === 'assistant' && message.content === finalMessage.content)) {
+            output.push(finalMessage);
+        }
+    }
+    return output;
+}

package/dist/cli_ratatui.d.ts

@@ -1,10 +1,3 @@
-/**
- * RatatuiApp — the interactive TUI application class.
- *
- * Uses the Rust/Ratatui renderer for terminal rendering with proper
- * differential rendering.  The CLI entry point that parses arguments
- * and launches this class lives in cli_main.ts.
- */
 import { TuiProcess, NullTuiProcess, HeadlessPaneManager } from './ui/ratatui/index.js';
 import { getMirrorCommandUsages, isRichSlashUsage } from './agent/commands/mirror_usages.js';
 import { type Session } from './session.js';
@@ -909,6 +902,8 @@ export declare class RatatuiApp {
      * its restricted tool surface must take precedence over that pane default.
      */
     private getEffectiveAgentMode;
+    private commandJobsUnsubscribe;
+    private commandJobStates;
     private createAgent;
     private awaitAgentBind;
     private bindAgentStore;