minimal-agent 0.10.0 → 0.12.0

package/src/tools/bash/attachImage.ts

@@ -0,0 +1,281 @@
+/**
+ * ============================================================
+ *  src/tools/bash/attachImage.ts —— Bash 的「让模型看一眼这张图」协议
+ * ------------------------------------------------------------
+ *  背景（为什么需要这个口子）：
+ *    Read 工具明确拒绝二进制/图片（read.ts 的黑名单），Bash 只能回文本，
+ *    全仓库唯一会产 `ToolResult.visionImages` 的是 WebBrowser。于是任何
+ *    「skill 脚本生成/截取了一张图，想让模型亲眼看看」的场景都物理上做不到 ——
+ *    computer-use（截屏）、生图核验、图表渲染核验全卡在这一处。
+ *
+ *  方案：约定一个 stdout sentinel。脚本自己打一行
+ *      <<<ATTACH_IMAGE:/abs/path.png|detail=low|maxLongSide=960>>>
+ *    Bash 解析出来填进 visionImages，并把该行**从给模型看的 content 里剥掉**
+ *    （协议是给宿主看的，不是给模型读的噪声）。
+ *
+ *  为什么是 Bash 的 sentinel 而不是新工具：
+ *    工具 schema 已占稳定系统提示词前缀的绝大头，新增一个多 action 的工具
+ *    等于让**所有用户的每次请求**都为它付 token。sentinel 是零新增 schema
+ *    字节的加性改动，而且天然通用 —— 任何脚本都能用，不绑任何具体 skill。
+ *
+ *  安全边界（重要）：
+ *    `multimodal.ts::imageToContentPart` 对路径**没有任何沙箱**，它会老实读
+ *    任何给它的绝对路径并 base64 进请求体。既然现在允许「命令输出决定读哪个
+ *    文件」，防线就必须建在这里：
+ *      ① 路径必须落在 cwd 或系统临时目录之下（realpath 之后比较，防软链逃逸）
+ *      ② 数量上限（图很贵，一次回 20 张能直接打爆上下文）
+ *      ③ 单图与总字节上限
+ *    越界的一律拒绝，并**如实写进 content 告诉模型哪张被拒、为什么** ——
+ *    静默丢弃会让脚本作者以为图发出去了，debug 时无从下手。
+ * ============================================================
+ */
+
+import { open, realpath, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, resolve } from 'node:path';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { pathContains } from '../../utils/pathContains.js';
+import { MAX_IMAGE_BYTES, sniffImageMime } from '../../multimodal.js';
+import type { ImageDetail, ImageInputSpec } from '../../types.js';
+
+/** 一次 Bash 调用最多附多少张图。图是上下文里最贵的东西，宁少勿多。 */
+export const MAX_ATTACH_IMAGES = 4;
+
+/**
+ * 一次 Bash 调用附图的总字节上限。取单图上限的 2 倍而非 4 倍：
+ * base64 会把体积撑到约 4/3，且 provider 侧有请求体上限（Claude 32MB），
+ * 留足余量给同一请求里的文本与历史。
+ */
+export const MAX_ATTACH_TOTAL_BYTES = MAX_IMAGE_BYTES * 2;
+
+/** 整行 sentinel（必须独占一行；行首尾允许空白）。 */
+const SENTINEL_LINE = /^[ \t]*<<<ATTACH_IMAGE:(.*?)>>>[ \t]*$/;
+
+/** 已知的可选段，从 payload 尾部往前剥；剩下的（可能含 `|`）才是路径。 */
+const OPTION_SEGMENT = /^(detail|maxLongSide)=(.*)$/;
+
+const VALID_DETAILS: ReadonlySet<string> = new Set<ImageDetail>(['low', 'default', 'high']);
+
+/** 解析出来但还没经过 fs / 边界校验的一条指令。 */
+export interface AttachImageDirective {
+  /** sentinel 里写的原始路径（可能是相对路径） */
+  rawPath: string;
+  detail?: ImageDetail;
+  maxLongSidePixel?: number;
+}
+
+export interface ExtractResult {
+  /** 剥掉全部 sentinel 行之后的 stdout */
+  text: string;
+  directives: AttachImageDirective[];
+}
+
+/**
+ * 纯函数：从 stdout 里摘出 sentinel 行并剥除。不碰文件系统，便于单测。
+ *
+ * 无法识别的 payload（如空路径、只有选项没有路径）当作**普通输出行保留** ——
+ * 宁可让模型看到一行奇怪的文本，也不要把用户真实的输出悄悄吃掉。
+ */
+export function extractAttachImageDirectives(stdout: string): ExtractResult {
+  if (!stdout.includes('<<<ATTACH_IMAGE:')) {
+    return { text: stdout, directives: [] };
+  }
+
+  const directives: AttachImageDirective[] = [];
+  const kept: string[] = [];
+
+  for (const line of stdout.split('\n')) {
+    const match = SENTINEL_LINE.exec(line);
+    if (!match) {
+      kept.push(line);
+      continue;
+    }
+    const directive = parsePayload(match[1] ?? '');
+    if (!directive) {
+      kept.push(line); // 认不出来的形状原样保留，不静默吞
+      continue;
+    }
+    directives.push(directive);
+  }
+
+  return { text: kept.join('\n'), directives };
+}
+
+/** 从尾部剥已知选项段，剩余部分（重新用 `|` 拼回）是路径 —— 容忍路径里含 `|`。 */
+function parsePayload(payload: string): AttachImageDirective | null {
+  const segments = payload.split('|');
+  let detail: ImageDetail | undefined;
+  let maxLongSidePixel: number | undefined;
+
+  while (segments.length > 1) {
+    const tail = segments[segments.length - 1]!;
+    const option = OPTION_SEGMENT.exec(tail.trim());
+    if (!option) break;
+
+    const [, key, rawValue] = option;
+    const value = (rawValue ?? '').trim();
+    if (key === 'detail') {
+      if (!VALID_DETAILS.has(value)) return null; // 写错了就整条不认，别猜
+      detail = value as ImageDetail;
+    } else {
+      const n = Number(value);
+      if (!Number.isFinite(n) || n <= 0) return null;
+      maxLongSidePixel = Math.floor(n);
+    }
+    segments.pop();
+  }
+
+  const rawPath = segments.join('|').trim();
+  if (!rawPath) return null;
+
+  return {
+    rawPath,
+    ...(detail ? { detail } : {}),
+    ...(maxLongSidePixel !== undefined ? { maxLongSidePixel } : {}),
+  };
+}
+
+export interface ResolveResult {
+  images: ImageInputSpec[];
+  /** 被拒绝的条目说明；调用方须把它拼进 content，让模型知道图没发出去。 */
+  rejections: string[];
+}
+
+export interface ResolveOptions {
+  /** 允许的根目录（默认 cwd + 系统临时目录）。测试可注入。 */
+  allowedRoots?: string[];
+  maxImages?: number;
+  maxTotalBytes?: number;
+}
+
+/**
+ * 校验并解析成 `ImageInputSpec`。逐条独立判定 —— 一张被拒不影响其它张。
+ */
+export async function resolveAttachImages(
+  directives: AttachImageDirective[],
+  options: ResolveOptions = {},
+): Promise<ResolveResult> {
+  if (directives.length === 0) return { images: [], rejections: [] };
+
+  const maxImages = options.maxImages ?? MAX_ATTACH_IMAGES;
+  const maxTotalBytes = options.maxTotalBytes ?? MAX_ATTACH_TOTAL_BYTES;
+  const roots = await canonicalRoots(options.allowedRoots ?? [getWorkingDir(), tmpdir()]);
+
+  const images: ImageInputSpec[] = [];
+  const rejections: string[] = [];
+  let totalBytes = 0;
+
+  for (const directive of directives) {
+    if (images.length >= maxImages) {
+      rejections.push(`${directive.rawPath}：一次最多附 ${maxImages} 张图，已超出`);
+      continue;
+    }
+
+    const absolute = resolve(getWorkingDir(), directive.rawPath);
+    const canonical = await canonicalize(absolute);
+
+    if (!roots.some((root) => isInside(root, canonical))) {
+      rejections.push(
+        `${directive.rawPath}：路径不在当前工作目录或系统临时目录之下，已拒绝`,
+      );
+      continue;
+    }
+
+    const st = await stat(canonical).catch(() => null);
+    if (!st) {
+      rejections.push(`${directive.rawPath}：文件不存在或不可读`);
+      continue;
+    }
+    if (!st.isFile()) {
+      rejections.push(`${directive.rawPath}：不是普通文件`);
+      continue;
+    }
+    if (st.size > MAX_IMAGE_BYTES) {
+      rejections.push(
+        `${directive.rawPath}：单图 ${(st.size / 1024 / 1024).toFixed(1)}MB 超过 ${MAX_IMAGE_BYTES / 1024 / 1024}MB 上限`,
+      );
+      continue;
+    }
+    if (totalBytes + st.size > maxTotalBytes) {
+      rejections.push(
+        `${directive.rawPath}：累计体积超过 ${maxTotalBytes / 1024 / 1024}MB 上限，已跳过`,
+      );
+      continue;
+    }
+
+    const mime = await sniffFileImageMime(canonical);
+    if (!mime) {
+      rejections.push(
+        `${directive.rawPath}：文件内容不是受支持的 JPEG/PNG/GIF/WEBP 图片，已跳过`,
+      );
+      continue;
+    }
+
+    totalBytes += st.size;
+    images.push({
+      source: canonical,
+      ...(directive.detail ? { detail: directive.detail } : {}),
+      ...(directive.maxLongSidePixel !== undefined
+        ? { maxLongSidePixel: directive.maxLongSidePixel }
+        : {}),
+    });
+  }
+
+  return { images, rejections };
+}
+
+/**
+ * 在接受 sentinel 时验魔数，不依赖扩展名。只读取头部，避免为拒绝一张大文件
+ * 再做一次完整读取。逐条返回 null，由调用方记录 rejection，不抛到整个回合。
+ */
+async function sniffFileImageMime(path: string): Promise<string | null> {
+  let handle;
+  try {
+    handle = await open(path, 'r');
+    const header = Buffer.alloc(16);
+    const { bytesRead } = await handle.read(header, 0, header.length, 0);
+    return sniffImageMime(header.subarray(0, bytesRead));
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+/**
+ * realpath 之后再比较 —— 否则一条指向 /etc 的软链就能绕过根目录白名单。
+ *
+ * 目标不存在时不能简单退回 `resolve()`：macOS 的 `os.tmpdir()` 是
+ * `/var/folders/…`（软链到 `/private/var/folders/…`），根目录已归一化而目标没有，
+ * 于是「临时目录下一个还没生成的文件」会被判成**越界**而不是**不存在** ——
+ * 报错指向错误的原因，脚本作者会去查权限而不是去查文件名。
+ * 因此回退到「归一化最近的存在祖先，再接回剩余段」。
+ */
+async function canonicalize(path: string): Promise<string> {
+  const absolute = resolve(path);
+  try {
+    return await realpath(absolute);
+  } catch {
+    const parent = dirname(absolute);
+    if (parent === absolute) return absolute; // 已到根，停止递归
+    return join(await canonicalize(parent), basename(absolute));
+  }
+}
+
+/**
+ * 根目录也必须 realpath：macOS 的 `os.tmpdir()` 返回 `/var/folders/...`，
+ * 而它其实是 `/private/var/folders/...` 的软链 —— 不归一化的话临时目录里的
+ * 图会被自己的边界检查误杀。
+ */
+async function canonicalRoots(roots: string[]): Promise<string[]> {
+  const out: string[] = [];
+  for (const root of roots) {
+    const canonical = await canonicalize(resolve(root));
+    if (!out.includes(canonical)) out.push(canonical);
+  }
+  return out;
+}
+
+/** target 是否落在 root 之内（含 root 自身）。判据实现见 `utils/pathContains.ts`（全仓唯一一份）。 */
+const isInside = pathContains;

package/src/tools/bash/bash.js

@@ -49,8 +49,15 @@ import { sanitizeCredentialEnv } from '../../config/configService.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { killTree } from '../shared/killTree.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
+import { MAX_ATTACH_IMAGES, extractAttachImageDirectives, resolveAttachImages, } from './attachImage.js';
 import { interpretCommandResult } from './semantics.js';
 import { scanDestructiveCommand } from './warnings.js';
+import { requestUserChoice } from '../../askBridge.js';
+import { classifyCommand } from '../../irreversible/rules.js';
+import { startBackgroundTask } from '../tasks/backgroundTaskService.js';
+import { processExecutionMetadata } from '../tasks/processEvidence.js';
+import { permanentDeleteReason } from '../shared/permanentDeleteGuard.js';
+import { ToolOutputStore } from '../shared/toolOutputStore.js';
 // ---------------- 0. 常量 ----------------
 const DEFAULT_TIMEOUT_MS = 120_000; // 2 min
 const MAX_TIMEOUT_MS = 600_000; // 10 min
@@ -250,6 +257,7 @@ const inputSchema = z.object({
         .string()
         .optional()
         .describe('用一句话主动语态描述命令做什么（5-10 词），如 "List files in current directory"'),
+    run_in_background: z.boolean().optional().describe('长时间构建、测试或开发服务器设为 true；用 TaskOutput 获取增量输出、TaskStop 停止'),
 });
 // ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
 const parameters = toToolParameters(inputSchema);
@@ -290,6 +298,11 @@ While the Bash tool can do similar things, it's better to use the built-in tools
   - Never skip hooks (--no-verify) or bypass signing (--no-gpg-sign, -c commit.gpgsign=false) unless the user has explicitly asked for it. If a hook fails, investigate and fix the underlying issue.
  - Avoid unnecessary \`sleep\` commands; do not retry failing commands in a sleep loop — diagnose the root cause.
 
+# Viewing images
+Read cannot open images. To look at one (screenshot, chart, photo), print a line by itself:
+\`<<<ATTACH_IMAGE:/abs/path.png>>>\` — optionally \`|detail=low\` (cheap overview) and \`|maxLongSide=960\`.
+The image is attached for you to see and the line is stripped from the output. Up to ${MAX_ATTACH_IMAGES} per call; the file must live under the working directory or the system temp directory.
+
 # Exit code semantics
 Some commands return non-zero exit codes for informational (non-error) reasons. Bash recognizes these and reports them as success (ok=true) — do NOT retry just because exit code is 1:
  - \`grep\` / \`rg\` exit 1 → no match found (not an error)
@@ -325,7 +338,7 @@ No bash found on this Windows machine: commands run in cmd.exe (UTF-8 enforced).
  - Use \`dir\` / \`copy\` / \`del\` / \`type\` instead of \`ls\` / \`cp\` / \`rm\` / \`cat\`
 \`&&\` and \`;\`-style chaining: \`&&\` works in cmd; \`;\` does not (use \`&\`).`}`;
 // ---------------- 4. call() —— 真正干活 ----------------
-async function call(input, signal) {
+async function call(input, signal, context) {
     const command = input.command;
     const timeoutMs = Math.min(input.timeout ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
     // 4a. 安全黑名单（命中即拒）
@@ -336,15 +349,81 @@ async function call(input, signal) {
             error: `安全检查拒绝执行：${forbiddenReason}\n命令：${command}`,
         };
     }
+    const permanentDelete = permanentDeleteReason(command, 'bash');
+    if (permanentDelete)
+        return { ok: false, error: `永久删除检查拒绝执行：${permanentDelete}\n命令：${command}` };
+    // 4a-1. 不可逆动作闸门：毁掉「最后一份副本」的命令要**停下来问人**。
+    //
+    // 与上面黑名单的分工：黑名单是「灾难且无正当用途」→ 直接拒；这里是
+    // 「不可逆但有正当用途」（force push / 删库 / 毁 reflog）→ 问一句。
+    // 判据与规则表都在内核 `src/irreversible/rules.ts`，与 ComputerUse 共用。
+    //
+    // ★ 选项顺序不能改：askBridge 在**没有交互宿主**时（`-p`、cron、子 agent）
+    //   自动选第一项。所以第一项必须是「取消」——无人可问时 fail-closed。
+    const irreversible = classifyCommand(command);
+    if (irreversible) {
+        const [answer] = await requestUserChoice([
+            {
+                question: `这条命令不可逆：${irreversible.why}。\n\n命令：${command}\n\n确认执行吗？`,
+                header: '不可逆操作',
+                options: [
+                    { label: '取消，不执行 (推荐)', description: '放弃这一步，请 AI 换个可回滚的做法' },
+                    { label: '我已确认后果，执行', description: '我清楚这一步做完找不回来' },
+                ],
+            },
+        ], signal);
+        const approved = answer?.selected?.[0]?.includes('执行') === true
+            && answer.selected[0]?.includes('取消') !== true;
+        if (!approved) {
+            return {
+                ok: false,
+                // 明确要求模型**停下**而不是改写命令绕过去。没有这句，模型收到拒绝后
+                // 极可能把 `--force` 换成 `-f`、把 `push --force` 换成 `push origin +main`
+                // 再试一次 —— 那既绕过了闸门，也不是用户想要的。
+                error: `已被用户/策略拒绝执行（不可逆操作：${irreversible.why}）。\n` +
+                    `命令：${command}\n\n` +
+                    `请**不要**改写命令重试（换 -f、换 +refspec、拆成多条都算绕过）。` +
+                    `改用可回滚的做法，或直接把这一步交还给用户手动执行。`,
+            };
+        }
+    }
     // 4a-2. 破坏性命令告警扫描（仅警告，不阻塞）
     //       命中后把警告挂到结果输出顶部，让模型/用户看见苗头。
     const destructiveWarning = scanDestructiveCommand(command);
+    if (input.run_in_background) {
+        try {
+            const cwd = context?.cwd ?? getWorkingDir();
+            const task = await startBackgroundTask(WIN_BASH
+                ? { command, executable: WIN_BASH, args: ['-c', command], cwd, env: sanitizedChildEnv(), sessionId: context?.sessionId, workspaceId: context?.workspaceId, shellKind: 'bash' }
+                : {
+                    command: process.platform === 'win32' ? `chcp 65001 >nul & ${command}` : command,
+                    cwd,
+                    env: sanitizedChildEnv(),
+                    shell: true,
+                    sessionId: context?.sessionId,
+                    workspaceId: context?.workspaceId,
+                    shellKind: 'bash',
+                }, context?.sessionState?.backgroundTasks);
+            return {
+                ok: true,
+                content: `${destructiveWarning ? `⚠️ 警告: ${destructiveWarning}\n` : ''}后台任务已启动。task_id=${task.id.replace(/^proc_/, '')}\nprocess_id=${task.id}\nlog=${task.logPath}\n使用 TaskOutput 增量读取输出，TaskStop 停止进程。`,
+                metadata: processExecutionMetadata({ shell: 'bash', mode: 'background', command, status: 'started', taskId: task.id }),
+            };
+        }
+        catch (error) {
+            return { ok: false, error: `后台命令启动失败：${error.message}` };
+        }
+    }
     // 4b. spawn —— 平台分派（见 0b 探测注释）：
     //     Unix:               /bin/sh -c <command>（shell:true）
     //     Windows + Git Bash: bash.exe -c <command>（POSIX 语法成立）
     //     Windows 无 bash:    cmd.exe，命令前缀 chcp 65001 强制 UTF-8 输出
     let stdout = '';
     let stderr = '';
+    const outputStore = new ToolOutputStore({
+        workspaceId: context?.workspaceId,
+        sessionId: context?.sessionId,
+    });
     let exitCode = null;
     let timedOut = false;
     let killedBySignal = false;
@@ -359,7 +438,7 @@ async function call(input, signal) {
     try {
         await new Promise((resolveP, rejectP) => {
             const spawnOpts = {
-                cwd: getWorkingDir(),
+                cwd: context?.cwd ?? getWorkingDir(),
                 env: sanitizedChildEnv(),
                 windowsHide: true,
                 // POSIX：detached 自成进程组，中断时 killTree 的 kill(-pid) 才能掀整组；win32 不 detached（taskkill /T 掀树）。
@@ -387,14 +466,16 @@ async function call(input, signal) {
             child.stdout?.setEncoding('utf8');
             child.stderr?.setEncoding('utf8');
             child.stdout?.on('data', (chunk) => {
-                // G1：即时封顶，防止狂输出命令在最终截断前撑爆内存（OOM）。不强行 kill，
-                // 让命令自己跑完或被 timeout 收走；超出上限的部分直接丢弃，最终仍按上限截断展示。
-                if (stdout.length < MAX_STREAM_BUFFER_CHARS)
-                    stdout += chunk;
+                if (!outputStore.append('stdout', chunk)) {
+                    child.stdout?.pause();
+                    outputStore.onDrain(() => child.stdout?.resume());
+                }
             });
             child.stderr?.on('data', (chunk) => {
-                if (stderr.length < MAX_STREAM_BUFFER_CHARS)
-                    stderr += chunk;
+                if (!outputStore.append('stderr', chunk)) {
+                    child.stderr?.pause();
+                    outputStore.onDrain(() => child.stderr?.resume());
+                }
             });
             child.on('error', (e) => {
                 ac.signal.removeEventListener('abort', onKill);
@@ -413,18 +494,36 @@ async function call(input, signal) {
         return {
             ok: false,
             error: `执行命令失败：${e.message}\n命令：${command}`,
+            metadata: processExecutionMetadata({ shell: 'bash', mode: 'foreground', command, status: 'failed', exitCode: null }),
         };
     }
     finally {
         clearTimeout(timer);
         signal?.removeEventListener('abort', onAbort);
     }
+    const storedOutput = await outputStore.finish();
+    stdout = storedOutput.stdout;
+    stderr = storedOutput.stderr;
+    // 4b-2. ATTACH_IMAGE sentinel：脚本可以打一行 `<<<ATTACH_IMAGE:path>>>` 让模型亲眼看图。
+    //       协议行**从 content 剥掉**（那是给宿主看的，不是给模型读的噪声）；被拒的条目
+    //       如实写进输出（静默丢弃会让脚本作者以为图发出去了，无从 debug）。
+    //       `ToolResult` 的成功与失败分支都能带 visionImages，所以脚本**不必**为了
+    //       附图而假装成功——非零退出码照样能把图带给模型。
+    const attach = extractAttachImageDirectives(stdout);
+    stdout = attach.text;
+    const { images: visionImages, rejections: attachRejections } = await resolveAttachImages(attach.directives);
     // 4c. 拼输出
     const parts = [];
     if (stdout)
         parts.push(`<stdout>\n${stdout.replace(/\s+$/, '')}\n</stdout>`);
     if (stderr)
         parts.push(`<stderr>\n${stderr.replace(/\s+$/, '')}\n</stderr>`);
+    if (visionImages.length > 0) {
+        parts.push(`[已附加 ${visionImages.length} 张图片供你查看]`);
+    }
+    if (attachRejections.length > 0) {
+        parts.push(`[附图被拒绝]\n${attachRejections.map((r) => `- ${r}`).join('\n')}`);
+    }
     if (parts.length === 0)
         parts.push('<no output>');
     if (timedOut) {
@@ -434,16 +533,27 @@ async function call(input, signal) {
         parts.push(`\n[被信号中断]`);
     }
     parts.push(`\n[exit code: ${exitCode === null ? 'killed' : exitCode}]`);
+    const outputReference = storedOutput.path
+        ? `\n[完整输出: ${storedOutput.path}; bytes=${storedOutput.bytes}; sha256=${storedOutput.sha256}; complete=${storedOutput.complete}]`
+        : '';
     let combinedOutput = parts.join('\n');
     // 4d. 大小兜底
-    if (combinedOutput.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    if (combinedOutput.length + outputReference.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+        const suffix = `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，预览已截断)${outputReference}`;
         combinedOutput =
-            combinedOutput.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS) +
-                `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，已截断)`;
+            combinedOutput.slice(0, Math.max(0, DEFAULT_MAX_RESULT_SIZE_CHARS - suffix.length)) + suffix;
     }
+    else
+        combinedOutput += outputReference;
     // 4e. 中断 / 超时仍然算硬失败
+    //     失败也带上已解析的附图：脚本挂掉前截的那张诊断图正是最该看的。
     if (timedOut || killedBySignal) {
-        return { ok: false, error: combinedOutput };
+        return {
+            ok: false,
+            error: combinedOutput,
+            metadata: processExecutionMetadata({ shell: 'bash', mode: 'foreground', command, status: 'failed', exitCode }),
+            ...(visionImages.length > 0 ? { visionImages } : {}),
+        };
     }
     // 4f. 语义化退出码判定
     //     交给 semantics 模块：grep/rg/find/diff/test 有"信息性退出码"，
@@ -458,9 +568,16 @@ async function call(input, signal) {
             ok: false,
             error: `命令失败 (exit ${exitCode}): ${stderr || stdout || semantic.message || ''}`.trim() +
                 `\n\n${finalContent}`,
+            metadata: processExecutionMetadata({ shell: 'bash', mode: 'foreground', command, status: 'failed', exitCode }),
+            ...(visionImages.length > 0 ? { visionImages } : {}),
         };
     }
-    return { ok: true, content: finalContent };
+    return {
+        ok: true,
+        content: finalContent,
+        metadata: processExecutionMetadata({ shell: 'bash', mode: 'foreground', command, status: 'completed', exitCode }),
+        ...(visionImages.length > 0 ? { visionImages } : {}),
+    };
 }
 // ---------------- 5. 导出 ----------------
 export const bashTool = {
@@ -472,5 +589,6 @@ export const bashTool = {
     isConcurrencySafe: false, // 默认按"会改状态"算；保守不并发
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'block',
-    call,
+    call: (input, signal) => call(input, signal),
+    callWithContext: (input, signal, context) => call(input, signal, context),
 };