@narumitw/pi-plan-mode 0.52.0 → 0.53.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
@@ -8,13 +8,13 @@ This independently installable extension adds a Codex-like `/plan` collaboration
8
8
 
9
9
  ## ✨ Features
10
10
 
11
- - Starts and manages Plan mode through `/plan`, `/plan <prompt>`, or the `--plan` startup flag.
12
- - Enables read-only exploration tools while blocking mutating tools and unsafe shell forms by default.
11
+ - Starts and manages Plan mode through `/plan`, `/plan start`, or `/plan <prompt>`.
12
+ - Defers Plan helper schemas until first use by default, then keeps the unlocked tool envelope stable while runtime policy blocks mutations and unsafe shell forms.
13
13
  - Requires structured questions for important ambiguity and explicit completion for a decision-ready plan.
14
14
  - Reviews the complete plan before implementation, export, save, continued planning, or discard.
15
15
  - Starts implementation in the planning session or a fresh linked session with the exact approved plan.
16
16
  - Persists Plan state and one saved plan across resume and compaction.
17
- - Exposes statusline state and configurable tool visibility, export destination, handoff behavior, shortcut, and thinking level.
17
+ - Exposes statusline state and a configurable Plan tool allowlist, export destination, plan reinjection, shortcut, and thinking level.
18
18
  - Cooperates anonymously with Workflow Mutex Protocol v1 participants so only one agent workflow starts in a session.
19
19
 
20
20
  ## 📦 Install
@@ -45,6 +45,32 @@ The package declares `dist/index.ts`, so an unbuilt local checkout must run the
45
45
  Run `/plan` to open the state-aware menu, then start Plan mode and ask the agent to inspect and design the change.
46
46
  Run `/plan <prompt>` when the first planning request is already known.
47
47
 
48
+ ## 🧱 Cache-stable mode transitions
49
+
50
+ Plan and Normal requests share one append-only conversation.
51
+ The extension appends one hidden, model-visible, versioned Plan contract before the first Plan prompt and one Normal contract before the first post-Plan Normal or implementation prompt.
52
+ Ordinary linear turns do not rewrite or duplicate these contracts.
53
+ **Implement here** therefore retains the Plan dialogue, structured questions, assistant tool calls, completion evidence, and `Implement the plan.` kickoff in order.
54
+ **Start fresh and implement** remains the explicit isolation path and transfers only the approved plan plus the Normal mode contract to a linked session.
55
+
56
+ The `context` hook filters legacy repeated `plan-mode-context` artifacts but preserves current transition messages.
57
+ When compaction removes the effective physical transition, the hook inserts one canonical fallback at a deterministic retained-history boundary.
58
+ Repeated transforms leave that fallback in place instead of moving it to the newest turn.
59
+ An inactive legacy state entry alone does not inject a Normal contract, so sessions that never entered Plan mode keep their ordinary context after resume or reload.
60
+ Manual `/tree` navigation restores branch-owned Plan state and chooses the matching effective contract without navigating automatically or adding a branch summary.
61
+ Pi currently lists hidden custom transition messages in `/tree`; Plan mode rejects those internal targets, so select an adjacent conversation entry instead.
62
+
63
+ The default `toolVisibility: "after-first-plan"` keeps `plan_mode_question` and `plan_mode_complete` registered but inactive until the first successful Plan activation in an extension runtime.
64
+ That activation appends the two helpers in canonical order and may cause one provider-prefix cache miss because `/plan` is a slash-command transition rather than a model-called deferred-tool loader.
65
+ The helpers and their active-only prompt metadata remain visible after that boundary across off, exit, save, export, implementation, and same-runtime session starts.
66
+ Failed, cancelled, stale, or workflow-busy activation restores the exact prior active-tool list and does not consume the first-activation boundary.
67
+ Choose `toolVisibility: "always"` to expose both helpers at session startup and preserve the previous stable-prefix behavior from the first request.
68
+ Neither choice guarantees a cache hit because provider serialization, cache lifetime, minimum cacheable prefix, implementation details, and session affinity still control reuse.
69
+ A user, Pi, or another extension can change the active tool set outside this extension's guarantee.
70
+
71
+ The default `thinkingLevel: "inherit"` path also avoids a Plan-specific reasoning-parameter change.
72
+ Choosing a fixed Plan thinking level remains supported, but switching reasoning parameters can prevent provider-side state reuse even when system instructions and tool schemas are stable.
73
+
48
74
  ## 💬 Commands
