@narumitw/pi-plan-mode 0.56.0 → 0.57.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,68 +47,28 @@ Run `/plan <prompt>` when the first planning request is already known.
47
47
 
48
48
  ## 💬 Commands
49
49
 
50
- ```text
51
- /plan
52
- /plan start
53
- /plan <prompt>
54
- /plan tools
55
- /plan show
56
- /plan finalize
57
- /plan implement
58
- /plan save
59
- /plan export [path]
60
- /plan exit
61
- ```
62
-
63
- In TUI and RPC, use bare `/plan` to open the menu for the current Plan state.
64
- When Plan mode is off and no plan is stored, the launch menu shows the effective next-start tools and offers **Start Plan mode**, **Choose tools, then start…**, **Settings**, and **How Plan mode works**.
65
- Settings edits the persistent defaults for later workflows.
66
- Launch-menu policy changes remain a draft until **Done — start with this policy** is selected; Back, Escape, Ctrl+C, disposal, session replacement, and shutdown discard the draft without changing Plan state, active tools, thinking, or the stored selection.
67
-
68
- Use `/plan start` when you want to enter Plan mode directly without sending a model message.
69
- Use `/plan <prompt>` to enter Plan mode and immediately submit `<prompt>` as the first Plan-mode user message.
70
- The exact argument `start` is reserved for direct activation; longer text such as `/plan start a migration` remains an inline planning prompt.
71
- The extension does not register a startup flag; run `/plan start` after launch for direct activation.
72
-
73
- Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific Plan policy before planning starts.
74
- 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.
75
- 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.
76
- Configured or previously selected names without current metadata appear as pending registration and remain selected for first-request resolution.
77
- Reopen the picker to refresh tools registered while it was closed because Pi exposes no live tool-registration event.
78
- In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC shows the complete unfiltered list.
79
- Once Plan mode is active, tools are locked: `/plan` no longer offers tool or Settings actions, and `/plan tools` rejects the request.
80
- Exit and start a new workflow if a different tool set is required.
81
- The `plan_mode_question` tool keeps a dedicated model-requested questionnaire instead of using command-menu navigation.
82
- `/plan show` displays the stored plan without starting a model turn, including the accepted plan while implementation is active.
83
- `/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.
84
- 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.
85
- The direct `/plan implement` compatibility route remains equivalent to **Implement here** and never opens a selector.
86
- A successful ready-plan export also leaves Plan mode; saved and active implementation exports retain their existing state.
87
- `show`, `save`, `export`, and `implement` fail closed when no applicable plan is stored; `finalize` requires active Plan mode.
88
- 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.
89
- 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.
90
- Prompts submitted while Plan mode is already active remain ordinary Plan follow-ups, and `/plan finalize` remains available as a Plan-preserving follow-up.
91
- TUI and RPC show a warning for a rejected busy transition, while print and JSON routes throw an observable error.
92
-
93
- `/plan export` uses the configured **Export destination**, which defaults to `PLAN.md`.
94
- Supply a path to override that default for one export.
95
- 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.
96
- Explicit `/plan export <path>` input always wins over the setting.
97
- Export never overwrites an existing file, directory, or symbolic link: choose another path or remove the existing target first.
98
- A successful export adds one trailing newline but otherwise preserves the accepted Markdown exactly.
99
- 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.
100
- Exporting a saved or active implementation plan leaves that state unchanged.
101
- Failed or cancelled exports leave every Plan-mode state unchanged.
102
- The resulting file is available to the agent through its normal file-reading tools.
103
- Export is an explicit user-requested file mutation.
104
- Model-initiated Plan-mode writes remain blocked.
105
-
106
- In TUI and RPC, **Export plan…** opens a single-line path input from every ready, saved, or active plan menu.
107
- The input shows both the configured value and its currently resolved path.
108
- Submit an empty value to use the configured destination, or enter a relative or absolute one-off path.
109
- A failed TUI export retains the draft for correction; RPC reopens its input dialog.
110
- Escape returns to the owning menu without writing a file.
111
- A successful ready-plan export closes the menu and ends Plan mode; saved and active implementation menus close without changing their stored state.
50
+ | Command | Purpose |
51
+ | --- | --- |
52
+ | `/plan` | Start or manage planning, review a plan, or choose same-session or fresh-session implementation. |
53
+ | `/plan start` | Enter Plan mode without sending a model message. |
54
+ | `/plan <prompt>` | Start planning with a prompt, or send a follow-up while already active. |
55
+ | `/plan tools` | Choose a session-specific tool policy, then start; cancellation changes nothing. |
56
+ | `/plan show` | Display the stored plan without starting a model turn. |
57
+ | `/plan finalize` | Ask the active planner to finish or ask one remaining material question. |
58
+ | `/plan implement` | Implement a completed or saved plan in this session, without a selector. |
59
+ | `/plan save` | Save a ready plan in this Pi session and leave Plan mode. |
60
+ | `/plan export [path]` | Write a ready, saved, or active implementation plan to Markdown. |
61
+ | `/plan exit` (alias: `off`) | Leave Plan mode and discard its ready plan, or clear a saved/active plan. |
62
+
63
+ All routes support TUI and RPC.
64
+ Print and JSON modes reject the menu and `tools`; stored-plan display and implementation have [additional mode restrictions](#-planning-and-implementation).
65
+ Exact subcommand words select routes; other text is a planning prompt, so `/plan start a migration` sends a prompt rather than rejecting trailing text.
66
+ There is no startup flag.
67
+
68
+ State-changing transitions require an idle run; tool selection is locked once planning starts.
69
+ `show`, `save`, `export`, and `implement` require an applicable stored plan; `finalize` requires active Plan mode.
70
+ 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.
71
+ 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.
112
72
 
113
73
  ## 🔒 Security and privacy
114
74
 
@@ -295,6 +255,7 @@ Saved plans and ordinary implementation after Plan handoff do not hold the group
295
255
  Every inactive start performs one final synchronous admission after asynchronous preflight and before changing Plan state, persistence, prompts, tools, thinking level, queues, or status.
296
256
  If another participant is active, TUI and RPC show an anonymous warning that another workflow is active.
297
257
  Print and JSON direct routes throw the same anonymous error before mutation.
258
+
298
259
  Launch-menu, selected-tool, shortcut, active-implementation **Start a new plan**, and restored activation use the same admission boundary.
299
260
  A rejected selected-tool launch does not save its draft choices.
300
261
 
@@ -321,140 +282,31 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
321
282
 
322
283
  ## ⚙️ Settings
323
284
 
324
- Open **Settings** from an inactive `/plan` menu to edit **Plan thinking**, **Plan policy tools**, **Plan reinjection**, **Export destination**, and **Plan mode shortcut**.
325
- You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
326
- `safeSubcommands` is JSON-only.
327
- The optional file is read at session start, watched for changes, and created only by an explicit Settings save or manual edit.
328
- The shortcut is disabled when `toggleShortcut` is omitted.
285
+ Open **Settings** from an inactive `/plan` menu, or edit `<getAgentDir()>/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`).
286
+ The optional file is read at session start and watched for changes; only an explicit save creates it.
287
+
329
288
  ```json
