@narumitw/pi-plan-mode 0.53.0 → 0.55.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
@@ -9,17 +9,18 @@ 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.
16
16
  - Persists Plan state and one saved plan across resume and compaction.
17
- - Exposes statusline state and a configurable Plan tool allowlist, export destination, plan reinjection, shortcut, and thinking level.
17
+ - Exposes statusline state and a configurable Plan tool allowlist, including reviewed native PowerShell inspection on Windows, plus 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
21
21
 
22
22
  This release requires Pi 0.80.6 or newer.
23
+ Native PowerShell tool support requires Pi 0.84.3 or newer on Windows; earlier Pi versions omit that optional tool and retain the existing Plan policy.
23
24
 
24
25
  ```bash
25
26
  pi install npm:@narumitw/pi-plan-mode
@@ -60,13 +61,11 @@ An inactive legacy state entry alone does not inject a Normal contract, so sessi
60
61
  Manual `/tree` navigation restores branch-owned Plan state and chooses the matching effective contract without navigating automatically or adding a branch summary.
61
62
  Pi currently lists hidden custom transition messages in `/tree`; Plan mode rejects those internal targets, so select an adjacent conversation entry instead.
62
63
 
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.
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.
70
69
 
71
70
  The default `thinkingLevel: "inherit"` path also avoids a Plan-specific reasoning-parameter change.
72
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.
@@ -120,7 +119,7 @@ Relative paths resolve from the command's current `ctx.cwd` at export time, abso
120
119
  Explicit `/plan export <path>` input always wins over the setting.
121
120
  Export never overwrites an existing file, directory, or symbolic link: choose another path or remove the existing target first.
122
121
  A successful export adds one trailing newline but otherwise preserves the accepted Markdown exactly.
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.
122
+ 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.
124
123
  Exporting a saved or active implementation plan leaves that state unchanged.
125
124
  Failed or cancelled exports leave every Plan-mode state unchanged.
126
125
  The resulting file is available to the agent through its normal file-reading tools.
@@ -139,22 +138,28 @@ The agent may inspect files and run read-only commands, but it should not edit f
139
138
  It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
140
139
  Configure persistent defaults or a one-workflow tool override before activation; Planning and ready menus deliberately keep those controls locked.
141
140
 
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`.
141
+ Plan mode registers `plan_mode_question` and `plan_mode_complete` during extension load and never changes their active status itself.
142
+ Another active-tool policy may hide them, in which case Plan start or restore fails without widening that policy.
143
+ By default, the Plan policy allows active safe built-ins such as `read`, limited `bash`, limited `powershell`, `grep`, `find`, and `ls`.
144
+ The optional native `powershell` tool must already be active, for example through Pi's Windows `defaultTools` setting, before Plan mode can select it.
147
145
  Built-in `edit` and `write`, `update_plan`, inactive tools, and deselected tools are blocked at execution time even though active schemas remain visible.
148
146
  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
147
  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
148
  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.
151
149
 
