minimal-agent 0.10.0 → 0.12.0

package/src/tools/bash/bash.ts

@@ -0,0 +1,642 @@
+/**
+ * ============================================================
+ *  src/tools/bash.ts —— Bash 工具（万能命令兜底）
+ * ------------------------------------------------------------
+ *  对应 kakadeai 主仓库的 BashTool。
+ *  这是 minimal-agent 的"瑞士军刀" —— 当 Read/Edit/Write/Glob/Grep
+ *  搞不定时（rm 文件、chmod、git、npm/curl、跑测试...），就用它。
+ *
+ *  设计原则（重要）：
+ *
+ *  1. 优先用专用工具，Bash 只做兜底
+ *     - 读文件 → Read（不要 cat/head/tail）
+ *     - 写文件 → Write（不要 echo > / cat <<EOF）
+ *     - 改文件 → Edit（不要 sed/awk）
+ *     - 列文件 → Glob（不要 find/ls）
+ *     - 搜内容 → Grep（不要 grep/rg）
+ *     这条放进 description 里反复强调，让模型自觉。
+ *
+ *  2. 安全黑名单：拦截灾难性命令
+ *     - rm -rf / 、 rm -rf $HOME、 rm -rf ~
+ *     - mkfs / format c: / dd if=...of=/dev/sd*
+ *     - shutdown / reboot / halt / poweroff
+ *     - fork bomb :(){ :|:& };:
+ *     - curl ... | sh / wget ... | bash （管道到 shell）
+ *     不可绕过：在 call() 入口正则匹配，命中直接拒绝。
+ *     注意：黑名单是兜底，不是真正的沙盒；模型规规矩矩工作时不会误伤。
+ *
+ *  3. 超时保护：默认 120s，可显式设到最多 600s（10 分钟）
+ *     - 防止跑死的命令吃光会话；
+ *     - AbortSignal + timer 双保险。
+ *
+ *  4. 跨平台：
+ *     - 用 spawn({ shell: true })，让平台自己挑 shell
+ *       （Unix → /bin/sh -c，Windows → cmd.exe /d /s /c）
+ *     - 对模型透明：在 prompt 里说"假定 bash 语法"，
+ *       Windows 用户可能要自行调整跨平台命令（这是 minimal 版本，不做转译）
+ *
+ *  5. 输出兜底：
+ *     - stdout / stderr / exit code 一起返回（结构化文本）
+ *     - 超过 30K 字符截断，避免把 npm install 的 200K 日志灌进上下文
+ * ============================================================
+ */
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+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
+
+// ---------------- 0b. Windows shell 探测（模块加载时一次性） ----------------
+//
+// 根因（2026-06-12 实跑事故）：本工具 description 宣称 bash，但 win32 下
+// spawn({shell:true}) 实际是 cmd.exe —— 模型写的 `mkdir -p doc/scripts`（完全正确的
+// bash 语法）被 cmd 直接报语法错误；且中文 Windows 下 cmd 错误输出是 GBK 编码、
+// 被 setEncoding('utf8') 解码成乱码，模型既看不懂错误也换不对路，瞎试几轮后停摆，
+// 工作流执行步因此在第一条命令上整体卡死。
+//
+// 对策（三层）：
+//   ① 优先探测真 bash（Git Bash）——POSIX 语法直接成立，description 不再撒谎；
+//      排除 System32\bash.exe（WSL：跑在 Linux 环境，cwd/路径语义完全不同，不可用）。
+//   ② 找不到才回落 cmd，命令前缀 `chcp 65001 >nul & ` 强制 UTF-8 输出（根治乱码）。
+//   ③ description 运行时声明实际 shell（见下），模型按真实语法写命令。
+// 可用 MINIMAL_AGENT_BASH_PATH 显式指定（绿色版 U 盘机器上 Git 安装位置不可预知）。
+function detectWindowsBash(): string | null {
+  if (process.platform !== 'win32') return null;
+  const explicit = process.env.MINIMAL_AGENT_BASH_PATH;
+  if (explicit && existsSync(explicit)) return explicit;
+  const pf = process.env.ProgramFiles ?? 'C:\\Program Files';
+  const pf86 = process.env['ProgramFiles(x86)'] ?? 'C:\\Program Files (x86)';
+  const local = process.env.LOCALAPPDATA ?? '';
+  const candidates = [
+    join(pf, 'Git', 'bin', 'bash.exe'),
+    join(pf, 'Git', 'usr', 'bin', 'bash.exe'),
+    join(pf86, 'Git', 'bin', 'bash.exe'),
+    local ? join(local, 'Programs', 'Git', 'bin', 'bash.exe') : '',
+  ].filter(Boolean);
+  for (const c of candidates) {
+    if (existsSync(c)) return c;
+  }
+  // PATH 兜底扫描（跳过 System32 的 WSL bash）
+  for (const dir of (process.env.PATH ?? '').split(';')) {
+    if (!dir || /\\system32\\?/i.test(dir)) continue;
+    const p = join(dir, 'bash.exe');
+    if (existsSync(p)) return p;
+  }
+  return null;
+}
+
+const WIN_BASH = detectWindowsBash();
+
+/**
+ * G1：stdout / stderr 即时缓冲上限（各自）。命令狂输出（如 cat 大文件 / yes）时，
+ * 在最终统一截断之前先把内存封顶，防 OOM。取最终展示截断阈值的 2 倍 —— 正常输出不受影响，
+ * 超大输出也只占有限内存（最终仍按 DEFAULT_MAX_RESULT_SIZE_CHARS 截断展示）。
+ */
+const MAX_STREAM_BUFFER_CHARS = DEFAULT_MAX_RESULT_SIZE_CHARS * 2;
+
+/**
+ * 灾难性命令黑名单。
+ * 命中任意一条就直接拒绝执行 —— 这层是"防猪队友"而不是真沙盒。
+ *
+ * 选词依据（每条注释解释为啥要拦）：
+ * - 历史上"误删生产/格盘/锁机"的真实事故都对应一类模式
+ * - 工程协作里这些命令几乎不会被合法用到（如要用，肯定是用户在终端自己手敲）
+ *
+ * 工具仅是"模型可调用的能力"，模型规规矩矩地写代码、跑测试时永远不会触到这些。
+ */
+const FORBIDDEN_PATTERNS: Array<{ pattern: RegExp; reason: string }> = [
+  // ---- rm -rf / 及变体 ----
+  // 经典："rm -rf /"、"rm -rf /*"、"rm -fr /usr"、"rm -rf $HOME"、"rm -rf ~"
+  // 也覆盖 sudo rm -rf /
+  {
+    pattern: /\brm\s+(?:-[a-zA-Z]*[rRf][a-zA-Z]*\s+)+(?:\/+\*?|\$HOME|~)(?:\s|$)/,
+    reason: '禁止递归删除根目录或家目录（rm -rf / 类）',
+  },
+  // 拦截 "rm -rf <绝对路径>" 中目标是关键系统目录的情况（防误伤其它正常 rm -rf ./tmp）
+  {
+    pattern: /\brm\s+(?:-[a-zA-Z]*[rRf][a-zA-Z]*\s+)+(?:\/etc|\/usr|\/bin|\/sbin|\/var|\/boot|\/lib|\/System|\/Windows|\/Users|\/home)(?:\/|\s|$)/,
+    reason: '禁止递归删除系统关键目录',
+  },
+
+  // ---- 格盘 / 改写裸设备 ----
+  {
+    pattern: /\bmkfs(?:\.[a-z0-9]+)?\b/i,
+    reason: '禁止格式化文件系统（mkfs）',
+  },
+  {
+    // 末尾不能用 \b：盘符 "C:" 后是非 word char，\b 匹配不到。
+    // 改成"盘符后跟空白/反斜杠/结尾"。
+    pattern: /\bformat\s+[A-Za-z]:(?=\s|\\|$)/i,
+    reason: '禁止 Windows 格盘命令（format X:）',
+  },
+  {
+    pattern: /\bdd\s+[^|;&]*\bof=\/dev\/(?:sd[a-z]|nvme|disk|hd[a-z]|mmcblk)/i,
+    reason: '禁止 dd 写入裸磁盘设备',
+  },
+  {
+    pattern: />\s*\/dev\/(?:sd[a-z]|nvme|disk|hd[a-z]|mmcblk)/i,
+    reason: '禁止重定向到裸磁盘设备',
+  },
+
+  // ---- 关机 / 重启 ----
+  // 只匹配「命令位置」的关机词：串首 / 换行 / ; & | ` ( { / $( / sudo·doas·exec·nohup / systemctl 之后。
+  // 事故（2026-07-02）：此前 /\b(?:shutdown|…)\b/ 对整段命令裸词扫描（注释也算），
+  // ppt.yaml stage_export 的 bash 注释「硬门 halt」被误杀 → 整步执行前被拒 →
+  // onError:halt → 确定性死端（resume 原样命令原样再拒，永久卡死）。
+  // "halt" 是工作流引擎自身词汇（onError: halt），注释/echo 文案里出现属正常写作。
+  // 已知窄化（防猪队友层可接受）：env/timeout 等间接调用不再拦；注释里 ASCII "; halt" 仍会误伤
+  // （workflows 全库有 bashBlacklist.sweep.test.ts 兜底扫描）。
+  {
+    pattern: /(?:^|[\n;&|`({]|\$\(|\b(?:sudo|doas|exec|nohup)\s+|\bsystemctl\s+)\s*(?:shutdown|reboot|halt|poweroff)\b/i,
+    reason: '禁止关机/重启命令',
+  },
+  {
+    pattern: /\binit\s+[06]\b/,
+    reason: '禁止 init 0/6（关机/重启）',
+  },
+
+  // ---- Fork bomb ----
+  {
+    pattern: /:\s*\(\s*\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/,
+    reason: '禁止 fork bomb',
+  },
+
+  // ---- 管道到 shell（典型恶意安装脚本模式） ----
+  // curl ... | sh / wget ... | bash / curl ... | python
+  {
+    pattern: /\b(?:curl|wget|fetch)\b[^|;&]*\|\s*(?:sh|bash|zsh|dash|python|perl|ruby|node)\b/i,
+    reason: '禁止从网络管道到 shell 解释器（curl ... | sh 模式）',
+  },
+
+  // ---- chmod 整盘 777 ----
+  {
+    pattern: /\bchmod\s+(?:-R\s+)?[0-7]*7[0-7]*\s+\/(?:\s|$)/,
+    reason: '禁止对根目录 chmod 777',
+  },
+
+  // ---- Windows 系统级删除 ----
+  {
+    pattern: /\b(?:del|erase)\s+\/[sS][^|;&]*[A-Za-z]:\\?\s*$/,
+    reason: '禁止 Windows 全盘删除（del /s 根目录）',
+  },
+  {
+    pattern: /\brmdir\s+\/[sS][^|;&]*[A-Za-z]:\\?\s*$/,
+    reason: '禁止 Windows 全盘 rmdir',
+  },
+  {
+    pattern: /\bdiskpart\b/i,
+    reason: '禁止 diskpart',
+  },
+];
+
+/**
+ * 检查命令是否命中黑名单。
+ * 返回命中的原因字符串，否则返回 null。
+ */
+export function checkForbidden(command: string): string | null {
+  for (const { pattern, reason } of FORBIDDEN_PATTERNS) {
+    if (pattern.test(command)) return reason;
+  }
+  return null;
+}
+
+/**
+ * 子进程环境变量：从 process.env 复制后**剥离 agent 自己的密钥**
+ * （`MINIMAL_AGENT_*` / `TAVILY_*`）。
+ *
+ * 动机（安全）：main.tsx 启动时会把 saved config 里的 key 注入 process.env。
+ * 若原样把 process.env 透传给 Bash 子进程，模型只要跑 `echo $MINIMAL_AGENT_API_KEY`
+ * 就能把 key（绿色版里是卖家预置的）读进 tool result、回传 LLM、甚至打到 -p stdout。
+ * 这些 env 是 agent 自身配置，子进程命令并不需要 —— 直接删掉，最小化泄露面。
+ * 其余变量（PATH / HOME / 用户自己 export 的）照常透传。
+ *
+ * 导出供测试断言。
+ */
+export function sanitizedChildEnv(
+  base: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  const env = sanitizeCredentialEnv(base);
+  for (const key of Object.keys(env)) {
+    if (key.startsWith('MINIMAL_AGENT_') || key.startsWith('TAVILY_')) {
+      delete env[key];
+    }
+  }
+  // 保证子进程里的 Python 用 UTF-8 解码（PEP 540 UTF-8 Mode）。否则中文 Windows 上
+  // locale.getpreferredencoding() = cp936/GBK，`subprocess.run(text=True)` / `open()`
+  // 默认就用 GBK 解码子进程的 UTF-8 输出 → 撞非法字节必崩（曾致 ppt 工作流 build_probe
+  // `UnicodeDecodeError: 'gbk' codec can't decode byte 0xa8` 直接 halt 整条工作流）。
+  // 这是 Bash 工具「保证 UTF-8 世界」既有立场（cmd 回落已 chcp 65001）的加性延伸：
+  // 一处覆盖所有 bash 步 spawn 的 python（内联 heredoc + 技能脚本），现在与将来。
+  // 跨平台安全：类 Unix 本就 UTF-8 → no-op；顺带治 POSIX/C locale(ASCII) 同类坑。
+  env.PYTHONUTF8 = '1';
+  env.PYTHONIOENCODING = 'utf-8';
+  return env;
+}
+
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+  command: z
+    .string()
+    .min(1, '必须提供 command')
+    .describe('要执行的 shell 命令（假定 bash 语法）'),
+  timeout: z
+    .number()
+    .int()
+    .positive()
+    .max(MAX_TIMEOUT_MS)
+    .optional()
+    .describe(`超时（毫秒），最多 ${MAX_TIMEOUT_MS}（${MAX_TIMEOUT_MS / 60_000} 分钟）；不填默认 ${DEFAULT_TIMEOUT_MS}`),
+  description: z
+    .string()
+    .optional()
+    .describe('用一句话主动语态描述命令做什么（5-10 词），如 "List files in current directory"'),
+  run_in_background: z.boolean().optional().describe('长时间构建、测试或开发服务器设为 true；用 TaskOutput 获取增量输出、TaskStop 停止'),
+});
+type BashInput = z.infer<typeof inputSchema>;
+
+// ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
+const parameters = toToolParameters(inputSchema);
+
+// ---------------- 3. Description（给 LLM 看的工具说明） ----------------
+//
+// 提炼自 kakadeai/tools/BashTool/prompt.ts 的 getSimplePrompt()。
+// 核心逻辑：
+//   - 先点明"专用工具优先"的原则，把每类操作映射到对应工具
+//   - 再列 Bash 自身的使用规范（绝对路径 / 不 cd / 超时 / 多命令并行...）
+//   - 最后强调安全黑名单（让模型知道哪些命令会被拒，避免反复试）
+const description = `Executes a given bash command and returns its output.
+
+The working directory persists between commands, but shell state does not. The shell environment is initialized from the user's profile.
+
+IMPORTANT: Avoid using this tool to run \`find\`, \`grep\`, \`cat\`, \`head\`, \`tail\`, \`sed\`, \`awk\`, or \`echo\` commands, unless explicitly instructed or after you have verified that a dedicated tool cannot accomplish your task. Instead, use the appropriate dedicated tool as this will provide a much better experience for the user:
+
+ - File search: Use Glob (NOT find or ls)
+ - Content search: Use Grep (NOT grep or rg)
+ - Read files: Use Read (NOT cat/head/tail)
+ - Edit files: Use Edit (NOT sed/awk)
+ - Write files: Use Write (NOT echo >/cat <<EOF)
+ - Communication: Output text directly (NOT echo/printf)
+While the Bash tool can do similar things, it's better to use the built-in tools as they provide a better user experience and make it easier to review tool calls and give permission.
+
+# Instructions
+ - If your command will create new directories or files, first use this tool to run \`ls\` to verify the parent directory exists and is the correct location.
+ - Always quote file paths that contain spaces with double quotes in your command (e.g., cd "path with spaces/file.txt").
+ - Try to maintain your current working directory throughout the session by using absolute paths and avoiding usage of \`cd\`. You may use \`cd\` if the User explicitly requests it.
+ - You may specify an optional timeout in milliseconds (up to ${MAX_TIMEOUT_MS}ms / ${MAX_TIMEOUT_MS / 60_000} minutes). By default, your command will timeout after ${DEFAULT_TIMEOUT_MS}ms (${DEFAULT_TIMEOUT_MS / 60_000} minutes).
+ - When issuing multiple commands:
+  - If the commands are independent and can run in parallel, make multiple Bash tool calls in a single message.
+  - If the commands depend on each other and must run sequentially, use a single Bash call with '&&' to chain them.
+  - Use ';' only when you need to run commands sequentially but don't care if earlier commands fail.
+  - DO NOT use newlines to separate commands (newlines are ok in quoted strings and here-strings).
+ - For git commands:
+  - Prefer to create a new commit rather than amending an existing commit.
+  - Before running destructive operations (e.g., git reset --hard, git push --force, git checkout --), consider whether there is a safer alternative that achieves the same goal. Only use destructive operations when they are truly the best approach.
+  - 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)
+ - \`find\` exit 1 → some directories inaccessible (non-fatal, partial results still returned)
+ - \`diff\` / \`cmp\` exit 1 → files differ (informational, not an error)
+ - \`test\` / \`[\` exit 1 → condition is false (the answer to a question, not a failure)
+Only exit codes ≥ 2 from these commands indicate a real failure. For all other commands, non-zero exit codes are treated as failures normally.
+
+# Safety
+The following command patterns are blocked at the tool level and will fail before execution (no need to try them):
+ - \`rm -rf /\` and variants targeting root, $HOME, ~, or system directories (/etc, /usr, /bin, /Windows, /Users, /home, ...)
+ - Filesystem destruction: \`mkfs\`, \`format X:\`, \`dd of=/dev/sdX\`, redirects to raw block devices
+ - Power management: \`shutdown\`, \`reboot\`, \`halt\`, \`poweroff\`, \`init 0/6\`
+ - Fork bombs
+ - Pipe-to-shell from network: \`curl ... | sh\`, \`wget ... | bash\`, etc.
+ - \`chmod 777 /\`, Windows full-disk \`del /s\` / \`rmdir /s\`, \`diskpart\`
+
+If you have a legitimate use case that requires one of the above patterns, ask the user to run the command themselves in their terminal — do not try to bypass the check.
+
+Separately, Bash scans for common destructive-but-recoverable patterns (\`git reset --hard\`, \`git push -f\` / \`--force\` / \`--force-with-lease\`, \`git checkout .\`, \`git restore .\`, \`git clean -f\`, \`git stash drop/clear\`, \`git branch -D\`, \`git commit --amend\` / \`--no-verify\`, \`rm -rf <path>\`, \`DROP TABLE\`, \`TRUNCATE\`, \`DELETE FROM\`, \`kubectl delete\`, \`terraform destroy\`, etc.) and prepends a \`⚠️ 警告:\` line to the output. These commands are NOT blocked — the warning is informational. Treat it as a signal to double-check intent and surface the warning to the user when relevant.${
+  process.platform !== 'win32'
+    ? ''
+    : WIN_BASH
+      ? `
+
+# Shell (this machine)
+Commands run in a real bash (Git Bash at ${WIN_BASH}). POSIX syntax works: \`mkdir -p\`, \`$VAR\`, \`$(...)\`, \`&&\`, \`[ -f x ]\` are all fine. Note the working directory is a Windows path — both \`D:\\path\` and \`/d/path\` forms work in this bash.`
+      : `
+
+# Shell (this machine) — IMPORTANT
+No bash found on this Windows machine: commands run in cmd.exe (UTF-8 enforced). POSIX syntax does NOT work here:
+ - NO \`mkdir -p\` — cmd's \`mkdir a\\b\\c\` creates intermediate directories by default; better: the Write tool auto-creates parent directories
+ - NO \`$VAR\` / \`$(...)\` / \`[ -f x ]\` / \`export\` — use \`%VAR%\`, \`if exist\`, \`set\`
+ - 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: BashInput, signal?: AbortSignal, context?: ToolCallContext): Promise<ToolResult> {
+  const command = input.command;
+  const timeoutMs = Math.min(input.timeout ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+
+  // 4a. 安全黑名单（命中即拒）
+  const forbiddenReason = checkForbidden(command);
+  if (forbiddenReason) {
+    return {
+      ok: false,
+      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' as const }
+          : {
+              command: process.platform === 'win32' ? `chcp 65001 >nul & ${command}` : command,
+              cwd,
+              env: sanitizedChildEnv(),
+              shell: true,
+              sessionId: context?.sessionId,
+              workspaceId: context?.workspaceId,
+              shellKind: 'bash' as const,
+            },
+        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 as 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: number | null = null;
+  let timedOut = false;
+  let killedBySignal = false;
+
+  // 用 AbortController 把外部 signal + 我们自己的 timeout 合并成一个
+  const ac = new AbortController();
+  const onAbort = () => ac.abort();
+  signal?.addEventListener('abort', onAbort, { once: true });
+  const timer = setTimeout(() => {
+    timedOut = true;
+    ac.abort();
+  }, timeoutMs);
+
+  try {
+    await new Promise<void>((resolveP, rejectP) => {
+      const spawnOpts = {
+        cwd: context?.cwd ?? getWorkingDir(),
+        env: sanitizedChildEnv(),
+        windowsHide: true,
+        // POSIX：detached 自成进程组，中断时 killTree 的 kill(-pid) 才能掀整组；win32 不 detached（taskkill /T 掀树）。
+        detached: process.platform !== 'win32',
+      };
+      const child = WIN_BASH
+        ? spawn(WIN_BASH, ['-c', command], spawnOpts)
+        : spawn(
+            process.platform === 'win32'
+              ? `chcp 65001 >nul & ${command}`
+              : command,
+            { ...spawnOpts, shell: true },
+          );
+
+      // 中断/超时收尾：杀**整棵进程树**（不是只杀直接 shell）。否则 win32 上 shell 被杀后，在飞的
+      // 孙进程（bun test / 构建 / 起服务…）变孤儿继续跑、还占着 stdout 管道让 'close' 永不触发 ——
+      // 表现为「点了停止、agent 停了、活儿还在后台跑」的"停不下来"（与 2026-07-02 生图事故同源）。
+      // 不再把 signal 交给 spawn 自己 kill（那只杀直接子进程，还会抢在 killTree 前把 shell 杀掉、
+      // 让 taskkill /T 够不到已成孤儿的孙进程）；改由这里统一 killTree + 立即 resolve，不空等 'close'。
+      const onKill = () => {
+        killedBySignal = true;
+        killTree(child);
+        resolveP();
+      };
+      if (ac.signal.aborted) onKill();
+      else ac.signal.addEventListener('abort', onKill, { once: true });
+
+      child.stdout?.setEncoding('utf8');
+      child.stderr?.setEncoding('utf8');
+      child.stdout?.on('data', (chunk) => {
+        if (!outputStore.append('stdout', chunk)) {
+          child.stdout?.pause();
+          outputStore.onDrain(() => child.stdout?.resume());
+        }
+      });
+      child.stderr?.on('data', (chunk) => {
+        if (!outputStore.append('stderr', chunk)) {
+          child.stderr?.pause();
+          outputStore.onDrain(() => child.stderr?.resume());
+        }
+      });
+      child.on('error', (e) => {
+        ac.signal.removeEventListener('abort', onKill);
+        rejectP(e);
+      });
+      child.on('close', (code, sig) => {
+        ac.signal.removeEventListener('abort', onKill);
+        exitCode = code;
+        if (sig) killedBySignal = true;
+        resolveP();
+      });
+    });
+  } catch (e) {
+    return {
+      ok: false,
+      error: `执行命令失败：${(e as Error).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: string[] = [];
+  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) {
+    parts.push(`\n[超时 ${timeoutMs}ms 后被中断]`);
+  } else if (killedBySignal && !timedOut) {
+    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 + outputReference.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
+    const suffix = `\n\n... (输出超过 ${DEFAULT_MAX_RESULT_SIZE_CHARS} 字符，预览已截断)${outputReference}`;
+    combinedOutput =
+      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,
+      metadata: processExecutionMetadata({ shell: 'bash', mode: 'foreground', command, status: 'failed', exitCode }),
+      ...(visionImages.length > 0 ? { visionImages } : {}),
+    };
+  }
+
+  // 4f. 语义化退出码判定
+  //     交给 semantics 模块：grep/rg/find/diff/test 有"信息性退出码"，
+  //     其它命令用默认语义（exitCode !== 0 即错）。
+  //     destructiveWarning 命中时把告警贴在输出头部，模型/用户都能看见。
+  const semantic = interpretCommandResult(
+    command,
+    exitCode ?? 0,
+    stdout,
+    stderr,
+  );
+  const finalContent = destructiveWarning
+    ? `⚠️ 警告: ${destructiveWarning}\n\n${combinedOutput}`
+    : combinedOutput;
+
+  if (semantic.isError) {
+    return {
+      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,
+    metadata: processExecutionMetadata({ shell: 'bash', mode: 'foreground', command, status: 'completed', exitCode }),
+    ...(visionImages.length > 0 ? { visionImages } : {}),
+  };
+}
+
+// ---------------- 5. 导出 ----------------
+export const bashTool: Tool<BashInput> = {
+  name: 'Bash',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: false,
+  isConcurrencySafe: false, // 默认按"会改状态"算；保守不并发
+  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  interruptBehavior: () => 'block',
+  call: (input, signal) => call(input, signal),
+  callWithContext: (input, signal, context) => call(input, signal, context),
+};