Shell 工具横评报告

Shell 工具是 agent 与宿主机之间权柄最大的接口。它同时是能力面（一切进程、文件、网络操作的入口）、 攻击面（提示注入可转化为任意代码执行）和体验面（超时、截断、后台化决定 agent 能否完成真实工程任务）。 8 个 harness 的源码显示，行业已经收敛出几组明确的设计张力：

张力一：隔离强度 vs 命令保真度

• OS 级沙箱（seatbelt / bwrap / landlock / Windows restricted token）把文件与网络边界交给内核，模型可以随便写 bash。
• 代价是平台分支复杂度、denial 判定启发式（codex 承认"没有完全确定的方法"，见 sandboxing/src/denial.rs）、以及沙箱内工具链缺失。
• 另一条路线完全不设 OS 沙箱（pi、goose、opencode），把边界收缩到"命令语义层"：静态分析命令 AST、逐段判定只读、危险模式硬拦截（mcode 的 permission 模块最完整）。

张力二：执行隔离 vs 状态连续性

• 每次调用起新进程（bash -lc <cmd>）是安全默认值：无残留状态、无跨调用污染。goose、ZCode、pi 默认采用。
• 真实任务需要状态：cwd、export、函数、后台服务。三种解法：
  1. shell snapshot 回放（codex）：捕获 aliases/functions/exports，注入每次新进程。隔离不破，状态延续有界。
  2. 持久 PTY 会话（dsh tool-bash-persistent）：每 agent 一个长驻终端，cwd/env 天然连续。风险是会话被 reset 前的一切都可被后续命令读取。
  3. 工具参数显式传递（opencode/gemini）：workdir 参数 + 后台进程表，把状态管理推给模型。

张力三：命令整体执行 vs 逐段语义分析

• bash -c 整串执行：零解析成本、语义 100% 保真。但权限判定只能看整串或首词。
• AST 拆分（opencode 自研 scanner、ZCode 用 unbash、mcode 用 bash-ast）：把 cat a && rm -rf / 拆成两段分别判定，只读段自动放行、写入段走审批。代价是解析器成为新的攻击面（别名、heredoc、命令替换、eval 都可能绕过解析）。
• 行业共识是"解析用于放行，不用于拦截"：解析不出确定语义（opencode 的 opaque、ZCode 的 hasParseErrors）时，回退到整体询问，绝不回退到整体放行。

张力四：审批摩擦 vs 自主性

• 逐次询问最安全，但 agent 每三步被打断一次，自主性归零。
• 收敛模式是三级：模式化只读自动放行（ZCode/mcode/opencode 的 readonly 判定）→ 会话级 allowlist（dsh 的 escalation、ZCode 的 alwaysAllowPatternSources）→ 全局模式切换（gemini plan/default/accepting_edits，dsh read-only/workspace-write/danger-full-access）。
• 关键细节：升级（escalation）必须带理由（dsh 强制 justification 非空句），且升级路径必须 fail-closed——沙箱不可用时前台命令直接抛错，不允许无沙箱降级执行（dsh bash-sandbox 的设计）。

张力五：输出保真 vs 上下文经济

• 截断上限收敛在 2000 行 / 50 KB（pi、opencode、goose 一致），完整输出落临时文件，向模型报告路径。
• 截断策略分头保留（ZCode 的 isModelContentBounded、goose 的 tail preview）与流式缓冲上限（gemini 16 MB）两派。
• 超时默认值 120–300 s；dsh 独有的 promoteOnTimeout（前台超时转后台而非杀死）代表"长任务不死"的设计取向。

3.1 codex（OpenAI，Rust）—— 进程池 + snapshot 的工业级方案

机制