152
- Limited `bash` uses a fail-closed policy, including when an extension overrides the canonical `bash` tool name.
150
+ Limited `bash` uses a fail-closed Bash policy, including when an extension overrides the canonical `bash` tool name.
153
151
  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`.
154
152
  It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands.
153
+
154
+ Limited `powershell` uses a separate fail-closed PowerShell policy, including when an extension overrides the canonical `powershell` tool name.
155
+ It accepts canonical inspection cmdlets such as `Get-ChildItem`, `Get-Content`, `Get-Item`, `Get-Location`, `Resolve-Path`, `Select-String`, `Test-Path`, `Measure-Object`, `Sort-Object`, `Format-List`, `Format-Table`, `Out-String`, and `Write-Output`.
156
+ It also accepts the same reviewed `git` and configured `gh` queries as limited Bash, including pipelines and semicolon-delimited command lists composed entirely of accepted commands.
157
+ It rejects redirects, variables, substitutions, script blocks, call operators, type or method expressions, stop-parsing tokens, multiline input, non-ASCII quotation delimiters, aliases, mutating cmdlets, and unknown commands.
158
+ Use canonical cmdlet names because PowerShell aliases are intentionally outside the reviewed policy.
159
+
155
160
  A rejected parsed command list or pipeline identifies its first blocked command segment; malformed or unsupported shell syntax reports the complete submitted input instead.
156
161
  Tests and builds may still write ignored caches or build artifacts and may execute project-defined hooks; enable or invoke them only when the repository is trusted.
157
- This is extension-level risk reduction, not an OS sandbox.
162
+ Both limited-shell policies are extension-level risk reduction, not an OS sandbox or confidentiality boundary.
158
163
 
159
164
  `plan_mode_question` follows Codex's `request_user_input` pattern: the agent can ask 1-3 concise questions, each with meaningful options and a free-form Other path.
160
165
  In TUI mode, a single question shows its header as plain muted text, submits as soon as its preset or custom answer is confirmed, and does not show tabs, Review, or question-navigation controls.
@@ -302,7 +307,7 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
302
307
 
303
308
  ## ⚙️ Settings
304
309
 
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**.
310
+ 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**.
306
311
  You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
307
312
  `safeSubcommands` remains JSON-only.
308
313
  You can change the Plan-mode shortcut with `toggleShortcut` as long as the file remains JSON-only and uses a valid key string.
@@ -311,7 +316,6 @@ When omitted, the shortcut is disabled by default.
311
316
  ```json
312
317
  {
313
318
  "thinkingLevel": "inherit",
314
- "toolVisibility": "after-first-plan",
315
319
  "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
316
320
  "implementationPlanRetention": "clear-on-start",
317
321
  "defaultPlanExportPath": "PLAN.md",
@@ -323,17 +327,12 @@ When omitted, the shortcut is disabled by default.
323
327
  }
324
328
  ```
325
329
 
326
- ### Plan helper visibility
330
+ ### Plan helper tools
327
331
 
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.
332
+ Plan helper schemas are stable from extension registration onward, and Plan mode does not call `setActiveTools()`.
333
+ Tool visibility alone is not Plan activation.
334
+ 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.
335
+ The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved or a legacy settings file is migrated.
337
336
 
338
337
  ### Default Plan policy tools
339
338
 
@@ -349,7 +348,7 @@ An ordinary tool registered or activated after the startup baseline is outside t
349
348
  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
349
  Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
351
350
  Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
352
- An effective active tool named `bash` remains subject to the limited-shell policy regardless of its source metadata.
351
+ An effective active tool named `bash` or `powershell` remains subject to its limited-shell policy regardless of its source metadata.
353
352
 
354
353
  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.
355
354
  The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
@@ -392,7 +391,7 @@ Avoid values that conflict with editor shortcuts.
392
391
 
393
392
  ### Safe shell subcommands
394
393
 
395
- `safeSubcommands` adds reviewed command validators to limited `bash`; it is not a raw shell allowlist.
394
+ `safeSubcommands` adds reviewed command validators to limited `bash` and `powershell`; it is not a raw shell allowlist.
396
395
  Only the following exact values are accepted:
397
396
 
398
397
  - `git`: `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, `grep`, `rev-parse`, `blame`, `describe`, `merge-base`, `ls-tree`, and `cat-file`.
@@ -456,7 +455,7 @@ A missing file stays absent until an explicit save.
456
455
  Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
457
456
  This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
458
457
 
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`.
458
+ Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
460
459
  Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
461
460
  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.
462
461
  If both files exist, the canonical filename takes precedence.
@@ -472,8 +471,8 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
472
471
  - `update_plan` checklist use is blocked while Plan mode is active.
473
472
  - 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
473
  - 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.
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.
474
+ - 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.
475
+ - 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.
477
476
  - Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
478
477
 
479
478
  ## 🗂️ Package layout