49
75
 
50
76
  ```text
@@ -63,16 +89,16 @@ Run `/plan <prompt>` when the first planning request is already known.
63
89
  In TUI and RPC, use bare `/plan` to open the menu for the current Plan state.
64
90
  When Plan mode is off and no plan is stored, the launch menu shows the effective next-start tools and offers **Start Plan mode**, **Choose tools, then start…**, **Settings**, and **How Plan mode works**.
65
91
  Settings edits the persistent defaults for later workflows.
66
- Launch-menu tool changes remain a draft until **Done — start Plan mode** is selected; Back, Escape, Ctrl+C, disposal, session replacement, and shutdown discard the draft without changing Plan state, active tools, thinking, or the stored selection.
92
+ Launch-menu policy changes remain a draft until **Done — start with this policy** is selected; Back, Escape, Ctrl+C, disposal, session replacement, and shutdown discard the draft without changing Plan state, active tools, thinking, or the stored selection.
67
93
 
68
94
  Use `/plan start` when you want to enter Plan mode directly without sending a model message.
69
95
  Use `/plan <prompt>` to enter Plan mode and immediately submit `<prompt>` as the first Plan-mode user message.
70
96
  The exact argument `start` is reserved for direct activation; longer text such as `/plan start a migration` remains an inline planning prompt.
71
- `--plan` also remains a direct activation path.
97
+ The extension does not register a startup flag; run `/plan start` after launch for direct activation.
72
98
 
73
- Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific override before Planning starts.
74
- Both routes use the same draft selector: **Done — start Plan mode** stores the selection and starts the workflow, while cancellation leaves Plan mode off and changes nothing.
75
- The bounded multi-select shows 10 rows at a time, supports viewport paging, descriptions, and explicit unavailable rows for blocked tools.
99
+ Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific Plan policy override before Planning starts.
100
+ Both routes use the same draft selector: **Done — start with this policy** stores the allowlist and starts the workflow, while cancellation leaves Plan mode off and changes nothing.
101
+ The bounded multi-select shows 10 rows at a time, supports viewport paging, descriptions, and explicit unavailable rows for blocked or currently inactive tools.
76
102
  In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC keeps the complete unfiltered list.
77
103
  Once Plan mode is active, tools are locked: `/plan` no longer offers tool or Settings actions, and `/plan tools` rejects the request.
78
104
  Exit and start a new workflow if a different tool set is required.
@@ -83,6 +109,10 @@ Completed and saved plan menus offer **Implement here**, which continues with th
83
109
  The direct `/plan implement` compatibility route remains equivalent to **Implement here** and never opens a selector.
84
110
  A successful ready-plan export also leaves Plan mode; saved and active implementation exports retain their existing state.
85
111
  `show`, `save`, `export`, and `implement` fail closed when no applicable plan is stored; `finalize` requires active Plan mode.
112
+ Pi executes extension commands immediately during streaming, but changing Plan state or handing off implementation during an active run would mix two mode contracts inside one run.
113
+ Plan mode therefore rejects busy start, exit, save, ready-plan export, implementation, state-changing menu action, and configured-shortcut transitions without changing state; wait for the run to settle and retry.
114
+ Prompts submitted while Plan mode is already active remain ordinary Plan follow-ups, and `/plan finalize` remains available as a Plan-preserving follow-up.
115
+ TUI and RPC show a warning for a rejected busy transition, while print and JSON routes throw an observable error.
86
116
 
87
117
  `/plan export` uses the configured **Export destination**, which defaults to `PLAN.md`.
88
118
  Supply a path to override that default for one export.
@@ -90,7 +120,7 @@ Relative paths resolve from the command's current `ctx.cwd` at export time, abso
90
120
  Explicit `/plan export <path>` input always wins over the setting.
91
121
  Export never overwrites an existing file, directory, or symbolic link: choose another path or remove the existing target first.
92
122
  A successful export adds one trailing newline but otherwise preserves the accepted Markdown exactly.
93
- After a ready plan is written, Plan mode ends, its tools and thinking level are restored, and the ready state is cleared without starting a model turn.
123
+ After a ready plan is written, Plan mode ends, its thinking level is restored, the current helper visibility is retained, and the ready state is cleared without starting a model turn.
94
124
  Exporting a saved or active implementation plan leaves that state unchanged.
95
125
  Failed or cancelled exports leave every Plan-mode state unchanged.
96
126
  The resulting file is available to the agent through its normal file-reading tools.
@@ -109,11 +139,15 @@ The agent may inspect files and run read-only commands, but it should not edit f
109
139
  It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
110
140
  Configure persistent defaults or a one-workflow tool override before activation; Planning and ready menus deliberately keep those controls locked.
111
141
 
112
- By default, Plan mode manages only Pi's built-in tools: `read`, limited `bash`, available read-only built-ins such as `grep`, `find`, and `ls`, plus the required `plan_mode_question` and `plan_mode_complete` tools.
113
- Built-in `edit` and `write` are blocked.
114
- `update_plan` is also blocked because it tracks execution progress rather than conversational planning.
115
- Extension and custom tools are disabled by default because Pi tools do not expose standardized mutability metadata; enable them before starting from Settings or the staged workflow selector only when you accept the risk.
116
- For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` if those extensions are loaded and you want to use them during planning.
142
+ Plan mode registers `plan_mode_question` and `plan_mode_complete` during extension load.
143
+ With the default **After first plan** visibility, `session_start` leaves both helpers inactive until the first admitted Plan workflow appends them in that order.
144
+ With **Always**, `session_start` appends missing helpers in the same canonical order.
145
+ Once revealed, ordinary Plan transitions never remove them during that extension runtime.
146
+ By default, the Plan policy allows active safe built-ins such as `read`, limited `bash`, `grep`, `find`, and `ls`.
147
+ Built-in `edit` and `write`, `update_plan`, inactive tools, and deselected tools are blocked at execution time even though active schemas remain visible.
148
+ Extension and custom tools are denied by default because Pi tools do not expose standardized mutability metadata; allow an already active custom tool before starting only when you accept the risk.
149
+ For example, you can opt into an active `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` tool when you want to use it during planning.
150
+ After they become visible, the Plan-only helpers remain visible in Normal mode, but their handlers and the `tool_call` policy reject calls unless Plan mode owns the active workflow.
117
151
 
