# pi-mode-switch

Cycle between operating modes with crouter's configurable **Cycle mode** binding (default **Alt+Shift+P**) — the way Claude's Shift+Tab cycles plan / accept-edits. Whenever the mode changes, the new mode's operating instructions are injected invisibly before your next message.

## Modes

| Mode | What it does |
|---|---|
| `normal` | Full tool access (default). Restrictions lifted. |
| `spec` | Write a specification before any code. No edits. |
| `plan` | Produce an implementation plan. Read-only, no changes. |

## Usage

- the configured `crtr.mode.cycle` binding (default `Alt+Shift+P`) — cycle `normal → spec → plan → normal`
- `/mode` — cycle without using the shortcut
- `/mode <normal\|spec\|plan>` — jump to a specific mode
- the agent can switch its own mode by running the bundled `bin/mode` CLI through its bash tool — e.g. `bash <plugin>/bin/mode normal` after a spec/plan is approved. The command prints that mode's guidance, so the text only enters context at the moment of the switch (no always-on tool)

The current mode renders as a badge on the **bottom-right of the input box**, diagonally opposite the session-name badge (top-left). Mode persists across `--resume`.

## How it works

The extension tracks the active mode and the mode whose guidance was last injected. On `before_agent_start` it compares the two: if they differ, it prepends that mode's guidance to the turn as a hidden `mode-switch-context` message and records the injection. Stay in the same mode and nothing extra is added. Returning to `normal` also strips stale guidance from context.

The agent can also switch its own mode without a permanent tool. The bundled `bin/mode` CLI, run through the normal bash tool, writes the requested mode to `nodes/<node-id>/mode/request.json` and prints that mode's operating instructions to stdout. The extension mirrors each mode's guidance to `mode/guidance/<mode>.txt` at session start, watches the request file to keep the badge and session state in sync, and applies each tokenized request once. The guidance reaches the agent through the command's own output, so it only enters context at the moment of the switch — no tool sits in the context window, and there's no coupling to an external runtime beyond the shared files.

This is guidance-only — it does not hard-restrict tools. The instructions tell the agent not to edit in spec/plan mode; combine with a tool gate if you want enforcement.

The input badge is drawn by wrapping whatever editor is already installed (for example, a session-name badge extension) in a transparent Proxy that overrides only `render()`. It composes instead of replacing, so other editor decorations keep working.

## Install

This package ships inside crouter. `crtr sys setup` registers its built package path with pi; there is no separate repository or package to install.

Run `/reload` in pi after setup. The extension resolves `crtr.mode.cycle` from the sparse `keybindings` object in `~/.crouter/config.json`; missing overrides use Alt+Shift+P, multiple gestures all register, and an empty list disables the shortcut. `/mode` remains available when the shortcut is disabled. Pi's stock actions and `~/.pi/agent/keybindings.json` remain untouched.