@narumitw/pi-plan-mode 0.57.0 → 0.58.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -11,7 +11,7 @@ Use a Codex-like `/plan` mode to explore a codebase, resolve important questions
11
11
  - Uses structured questions for important ambiguity and explicit completion for a decision-ready plan.
12
12
  - Reviews the complete plan before implementation, export, save, further planning, or discard.
13
13
  - Implements in the planning session or a fresh linked session with the approved plan.
14
- - Selects an implementation model and thinking level through saved defaults or one-menu overrides, without switching back automatically.
14
+ - Configures persistent or one-shot destination model and thinking choices for fresh implementation.
15
15
  - Restores Plan state and one saved plan across resume and compaction.
16
16
  - Configures the Plan tool allowlist, reviewed shell commands, user-trusted subcommands, export path, plan reinjection, shortcut, and thinking level.
17
17
  - Publishes statusline state and cooperates anonymously with Workflow Mutex Protocol v1 participants.
@@ -46,6 +46,45 @@ Install only from sources you trust because Pi extensions run with Pi's permissi
46
46
  Run `/plan` to open the state-aware menu, then start Plan mode and ask the agent to inspect and design the change.
47
47
  Run `/plan <prompt>` when the first planning request is already known.
48
48
 
49
+ ## 🗺️ How it works
50
+
51
+ Plan mode keeps exploration and implementation on opposite sides of an explicit review boundary:
52
+
53
+ ```mermaid
54
+ flowchart LR
55
+ start["Start: /plan or /plan with a prompt"]
56
+ start --> explore["Explore safely: inspect and clarify"]
57
+ explore --> complete["Complete the plan with plan_mode_complete"]
58
+ complete --> review["Review the ready plan"]
59
+ review -->|Revise| explore
60
+ review -->|Implement here| current["Current session: planning context retained"]
61
+ review -->|Start fresh| fresh["Fresh session: approved plan transferred"]
62
+ review -->|Save| saved["Saved for later"]
63
+ review -->|Export| exported["Markdown file"]
64
+ ```
65
+
66
+ During planning, the agent can inspect the project and ask material questions, but Plan mode blocks editing tools and unsafe shell forms. Implementation starts only after the plan is complete and you choose a handoff:
67
+
68
+ ```mermaid
69
+ sequenceDiagram
70
+ actor User
71
+ participant Pi
72
+ participant Plan as Plan mode
73
+ participant Work as Implementation
74
+
75
+ User->>Pi: Start planning
76
+ Pi->>Plan: Apply the configured Plan tool policy
77
+ Plan->>User: Ask material questions when needed
78
+ User-->>Plan: Answer or refine the request
79
+ Plan->>Pi: Submit the complete plan
80
+ Pi-->>User: Show the ready-plan review
81
+ alt Implement here
82
+ Pi->>Work: Restore Normal mode in the current session
83
+ else Start fresh and implement
84
+ Pi->>Work: Create a fresh session with the approved plan
85
+ end
86
+ ```
87
+
49
88
  ## 💬 Commands
50
89
 
51
90
  | Command | Purpose |
@@ -58,11 +97,12 @@ Run `/plan <prompt>` when the first planning request is already known.
58
97
  | `/plan finalize` | Ask the active planner to finish or ask one remaining material question. |
59
98
  | `/plan implement` | Implement a completed or saved plan in this session, without a selector. |
60
99
  | `/plan save` | Save a ready plan in this Pi session and leave Plan mode. |
100
+ | `/plan settings` | Open the same Plan Settings screen available from the menus. |
61
101
  | `/plan export [path]` | Write a ready, saved, or active implementation plan to Markdown. |
62
102
  | `/plan exit` (alias: `off`) | Leave Plan mode and discard its ready plan, or clear a saved/active plan. |
63
103
 
64
104
  All routes support TUI and RPC.
