命令执行工具 - BashTool 安全设计与实现

从源码角度解析 Claude Code BashTool：只读命令判定、AST 安全解析、自动后台化、输出截断和专用工具 vs shell 命令的设计权衡。

执行链路总览

一条 Bash 命令从 AI 决策到实际执行的完整路径：

AI 生成 tool_use: { command: "npm test" }
  ↓
BashTool.validateInput()         ← 基础输入校验
  ↓
BashTool.checkPermissions()      ← 权限检查（详见安全体系章节）
  ├── isReadOnly()? → 自动 allow（只读命令免审批）
  ├── bashToolHasPermission()    ← AST 解析 + 语义检查 + 规则匹配
  └── 未匹配 → 弹窗确认
  ↓
BashTool.call() → runShellCommand()
  ↓
shouldUseSandbox(input)          ← 是否需要沙箱包裹
  ↓
Shell.exec(command, { shouldUseSandbox, shouldAutoBackground })
  ↓
spawn(wrapped_command)           ← 实际进程创建

只读命令的判定：为什么 Read 免审批而 Bash 不一定

BashTool 的 isReadOnly() 方法（packages/builtin-tools/src/tools/BashTool/BashTool.tsx:655）决定一条命令是否被视为”只读”：

isReadOnly(input) {
  const compoundCommandHasCd = commandHasAnyCd(input.command)
  const result = checkReadOnlyConstraints(input, compoundCommandHasCd)
  return result.behavior === 'allow'
}

判定逻辑基于 4 个命令集合（BashTool.tsx:120-166）：

集合	命令	性质
BASH_SEARCH_COMMANDS	find, grep, rg, ag, ack, locate, which, whereis	搜索类
BASH_READ_COMMANDS	cat, head, tail, wc, stat, file, jq, awk, sort, uniq…	读取/分析类
BASH_LIST_COMMANDS	ls, tree, du	列表类
BASH_SEMANTIC_NEUTRAL_COMMANDS	echo, printf, true, false, :	语义中性（不影响判定）

对于复合命令（ls dir && echo "---" && ls dir2），系统拆分后逐段检查——所有非中性段都必须属于上述集合，整条命令才被视为只读。

// BashTool.tsx — 简化的判定逻辑
for (const part of partsWithOperators) {
  if (BASH_SEMANTIC_NEUTRAL_COMMANDS.has(baseCommand)) continue  // 跳过中性段
  if (!isPartSearch && !isPartRead && !isPartList) {
    return { isSearch: false, isRead: false, isList: false }  // 有任何一段不通过 → 非只读
  }
}

AST 安全解析：tree-sitter bash 解析

preparePermissionMatcher()（BashTool.tsx:663）在权限检查前用 parseForSecurity() 解析命令结构：

async preparePermissionMatcher({ command }) {
  const parsed = await parseForSecurity(command)
  if (parsed.kind !== 'simple') {
    return () => true  // 解析失败 → fail-safe，触发所有 hook
  }
  // 提取子命令列表，剥离 VAR=val 前缀
  const subcommands = parsed.commands.map(c => c.argv.join(' '))
  return pattern => {
    return subcommands.some(cmd => matchWildcardPattern(pattern, cmd))
  }
}

关键安全点：对于复合命令 ls && git push，解析后拆分为 ["ls", "git push"]，确保 git push 不会因为前半段是只读命令而绕过权限检查。解析失败时采用 fail-safe 策略——假设不安全，触发所有安全 hook。

超时控制：分级策略

用户指定 timeout → 直接使用
  ↓ 未指定
getDefaultTimeoutMs()
  ├── 默认上限：120,000ms（2 分钟）
  └── 最大上限：600,000ms（10 分钟，用户显式设置时）

超时后系统不会直接杀进程——ShellCommand（src/utils/ShellCommand.ts:144）通过 onTimeout 回调通知调用方，由调用方决定是终止还是后台化。

自动后台化

长时间运行的命令可以自动转为后台任务，不阻塞 AI 的 agentic loop：

// BashTool.tsx:1158
const shouldAutoBackground = !isBackgroundTasksDisabled 
  && isAutobackgroundingAllowed(command)

自动后台化的完整链路：

命令开始执行
  ↓ 进度轮询
15 秒内未完成（ASSISTANT_BLOCKING_BUDGET_MS）
  ↓
检查 isAutobackgroundingAllowed(command)
  ↓ 允许
将前台任务转为后台任务（backgroundExistingForegroundTask）
  ↓
shellCommand.onTimeout → spawnBackgroundTask()
  ↓
返回 taskId 给 AI，AI 可以继续做其他事
  ↓
后台任务完成后通过通知机制汇报结果

主线程 Agent 有 15 秒的阻塞预算——超过这个时间，系统自动将命令后台化。这防止了一个 npm install 阻塞整个 agentic loop 数分钟。

输出截断策略

命令输出过长时会触发截断，防止把海量日志塞进 AI 的上下文窗口：

截断点	位置	行为
maxResultSizeChars	工具级（通常 100K 字符）	超长输出在写入消息前截断
进度轮询截断	onProgress 回调	只传递最后几行作为进度显示
totalBytes 标记	isIncomplete 参数	告知 AI 输出被截断

截断不是简单砍尾——isIncomplete 标记确保 AI 知道输出不完整，可以决定是否需要用更精确的命令重新获取。

为什么用专用工具而不是直接调 shell

Claude Code 为文件读写、代码搜索等操作提供了专用工具（Read、Grep、Glob），而不是让 AI 用 cat、grep 等 shell 命令。这不仅是用户体验的选择，更是架构层面的设计决策：

维度	专用工具	Bash 命令
权限粒度	Read 是只读操作 → 自动放行	Bash: cat file 需要审批整条命令（cat 在只读集合中但走不同路径）
输出结构化	返回结构化数据，UI 可渲染 diff、高亮	纯文本输出，无渲染优化
性能优化	文件缓存、分页、token 预算控制	每次都是新进程，无缓存
并发安全	isConcurrencySafe() 返回 true → 可并行执行	Bash 命令可能有副作用，串行执行
安全审计	工具名精确匹配权限规则	需 AST 解析命令结构后匹配

isConcurrencySafe()（BashTool.tsx:652）是一个常被忽视但重要的设计——只有只读命令可以在 agentic loop 中并行执行，有副作用的命令必须串行，防止竞态条件。

进度反馈的流式设计

BashTool 的命令执行是流式的，通过 onProgress 回调逐行推送输出：

runShellCommand()
  ├── Shell.exec() 启动子进程
  ├── 每秒轮询输出文件
  ├── onProgress(lastLines, allLines, totalLines, totalBytes, isIncomplete)
  │   ├── 更新 lastProgressOutput / fullOutput
  │   └── resolveProgress() → 唤醒 generator yield
  ├── yield { type: 'progress', output, fullOutput, elapsedTimeSeconds }
  └── return { code, stdout, interrupted, ... }

UI 层通过 useToolCallProgress hook 实时展示命令输出。resolveProgress() 信号机制让 generator 在有新数据时才 yield，避免了忙等待。