118
152
  Limited `bash` uses a fail-closed policy, including when an extension overrides the canonical `bash` tool name.
119
153
  It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`.
@@ -136,8 +170,9 @@ The TUI rejects either field above 4,000 characters instead of truncating it.
136
170
  RPC keeps the existing sequential `select` and `editor` dialogs because Pi RPC cannot render custom TUI components.
137
171
  If you cancel or no interactive UI is available, the agent should ask a concise plain-text question or proceed only with a clearly stated low-risk assumption instead of prematurely producing a final plan.
138
172
 
139
- Pi activates tools by tool name.
140
- The pre-start selector stores accepted session selections by name and shows each effective tool's source from Pi metadata, such as `built-in`, a user extension path, or a project extension path.
173
+ Pi identifies tools by tool name.
174
+ The pre-start selector stores accepted session policy names and shows each effective tool's source from Pi metadata, such as `built-in`, a user extension path, or a project extension path.
175
+ A selected name can run in Plan mode only when that effective tool was already active at session startup.
141
176
  If an extension overrides a built-in tool with the same name, Pi exposes the effective tool for that name and the selector shows that source.
142
177
 
143
178
  A complete Plan mode answer should appear only after the agent has resolved discoverable facts and high-impact user decisions.
@@ -148,36 +183,41 @@ Its visible result contains the full plan, and versioned result details let the
148
183
  `plan_mode_complete` uses Pi's `terminate: true` hint.
149
184
  Termination is best effort: if a model puts it in a parallel tool batch, Pi terminates the batch early only when every finalized sibling tool also terminates.
150
185
  The prompt therefore requires the completion call to be standalone and last.
151
- The extension deliberately does not infer completion from phrases such as “I will present the plan,” and it does not automatically retry a turn with no plan because research and clarification turns may legitimately remain unfinished.
152
- If a turn ends without a plan, Plan mode stays active; use `/plan finalize` for explicit recovery.
186
+ The extension deliberately does not infer completion from phrases such as “I will present the plan,” and ordinary research or clarification turns never trigger automatic retries.
187
+ `/plan finalize` and its exact canonical finalization prompt are explicit recovery requests.
188
+ If one of those requests ends normally without a valid structured question or completed plan, Plan mode waits for `agent_settled` and retries once with stronger tool guidance.
189
+ A valid question, accepted completion, user cancellation, explicit exit, workflow supersession, reload, session replacement, or shutdown cancels the retry.
190
+ A second prose-only failure leaves Plan mode active, warns in interactive modes, and requires another explicit `/plan finalize` request.
153
191
 
154
192
  Legacy sessions and models may still submit one non-empty `<proposed_plan>` block with tags on their own lines.
155
193
  That compatibility path remains accepted, but it is not the primary workflow.
156
194
  Empty, malformed, unclosed, or multiple legacy blocks keep Plan mode active and produce a warning.
157
195
 
158
196
  After completion, `/plan` opens the ready actions when interactive UI is available.
159
- The same flat menu shows **Implement here** and **Start fresh and implement**, explains which conversation context each choice uses, and previews how long the approved plan will remain active.
160
- **Implement here**—and the compatibility route `/plan implement`—disables Plan mode, restores full tool access, captures the current **After Implement** policy, and starts implementation in the current session with its planning conversation.
197
+ 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.
198
+ **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.
161
199
  **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.
162
200
  The destination still loads its normal `AGENTS.md`, skills, project resources, and extensions.
163
- Choosing **Export plan…** asks for a destination, writes the plan, restores normal tools and thinking, and leaves Plan mode without starting a model turn.
201
+ 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.
164
202
  Choosing **Save for later**—or running `/plan save`—instead stores one plan in the current Pi session before leaving Plan mode.
165
203
 
166
- When a workflow was started only with `--plan` and no `/plan` command has run in that session, the automatic menu cannot obtain Pi's command-only session replacement capability; choosing fresh asks you to reopen `/plan`, where the same action is available.
204
+ When a resumed active Plan workflow completes before `/plan` has run in that resumed session, the automatic menu cannot obtain Pi's command-only session replacement capability; choosing fresh asks you to reopen `/plan`, where the same action is available.
167
205
  A successful fresh handoff does not delete or consume the source planning session.
168
206
  Resume it later to inspect or hand off the ready/saved plan again; this deliberate duplication is the recovery path if the destination work is abandoned.
169
207
  In-memory sessions create an unlinked fresh session because no parent file exists.
170
208
  Escape, Ctrl+C, menu disposal, source replacement/shutdown, model/auth failure, or cancellation by another extension before replacement leaves the source plan unchanged.
171
- Once replacement succeeds, the destination persists active-plan state before kickoff.
172
- If persistence fails, the complete request is placed in the destination editor and the source remains resumable.
173
- If kickoff fails, the destination retains the active plan; send a message to continue, use `/plan exit` to clear it, or resume the parent planning session.
209
+ Under **Off — conversation history only**, the destination receives the complete plan in its initial user prompt and does not persist active-plan state.
210
+ If that kickoff fails, the complete request remains in the destination editor and the source remains resumable.
211
+ Under either guaranteed-plan policy, the destination persists active-plan state before kickoff.
212
+ If guaranteed-plan persistence fails, the complete request is placed in the destination editor and the source remains resumable.
213
+ If a guaranteed-plan kickoff fails, the destination retains the active plan; send a message to continue, use `/plan exit` to clear it, or resume the parent planning session.
174
214
 
175
215
  A saved plan appears as `plan saved` and remains available after reload, resume, branch-local fork, and compaction in that session.
176
216
  It does not expire automatically, cross into a new session, or participate in ordinary model context.
177
217
  Open `/plan` to Show, Implement here, Start fresh and implement, Export, open Settings, or Clear it; `/plan show`, `/plan implement`, `/plan export [path]`, and `/plan exit`/`off` retain their direct routes in TUI and RPC.
178
218
  Fresh implementation checks idle state, the selected model, and authentication before session replacement; Implement here keeps its established preflight behavior.
179
219
  Starting another workflow with `/plan start`, `/plan <prompt>`, or `/plan tools` is blocked until the saved plan is implemented or cleared, so the single saved slot is never silently overwritten.
180
- Resuming that session with `--plan` moves the saved plan back to ready Plan mode.
220
+ Resuming that session keeps the plan saved; open `/plan` to review, implement, export, or clear it.
181
221
  Cancellation or failed implementation preflight leaves it unchanged.
182
222
 
183
223
  Text print and JSON modes cannot display the bare `/plan` menu and reject that route before changing state; use `/plan start` for direct no-prompt activation or `/plan <prompt>` to start planning with a prompt.
@@ -187,20 +227,24 @@ Successful export is observable through the created file; exporting a ready plan
187
227
  An existing target or missing plan fails the command without changing state.
188
228
  These modes reject saved-plan display and implementation before changing state because Pi provides neither printable custom-message output nor acknowledged extension-triggered turns; resume the session in TUI or RPC to show or implement it.
189
229
 
190
- Both implementation paths apply the current **After Implement** policy in their destination; the fresh-session choice does not change retention semantics.
191
- With the default **Keep plan active** policy, the exact accepted plan remains active across later turns, session resume, and manual or automatic compaction without depending on the compaction summary.
192
- Plan mode avoids a duplicate context block while the original implementation handoff remains available and injects one hidden canonical copy after that handoff is compacted away.
193
- This can consume up to the existing 50,000-character plan limit in model context when reinjection is needed.
194
- **Use plan for handoff only** clears retained state immediately after the first implementation request receives the complete plan.
195
- **Clear after first implementation run** keeps the plan through that run, including retries, compaction retries, and queued continuation, then clears it at `agent_settled`.
230
+ Both implementation paths apply the current **Plan reinjection** policy in their destination.
231
+ The default **Off — conversation history only** policy does not create active-plan state or inject a hidden plan context.
232
+ Implement here sends `Implement the plan.` and leaves the accepted plan in ordinary planning history.
233
+ Start fresh and implement, or implementing a saved plan here, puts the complete plan in one ordinary initial user prompt because no reliable planning conversation is present.
234
+ Later model calls then rely on Pi's normal conversation history and compaction behavior.
235
+ **Through first implementation run** guarantees the exact plan throughout that run, including retries, compaction retries, and queued continuation, then clears active-plan state at `agent_settled`.
236
+ **Until manually cleared** guarantees the exact plan across later turns, resume, and manual or automatic compaction until `/plan exit` or supersession.
237
+ The guaranteed policies avoid a duplicate context block while the original implementation handoff remains available and inject one hidden canonical copy after that handoff is compacted away.
238
+ Reinjection can consume up to the existing 50,000-character plan limit in model context.
196
239
  Cleanup is bound to the matching implementation, so an older run settling cannot clear a newer handoff.
197
240
 
198
- While implementation is active, `/plan show` displays the accepted plan.
241
+ While a guaranteed plan is active, `/plan show` displays the accepted plan.
199
242
  Interactive `/plan` offers Show, Export plan…, Settings, Start a new plan, and Clear; `/plan exit` and `/plan off` are the direct clear routes.
200
- Settings changes never alter the policy already captured by the active implementation.
201
- Automatic cleanup has the same observable result as clearing: its active status and future injected plan context disappear, while the implementation request that triggered cleanup still receives the complete plan.
202
- Starting a new Plan-mode workflow or implementing a replacement plan supersedes the previous active plan.
203
- The extension deliberately does not infer completion from assistant prose or agent settlement, so clear the active plan when the implementation no longer applies.
243
+ Settings changes never alter the policy already captured by an active guaranteed-plan implementation.
244
+ Automatic first-run cleanup removes the active status and future injected context after the triggering implementation run has received the complete plan.
245
+ Starting a new Plan-mode workflow or implementing a replacement plan supersedes an active guaranteed plan.
246
+ The extension deliberately does not infer completion from assistant prose or agent settlement under **Until manually cleared**, so clear the active plan when it no longer applies.
247
+ Under **Off — conversation history only**, implementation messages remain ordinary conversation history and there is no active plan for `/plan exit` to remove.
204
248
  Choosing Stay before implementation keeps the plan ready.
205
249
  Revision feedback starts another Plan-mode turn and clears the previous implementable plan until an updated completion arrives.
206
250
  For clarification-only follow-ups, the agent answers and resubmits the complete unchanged plan so it remains implementable.
@@ -212,11 +256,11 @@ With `@narumitw/pi-statusline`, this appears in the extension status area:
212
256
  - `plan active`: Plan mode is enabled and still gathering context or drafting a plan.
213
257
  - `plan ready`: A completed plan is stored until you implement it, export it, save it, continue planning, or exit Plan mode.
214
258
  - `plan saved`: One completed plan is stored outside model context in the current session until you implement or clear it.
215
- - `plan implementing`: The exact accepted plan is currently retained under its captured **After Implement** policy.
259
+ - `plan implementing`: The exact accepted plan is guaranteed under **Through first implementation run** or **Until manually cleared**.
216
260
 
217
261
  You can also exit directly.
218
262
  Before implementation, direct exit discards the latest proposed plan; while a plan is saved, it clears that saved plan.
219
- During implementation, it removes both the original implementation handoff and the extension's canonical active-plan block from later model calls; an earlier Pi-generated compaction summary may still describe prior work:
263
+ During a guaranteed-plan implementation, it removes both the original implementation handoff and the extension's canonical active-plan block from later model calls; an earlier Pi-generated compaction summary may still describe prior work:
220
264
 
221
265
  ```text
