企业官网建设流程全解析

Pilot Shell auto_approve_plan详解：模型切换流程中的ExitPlanMode授权

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell

如果你在用 Pilot Shell 搭配 Claude Code 跑 spec 驱动开发，大概率遇到过这个场景：规划阶段用上了更聪明的模型（opusplan），计划批准后却要再点一次"退出计划模式"的确认框——多此一举，甚至可能让权限模式被意外降级。Pilot Shell 的auto_approve_planhook 就是为了解决这个 ExitPlanMode 授权问题而生的：它精准识别"这次退出是模型切换流程的一部分"，自动放行冗余确认，同时绝不替用户批准计划本身。

一、先理清背景：为什么需要 auto_approve_plan？

Pilot Shell 的/spec工作流分两条"腿"：

1. 规划腿（planning leg）：在计划模式下，由更强的模型（如 Opus）负责探索代码库、撰写计划文档；
2. 实现腿（implementation leg）：计划获批后，切换回日常模型开始写代码。

在"自动模型切换"（Automated Model Switching）模式下，这两条腿的切换依赖 Claude Code 原生的计划模式工具EnterPlanMode和ExitPlanMode。问题在于：ExitPlanMode属于"必须用户交互"的工具，它自带一个确认对话框。而在/spec流程里，用户已经在独立的审批环节批准过计划，退出时的这个对话框就成了冗余的二次确认——更麻烦的是，退出计划模式时 Claude Code 会把会话权限模式"顺带"降级（上游行为），如果处理不当，用户的bypassPermissions设置会在规划结束后悄悄丢失。

auto_approve_plan就注册在PermissionRequest事件上（见 hooks.json），对每一次权限请求做"守门"判断，但它的第一原则是：拿不准就闭嘴——不输出任何决策，把决定权交还给 Claude Code 原生的对话框。

二、核心逻辑：三条决策分支

主逻辑在_exit_plan_mode_decision中，按优先级走三条分支：

分支 1：已预置的原生计划交接（prepared native handoff）

如果/spec在规划前就通过native_plan_capture.py预置了原生草稿（native-spec-planning.json），hook 会先用 SHA256 校验草稿内容与绑定关系是否一致：

• 若用户配置保留审批（approval_required: true）→ 什么都不做，让原生审批对话框出现，Pilot 绝不越权；
• 若用户明确关闭了审批门槛，且退出内容与预置草稿完全匹配 → 自动放行，并回显updatedInput告诉运行时"交互已收集"，从而跳过冗余对话框。

分支 2：Pilot spec 规划腿的退出（经典场景）

判断条件是_is_spec_plan_leg：这个ExitPlanMode必须属于一个在入口处就已登记归属的 Pilot 规划腿，且对应计划文件可读、状态为已批准。满足则输出behavior: "allow"，并在tool_input完整时回显updatedInput以抑制冗余对话框。

关键设计：计划归属是在EnterPlanMode触发时由plan_mode_tracker.py的record_plan_leg_owner提前写入的，而不是在退出时靠"当前会话状态"反推——因为一个正在实施中、已批准的计划，和一个等待退出的规划腿，在退出瞬间的状态长得一模一样，事后推断必然出错。

分支 3：其他一切情况 → 保持沉默

原生的计划模式（比如你手动按 Shift+Tab 进入的）、/buildBuildout 中出现的计划、兄弟会话的状态、任何读不出来的计划文件，一律返回None。此时 hook 不打印任何输出，Claude Code 自己的计划对话框照常出现——这永远是最安全的兜底。

三、细节里的安全设计（也是测试重点）

这个 hook 的测试文件 有 700 多行，几乎每行注释都在讲一个真实踩过的坑，值得新手借鉴：

• 放行消息从不宣称"计划已批准"。测试test_allow_message_does_not_claim_plan_approval强制要求消息里必须带有 "NOT plan approval" 的免责声明——早期版本输出过 "Plan auto-approved" 字样，导致模型误以为用户批准了计划，直接跳过了真正的审批环节；
• updatedInput只在 Pilot 规划腿出现。这个字段会告诉运行时"必需的交互已收集"，等于替用户点了确认，一旦泄漏到原生计划模式，就等于 hook 替用户批准了计划；
• bypassPermissions 恢复只认"正向证据"。只有plan_mode_tracker在规划前明确记录了"进入计划模式前就是 bypass 模式"，退出后才会挂上恢复标记（marker），并在下一次权限请求时回放setMode恢复；没有证据就绝不动权限设置。恢复标记是单次消耗的，且会话隔离，防止一个会话的标记误伤兄弟会话（见_restore_decision）；
• 失败开放（fail-open），但开放的是"沉默"而非"放行"。辅助库缺失、计划文件解码失败、项目根路径不确定时，hook 一律退回到原生对话框，既不把用户困死在计划模式里，也不替用户做决定。

四、如何自己动手验证

想深入理解，建议按这条路径读源码（都很短）：

1. 入口分发：auto_approve_plan.py 的 main 函数，只看ExitPlanMode/EnterPlanMode/ 其他三种分流；
2. 状态登记：plan_mode_tracker.py 中PreToolUse(EnterPlanMode)如何记录归属与前置权限模式；
3. 审批语义：12-approval.md 描述了/spec流程中人工审批与"已预置原生计划"路径的关系，以及 spec-native-plan.md 这份自动模式下的交接 runbook；
4. 行为契约：通读 test_auto_approve_plan.py，每个测试名就是一个安全不变量。

五、小结

auto_approve_plan展示了 hook 工程里一个非常克制的姿态：它只做减法——在确认"用户已经批准过"的前提下，移除模型切换流程中冗余的那一次ExitPlanMode确认，并小心地维护会话的权限模式；在所有模糊地带，它选择闭嘴，把决定权还给人和运行时。对于希望在自己的 Claude Code 工作流里做类似"智能授权"的同学，这套"入口登记归属 + 正向证据 + 失败沉默"的三板斧，比任何激进的全局放行都更值得抄作业。

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell