@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 +33 -34
- package/dist/chunks/{chunk-D2V3VWND.ts → chunk-KSGLZ4S2.js} +367 -258
- package/dist/chunks/chunk-KSGLZ4S2.js.map +7 -0
- package/dist/chunks/{interactive-ui-VESWS25D.ts → interactive-ui-PSDKEVVG.js} +3 -33
- package/dist/chunks/interactive-ui-PSDKEVVG.js.map +7 -0
- package/dist/index.ts +103 -307
- package/dist/index.ts.map +3 -3
- package/package.json +5 -5
- package/src/plan-mode.ts +49 -211
- package/src/presentation.ts +50 -17
- package/src/required-tools.ts +17 -0
- package/src/settings-menu.ts +0 -34
- package/src/settings.ts +0 -19
- package/src/tool-policy.ts +137 -2
- package/dist/chunks/chunk-D2V3VWND.ts.map +0 -7
- package/dist/chunks/interactive-ui-VESWS25D.ts.map +0 -7
- package/src/helper-tool-visibility.ts +0 -142
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
|
-
-
|
|
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
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
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
|
|
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
|
-
|
|
144
|
-
|
|
145
|
-
|
|
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
|
-
|
|
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
|
|
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
|
|
330
|
+
### Plan helper tools
|
|
327
331
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
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
|
|
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,
|
|
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
|
|
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
|