222
266
  /plan exit
@@ -232,11 +276,11 @@ Saved plans and ordinary implementation after Plan handoff do not hold the group
232
276
  Every inactive start performs one final synchronous admission after asynchronous preflight and before changing Plan state, persistence, prompts, tools, thinking level, queues, or status.
233
277
  If another participant is active, TUI and RPC show an anonymous warning that another workflow is active.
234
278
  Print and JSON direct routes throw the same anonymous error before mutation.
235
- Launch-menu, selected-tool, shortcut, startup-flag, active-implementation **Start a new plan**, and restored activation use the same admission boundary.
279
+ Launch-menu, selected-tool, shortcut, active-implementation **Start a new plan**, and restored activation use the same admission boundary.
236
280
  A rejected selected-tool launch does not save its draft choices.
237
281
 
238
282
  Restored active Plan state acquires before restoring restrictive tools, thinking, status, or model hooks.
239
- If restoration is busy, Plan mode stays non-running, leaves persisted history untouched, does not alter active tools, and requires a later reload or explicit new start after the other workflow ends.
283
+ If restoration is busy, Plan mode stays non-running, leaves persisted history and active tools untouched, and requires a later reload or explicit new start after the other workflow ends.
240
284
  Planning-session cancellation during a fresh implementation preflight keeps the source Plan and its ownership.