330
289
  {
331
290
  "thinkingLevel": "inherit",
332
- "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
333
291
  "implementationPlanRetention": "clear-on-start",
334
- "defaultPlanExportPath": "PLAN.md",
335
- "safeSubcommands": {
336
- "git": ["rev-parse", "blame"],
337
- "gh": ["pr view", "issue list"],
338
- "kubectl": ["get", "apply"],
339
- "npm": ["run inspect-custom"]
340
- },
341
- "toggleShortcut": "<your_key>"
292
+ "defaultPlanExportPath": "PLAN.md"
342
293
  }
343
294
  ```
344
295
 
345
- ### Plan helper tools
346
-
347
- Plan helper schemas are stable from extension registration onward, and Plan mode does not call `setActiveTools()`.
348
- Tool visibility alone is not Plan activation.
349
- 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.
350
- The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved or a legacy settings file is migrated.
351
-
352
- ### Default Plan policy tools
353
-
354
- `defaultPlanTools` defines the initial runtime allowlist when a session has no stored pre-start selection.
355
- Omit it—or choose **Use automatic safe built-ins**—to allow already-active safe built-ins by default.
356
- An explicit empty array appears as **No optional tools** and denies every ordinary tool while the required helpers remain callable in Plan mode.
357
- Neither setting changes model-visible tool schemas.
358
-
359
- Tool names must be non-empty strings; duplicates are removed in first-seen order.
360
- Explicit configured or session-selected names remain policy intent when their tool is unknown or inactive, but Plan mode never registers or activates them.
361
- 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.
362
- 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.
363
- 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.
364
- The resolved allowlist persists with the active workflow and restores without reopening the resolution boundary after reload, resume, or tree navigation.
365
- 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.
366
- Settings shows unresolved names as pending registration; resetting to automatic removes the entire override.
367
- 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.
368
- Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
369
- Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
370
- An effective active tool named `bash` or `powershell` remains subject to its limited-shell policy regardless of its source metadata.
371
-
372
- 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.
373
- The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
374
- 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.
375
-
376
- ### Plan reinjection
377
-
378
- 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.
379
- 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.
380
- In the planning session, this policy sends `Implement the plan.` and relies on the accepted plan already present in ordinary conversation history.
381
- 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.
382
- Use `clear-after-first-run` for **Through first implementation run** to guarantee the exact plan until that implementation's first fully settled run ends.
383
- Use `keep` for **Until manually cleared** to guarantee and reinject the exact plan until `/plan exit` or supersession.
384
- A resumed guaranteed-plan cleanup policy re-arms against the first context in the replacement session.
385
- Failed handoff delivery restores the ready or saved plan and does not run automatic cleanup.
386
-
387
- Changing this setting applies to the next Implement action only.
388
- Each guaranteed-plan implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
389
- Conversation-history-only implementation has no active Plan-mode state to show, export, or clear after kickoff.
390
-
391
- ### Export destination
392
-
393
- `defaultPlanExportPath` controls only exports that omit a path.
394
- Omit it—or submit an empty value in Settings—to use `PLAN.md`.
395
- The value must be a non-empty string of at most 4,096 characters without terminal control characters or NUL.
396
- Relative values are resolved against the current working directory at export time; the Settings detail and every export input preview the concrete resolved destination.
397
- An explicit `/plan export <path>` is a one-off override and does not edit Settings.
398
- Saving a new destination affects the next export immediately, including export of a currently active implementation.
399
-
400
- The existing no-overwrite, cancellation, and atomic Plan-state behavior is unchanged.
401
- A failed save rolls the row back to its previous value; a failed or cancelled export preserves the plan and target.
402
- Long previews wrap or truncate to the available terminal width without changing the raw path used by the action.
403
-
404
- ### Toggle shortcut
405
-
406
- `toggleShortcut` controls the global Plan-mode keybinding used by the TUI shortcut.
407
- Omit this setting to keep the shortcut disabled.
408
- Set `toggleShortcut` to the key string you want.
409
- Avoid values that conflict with editor shortcuts.
410
-
411
- ### Safe shell subcommands
412
-
413
- `safeSubcommands` maps any command prefix to subcommand prefixes that the user chooses to trust completely in limited `bash` and `powershell`.
414
- For example, `"kubectl": ["get", "apply"]` trusts commands beginning with `kubectl get` or `kubectl apply`, while `"npm": ["run inspect-custom"]` trusts commands beginning with `npm run inspect-custom`.
415
- Command keys and subcommand entries are trimmed and must be non-empty strings.
416
- Matches are literal and case-sensitive after leading whitespace in the submitted command is ignored.
417
- A match requires the complete `<command> <subcommand>` prefix followed by whitespace, a shell control operator, or the end of the submitted command, so `"kubectl": ["apply"]` does not match `kubectl applies`.
418
- Duplicate values and command keys that become equal after trimming are merged in first-seen order.
419
- Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
420
-
421
- When a configured prefix matches, Plan mode permits the complete submitted command without parsing or applying any command, argument, mutation, chain, redirect, expansion, substitution, multiline, or PowerShell syntax checks.
422
- For example, `"kubectl": ["apply"]` also permits `kubectl apply -f deployment.yaml && rm -rf build`.
423
- Likewise, `"gh": ["pr view"]` permits `gh pr view 218 --web`, `gh pr view 218 > pr.txt`, and any trailing shell content.
424
- The setting therefore delegates the complete shell decision to the user and can allow arbitrary code execution with Pi's permissions.
425
- It is not a sandbox, confirmation gate, or read-only guarantee.
426
- Choose entries that are as specific as your workflow permits, and configure them only for commands and repositories you fully trust.
427
-
428
- Commands that do not match still use the built-in fail-closed reviewed policy.
429
- That default policy includes Git `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, and `grep`, with command-specific argument checks.
430
- It rejects output and input redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff, textconv, filter, or signature helpers, mutating flags, malformed command layouts, and any parsed chain containing an unsafe segment.
431
- 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.
432
- Use the negative flags when you want to suppress those configured helpers.
433
- 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 unless explicitly trusted through `safeSubcommands`.
434
-
435
- Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while configured commands can expose or modify any data available to Pi's process.
436
- A built-in-policy `git -C <path>` inspection is accepted only when the path keeps Git in Pi's current working directory.
437
- The default policy reduces accidental mutation and cross-repository executable configuration; configured `safeSubcommands` bypass that protection.
438
- A non-object `safeSubcommands`, empty command or subcommand string, non-array value, or non-string entry invalidates the entire settings file and triggers the normal warning/default fallback on session start.
439
-
440
- ### Thinking level
441
-
442
- Plan mode inherits Pi's current thinking level by default.
443
- Set `thinkingLevel` to request a fixed level only while Plan mode is active.
444
- Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
445
- 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.
446
- A Settings save does not change Pi's current or default thinking level and takes effect only when the next Plan workflow starts.
447
-
448
- Settings saves are serialized in invocation order inside one Pi process.
449
- 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.
450
- A missing file stays absent until an explicit save.
451
- Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
452
- This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
453
-
454
- Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
455
- Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
456
- 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.
457
- If both files exist, the canonical filename takes precedence.
296
+ By default, Plan mode inherits thinking, allows active safe built-ins, exports to `PLAN.md`, and relies on ordinary conversation history after implementation starts.
297
+ The shortcut is disabled unless configured.
298
+ Settings saves apply to later workflows; an active implementation keeps its captured reinjection policy.
299
+ The export destination affects the next export immediately.
300
+
301
+ > [!WARNING]
302
+ > `safeSubcommands` is a JSON-only full-command trust override, not a read-only allowlist.
303
+ > A matching prefix bypasses all shell checks, including checks on trailing commands, redirects, and mutations.
304
+ > Configure it only for commands and repositories you fully trust.
305
+
306
+ Saves are ordered within one Pi process, preserve unknown fields, and publish atomically; separate Pi processes can still race.
307
+ Invalid settings remain untouched and make Settings read-only; session-start failures use safe defaults.
308
+
309
+ 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.
458
310
 