• 入口是 unified_exec 工具族：exec_command、write_stdin、terminal_session。 参数包含 cmd / shell / login / tty / yield_time_ms(默认10s) / timeout_ms / max_output_tokens / sandbox_permissions / prefix_rule。
• 执行模型：每条命令 shell -lc "<cmd>" 新进程；但维护 ≤64 个交互进程池（MAX_UNIFIED_EXEC_PROCESSES）， 模型用 write_stdin 与进程交互，实现"伪持久会话"。
• 状态延续：shell snapshot 机制——首跑时捕获 aliases、functions、exported vars、shell 选项， 后续每次新进程执行前注入回放（shell-command/src/shell_snapshot.rs）。
• 沙箱：macOS seatbelt（.sbpl 策略文件）、Linux landlock+bwrap、Windows restricted token； 网络侧有 proxy + 按域名规则。沙箱拒绝后按策略去沙箱重试（不重复提示，靠缓存）。
• 审批：AskForApproval 四态（UnlessTrusted / OnRequest / Granular / Never）+ execpolicy 前缀规则 （PrefixPattern，支持 alt）+ 危险命令检测（rm -f、sudo 递归、env、trap、Windows 专属规则）+ Guardian LLM 审查。
• 命令解析：tree-sitter 把 bash 拆为 Read / ListFiles / Search / Unknown 四类， 用于遥测分类（read/list_files/search/unknown/mixed）与只读权限收窄；解析失败折叠为 Unknown。
• 输出：默认 10k tokens，硬上限 1 MiB。

设计影响面

• 进程池 + snapshot 兼顾隔离与连续，但实现成本最高（Rust、多平台沙箱、snapshot 凭证安全处理）。
• "沙箱拒绝→去沙箱重试"极大降低合法任务的摩擦，但依赖 denial 判定启发式——源码注释自承"没有完全确定的方法"。
• 对中型 harness 的可借鉴点：yield_time 前台让位 + write_stdin 轮询的模式，比"阻塞等待"对模型友好。

3.2 dsh（DeepSeek Harness，TypeScript）—— 能力接缝（seam）架构

机制

• Shell 是一个抽象服务（ShellExecutor）：调用方拿到进程句柄，前台/后台是调用方语义，不是进程属性。 同一句柄可被 result()（前台投影）或保留（后台 producer）。
• 一次性工具与持久工具是两个独立工具、两个独立接缝：tool-bash 注入 ['shell']（本执行器）， tool-bash-persistent 注入 ['terminals']（PTY 终端接缝）。两者互斥挂载，模型任一宿主只看到一个 shell 工具。
• 三套一次性执行器实现：bash-local（新进程/次，默认超时 120s/上限 600s，输出 64 KB + 64 MiB spill）、 bash-sandbox（包装同一 argv 过 ctx.sandbox）、tool-bash-persistent（每 agent 一个长驻 PTY，300s/命令，16k 字符截断，超时/退出即 reset）。
• 沙箱：SandboxMode 三档；平台 runner 链 Linux [bwrap, landlock] / macOS [seatbelt] / Windows [windows-acl]； 选链按平台优先、探测仲裁；不可用即 fail-closed（前台抛 SANDBOX_UNAVAILABLE）。
• 升级（escalation）：sandbox_permissions 必须配对非空 justification；经 ctx.approval 通道 fail-closed 审批； 升级词汇表 ['workspace-write','danger-full-access']；拒绝时给出同轮 escalation hint。
• 后台：job registry + run_in_background；promoteOnTimeout——前台命令超时后转后台而非杀死； onExpiry:'none'|'kill' 由调用方决定到期语义。
• 环境治理：凭证 scrub → 调用方 env → 托管 DSH_* 快照（类型化托管键，调用方无法覆盖）。

设计影响面

• seam 架构把"执行/沙箱/策略/审批"彻底解耦，可组合（无沙箱组合 = 本地执行器）；但抽象层数量多，认知成本高。
• XXX(stateful-shell) TODO 表明团队仍在权衡持久 shell 的工作流需求。
• 对中型 harness 的可借鉴点：前台投影 + 句柄保留的统一抽象；escalation 强制 justification 的审计价值。

3.3 gemini-cli（Google，TypeScript）—— 非活跃超时与模式化策略

机制

