# Plan Mode

Pi extension for read-only planning followed by an explicit, user-selected approval handoff to Build mode.

## Install

Install the umbrella Git package to load both extensions and the bundled planning skill:

```bash
pi install git:github.com/pixelsnis/pi-extensions
```

To install just this extension from npm, after the package has been published:

```bash
pi install npm:@pixelsnis/pi-plan-mode
```

Restart Pi or run `/reload` after changing package settings. To remove an installation, use the same package source with `pi remove`, for example `pi remove npm:@pixelsnis/pi-plan-mode` or `pi remove git:github.com/pixelsnis/pi-extensions`.

## Modes and tool gate

Build is the default mode. `/plan` toggles between Build and Plan and updates the mode badge. `/plan-profile` displays the selected model profile; `/plan-profile <name>` changes it.

Plan mode is deny-by-default for **agent tool calls**. It permits `read`, `grep`, `find`, and `ls` for inspection; `plan_save` to write the current generated plan file; and `plan_present` to open explicit review. A top-level `allowedTools` list can add exact, case-sensitive agent tool names to this built-in set:

```json
"allowedTools": ["ask_user_question", "web_search"]
```

The list is global and additive across all model profiles. Omit it or use `[]` to retain the default behavior. Names are accepted before a tool is registered, so a valid unknown name is harmless until a matching third-party tool becomes available; the matching is exact and case-sensitive. Each name must be a non-empty, already-trimmed string, and duplicate names are configuration errors. Unlisted agent tools remain blocked.

Without `"bash"` in `allowedTools`, Bash is conditionally permitted only for simple read-only commands from this exact allowlist:

- `pwd`, `ls`, `find`, `grep`, `rg`, `cat`, `head`, `tail`, `wc`, `file`, and `stat`
- Git's `status`, `diff`, `log`, and `show` subcommands

For example, `ls -la`, `find . -type f -name '*.ts'`, `pwd && ls -la`, `rg -n 'PLAN_TOOLS\b' extensions/plan-mode/index.ts`, `rg -n '.*;$' extensions/plan-mode/index.ts`, and `rg -n 'PLAN_TOOLS|READ_ONLY_BASH_COMMANDS' extensions/plan-mode/index.ts | head -5 && git status --short --branch` are accepted. Every command in every pipeline and `&&` branch must independently pass the same checks. Single-quoted text is literal, so quoted regex punctuation such as backslashes and `$` is safe; double-quoted text allows literal regex patterns but rejects unescaped `$`, backticks, and `!`. The recognizer rejects unlisted commands, other shell chaining/operators (including `;`, `||`, and lone `&`), redirection, command/process substitutions, multiline input, wrappers, and known mutating or execution options (including `find -delete`, `find -exec*`, `file --compile`, Git external-diff/textconv/output options, and ripgrep preprocessor options). If a command cannot be parsed or its read-only behavior is uncertain, it is blocked. Listing `"bash"` explicitly trusts every agent Bash call and removes this read-only filter; Plan Mode does not infer side effects for any allowlisted tool. Interactive `!`/`!!` shell commands remain unconditionally blocked by the separate `user_bash` handler, even when `bash` is allowlisted.

This is a tool gate, not an OS sandbox: extensions execute with Pi's normal process permissions. Pi still records extension state in the session, and the user-invoked `/plan-profile` command may update the profile selection in `plan-mode.json`. Allowlisting a mutating built-in such as `write` or `edit` likewise trusts every call to that exact name.

The extension injects a hidden mode-context message, but does not display the plan inline. Its bundled `plan-writing` skill supplies the generic planning workflow and is included in both this package and the repository's root Pi manifest.

## Save and review a plan

1. Switch to Plan with `/plan` and ask Pi to inspect the project and prepare a plan.
2. The agent reads the `plan-writing` skill and saves the plan using `plan_save`. That tool accepts Markdown only; it never accepts a destination path. It returns a path relative to the session working directory.
3. The agent calls `plan_present` with only the exact relative path string returned by `plan_save`. Do not substitute an absolute path or another spelling, even if it resolves to the same file. In the Pi TUI, a scrollable review shows the plan and requires an explicit choice:
   - **R — Refine:** return to chat in Plan mode without recording approval.
   - **N — Approve & Execute:** start a linked fresh session in Build mode.
   - **H — Approve & Continue Here:** switch this session to Build mode and continue here with the current model and effort.
   - **Esc — Cancel:** keep Plan mode active; no approval is recorded.

Approval uses a one-time handoff. Before execution, the extension checks that the plan still belongs to the source session and is readable, and that the selected profile has not changed. Stale, missing, or invalid plans do not execute. In a non-TUI run, `plan_present` cannot record approval and returns without executing.

The internal `/plan-handoff` and `/plan-build-start` commands carry the approved handoff. They are implementation details; use the review UI rather than invoking them directly.

## Plan-file location and safeguards

- In a Git project, the extension stores plans beneath the repository's Git administrative directory in `implementation-plans/` (normally `.git/implementation-plans/`). Plans are not ordinary tracked project files.
- Outside a Git project, it creates a unique `<project>-implementation-plans.*` directory under the operating system's temporary directory.
- The extension creates private directories/files, requires a non-empty plan no larger than 200 KiB, and rejects redirected directories, symlinks, and linked/non-regular plan files. It stores and validates the canonical absolute plan path internally, but `plan_present` accepts only the exact relative path string returned by `plan_save` for the current session working directory.

Keep the path returned by the tool; do not guess or substitute a path. Plans in temporary storage may be removed by the operating system.

## Model profiles

Optional configuration is read from `$PI_CODING_AGENT_DIR/plan-mode.json`, or `~/.pi/agent/plan-mode.json` when `PI_CODING_AGENT_DIR` is unset. A profile contains both Plan and Build model settings:

```json
{
  "profiles": {
    "work": {
      "plan": { "id": "provider/planning-model", "effort": "medium" },
      "build": { "id": "provider/build-model", "effort": "high" }
    }
  },
  "selectedProfile": "work",
  "allowedTools": ["ask_user_question", "web_search"]
}
```

Replace the example IDs with exact `provider/model-id` values available in your Pi installation. Configure one to five profiles. Profile names must be safe single tokens beginning with a letter or digit and may contain letters, digits, `_`, or `-`; `__proto__`, `constructor`, and `prototype` are reserved and rejected. Each profile must define both `plan` and `build`; each `effort` must be `default`, `low`, `medium`, `high`, `xhigh`, or `max`. Pi may clamp a level to what the selected model supports. `allowedTools` is a top-level setting shared by every profile, additive to the fixed Plan tools, and is preserved when `/plan-profile <name>` rewrites the file; it is not profile-specific. Unknown fields, duplicate JSON keys, an invalid `selectedProfile`, and malformed `allowedTools` entries are reported as configuration errors. If `selectedProfile` is omitted, the first profile in file order is selected.

The extension does not validate `allowedTools` against Pi's current tool registry, which permits third-party tools that register later. This is an explicit trust boundary: Plan Mode cannot determine an allowlisted tool's side effects, so every call to that exact name is allowed. In particular, allowlisting `bash` removes the agent Bash command filter, and allowlisting mutating built-ins such as `write` or `edit` permits them. Interactive `!`/`!!` commands are still blocked separately. Restart Pi or run `/reload` after changing the configuration.

The older top-level format remains supported:

```json
{
  "plan": { "id": "provider/planning-model", "effort": "medium" },
  "build": { "id": "provider/build-model", "effort": "high" },
  "allowedTools": ["ask_user_question", "web_search"]
}
```

`allowedTools` is also accepted in this legacy top-level form and has the same global semantics. Profile selection converts legacy settings to the profile form without discarding or reordering the list.

`effort: "default"` does not force a level; a fresh session uses Pi's configured default. Continue Here ignores the Build settings and keeps whatever model and effort are currently active. Missing or unavailable models and invalid configuration are reported. Selecting a profile persists it to the config file, so treat that file as user configuration rather than part of the plan-file write boundary.

## Troubleshooting

- **Plan tools are missing:** Confirm the extension loaded, then restart Pi or run `/reload`.
- **Plan mode appears inactive:** Use `/plan`; the badge shows the current mode and selected profile.
- **Approval does not start execution:** Review in the interactive TUI. Check that the plan path is still readable and that the configured Build model is available; stale handoffs require a new review.
- **A profile will not load:** Check JSON syntax, exact provider/model IDs, both `plan` and `build` entries, valid effort names, and model authentication.
- **A plan cannot be saved or reviewed:** Keep the exact tool-returned path and ensure the plan is non-empty and within 200 KiB. Do not replace its generated directory or file with a symlink.

## Local development

From the repository root, load just this package for a local session:

```bash
pi --no-extensions -e ./extensions/plan-mode
```

The bundled skill source is at `skills/plan-writing/SKILL.md`; the parent repository's root package also exposes it for the Git installation route.