241
285
  Successful session replacement relies on source-session shutdown to clean up and release; the destination's ordinary active implementation does not acquire the Plan mutex.
242
286
 
@@ -258,7 +302,7 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
258
302
 
259
303
  ## ⚙️ Settings
260
304
 
261
- Open **Settings** from an inactive `/plan` menu to edit one flat group of five workflow choices: **Plan thinking**, **Plan tools**, **After Implement**, **Export destination**, and **Plan mode shortcut**.
305
+ Open **Settings** from an inactive `/plan` menu to edit one flat group of six workflow choices: **Plan thinking**, **Plan policy tools**, **Plan reinjection**, **Export destination**, **Plan mode shortcut**, and **Plan tools**.
262
306
  You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
263
307
  `safeSubcommands` remains JSON-only.
264
308
  You can change the Plan-mode shortcut with `toggleShortcut` as long as the file remains JSON-only and uses a valid key string.
@@ -267,8 +311,9 @@ When omitted, the shortcut is disabled by default.
267
311
  ```json
268
312
  {
269
313
  "thinkingLevel": "inherit",
314
+ "toolVisibility": "after-first-plan",
270
315
  "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
271
- "implementationPlanRetention": "keep",
316
+ "implementationPlanRetention": "clear-on-start",
272
317
  "defaultPlanExportPath": "PLAN.md",
273
318
  "safeSubcommands": {
274
319
  "git": ["status", "log", "rev-parse", "blame"],
@@ -278,37 +323,52 @@ When omitted, the shortcut is disabled by default.
278
323
  }
279
324
  ```