65
- Print and JSON modes reject the menu and `tools`; stored-plan display and implementation have [additional mode restrictions](#-planning-and-implementation).
105
+ Print and JSON modes reject the menu, `tools`, and `settings`; stored-plan display and implementation have [additional mode restrictions](#-planning-and-implementation).
66
106
  Exact subcommand words select routes; other text is a planning prompt, so `/plan start a migration` sends a prompt rather than rejecting trailing text.
67
107
  There is no startup flag.
68
108
 
@@ -151,16 +191,24 @@ Empty, malformed, unclosed, or multiple legacy blocks keep Plan mode active and
151
191
 
152
192
  After completion, `/plan` opens the ready actions when interactive UI is available.
153
193
  The same flat menu shows **Implement here** and **Start fresh and implement**, explains which conversation context each choice uses, and previews the selected **Plan reinjection** policy.
154
- **Implementation options…** stages model and thinking choices for either action in that menu; `/plan implement` uses saved defaults.
155
- Choices take effect only when implementation starts and do not change Pi's global defaults.
156
- After kickoff, run settlement, user abort, and active-plan clearing do not restore the previous model or thinking; subsequent manual choices remain yours.
157
- Implementation preferences are characterized on Pi 0.85.0; use that release or newer for this feature.
158
- See [implementation preferences](./docs/settings.md#implementation-model-and-thinking) for inheritance and failure behavior.
159
-
160
- Selecting another provider with **Implement here** sends the retained planning conversation to that provider.
161
- Fresh implementation transfers only the approved plan plus the destination's normal resources.
162
194
  **Implement here**—and the compatibility route `/plan implement`—appends the Normal contract, lifts the Plan runtime policy, captures the reinjection setting, and starts implementation in the current session with its complete planning conversation and tool calls.
163
- **Start fresh and implement** waits for the source session to become idle, verifies the selected model and authentication, creates a new session linked to the persisted source as its parent, and transfers the exact approved plan without copying planning messages, tool results, or compaction/branch summaries.
195
+ **Start fresh and implement** opens a settings page before replacement.
196
+ Its searchable model list snapshots the session's scoped models when configured, otherwise Pi's currently available models, and shows each provider, model ID, and friendly name.
197
+ Pi 0.80.6–0.82.1 does not expose session model scopes to extensions, so the list uses all currently available models on those releases.
198
+ One-shot provider and model identifiers are limited to 512 characters each; longer custom identifiers are rejected before the source session is replaced.
199
+ The model and thinking rows start from the persistent **Fresh model** and **Fresh thinking** defaults; when either setting is omitted, they show the planning session's current value with **same as plan** and carry it into the fresh session independently.
200
+ The fixed thinking choices are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
201
+ Back navigation preserves this menu-local draft, while closing and reopening the menu restores both persistent defaults.
202
+ If the configured model is outside the current scope or no longer available, the row reports the fallback and uses **same as plan** without deleting the stored preference.
203
+ The saved-plan menu keeps its direct fresh-session action without optional rows and applies the same persistent defaults and fallback.
204
+
205
+ Starting from that settings page waits for the source session to become idle, re-resolves and authenticates an explicit model, creates a new session linked to the persisted source as its parent, and transfers the exact approved plan without copying planning messages, tool results, or compaction/branch summaries.
206
+ The destination consumes the one-shot choices before its first provider request, applies an explicit model first, and then applies explicit thinking.
207
+ Concurrent prompts that arrive while those choices are being applied are queued as follow-ups behind the kickoff prompt.
208
+ If durable consumption blocks the kickoff, the handoff reports a partial start and restores a conversation-history prompt to the editor instead of reporting success.
209
+ Changing only the model keeps the planning thinking level; changing only the thinking level keeps the planning model.
210
+ If Pi clamps an unsupported thinking level, the extension reports the effective level.
211
+ If the chosen model disappears or loses authentication after source preflight, the destination reports the race, consumes the intent without retrying it later, and continues with its default model.
164
212
  The destination still loads its normal `AGENTS.md`, skills, project resources, and extensions.
165
213
  Choosing **Export plan…** asks for a destination, writes the plan, appends the Normal contract, restores inherited thinking, and leaves Plan mode without starting a model turn or changing active tools.
166
214
  Choosing **Save for later**—or running `/plan save`—instead stores one plan in the current Pi session before leaving Plan mode.
@@ -171,6 +219,8 @@ Resume it later to inspect or hand off the ready/saved plan again; this delibera
171
219
  In-memory sessions create an unlinked fresh session because no parent file exists.
172
220
  Escape, Ctrl+C, menu disposal, source replacement/shutdown, model/auth failure, or cancellation by another extension before replacement leaves the source plan unchanged.
173
221
  Under **Off — conversation history only**, the destination receives the complete plan in its initial user prompt and does not persist active-plan state.
222
+ When a one-shot runtime choice exists, only that temporary non-model state is persisted and it is removed before the first request.
223
+ If that removal cannot be persisted, the request is not sent and can be retried after session persistence is available.
174
224
  If that kickoff fails, the complete request remains in the destination editor and the source remains resumable.
175
225
  Under either guaranteed-plan policy, the destination persists active-plan state before kickoff.
176
226
  If guaranteed-plan persistence fails, the complete request is placed in the destination editor and the source remains resumable.
@@ -251,10 +301,6 @@ Only the latest active Plan contract authorizes the helpers; inactive or stale c
251
301
  Plan mode does not widen a restrictive active-tool policy; start or restore fails when a required helper is unavailable.
252
302
  Stable schemas preserve a cache-eligible prefix but cannot guarantee a hit because provider serialization, cache lifetime, minimum prefix size, implementation details, and session affinity remain external.
253
303
 
254
- An explicit implementation model or thinking change is an intentional provider/cache boundary at handoff, not an ordinary-turn context rewrite.
255
- Preferences and fresh-session acknowledgements are non-model state; they do not add tool schemas or leading prompt instructions.
256
- Subsequent turns retain the existing append-only context behavior.
257
-
258
304
  The default `thinkingLevel: "inherit"` avoids a Plan-specific reasoning-parameter change.
259
305
  A fixed Plan thinking level remains supported, but changing reasoning parameters can prevent provider-side state reuse even when prompts and tool schemas stay stable.
260
306
 
@@ -295,19 +341,23 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
295
341
 
296
342
  ## ⚙️ Settings
297
343
 
298
- Open **Settings** from an inactive `/plan` menu, or edit `<getAgentDir()>/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`).
344
+ Run `/plan settings`, open **Settings** from an inactive `/plan` menu, or edit `<getAgentDir()>/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`).
299
345
  The optional file is read at session start and watched for changes; only an explicit save creates it.
300
346
 
301
347
  ```json
302
348
  {
303
349
  "thinkingLevel": "inherit",
304
350
  "implementationPlanRetention": "clear-on-start",
351
+ "defaultImplementationModel": {
352
+ "provider": "anthropic",
353
+ "modelId": "claude-sonnet-4-5"
354
+ },
355
+ "defaultImplementationThinkingLevel": "high",
305
356
  "defaultPlanExportPath": "PLAN.md"
306
357
  }
307
358
  ```
308
359
 
309
- By default, Plan mode inherits thinking, allows active safe built-ins, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
310
- Implementation model and thinking defaults are optional Settings rows; unset values keep existing behavior, including normal restoration of Plan-specific thinking.
360
+ By default, Plan mode inherits thinking, allows active safe built-ins, uses the planning model and thinking level for fresh implementation, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
311
361
  The shortcut is disabled unless configured.
312
362
  Settings saves apply to later workflows; an active implementation keeps its captured reinjection policy.
313
363
  The export destination affects the next export immediately.