# Plan mode

**Status:** Implemented · **Code:** `Scripts/permissions.js` (`_reviewPlan`,
`_approvePlan`, `writeFeedback`, `sendFeedback`), `Scripts/main.js` (`commandPlan`)

Claude researches and proposes without changing anything, then presents a plan
for approval.

## Entering

`Plan with Claude…` (⌘⇧P) switches a **running** session to plan mode with the
`set_permission_mode` control request, so existing context carries into the
planning, then prompts. The permission mode can also be set to `plan` for a
whole session.

## The handoff

`ExitPlanMode` arrives as a `can_use_tool` request with
`requires_user_interaction: true`, carrying:

- `plan` — the plan as Markdown
- `planFilePath` — where Claude Code saved it (`~/.claude/plans/<slug>.md`)

The plan file is opened when it exists (it is the real artifact), otherwise the
`plan` text is shown in a scratch tab.

Announcement is a **`NotificationRequest`**, not an action panel: notifications
do not block the window, so the plan stays scrollable and editable while the
decision is open. Actions: `Approve`, `Auto-accept edits`, `Write Feedback…`.
`_reviewPlanFallback` uses a panel if notifications are unavailable.

## Approving

```jsonc
{"behavior":"allow",
 "updatedPermissions":[{"type":"setMode","mode":"acceptEdits"|"default","destination":"session"}]}
```

The two approve options map onto Claude Code's own "auto-accept edits" and
"manually approve edits". The CLI answers with *"User has approved your plan.
You can now start coding."*

If the plan document was edited, `updatedInput.plan` carries the user's version
— **and the CLI writes it to `planFilePath`**, making it the plan of record.
Verified: an edited plan was what Claude then followed.

## Three feedback channels

All combine into one `deny` message:

1. **Edit the plan document.** Unsaved editor content wins over disk
   (`_currentPlanText` prefers an open editor over `readFile`).
2. **Highlight a passage** in the plan, then send feedback — the selection is
   quoted back so "this part is wrong" has a referent (`_planSelection`).
3. **Write Feedback…** opens a scratch Markdown tab with a comment header.
   Write freely, then `Send Feedback` in the sidebar. The header is stripped up
   to the first `-->`.

Nova gives extensions no multi-line input field, so the editor *is* the text
box. The one-line `showInputPanel` remains only as a fallback when a scratch tab
cannot be opened.

Denying keeps the session in plan mode; Claude revises and re-presents.

## Gotchas

- Dismissing the notification leaves the plan pending in the sidebar with its
  choices. Plans are expensive; never auto-deny on dismissal.
- `_showPlan` is also reachable from the `Open Plan` sidebar row.