• ShellTool 基于 node-pty；参数 command / dir_path / is_background / delay_ms。
• 超时是非活跃超时（默认 300s）：任意输出事件重置计时器——长构建只要持续输出就不会被杀。
• 输出：直播缓冲 100k 字符；进程缓冲上限 16 MB，溢出从头截断并附 GEMINI_CLI_WARNING 提示。
• 后台：专属工具 list_background_processes 与 read_background_output；后台命令输出落 background-<pid>.log 文件；完成通知截断注入 5000 字符。
• 沙箱：三平台 manager（macOS sandbox-exec/seatbelt、Linux bwrap+seccomp BPF、Windows 编译 helper exe）； 策略来自 TOML（~/.gemini/policies/sandbox.toml），内置 plan/default/accepting_edits 三模式， 每模式含 network / readonly / approvedTools / allowOverrides。
• 命令安全：isDangerousCommand 覆盖 ln -s、rm -f、sudo 递归、find -exec、git config 覆盖全局、rg 危险参数。
• 远程内容包裹：命令输出若来自远程源，注入 wrapUntrusted 标记防注入。

设计影响面

• "非活跃超时"是对构建/测试类任务的友好设计，但牺牲了硬时限保证（失控进程可持续输出不被杀）。
• TOML 模式化策略把权限表达为数据，运维友好；但模式与工具语义耦合（accepting_edits 白名单 sed/awk/perl）。
• 对中型 harness 的可借鉴点：后台进程的"日志落盘 + 工具化读取"闭环。

3.4 opencode（SST，TypeScript/Effect）—— 自研 scanner + 规则集权限

机制

• Shell 工具参数 command / workdir / timeout(默认2min) / background；每次 create 起一个进程， 合并 stdout/stderr 写入输出文件，文件保留 7 天。
• 自研 ShellParse scanner（shell/parse.ts）：支持 posix/bash/powershell 三文法； 维护 ARITY 表（git:2, docker:2, npm run:3…）识别命令与子命令；提取 resource + save（重定向目标）与涉及目录； 无法分析时返回 opaque——直接报错，绝不降级放行。
• 权限：解析出的每个 resource 走 permission.assert；规则是按 action+resource 双通配符的规则集， 默认 ask；findLast 匹配实现"后配置覆盖先配置"。
• 后台：jobs 服务 + 完成自动发合成消息（含输出）；工具描述明确禁止轮询（"polling is not useful work"）。
• ShellSelect：按平台解析 shell（/etc/shells → Git Bash → pwsh → cmd）。
• 另有 daemon 化 PersistentPty 服务（持久终端 + handoff），但当前仅服务实验性终端 API，不进 shell 工具路径。
• 环境标记：AGENT=1 / OPENCODE=1 / OPENCODE_SESSION_ID。

设计影响面

• scanner 把权限粒度从"整条命令"推进到"命令 + 重定向目标 + 涉及目录"，是命令层权限的业界最细粒度。
• 代价：scanner 自身成为攻击面（heredoc、命令替换、eval、别名均可制造 opaque）；opencode 用"解析失败即整体询问"兜底。
• 对中型 harness 的可借鉴点：resource/save 双粒度权限模型；"禁止轮询"的提示词工程。

3.5 pi（earendil-works，TypeScript）—— 极简无沙箱 + 可扩展执行面

机制

• bash 工具参数极简：command / timeout(秒，无默认)。powershell 工具同构（加 UTF-8 输出前缀）。
• 执行：spawn(shell, args, command)，detached 进程树；超时/取消走 killProcessTree（先 SIGTERM 后升级）。
• 输出：2000 行 / 50 KB（DEFAULT_MAX_LINES/BYTES），尾部保留；完整输出落临时文件并把路径写进结果。
• 通用 execCommand：默认缓冲上限 min(256 MiB, 字符串上限)；超限即杀进程并把退出码改写为 1（截断绝不伪装成功）；SIGTERM→5s→SIGKILL。
• 无 OS 沙箱、无内建审批。BashOperations 接口允许宿主替换执行面（远程 SSH 即通过此实现）。
• codemode：QuickJS WASM 沙箱（worker 线程、256 MiB 堆上限、每次执行独立 worker、仅注入 tools）， 是 shell 之外的第二执行面——模型写 JS 调用工具而非直接写 bash。工具名"codemode：false"的标记说明其权限模型独立。
• 输出流处理有精细边界处理：跨块 ANSI 转义不完整序列、二进制清洗、UTF-8 跨块解码。