459
311
  ## 🧠 Codex-like behavior
460
312
 
@@ -469,34 +321,18 @@ This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
469
321
 
470
322
  ## 🗂️ Package layout
471
323
 
472
- ```txt
324
+ ```text
473
325
  packages/pi-plan-mode/
474
- ├── dist/ # Generated TypeScript runtime loaded by Jiti
475
- ├── scripts/
476
- │ └── build-runtime.mjs # Deterministic runtime builder and boundary validator
477
- ├── src/
478
- │ ├── index.ts # Thin Pi package entrypoint
479
- │ ├── plan-mode.ts # Extension registration, mode state, and UI loading boundary
480
- │ ├── interactive-ui.ts # Lazily loaded interactive menu surface
481
- │ └── *.ts # Package-local prompt, policy, question, and message modules
482
- ├── README.md
483
- ├── LICENSE
484
- ├── tsconfig.json
485
- └── package.json
486
- ```
487
-
488
- `index.ts` is the Pi entrypoint and forwards to `plan-mode.ts`; the other source modules are internal.
489
- The package exposes its Pi extension through `package.json`:
490
-
491
- ```json
492
- {
493
- "pi": {
494
- "extensions": ["./dist/index.ts"]
495
- }
496
- }
326
+ ├── src/ # Policy, questions, settings, and handoff modules
327
+ │ ├── index.ts # Thin Pi entrypoint
328
+ │ └── plan-mode.ts # Planning policy and implementation handoff
329
+ ├── dist/ # Generated Jiti runtime
330
+ ├── scripts/build-runtime.mjs # Runtime builder
331
+ ├── docs/ # Published reference documentation
332
+ └── test/ # Behavior and lifecycle coverage
497
333
  ```
498
334
 
499
- The generated runtime is built from the authoritative `src/index.ts` graph and does not import back into `src`.
335
+ The generated runtime is built from `src/index.ts` and does not import back into `src`.
500
336
 
501
337
  ## 🔎 Keywords
502
338
 
@@ -0,0 +1,48 @@
1
+ # Plan command workflows
2
+
3
+ [Back to README](../README.md#-commands)
4
+
5
+ ## Start and choose tools
6
+
7
+ `/plan start` activates Plan mode without sending a model message.
8
+ `/plan <prompt>` starts with an initial planning message, or sends an ordinary follow-up when already active.
9
+ Only the exact argument `start` selects direct activation; `/plan start a migration` is a planning prompt.
10
+ There is no startup flag; run `/plan start` after Pi launches.
11
+
12
+ Before starting, `/plan tools` or **Choose tools, then start…** stages a session-specific tool policy.
13
+ **Done — start with this policy** stores the selection and starts Plan mode.
14
+ Back, Escape, Ctrl+C, disposal, session replacement, or shutdown discards the unconfirmed draft without changing Plan state, active tools, thinking, or stored selection.
15
+ Persistent defaults belong in [Settings](./settings.md).
16
+
17
+ The TUI selector supports fuzzy search and paging; RPC shows the unfiltered list.
18
+ Blocked, inactive, or not-yet-registered tools remain distinguishable, and selected names awaiting metadata stay selected for first-request resolution.
19
+ Reopen the selector to refresh newly registered tools.
20
+ Active and ready workflows lock tools and settings; exit and start a new workflow to change the allowlist.
21
+ See [Planning and implementation](../README.md#-planning-and-implementation) for the first-request policy boundary, completion, and same-session versus fresh-session handoff.
22
+
23
+ ## Busy transitions and recovery
24
+
25
+ Wait for Pi's run to settle before starting, exiting, saving, exporting a ready plan, implementing, or using another state-changing menu action or configured shortcut.
26
+ Busy transitions leave state unchanged and report a warning in TUI/RPC or an error in print/JSON mode.
27
+ An ordinary follow-up or `/plan finalize` can still run while Plan mode is active because neither changes its mode contract.
28
+
29
+ `show`, `save`, `export`, and `implement` require an applicable stored plan; `finalize` requires active Plan mode.
30
+ Cancellation and failed implementation preflight leave the stored plan intact.
31
+ For finalization retries, fresh-session recovery, and non-interactive limitations, see [Planning and implementation](../README.md#-planning-and-implementation).
32
+
33
+ ## Export Markdown
34
+
35
+ `/plan export [path]` writes a ready, saved, or active implementation plan.
36
+ Without a path, it uses the configured **Export destination**, defaulting to `PLAN.md`; an explicit path always overrides the setting for that export.
37
+ Relative paths resolve from Pi's current working directory at export time, absolute paths stay absolute, a leading `@` is accepted, and missing parent directories are created.
38
+ Existing files, directories, and symbolic links are never overwritten: choose another path or remove the target first.
39
+ The output preserves accepted Markdown exactly apart from one trailing newline.
40
+
41
+ In TUI or RPC, **Export plan…** asks for a destination and shows the configured value and its resolved path.
42
+ Submit an empty value to use the configured destination.
43
+ A failed export retains the TUI draft for correction or reopens the RPC input; Escape returns without writing.
44
+
45
+ A successful ready-plan export ends Plan mode, restores thinking, and clears the ready state without starting a model turn or changing active tools.
46
+ Saved and active implementation exports preserve their existing state.
47
+ Failed or cancelled exports leave Plan state unchanged.
48
+ Export is an explicit user-requested file mutation, and the resulting file can be read with normal tools; model-initiated Plan-mode writes remain blocked.
@@ -0,0 +1,147 @@
1
+ # Pi Plan Mode settings reference
2
+
3
+ [Back to README](../README.md)
4
+
5
+ - [Default Plan policy tools](#default-plan-policy-tools)
6
+ - [Plan reinjection](#plan-reinjection)
7
+ - [Export destination](#export-destination)
8
+ - [Toggle shortcut](#toggle-shortcut)
9
+ - [Safe shell subcommands](#safe-shell-subcommands)
10
+ - [Thinking level and persistence](#thinking-level)
11
+
12
+ ## ⚙️ Settings
13
+
14
+ Open **Settings** from an inactive `/plan` menu to edit **Plan thinking**, **Plan policy tools**, **Plan reinjection**, **Export destination**, and **Plan mode shortcut**.
15
+ You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
16
+ `safeSubcommands` is JSON-only.
17
+ The optional file is read at session start, watched for changes, and created only by an explicit Settings save or manual edit.
18
+ The shortcut is disabled when `toggleShortcut` is omitted.
19
+ ```json
20
+ {
21
+ "thinkingLevel": "inherit",
22
+ "defaultPlanTools": ["read", "bash", "grep", "find", "ls"],
23
+ "implementationPlanRetention": "clear-on-start",
24
+ "defaultPlanExportPath": "PLAN.md",
25
+ "safeSubcommands": {
26
+ "git": ["rev-parse", "blame"],
27
+ "gh": ["pr view", "issue list"],
28
+ "kubectl": ["get", "apply"],
29
+ "npm": ["run inspect-custom"]
30
+ },
31
+ "toggleShortcut": "<your_key>"
32
+ }
33
+ ```
34
+
35
+ ### Plan helper tools
36
+
37
+ Plan helper schemas are stable from extension registration onward, and Plan mode does not call `setActiveTools()`.
38
+ Tool visibility alone is not Plan activation.
39
+ 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.
40
+ The retired `toolVisibility` key is ignored and preserved as unknown data when another setting is saved or a legacy settings file is migrated.
41
+
42
+ ### Default Plan policy tools
43
+
44
+ `defaultPlanTools` defines the initial runtime allowlist when a session has no stored pre-start selection.
45
+ Omit it—or choose **Use automatic safe built-ins**—to allow already-active safe built-ins by default.
46
+ An explicit empty array appears as **No optional tools** and denies every ordinary tool while the required helpers remain callable in Plan mode.
47
+ Neither setting changes model-visible tool schemas.
48
+
49
+ Tool names must be non-empty strings; duplicates are removed in first-seen order.
50
+ Explicit configured or session-selected names remain policy intent when their tool is unknown or inactive, but Plan mode never registers or activates them.
51
+ 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.
52
+ 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.
53
+ 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.
54
+ The resolved allowlist persists with the active workflow and restores without reopening the resolution boundary after reload, resume, or tree navigation.
55
+ 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.
56
+ Settings shows unresolved names as pending registration; resetting to automatic removes the entire override.
57
+ 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.
58
+ Plan mode does not interpret a selected custom tool's arguments or actions: allowing one trusts the whole effective tool.
59
+ Pi resolves tools by name, so if an extension overrides a built-in name, the effective extension tool is selected instead.
60
+ An effective active tool named `bash` or `powershell` remains subject to its limited-shell policy regardless of its source metadata.
61
+
62
+ 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.
63
+ The global setting remains the policy baseline for fresh sessions and sessions without an explicit selection.
64
+ 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.
65
+
66
+ ### Plan reinjection
67
+
68
+ 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.
69
+ 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.
70
+ In the planning session, this policy sends `Implement the plan.` and relies on the accepted plan already present in ordinary conversation history.
71
+ 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.
72
+ Use `clear-after-first-run` for **Through first implementation run** to guarantee the exact plan until that implementation's first fully settled run ends.
73
+ Use `keep` for **Until manually cleared** to guarantee and reinject the exact plan until `/plan exit` or supersession.
74
+ A resumed guaranteed-plan cleanup policy re-arms against the first context in the replacement session.
75
+ Failed handoff delivery restores the ready or saved plan and does not run automatic cleanup.
76
+
77
+ Changing this setting applies to the next Implement action only.
78
+ Each guaranteed-plan implementation stores its effective policy, so a later Settings save cannot shorten or extend an implementation already in progress.
79
+ Conversation-history-only implementation has no active Plan-mode state to show, export, or clear after kickoff.
80
+
81
+ ### Export destination
82
+
83
+ `defaultPlanExportPath` controls only exports that omit a path.
84
+ Omit it—or submit an empty value in Settings—to use `PLAN.md`.
85
+ The value must be a non-empty string of at most 4,096 characters without terminal control characters or NUL.
86
+ Relative values are resolved against the current working directory at export time; the Settings detail and every export input preview the concrete resolved destination.
87
+ An explicit `/plan export <path>` is a one-off override and does not edit Settings.
88
+ Saving a new destination affects the next export immediately, including export of a currently active implementation.
89
+
90
+ The existing no-overwrite, cancellation, and atomic Plan-state behavior is unchanged.
91
+ A failed save rolls the row back to its previous value; a failed or cancelled export preserves the plan and target.
92
+ Long previews wrap or truncate to the available terminal width without changing the raw path used by the action.
93
+
94
+ ### Toggle shortcut
95
+
96
+ `toggleShortcut` controls the global Plan-mode keybinding used by the TUI shortcut.
97
+ Omit this setting to keep the shortcut disabled.
98
+ Set `toggleShortcut` to the key string you want.
99
+ Avoid values that conflict with editor shortcuts.
100
+
101
+ ### Safe shell subcommands
102
+
103
+ `safeSubcommands` maps any command prefix to subcommand prefixes that the user chooses to trust completely in limited `bash` and `powershell`.
104
+ For example, `"kubectl": ["get", "apply"]` trusts commands beginning with `kubectl get` or `kubectl apply`, while `"npm": ["run inspect-custom"]` trusts commands beginning with `npm run inspect-custom`.
105
+ Command keys and subcommand entries are trimmed and must be non-empty strings.
106
+ Matches are literal and case-sensitive after leading whitespace in the submitted command is ignored.
107
+ A match requires the complete `<command> <subcommand>` prefix followed by whitespace, a shell control operator, or the end of the submitted command, so `"kubectl": ["apply"]` does not match `kubectl applies`.
108
+ Duplicate values and command keys that become equal after trimming are merged in first-seen order.
109
+ Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
110
+
111
+ When a configured prefix matches, Plan mode permits the complete submitted command without parsing or applying any command, argument, mutation, chain, redirect, expansion, substitution, multiline, or PowerShell syntax checks.
112
+ For example, `"kubectl": ["apply"]` also permits `kubectl apply -f deployment.yaml && rm -rf build`.
113
+ Likewise, `"gh": ["pr view"]` permits `gh pr view 218 --web`, `gh pr view 218 > pr.txt`, and any trailing shell content.
114
+ The setting therefore delegates the complete shell decision to the user and can allow arbitrary code execution with Pi's permissions.
115
+ It is not a sandbox, confirmation gate, or read-only guarantee.
116
+ Choose entries that are as specific as your workflow permits, and configure them only for commands and repositories you fully trust.
117
+
118
+ Commands that do not match still use the built-in fail-closed reviewed policy.
119
+ That default policy includes Git `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, and `grep`, with command-specific argument checks.
120
+ It rejects output and input redirects, shell expansion and substitution, explicit pager or browser requests, explicit external diff, textconv, filter, or signature helpers, mutating flags, malformed command layouts, and any parsed chain containing an unsafe segment.
121
+ 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.
122
+ Use the negative flags when you want to suppress those configured helpers.
123
+ 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 unless explicitly trusted through `safeSubcommands`.
124
+
125
+ Read-only does not mean private: Git inspection can expose repository history and tracked secrets, while configured commands can expose or modify any data available to Pi's process.
126
+ A built-in-policy `git -C <path>` inspection is accepted only when the path keeps Git in Pi's current working directory.
127
+ The default policy reduces accidental mutation and cross-repository executable configuration; configured `safeSubcommands` bypass that protection.
128
+ A non-object `safeSubcommands`, empty command or subcommand string, non-array value, or non-string entry invalidates the entire settings file and triggers the normal warning/default fallback on session start.
129
+
130
+ ### Thinking level
131
+
132
+ Plan mode inherits Pi's current thinking level by default.
133
+ Set `thinkingLevel` to request a fixed level only while Plan mode is active.
134
+ Supported values are `inherit`, `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`.
135
+ 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.
136
+ A Settings save does not change Pi's current or default thinking level and takes effect only when the next Plan workflow starts.
137
+
138
+ Settings saves are serialized in invocation order inside one Pi process.
139
+ 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.
140
+ A missing file stays absent until an explicit save.
141
+ Invalid JSON, invalid values, oversized content, non-regular files, and read failures make Settings read-only; the existing bytes and previous effective settings remain.
142
+ This in-process queue is not a cross-process lock, so concurrent separate Pi processes can still race.
143
+
144
+ Invalid settings produce a warning and fall back to inherited thinking, available safe-built-in tool defaults, `clear-on-start`, and `PLAN.md`.
145
+ Compatibility: a valid legacy `plan-mode.json` remains readable with a warning and is never modified automatically.
146
+ 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.
147
+ If both files exist, the canonical filename takes precedence.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@narumitw/pi-plan-mode",
3
- "version": "0.56.0",
3
+ "version": "0.57.1",
4
4
  "description": "Pi extension that adds a Codex-like read-only /plan collaboration mode.",
5
5
  "type": "module",
6
6
  "license": "MIT",
@@ -15,6 +15,7 @@
15
15
  "files": [
16
16
  "src",
17
17
  "dist",
18
+ "docs",
18
19
  "README.md",
19
20
  "LICENSE"
20
21
  ],
@@ -36,8 +37,8 @@
36
37
  },
37
38
  "devDependencies": {
38
39
  "@biomejs/biome": "2.5.11",
39
- "@earendil-works/pi-coding-agent": "0.84.4",
40
- "@earendil-works/pi-tui": "0.84.4",
40
+ "@earendil-works/pi-coding-agent": "0.85.0",
41
+ "@earendil-works/pi-tui": "0.85.0",
41
42
  "esbuild": "0.28.2",
42
43
  "typescript": "7.0.2"
43
44
  },