280
325
 
281
- ### Default Plan tools
326
+ ### Plan helper visibility
282
327
 
283
- `defaultPlanTools` defines the initial tool selection when a session has no stored pre-start selection.
284
- Omit it—or choose **Use automatic safe built-ins**—to keep the available safe built-ins as the default.
285
- An explicit empty array appears as **Required tools only** and enables only `plan_mode_question` and `plan_mode_complete`.
328
+ `toolVisibility` accepts `"after-first-plan"` or `"always"`.
329
+ Omit it—or choose **After first plan**—to keep both Plan helpers out of model requests until the first successful Plan activation in that extension runtime.
330
+ A successful activation keeps the helpers visible for the rest of that runtime; changing the setting back to **After first plan** while inactive resets and hides them at an idle, mutex-admitted boundary.
331
+ Choose **Always** to make the helpers model-visible at session startup and avoid the lazy first-use prefix change.
332
+ Settings-menu changes apply and persist immediately only after idle and Workflow Mutex admission; failure restores the prior runtime and displayed value.
333
+ Manual file changes reload automatically and apply visibility when the session is inactive, idle, and mutex-admitted.
334
+ An unsafe manual reload keeps the current tool envelope until the next session start or successful Plan activation.
335
+ A restored active Plan reveals its helpers only after acquiring workflow ownership, while a busy restore leaves active tools untouched.
336
+ This setting uses ordinary active-tool activation and does not claim Pi native deferred loading.
337
+
338
+ ### Default Plan policy tools
339
+
340
+ `defaultPlanTools` defines the initial runtime allowlist when a session has no stored pre-start selection.
341
+ Omit it—or choose **Use automatic safe built-ins**—to allow already-active safe built-ins by default.
342
+ An explicit empty array appears as **No optional tools** and denies every ordinary tool while the required helpers remain callable in Plan mode.
343
+ Neither setting changes model-visible tool schemas.
286
344
 
