Bash 工具

Shell 执行、环境快照、命令构造、23 个安全验证器、权限管道、沙箱与后台任务。

1. 架构概述

Bash 工具是 Claude Code 触达操作系统的主要入口，也是风险最高的一类工具。一次看似简单的命令执行，背后要经过输入校验、权限判定、命令重写、快照恢复、沙箱包装、输出裁剪和结果解释等多层处理。

Bash 的难点不只是“能不能跑命令”，而是“怎样在保留用户 Shell 体验的前提下，把副作用控制在可审计、可中断、可回滚的范围内”。这一课讲的就是这套控制链条。

五个重要的源目录：

2. 输入/输出架构

Bash 工具对模型暴露的是一个“受限制的公共输入模式”，对内部执行路径则保留一套更完整的输入结构。最典型的例子就是 _simulatedSedEdit：这个字段内部会用，但绝不允许模型直接提供。

这样做的原因很直接。如果模型能自己构造这个隐藏字段，就可能把真实写文件动作伪装成一条看起来无害的命令，通过权限弹窗欺骗用户。

// tools/BashTool/BashTool.tsx — fullInputSchema (internal)
const fullInputSchema = lazySchema(() => z.strictObject({
  command:                 z.string(),          // the shell command
  timeout:                 z.number().optional(), // ms, max = getMaxTimeoutMs()
  description:             z.string().optional(), // model-facing active-voice summary
  run_in_background:       z.boolean().optional(),
  dangerouslyDisableSandbox: z.boolean().optional(),

  // NEVER exposed to model — set only by sed-edit permission dialog
  _simulatedSedEdit: z.object({
    filePath: z.string(),
    newContent: z.string()
  }).optional()
}))

// Public schema omits _simulatedSedEdit (and optionally run_in_background)
const inputSchema = lazySchema(() =>
  isBackgroundTasksDisabled
    ? fullInputSchema().omit({ run_in_background: true, _simulatedSedEdit: true })
    : fullInputSchema().omit({ _simulatedSedEdit: true })
)

输出模式

// tools/BashTool/BashTool.tsx — outputSchema
z.object({
  stdout:           z.string(),
  stderr:           z.string(),
  interrupted:      z.boolean(),
  rawOutputPath:    z.string().optional(),     // MCP large-output path
  isImage:          z.boolean().optional(),    // base64 PNG/JPEG detected
  backgroundTaskId: z.string().optional(),     // set when run_in_background=true
  backgroundedByUser:        z.boolean().optional(),
  assistantAutoBackgrounded: z.boolean().optional(), // auto-bg after 15s
  dangerouslyDisableSandbox: z.boolean().optional(),
  returnCodeInterpretation:  z.string().optional(),  // semantic exit-code note
  noOutputExpected:          z.boolean().optional(),  // shows "Done" vs "(No output)"
  persistedOutputPath: z.string().optional(),  // >30KB → written to disk
  persistedOutputSize: z.number().optional()
})

3.Shell快照系统 ARCH

Bash 工具之所以能“像用户自己的 shell 一样工作”，靠的不是每次都启动一个昂贵的交互式登录 shell，而是会话开始时先做一次环境快照，然后后续命令都复用这份快照。

这份快照保存的不是简单 PATH，而是一整套 shell 语境：别名、函数、选项、某些 shim，以及配置文件加载后的状态。这让 Claude 既能拿到贴近用户环境的执行结果，又不至于每条命令都付出完整登录 shell 的成本。

// utils/bash/ShellSnapshot.ts — snapshot creation (simplified)
export const createAndSaveSnapshot = async (binShell: string) => {
  const configFile = getConfigFile(binShell)       // .zshrc / .bashrc / .profile
  const configFileExists = await pathExists(configFile)

  const snapshotPath = join(
    getClaudeConfigHomeDir(), 'shell-snapshots',
    `snapshot-${shellType}-${Date.now()}-${randomId}.sh`
  )

  const script = await getSnapshotScript(binShell, snapshotPath, configFileExists)
  execFile(binShell, ['-i', '-c', script], { timeout: 10000 })
  return snapshotPath
}

4.指挥建设管道 ARCH

buildExecCommand() 真正做的不是“把一行命令拼起来”，而是在安全与可用性之间做平衡：修正 Windows 空设备重定向、决定是否补 < /dev/null、加上 eval 包装、处理管道位置，再把快照与环境脚本一起接入最终命令串。

这里的复杂度几乎都来自 shell 语义本身。Claude Code 不是简单调用 spawn(command)，而是在努力让命令既保留用户习惯、又不会被 shell 细节和注入边角情况轻易绕过。

