1 工具定位

想要用好工具，首先要厘清它在 Agent 体系中的定位。下文将从三个层级拆解 Agent，以此界定工具的作用。

执行层：给模型提供执行能力，主体就是工具。
状态层: 对应 Agent Loop 运行过程中的各类状态，包含 Skill、记忆模块。
编排层: 负责管控多 Agent 协同逻辑，包含子 Agent、多 Agent 集群模式。

如果 Agent 是一个人，那么工具就是手脚，没有手脚的人什么也创造不了。明确定位后，我们再来看 Claude Code（简称 CC）工具的整体架构与设计逻辑。

2 工具的架构

Claude Code（简称 CC）的工具体系具备一套完整设计逻辑，具体如下。

2.1 设计思想

CC 工具遵循纵深防御（Defense in Depth）设计思想：单一防护层存在失效风险，多层防护叠加后，违规绕过的成本会远高于合规使用。

CC Tools

按照工具流程阐述一下关键点：

2.2 并发安全编排

CC的机制是只读并行，写入串行。对于只读工具（Read/Grep/Glob）并行执行，写操作（Edit/Write/Bash）串行执行。

这套设计兼顾安全性与运行效率，逻辑十分合理。CC 的实际机制更为严苛精细，例如 Bash 工具会对 Unix、PowerShell 命令做区分：ls、grep、cat 等归为只读操作，文件新增、修改、删除类归为写入操作，这类只读命令同样支持并行执行。

并发调度保障了工具的运行效率，而权限管控则是 CC 安全体系的核心。

2.3 权限决策

权限决策是 CC 工具的核心机制，也是其人机协同（HITL，人工介入）的底层基座。权限决策的原理近似程序钩子（Hook），流程运行至此时会主动暂停，等待人工审批通过后再继续执行。

CC 的权限决策相比 HITL 更为复杂，它是一个权限决策链，在该决策链上，每一步都可直接短路返回。CC的决策链六个节点规则如下：

deny 规则：预先配置全局禁止操作清单，工具 / 命令一旦命中黑名单，直接拦截、终止整个权限链路，后续流程全部不执行。例如使用 Bash 工具执行 rm -rf /、格式化磁盘、高危提权命令等高危操作，命中拒绝规则后会直接提示操作被禁止，不会进入后续校验环节。
ask 规则 (HITL)：未命中拒绝规则，但匹配人工确认清单，立刻弹出交互窗口等待用户手动选择同意 / 拒绝。例如使用 Bash 工具执行普通文件删除、使用 Edit 工具修改系统级配置文件、使用 Read 工具读取隐私密钥文件，都会触发人工确认弹窗。
tool.checkPermissions 工具权限自检：工具执行前自动校验自身属性、操作范围、运行约束，校验异常会触发拦截或询问。例如在受限工作目录内，使用 Bash 工具尝试切换到工作目录上级目录、使用 Read/Edit 工具访问工作目录外文件，权限自检识别出路径越界，直接触发人工询问；同时所有工具默认标记 isReadOnly=false、isConcurrencySafe=false，仅白名单工具会修改该标记。
Safety 路径：专属安全校验通道，重点校验操作路径、访问目录，.git/、.claude/ 为系统强制保护目录，即使开启全局免确认 (bypass) 模式也无法绕过。例如使用 Read 读取 .claude/settings.json、使用 Edit 修改 .git/config，哪怕已开启免确认，安全路径校验仍会强制弹出人工确认，保护核心配置与版本目录。
allow 规则：前面所有校验全部通过，命中全局放行白名单，直接允许工具执行，无需人工干预。例如使用 Read 读取普通业务代码文件、使用 Bash 执行 ls/pwd/cd 等常规目录查看命令、使用 Agent 做纯文本查询类操作，命中放行规则后自动执行。
Auto Mode 自动分类器：前面所有规则（拒绝 / 询问 / 放行）均未命中时，由自动分类器做最终风险判定，决定放行或转为人工询问；该模块遵循「铁闸原则」，一旦服务异常、不可用，直接拒绝所有操作。例如执行未收录在黑白名单的自定义脚本（通过 Bash 运行项目内部陌生脚本）、使用小众组合工具执行非常规操作，会进入自动分类器判断；若分类器故障，此类操作会统一被拦截。

2.4 双路径输出（Dual-Path）

工具执行完成后，原始结果会被 Harness 分发至两条独立链路，同时在模型链路入口叠加「溢出保护规则」，完整结构如下：

工具原始结果
├─ 🔗 路径1：模型链路（ToolMessage → LLM 上下文）【核心推理用】
│  └─ 前置保护：溢出截断规则（maxResultSizeChars）→ 超长内容本地落盘，仅向大模型传递内容预览片段
└─ 🔗 路径2：UI 链路（present_for_display → 终端/IDE 界面）【用户查看用】
     └─ 无字符上限，完整渲染富文本

该设计解决了两大核心矛盾：模型侧需要严控 Token 数量，用户侧则希望查看完整的美化内容。：

模型链路：精简、截断超长内容，严控 Token，避免上下文溢出，保障推理稳定。
UI 链路：完整保留原始内容并做富文本渲染，保证用户查看体验。
超长内容会自动落盘兜底，两条链路相互独立，也便于后续分别迭代优化。

3 BriefTools的裁剪

最新版本 CC 共包含 28 类工具，设计逻辑十分精巧，本文不再展开。该版本并未收录 2025 年 03 月泄露版中的 BriefTool，官方为何选择移除这一工具？

BriefTool（全称 SendUserMessage）是唯一对外交互回复入口，强制模型通过该工具输出内容，以此规范格式；同时承担文本排版、终端渲染工作，让每一轮交互都形成完整闭环。

该工具最初为何被设计出来？早期大模型无法区分纯文本回复与工具调用，输出格式杂乱。为此官方推出 BriefTool。

实测验证发现，即便借助系统提示词、工具描述做多重约束，该工具依旧难以被模型正常触发。随着大模型能力持续升级，该工具不再是能力短板，反而会占用上下文资源，且存在触发不稳定的问题，因此将其移除是合理决策。

小结

CC 整套工具体系贯穿纵深防御的核心设计思想，让 CC 能够安全、高效地执行各类工具，其并发执行、权限执行链以及双流输出的精妙设计，确实是值得学习模仿的典范。

移除 BriefTool 这一调整，也体现出 Harness Engineering（模型适配层工程）具备动态迭代特性：配套架构需要随大模型能力同步演进，这也再次印证了行业核心观点：Agent是模型的延伸。

CC-tools