深度拆解复刻 Claude Code 权限系统

不需要任何安全或密码学背景。本章讲的全是「在哪一行代码上做判断」这种工程问题。

本章导读(你在这)
  ↓
① 先看一眼真实的决策过程    ← 三条调用走出三种结果,先有画面
  ↓
② 验收结果 + 为什么不是 Prompt
  ↓
③ 四态决定                  ← 为什么不是 boolean,三个字段各自的作用
  ↓
④ 请求与规则                ← 权限层的输入契约、一条规则长什么样
  ↓
⑤ 三道闸门如何合并          ← 本章最核心的一节:优先级
  ↓
⑥ 硬边界 / Shell / 审批 / 审计
  ↓
⑦ 插入 Agent Loop + P02/P03 差异
  ↓
⑧ 四个场景 + effect 驱动
  ↓
⑨ 边界、运行、验证与小结

① 工作区硬边界    effect 不是 write,不表态 → 无候选
② Shell 默认      effect 不是 execute,不表态 → 无候选
③ 规则            confirm-file-write 不匹配 → 无候选
④ 合并            一个候选都没有 → passthrough
⑤ 收敛            passthrough → allow(default)
⑥ 审批            不需要
⑦ 审计            [Permission] glob: allow (default) - No ...
⑧ 执行            handler 跑起来

默认允许,但仍然留了记录。

① 工作区硬边界    path 在 workspace 内 → 不表态
③ 规则            confirm-file-write 匹配 → ask
④ 合并            最强的是 ask
⑤ 收敛            调用 ApprovalProvider
                 → 工具调用需要批准: write_file
                   原因: File writes require explicit approval...
                   允许本次调用? [y/N] y → allow(terminal-approval)
⑥ 审计            [Permission] write_file: allow (terminal-approval)
⑦ 执行            handler 跑起来

① 工作区硬边界    safePath 拒绝 → deny
③ 规则            confirm-file-write 匹配 → ask
④ 合并            deny 和 ask 都在 → deny 优先
⑥ 审批            ❌ 根本没调用,用户看不到任何提示框
⑦ 审计            [Permission] write_file: deny (workspace-boundary)
⑧ 执行            ❌ handler 一次都没跑
⑨ 回填模型        Error [permission_denied]: Writing outside ...

在 system prompt 写「不要删除系统文件」只是软约束:模型可能理解错误、用户输入与系统指令冲突、多轮上下文弱化早期提醒、不可能枚举所有危险命令组合、无法证明副作用前一定检查了。

权限策略必须在代码里,位置固定:

模型返回 tool_calls
      ↓
ToolRegistry.prepare:查找 + JSON 解析 + Zod 校验
      ↓
PermissionPolicy.decide:硬边界 + 规则 + 审批 + 审计  ← 这里
      ↓
ToolRegistry.invoke:执行 handler
      ↓
回填相同 tool_call_id

只返回 true/false,运行时不知道「需要询问」和「不发表意见」的区别,也无法解释决定来源。本章四种行为:

每个决定携带原因和来源。最终拒绝转成稳定工具结果:Error [permission_denied]: ...,不是含混的 Permission denied.

一次权限判断有三层输入:

1. 系统硬边界:工作区外写入直接 deny。
2. 结构化参与方:Shell 默认策略、规则、后续 Hook 建议。
3. 显式审批:只有合并结果为 ask 时才调用。

合并优先级固定:deny > ask > allow > passthrough。核心代码按这个顺序找第一个决定。只有 passthrough 或完全没参与方时才默认 allow(落在没有规则反对的读取上)。

调用 {"path":"../outside.txt","content":"x"}:项目规则可能允许、未来 Hook 可能建议允许、用户甚至输入 y——但工作区外写入仍必须拒绝,且不能先弹审批框。

PermissionPolicy 先询问 WorkspaceWriteBoundary。它继承第 2 章 safePath 的全部保证:拒绝绝对路径、..、Windows 保留名、junction/符号链接逃逸。真实路径解析抛异常时也得到「Write path could not be resolved safely」,不降级成允许。

不能用关键词黑名单判断 PowerShell 是否安全。Get-Content 看起来只读,但参数可指向工作区外;普通命令还可调脚本、启动子进程、访问网络。只匹配 Remove-Item 既不完整也容易绕过。

因此只要工具 effect 是 execute,系统就产生默认 ask。审批只授权当前一次调用,不保存「永远允许」。

以下情况都变成 deny:没有审批器、审批器抛异常、返回普通 object/boolean、再次返回 ask、返回 passthrough、终端无交互 stdin、用户直接回车或输入其他内容。真实终端只接受 y 和 yes。

审计发生在规则合并和审批完成之后,记录的是最终结果:[Permission] write_file: allow (terminal-approval) - User approved。审计器失败时不执行未留记录的副作用,转成 permission_evaluation_error,handler 调用次数为零,消息仍配对。

权限拒绝仍生成与原调用 ID 配对的 permission_denied tool result。validateToolPairing() 每轮检查:assistant 工具调用后必须立即跟对应数量的 tool 消息,ID 严格匹配。

P03 只增加一个 capability policy。组合根根据固定 profile 自己构造策略,不接收调用方拼好的宽松策略;缺 approvalProvider 或 auditSink 直接启动失败。

Set-Location 'F:\笔记\Agent实操\code'
npm ci
npm run test:ch03

 Test Files  10 passed (10)
      Tests  61 passed (61)

跑测试时你会看到一行 配置错误: Missing required settings: ...——这不是失败,是被测试断言的预期输出(验证缺配置时 CLI 返回退出码 2)。

npm run ch03 -- --prompt '读取 README.md,然后把一句摘要写入 chapter3-note.txt'

[Permission] read_file: allow (default) - No permission rule blocked the request

工具调用需要批准: write_file
原因: File writes require explicit approval from chapter 3 onward
参数: {"path":"chapter3-note.txt","content":"..."}
允许本次调用? [y/N]

这条 prompt 是专门挑的:先 read_file(默认放行)再 write_file(必须审批),一次跑完看两条路径。敲 y 后看到:

[Permission] write_file: allow (terminal-approval) - User approved this tool call

第 3 步:再跑一次,在审批框直接回车。预期先 [Permission] write_file: deny ...,模型随后收到 Error [permission_denied]: User denied this tool call,且文件内容没有任何变化。[y/N] 里大写的 N 是默认值,回车等于拒绝——这是本章最值得亲手做的验证。

npm run ch03 -- --prompt '把 hello 写入 ../outside.txt'
# [Permission] write_file: deny (workspace-boundary) - Writing outside ...

# 统一入口
npm run agent-tutorial -- run --chapter 3 --prompt '读取 README.md,然后把一句摘要写入 chapter3-note.txt'

注意这次没有弹审批框——你根本没有机会批准它。code/ 的上一级目录里不会出现 outside.txt。

1. 一次 glob 调用,四个参与方分别产出什么候选?最终 source 是什么?
2. 为什么 boolean 表达不了「需要问一下」?举出规则乙那种「不表态」的问题。
3. 候选集合是 [deny, ask] 时,用户会看到审批框吗?为什么?
4. 审批器抛异常,最终 behavior 是什么?如果换成「默认允许」会有什么风险?
5. 审计器抛异常,handler 执行了吗?模型收到什么?
6. 第 3 章的 Agent Loop 比第 2 章多了几处改动?
7. toToolResult() 为什么只允许 deny 调用?