287
345
  Tool names must be non-empty strings; duplicates are removed in first-seen order.
288
- Unknown, unavailable, and Plan-mode-blocked names are ignored when tools are activated.
289
- Settings retains configured unavailable names and shows them as unavailable; resetting to automatic removes the entire override.
290
- A tool registered after Plan mode is already active is not added automatically; exit and start a new Plan workflow to apply another set.
291
- Non-built-in tools named in this global setting are an explicit user-risk opt-in, just like selecting them in the pre-start workflow selector.
292
- Plan mode does not interpret their arguments or actions: enabling one trusts the whole effective tool.
346
+ Unknown, inactive, and Plan-mode-blocked names are unavailable to the policy and never become active merely by entering Plan mode.
347
+ Settings retains configured inactive names and shows them as unavailable; resetting to automatic removes the entire override.
348
+ An ordinary tool registered or activated after the startup baseline is outside the current workflow policy; start a later session to include it in the selectable baseline.
349
+ Non-built-in names in this global setting are an explicit user-risk opt-in, just like selecting them in the pre-start workflow selector.
350
+ Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
293
351
  Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
294
- An effective tool named `bash` remains subject to the limited-shell policy regardless of its source metadata.
352
+ An effective active tool named `bash` remains subject to the limited-shell policy regardless of its source metadata.
295
353
 
296
354
  A selection accepted through **Choose tools, then start…** or `/plan tools` is stored in that Pi session and takes precedence over `defaultPlanTools` when the session resumes.
