@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 +33 -36
- package/dist/chunks/{chunk-U5CQ7RQX.js → chunk-AS76FCC5.js} +242 -265
- package/dist/chunks/chunk-AS76FCC5.js.map +7 -0
- package/dist/chunks/{interactive-ui-W3VYAJIQ.js → interactive-ui-UCL5UIJN.js} +43 -51
- package/dist/chunks/interactive-ui-UCL5UIJN.js.map +7 -0
- package/dist/index.ts +224 -321
- package/dist/index.ts.map +3 -3
- package/package.json +1 -1
- package/src/plan-launch-menu.ts +13 -5
- package/src/plan-mode.ts +263 -238
- package/src/required-tools.ts +17 -0
- package/src/settings-menu.ts +36 -47
- package/src/settings.ts +0 -19
- package/src/state.ts +30 -0
- package/src/tool-selection.ts +2 -4
- package/dist/chunks/chunk-U5CQ7RQX.js.map +0 -7
- package/dist/chunks/interactive-ui-W3VYAJIQ.js.map +0 -7
- package/src/helper-tool-visibility.ts +0 -142
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
|
-
-
|
|
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
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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
|
|
149
|
-
Built-in `edit` and `write`, `update_plan`, inactive
|
|
150
|
-
Extension and custom tools are denied by default because Pi tools do not expose standardized mutability metadata; allow
|
|
151
|
-
For example, you can opt into
|
|
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
|
|
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
|
|
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
|
|
333
|
+
### Plan helper tools
|
|
336
334
|
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
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
|
-
|
|
356
|
-
|
|
357
|
-
|
|
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,
|
|
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
|
|
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
|