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

① 工作区硬边界    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
                  参数: {"path":"chapter3-note.txt",...}  允许本次调用? [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 里写「不要删除系统文件」只是软约束：模型可能理解错、输入可能与指令冲突、多轮会弱化早期提醒、无法枚举所有危险命令、无法证明检查发生在副作用前。权限策略必须在代码里，位置固定：prepare → decide → invoke。模型只能提出调用请求，是否执行由 Harness 决定。

boolean 表达不出「暂缓」：规则甲想让 write_file「问一下」，返回 false 变成直接拒绝、返回 true 直接执行。规则乙对 write_file 没意见，但「所有规则都 true 才执行」会让弃权变成赞成票。四种行为各有含义。

export const PERMISSION_BEHAVIORS = Object.freeze([
  "allow", "deny", "ask", "passthrough",
] as const);
// 每个决定还带 reason（原因）+ source（来源）

权限规则不重新解析 OpenAI 参数，也不处理未知工具。只有 prepare 成功（定义存在、arguments 是合法 JSON、Zod 已通过、effect 来自受信本地定义）才构造 Request。非法 JSON、多余字段、错误类型在权限系统之前就失败。

一次权限判断有三层输入：① 系统硬边界（工作区外写入直接 deny）；② 结构化参与方（Shell 默认、规则、第 4 章 Hook 建议）；③ 显式审批（只有合并结果为 ask 才调用）。①–④ 全部跑，不是命中一个就短路，审计才能看到完整冲突，而不是「碰巧第一个匹配的规则说了什么」。

候选如何合并：
找第一个 deny → 有就返回
再找第一个 ask → 有就返回
再找第一个 allow → 有就返回
都没有 → passthrough → 转成 allow（default）

优先级：deny > ask > allow > passthrough
一句话记住它：越保守的越赢。

「不能先弹审批框」是安全要求：如果先弹框，用户在赶时间时连着敲了几个 y，这一个也敲下去了，系统随后还是拒绝——那这个框的存在就只教会用户「批准了也可能不执行」。审批框应该只在「你的回答真的能决定结果」时出现。

const allowed = await this.#writeBoundary.isPathWithinWorkspace(
  request.context.workspace, rawPath);
return allowed ? undefined
  : new PermissionDecision("deny",
      "Writing outside the workspace is forbidden",
      "workspace-boundary");

core 只依赖接口，不导入 Node adapter。组合根注入的 NodeWorkspaceFileSystem 内部复用第 2 章 safePath——绝对路径、..、Windows 保留名、junction 逃逸全部继承。

Get-Content 看起来只读，但参数可指向工作区外；普通命令可调用脚本、启动子进程、访问网络。只匹配 Remove-Item、Format-Volume 既不完整也易绕过。只要 effect 是 execute 就产生默认 ask。

if (definition.effect !== "execute") return undefined;
return new PermissionDecision("ask",
  "Shell execution requires approval", "shell-default");

审计在规则合并和审批完成之后、执行之前，记录的是最终结果。格式：[Permission] 工具名: behavior (source) - reason。审计写的是 stderr，最终答案写的是 stdout——重定向只拿回答，不混日志。

[Permission] write_file: allow (terminal-approval) - User approved this tool call
[Permission] write_file: deny (workspace-boundary) - Writing outside ...

P03 只增加一个 capability：policy。两个 profile 使用相同的五工具注册表和同一个 Agent Loop。组合根根据固定 capability 构建策略，而不是接收调用方拼好的策略；缺少 approvalProvider / auditSink 时启动构建阶段抛错，不允许无边界启动。profileForChapter(profile.chapter) !== profile 的引用相等检查拒绝调用方伪造的同编号 profile。

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]

# 敲 y  → [Permission] write_file: allow (terminal-approval)
# 直接回车 → [Permission] write_file: deny (terminal-approval)
#         模型收到 Error [permission_denied]，文件内容不变
# 确认文件: Get-Content .\chapter3-note.txt

npm run ch03 -- --prompt '把 hello 写入 ../outside.txt'
# [Permission] write_file: deny (workspace-boundary) - Writing outside ...
# 注意没有弹审批框——你根本没有机会批准它
# code/ 的上一级目录里不会出现 outside.txt

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

• 权限判断必须在代码的固定位置——prepare 之后、invoke 之前，Prompt 做不到这个保证。
• 决定不是 boolean 而是四态，因为「需要问一下」和「我不表态」都必须能表达出来。
• deny > ask > allow > passthrough：任何一个参与方的拒绝，都不能被其他人的允许推翻。

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