@narumitw/pi-plan-mode 0.54.0 → 0.55.1

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
@@ -9,7 +9,7 @@ This independently installable extension adds a Codex-like `/plan` collaboration
9
9
  ## ✨ Features
10
10
 
11
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.
12
+ - Keeps Plan helper schemas stable from startup while runtime policy blocks inactive helpers, 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.
@@ -61,13 +61,11 @@ An inactive legacy state entry alone does not inject a Normal contract, so sessi
61
61
  Manual `/tree` navigation restores branch-owned Plan state and chooses the matching effective contract without navigating automatically or adding a branch summary.
62
62
  Pi currently lists hidden custom transition messages in `/tree`; Plan mode rejects those internal targets, so select an adjacent conversation entry instead.
63
63
 
64
- 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.
65
- 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.
66
- The helpers and their active-only prompt metadata remain visible after that boundary across off, exit, save, export, implementation, and same-runtime session starts.
67
- Failed, cancelled, stale, or workflow-busy activation restores the exact prior active-tool list and does not consume the first-activation boundary.
68
- Choose `toolVisibility: "always"` to expose both helpers at session startup and preserve the previous stable-prefix behavior from the first request.
69
- Neither choice guarantees a cache hit because provider serialization, cache lifetime, minimum cacheable prefix, implementation details, and session affinity still control reuse.
70
- A user, Pi, or another extension can change the active tool set outside this extension's guarantee.
64
+ Plan mode registers `plan_mode_question` and `plan_mode_complete` once and keeps their names and definitions stable across Normal, Plan, ready, implementation, and restored workflows.
65
+ Visible helpers do not mean `/plan` is active, and their global descriptions explicitly exclude ordinary planning, the `writing-plans` skill, roadmaps, checklists, and plan-file work.
66
+ Positive helper instructions live only in the latest effective active Plan contract, while inactive or stale calls fail without accepting a plan or opening question UI.
67
+ Plan mode never widens a restrictive active-tool policy; start or restore fails when a required helper is unavailable.
68
+ Stable schemas preserve a cache-eligible prefix but cannot guarantee a hit because provider serialization, cache lifetime, minimum cacheable prefix, implementation details, and session affinity remain external.
71
69
 
72
70
  The default `thinkingLevel: "inherit"` path also avoids a Plan-specific reasoning-parameter change.
73
71
  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.
@@ -99,7 +97,9 @@ The extension does not register a startup flag; run `/plan start` after launch f
99
97
 
100
98
  Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific Plan policy override before Planning starts.
101
99
  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.
102
- The bounded multi-select shows 10 rows at a time, supports viewport paging, descriptions, and explicit unavailable rows for blocked or currently inactive tools.
100
+ The bounded multi-select shows 10 rows at a time, supports viewport paging, descriptions, and explicit unavailable rows for blocked, currently inactive, or configured but not-yet-registered tools.
101
+ Configured or previously selected names without current metadata appear as pending registration and remain selected for first-request resolution.
102
+ Reopen the picker to refresh tools registered while it was closed because Pi exposes no live tool-registration event.
103
103
  In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC keeps the complete unfiltered list.
104
104
  Once Plan mode is active, tools are locked: `/plan` no longer offers tool or Settings actions, and `/plan tools` rejects the request.
105
105
  Exit and start a new workflow if a different tool set is required.
@@ -121,7 +121,7 @@ Relative paths resolve from the command's current `ctx.cwd` at export time, abso
121
121
  Explicit `/plan export <path>` input always wins over the setting.
122
122
  Export never overwrites an existing file, directory, or symbolic link: choose another path or remove the existing target first.
123
123
  A successful export adds one trailing newline but otherwise preserves the accepted Markdown exactly.
124
- 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.
124
+ After a ready plan is written, Plan mode ends, its thinking level is restored, the stable helper envelope is unchanged, and the ready state is cleared without starting a model turn.
125
125
  Exporting a saved or active implementation plan leaves that state unchanged.
126
126
  Failed or cancelled exports leave every Plan-mode state unchanged.
127
127
  The resulting file is available to the agent through its normal file-reading tools.
@@ -140,15 +140,13 @@ The agent may inspect files and run read-only commands, but it should not edit f
140
140
  It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
141
141
  Configure persistent defaults or a one-workflow tool override before activation; Planning and ready menus deliberately keep those controls locked.
142
142
 
143
- Plan mode registers `plan_mode_question` and `plan_mode_complete` during extension load.
144
- With the default **After first plan** visibility, `session_start` leaves both helpers inactive until the first admitted Plan workflow appends them in that order.
145
- With **Always**, `session_start` appends missing helpers in the same canonical order.
146
- Once revealed, ordinary Plan transitions never remove them during that extension runtime.
143
+ Plan mode registers `plan_mode_question` and `plan_mode_complete` during extension load and never changes their active status itself.
144
+ Another active-tool policy may hide them, in which case Plan start or restore fails without widening that policy.
147
145
  By default, the Plan policy allows active safe built-ins such as `read`, limited `bash`, limited `powershell`, `grep`, `find`, and `ls`.