297
- The global setting remains the baseline for fresh sessions and sessions without an explicit selection.
298
- Settings saves immediately, but the saved tools and thinking level apply only when a later Plan workflow starts; they never mutate a workflow already in progress.
299
-
300
- ### After Implement
301
-
302
- `implementationPlanRetention` controls the result of the next Implement action.
303
- Omit it or use `keep` for **Keep plan active**, the backward-compatible behavior that retains and reinjects the exact plan until `/plan exit` or supersession.
304
- Use `clear-on-start` for **Use plan for handoff only**: the first matching implementation request receives the complete plan, then retained state clears before later requests.
305
- Use `clear-after-first-run` to retain the plan until that implementation's first fully settled run ends.
306
- A resumed cleanup policy re-arms against the first context in the replacement session.
355
+ The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
356
+ Settings saves immediately, but saved policy names and thinking apply only when a later Plan workflow starts; they never mutate active schemas or a workflow already in progress.
357
+
358
+ ### Plan reinjection
359
+
360
+ The stable JSON field `implementationPlanRetention` controls whether and how long the `context` hook restores the exact approved plan when ordinary model context no longer contains it.
361
+ Omit it or use `clear-on-start` for **Off — conversation history only**, the default Codex-like behavior with no active-plan state or hidden context injection.
362
+ In the planning session, this policy sends `Implement the plan.` and relies on the accepted plan already present in ordinary conversation history.
363
+ A fresh session or saved-plan implementation instead places the complete plan in one ordinary kickoff prompt because its planning history is unavailable or intentionally excluded.
364
+ Use `clear-after-first-run` for **Through first implementation run** to guarantee the exact plan until that implementation's first fully settled run ends.
365
+ Use `keep` for **Until manually cleared** to guarantee and reinject the exact plan until `/plan exit` or supersession.
366
+ A resumed guaranteed-plan cleanup policy re-arms against the first context in the replacement session.
307
367
  Failed handoff delivery restores the ready or saved plan and does not run automatic cleanup.
308
368
 
309
369
  Changing this setting applies to the next Implement action only.
310
- Each active implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
311
- `/plan exit` remains available under every policy.
370
+ Each guaranteed-plan implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
371
+ Conversation-history-only implementation has no active Plan-mode state to show, export, or clear after kickoff.
312
372
 
313
373
  ### Export destination
314
374
 
@@ -396,7 +456,7 @@ A missing file stays absent until an explicit save.
396
456
  Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
397
457
  This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
398
458
 
399
- Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `keep`, and `PLAN.md`.
459
+ Invalid settings produce a warning and fall back to inherited thinking, `after-first-plan` helper visibility, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
400
460
  Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
401
461
  If Settings is explicitly saved while only that legacy file exists, the extension creates canonical `pi-plan-mode.json` from the complete legacy document, applies the selected change, preserves unknown fields, and leaves the legacy file untouched.
402
462
  If both files exist, the canonical filename takes precedence.
@@ -410,8 +470,10 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
410
470
  - The agent should use `plan_mode_question` for important non-discoverable preferences or tradeoffs before finalizing.
411
471
  - The agent completes with a standalone `plan_mode_complete` tool call instead of relying on semantic prose detection.
412
472
  - `update_plan` checklist use is blocked while Plan mode is active.
413
- - The implementation boundary is explicit: Plan mode restores tools before saving or starting implementation, saving keeps the plan outside ordinary model context, choosing implementation immediately triggers a normal agent turn with full tool access, and the accepted plan follows the captured `keep`, `clear-on-start`, or `clear-after-first-run` lifecycle.
473
+ - The implementation boundary is explicit: Plan mode appends the Normal contract and lifts its runtime allowlist before saving or starting implementation, while revealed helpers remain active.
474
+ - The default `clear-on-start` policy follows Codex by using ordinary conversation history only; `clear-after-first-run` and `keep` add explicit exact-plan guarantees.
414
475
  - Pi extension safety is approximated with tool classification and fail-closed filtering for every effective tool named `bash`; other non-built-in tools remain user-selected at user risk because Pi does not expose standardized tool mutability metadata.
476
+ - Plan and Normal instructions are append-only conversation contracts; **Always** keeps tool schemas stable from startup, while **After first plan** intentionally changes the helper schema and prompt-metadata prefix once before keeping it stable.
415
477
  - Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
416
478
 
417
479
  ## 🗂️ Package layout