Claude Code 的 Bash 子代理是干什么的

Claude Code 曾经有一个内置子代理，名字就叫 Bash。系统提示里写的是：Command execution specialist，专门跑 git、构建、测试这类终端命令，手里只有 Bash 这一个工具。Jarrod Watts 2026 年初那条帖讲的就是它。后来官方把它撤了。现在还想把吵闹的命令输出从主对话里挪出去，得自己写一个。

官方文档：https://code.claude.com/docs/en/sub-agents

Anthropic 工程师说明（2.1.50 移除）：https://github.com/anthropics/claude-code/issues/30693

它当初要解决什么

主对话里直接跑 Bash，输出会整段进上下文。一次测试、一次 git log、或一次 gh api 翻评论，就能把窗口占掉一大截。后面再让模型改代码，它得先背着这些日志。

Bash 子代理的做法是：主对话只发一句任务，子代理在自己的上下文里跑命令，回来只交摘要。主对话继续写代码，不必记住每一行 stdout。

它也只该干这个。没有 Read、没有 Edit、没有 MCP。让它读完文件再改是找错人。

2.1.50 之后没有这个类型了

内置 subagent_type Bash 在 2.1.50 被拿掉。Anthropic 的 Dickson Tsai 在 issue 里写得很直接：后台跑的时候，权限请求经常被静默拒绝；一个号称只会跑命令的代理，结果一条命令都跑不了。与其修这个类型，不如让你自己写一个，把允许的命令写进 tools。

所以今天如果你跟 Claude 说「用 Bash 子代理跑一遍测试」，它要么找不到这个类型，要么会去调 general-purpose 或你自己定义的代理。别再抄旧教程里的 Task(subagent_type=Bash)。

自己做一个命令代理

文件放在项目 .claude/agents/cmd.md，或用户级 ~/.claude/agents/。文件长这样：

markdown

---
name: cmd
tools: Read, Grep, Glob
description: 跑 git、测试、构建和只读查询。命令输出很吵、主对话不需要全文时用。
model: haiku
---

你只负责跑命令并交摘要。

动手前先确认工作目录。每条命令写清目的。跑完只回报退出码、失败的那几行（最多 30 行）、跟任务相关的结论。

不要改文件。不要提交。不要推远程。命令被拒绝就如实说，不要编一段看起来像成功的输出。

frontmatter 的 tools 写成允许名单，不要裸给全部终端权限。按命令族收窄：git status / diff / log / rev-parse，gh 的 pr view、pr diff、api，再加上测试命令。需要解释输出时才加 Read、Grep、Glob。

具体写法见官方字段表：https://code.claude.com/docs/en/sub-agents#supported-frontmatter-fields 。Dickson 给的例子是把 gh pr diff、gh pr view、git diff、git log 这类只读查询写进 tools，再配 Glob、Grep、Read。

description 写清什么时候该用。Claude 靠这段决定要不要委派，写太虚它就不会调用。文件放在项目的 .claude/agents/，或用户级 ~/.claude/agents/。保存之后一般几秒就能用；如果这个 agents 目录是本场会话才新建的，重启一次 Claude Code。

试一句：用 cmd 代理跑一遍测试，只告诉我失败的用例。或直接 at 这个代理，让它看当前分支比 main 多了哪些提交。

权限：后台跑之前先批过

子代理在后台时，没批过的工具会被直接拒绝，不会弹窗。以前内置 Bash 类型就是栽在这里。

先在主对话里把常用命令批一次，或写进项目的 settings.local.json 的 permissions.allow。只给只读查询和测试。提交、推送、删文件继续留在主对话里手动批。不要把全部终端命令一次性放开，子代理会继承你放开的范围。

isolation 设成 worktree 适合让它改一棵独立工作树。纯跑测试、看 git 状态，不必开。开了之后，命令被钉在那棵 worktree 里；工作目录跑回主仓库会被拒绝（2.1.203 之后更严）。

什么时候别用

只要跑一条短命令，主对话直接跑更快。子代理要另开上下文，还可能再付一轮。
命令结果你接下来马上要引用原文。摘要会丢细节。
需要改文件。给它 Edit / Write，或者别用命令代理。
权限还没批过，又准备丢到后台。结果就是全员提示 Permission denied。

还有一个旧坑：终端工具被拒绝时，早期版本的子代理有时会编一段看起来像命令输出的文字交差，主对话当真往下改。2.1 之后好一些，但提示词里仍要写一句：被拒绝就说实话，不要编。回来的结果如果 totalToolUseCount 是 0，当它没跑过。

小结

内置 Bash 子代理：把吵的命令输出隔离出主对话，手里只有 Bash
2.1.50 已移除。别再调 subagent_type Bash
现在自己写一个，tools 里按命令族收窄权限，description 写清何时调用
后台跑之前先批权限。没批过的命令会被静默拒绝
一条短命令、马上要引用原文、要改文件，都别走这个代理

子代理文档：https://code.claude.com/docs/en/sub-agents 2.1.50 移除说明：https://github.com/anthropics/claude-code/issues/30693 安装 Claude Code：https://claude.ai/install.sh