// Before: wc reads /dev/null, rg blocks
eval 'rg foo | wc -l' < /dev/null

// After: rg reads /dev/null, wc reads rg's output
eval 'rg foo' < /dev/null | wc -l

// bash
shopt -u extglob 2>/dev/null || true

// zsh
setopt NO_EXTENDED_GLOB 2>/dev/null || true

// When CLAUDE_CODE_SHELL_PREFIX is set (shell may differ)
{ shopt -u extglob || setopt NO_EXTENDED_GLOB; } >/dev/null 2>&1 || true

5. 23个安全验证器 SECURITY

Bash 安全验证并不是一个“大 if”或单条黑名单规则，而是一串分层验证器。每个验证器只负责拦一类风险：不完整命令、危险变量、控制字符、命令替换、重定向、here-doc、jq 特殊函数等等。

这种链式设计的好处是：每条规则都可以非常聚焦，而且第一条明确命中的结论就能直接返回。它形成的是纵深防御，而不是依赖某一个万能检查。

验证器按顺序运行。 第一个非passthrough 结果获胜。

// Safe — ALLOWED:
git commit -m "$(cat <<'EOF'
Fix the login bug

Resolves #1234
EOF
)"

// Unsafe — BLOCKED (substitution in command-name position):
$(cat <<'EOF'
chmod
EOF
) 777 /etc/shadow

type ValidationContext = {
  originalCommand:        string  // verbatim from Claude
  baseCommand:            string  // first token after env vars
  unquotedContent:        string  // double-quotes stripped
  fullyUnquotedContent:   string  // both quote types stripped
  fullyUnquotedPreStrip:  string  // before safe-redirection stripping
  unquotedKeepQuoteChars: string  // strips content but keeps quote delimiters
  treeSitter?:            TreeSitterAnalysis | null  // AST, if available
}

6. 管道许可

通过安全验证之后，命令还要再走一层权限判断。这里考虑的不只是“危险不危险”，还包括当前 permission mode、用户已有的 allow/deny 规则、包装器剥离后的真实命令，以及自动分类器结果。

换句话说，Bash 的权限系统不是单点确认框，而是一套基于命令形态归一化之后再做匹配的决策系统。这也是为什么它能把 NODE_ENV=prod npm run build 这类命令正确归入同一规则族。

// SECURITY NOTE: Phase 2 does NOT strip env vars.
// After a wrapper, VAR=val is treated as the command to execute.
// `timeout 10 MY_CMD=foo` — MY_CMD=foo is the command name, not an env assignment.
// Stripping it here would create a false permission match.

7. 沙盒 SECURITY

即便命令被允许执行，也不代表它会直接在完全开放的环境里跑。是否进入沙盒、沙盒开放哪些目录和网络能力，是另外一条独立决策链。

这一层和权限提示的关系很重要：权限是“你能不能做”，沙盒是“你做的时候边界在哪里”。两者配合，才能让 Claude 既可执行真实命令，又不至于失控。

function shouldUseSandbox(input: SandboxInput): boolean {
  // 1. Sandboxing must be enabled in the first place
  if (!SandboxManager.isSandboxingEnabled()) return false

  // 2. Explicit user override (AND policy must allow unsandboxed commands)
  if (input.dangerouslyDisableSandbox && SandboxManager.areUnsandboxedCommandsAllowed())
    return false

  // 3. Empty command
  if (!input.command) return false

  // 4. User-configured excluded commands (not a security boundary — just convenience)
  if (containsExcludedCommand(input.command)) return false

  return true
}

沙箱通过以下方式在进程生成时控制文件系统和网络访问 SandboxManager。 通过系统提示，Claude 会收到关于活动限制的提示，以便它可以调整其行为：

• 文件系统读取：仅拒绝列表（例如， ~/.ssh)
• 文件系统写入：仅允许列表（例如，项目目录 + $TMPDIR)
• Network：可选的 allowedHosts / DeniedHosts

8.后台执行 PERF

后台执行有三条路径：模型显式要求、用户手动送后台，以及助理模式下的自动后台化。它们表面效果相似，内部却会带不同标记，方便后续 UI 和模型推理区分“这是用户主动送后台的”还是“系统为了响应性自动处理的”。

这里体现的不是单纯性能优化，而是对交互体验的妥协设计：Claude Code 宁可把长任务转入后台，也不愿把主对话线程完全堵死。

当命令处于后台时， backgroundTaskId 返回并输出流式传输到文件 getTaskOutputPath(taskId)。 该模型被赋予了输出路径，以便稍后可以通过 FileRead 工具读取它。

// tools/BashTool/BashTool.tsx — assistant auto-background message
const ASSISTANT_BLOCKING_BUDGET_MS = 15_000