设计影响面

• 哲学是"宿主负责安全，工具负责能力"：把 BashOperations 做成接缝，本地极简、远程委派，沙箱策略外置。
• codemode 代表另一条路线——用能力受限的 DSL 替代 shell 完成工具编排，天然无注入面（无 Node/FS/网络）。
• 对中型 harness 的可借鉴点：截断改写退出码的诚实性设计；BashOperations 接缝。

3.6 mcode（minimax/mavis，TypeScript）—— 静态分析权限管线 + 可恢复删除

机制

• bash 工具参数 command / description / timeout / run_in_background；描述明确"优先专用工具、cd 不跨调用持久"。
• 三档超时：direct 前台（默认 120s/上限 300s）、managed 前台（soft-yield 60s 后给 task_id，总上限 3600s 含前台耗时）、显式后台（指定或 3600s）。
• 沙箱：SRT 运行时（seatbelt / Windows srt-win WFP / Linux bwrap+seccomp）；文件系统四模式 （read_only / workspace_write / delete_guard / full_access）；网络 deny/allow_all；凭证文件屏蔽。
• 静态分析权限管线（agent-modules/permission/src/tools/）：bash AST → 命令拆分 → heredoc 体剥离 → wrapper 展开 → fast-allow 首词白名单（~100 个只读/构建命令）→ slow-command 扫描 → 危险模式硬拒（curl 管道执行等）→ 命中即降级 ASK。
• 删除改路由：rm 经 mavis-trash -- sentinel 走可恢复删除（Windows 回收站/宿主回收站）； 禁止用绝对路径绕过；SIGKILL 级 kill -9 从 fast-allow 降级。
• 后台 bash 复用同一 pi bash 工具与同一环境消毒器——后台不是绕过边界的侧门。

设计影响面

• 权限判定完全在命令语义层完成，模型体验上"只读命令零打扰"；代价是庞大的静态分析代码面与持续的绕过对抗。
• delete_guard + 可恢复删除是数据安全与 agent 自主性的折中：允许删，但可撤销。
• 对中型 harness 的可借鉴点：heredoc 体剥离（防 heredoc 藏命令）、wrapper 展开（sudo/env/time 取真实命令）。

3.7 ZCode（闭源分发 + 开源 CLI 核心，TypeScript）—— 重权限、轻沙箱

机制

• Bash 工具经 ExecutionPort 抽象执行（node adapter 是参考实现）；参数 command / timeout / run_in_background / dangerouslyDisableSandbox。
• 超时：默认 120s / 上限 600s（环境变量可覆盖）；取消支持 best-effort 进程树清理。
• 命令解析：unbash AST；classifyCommand 输出遥测类别（test/package/git/build/search/network）； isRuntimeReadOnlyBashCommand 逐段判定只读（含 git 子命令语义、写入选项、重定向）——只读命令自动放行。
• 权限：工具声明 riskLevel:"high", needsApproval:true, denyPriority:"beforeAsk"； 命令注册表（HIGH_RISK_ROOT_COMMANDS: bash/chmod/dd/mkfs/rm…）+ wrapper 选项展开（sudo/env/time）+ docker 规则； prepareApproval 钩子——只能把 ask 收窄为 proceed，反向不允许；预览失败时 fail-open 为纯询问（不静默放行）。
• 后台：显式 run_in_background 与 auto_on_timeout（超时自动转后台；sleep 除外）；输出落盘 5 GiB 软上限。
• 输出：inline 上限 30 KB（头尾字符级保留，isModelContentBounded 保证模型侧有界）；落盘策略按前台/后台区分。
• OS 沙箱已撤除：ExecutionRequest.sandbox 字段保留但无消费方； 代码注释明确"准备阶段只剩 shell snapshot"（node-execution-adapter-run.ts:399）； dangerouslyDisableSandbox 仅影响遥测 sandboxed 标记。隔离责任转移到权限规则 + cwd 策略（decideBashCwdPolicy）。
• Shell 选择：$SHELL → 固定 posix 目录（/bin、/usr/bin…）→ Windows Git Bash 候选路径；shell snapshot 处理启动环境；默认 login shell（snapshot 存在时退化）。

