24 24 - kernel declares "active mode is runtime state, not conversation state"
25 25 - persistence requires baseline tracking with stale-tool/stale-model/user-touched edge cases
26 -- apply-time model/thinking pollution already bleeds user defaults; restore makes it worse
26 +- apply-time model/thinking pollution needs a captured baseline to undo cleanly
27 27 - cross-session mode continuity is rare in practice
29 29 ##
Validation status 36 36 - `pi.getAllTools()` + `pi.setActiveTools()` can apply filtered tool lists.
37 37 - `pi.setModel()` and `pi.setThinkingLevel()` are public APIs.
38 38 - `getAgentDir()` resolves the global Pi agent dir.
39 -- `pi-tui.Text` + `Theme.fg()` + `Theme.bold()` for themed header rendering.
40 -- `ctx.ui.setHeader(factory)` installs a custom header above chat; `undefined` restores the built-in.
39 +- `pi-tui.Text` + `Theme.fg()` + `Theme.bold()` for compact themed widget rendering.
40 +- `ctx.ui.setWidget("mode", factory)` installs a visible one-line mode widget above the editor; `undefined` clears it.
48 48 It is not package-exported.
49 49 V1 uses a declared `yaml` dependency for frontmatter parsing.
50 50 - Session persistence (`appendEntry`/`mode-state`).
51 - Memory-only state eliminates baseline tracking and stale-state edge cases.
52 -- Baseline restore on `/mode off`.
53 - Switching into a mode that overrides model/thinking already mutates user defaults via `pi.setModel`/`setThinkingLevel`; restoring adds complexity without removing the underlying SDK limitation.
51 + Memory-only state keeps baseline snapshots process-local and avoids stale cross-session state.
52 +- Cross-session baseline restore.
53 + Baselines are process-local and reset on `session_start`.
54 54 - Compaction checkpoint.
55 55 Process memory persists across compaction within one session.
56 56 - Branch restore on `session_start`.
64 64 - No settings mutation for mode switching.
65 65 - No `/reload` as part of mode switching.
66 66 - No extension-to-extension API.
67 -- No mode baseline restore/update system.
67 +- No cross-session baseline restore/update system.
68 68 - No tool metadata in the active block.
69 -- No shortcut/keybinding support.
69 +- No custom keybinding config.
70 70 - No file watching.
71 71 - No cross-session mode persistence.
72 -- No restore of previous tools/model/thinking on `/mode off`.
72 +- No preservation of manual model/thinking changes made while a mode is active.
110 110 id: string; // file stem
111 111 description?: string; // shown by /mode, no runtime behavior
112 - accent?: AccentColor; // theme color for header banner
112 + accent?: AccentColor; // theme color for widget banner
113 113 model?: string; // provider/model-id, split at first slash
114 114 thinking?: ThinkingLevel;
115 115 reminder?: string; // short active-block reminder
116 - tools?: string[]; // absent/empty = do not change active tools
116 + tools?: string[]; // absent/empty = use captured baseline tools
117 117 body: string; // Markdown body appended to system prompt while active
151 151 1. Reload mode files.
152 152 2. Resolve mode by id.
153 -3. Set in-memory `activeModeId = id`.
153 +3. Set in-memory `activeMode = mode`.
154 154 4. Set in-memory `neutralize = false`.
155 155 5. If `tools` exists and is non-empty, validate names against `pi.getAllTools()` and apply valid names via `pi.setActiveTools(validTools)`.
156 156 6. Warn for unknown tools and continue.
159 159 9. If resolved, call `await pi.setModel(model)`.
160 160 10. If `pi.setModel()` returns `false`, warn and keep current model.
161 161 11. If `thinking` exists, call `pi.setThinkingLevel(thinking)`.
162 -12. Install themed header via `ctx.ui.setHeader(buildHeader(mode))`.
162 +12. Install themed widget via `ctx.ui.setWidget("mode", buildWidget(mode))`.
164 -`tools` absent or empty means the mode does not alter active tools.
164 +`tools` absent or empty means the mode uses the captured baseline tools.
166 -Switching from mode A to mode B does not restore baseline first.
167 -B only applies fields it declares.
166 +Before the first mode switch, capture `pi.getActiveTools()`, `ctx.model`, and `pi.getThinkingLevel()` as the session-local baseline.
167 +Switching from mode A to mode B restores baseline tools/model/thinking first, then applies B's fields.
169 -**SDK limitation:** `pi.setModel` and `pi.setThinkingLevel` write to the user's global default settings.
170 -Declaring `model:` or `thinking:` in a mode mutates user defaults for the duration the mode is applied.
171 -Revert with `/model <id>` and `/thinking <level>` after `/mode off` if the user wants the original defaults back.
169 +**SDK limitation:** `pi.setModel` and `pi.setThinkingLevel` write to the user's global default settings, and thinking restore may be clamped by current model capabilities.
170 +`/mode off`, `session_start`, and `session_shutdown` restore the captured baseline when one exists.
173 172 ##
Normal/off behavior 185 -- If `activeModeId` is `null` (no mode was active), notify `no mode active` and return.
184 +- If `activeMode` is `null` (no mode was active), notify `no mode active` and return.
187 - - Set in-memory `activeModeId = null`.
186 + - Set in-memory `activeMode = null`.
188 187 - Set in-memory `neutralize = true`.
189 - - Clear the custom header via `ctx.ui.setHeader(undefined)` so the built-in header returns.
188 + - Restore baseline tools via `pi.setActiveTools(baselineTools)`.
189 + - Restore baseline model via `pi.setModel(baselineModel)`.
190 + - Restore baseline thinking via `pi.setThinkingLevel(baselineThinking)`.
191 + - Clear the baseline snapshot.
192 + - Clear the custom widget via `ctx.ui.setWidget("mode", undefined)`.
191 -Tools/model/thinking are **not** restored.
192 -They keep whatever the last mode or manual change set them to.
194 +Manual tools/model/thinking changes made while a mode is active are overwritten by baseline restore.
194 196 Fresh normal sessions with no prior mode get no mode block.
195 197 The kernel block is only injected after `/mode off` (when `neutralize = true`).
245 247 /mode status same as /mode
246 248 /mode list show available modes
247 249 /mode <
id> switch active mode
248 -/mode select open an interactive mode picker
250 +/mode select open the fuzzy mode picker
249 251 /mode next cycle to the next mode
250 252 /mode off turn mode off (notify "no mode active" if already off)
251 253 /mode normal alias for /mode off
266 -Active mode replaces the built-in header (logo/instructions) with a themed banner above the chat:
268 +Active mode shows a compact themed widget above the editor:
271 - tools: read, grep, find, ls · model: openai/gpt-5.2-codex · thinking: high
271 +▎ MODE: plan Read-only planning tools: read,grep,find,ls · model: openai/gpt-5.2-codex · thinking: high
274 274 - `accent` frontmatter controls the banner color via `theme.fg(accent, ...)`.
275 275 - Default accent is `accent` (theme default).
276 -- Description line omitted when `description` is absent.
277 -- Meta line (`tools · model · thinking`) omitted when no metadata is declared.
278 -- `accent` defaults; if absent, the banner uses theme accent.
276 +- Description segment is omitted when `description` is absent.
277 +- Meta segment (`tools · model · thinking`) is omitted when no metadata is declared.
280 -`ctx.ui.setHeader(undefined)` clears the custom header and restores the built-in (logo + onboarding) on `/mode off` and `session_start`.
279 +`ctx.ui.setWidget("mode", undefined)` clears the custom widget on `/mode off`, `session_start`, and `session_shutdown`.
282 -The header and footer status are the persistent UI signals of mode state.
281 +The widget and footer status are the persistent UI signals of mode state.
283 282 The footer status shows `mode:<id>` and clears on `/mode off`, `session_start`, and `session_shutdown`.
284 -`ctrl+shift+m` opens the interactive mode picker.
283 +`alt+m` opens the fuzzy mode picker.
285 284 `notify` is reserved for warnings (unknown tool, model not found, malformed ref, parse error, unknown mode id) and empty-picker status.
290 -The in-memory `state.activeModeId` survives `session_compact` automatically (same process).
289 +The in-memory `state.activeMode` survives `session_compact` automatically (same process).
291 290 `before_agent_start` keeps injecting the current mode body/kernel.
293 292 ##
Session lifecycle 297 -1. Reload mode files.
298 -2. Reset in-memory state: `activeModeId = null`, `neutralize = false`.
299 -3. Clear custom header.
296 +1. Restore any captured baseline tools/model/thinking.
297 +2. Reload mode files.
298 +3. Reset in-memory state: `activeMode = null`, `neutralize = false`.
299 +4. Clear baseline tools/model/thinking.
300 +5. Clear custom widget.
301 302 Users must re-run `/mode <id>` after each `session_start`.
303 -`session_shutdown`: clear custom header.
304 +`session_shutdown`: restore any captured baseline, then clear custom widget and status.
305 306 ##
Extension/resource model