backgroundInfo = `Command exceeded the assistant-mode blocking budget (${ASSISTANT_BLOCKING_BUDGET_MS / 1000}s) 
and was moved to the background with ID: ${backgroundTaskId}. 
Output is being written to: ${outputPath}. 
In assistant mode, delegate long-running work to a subagent or use run_in_background`

function detectBlockedSleepPattern(command: string): string | null {
  const m = /^sleep\s+(\d+)\s*$/.exec(first)
  if (!m) return null
  const secs = parseInt(m[1]!, 10)
  if (secs < 2) return null  // sub-2s sleeps are fine (rate limiting, pacing)

  const rest = parts.slice(1).join(' ').trim()
  return rest
    ? `sleep ${secs} followed by: ${rest}`    // suggest Monitor
    : `standalone sleep ${secs}`               // "what are you waiting for?"
}

9. 输出处理

Bash 输出处理不只是收集 stdout。它还要决定何时截断、何时落盘、何时识别图像、何时把退出码解释成人类可读语义，以及何时剥离内部提示协议标记。

也就是说，Bash 工具真正返回给模型的并不是‘原始子进程输出’，而是一份经过解释、过滤和预算控制后的结果表示。

输出尺寸限制

// utils/shell/outputLimits.ts
export const BASH_MAX_OUTPUT_UPPER_LIMIT = 150_000  // chars — hard cap
export const BASH_MAX_OUTPUT_DEFAULT     = 30_000   // chars — configurable via BASH_MAX_OUTPUT_LENGTH

当输出超出内联限制时，完整输出将保留到工具结果目录中的文件中。 该模型接收到一个 <persisted-output> 包含文件路径和预览的消息。 工具结果目录副本的上限为 64MB 通过硬链接之前的截断。

图像检测和调整大小

If stdout 以 Base64 编码的 PNG 或 JPEG 标头开头， isImageOutput() sets isImage: true 输出被包装在 image 克劳德的内容块。 大图像在发送之前会调整大小，以保持在内容块限制之内。

语义退出代码解释

interpretCommandResult() 使用每个命令的众所周知的代码表将非零退出代码映射到人类可读的注释。 例如， grep 返回 1 表示“没有匹配项”（不是错误），并且 diff 返回 1 表示“文件不同”（不是错误）。 这些在 UI 中显示为 returnCodeInterpretation 而不是将它们视为失败。

Claude Code 提示协议

设置的 CLIs 和 SDKs CLAUDECODE=1 可以发射 <claude-code-hint /> 标记到 stderr（合并到 stdout）。 该工具扫描这些标签，记录它们以供提示推荐系统使用，然后 在模型看到输出之前剥离它们 — 零代币侧通道。 子代理输出也会被剥离，因此提示不会逃脱代理边界。

10.UI分类

Claude Code 不只是执行命令，也会给这些命令打上展示语义：哪些结果默认可以折叠、哪些属于读取类输出、哪些属于静默成功命令、哪些更像文件编辑而不是 Bash 命令本身。

这种分类直接影响用户界面和权限提示的可理解性。换句话说，UI 里的 Bash 并不是‘原样显示命令行’，而是对命令意图做了一层重新解释。

// tools/BashTool/BashTool.tsx — command sets for collapsible display
const BASH_SEARCH_COMMANDS = new Set(['find', 'grep', 'rg', 'ag', 'ack', ...])
const BASH_READ_COMMANDS   = new Set(['cat', 'head', 'tail', 'jq', 'awk', ...])
const BASH_LIST_COMMANDS   = new Set(['ls', 'tree', 'du'])

// Semantic-neutral: don't affect the read/search classification of a pipeline
const BASH_SEMANTIC_NEUTRAL_COMMANDS = new Set(['echo', 'printf', 'true', 'false', ':'])

对于像这样的管道 cat file | jq .name, 所有零件 必须是整个管道的搜索/读取命令才能被视为可折叠。 单个非搜索命令使整个管道不可折叠。 中性命令（echo, true) 在任何位置都会被跳过。

The BASH_SILENT_COMMANDS 放 （mv, cp, rm, mkdir等）驱动一个单独的决定：当这些命令成功但没有标准输出时，在 UI 中显示“完成”而不是“（无输出）”。

The sed 特殊情况：如果命令与 sed 就地编辑模式匹配（sed -i 's/.../.../' file），该工具的 userFacingName() 使用以下命令将其呈现为文件编辑操作（不是 bash 命令） FileEdit 工具的显示名称。 这意味着用户看到的是文件差异样式的权限对话框，而不是通用命令批准。

要点