设计影响面

• "撤除沙箱、强化权限规则"是一个明确的产品决策：在本机桌面场景下，内核级沙箱的兼容成本高于收益，权限层承担了全部边界。
• prepareApproval 单向收窄 + 预览失败 fail-open，是权限钩子设计的正确姿势（钩子不能制造权限，只能放弃预览）。
• 对中型 harness 的可借鉴点：auto_on_timeout 后台化；decideBashCwdPolicy 把 cwd 当策略面管理。

3.8 goose（Block，Rust）—— 最小内核 + 扩展注入

机制

• shell 是 developer 平台扩展的一个工具：参数 command / timeout_secs(默认300s)；描述由 shell 类型动态生成（cmd 时提示多行问题）。
• 执行：tokio::process::Command，shell -c；Linux 上 prctl(PR_SET_PDEATHSIG) 防孤儿进程。
• 输出：2000 行 / 50 KB 上限；超限落临时文件，预览取尾部 50 行 / 10 KB； truncate_preview_bytes 防 \r 进度条伪造无换行长行绕过预览上限。
• 进程退出后再 drain 500ms（OUTPUT_DRAIN_TIMEOUT）——兼容"后台化子进程继承 stdio"的场景，drain 失败仅标记 output_truncated。
• Flatpak 检测：自动改走 flatpak-spawn --host 并显式传递宿主 login PATH。
• ! 前缀 kickoff 消息直接作为 shell 命令执行（ops_bang_shell）——人类敲命令的快速通道。
• git 命令加固：safe.bareRepository=explicit + core.fsmonitor=false（防配置注入与 fsmonitor hook）。
• 无 OS 沙箱、无内建审批；边界依赖 MCP 宿主层与扩展配置。

设计影响面

• 最小内核 + 扩展注入的架构使 shell 工具零特化，但也意味着安全策略全部外推。
• \r 绕过预览的防御说明：截断实现必须假设"输出可能是对抗性的"。
• 对中型 harness 的可借鉴点：PDEATHSIG 防孤儿；git 加固参数。

3.9 Kiro —— 闭源，无源码可评

本仓库仅为 Kiro 的 issue 追踪与自动化脚本（label 分类、重复检测、stale 管理），不含 harness 源码。 官方资料称 Web 端在多仓库任务中使用 isolated cloud sandboxes（云端隔离沙箱）， IDE/CLI/Crew 共用"一个统一 agent harness"。设计细节无法从源码核验，本报告不对其内部机制做任何断言。

4.1 持久化 shell：三条路线的收益与风险

4.2 管道策略：整串执行 vs 逐段分析

"管道"在本报告含两层：shell 语法管道（|、&&、;）与数据的stdio流转。8 个 harness 对前者的处理分三档：

4.3 沙箱策略分级与撤除

值得注意的数据点：

• ZCode 的主动撤除（源码注释"沙箱撤除后"）说明：在单租户桌面场景，内核沙箱的平台兼容维护成本（macOS seatbelt 策略编译、Windows helper 分发、Linux bwrap 依赖）可能超过其边际收益，权限层可以独立承担边界。
• codex 的 denial 启发式自承不确定（7 个关键词 + exit code 2/126/127 快拒 + SIGSYS 特判），说明"检测沙箱拒绝"与"命令自身失败"在经验上不可区分——这是所有依赖沙箱重试策略的 harness 的共同债务。
• fail-closed 是硬约束：dsh 规定沙箱 runner 不可用时前台命令抛错、后台进程标记 runnerFailed；不允许无沙箱降级执行。

4.4 审批 UX 的四档光谱

4.5 超时、截断与后台化

5.1 决策清单（按优先级）

5.2 一句话立场

Shell 工具的设计顺序应当是：先定租户模型（单租户桌面 vs 多租户服务端），再定沙箱档位； 权限层一律"解析只放行、不拦截"；持久状态宁缺毋滥，必须持久则显式 reset； 截断必须诚实（字节封顶 + 退出码改写）；超时必须留逃生口（转后台而非杀死）。