First version

2026-08-11 12:38:02 -03:00
parent 42e875d866
commit 89d1a06204
37 changed files with 5660 additions and 4 deletions
@@ -0,0 +1,69 @@
+# 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.