# 06 | `/plan` 命令实现与一比一复现指南

> 基于 Claude Code v2.1.88 反编译源码的逆向分析文档。本文目标是把 Plan Mode 拆成可施工规格：让 GPT-4 级别模型也能按步骤实现出结构和行为接近源码的版本，而不是只理解概念。

## 目录

1. [一句话总结](#1-一句话总结)
2. [必须实现的能力边界](#2-必须实现的能力边界)
3. [核心文件和职责](#3-核心文件和职责)
4. [整体数据流](#4-整体数据流)
5. [最小状态模型](#5-最小状态模型)
6. [`/plan` local-jsx 命令](#6-plan-local-jsx-命令)
7. [Plan 文件系统](#7-plan-文件系统)
8. [权限模式切换](#8-权限模式切换)
9. [EnterPlanModeTool](#9-enterplanmodetool)
10. [ExitPlanModeV2Tool](#10-exitplanmodev2tool)
11. [Plan Mode 附件系统](#11-plan-mode-附件系统)
12. [Plan workflow prompt](#12-plan-workflow-prompt)
13. [Explore Agent 与 Plan Agent](#13-explore-agent-与-plan-agent)
14. [Auto mode 与 Plan mode 的交互](#14-auto-mode-与-plan-mode-的交互)
15. [Teammate 审批流](#15-teammate-审批流)
16. [从零实现顺序](#16-从零实现顺序)
17. [最小可用版本](#17-最小可用版本)
18. [完整版本增强项](#18-完整版本增强项)
19. [测试清单](#19-测试清单)
20. [常见错误](#20-常见错误)
21. [关键结论](#21-关键结论)

---

## 1. 一句话总结

Plan Mode 是一个权限受限的规划状态。进入后，模型只能读取代码和编辑唯一的 plan 文件；完成规划后必须调用 `ExitPlanMode` 请求用户批准，批准后恢复进入前的权限模式并开始实现。

它由六层组成：

```
用户 /plan 或模型 EnterPlanMode
    │
    ▼
切换 toolPermissionContext.mode = "plan"
    │
    ▼
记录 prePlanMode，准备退出时恢复
    │
    ▼
附件系统注入 plan_mode 工作流 prompt
    │
    ▼
模型只读探索 + 写 plan 文件
    │
    ▼
模型调用 ExitPlanMode
    │
    ▼
用户或 team lead 审批
    │
    ▼
恢复 prePlanMode，注入 plan_mode_exit 附件
```

最重要的设计点：**`/plan` 本身只切换状态；真正指导模型如何规划的是附件系统注入的 plan mode prompt；真正退出和审批的是 `ExitPlanModeV2Tool`。**

---

## 2. 必须实现的能力边界

Plan Mode 必须支持：

1. 用户输入 `/plan` 进入 plan mode。
2. 用户输入 `/plan <description>` 进入 plan mode，并把描述作为下一轮模型查询。
3. 模型主动调用 `EnterPlanMode` 进入 plan mode。
4. 已在 plan mode 时，`/plan` 显示当前 plan 文件内容。
5. 已在 plan mode 时，`/plan open` 用外部编辑器打开 plan 文件。
6. 进入 plan mode 后，只允许读操作和编辑 plan 文件。
7. 进入 plan mode 后，附件系统注入 plan workflow 指令。
8. 模型必须把计划写到 plan 文件。
9. 模型必须用 `ExitPlanMode` 请求批准，不能用普通文本问“可以开始吗”。
10. 用户批准后恢复进入前的权限模式。
11. 退出后注入 `plan_mode_exit` 附件，提醒模型现在可以修改文件。
12. 会话恢复、fork、远程会话尽量保留 plan 文件。
13. teammate 可走 leader 审批流。

Plan Mode 不应该：

1. 直接修改业务文件。
2. 在 plan mode 内运行写操作 shell 命令。
3. 让 subagent 调用 `EnterPlanMode`。
4. 让模型在未写 plan 的情况下对 plan-required teammate 退出。
5. 在 channels 环境中进入一个无法退出的 plan mode。

---

## 3. 核心文件和职责

| 文件 | 职责 |
|------|------|
| `src/commands/plan/index.ts` | 注册 `/plan` local-jsx 命令 |
| `src/commands/plan/plan.tsx` | `/plan` 命令主逻辑：进入、显示、打开 plan |
| `src/bootstrap/state.ts` | 保存 plan mode 附件标志、plan slug cache、退出标志 |
| `src/utils/permissions/permissionSetup.ts` | 进入 plan mode 前准备权限上下文 |
| `src/utils/permissions/PermissionUpdate.ts` | 应用 `{ type: 'setMode', mode: 'plan' }` |
| `src/utils/plans.ts` | plan 文件路径、读写、slug、resume/fork 恢复 |
| `src/tools/EnterPlanModeTool/EnterPlanModeTool.ts` | 模型主动进入 plan mode 的工具 |
| `src/tools/EnterPlanModeTool/prompt.ts` | 告诉模型何时应该使用 EnterPlanMode |
| `src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts` | 退出、审批、恢复权限、返回 approved plan |
| `src/tools/ExitPlanModeTool/prompt.ts` | 告诉模型如何调用 ExitPlanMode |
| `src/utils/attachments.ts` | 根据状态生成 `plan_mode` / `plan_mode_exit` 附件 |
| `src/utils/messages.ts` | 把附件转换成模型可见 workflow prompt |
| `src/utils/planModeV2.ts` | Explore/Plan agent 数量、interview phase、实验变体 |
| `src/tools/AgentTool/built-in/exploreAgent.ts` | Explore agent 定义，只读搜索 |
| `src/tools/AgentTool/built-in/planAgent.ts` | Plan agent 定义，只读规划 |
| `src/tools.ts` | 注册 EnterPlanMode 和 ExitPlanMode 工具 |

---

## 4. 整体数据流

### 4.1 用户输入 `/plan`

```
用户输入 /plan [description]
    │
    ▼
processSlashCommand
    │
    ▼
找到 local-jsx command: plan
    │
    ▼
load() -> import('./plan.js')
    │
    ▼
call(onDone, context, args)
    │
    ├─ 当前不在 plan mode
    │     ├─ handlePlanModeTransition(currentMode, 'plan')
    │     ├─ prepareContextForPlanMode(...)
    │     ├─ applyPermissionUpdate(... setMode plan ...)
    │     └─ onDone('Enabled plan mode', { shouldQuery: args 非空且不是 open })
    │
    └─ 当前已在 plan mode
          ├─ 没有 plan 文件 -> onDone('Already in plan mode. No plan written yet.')
          ├─ args[0] === 'open' -> editFileInEditor(planPath)
          └─ 否则 renderToString(<PlanDisplay />)
```

### 4.2 模型主动调用 `EnterPlanMode`

```
模型判断任务复杂
    │
    ▼
调用 EnterPlanMode({})
    │
    ▼
validate: 非 agent context，channels 未启用
    │
    ▼
handlePlanModeTransition(currentMode, 'plan')
    │
    ▼
setAppState(toolPermissionContext.mode = 'plan')
    │
    ▼
tool_result 返回 plan mode 指令摘要
    │
    ▼
下一轮 attachment 注入完整 workflow prompt
```

### 4.3 模型退出 plan mode

```
模型写完 plan 文件
    │
    ▼
调用 ExitPlanMode({})
    │
    ▼
validate: 非 teammate 必须当前 mode === 'plan'
    │
    ▼
checkPermissions
    │
    ├─ teammate -> allow
    └─ 普通用户 -> ask "Exit plan mode?"
    │
    ▼
call()
    │
    ├─ 读取 plan 文件
    ├─ 如果 input.plan 存在，写回 plan 文件
    ├─ teammate required -> 发 leader mailbox，等待审批
    └─ 普通用户 -> 恢复 prePlanMode
    │
    ▼
tool_result:
  User has approved your plan. You can now start coding.
```

---

## 5. 最小状态模型

要实现 Plan Mode，至少需要以下状态字段。

### 5.1 ToolPermissionContext

伪类型：

```typescript
type ToolPermissionContext = {
  mode: 'default' | 'plan' | 'auto' | 'acceptEdits' | 'bypassPermissions'
  prePlanMode?: 'default' | 'auto' | 'acceptEdits' | 'bypassPermissions'
  strippedDangerousRules?: PermissionRule[]
}
```

字段含义：

| 字段 | 作用 |
|------|------|
| `mode` | 当前权限模式 |
| `prePlanMode` | 进入 plan mode 前的模式，退出时恢复 |
| `strippedDangerousRules` | auto/plan 期间临时移除的危险 allow rules |

### 5.2 Bootstrap state

伪类型：

```typescript
type BootstrapState = {
  needsPlanModeExitAttachment: boolean
  hasExitedPlanModeInSession: boolean
  planSlugCache: Map<SessionId, string>
}
```

字段含义：

| 字段 | 作用 |
|------|------|
| `needsPlanModeExitAttachment` | 刚退出 plan mode 时置 true，附件系统消费后清零 |
| `hasExitedPlanModeInSession` | 用于判断重新进入 plan mode 是否需要 reentry 指令 |
| `planSlugCache` | session id -> plan slug，保证同一 session 使用同一 plan 文件 |

### 5.3 关键状态函数

必须提供：

```typescript
function handlePlanModeTransition(fromMode: string, toMode: string): void
function needsPlanModeExitAttachment(): boolean
function setNeedsPlanModeExitAttachment(value: boolean): void
function hasExitedPlanModeInSession(): boolean
function setHasExitedPlanMode(value: boolean): void
function getPlanSlugCache(): Map<SessionId, string>
function getSessionId(): SessionId
```

`handlePlanModeTransition` 逻辑：

```typescript
if (toMode === 'plan' && fromMode !== 'plan') {
  STATE.needsPlanModeExitAttachment = false
}

if (fromMode === 'plan' && toMode !== 'plan') {
  STATE.needsPlanModeExitAttachment = true
}
```

注意：源码中 `ExitPlanModeV2Tool.call()` 也会显式设置：

```typescript
setHasExitedPlanMode(true)
setNeedsPlanModeExitAttachment(true)
```

---

## 6. `/plan` local-jsx 命令

### 6.1 注册文件

文件：`src/commands/plan/index.ts`

```typescript
const plan = {
  type: 'local-jsx',
  name: 'plan',
  description: 'Enable plan mode or view the current session plan',
  argumentHint: '[open|<description>]',
  load: () => import('./plan.js'),
} satisfies Command
```

实现要求：

1. `type` 必须是 `local-jsx`。
2. `name` 必须是 `plan`。
3. `load` 动态 import `./plan.js`。
4. 该 command 必须加入全局 commands 列表。

### 6.2 `call()` 函数签名

文件：`src/commands/plan/plan.tsx`

```typescript
export async function call(
  onDone: LocalJSXCommandOnDone,
  context: LocalJSXCommandContext,
  args: string,
): Promise<React.ReactNode>
```

`context` 至少需要：

```typescript
type LocalJSXCommandContext = {
  getAppState(): AppState
  setAppState(updater: (prev: AppState) => AppState): void
}
```

### 6.3 当前不在 plan mode

完整伪代码：

```typescript
const appState = getAppState()
const currentMode = appState.toolPermissionContext.mode

if (currentMode !== 'plan') {
  handlePlanModeTransition(currentMode, 'plan')

  setAppState(prev => ({
    ...prev,
    toolPermissionContext: applyPermissionUpdate(
      prepareContextForPlanMode(prev.toolPermissionContext),
      {
        type: 'setMode',
        mode: 'plan',
        destination: 'session',
      },
    ),
  }))

  const description = args.trim()
  if (description && description !== 'open') {
    onDone('Enabled plan mode', { shouldQuery: true })
  } else {
    onDone('Enabled plan mode')
  }

  return null
}
```

分支含义：

| 输入 | 行为 |
|------|------|
| `/plan` | 进入 plan mode，不立即 query |
| `/plan open` 且当前不在 plan mode | 只进入 plan mode，不打开文件 |
| `/plan 重构认证模块` | 进入 plan mode，并 `shouldQuery: true` |

为什么 `/plan <description>` 要 `shouldQuery: true`：用户提供了任务描述，进入 plan mode 后要立刻让模型开始规划。

### 6.4 当前已在 plan mode

完整伪代码：

```typescript
const planContent = getPlan()
const planPath = getPlanFilePath()

if (!planContent) {
  onDone('Already in plan mode. No plan written yet.')
  return null
}

const argList = args.trim().split(/\s+/)

if (argList[0] === 'open') {
  const result = await editFileInEditor(planPath)
  if (result.error) {
    onDone(`Failed to open plan in editor: ${result.error}`)
  } else {
    onDone(`Opened plan in editor: ${planPath}`)
  }
  return null
}

const editor = getExternalEditor()
const editorName = editor ? toIDEDisplayName(editor) : undefined
const display = (
  <PlanDisplay
    planContent={planContent}
    planPath={planPath}
    editorName={editorName}
  />
)

const output = await renderToString(display)
onDone(output)
return null
```

### 6.5 PlanDisplay 组件

显示结构：

```tsx
<Box flexDirection="column">
  <Text bold>Current Plan</Text>
  <Text dimColor>{planPath}</Text>
  <Box marginTop={1}>
    <Text>{planContent}</Text>
  </Box>
  {editorName && (
    <Box marginTop={1}>
      <Text dimColor>"/plan open"</Text>
      <Text dimColor> to edit this plan in </Text>
      <Text bold dimColor>{editorName}</Text>
    </Box>
  )}
</Box>
```

注意：源码使用 React compiler cache，复现时不需要实现缓存。

---

## 7. Plan 文件系统

核心文件：`src/utils/plans.ts`

### 7.1 文件位置

默认：

```text
~/.claude/plans/{slug}.md
```

如果是 subagent：

```text
~/.claude/plans/{slug}-agent-{agentId}.md
```

如果用户设置了 `plansDirectory`：

```json
{
  "plansDirectory": ".claude/plans"
}
```

则相对于项目根目录解析，且必须位于项目根目录内。

### 7.2 必须实现的 API

```typescript
function getPlanSlug(sessionId?: SessionId): string
function setPlanSlug(sessionId: SessionId, slug: string): void
function clearPlanSlug(sessionId?: SessionId): void
function clearAllPlanSlugs(): void
function getPlansDirectory(): string
function getPlanFilePath(agentId?: AgentId): string
function getPlan(agentId?: AgentId): string | null
async function copyPlanForResume(log: LogOption, targetSessionId?: SessionId): Promise<boolean>
async function copyPlanForFork(log: LogOption, targetSessionId: SessionId): Promise<boolean>
async function persistFileSnapshotIfRemote(): Promise<void>
```

### 7.3 `getPlansDirectory`

伪代码：

```typescript
function getPlansDirectory(): string {
  const settingsDir = getInitialSettings().plansDirectory

  if (settingsDir) {
    const cwd = getCwd()
    const resolved = resolve(cwd, settingsDir)

    if (!resolved.startsWith(cwd + sep) && resolved !== cwd) {
      logError(new Error(`plansDirectory must be within project root: ${settingsDir}`))
      return join(getClaudeConfigHomeDir(), 'plans')
    }

    mkdirSync(resolved, { recursive: true })
    return resolved
  }

  const fallback = join(getClaudeConfigHomeDir(), 'plans')
  mkdirSync(fallback, { recursive: true })
  return fallback
}
```

源码中该函数用 `memoize` 包裹，因为渲染和权限检查会频繁调用。

### 7.4 `getPlanSlug`

伪代码：

```typescript
function getPlanSlug(sessionId = getSessionId()) {
  const cache = getPlanSlugCache()
  let slug = cache.get(sessionId)

  if (!slug) {
    const plansDir = getPlansDirectory()
    for (let i = 0; i < 10; i++) {
      slug = generateWordSlug()
      const filePath = join(plansDir, `${slug}.md`)
      if (!existsSync(filePath)) break
    }
    cache.set(sessionId, slug)
  }

  return slug
}
```

关键规则：

1. slug 延迟生成。
2. 同一 session id 重复调用返回同一个 slug。
3. 最多重试 10 次避免文件名冲突。
4. 生成结果放进 `planSlugCache`。

### 7.5 `getPlanFilePath`

```typescript
function getPlanFilePath(agentId?: AgentId): string {
  const planSlug = getPlanSlug(getSessionId())

  if (!agentId) {
    return join(getPlansDirectory(), `${planSlug}.md`)
  }

  return join(getPlansDirectory(), `${planSlug}-agent-${agentId}.md`)
}
```

### 7.6 `getPlan`

```typescript
function getPlan(agentId?: AgentId): string | null {
  const filePath = getPlanFilePath(agentId)
  try {
    return readFileSync(filePath, 'utf-8')
  } catch (error) {
    if (isENOENT(error)) return null
    logError(error)
    return null
  }
}
```

### 7.7 Resume 恢复

`copyPlanForResume(log, targetSessionId)`：

1. 从消息历史中找 `slug`。
2. `setPlanSlug(targetSessionId, slug)`。
3. 如果 plan 文件还在，返回 true。
4. 如果文件丢失且不是远程环境，返回 false。
5. 如果是远程环境，尝试恢复：
   - 优先从 `file_snapshot` 中找 `key === 'plan'`
   - 否则从消息历史中找 `ExitPlanMode` tool_use input 的 `plan`
   - 否则找 user message 的 `planContent`
   - 否则找 `plan_file_reference` attachment
6. 恢复成功后写回 plan 文件。

### 7.8 Fork 恢复

`copyPlanForFork(log, targetSessionId)`：

1. 从原日志取 original slug。
2. 为 target session 生成新 slug。
3. 把原 plan 文件复制到新 plan 文件。
4. 不复用原 slug，避免 fork 会话互相覆盖。

### 7.9 远程会话 snapshot

`persistFileSnapshotIfRemote()`：

1. 只在远程环境中运行。
2. 读取当前 plan 文件。
3. 写入一条 `system` / `file_snapshot` transcript message。
4. 用于 remote resume 时恢复 plan 文件。

---

## 8. 权限模式切换

核心文件：`src/utils/permissions/permissionSetup.ts`

### 8.1 `prepareContextForPlanMode`

完整伪代码：

```typescript
function prepareContextForPlanMode(context: ToolPermissionContext) {
  const currentMode = context.mode
  if (currentMode === 'plan') return context

  if (feature('TRANSCRIPT_CLASSIFIER')) {
    const planAutoMode = shouldPlanUseAutoMode()

    if (currentMode === 'auto') {
      if (planAutoMode) {
        return { ...context, prePlanMode: 'auto' }
      }

      autoModeStateModule?.setAutoModeActive(false)
      setNeedsAutoModeExitAttachment(true)
      return {
        ...restoreDangerousPermissions(context),
        prePlanMode: 'auto',
      }
    }

    if (planAutoMode && currentMode !== 'bypassPermissions') {
      autoModeStateModule?.setAutoModeActive(true)
      return {
        ...stripDangerousPermissionsForAutoMode(context),
        prePlanMode: currentMode,
      }
    }
  }

  return { ...context, prePlanMode: currentMode }
}
```

### 8.2 行为表

| 进入前模式 | planAutoMode | 结果 |
|------------|--------------|------|
| `plan` | 任意 | 原样返回 |
| `auto` | true | 保持 auto active，记录 `prePlanMode: 'auto'` |
| `auto` | false | 关闭 auto active，恢复危险权限，记录 `prePlanMode: 'auto'` |
| `default` | true | 打开 auto active，剥离危险权限，记录 `prePlanMode: 'default'` |
| `acceptEdits` | true | 打开 auto active，剥离危险权限，记录 `prePlanMode: 'acceptEdits'` |
| `bypassPermissions` | true | 不打开 auto，记录 `prePlanMode: 'bypassPermissions'` |
| 其他 | false | 只记录 `prePlanMode: currentMode` |

### 8.3 应用 mode 更新

进入 plan mode 时不能只改 `mode`，必须先 `prepareContextForPlanMode`，再 `applyPermissionUpdate`：

```typescript
toolPermissionContext: applyPermissionUpdate(
  prepareContextForPlanMode(prev.toolPermissionContext),
  { type: 'setMode', mode: 'plan', destination: 'session' },
)
```

这样才能保留 `prePlanMode` 和 auto mode side effects。

### 8.4 Plan mode 权限规则

复现时至少要保证：

| 工具类别 | Plan mode 行为 |
|----------|----------------|
| FileRead | 允许 |
| Glob/Grep | 允许 |
| FileWrite | 只允许写 plan 文件 |
| FileEdit | 只允许编辑 plan 文件 |
| NotebookEdit | 禁止 |
| Bash/PowerShell | 只允许只读命令 |
| Agent | 允许 Explore/Plan 等只读 agent |
| ExitPlanMode | 允许主线程调用；部分 agent 场景特殊处理 |
| EnterPlanMode | agent context 禁止 |

实现上可以在权限检查层判断：

```typescript
if (context.mode === 'plan') {
  if (tool is readOnly) allow
  if (tool edits file && target === getPlanFilePath(agentId)) allow
  if (tool === ExitPlanMode) allow
  otherwise deny or ask
}
```

---

## 9. EnterPlanModeTool

核心文件：`src/tools/EnterPlanModeTool/EnterPlanModeTool.ts`

### 9.1 工具定义

```typescript
export const EnterPlanModeTool = buildTool({
  name: 'EnterPlanMode',
  searchHint: 'switch to plan mode to design an approach before coding',
  shouldDefer: true,
  isConcurrencySafe: true,
  isReadOnly: true,
})
```

### 9.2 Schema

输入是 strict empty object：

```typescript
const inputSchema = z.strictObject({})
```

输出：

```typescript
{
  message: string
}
```

### 9.3 isEnabled

channels 场景禁用：

```typescript
if ((feature('KAIROS') || feature('KAIROS_CHANNELS')) &&
    getAllowedChannels().length > 0) {
  return false
}
return true
```

原因：channels 用户可能不在 TUI 前，`ExitPlanMode` 审批弹窗会卡住。

### 9.4 call

完整伪代码：

```typescript
async call(_input, context) {
  if (context.agentId) {
    throw new Error('EnterPlanMode tool cannot be used in agent contexts')
  }

  const appState = context.getAppState()
  handlePlanModeTransition(appState.toolPermissionContext.mode, 'plan')

  context.setAppState(prev => ({
    ...prev,
    toolPermissionContext: applyPermissionUpdate(
      prepareContextForPlanMode(prev.toolPermissionContext),
      { type: 'setMode', mode: 'plan', destination: 'session' },
    ),
  }))

  return {
    data: {
      message:
        'Entered plan mode. You should now focus on exploring the codebase and designing an implementation approach.',
    },
  }
}
```

### 9.5 tool_result 映射

标准模式返回：

```text
Entered plan mode...

In plan mode, you should:
1. Thoroughly explore the codebase...
...
Remember: DO NOT write or edit any files yet.
```

interview phase 返回：

```text
Entered plan mode...

DO NOT write or edit any files except the plan file.
Detailed workflow instructions will follow.
```

注意：完整 workflow 不在这里，而在 attachment -> messages.ts 中注入。

---

## 10. ExitPlanModeV2Tool

核心文件：`src/tools/ExitPlanModeTool/ExitPlanModeV2Tool.ts`

这是 Plan Mode 最复杂的模块。要一比一实现，必须按分支表写。

### 10.1 工具定义

```typescript
export const ExitPlanModeV2Tool = buildTool({
  name: 'ExitPlanMode',
  searchHint: 'present plan for approval and start coding (plan mode only)',
  shouldDefer: true,
  isConcurrencySafe: true,
  isReadOnly: false,
})
```

### 10.2 Schema

源码的公开 input schema 是 strict empty object：

```typescript
const inputSchema = z.strictObject({})
```

但 `call()` 内部会检查：

```typescript
const inputPlan =
  'plan' in input && typeof input.plan === 'string' ? input.plan : undefined
```

原因：CCR web UI 或 permission result 可能把用户编辑过的 plan 放进 `input.plan`。这个字段不是普通模型应该手写的 schema 字段。

输出包含：

```typescript
type Output = {
  plan?: string | null
  isAgent?: boolean
  filePath?: string
  hasTaskTool?: boolean
  planWasEdited?: boolean
  awaitingLeaderApproval?: boolean
  requestId?: string
}
```

### 10.3 requiresUserInteraction

```typescript
requiresUserInteraction() {
  if (isTeammate()) return false
  return true
}
```

含义：

| 场景 | 是否需要本地用户弹窗 |
|------|----------------------|
| 普通用户 | 需要 |
| teammate plan required | 不需要本地弹窗，发给 leader 审批 |
| teammate voluntary plan | 不需要本地弹窗，直接退出 |

### 10.4 validateInput

```typescript
async validateInput(_input, { getAppState, options }) {
  if (isTeammate()) {
    return { result: true }
  }

  const mode = getAppState().toolPermissionContext.mode
  if (mode !== 'plan') {
    logEvent('tengu_exit_plan_mode_called_outside_plan', ...)
    return {
      result: false,
      message:
        'You are not in plan mode. This tool is only for exiting plan mode after writing a plan. If your plan was already approved, continue with implementation.',
      errorCode: 1,
    }
  }

  return { result: true }
}
```

### 10.5 checkPermissions

```typescript
async checkPermissions(input, context) {
  if (isTeammate()) {
    return { behavior: 'allow', updatedInput: input }
  }

  return {
    behavior: 'ask',
    message: 'Exit plan mode?',
    updatedInput: input,
  }
}
```

### 10.6 call 总流程

伪代码：

```typescript
async call(input, context) {
  const isAgent = !!context.agentId
  const filePath = getPlanFilePath(context.agentId)
  const inputPlan =
    'plan' in input && typeof input.plan === 'string'
      ? input.plan
      : undefined
  const plan = inputPlan ?? getPlan(context.agentId)

  if (inputPlan !== undefined && filePath) {
    await writeFile(filePath, inputPlan, 'utf-8').catch(logError)
    void persistFileSnapshotIfRemote()
  }

  if (isTeammate() && isPlanModeRequired()) {
    return await submitPlanToLeader(...)
  }

  restorePermissionMode(context)

  const hasTaskTool =
    isAgentSwarmsEnabled() &&
    context.options.tools.some(t => toolMatchesName(t, AGENT_TOOL_NAME))

  return {
    data: {
      plan,
      isAgent,
      filePath,
      hasTaskTool: hasTaskTool || undefined,
      planWasEdited: inputPlan !== undefined || undefined,
    },
  }
}
```

### 10.7 teammate required 分支

如果 `isTeammate() && isPlanModeRequired()`：

1. 如果没有 plan，抛错：

```typescript
throw new Error(
  `No plan file found at ${filePath}. Please write your plan to this file before calling ExitPlanMode.`,
)
```

2. 生成 `requestId`：

```typescript
generateRequestId('plan_approval', formatAgentId(agentName, teamName || 'default'))
```

3. 写 mailbox：

```typescript
const approvalRequest = {
  type: 'plan_approval_request',
  from: agentName,
  timestamp: new Date().toISOString(),
  planFilePath: filePath,
  planContent: plan,
  requestId,
}

await writeToMailbox(
  'team-lead',
  {
    from: agentName,
    text: jsonStringify(approvalRequest),
    timestamp: new Date().toISOString(),
  },
  teamName,
)
```

4. 如果是 in-process teammate，更新 task 状态为 awaiting approval。
5. 返回：

```typescript
{
  plan,
  isAgent: true,
  filePath,
  awaitingLeaderApproval: true,
  requestId,
}
```

### 10.8 普通退出时恢复权限

核心伪代码：

```typescript
context.setAppState(prev => {
  if (prev.toolPermissionContext.mode !== 'plan') return prev

  setHasExitedPlanMode(true)
  setNeedsPlanModeExitAttachment(true)

  let restoreMode = prev.toolPermissionContext.prePlanMode ?? 'default'

  if (feature('TRANSCRIPT_CLASSIFIER')) {
    if (restoreMode === 'auto' && !isAutoModeGateEnabled()) {
      restoreMode = 'default'
    }

    const restoringToAuto = restoreMode === 'auto'
    const autoWasUsedDuringPlan = autoModeStateModule?.isAutoModeActive() ?? false
    autoModeStateModule?.setAutoModeActive(restoringToAuto)

    if (autoWasUsedDuringPlan && !restoringToAuto) {
      setNeedsAutoModeExitAttachment(true)
    }
  }

  let baseContext = prev.toolPermissionContext

  if (restoreMode === 'auto') {
    baseContext = stripDangerousPermissionsForAutoMode(baseContext)
  } else if (prev.toolPermissionContext.strippedDangerousRules) {
    baseContext = restoreDangerousPermissions(baseContext)
  }

  return {
    ...prev,
    toolPermissionContext: {
      ...baseContext,
      mode: restoreMode,
      prePlanMode: undefined,
    },
  }
})
```

### 10.9 gate fallback notification

如果进入 plan 前是 `auto`，但退出时 auto gate 关闭：

1. 恢复到 `default`。
2. 添加 notification：

```typescript
context.addNotification?.({
  key: 'auto-mode-gate-plan-exit-fallback',
  text: `plan exit -> default · ${gateFallbackNotification}`,
  priority: 'immediate',
  color: 'warning',
  timeoutMs: 10000,
})
```

### 10.10 tool_result 映射

#### teammate 等待审批

```text
Your plan has been submitted to the team lead for approval.

Plan file: <filePath>

What happens next:
1. Wait for the team lead to review your plan
2. You will receive a message in your inbox with approval/rejection
3. If approved, you can proceed with implementation
4. If rejected, refine your plan based on the feedback

Important: Do NOT proceed until you receive approval.

Request ID: <requestId>
```

#### agent 场景

```text
User has approved the plan. There is nothing else needed from you now. Please respond with "ok"
```

#### 空 plan

```text
User has approved exiting plan mode. You can now proceed.
```

#### 普通用户批准

```text
User has approved your plan. You can now start coding. Start with updating your todo list if applicable

Your plan has been saved to: <filePath>
You can refer back to it if needed during implementation.

## Approved Plan:
<plan>
```

如果用户编辑过 plan，标题变成：

```text
## Approved Plan (edited by user):
```

如果当前工具列表有 Agent/Team 工具，还会附加并行任务提示。

---

## 11. Plan Mode 附件系统

核心文件：`src/utils/attachments.ts` 和 `src/utils/messages.ts`

### 11.1 Attachment 类型

必须支持：

```typescript
type Attachment =
  | {
      type: 'plan_mode'
      reminderType: 'full' | 'sparse'
      isSubAgent?: boolean
      planFilePath: string
      planExists: boolean
    }
  | {
      type: 'plan_mode_reentry'
      planFilePath: string
    }
  | {
      type: 'plan_mode_exit'
      planFilePath: string
      planExists: boolean
    }
  | {
      type: 'plan_file_reference'
      planFilePath: string
      planContent: string
    }
```

### 11.2 `getPlanModeAttachments`

生成条件：

1. 当前 `toolPermissionContext.mode !== 'plan'`，返回 `[]`。
2. 如果已有 plan mode attachment 且距离上次不足阈值 human turns，返回 `[]`。
3. 读取 `planFilePath = getPlanFilePath(agentId)`。
4. 读取 `existingPlan = getPlan(agentId)`。
5. 如果 `hasExitedPlanModeInSession()` 且 plan 存在，先加入 `plan_mode_reentry`，然后 `setHasExitedPlanMode(false)`。
6. 计算 full/sparse reminder。
7. 加入 `plan_mode` attachment。

伪代码：

```typescript
async function getPlanModeAttachments(messages, toolUseContext) {
  const mode = toolUseContext.getAppState().toolPermissionContext.mode
  if (mode !== 'plan') return []

  if (messages?.length) {
    const { turnCount, foundPlanModeAttachment } =
      getPlanModeAttachmentTurnCount(messages)

    if (foundPlanModeAttachment &&
        turnCount < PLAN_MODE_ATTACHMENT_CONFIG.TURNS_BETWEEN_ATTACHMENTS) {
      return []
    }
  }

  const planFilePath = getPlanFilePath(toolUseContext.agentId)
  const existingPlan = getPlan(toolUseContext.agentId)
  const attachments = []

  if (hasExitedPlanModeInSession() && existingPlan !== null) {
    attachments.push({ type: 'plan_mode_reentry', planFilePath })
    setHasExitedPlanMode(false)
  }

  const attachmentCount =
    countPlanModeAttachmentsSinceLastExit(messages ?? []) + 1

  const reminderType =
    attachmentCount % FULL_REMINDER_EVERY_N_ATTACHMENTS === 1
      ? 'full'
      : 'sparse'

  attachments.push({
    type: 'plan_mode',
    reminderType,
    isSubAgent: !!toolUseContext.agentId,
    planFilePath,
    planExists: existingPlan !== null,
  })

  return attachments
}
```

### 11.3 human turn 计数

`getPlanModeAttachmentTurnCount(messages)` 从后往前扫描：

1. 只数 human user turns。
2. 不数 `isMeta` user message。
3. 不数 tool_result user message。
4. 遇到最近的 `plan_mode` 或 `plan_mode_reentry` attachment 停止。

这是为了避免 tool loop 中每次工具调用都重复注入 plan prompt。

### 11.4 full/sparse 规则

源码逻辑：

```typescript
const attachmentCount =
  countPlanModeAttachmentsSinceLastExit(messages ?? []) + 1

const reminderType =
  attachmentCount % FULL_REMINDER_EVERY_N_ATTACHMENTS === 1
    ? 'full'
    : 'sparse'
```

含义：第 1、N+1、2N+1 次注入 full，其余 sparse。

### 11.5 `getPlanModeExitAttachment`

退出后一次性注入：

```typescript
async function getPlanModeExitAttachment(toolUseContext) {
  if (!needsPlanModeExitAttachment()) return []

  const appState = toolUseContext.getAppState()
  if (appState.toolPermissionContext.mode === 'plan') {
    setNeedsPlanModeExitAttachment(false)
    return []
  }

  setNeedsPlanModeExitAttachment(false)

  const planFilePath = getPlanFilePath(toolUseContext.agentId)
  const planExists = getPlan(toolUseContext.agentId) !== null

  return [{ type: 'plan_mode_exit', planFilePath, planExists }]
}
```

### 11.6 messages.ts 中的渲染

`plan_mode`：

```typescript
return getPlanModeInstructions(attachment)
```

`plan_mode_reentry`：

```text
You are returning to plan mode after having previously exited it.
A plan file exists at <path>.

Before proceeding:
1. Read existing plan
2. Compare current request
3. Different task -> overwrite
4. Same task -> modify and clean stale parts
5. Always edit plan file before ExitPlanMode
```

`plan_mode_exit`：

```text
## Exited Plan Mode

You have exited plan mode. You can now make edits, run tools, and take actions.
The plan file is located at <path> if you need to reference it.
```

---

## 12. Plan workflow prompt

核心文件：`src/utils/messages.ts`

### 12.1 标准 5 阶段 workflow

`getPlanModeV2Instructions(attachment)` 生成主要 prompt。

开头必须包含硬约束：

```text
Plan mode is active. The user indicated that they do not want you to execute yet -- you MUST NOT make any edits (with the exception of the plan file mentioned below), run any non-readonly tools (including changing configs or making commits), or otherwise make any changes to the system. This supercedes any other instructions you have received.
```

然后给出 plan 文件信息：

```text
No plan file exists yet. You should create your plan at <path> using FileWrite.
```

或：

```text
A plan file already exists at <path>. You can read it and make incremental edits using FileEdit.
```

### 12.2 Phase 1: Initial Understanding

要求：

1. 全面理解用户请求。
2. 搜索可复用函数、工具、模式。
3. 只能使用 `Explore` subagent 类型。
4. 最多启动 `getPlanModeV2ExploreAgentCount()` 个 Explore agents。
5. 单文件/小改动用 1 个 agent。
6. 范围不确定或跨模块时用多个 agent。

### 12.3 Phase 2: Design

要求：

1. 启动 `Plan` agent 设计实现。
2. 默认至少 1 个 Plan agent。
3. trivial task 可以跳过。
4. 最多 `getPlanModeV2AgentCount()` 个 Plan agents。
5. agent prompt 必须包含 Phase 1 的完整背景、文件名、代码路径、约束。

### 12.4 Phase 3: Review

要求：

1. 读取 agents 识别出的关键文件。
2. 确认方案符合用户原始意图。
3. 有疑问时用 `AskUserQuestion`。

### 12.5 Phase 4: Final Plan

要求模型把 plan 写入 plan 文件。

默认 control 版本至少包括：

1. context：为什么要做这个改动。
2. 推荐方案，不列无关替代方案。
3. 需要修改的关键文件路径。
4. 可复用的现有函数和工具，带文件路径。
5. 验证方式，最好是端到端命令。

### 12.6 Phase 5: ExitPlanMode

关键规则：

1. 当计划完成后必须调用 `ExitPlanMode`。
2. 当前 turn 只能以 `AskUserQuestion` 或 `ExitPlanMode` 结束。
3. 不允许普通文本问“这个计划可以吗”。
4. 不允许用 `AskUserQuestion` 请求 plan approval。
5. 只有澄清需求或选择方案时才用 `AskUserQuestion`。

### 12.7 Interview phase

开关函数：

```typescript
function isPlanModeInterviewPhaseEnabled() {
  if (process.env.USER_TYPE === 'ant') return true
  const env = process.env.CLAUDE_CODE_PLAN_MODE_INTERVIEW_PHASE
  if (isEnvTruthy(env)) return true
  if (isEnvDefinedFalsy(env)) return false
  return getFeatureValue_CACHED_MAY_BE_STALE(
    'tengu_plan_mode_interview_phase',
    false,
  )
}
```

interview phase 不强制 Explore/Plan agents，而是让模型：

1. 直接读取代码。
2. 逐步写 plan 文件。
3. 遇到决策就问用户。
4. 反复迭代，直到所有歧义解决。
5. 最后调用 `ExitPlanMode`。

首轮要求：

```text
Start by quickly scanning a few key files to form an initial understanding.
Then write a skeleton plan and ask the user your first round of questions.
Don't explore exhaustively before engaging the user.
```

### 12.8 PewterLedger 实验

文件：`src/utils/planModeV2.ts`

变体：

```typescript
type PewterLedgerVariant = 'trim' | 'cut' | 'cap' | null
```

| 变体 | 作用 |
|------|------|
| `null` | control，完整 plan |
| `trim` | 轻度缩短 |
| `cut` | 中度缩短，减少背景 |
| `cap` | 强限制，40 行上限 |

复现最小版本可以先只实现 control。

---

## 13. Explore Agent 与 Plan Agent

### 13.1 Explore Agent

文件：`src/tools/AgentTool/built-in/exploreAgent.ts`

关键定义：

```typescript
const EXPLORE_AGENT = {
  agentType: 'Explore',
  model: process.env.USER_TYPE === 'ant' ? 'inherit' : 'haiku',
  omitClaudeMd: true,
  disallowedTools: [
    'Agent',
    'ExitPlanMode',
    'FileEdit',
    'FileWrite',
    'NotebookEdit',
  ],
}
```

必须保证：

1. 只读。
2. 不能嵌套 Agent。
3. 不能退出 plan mode。
4. 不能写文件。
5. 主要用于快速搜索代码。

### 13.2 Plan Agent

文件：`src/tools/AgentTool/built-in/planAgent.ts`

关键定义：

```typescript
const PLAN_AGENT = {
  agentType: 'Plan',
  model: 'inherit',
  omitClaudeMd: true,
  tools: EXPLORE_AGENT.tools,
  disallowedTools: EXPLORE_AGENT.disallowedTools,
}
```

Plan Agent 的 prompt 要求：

1. 作为软件架构师。
2. 基于 Explore 结果设计方案。
3. 输出分步实现策略。
4. 输出 `Critical Files for Implementation`。
5. 仍然只读，不能写文件。

### 13.3 agent 数量

文件：`src/utils/planModeV2.ts`

```typescript
function getPlanModeV2ExploreAgentCount() {
  if (env CLAUDE_CODE_PLAN_V2_EXPLORE_AGENT_COUNT is 1..10) return env
  return 3
}

function getPlanModeV2AgentCount() {
  if (env CLAUDE_CODE_PLAN_V2_AGENT_COUNT is 1..10) return env
  if (subscriptionType === 'max' && rateLimitTier === 'default_claude_max_20x') return 3
  if (subscriptionType === 'enterprise' || subscriptionType === 'team') return 3
  return 1
}
```

---

## 14. Auto mode 与 Plan mode 的交互

如果实现项目没有 auto mode，可以跳过本节，直接把 `prePlanMode` 恢复为原 mode。

如果有 auto mode，必须实现：

1. `shouldPlanUseAutoMode()`
2. `prepareContextForPlanMode()`
3. `transitionPlanAutoMode()`
4. ExitPlanMode 里的 auto restore/fallback

### 14.1 shouldPlanUseAutoMode

```typescript
return (
  hasAutoModeOptIn() &&
  isAutoModeGateEnabled() &&
  getUseAutoModeDuringPlan()
)
```

### 14.2 settings 中途变化

`transitionPlanAutoMode(context)`：

1. 只在 `mode === 'plan'` 时生效。
2. 如果 `prePlanMode === 'bypassPermissions'`，不激活 auto。
3. 如果 want 和 have 都 true，重新 strip dangerous permissions。
4. 如果 want true have false，打开 auto 并 strip。
5. 如果 want false have true，关闭 auto 并 restore dangerous permissions。

---

## 15. Teammate 审批流

当 teammate 使用 plan mode，分两类。

### 15.1 plan_mode_required teammate

流程：

```
teammate 调用 ExitPlanMode
    │
    ├─ 如果 plan 文件不存在 -> 抛错
    │
    ├─ 生成 plan_approval_request
    │
    ├─ 写入 team-lead mailbox
    │
    ├─ 标记 teammate task awaiting approval
    │
    └─ 返回 awaitingLeaderApproval: true
```

teammate 收到 tool result 后必须停止实现，等待 inbox。

### 15.2 voluntary plan mode teammate

如果不是 required：

1. `requiresUserInteraction()` 返回 false。
2. `checkPermissions()` allow。
3. `call()` 直接恢复权限模式。

---

## 16. 从零实现顺序

如果让 GPT-4 级别模型实现，不要一次让它写全部。按这个顺序分任务。

### 步骤 1：实现状态字段

实现：

1. `toolPermissionContext.mode`
2. `toolPermissionContext.prePlanMode`
3. `needsPlanModeExitAttachment`
4. `hasExitedPlanModeInSession`
5. `planSlugCache`

### 步骤 2：实现 `plans.ts`

实现：

1. `getPlansDirectory`
2. `getPlanSlug`
3. `getPlanFilePath`
4. `getPlan`
5. `clearPlanSlug`

先不实现 resume/fork。

### 步骤 3：实现权限准备函数

实现：

1. `handlePlanModeTransition`
2. `prepareContextForPlanMode`
3. `applyPermissionUpdate({ type: 'setMode' })`

### 步骤 4：实现 `/plan` 命令

实现：

1. `src/commands/plan/index.ts`
2. `src/commands/plan/plan.tsx`
3. `PlanDisplay`
4. `/plan open`

### 步骤 5：实现 Plan Mode 权限拦截

至少保证：

1. 读工具允许。
2. 非 plan 文件写入禁止。
3. plan 文件写入允许。
4. ExitPlanMode 允许。

### 步骤 6：实现 EnterPlanModeTool

实现：

1. empty input schema
2. channels disabled gate
3. agent context 禁止
4. call 切 mode
5. tool_result prompt

### 步骤 7：实现 ExitPlanModeV2Tool

先实现普通用户版本：

1. validate mode 必须是 plan
2. checkPermissions ask
3. 读取 plan
4. 恢复 prePlanMode
5. 返回 approved plan

再补 teammate 和 input.plan。

### 步骤 8：实现 attachment

实现：

1. `plan_mode`
2. `plan_mode_exit`
3. `plan_mode_reentry`
4. human turn throttle

### 步骤 9：实现 workflow prompt

先实现标准 5 阶段。

之后再补：

1. interview phase
2. PewterLedger variants
3. sparse reminders

### 步骤 10：实现 Explore/Plan agents

实现：

1. Explore agent 只读定义
2. Plan agent 只读定义
3. agent count env override

### 步骤 11：实现恢复和远程增强

实现：

1. `copyPlanForResume`
2. `copyPlanForFork`
3. `persistFileSnapshotIfRemote`
4. `plan_file_reference`

---

## 17. 最小可用版本

如果只想先跑通 Plan Mode，保留这些：

1. `/plan` 命令。
2. `toolPermissionContext.mode = 'plan'`。
3. `prePlanMode`。
4. `getPlanFilePath` 和 `getPlan`。
5. 只允许写 plan 文件。
6. `EnterPlanModeTool`。
7. `ExitPlanModeTool` 普通用户流程。
8. `plan_mode` 附件注入一个简单 workflow。

可以暂时省略：

1. auto mode。
2. teammate。
3. resume/fork。
4. remote snapshot。
5. PewterLedger。
6. interview phase。
7. full/sparse 节流。
8. Explore/Plan agent 数量实验。

最小可用数据流：

```
/plan task
    │
    ▼
mode = plan, prePlanMode = oldMode
    │
    ▼
attachment 注入：只能读代码，写 plan 文件
    │
    ▼
模型写 ~/.claude/plans/<slug>.md
    │
    ▼
模型调用 ExitPlanMode
    │
    ▼
用户批准
    │
    ▼
mode = prePlanMode
```

---

## 18. 完整版本增强项

按优先级补：

1. `/plan open`。
2. `plan_mode_exit` 附件。
3. `plan_mode_reentry` 附件。
4. full/sparse 注入节流。
5. Explore/Plan agents。
6. agent count env override。
7. interview phase。
8. auto mode integration。
9. teammate approval。
10. resume/fork plan recovery。
11. remote file snapshot。
12. PewterLedger variants。

---

## 19. 测试清单

### 19.1 `/plan` 基本行为

```text
初始 mode = default
输入 /plan
期望:
- mode = plan
- prePlanMode = default
- onDone('Enabled plan mode')
- shouldQuery 不为 true
```

```text
初始 mode = default
输入 /plan 重构认证模块
期望:
- mode = plan
- prePlanMode = default
- onDone('Enabled plan mode', { shouldQuery: true })
```

```text
初始 mode = plan
没有 plan 文件
输入 /plan
期望:
- onDone('Already in plan mode. No plan written yet.')
```

```text
初始 mode = plan
有 plan 文件
输入 /plan
期望:
- 输出 Current Plan
- 输出 plan path
- 输出 plan content
```

```text
初始 mode = plan
有 plan 文件
输入 /plan open
期望:
- 调用 editFileInEditor(planPath)
- 成功时输出 Opened plan in editor
- 失败时输出 Failed to open plan in editor
```

### 19.2 Plan 文件

测试：

1. 同一 session 多次 `getPlanFilePath()` 返回同一路径。
2. 不同 session slug 不同。
3. `agentId` 存在时文件名包含 `-agent-{agentId}`。
4. `plansDirectory` 越界时 fallback 到 `~/.claude/plans`。
5. `getPlan()` 文件不存在返回 null。
6. `getPlan()` 读错误时 logError 并返回 null。

### 19.3 EnterPlanModeTool

测试：

1. input schema 不接受任何字段。
2. `context.agentId` 存在时抛错。
3. channels active 时 `isEnabled() === false`。
4. call 后 mode 变 plan。
5. call 后 `prePlanMode` 记录旧 mode。

### 19.4 ExitPlanModeV2Tool

普通用户：

1. mode 不是 plan 时 validate 拒绝。
2. mode 是 plan 时 validate 通过。
3. checkPermissions 返回 ask。
4. call 后 mode 恢复 prePlanMode。
5. call 后 `prePlanMode` 清空。
6. call 后 `hasExitedPlanModeInSession = true`。
7. call 后 `needsPlanModeExitAttachment = true`。
8. plan 为空时 tool_result 返回 “approved exiting plan mode”。
9. plan 非空时 tool_result 包含 approved plan。

input.plan：

1. 传入 `input.plan` 时写回 plan 文件。
2. `planWasEdited = true`。
3. tool_result 标题是 `Approved Plan (edited by user)`。

teammate：

1. `requiresUserInteraction()` 返回 false。
2. plan_required 且无 plan 时抛错。
3. plan_required 且有 plan 时写 mailbox。
4. 返回 `awaitingLeaderApproval: true`。

### 19.5 附件系统

测试：

1. mode 非 plan 时不注入 `plan_mode`。
2. mode plan 时注入 `plan_mode`。
3. plan 文件不存在时 `planExists = false`。
4. plan 文件存在时 `planExists = true`。
5. tool loop 中不因为 assistant/tool messages 反复注入。
6. 退出后注入一次 `plan_mode_exit`。
7. `plan_mode_exit` 注入后 flag 清零。
8. 重新进入且 plan 存在时先注入 `plan_mode_reentry`。

### 19.6 权限

Plan mode 中：

| 操作 | 期望 |
|------|------|
| FileRead 任意文件 | 允许 |
| Grep/Glob | 允许 |
| FileWrite plan 文件 | 允许 |
| FileWrite 业务文件 | 拒绝 |
| FileEdit plan 文件 | 允许 |
| FileEdit 业务文件 | 拒绝 |
| Bash `ls` | 允许 |
| Bash `rm file` | 拒绝 |
| ExitPlanMode | 允许/ask |
| EnterPlanMode in agent | 拒绝 |

### 19.7 workflow prompt

检查 `plan_mode` prompt 必须包含：

1. 不允许修改文件，除了 plan 文件。
2. plan file path。
3. Phase 1 Explore。
4. Phase 2 Plan。
5. Phase 3 Review。
6. Phase 4 写 plan 文件。
7. Phase 5 调用 ExitPlanMode。
8. 禁止用文本请求 plan approval。

---

## 20. 常见错误

### 错误 1：只改 mode，不记录 prePlanMode

退出时无法恢复原权限模式。

正确：

```typescript
prepareContextForPlanMode(prev.toolPermissionContext)
```

### 错误 2：`/plan <description>` 没有 `shouldQuery: true`

用户输入任务描述后，模型不会开始规划。

### 错误 3：允许写任意文件

Plan mode 的核心是只读探索。唯一允许写的是 plan 文件。

### 错误 4：把完整 workflow 放进 EnterPlanMode tool_result

源码中 EnterPlanMode 只返回简短说明。完整 workflow 由 attachment 注入。这样 `/plan` 和 `EnterPlanMode` 两种入口能共享同一套指令。

### 错误 5：ExitPlanMode 不走用户审批

普通用户必须通过 `checkPermissions -> ask`。

### 错误 6：ExitPlanMode 不设置 exit attachment flag

退出后模型不知道自己已经可以写文件。

正确：

```typescript
setHasExitedPlanMode(true)
setNeedsPlanModeExitAttachment(true)
```

### 错误 7：plan 文件 slug 每次重新生成

同一 session 必须复用同一个 slug，否则 `/plan` 读不到之前写的 plan。

### 错误 8：subagent 复用主 plan 文件名

subagent plan 文件必须带 `-agent-{agentId}`，否则会覆盖主会话 plan。

### 错误 9：普通文本询问 plan approval

prompt 必须明确禁止：

```text
Do NOT ask about plan approval in text or AskUserQuestion.
Use ExitPlanMode.
```

### 错误 10：teammate required 没 plan 也允许退出

plan_mode_required teammate 必须先写 plan 文件，否则抛错。

---

## 21. 关键结论

要一比一实现 Plan Mode，不要把它当成一个 `/plan` 命令。它实际是一个状态机：

```text
default/auto/acceptEdits/bypassPermissions
    │
    ▼
plan
    │
    ├─ attachment 注入 workflow
    ├─ 权限层限制只读 + plan 文件写入
    ├─ model 写 plan
    └─ ExitPlanMode 审批
    │
    ▼
prePlanMode
```

最小实现先抓住四件事：

1. `prePlanMode` 保存和恢复。
2. plan 文件路径稳定。
3. plan mode 权限只允许读和写 plan 文件。
4. ExitPlanMode 是唯一 plan approval 出口。

完整实现再补：

1. attachment 节流。
2. reentry/exit 附件。
3. Explore/Plan agents。
4. auto mode 交互。
5. teammate 审批。
6. resume/fork/remote recovery。
7. 实验变体。

按本文顺序实现，GPT-4 级别模型可以把每一步当成独立小任务完成，并通过测试清单逐项验证。