@zergai/ztc 0.5.0-beta.1 → 0.6.0-beta.1

package/dist/utils/shell.js

@@ -6,7 +6,9 @@ import { buildSandboxCommandPlan } from './sandbox.js';
 import { buildTemporaryWriteRootSubprocessEnv, buildUserSubprocessEnv } from './subprocess_env.js';
 import { CheckedShellCoordinator, formatCheckedStageCommand } from './checked_shell.js';
 import { parseCommandExecutionPolicy } from '../agent/runtime/command_execution_policy.js';
+import { COPY_ADVICE, copyNote, ToolOutputCopy } from './tool_output_copies.js';
 const MAX_OUTPUT = 10000;
+const OMITTED = '\n… [output omitted] …\n';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DOCKER_TIMEOUT_MS = 120000;
 const PROTECTED_ROOTS = [
@@ -178,7 +180,7 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
         throw new Error(`Command rejected for safety reasons: ${describeSafetyRule(verdict.rule)} (target: ${verdict.token}). `
             + `[safety rule=${verdict.rule} token=${verdict.token}]`);
     }
-    const { env, temporaryWriteRoot, stdin, noTimeout, executionMode = 'foreground', turnInterruptPolicy, onExecutionPolicy, onOutput, checked, onCheckedProgress, ...sandboxCommandOptions } = sandboxOptions ?? {};
+    const { env, temporaryWriteRoot, stdin, noTimeout, executionMode = 'foreground', turnInterruptPolicy, onExecutionPolicy, onOutput, checked, onCheckedProgress, outputCopy, ...sandboxCommandOptions } = sandboxOptions ?? {};
     if (checked && (process.platform !== 'darwin' && process.platform !== 'linux' || DOCKER_CONTAINER)) {
         throw new Error('Checked execution supports local macOS/Linux Bash only; Docker and Windows are unsupported.');
     }
@@ -238,6 +240,9 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
         let stderr = '';
         let stdoutOverflow = false;
         let stderrOverflow = false;
+        // Opened when a stream first passes MAX_OUTPUT; null when no copy could be kept.
+        let stdoutCopy;
+        let stderrCopy;
         let timedOut = false;
         let cancelled = false;
         let outputError;
@@ -250,6 +255,11 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
                 onAbort();
             }
             stdoutOverflow ||= stdout.length + chunk.length > MAX_OUTPUT;
+            if (stdoutOverflow && outputCopy && stdoutCopy === undefined) {
+                stdoutCopy = ToolOutputCopy.open(outputCopy.folder, outputCopy.id, 'stdout');
+                stdoutCopy?.write(stdout);
+            }
+            stdoutCopy?.write(chunk);
             stdout = retainOutputEdges(stdout, chunk);
         });
         child.stderr?.on('data', (chunk) => {
@@ -261,6 +271,11 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
                 onAbort();
             }
             stderrOverflow ||= stderr.length + chunk.length > MAX_OUTPUT;
+            if (stderrOverflow && outputCopy && stderrCopy === undefined) {
+                stderrCopy = ToolOutputCopy.open(outputCopy.folder, outputCopy.id, 'stderr');
+                stderrCopy?.write(stderr);
+            }
+            stderrCopy?.write(chunk);
             stderr = retainOutputEdges(stderr, chunk);
         });
         let killTimer = null;
@@ -328,6 +343,15 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
                 signal.removeEventListener('abort', onAbort);
             if (childPid)
                 activeChildGroups.delete(childPid);
+            stdoutCopy?.close();
+            stderrCopy?.close();
+        };
+        // Where output was cut, name the file that holds all of it.
+        const copied = () => {
+            const recallId = outputCopy?.recallable ? outputCopy.id : undefined;
+            const out = nameCopy(stdout, stdoutCopy, recallId, 'stdout'), err = nameCopy(stderr, stderrCopy, recallId, 'stderr');
+            const outputCopies = { ...(out.path ? { stdout: out.path } : {}), ...(err.path ? { stderr: err.path } : {}) };
+            return { stdout: out.text, stderr: err.text, ...(Object.keys(outputCopies).length ? { outputCopies } : {}) };
         };
         let settled = false;
         const settleResolve = (r) => {
@@ -356,11 +380,13 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
                 return;
             }
             const outcome = coordinator?.finish(1, cancelled ? 'cancelled' : undefined);
+            const { outputCopies, ...named } = copied();
             settleResolve({
                 command,
                 cwd: effectiveCwd,
-                stdout: appendSandboxAudit(stdout, sandboxPlan.auditPath),
-                stderr: stderr || err.message,
+                stdout: appendSandboxAudit(named.stdout, sandboxPlan.auditPath),
+                stderr: named.stderr || err.message,
+                ...(outputCopies ? { outputCopies } : {}),
                 exitCode: outcome?.exitCode ?? 1,
                 truncated: stdoutOverflow || stderrOverflow,
                 ...(outcome ? { checked: outcome.checked } : {}),
@@ -377,16 +403,18 @@ export async function runShellCommand(command, cwd, signal, timeoutMs, sandboxOp
                 settleReject(new Error('Command cancelled'));
                 return;
             }
+            const { outputCopies, ...named } = copied();
             const finalStderr = timedOut
-                ? (stderr ? stderr + '\nCommand timed out' : 'Command timed out')
-                : stderr;
+                ? (named.stderr ? named.stderr + '\nCommand timed out' : 'Command timed out')
+                : named.stderr;
             const exitCode = timedOut ? 124 : (code ?? (sig ? 128 : 1));
             const outcome = coordinator?.finish(exitCode, timedOut ? 'timed_out' : cancelled ? 'cancelled' : undefined);
             settleResolve({
                 command,
                 cwd: effectiveCwd,
-                stdout: appendSandboxAudit(stdout, sandboxPlan.auditPath),
+                stdout: appendSandboxAudit(named.stdout, sandboxPlan.auditPath),
                 stderr: finalStderr,
+                ...(outputCopies ? { outputCopies } : {}),
                 exitCode: outcome?.exitCode ?? exitCode,
                 truncated: stdoutOverflow || stderrOverflow,
                 ...(outcome ? { checked: outcome.checked } : {}),
@@ -399,7 +427,15 @@ function retainOutputEdges(current, chunk) {
     if (output.length <= MAX_OUTPUT)
         return output;
     const half = Math.floor(MAX_OUTPUT / 2);
-    return `${output.slice(0, half)}\n… [output omitted] …\n${output.slice(-half)}`;
+    return `${output.slice(0, half)}${OMITTED}${output.slice(-half)}`;
+}
+/** Names the full copy at the cut, or keeps the plain mark when no copy was kept. */
+function nameCopy(output, copy, recallId, stream) {
+    const path = copy?.close() ?? null;
+    const at = Math.floor(MAX_OUTPUT / 2);
+    if (!path || output.slice(at, at + OMITTED.length) !== OMITTED)
+        return { text: output };
+    return { text: `${output.slice(0, at)}\n… [output omitted; ${copyNote('output', path, recallId, stream)}; ${COPY_ADVICE}] …\n${output.slice(at + OMITTED.length)}`, path };
 }
 function appendSandboxAudit(stdout, auditPath) {
     if (!auditPath) {

package/dist/utils/subprocess_env.d.ts

@@ -1,4 +1,31 @@
 export declare function reserveUserSubprocessCredentials(names: readonly string[]): void;
+/**
+ * Every variable ZTC reads a model-route credential from: each provider's
+ * standard key (PROVIDER_API_KEY_ENV), the legacy ZTC_API_KEY override, the
+ * platform and required-Router bearers, and the subscription/API credentials
+ * the Claude Code and Codex CLI backends consume.
+ */
+export declare const MODEL_ROUTE_CREDENTIAL_ENV: readonly string[];
+/**
+ * Keep the run's inference credentials in the host process. Headless runs are
+ * driven by a model with no human reviewing each command, so every tool child
+ * (run_command shells, process and command panes, run_and_capture launches,
+ * language servers, search and git helpers) loses the route credentials and
+ * any variable the config names as a provider key (`apiKeyEnv`). The parent
+ * keeps its environment; headless `ztc` panes regain them through
+ * `restoreModelRouteCredentials`, and framework children that build their own
+ * env (colony panes, CLI backends) are unaffected. Names ZTC could never read
+ * a key from are skipped rather than failing the run.
+ */
+export declare function reserveModelRouteCredentials(namedKeyEnv?: Readonly<Record<string, string>>): readonly string[];
+/**
+ * Give a ZTC framework child that runs its own inference (a headless `ztc`
+ * pane: sub-agent or sim agent) back the reserved route credentials present
+ * in `source`. That child reserves them again at its own init, so its tool
+ * children stay clean. Broker tokens and the ZTC infra variables that every
+ * pane loses (ZTC_AUTH_TOKEN, ZTC_BROKER_TOKEN, ...) are never restored.
+ */
+export declare function restoreModelRouteCredentials(env: NodeJS.ProcessEnv, source: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 /** Keep pane-local control fields while removing host RPC credentials. */
 export declare function removeUserSubprocessCredentials(source: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
 export declare function buildUserSubprocessEnv(source?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/utils/subprocess_env.js

@@ -1,3 +1,4 @@
+import { PROVIDER_API_KEY_ENV } from '../config/provider_api_key_env.js';
 const USER_SUBPROCESS_STRIPPED_ZTC_ENV = [
     'ZERG_ROUTER_BASE_URL',
     'ZTC_AUTH_TOKEN',
@@ -17,16 +18,81 @@ const USER_SUBPROCESS_STRIPPED_ZTC_ENV = [
     'ZTC_PANE_RELAY',
     'ZTC_PARENT_PID',
 ];
+const STRIPPED_ZTC_ENV_NAMES = new Set(USER_SUBPROCESS_STRIPPED_ZTC_ENV);
 // Host configuration reserves these names for the lifetime of this process.
 // Removing a resource/profile must not expose its formerly inherited credential.
 const hostCredentialEnvNames = new Set();
-export function reserveUserSubprocessCredentials(names) {
+// Remote-resource broker tokens: no child of any kind may regain these.
+const brokerCredentialEnvNames = new Set();
+// Inference credentials reserved by a headless run; only ZTC framework children
+// that infer for themselves (headless `ztc` panes) may regain them.
+const modelRouteCredentialEnvNames = new Set();
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
+function reserveCredentialNames(names, kind) {
     for (const name of names) {
-        if (typeof name !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(name))
+        if (typeof name !== 'string' || !ENV_NAME.test(name))
             throw new Error('Invalid host broker credential environment variable');
     }
-    for (const name of names)
+    for (const name of names) {
         hostCredentialEnvNames.add(name);
+        kind.add(name);
+    }
+}
+export function reserveUserSubprocessCredentials(names) {
+    reserveCredentialNames(names, brokerCredentialEnvNames);
+}
+/**
+ * Every variable ZTC reads a model-route credential from: each provider's
+ * standard key (PROVIDER_API_KEY_ENV), the legacy ZTC_API_KEY override, the
+ * platform and required-Router bearers, and the subscription/API credentials
+ * the Claude Code and Codex CLI backends consume.
+ */
+export const MODEL_ROUTE_CREDENTIAL_ENV = Object.freeze([...new Set([
+        ...Object.values(PROVIDER_API_KEY_ENV).flat(),
+        'ZTC_API_KEY',
+        'ZTC_AUTH_TOKEN',
+        'ZERG_AUTH_TOKEN',
+        'ANTHROPIC_AUTH_TOKEN',
+        'CLAUDE_CODE_OAUTH_TOKEN',
+        'CODEX_API_KEY',
+        'CODEX_ACCESS_TOKEN',
+    ])]);
+/**
+ * Keep the run's inference credentials in the host process. Headless runs are
+ * driven by a model with no human reviewing each command, so every tool child
+ * (run_command shells, process and command panes, run_and_capture launches,
+ * language servers, search and git helpers) loses the route credentials and
+ * any variable the config names as a provider key (`apiKeyEnv`). The parent
+ * keeps its environment; headless `ztc` panes regain them through
+ * `restoreModelRouteCredentials`, and framework children that build their own
+ * env (colony panes, CLI backends) are unaffected. Names ZTC could never read
+ * a key from are skipped rather than failing the run.
+ */
+export function reserveModelRouteCredentials(namedKeyEnv = {}) {
+    const names = [...new Set([
+            ...MODEL_ROUTE_CREDENTIAL_ENV,
+            ...Object.values(namedKeyEnv).filter(name => typeof name === 'string' && ENV_NAME.test(name)),
+        ])];
+    reserveCredentialNames(names, modelRouteCredentialEnvNames);
+    return names;
+}
+/**
+ * Give a ZTC framework child that runs its own inference (a headless `ztc`
+ * pane: sub-agent or sim agent) back the reserved route credentials present
+ * in `source`. That child reserves them again at its own init, so its tool
+ * children stay clean. Broker tokens and the ZTC infra variables that every
+ * pane loses (ZTC_AUTH_TOKEN, ZTC_BROKER_TOKEN, ...) are never restored.
+ */
+export function restoreModelRouteCredentials(env, source) {
+    const restored = { ...env };
+    for (const name of modelRouteCredentialEnvNames) {
+        if (brokerCredentialEnvNames.has(name) || STRIPPED_ZTC_ENV_NAMES.has(name))
+            continue;
+        const value = source[name];
+        if (value !== undefined)
+            restored[name] = value;
+    }
+    return restored;
 }
 /** Keep pane-local control fields while removing host RPC credentials. */
 export function removeUserSubprocessCredentials(source) {

package/dist/utils/tool_output_copies.d.ts

@@ -0,0 +1,44 @@
+/** Closes every note that names a copy. Without it a model saw the path and ran the whole command again. */
+export declare const COPY_ADVICE = "read or grep that file instead of running the call again";
+/** What a copy holds: a whole tool result, a command's stdout or stderr, or a failed command's combined output. */
+export type CopyPart = 'result' | 'stdout' | 'stderr' | 'output';
+export declare const COPY_PARTS: readonly CopyPart[];
+/** Names a copy, and recall_tool_response when the copy belongs to a tool call. */
+export declare function copyNote(label: string, path: string, toolUseId?: string, part?: CopyPart): string;
+/** A copy stops growing here and says so, so a runaway command cannot fill the disk. */
+export declare const TOOL_OUTPUT_COPY_MAX_BYTES: number;
+export declare function canReadCopies(toolNames: Iterable<string>): boolean;
+/** A name for a copy whose tool call has no id. */
+export declare function unnamedCopy(): string;
+/** Names a shortened result's copy and the call's other copies, whose own notes the shortening may have cut off. */
+export declare function resultCopyNote(toolUseId: string, path: string): string;
+/** Streams a copy to disk as the output arrives. */
+export declare class ToolOutputCopy {
+    readonly path: string;
+    private readonly fd;
+    private written;
+    private failed;
+    private closed;
+    private readonly digest;
+    private constructor();
+    /** Null when the session's copy folder cannot be used; the output is then shortened with no copy. */
+    static open(folder: string, id: string, part: CopyPart): ToolOutputCopy | null;
+    write(text: string): void;
+    /** The copy's path, or null when it could not be written. Its digest is recorded beside it. */
+    close(): string | null;
+}
+/** Saves whole text in the session's copy folder and returns its path, or null when no copy could be kept. */
+export declare function saveCopy(folder: string, id: string, part: CopyPart, text: string): string | null;
+/** The path of an existing copy in the session's copy folder, or null when there is none. */
+export declare function findCopy(folder: string, id: string, part: CopyPart): string | null;
+/** Whether a copy still holds the bytes whose digest was recorded when it was written. */
+export declare function copyMatchesDigest(path: string): boolean;
+export interface CopyChunk {
+    content: string;
+    cursor: number;
+    nextCursor: number;
+    totalBytes: number;
+    complete: boolean;
+}
+/** Reads up to maxBytes of a copy from a UTF-8 boundary, or null when the file is gone. */
+export declare function readCopyChunk(path: string, cursor?: number, maxBytes?: number): CopyChunk | null;

package/dist/utils/tool_output_copies.js

@@ -0,0 +1,196 @@
+/**
+ * Full copies of tool output that was shortened before the model saw it (user 2026-10-26: "store the rest of the
+ * result on a file in tmp or smth with the path mentioned in the context so it can read that and check"). Copies live
+ * in the session's own private folder (ToolResponseStore.outputCopyDir), so they are deleted with the session and two
+ * sessions never share a name (PR #817 review: one shared temp folder let `tool_0` of one session read another's).
+ * Callers keep ephemeral tools' output out of here. A copy is named by its tool call and part, with its sha256 beside
+ * it; recall_tool_response reads it only while the digest matches, and writes a result's copy again from the session
+ * store when it is gone.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { closeSync, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, writeFileSync, writeSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+/** Closes every note that names a copy. Without it a model saw the path and ran the whole command again. */
+export const COPY_ADVICE = 'read or grep that file instead of running the call again';
+export const COPY_PARTS = ['result', 'stdout', 'stderr', 'output'];
+/** Names a copy, and recall_tool_response when the copy belongs to a tool call. */
+export function copyNote(label, path, toolUseId, part = 'result') {
+    const recall = toolUseId ? ` (also recall_tool_response tool_use_id=${toolUseId}${part === 'result' ? '' : ` part=${part}`})` : '';
+    return `full ${label}: ${path}${recall}`;
+}
+/** A copy stops growing here and says so, so a runaway command cannot fill the disk. */
+export const TOOL_OUTPUT_COPY_MAX_BYTES = 64 * 1024 * 1024;
+const STOPPED = `\n[copy stopped at ${TOOL_OUTPUT_COPY_MAX_BYTES / 1024 / 1024} MB]\n`;
+/** Tools that can read a copy, by its path or by recall. An agent with none of them keeps no copy and names none. */
+const COPY_READERS = new Set(['recall_tool_response', 'read_file', 'run_command', 'exec_command', 'search', 'Read', 'Bash', 'Grep']);
+export function canReadCopies(toolNames) {
+    for (const name of toolNames)
+        if (COPY_READERS.has(name))
+            return true;
+    return false;
+}
+function copyFolder(dir) {
+    const uid = process.getuid?.();
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const info = lstatSync(dir);
+        // Another user's folder, a link or a readable folder would expose the output.
+        if (!info.isDirectory() || (uid !== undefined && info.uid !== uid) || (info.mode & 0o077) !== 0)
+            return null;
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}
+function copyPath(dir, name) {
+    return join(dir, /^[A-Za-z0-9_.-]{1,180}$/.test(name) ? `${name}.txt`
+        : `${createHash('sha256').update(name).digest('hex').slice(0, 32)}.txt`);
+}
+/** A name for a copy whose tool call has no id. */
+export function unnamedCopy() {
+    return `run-${randomUUID()}`;
+}
+const copyName = (id, part) => `${id}.${part}`;
+/** Names a shortened result's copy and the call's other copies, whose own notes the shortening may have cut off. */
+export function resultCopyNote(toolUseId, path) {
+    const others = ['stdout', 'stderr', 'output'].flatMap(part => {
+        const other = findCopy(dirname(path), toolUseId, part);
+        return other ? [copyNote(part === 'output' ? 'command output' : part, other, toolUseId, part)] : [];
+    });
+    return [copyNote('output', path, toolUseId), ...others].join('; ');
+}
+/** Streams a copy to disk as the output arrives. */
+export class ToolOutputCopy {
+    path;
+    fd;
+    written = 0;
+    failed = false;
+    closed = false;
+    digest = createHash('sha256');
+    constructor(path, fd) {
+        this.path = path;
+        this.fd = fd;
+    }
+    /** Null when the session's copy folder cannot be used; the output is then shortened with no copy. */
+    static open(folder, id, part) {
+        const dir = copyFolder(folder);
+        if (!dir)
+            return null;
+        const path = copyPath(dir, copyName(id, part));
+        try {
+            return new ToolOutputCopy(path, openSync(path, 'w', 0o600));
+        }
+        catch {
+            return null;
+        }
+    }
+    write(text) {
+        if (this.failed || this.closed || this.written >= TOOL_OUTPUT_COPY_MAX_BYTES)
+            return;
+        const bytes = Buffer.from(text, 'utf8');
+        const room = TOOL_OUTPUT_COPY_MAX_BYTES - this.written;
+        try {
+            const kept = bytes.length > room ? bytes.subarray(0, room) : bytes;
+            writeSync(this.fd, kept);
+            this.digest.update(kept);
+            this.written += kept.length;
+            if (bytes.length > room) {
+                writeSync(this.fd, STOPPED);
+                this.digest.update(STOPPED);
+            }
+        }
+        catch {
+            this.failed = true;
+        }
+    }
+    /** The copy's path, or null when it could not be written. Its digest is recorded beside it. */
+    close() {
+        if (!this.closed) {
+            this.closed = true;
+            try {
+                closeSync(this.fd);
+            }
+            catch {
+                this.failed = true;
+            }
+            if (!this.failed) {
+                try {
+                    writeFileSync(digestPath(this.path), this.digest.digest('hex'), { mode: 0o600 });
+                }
+                catch {
+                    this.failed = true;
+                }
+            }
+        }
+        return this.failed ? null : this.path;
+    }
+}
+// A result is shortened again on every request; write its copy once.
+const saved = new Map();
+const digestPath = (path) => join(dirname(path), `${basename(path, '.txt')}.sha256`);
+/** Saves whole text in the session's copy folder and returns its path, or null when no copy could be kept. */
+export function saveCopy(folder, id, part, text) {
+    const dir = copyFolder(folder);
+    if (!dir)
+        return null;
+    const path = copyPath(dir, copyName(id, part));
+    if (saved.get(path) === text.length && existsSync(path))
+        return path;
+    const copy = ToolOutputCopy.open(folder, id, part);
+    if (!copy)
+        return null;
+    copy.write(text);
+    const written = copy.close();
+    if (written)
+        saved.set(written, text.length);
+    return written;
+}
+/** The path of an existing copy in the session's copy folder, or null when there is none. */
+export function findCopy(folder, id, part) {
+    const dir = copyFolder(folder);
+    if (!dir)
+        return null;
+    const path = copyPath(dir, copyName(id, part));
+    return existsSync(path) ? path : null;
+}
+/** Whether a copy still holds the bytes whose digest was recorded when it was written. */
+export function copyMatchesDigest(path) {
+    try {
+        const recorded = readFileSync(digestPath(path), 'utf8').trim();
+        return /^[a-f0-9]{64}$/.test(recorded) && createHash('sha256').update(readFileSync(path)).digest('hex') === recorded;
+    }
+    catch {
+        return false;
+    }
+}
+/** Reads up to maxBytes of a copy from a UTF-8 boundary, or null when the file is gone. */
+export function readCopyChunk(path, cursor = 0, maxBytes = 8192) {
+    let fd;
+    try {
+        fd = openSync(path, 'r');
+    }
+    catch {
+        return null;
+    }
+    try {
+        const totalBytes = fstatSync(fd).size;
+        if (cursor > totalBytes)
+            throw new RangeError('cursor must identify a UTF-8 boundary within the source');
+        // One extra byte shows whether the cut lands inside a character.
+        const body = Buffer.alloc(Math.min(maxBytes + 1, totalBytes - cursor));
+        const read = readSync(fd, body, 0, body.length, cursor);
+        if (read > 0 && (body[0] & 0xc0) === 0x80)
+            throw new RangeError('cursor must identify a UTF-8 boundary within the source');
+        let end = Math.min(maxBytes, read);
+        while (end > 0 && end < read && (body[end] & 0xc0) === 0x80)
+            end--;
+        if (end === 0 && read > 0)
+            throw new RangeError('maxBytes cannot fit the next UTF-8 character');
+        return { content: body.subarray(0, end).toString('utf8'), cursor, nextCursor: cursor + end, totalBytes,
+            complete: cursor + end === totalBytes };
+    }
+    finally {
+        closeSync(fd);
+    }
+}

package/dist/utils/tool_result_message.d.ts

@@ -2,4 +2,11 @@ import type { Message } from '../types.js';
 type MessageLike = Pick<Message, 'role' | 'content' | 'metadata'>;
 export declare function looksLikeToolResultContent(content: string): boolean;
 export declare function isToolResultMessage(message: MessageLike): boolean;
+/**
+ * A background job's output the host hands the model in a user turn. Drawn as "You" it read as if the person had
+ * typed raw JSON (2026-10-27); the person sees the job's own notice instead.
+ */
+export declare function isCommandObservationMessage(message: MessageLike): boolean;
+/** An auto-continue prompt or interrupted-turn marker the host gives the model; the person sees the host's own notice. */
+export declare function isHostPromptMessage(message: MessageLike): boolean;
 export {};

package/dist/utils/tool_result_message.js

@@ -28,3 +28,14 @@ export function isToolResultMessage(message) {
     }
     return looksLikeToolResultContent(message.content);
 }
+/**
+ * A background job's output the host hands the model in a user turn. Drawn as "You" it read as if the person had
+ * typed raw JSON (2026-10-27); the person sees the job's own notice instead.
+ */
+export function isCommandObservationMessage(message) {
+    return message.role === 'user' && message.metadata?.managedCommandObservation === true;
+}
+/** An auto-continue prompt or interrupted-turn marker the host gives the model; the person sees the host's own notice. */
+export function isHostPromptMessage(message) {
+    return message.role === 'user' && (message.metadata?.autoContinue === true || message.metadata?.interruptedTurn === true);
+}

package/dist/utils/tool_trace.d.ts

@@ -7,6 +7,19 @@ export declare function formatToolDisplayLabel(tool: string): string;
 export declare function formatToolStart(tool: string, args: Record<string, unknown>, emulationId?: string): string;
 export declare function formatToolEnd(tool: string, result: string, durationMs?: number, emulationId?: string): string;
 export declare function formatToolError(tool: string, error: string, emulationId?: string): string;
+/**
+ * An image a tool produced or opened. `path` names a file to read at render
+ * time; `data` is base64 bytes that exist only in the tool result.
+ */
+export type ToolOutputImage = {
+    label: string;
+    path: string;
+} | {
+    label: string;
+    mediaType: string;
+    data: string;
+    path?: string;
+};
 /** One call's block inside a grouped tool message body. */
 export interface ToolOutputSection {
     /** Tool that produced the block; drives its highlight mode. */
@@ -38,6 +51,8 @@ export interface ToolOutputMessage {
      * its own tool's mode instead of the group's generic one.
      */
     sections?: ToolOutputSection[];
+    /** Images the calls returned or opened, in call order. */
+    images?: ToolOutputImage[];
 }
 /** Represents a single tool call in a batch */
 export interface BatchedToolCall {

package/dist/utils/tool_trace.js

@@ -1,8 +1,11 @@
+import { basename } from 'node:path';
 import { getTraceStyle } from '../emulation/trace_style.js';
 import { getEmulationToolMapping } from '../emulation/tool_adapters.js';
+import { parseImageToolResult } from '../agent/tool_result_parsing.js';
 import { DEFAULT_MESSAGE_DISPLAY, parseToolOutputLines, } from '../config/message_display.js';
 import { displayWidth, sanitizeTerminalText } from '../ui/core/text_width.js';
 import { formatTracePath, formatBytes, formatDuration } from './path_format.js';
+import { failureWithoutExecutionSuffix } from '../agent/runtime/command_execution_policy.js';
 /**
  * Column budget for a tool body line when the caller has no terminal width.
  * Wide enough for a normal source line, small enough that a minified bundle or
@@ -295,6 +298,12 @@ function formatOutcome(tool, result, durationMs) {
     const parsed = parseResult(result);
     const duration = typeof durationMs === 'number' ? ` in ${formatDuration(durationMs)}` : '';
     const toolLabel = formatToolDisplayLabel(tool);
+    // Any tool can return an image (screenshot, computer, read_file, MCP). The
+    // transcript draws the image itself; the summary is its description.
+    const image = parseImageToolResult(result);
+    if (image) {
+        return `${typeof image.description === 'string' && image.description ? image.description : 'Image'}${duration}`;
+    }
     if (!parsed) {
         const text = String(result || '').trim();
         if (text) {
@@ -310,6 +319,9 @@ function formatOutcome(tool, result, durationMs) {
         return `Found ${count} ${label}${duration}`;
     }
     if (tool === 'run_command') {
+        // A background start returns at once; "done" read as if the job had finished (2026-10-27).
+        if (typeof parsed.job_id === 'string' && parsed.status === 'running')
+            return `Bash running in the background${duration}`;
         const stdout = String(parsed.stdout || '');
         const stderr = String(parsed.stderr || '');
         const lines = (stdout || stderr).trim().split('\n').filter(Boolean).length;
@@ -375,8 +387,8 @@ function formatOutcome(tool, result, durationMs) {
 }
 function collectOutputLines(tool, result, maxWidth) {
     // Image bytes belong to the tool result, never the text scrollback. The
-    // existing screenshot outcome renders the human-readable description.
-    if (tool === 'screenshot')
+    // outcome line carries the description and the transcript draws the image.
+    if (tool === 'screenshot' || parseImageToolResult(result))
         return { lines: [], truncated: false };
     const parsed = parseResult(result);
     if (!parsed) {
@@ -549,8 +561,8 @@ export function formatToolEnd(tool, result, durationMs, emulationId) {
 export function formatToolError(tool, error, emulationId) {
     const style = getTraceStyle(emulationId);
     const label = formatToolDisplayLabel(tool);
-    // Provide helpful error messages
-    let displayError = error;
+    // Provide helpful error messages. The execution policy is host bookkeeping; the model reads failures without it.
+    let displayError = failureWithoutExecutionSuffix(error);
     if (error.includes('Screen Recording permission')) {
         displayError = 'Screen Recording permission required (System Settings > Privacy & Security)';
     }
@@ -562,6 +574,23 @@ export function formatToolError(tool, error, emulationId) {
     }
     return `< ${label} failed: ${displayError}`;
 }
+/**
+ * Images in one tool call's result: an image envelope from any tool, or the
+ * file opened by Codex's native image viewer (its `imageView` action).
+ */
+function toolOutputImages(tool, args, result) {
+    const image = parseImageToolResult(result);
+    if (image && typeof image.data === 'string' && typeof image.mediaType === 'string') {
+        const path = image.path ?? (typeof args?.path === 'string' ? args.path : '');
+        const label = path ? basename(path)
+            : typeof image.description === 'string' && image.description ? image.description : formatToolDisplayLabel(tool);
+        return [{ label, mediaType: image.mediaType, data: image.data, ...(image.path ? { path: image.path } : {}) }];
+    }
+    if (tool === 'imageView' && typeof args?.path === 'string' && args.path) {
+        return [{ label: basename(args.path), path: args.path }];
+    }
+    return [];
+}
 export function buildToolOutputMessage(tool, result, durationMs, emulationId, maxWidth, display = {}) {
     const label = formatToolDisplayLabel(tool);
     tool = getEmulationToolMapping(emulationId)?.[tool] ?? tool;
@@ -637,21 +666,23 @@ export function buildToolGroupOutput(calls, emulationId, maxWidth, display = {})
     });
     if (calls.length === 0)
         return { tool: '', label: 'Tool', preview: '', full: '', truncated: false };
+    const images = calls.flatMap(call => call.status === 'complete' ? toolOutputImages(call.name, call.args, call.result || '') : []);
+    const withImages = (output) => images.length > 0 ? { ...output, images } : output;
     if (calls.length === 1)
-        return { ...outputs[0], tool: calls[0].name, label: 'Tool' };
+        return withImages({ ...outputs[0], tool: calls[0].name, label: 'Tool' });
     if (display.collapseToolCalls === false) {
         // No sections here on purpose: this shape concatenates each call's
         // *preview*, while `full` concatenates its expanded text, and the two have
         // different line counts. Sections would colour the wrong lines in whichever
         // form the user is not looking at, so the body takes the group's generic
         // colours instead.
-        return {
+        return withImages({
             tool: 'tool_group',
             label: 'Tool',
             preview: outputs.map(output => output.preview).join('\n'),
             full: outputs.map(output => output.full).join('\n'),
             truncated: outputs.some(output => output.truncated),
-        };
+        });
     }
     const names = [...new Set(calls.map(call => formatToolDisplayLabel(call.name)))];
     const namesLabel = names.slice(0, 3).join(', ') + (names.length > 3 ? ` +${names.length - 3}` : '');
@@ -684,13 +715,13 @@ export function buildToolGroupOutput(calls, emulationId, maxWidth, display = {})
             ...(query ? { query } : {}),
         };
     });
-    return {
+    return withImages({
         tool: 'tool_group', label: 'Tool', truncated: true,
         headerLines: 2,
         sections,
         preview: `▶ ${title}\n⎿  ${status} (ctrl+o to expand)`,
         full: [`▼ ${title}`, `⎿  ${status}`, ...fullBlocks].join('\n'),
-    };
+    });
 }
 /**
  * Format a batched tool display header