第 7 课：内置工具与安全边界

结论

工具是 coding agent 从“会回答”变成“会行动”的边界，也是风险最大的边界。安全边界不能只靠 prompt 里的自我约束，必须落实到工具 allowlist、审批、路径限制和执行策略。

入口问题

如果一个 agent 被要求只读仓库，怎样保证它真的没有写入能力？

心智模型

• 只读工具只能观察代码和文本。
• 命令工具可以产生外部副作用，即使没有编辑工具也可能修改环境。
• 编辑和写入工具直接改变工作区。
• 权限模式应该从任务最小需要出发，而不是默认全开。

源码推演（省略版）

下面不是完整源码，而是把本课主线压缩成可以在文档里直接阅读的关键形状。读者即使不打开本地源码，也应该能看出运行时如何组织职责。

function toolsForMode(mode: PermissionMode) {
  if (mode === "readonly") return [read, search, list];
  if (mode === "ask-before-edit") return [read, search, list, bash, proposeEdit];
  if (mode === "full-auto") return [read, search, list, bash, edit, write];
}

const session = createAgentSession({ tools: toolsForMode(mode) });

• 核心细节是：工具集合在创建 session 时就确定，模型看不到的工具就不能调用。
• bash 需要特殊对待，因为它可能通过命令间接写文件或访问网络。
• 后续高级课程的审批和沙箱，都是在这个 allowlist 模型上继续加防线。

课堂练习

为 readonly、ask-before-edit、full-auto 三种模式设计工具集合和用户确认点。

掌握标准

• 能把工具按风险分级。
• 能解释为什么禁用 edit/write 后仍要限制 bash。
• 能为一个任务选择最小工具集合。

课后习题

1. 实践题：基于本课的省略版源码，补出一个最小实现草图，要求写清输入、输出、副作用和错误处理。
2. 思考题：本课机制如果只靠 prompt 约束，而不放进 harness 或 runtime，会出现什么工程风险？