@narumitw/pi-plan-mode 0.55.2 → 0.56.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,20 +2,18 @@
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@narumitw/pi-plan-mode)](https://www.npmjs.com/package/@narumitw/pi-plan-mode) [![Pi extension](https://img.shields.io/badge/Pi-extension-blue)](https://pi.dev) [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](./LICENSE)
4
4
 
5
- Explore a codebase, resolve important questions, and produce an implementation-ready plan before Pi is allowed to edit files.
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
- - Keeps Plan helper schemas stable from startup while runtime policy blocks inactive helpers, mutations, and unsafe shell forms.
13
- - Requires structured questions for important ambiguity and explicit completion for a decision-ready plan.
14
- - Reviews the complete plan before implementation, export, save, continued planning, or discard.
15
- - Starts implementation in the planning session or a fresh linked session with the exact approved plan.
16
- - Persists Plan state and one saved plan across resume and compaction.
17
- - Exposes statusline state and a configurable Plan tool allowlist, including reviewed native PowerShell inspection on Windows, plus export destination, plan reinjection, shortcut, and thinking level.
18
- - Cooperates anonymously with Workflow Mutex Protocol v1 participants so only one agent workflow starts in a session.
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
+ - Restores Plan state and one saved plan across resume and compaction.
15
+ - Configures the Plan tool allowlist, reviewed shell commands, user-trusted subcommands, export path, plan reinjection, shortcut, and thinking level.
16
+ - Publishes statusline state and cooperates anonymously with Workflow Mutex Protocol v1 participants.
19
17
 
20
18
  ## 📦 Install
21
19
 
@@ -39,37 +37,14 @@ npm --workspace @narumitw/pi-plan-mode run build
39
37
  pi -e ./packages/pi-plan-mode
40
38
  ```
41
39
 
42
- The package declares `dist/index.ts`, so an unbuilt local checkout must run the build before Pi loads the package directory.
40
+ The package declares `dist/index.ts`, so build an unbuilt local checkout before Pi loads the package directory.
41
+ Install only from sources you trust because Pi extensions run with Pi's permissions.
43
42
 
44
43
  ## 🚀 Quick start
45
44
 
46
45
  Run `/plan` to open the state-aware menu, then start Plan mode and ask the agent to inspect and design the change.
47
46
  Run `/plan <prompt>` when the first planning request is already known.
48
47
 
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
48
  ## 💬 Commands
74
49
 
75
50
  ```text
@@ -95,12 +70,12 @@ Use `/plan <prompt>` to enter Plan mode and immediately submit `<prompt>` as the
95
70
  The exact argument `start` is reserved for direct activation; longer text such as `/plan start a migration` remains an inline planning prompt.
96
71
  The extension does not register a startup flag; run `/plan start` after launch for direct activation.
97
72
 
98
- Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific Plan policy override before Planning starts.
73
+ Use **Choose tools, then start…** or the `/plan tools` compatibility shortcut to choose a session-specific Plan policy before planning starts.
99
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.
100
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.
101
76
  Configured or previously selected names without current metadata appear as pending registration and remain selected for first-request resolution.
102
77
  Reopen the picker to refresh tools registered while it was closed because Pi exposes no live tool-registration event.
103
- In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC keeps the complete unfiltered list.
78
+ In TUI mode, type to fuzzy-search tool names, descriptions, policy, and source metadata; RPC shows the complete unfiltered list.
104
79
  Once Plan mode is active, tools are locked: `/plan` no longer offers tool or Settings actions, and `/plan tools` rejects the request.
105
80
  Exit and start a new workflow if a different tool set is required.
106
81
  The `plan_mode_question` tool keeps a dedicated model-requested questionnaire instead of using command-menu navigation.
@@ -135,10 +110,11 @@ A failed TUI export retains the draft for correction; RPC reopens its input dial
135
110
  Escape returns to the owning menu without writing a file.
136
111
  A successful ready-plan export closes the menu and ends Plan mode; saved and active implementation menus close without changing their stored state.
137
112
 
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.
113
+ ## 🔒 Security and privacy
114
+
115
+ While Plan mode is active, the policy blocks built-in editing tools and instructs the agent not to edit files or implement the change.
116
+ It should explore first and ask structured questions when a preference or tradeoff materially changes the plan.
117
+ Configure persistent defaults or a one-workflow tool override before activation; active and ready workflows lock those controls.
142
118
 
143
119
  Plan mode registers `plan_mode_question` and `plan_mode_complete` during extension load and never changes their active status itself.
144
120
  Another active-tool policy may hide them, in which case Plan start or restore fails without widening that policy.
@@ -147,21 +123,32 @@ The optional native `powershell` tool must be active when an automatic Plan poli
147
123
  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
124
  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
125
  For example, you can opt into `firecrawl_scrape`, `firecrawl_search`, or `lsp_diagnostics` when you want to use the effective active tool during planning.
126
+ An active selectable tool omitted from the Plan policy reports that it needs explicit selection through `/plan tools` or `defaultPlanTools` before the next workflow.
127
+ Registered but inactive, unregistered, metadata-free, and built-in blocked tools report their distinct fail-closed reasons instead of suggesting that every denial is a missing selection.
128
+ A tool admitted before later deactivation can be reactivated and reused in the current workflow without restarting.
150
129
  After they become visible, the Plan-only helpers remain visible in Normal mode, but their handlers and the `tool_call` policy reject calls unless Plan mode owns the active workflow.
151
130
 
152
131
  Limited `bash` uses a fail-closed Bash policy, including when an extension overrides the canonical `bash` tool name.
153
132
  It accepts common inspection commands, read-only Git and npm queries, pipelines and command lists composed entirely of accepted commands, plus selected checks such as `npm test`, `npm run typecheck`, and `cargo test`.
154
- It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, mutating flags, dependency changes, editors, and unknown commands.
133
+ It also accepts `hostname` without arguments and local Windows `tasklist` queries using reviewed display, filter, module, and service flags.
134
+ Reviewed Git inspections may place `--no-pager` before the accepted subcommand.
135
+ 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.
136
+ Other targets are rejected so `git -C` cannot introduce executable configuration, hooks, filters, signing programs, or lazy-fetch remotes from another repository.
137
+ It rejects output/input redirects, shell expansion, substitutions, subshells, background jobs, incomplete or directory-changing `-C` pairs, other Git global options, Git config overrides, mutating flags, dependency changes, editors, and unknown commands.
155
138
 
156
139
  Limited `powershell` uses a separate fail-closed PowerShell policy, including when an extension overrides the canonical `powershell` tool name.
157
140
  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`.
141
+ It accepts local `Get-Process` and `Get-Service` queries with reviewed static selectors while rejecting remote and object-input parameters.
158
142
  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.
159
143
  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.
160
144
  Use canonical cmdlet names because PowerShell aliases are intentionally outside the reviewed policy.
161
145
 
162
146
  A rejected parsed command list or pipeline identifies its first blocked command segment; malformed or unsupported shell syntax reports the complete submitted input instead.
163
147
  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.
164
- Both limited-shell policies are extension-level risk reduction, not an OS sandbox or confidentiality boundary.
148
+ Both limited-shell policies reduce risk but do not provide an OS sandbox or confidentiality boundary.
149
+ A configured `safeSubcommands` match bypasses both policies completely, so use it only when you intend to trust the entire submitted shell command.
150
+
151
+ ## 🧭 Planning and implementation
165
152
 
166
153
  `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.
167
154
  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.
@@ -274,6 +261,30 @@ During a guaranteed-plan implementation, it removes both the original implementa
274
261
  /plan exit
275
262
  ```
276
263
 
264
+ ## 🧱 Cache-stable mode transitions
265
+
266
+ Plan and Normal requests share one append-only conversation.
267
+ 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.
268
+ Ordinary linear turns do not rewrite or duplicate these contracts.
269
+ **Implement here** retains the Plan dialogue, structured questions, tool calls, completion evidence, and `Implement the plan.` kickoff in order.
270
+ **Start fresh and implement** is the isolation path and transfers only the approved plan plus the Normal contract to a linked session.
271
+
272
+ The `context` hook filters repeated legacy `plan-mode-context` artifacts but preserves current transition messages.
273
+ If compaction removes the effective transition, the hook inserts one canonical fallback at a deterministic retained-history boundary.
274
+ Repeated transforms leave that fallback in place instead of moving it to the newest turn.
275
+ 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.
276
+ Manual `/tree` navigation restores branch-owned Plan state and chooses the matching contract without navigating or adding a branch summary.
277
+ Pi lists hidden transition messages in `/tree`; Plan mode rejects those internal targets, so select an adjacent conversation entry.
278
+
279
+ 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.
280
+ Visible helpers do not mean `/plan` is active, and their descriptions exclude ordinary planning, the `writing-plans` skill, roadmaps, checklists, and plan-file work.
281
+ Only the latest active Plan contract authorizes the helpers; inactive or stale calls fail without accepting a plan or opening question UI.
282
+ Plan mode does not widen a restrictive active-tool policy; start or restore fails when a required helper is unavailable.
283
+ 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.
284
+
285
+ The default `thinkingLevel: "inherit"` avoids a Plan-specific reasoning-parameter change.
286
+ 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.
287
+
277
288
  ## 🤝 Workflow coexistence
278
289
 
279
290
  Plan mode is independently installable and keeps its standalone behavior when no other protocol participant is present.
@@ -310,12 +321,11 @@ Guaranteed coexistence with Goal requires `@narumitw/pi-goal` `0.53.0` or newer
310
321
 
311
322
  ## ⚙️ Settings
312
323
 
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**.
324
+ Open **Settings** from an inactive `/plan` menu to edit **Plan thinking**, **Plan policy tools**, **Plan reinjection**, **Export destination**, and **Plan mode shortcut**.
314
325
  You can also edit `$PI_CODING_AGENT_DIR/pi-plan-mode.json` (normally `~/.pi/agent/pi-plan-mode.json`) manually.
315
- `safeSubcommands` remains JSON-only.
316
- You can change the Plan-mode shortcut with `toggleShortcut` as long as the file remains JSON-only and uses a valid key string.
317
- 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.
318
- When omitted, the shortcut is disabled by default.
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.
319
329
  ```json
320
330
  {
321
331
  "thinkingLevel": "inherit",
@@ -323,8 +333,10 @@ When omitted, the shortcut is disabled by default.
323
333
  "implementationPlanRetention": "clear-on-start",
324
334
  "defaultPlanExportPath": "PLAN.md",
325
335
  "safeSubcommands": {
326
- "git": ["status", "log", "rev-parse", "blame"],
327
- "gh": ["pr view", "pr list", "issue view", "issue list"]
336
+ "git": ["rev-parse", "blame"],
337
+ "gh": ["pr view", "issue list"],
338
+ "kubectl": ["get", "apply"],
339
+ "npm": ["run inspect-custom"]
328
340
  },
329
341
  "toggleShortcut": "<your_key>"
330
342
  }
@@ -398,55 +410,32 @@ Avoid values that conflict with editor shortcuts.
398
410
 
399
411
  ### Safe shell subcommands
400
412
 
401
- `safeSubcommands` adds reviewed command validators to limited `bash` and `powershell`; it is not a raw shell allowlist.
402
- Only the following exact values are accepted:
403
-
404
- - `git`: `status`, `log`, `diff`, `show`, `branch`, `remote`, `ls-files`, `grep`, `rev-parse`, `blame`, `describe`, `merge-base`, `ls-tree`, and `cat-file`.
405
- - `gh`: `pr view`, `pr list`, `issue view`, and `issue list`.
406
-
407
- The first eight Git validators are built in and remain enabled when omitted, so listing them is valid but redundant.
408
- The other six Git validators and every `gh` path require an explicit opt-in.
409
- 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`.
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.
410
419
  Omitted `safeSubcommands`, an empty object, and empty arrays preserve the default policy.
411
- Duplicate values are removed in first-seen order.
412
-
413
- With the example configuration above, commands such as these are accepted:
414
-
415
- ```bash
416
- git rev-parse --show-toplevel
417
- git blame -- src/plan-mode.ts
418
- git diff --cached
419
- git show --stat --oneline HEAD
420
- git log -p -1 HEAD -- src/plan-mode.ts
421
- gh pr view 218 --json number,title,state
422
- gh issue list --state open --json number,title,state
423
- ```
424
-
425
- The command-specific validators still reject unsafe forms, including:
426
420
 
427
- ```bash
428
- git blame --textconv -- src/plan-mode.ts
429
- git cat-file --filters HEAD
430
- git diff --ext-diff
431
- git log --show-signature -1
432
- git remote show origin
433
- git show --textconv HEAD
434
- gh pr merge 218
435
- gh pr view 218
436
- gh pr view 218 --web
437
- gh pr view 218 > pr.txt
438
- gh pr list --json number,title && gh pr merge 218
439
- ```
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.
440
427
 
441
- 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.
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.
442
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.
443
432
  Use the negative flags when you want to suppress those configured helpers.
444
- 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.
445
- GitHub CLI read paths require `--json <fields>` output so Plan mode does not rely on `GH_PAGER`, `PAGER`, or gh pager configuration.
446
- 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.
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`.
447
434
 
448
- 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.
449
- The policy reduces accidental mutation and explicit helper execution; it is not a sandbox or a confidentiality boundary.
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.
450
439
 
451
440
  ### Thinking level
452
441
 
@@ -471,16 +460,12 @@ If both files exist, the canonical filename takes precedence.
471
460
 
472
461
  This extension maps Codex's `ModeKind::Plan` behavior onto Pi's extension API:
473
462
 
474
- - Plan mode is a conversational collaboration mode, not TODO/progress tracking.
475
- - `/plan <prompt>` follows Codex behavior by switching to Plan mode before submitting the inline prompt.
476
- - The agent should use `plan_mode_question` for important non-discoverable preferences or tradeoffs before finalizing.
477
- - The agent completes with a standalone `plan_mode_complete` tool call instead of relying on semantic prose detection.
478
- - `update_plan` checklist use is blocked while Plan mode is active.
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.
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.
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.
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.
483
- - Unlike native Codex, this extension uses a terminating Pi tool plus an `agent_settled` ready flow; Pi cannot provide sandbox-level enforcement.
463
+ - Plan mode is conversational collaboration, not TODO or progress tracking.
464
+ - `/plan <prompt>` enters Plan mode before submitting the prompt.
465
+ - The agent uses `plan_mode_question` for material preferences and completes with a standalone `plan_mode_complete` call instead of prose detection.
466
+ - `update_plan` is blocked until the explicit implementation boundary restores Normal mode.
467
+ - The default `clear-on-start` policy uses conversation history; `clear-after-first-run` and `keep` add exact-plan guarantees.
468
+ - Append-only Plan and Normal contracts keep helper schemas stable, but Pi's tool policy is risk reduction rather than Codex sandbox enforcement.
484
469
 
485
470
  ## 🗂️ Package layout
486
471
 
@@ -490,7 +475,7 @@ packages/pi-plan-mode/
490
475
  ├── scripts/
491
476
  │ └── build-runtime.mjs # Deterministic runtime builder and boundary validator
492
477
  ├── src/
493
- │ ├── index.ts # Pi package entrypoint
478
+ │ ├── index.ts # Thin Pi package entrypoint
494
479
  │ ├── plan-mode.ts # Extension registration, mode state, and UI loading boundary
495
480
  │ ├── interactive-ui.ts # Lazily loaded interactive menu surface
496
481
  │ └── *.ts # Package-local prompt, policy, question, and message modules