148
- The optional native `powershell` tool must already be active, for example through Pi's Windows `defaultTools` setting, before Plan mode can select it.
149
- Built-in `edit` and `write`, `update_plan`, inactive tools, and deselected tools are blocked at execution time even though active schemas remain visible.
150
- 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.
151
- For example, you can opt into an active `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` tool when you want to use it during planning.
146
+ The optional native `powershell` tool must be active when an automatic Plan policy starts, for example through Pi's Windows `defaultTools` setting, unless its name was explicitly retained for first-request resolution.
147
+ Built-in `edit` and `write`, `update_plan`, tools still inactive at the first request, 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; explicitly allow a custom-tool name before starting only when you accept the risk.
149
+ For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` when you want to use the effective active tool during planning.
152
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.
153
151
 
154
152
  Limited `bash` uses a fail-closed Bash policy, including when an extension overrides the canonical `bash` tool name.
@@ -181,7 +179,8 @@ If you cancel or no interactive UI is available, the agent should ask a concise
181
179
 
182
180
  Pi identifies tools by tool name.
183
181
  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.
184
- A selected name can run in Plan mode only when that effective tool was already active at session startup.
182
+ A selected name can run in Plan mode only when Pi has registered and activated the effective selectable tool by that workflow's first provider-bound context.
183
+ The allowlist freezes at that boundary, so a tool registered or activated later waits for the next Plan workflow.
185
184
  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.
186
185
 
187
186
  A complete Plan mode answer should appear only after the agent has resolved discoverable facts and high-impact user decisions.
@@ -311,7 +310,7 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
311
310
 
312
311
  ## ⚙️ Settings
313
312
 
314
- 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**.
313
+ Open **Settings** from an inactive `/plan` menu to edit one flat group of five workflow choices: **Plan thinking**, **Plan policy tools**, **Plan reinjection**, **Export destination**, and **Plan mode shortcut**.
315
314
  You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
316
315
  `safeSubcommands` remains JSON-only.
317
316
  You can change the Plan-mode shortcut with `toggleShortcut` as long as the file remains JSON-only and uses a valid key string.
@@ -320,7 +319,6 @@ When omitted, the shortcut is disabled by default.
320
319
  ```json
321
320
  {
322
321
  "thinkingLevel": "inherit",
323
- "toolVisibility": "after-first-plan",
324
322
  "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
325
323
  "implementationPlanRetention": "clear-on-start",
326
324
  "defaultPlanExportPath": "PLAN.md",
@@ -332,17 +330,12 @@ When omitted, the shortcut is disabled by default.
332
330
  }
333
331
  ```
334
332
 
335
- ### Plan helper visibility
333
+ ### Plan helper tools
336
334
 
337
- `toolVisibility` accepts `"after-first-plan"` or `"always"`.
338
- 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.
339
- 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.
340
- Choose **Always** to make the helpers model-visible at session startup and avoid the lazy first-use prefix change.
341
- Settings-menu changes apply and persist immediately only after idle and Workflow Mutex admission; failure restores the prior runtime and displayed value.
342
- Manual file changes reload automatically and apply visibility when the session is inactive, idle, and mutex-admitted.
343
- An unsafe manual reload keeps the current tool envelope until the next session start or successful Plan activation.
344
- A restored active Plan reveals its helpers only after acquiring workflow ownership, while a busy restore leaves active tools untouched.
345
- This setting uses ordinary active-tool activation and does not claim Pi native deferred loading.
335
+ Plan helper schemas are stable from extension registration onward, and Plan mode does not call `setActiveTools()`.
336
+ Tool visibility alone is not Plan activation.
337
+ Only the latest effective active Plan contract authorizes `plan_mode_question` or `plan_mode_complete`; ordinary planning and the `writing-plans` skill use their own workflow instead.
338
+ The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved or a legacy settings file is migrated.
346
339
 
347
340
  ### Default Plan policy tools
348
341
 
@@ -352,9 +345,13 @@ An explicit empty array appears as **No optional tools** and denies every ordina
352
345
  Neither setting changes model-visible tool schemas.
353
346
 
354
347
  Tool names must be non-empty strings; duplicates are removed in first-seen order.
355
- Unknown, inactive, and Plan-mode-blocked names are unavailable to the policy and never become active merely by entering Plan mode.
356
- Settings retains configured inactive names and shows them as unavailable; resetting to automatic removes the entire override.
357
- 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.
348
+ Explicit configured or session-selected names remain policy intent when their tool is unknown or inactive, but Plan mode never registers or activates them.
349
+ The inactive menu takes a fresh registered and active tool snapshot each time it opens, while an already open picker does not update in place.
350
+ At the workflow's first provider-bound context, after every `before_agent_start` handler has settled, Plan mode resolves retained names against Pi's live registered and active tools and freezes the executable allowlist.
351
+ Automatic defaults recheck the effective source metadata at that boundary, so a custom override of a safe built-in name still requires explicit opt-in.
352
+ The resolved allowlist persists with the active workflow and restores without reopening the resolution boundary after reload, resume, or tree navigation.
353
+ Unknown, inactive, and Plan-mode-blocked names remain unavailable after that resolution, and a later registration or activation waits for the next Plan workflow rather than a new session.
354
+ Settings shows unresolved names as pending registration; resetting to automatic removes the entire override.
358
355
  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.
359
356
  Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
360
357
  Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
@@ -465,7 +462,7 @@ A missing file stays absent until an explicit save.
465
462
  Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
466
463
  This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
467
464
 
468
- 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`.
465
+ Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
469
466
  Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
470
467
  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.
471
468
  If both files exist, the canonical filename takes precedence.
@@ -482,7 +479,7 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
482
479
  - 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.
483
480
  - 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.
484
481
  - Pi extension safety is approximated with tool classification and separate fail-closed filtering for every effective tool named `bash` or `powershell`; other non-built-in tools remain user-selected at user risk because Pi does not expose standardized tool mutability metadata.
485
- - 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.
482
+ - Plan and Normal instructions are append-only conversation contracts, while helper schemas stay stable from startup and visible helpers remain inactive without the latest effective Plan contract.
486
483
  - Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
487
484
 
488
485
  ## 🗂️ Package layout