@narumitw/pi-plan-mode 0.55.3 → 0.57.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 +113 -292
- package/dist/chunks/{chunk-TZVK4O2Q.js → chunk-YUFPCQVG.js} +1664 -1455
- package/dist/chunks/chunk-YUFPCQVG.js.map +7 -0
- package/dist/chunks/{interactive-ui-S7ZRCAGJ.js → interactive-ui-M3GEZN4M.js} +183 -84
- package/dist/chunks/interactive-ui-M3GEZN4M.js.map +7 -0
- package/dist/index.ts +185 -17
- package/dist/index.ts.map +3 -3
- package/docs/command-workflows.md +52 -0
- package/docs/settings.md +169 -0
- package/package.json +5 -7
- package/src/fresh-implementation-preferences.ts +102 -0
- package/src/fresh-implementation.ts +46 -3
- package/src/implementation-options.ts +127 -0
- package/src/implementation-preferences.ts +145 -0
- package/src/plan-action-controller.ts +26 -10
- package/src/plan-action-menus.ts +65 -104
- package/src/plan-mode.ts +106 -6
- package/src/saved-plan-menu.ts +35 -7
- package/src/settings-menu.ts +35 -1
- package/src/settings.ts +55 -31
- package/src/tool-policy.ts +97 -5
- package/dist/chunks/chunk-TZVK4O2Q.js.map +0 -7
- package/dist/chunks/interactive-ui-S7ZRCAGJ.js.map +0 -7
package/README.md
CHANGED
|
@@ -2,20 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
[](https://www.npmjs.com/package/@narumitw/pi-plan-mode) [](https://pi.dev) [](./LICENSE)
|
|
4
4
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
This independently installable extension adds a Codex-like `/plan` collaboration mode that Pi core does not provide.
|
|
5
|
+
Use a Codex-like `/plan` mode to explore a codebase, resolve important questions, and approve an implementation-ready plan before Pi edits files.
|
|
8
6
|
|
|
9
7
|
## ✨ Features
|
|
10
8
|
|
|
11
9
|
- Starts and manages Plan mode through `/plan`, `/plan start`, or `/plan <prompt>`.
|
|
12
|
-
-
|
|
13
|
-
-
|
|
14
|
-
- Reviews the complete plan before implementation, export, save,
|
|
15
|
-
-
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
10
|
+
- Blocks mutations, inactive helpers, and unsafe shell forms while keeping helper schemas stable.
|
|
11
|
+
- Uses structured questions for important ambiguity and explicit completion for a decision-ready plan.
|
|
12
|
+
- Reviews the complete plan before implementation, export, save, further planning, or discard.
|
|
13
|
+
- Implements in the planning session or a fresh linked session with the approved plan.
|
|
14
|
+
- Selects an implementation model and thinking level through saved defaults or one-menu overrides, without switching back automatically.
|
|
15
|
+
- Restores Plan state and one saved plan across resume and compaction.
|
|
16
|
+
- Configures the Plan tool allowlist, reviewed shell commands, user-trusted subcommands, export path, plan reinjection, shortcut, and thinking level.
|
|
17
|
+
- Publishes statusline state and cooperates anonymously with Workflow Mutex Protocol v1 participants.
|
|
19
18
|
|
|
20
19
|
## 📦 Install
|
|
21
20
|
|
|
@@ -39,106 +38,44 @@ npm --workspace @narumitw/pi-plan-mode run build
|
|
|
39
38
|
pi -e ./packages/pi-plan-mode
|
|
40
39
|
```
|
|
41
40
|
|
|
42
|
-
The package declares `dist/index.ts`, so an unbuilt local checkout
|
|
41
|
+
The package declares `dist/index.ts`, so build an unbuilt local checkout before Pi loads the package directory.
|
|
42
|
+
Install only from sources you trust because Pi extensions run with Pi's permissions.
|
|
43
43
|
|
|
44
44
|
## 🚀 Quick start
|
|
45
45
|
|
|
46
46
|
Run `/plan` to open the state-aware menu, then start Plan mode and ask the agent to inspect and design the change.
|
|
47
47
|
Run `/plan <prompt>` when the first planning request is already known.
|
|
48
48
|
|
|
49
|
-
## 🧱 Cache-stable mode transitions
|
|
50
|
-
|
|
51
|
-
Plan and Normal requests share one append-only conversation.
|
|
52
|
-
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.
|
|
53
|
-
Ordinary linear turns do not rewrite or duplicate these contracts.
|
|
54
|
-
**Implement here** therefore retains the Plan dialogue, structured questions, assistant tool calls, completion evidence, and `Implement the plan.` kickoff in order.
|
|
55
|
-
**Start fresh and implement** remains the explicit isolation path and transfers only the approved plan plus the Normal mode contract to a linked session.
|
|
56
|
-
|
|
57
|
-
The `context` hook filters legacy repeated `plan-mode-context` artifacts but preserves current transition messages.
|
|
58
|
-
When compaction removes the effective physical transition, the hook inserts one canonical fallback at a deterministic retained-history boundary.
|
|
59
|
-
Repeated transforms leave that fallback in place instead of moving it to the newest turn.
|
|
60
|
-
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.
|
|
61
|
-
Manual `/tree` navigation restores branch-owned Plan state and chooses the matching effective contract without navigating automatically or adding a branch summary.
|
|
62
|
-
Pi currently lists hidden custom transition messages in `/tree`; Plan mode rejects those internal targets, so select an adjacent conversation entry instead.
|
|
63
|
-
|
|
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.
|
|
69
|
-
|
|
70
|
-
The default `thinkingLevel: "inherit"` path also avoids a Plan-specific reasoning-parameter change.
|
|
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.
|
|
72
|
-
|
|
73
49
|
## 💬 Commands
|
|
74
50
|
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC keeps the complete unfiltered list.
|
|
104
|
-
Once Plan mode is active, tools are locked: `/plan` no longer offers tool or Settings actions, and `/plan tools` rejects the request.
|
|
105
|
-
Exit and start a new workflow if a different tool set is required.
|
|
106
|
-
The `plan_mode_question` tool keeps a dedicated model-requested questionnaire instead of using command-menu navigation.
|
|
107
|
-
`/plan show` displays the stored plan without starting a model turn, including the accepted plan while implementation is active.
|
|
108
|
-
`/plan finalize` explicitly asks the agent to complete the plan or ask one remaining material question, `/plan save` stores a completed ready plan for later and leaves Plan mode, and `/plan export [path]` writes a ready, saved, or active implementation plan to Markdown.
|
|
109
|
-
Completed and saved plan menus offer **Implement here**, which continues with the planning conversation, and **Start fresh and implement**, which opens a new session and transfers only the approved plan.
|
|
110
|
-
The direct `/plan implement` compatibility route remains equivalent to **Implement here** and never opens a selector.
|
|
111
|
-
A successful ready-plan export also leaves Plan mode; saved and active implementation exports retain their existing state.
|
|
112
|
-
`show`, `save`, `export`, and `implement` fail closed when no applicable plan is stored; `finalize` requires active Plan mode.
|
|
113
|
-
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.
|
|
114
|
-
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.
|
|
115
|
-
Prompts submitted while Plan mode is already active remain ordinary Plan follow-ups, and `/plan finalize` remains available as a Plan-preserving follow-up.
|
|
116
|
-
TUI and RPC show a warning for a rejected busy transition, while print and JSON routes throw an observable error.
|
|
117
|
-
|
|
118
|
-
`/plan export` uses the configured **Export destination**, which defaults to `PLAN.md`.
|
|
119
|
-
Supply a path to override that default for one export.
|
|
120
|
-
Relative paths resolve from the command's current `ctx.cwd` at export time, absolute paths remain absolute, a leading `@` is accepted for Pi path compatibility, and missing parent directories are created.
|
|
121
|
-
Explicit `/plan export <path>` input always wins over the setting.
|
|
122
|
-
Export never overwrites an existing file, directory, or symbolic link: choose another path or remove the existing target first.
|
|
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 stable helper envelope is unchanged, and the ready state is cleared without starting a model turn.
|
|
125
|
-
Exporting a saved or active implementation plan leaves that state unchanged.
|
|
126
|
-
Failed or cancelled exports leave every Plan-mode state unchanged.
|
|
127
|
-
The resulting file is available to the agent through its normal file-reading tools.
|
|
128
|
-
Export is an explicit user-requested file mutation.
|
|
129
|
-
Model-initiated Plan-mode writes remain blocked.
|
|
130
|
-
|
|
131
|
-
In TUI and RPC, **Export plan…** opens a single-line path input from every ready, saved, or active plan menu.
|
|
132
|
-
The input shows both the configured value and its currently resolved path.
|
|
133
|
-
Submit an empty value to use the configured destination, or enter a relative or absolute one-off path.
|
|
134
|
-
A failed TUI export retains the draft for correction; RPC reopens its input dialog.
|
|
135
|
-
Escape returns to the owning menu without writing a file.
|
|
136
|
-
A successful ready-plan export closes the menu and ends Plan mode; saved and active implementation menus close without changing their stored state.
|
|
137
|
-
|
|
138
|
-
When Plan mode is active, ask the agent to design the change.
|
|
139
|
-
The agent may inspect files and run read-only commands, but it should not edit files or execute the implementation.
|
|
140
|
-
It should explore first, then use structured questions when your preference or a tradeoff materially changes the plan.
|
|
141
|
-
Configure persistent defaults or a one-workflow tool override before activation; Planning and ready menus deliberately keep those controls locked.
|
|
51
|
+
| Command | Purpose |
|
|
52
|
+
| --- | --- |
|
|
53
|
+
| `/plan` | Start or manage planning, review a plan, or choose same-session or fresh-session implementation. |
|
|
54
|
+
| `/plan start` | Enter Plan mode without sending a model message. |
|
|
55
|
+
| `/plan <prompt>` | Start planning with a prompt, or send a follow-up while already active. |
|
|
56
|
+
| `/plan tools` | Choose a session-specific tool policy, then start; cancellation changes nothing. |
|
|
57
|
+
| `/plan show` | Display the stored plan without starting a model turn. |
|
|
58
|
+
| `/plan finalize` | Ask the active planner to finish or ask one remaining material question. |
|
|
59
|
+
| `/plan implement` | Implement a completed or saved plan in this session, without a selector. |
|
|
60
|
+
| `/plan save` | Save a ready plan in this Pi session and leave Plan mode. |
|
|
61
|
+
| `/plan export [path]` | Write a ready, saved, or active implementation plan to Markdown. |
|
|
62
|
+
| `/plan exit` (alias: `off`) | Leave Plan mode and discard its ready plan, or clear a saved/active plan. |
|
|
63
|
+
|
|
64
|
+
All routes support TUI and RPC.
|
|
65
|
+
Print and JSON modes reject the menu and `tools`; stored-plan display and implementation have [additional mode restrictions](#-planning-and-implementation).
|
|
66
|
+
Exact subcommand words select routes; other text is a planning prompt, so `/plan start a migration` sends a prompt rather than rejecting trailing text.
|
|
67
|
+
There is no startup flag.
|
|
68
|
+
|
|
69
|
+
State-changing transitions require an idle run; tool selection is locked once planning starts.
|
|
70
|
+
`show`, `save`, `export`, and `implement` require an applicable stored plan; `finalize` requires active Plan mode.
|
|
71
|
+
Export defaults to the configured destination (`PLAN.md` when unset), never overwrites an existing target, and ends Plan mode only when exporting a ready plan.
|
|
72
|
+
See [command workflows](./docs/command-workflows.md) for tool selection, busy-state recovery, path handling, and export cancellation, and [Security and privacy](#-security-and-privacy) before allowing custom tools.
|
|
73
|
+
|
|
74
|
+
## 🔒 Security and privacy
|
|
75
|
+
|
|
76
|
+
While Plan mode is active, the policy blocks built-in editing tools and instructs the agent not to edit files or implement the change.
|
|
77
|
+
It should explore first and ask structured questions when a preference or tradeoff materially changes the plan.
|
|
78
|
+
Configure persistent defaults or a one-workflow tool override before activation; active and ready workflows lock those controls.
|
|
142
79
|
|
|
143
80
|
Plan mode registers `plan_mode_question` and `plan_mode_complete` during extension load and never changes their active status itself.
|
|
144
81
|
Another active-tool policy may hide them, in which case Plan start or restore fails without widening that policy.
|
|
@@ -154,6 +91,7 @@ After they become visible, the Plan-only helpers remain visible in Normal mode,
|
|
|
154
91
|
|
|
155
92
|
Limited `bash` uses a fail-closed Bash policy, including when an extension overrides the canonical `bash` tool name.
|
|
156
93
|
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`.
|
|
94
|
+
It also accepts `hostname` without arguments and local Windows `tasklist` queries using reviewed display, filter, module, and service flags.
|
|
157
95
|
Reviewed Git inspections may place `--no-pager` before the accepted subcommand.
|
|
158
96
|
They may also place one or more complete `-C <path>` pairs before the accepted subcommand only when every path is `.` or the exact current Pi working directory.
|
|
159
97
|
Other targets are rejected so `git -C` cannot introduce executable configuration, hooks, filters, signing programs, or lazy-fetch remotes from another repository.
|
|
@@ -161,13 +99,17 @@ It rejects output/input redirects, shell expansion, substitutions, subshells, ba
|
|
|
161
99
|
|
|
162
100
|
Limited `powershell` uses a separate fail-closed PowerShell policy, including when an extension overrides the canonical `powershell` tool name.
|
|
163
101
|
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`.
|
|
102
|
+
It accepts local `Get-Process` and `Get-Service` queries with reviewed static selectors while rejecting remote and object-input parameters.
|
|
164
103
|
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.
|
|
165
104
|
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.
|
|
166
105
|
Use canonical cmdlet names because PowerShell aliases are intentionally outside the reviewed policy.
|
|
167
106
|
|
|
168
107
|
A rejected parsed command list or pipeline identifies its first blocked command segment; malformed or unsupported shell syntax reports the complete submitted input instead.
|
|
169
108
|
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.
|
|
170
|
-
Both limited-shell policies
|
|
109
|
+
Both limited-shell policies reduce risk but do not provide an OS sandbox or confidentiality boundary.
|
|
110
|
+
A configured `safeSubcommands` match bypasses both policies completely, so use it only when you intend to trust the entire submitted shell command.
|
|
111
|
+
|
|
112
|
+
## 🧭 Planning and implementation
|
|
171
113
|
|
|
172
114
|
`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.
|
|
173
115
|
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.
|
|
@@ -209,6 +151,14 @@ Empty, malformed, unclosed, or multiple legacy blocks keep Plan mode active and
|
|
|
209
151
|
|
|
210
152
|
After completion, `/plan` opens the ready actions when interactive UI is available.
|
|
211
153
|
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.
|
|
154
|
+
**Implementation options…** stages model and thinking choices for either action in that menu; `/plan implement` uses saved defaults.
|
|
155
|
+
Choices take effect only when implementation starts and do not change Pi's global defaults.
|
|
156
|
+
After kickoff, run settlement, user abort, and active-plan clearing do not restore the previous model or thinking; subsequent manual choices remain yours.
|
|
157
|
+
Implementation preferences are characterized on Pi 0.85.0; use that release or newer for this feature.
|
|
158
|
+
See [implementation preferences](./docs/settings.md#implementation-model-and-thinking) for inheritance and failure behavior.
|
|
159
|
+
|
|
160
|
+
Selecting another provider with **Implement here** sends the retained planning conversation to that provider.
|
|
161
|
+
Fresh implementation transfers only the approved plan plus the destination's normal resources.
|
|
212
162
|
**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.
|
|
213
163
|
**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.
|
|
214
164
|
The destination still loads its normal `AGENTS.md`, skills, project resources, and extensions.
|
|
@@ -280,6 +230,34 @@ During a guaranteed-plan implementation, it removes both the original implementa
|
|
|
280
230
|
/plan exit
|
|
281
231
|
```
|
|
282
232
|
|
|
233
|
+
## 🧱 Cache-stable mode transitions
|
|
234
|
+
|
|
235
|
+
Plan and Normal requests share one append-only conversation.
|
|
236
|
+
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.
|
|
237
|
+
Ordinary linear turns do not rewrite or duplicate these contracts.
|
|
238
|
+
**Implement here** retains the Plan dialogue, structured questions, tool calls, completion evidence, and `Implement the plan.` kickoff in order.
|
|
239
|
+
**Start fresh and implement** is the isolation path and transfers only the approved plan plus the Normal contract to a linked session.
|
|
240
|
+
|
|
241
|
+
The `context` hook filters repeated legacy `plan-mode-context` artifacts but preserves current transition messages.
|
|
242
|
+
If compaction removes the effective transition, the hook inserts one canonical fallback at a deterministic retained-history boundary.
|
|
243
|
+
Repeated transforms leave that fallback in place instead of moving it to the newest turn.
|
|
244
|
+
An inactive legacy state entry does not inject a Normal contract, so sessions that never entered Plan mode keep their ordinary context after resume or reload.
|
|
245
|
+
Manual `/tree` navigation restores branch-owned Plan state and chooses the matching contract without navigating or adding a branch summary.
|
|
246
|
+
Pi lists hidden transition messages in `/tree`; Plan mode rejects those internal targets, so select an adjacent conversation entry.
|
|
247
|
+
|
|
248
|
+
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.
|
|
249
|
+
Visible helpers do not mean `/plan` is active, and their descriptions exclude ordinary planning, the `writing-plans` skill, roadmaps, checklists, and plan-file work.
|
|
250
|
+
Only the latest active Plan contract authorizes the helpers; inactive or stale calls fail without accepting a plan or opening question UI.
|
|
251
|
+
Plan mode does not widen a restrictive active-tool policy; start or restore fails when a required helper is unavailable.
|
|
252
|
+
Stable schemas preserve a cache-eligible prefix but cannot guarantee a hit because provider serialization, cache lifetime, minimum prefix size, implementation details, and session affinity remain external.
|
|
253
|
+
|
|
254
|
+
An explicit implementation model or thinking change is an intentional provider/cache boundary at handoff, not an ordinary-turn context rewrite.
|
|
255
|
+
Preferences and fresh-session acknowledgements are non-model state; they do not add tool schemas or leading prompt instructions.
|
|
256
|
+
Subsequent turns retain the existing append-only context behavior.
|
|
257
|
+
|
|
258
|
+
The default `thinkingLevel: "inherit"` avoids a Plan-specific reasoning-parameter change.
|
|
259
|
+
A fixed Plan thinking level remains supported, but changing reasoning parameters can prevent provider-side state reuse even when prompts and tool schemas stay stable.
|
|
260
|
+
|
|
283
261
|
## 🤝 Workflow coexistence
|
|
284
262
|
|
|
285
263
|
Plan mode is independently installable and keeps its standalone behavior when no other protocol participant is present.
|
|
@@ -290,6 +268,7 @@ Saved plans and ordinary implementation after Plan handoff do not hold the group
|
|
|
290
268
|
Every inactive start performs one final synchronous admission after asynchronous preflight and before changing Plan state, persistence, prompts, tools, thinking level, queues, or status.
|
|
291
269
|
If another participant is active, TUI and RPC show an anonymous warning that another workflow is active.
|
|
292
270
|
Print and JSON direct routes throw the same anonymous error before mutation.
|
|
271
|
+
|
|
293
272
|
Launch-menu, selected-tool, shortcut, active-implementation **Start a new plan**, and restored activation use the same admission boundary.
|
|
294
273
|
A rejected selected-tool launch does not save its draft choices.
|
|
295
274
|
|
|
@@ -316,216 +295,58 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
|
|
|
316
295
|
|
|
317
296
|
## ⚙️ Settings
|
|
318
297
|
|
|
319
|
-
Open **Settings** from an inactive `/plan` menu
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
You can change the Plan-mode shortcut with `toggleShortcut` as long as the file remains JSON-only and uses a valid key string.
|
|
323
|
-
The file is optional, is read at session start and reloaded automatically when changed, and is created only after an explicit Settings save or manual edit.
|
|
324
|
-
When omitted, the shortcut is disabled by default.
|
|
298
|
+
Open **Settings** from an inactive `/plan` menu, or edit `<getAgentDir()>/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`).
|
|
299
|
+
The optional file is read at session start and watched for changes; only an explicit save creates it.
|
|
300
|
+
|
|
325
301
|
```json
|
|
326
302
|
{
|
|
327
303
|
"thinkingLevel": "inherit",
|
|
328
|
-
"defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
|
|
329
304
|
"implementationPlanRetention": "clear-on-start",
|
|
330
|
-
"defaultPlanExportPath": "PLAN.md"
|
|
331
|
-
"safeSubcommands": {
|
|
332
|
-
"git": ["status", "log", "rev-parse", "blame"],
|
|
333
|
-
"gh": ["pr view", "pr list", "issue view", "issue list"]
|
|
334
|
-
},
|
|
335
|
-
"toggleShortcut": "<your_key>"
|
|
305
|
+
"defaultPlanExportPath": "PLAN.md"
|
|
336
306
|
}
|
|
337
307
|
```
|
|
338
308
|
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
|
|
344
|
-
The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved or a legacy settings file is migrated.
|
|
345
|
-
|
|
346
|
-
### Default Plan policy tools
|
|
309
|
+
By default, Plan mode inherits thinking, allows active safe built-ins, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
|
|
310
|
+
Implementation model and thinking defaults are optional Settings rows; unset values keep existing behavior, including normal restoration of Plan-specific thinking.
|
|
311
|
+
The shortcut is disabled unless configured.
|
|
312
|
+
Settings saves apply to later workflows; an active implementation keeps its captured reinjection policy.
|
|
313
|
+
The export destination affects the next export immediately.
|
|
347
314
|
|
|
348
|
-
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
315
|
+
> [!WARNING]
|
|
316
|
+
> `safeSubcommands` is a JSON-only full-command trust override, not a read-only allowlist.
|
|
317
|
+
> A matching prefix bypasses all shell checks, including checks on trailing commands, redirects, and mutations.
|
|
318
|
+
> Configure it only for commands and repositories you fully trust.
|
|
352
319
|
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
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.
|
|
356
|
-
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.
|
|
357
|
-
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.
|
|
358
|
-
The resolved allowlist persists with the active workflow and restores without reopening the resolution boundary after reload, resume, or tree navigation.
|
|
359
|
-
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.
|
|
360
|
-
Settings shows unresolved names as pending registration; resetting to automatic removes the entire override.
|
|
361
|
-
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.
|
|
362
|
-
Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
|
|
363
|
-
Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
|
|
364
|
-
An effective active tool named `bash` or `powershell` remains subject to its limited-shell policy regardless of its source metadata.
|
|
320
|
+
Saves are ordered within one Pi process, preserve unknown fields, and publish atomically; separate Pi processes can still race.
|
|
321
|
+
Invalid settings remain untouched and make Settings read-only; session-start failures use safe defaults.
|
|
365
322
|
|
|
366
|
-
|
|
367
|
-
The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
|
|
368
|
-
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.
|
|
369
|
-
|
|
370
|
-
### Plan reinjection
|
|
371
|
-
|
|
372
|
-
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.
|
|
373
|
-
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.
|
|
374
|
-
In the planning session, this policy sends `Implement the plan.` and relies on the accepted plan already present in ordinary conversation history.
|
|
375
|
-
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.
|
|
376
|
-
Use `clear-after-first-run` for **Through first implementation run** to guarantee the exact plan until that implementation's first fully settled run ends.
|
|
377
|
-
Use `keep` for **Until manually cleared** to guarantee and reinject the exact plan until `/plan exit` or supersession.
|
|
378
|
-
A resumed guaranteed-plan cleanup policy re-arms against the first context in the replacement session.
|
|
379
|
-
Failed handoff delivery restores the ready or saved plan and does not run automatic cleanup.
|
|
380
|
-
|
|
381
|
-
Changing this setting applies to the next Implement action only.
|
|
382
|
-
Each guaranteed-plan implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
|
|
383
|
-
Conversation-history-only implementation has no active Plan-mode state to show, export, or clear after kickoff.
|
|
384
|
-
|
|
385
|
-
### Export destination
|
|
386
|
-
|
|
387
|
-
`defaultPlanExportPath` controls only exports that omit a path.
|
|
388
|
-
Omit it—or submit an empty value in Settings—to use `PLAN.md`.
|
|
389
|
-
The value must be a non-empty string of at most 4,096 characters without terminal control characters or NUL.
|
|
390
|
-
Relative values are resolved against the current working directory at export time; the Settings detail and every export input preview the concrete resolved destination.
|
|
391
|
-
An explicit `/plan export <path>` is a one-off override and does not edit Settings.
|
|
392
|
-
Saving a new destination affects the next export immediately, including export of a currently active implementation.
|
|
393
|
-
|
|
394
|
-
The existing no-overwrite, cancellation, and atomic Plan-state behavior is unchanged.
|
|
395
|
-
A failed save rolls the row back to its previous value; a failed or cancelled export preserves the plan and target.
|
|
396
|
-
Long previews wrap or truncate to the available terminal width without changing the raw path used by the action.
|
|
397
|
-
|
|
398
|
-
### Toggle shortcut
|
|
399
|
-
|
|
400
|
-
`toggleShortcut` controls the global Plan-mode keybinding used by the TUI shortcut.
|
|
401
|
-
Omit this setting to keep the shortcut disabled.
|
|
402
|
-
Set `toggleShortcut` to the key string you want.
|
|
403
|
-
Avoid values that conflict with editor shortcuts.
|
|
404
|
-
|
|
405
|
-
### Safe shell subcommands
|
|
406
|
-
|
|
407
|
-
`safeSubcommands` adds reviewed command validators to limited `bash` and `powershell`; it is not a raw shell allowlist.
|
|
408
|
-
Only the following exact values are accepted:
|
|
409
|
-
|
|
410
|
-
- `git`: `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, `grep`, `rev-parse`, `blame`, `describe`, `merge-base`, `ls-tree`, and `cat-file`.
|
|
411
|
-
- `gh`: `pr view`, `pr list`, `issue view`, and `issue list`.
|
|
412
|
-
|
|
413
|
-
The first eight Git validators are built in and remain enabled when omitted, so listing them is valid but redundant.
|
|
414
|
-
The other six Git validators and every `gh` path require an explicit opt-in.
|
|
415
|
-
Git entries select one exact subcommand; `gh` entries select one exact two-word path, so `"pr view"` never enables `pr merge`, `pr close`, or `pr edit`.
|
|
416
|
-
Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
|
|
417
|
-
Duplicate values are removed in first-seen order.
|
|
418
|
-
|
|
419
|
-
With the example configuration above, commands such as these are accepted:
|
|
420
|
-
|
|
421
|
-
```bash
|
|
422
|
-
git -C . status --short
|
|
423
|
-
git rev-parse --show-toplevel
|
|
424
|
-
git blame -- src/plan-mode.ts
|
|
425
|
-
git diff --cached
|
|
426
|
-
git show --stat --oneline HEAD
|
|
427
|
-
git log -p -1 HEAD -- src/plan-mode.ts
|
|
428
|
-
git -C . diff --check
|
|
429
|
-
gh pr view 218 --json number,title,state
|
|
430
|
-
gh issue list --state open --json number,title,state
|
|
431
|
-
```
|
|
432
|
-
|
|
433
|
-
The command-specific validators still reject unsafe forms, including:
|
|
434
|
-
|
|
435
|
-
```bash
|
|
436
|
-
git -C
|
|
437
|
-
git -C packages/pi-plan-mode status --short
|
|
438
|
-
git -C packages -C .. status --short
|
|
439
|
-
git -c core.fsmonitor=false -C . status --short
|
|
440
|
-
git -C . checkout main
|
|
441
|
-
git blame --textconv -- src/plan-mode.ts
|
|
442
|
-
git cat-file --filters HEAD
|
|
443
|
-
git diff --ext-diff
|
|
444
|
-
git log --show-signature -1
|
|
445
|
-
git remote show origin
|
|
446
|
-
git show --textconv HEAD
|
|
447
|
-
gh pr merge 218
|
|
448
|
-
gh pr view 218
|
|
449
|
-
gh pr view 218 --web
|
|
450
|
-
gh pr view 218 > pr.txt
|
|
451
|
-
gh pr list --json number,title && gh pr merge 218
|
|
452
|
-
```
|
|
453
|
-
|
|
454
|
-
Redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff/textconv/filter/signature helpers, output flags, malformed command layouts, and any chain containing an unsafe segment fail closed.
|
|
455
|
-
Read-dominant Git validators accept ordinary inspection flags without requiring `--no-textconv` or `--no-ext-diff`; Git may therefore invoke a helper configured by the user or trusted repository even when the command does not request one explicitly.
|
|
456
|
-
Use the negative flags when you want to suppress those configured helpers.
|
|
457
|
-
Mixed read/write surfaces remain narrower: use `git remote show -n` to avoid invoking a transport helper, while mutating `branch` and `remote` forms remain blocked.
|
|
458
|
-
GitHub CLI read paths require `--json <fields>` output so Plan mode does not rely on `GH_PAGER`, `PAGER`, or gh pager configuration.
|
|
459
|
-
Unknown `safeSubcommands` keys or values, non-array values, and non-string entries invalidate the entire settings file and trigger the normal warning/default fallback on session start.
|
|
460
|
-
|
|
461
|
-
Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while `gh` queries can expose remote repository, pull request, and issue data available to your authenticated account.
|
|
462
|
-
A `git -C <path>` inspection is accepted only when the path keeps Git in Pi's current working directory.
|
|
463
|
-
The policy reduces accidental mutation and cross-repository executable configuration; it is not a sandbox or a confidentiality boundary.
|
|
464
|
-
|
|
465
|
-
### Thinking level
|
|
466
|
-
|
|
467
|
-
Plan mode inherits Pi's current thinking level by default.
|
|
468
|
-
Set `thinkingLevel` to request a fixed level only while Plan mode is active.
|
|
469
|
-
Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
|
|
470
|
-
The extension snapshots the prior level and restores it on exit only if the level still matches the value it applied; a manual change made during Plan mode is preserved.
|
|
471
|
-
A Settings save does not change Pi's current or default thinking level and takes effect only when the next Plan workflow starts.
|
|
472
|
-
|
|
473
|
-
Settings saves are serialized in invocation order inside one Pi process.
|
|
474
|
-
Each save re-reads the latest valid document, preserves unknown top-level fields and unedited `safeSubcommands`, then publishes through a same-directory temporary file and rename.
|
|
475
|
-
A missing file stays absent until an explicit save.
|
|
476
|
-
Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
|
|
477
|
-
This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
|
|
478
|
-
|
|
479
|
-
Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
|
|
480
|
-
Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
|
|
481
|
-
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.
|
|
482
|
-
If both files exist, the canonical filename takes precedence.
|
|
323
|
+
Read the [settings reference](./docs/settings.md) for all accepted values, tool-policy resolution, reinjection choices, shortcut configuration, shell-override examples, and legacy-file migration.
|
|
483
324
|
|
|
484
325
|
## 🧠 Codex-like behavior
|
|
485
326
|
|
|
486
327
|
This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
|
|
487
328
|
|
|
488
|
-
- Plan mode is
|
|
489
|
-
- `/plan <prompt>`
|
|
490
|
-
- The agent
|
|
491
|
-
-
|
|
492
|
-
- `
|
|
493
|
-
-
|
|
494
|
-
- 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.
|
|
495
|
-
- 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.
|
|
496
|
-
- 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.
|
|
497
|
-
- Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
|
|
329
|
+
- Plan mode is conversational collaboration, not TODO or progress tracking.
|
|
330
|
+
- `/plan <prompt>` enters Plan mode before submitting the prompt.
|
|
331
|
+
- The agent uses `plan_mode_question` for material preferences and completes with a standalone `plan_mode_complete` call instead of prose detection.
|
|
332
|
+
- `update_plan` is blocked until the explicit implementation boundary restores Normal mode.
|
|
333
|
+
- The default `clear-on-start` policy uses conversation history; `clear-after-first-run` and `keep` add exact-plan guarantees.
|
|
334
|
+
- Append-only Plan and Normal contracts keep helper schemas stable, but Pi's tool policy is risk reduction rather than Codex sandbox enforcement.
|
|
498
335
|
|
|
499
336
|
## 🗂️ Package layout
|
|
500
337
|
|
|
501
|
-
```
|
|
338
|
+
```text
|
|
502
339
|
packages/pi-plan-mode/
|
|
503
|
-
├──
|
|
504
|
-
├──
|
|
505
|
-
│ └──
|
|
506
|
-
├──
|
|
507
|
-
|
|
508
|
-
|
|
509
|
-
|
|
510
|
-
│ └── *.ts # Package-local prompt, policy, question, and message modules
|
|
511
|
-
├── README.md
|
|
512
|
-
├── LICENSE
|
|
513
|
-
├── tsconfig.json
|
|
514
|
-
└── package.json
|
|
515
|
-
```
|
|
516
|
-
|
|
517
|
-
`index.ts` is the Pi entrypoint and forwards to `plan-mode.ts`; the other source modules are internal.
|
|
518
|
-
The package exposes its Pi extension through `package.json`:
|
|
519
|
-
|
|
520
|
-
```json
|
|
521
|
-
{
|
|
522
|
-
"pi": {
|
|
523
|
-
"extensions": ["./dist/index.ts"]
|
|
524
|
-
}
|
|
525
|
-
}
|
|
340
|
+
├── src/ # Policy, questions, settings, and handoff modules
|
|
341
|
+
│ ├── index.ts # Thin Pi entrypoint
|
|
342
|
+
│ └── plan-mode.ts # Planning policy and implementation handoff
|
|
343
|
+
├── dist/ # Generated Jiti runtime
|
|
344
|
+
├── scripts/build-runtime.mjs # Runtime builder
|
|
345
|
+
├── docs/ # Published reference documentation
|
|
346
|
+
└── test/ # Behavior and lifecycle coverage
|
|
526
347
|
```
|
|
527
348
|
|
|
528
|
-
The generated runtime is built from
|
|
349
|
+
The generated runtime is built from `src/index.ts` and does not import back into `src`.
|
|
529
350
|
|
|
530
351
|
## 🔎 Keywords
|
|
531
352
|
|