@openlines/opl-pi-sht 0.2.11 → 0.3.0

package/extensions/opl-input/configure.ts

@@ -0,0 +1,144 @@
+import type { ExtensionContext, KeybindingsManager, Theme } from "@earendil-works/pi-coding-agent";
+import { getSettingsListTheme } from "@earendil-works/pi-coding-agent";
+import { SettingsList, truncateToWidth, type SettingItem } from "@earendil-works/pi-tui";
+
+import { readInputConfig, saveInputConfig, type EditableInputConfig } from "./config.js";
+
+// The configurator seam. opl-configurator owns the /configurator command and reads this
+// globalThis array lazily; the entry shape is duplicated by hand on both sides because
+// install.sh copies one extension directory at a time.
+export const CONFIGURATOR_REGISTRY_KEY = "__oplConfiguratorTabs";
+
+/** What the configurator shell hands to each tab's factory. */
+export interface ConfiguratorTabApi {
+  ctx: ExtensionContext;
+  tui: { requestRender(): void };
+  theme: Theme;
+  keybindings: KeybindingsManager;
+  done: (result: void) => void;
+}
+
+export interface ConfiguratorTabComponent {
+  render(width: number): string[];
+  invalidate?(): void;
+  handleInput?(data: string): void;
+}
+
+interface ConfiguratorTab {
+  id: string;
+  hotkey: string;
+  label: string;
+  create: (api: ConfiguratorTabApi) => ConfiguratorTabComponent;
+}
+
+const BASE_COMPANION_TYPES = ["cat", "dog", "bunny"];
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)];
+}
+
+function declaredCompanionTypes(companion: Record<string, unknown>): string[] {
+  const types = companion.types;
+  if (!Array.isArray(types)) return [];
+  return unique(
+    types
+      .filter((entry): entry is Record<string, unknown> => typeof entry === "object" && entry !== null)
+      .map((entry) => entry.typeName)
+      .filter((name): name is string => typeof name === "string" && name.length > 0),
+  );
+}
+
+function companionRecord(config: Record<string, unknown>): Record<string, unknown> {
+  return typeof config.companion === "object" && config.companion !== null && !Array.isArray(config.companion)
+    ? (config.companion as Record<string, unknown>)
+    : {};
+}
+
+/** Built-ins plus any declared typeName and the live selection, in that order, deduped. */
+export function companionTypeValues(config: Record<string, unknown>): string[] {
+  const companion = companionRecord(config);
+  const currentType = typeof companion.type === "string" && companion.type.length > 0 ? companion.type : "cat";
+  return unique([...BASE_COMPANION_TYPES, ...declaredCompanionTypes(companion), currentType]);
+}
+
+/** Map a setting item id to its write patch; null for an id the tab does not own. */
+export function inputFieldPatch(id: string, value: string): EditableInputConfig | null {
+  if (id === "boxedView") return { boxedView: value === "true" };
+  if (id === "companion.enabled") return { companion: { enabled: value === "true" } };
+  if (id === "companion.type") return { companion: { type: value } };
+  return null;
+}
+
+/** Publish the input settings screen as a tab, once per extension load. */
+export function registerInputConfiguratorTab(): void {
+  const tab: ConfiguratorTab = {
+    id: "opl-input",
+    hotkey: "i",
+    label: "Input",
+    create: (api) => createInputComponent(api),
+  };
+
+  const holder = globalThis as Record<string, unknown>;
+  const registry = holder[CONFIGURATOR_REGISTRY_KEY];
+  if (Array.isArray(registry)) {
+    if (!registry.some((entry) => entry?.id === "opl-input")) registry.push(tab);
+  } else {
+    holder[CONFIGURATOR_REGISTRY_KEY] = [tab];
+  }
+}
+
+function createInputComponent(api: ConfiguratorTabApi): ConfiguratorTabComponent {
+  const { ctx, theme, done } = api;
+  let config = readInputConfig();
+  let settingsList: SettingsList | null = null;
+
+  const createSettingsList = (): SettingsList => {
+    const companion = companionRecord(config);
+    const boxedView = typeof config.boxedView === "boolean" ? config.boxedView : true;
+    const enabled = typeof companion.enabled === "boolean" ? companion.enabled : false;
+    const currentType = typeof companion.type === "string" && companion.type.length > 0 ? companion.type : "cat";
+
+    const typeValues = companionTypeValues(config);
+
+    const items: SettingItem[] = [
+      { id: "boxedView", label: "Boxed view", currentValue: boxedView ? "true" : "false", values: ["true", "false"] },
+      { id: "companion.enabled", label: "Companion", currentValue: enabled ? "true" : "false", values: ["true", "false"] },
+      { id: "companion.type", label: "Companion type", currentValue: currentType, values: typeValues },
+    ];
+
+    return new SettingsList(items, items.length, getSettingsListTheme(), save, () => done(undefined));
+  };
+
+  const save = (id: string, value: string) => {
+    const patch = inputFieldPatch(id, value);
+    if (!patch) return; // never misroute an unexpected id into companion.type
+
+    try {
+      const changed = saveInputConfig(patch);
+      if (changed) {
+        config = readInputConfig();
+        settingsList = createSettingsList();
+        settingsList.selectItem(id);
+        ctx.ui.notify("opl-input saved. Run /reload (or restart Pi) to apply.", "info");
+      }
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Could not save opl-input config: ${message}`, "error");
+      done(undefined);
+    }
+  };
+
+  settingsList = createSettingsList();
+
+  return {
+    render(width: number) {
+      return [
+        truncateToWidth(theme.bold("Configure OPL Input"), width),
+        truncateToWidth(theme.fg("dim", "Reload (/reload) is required for changes to apply"), width),
+        ...(settingsList ?? createSettingsList()).render(width),
+      ];
+    },
+    invalidate() { settingsList?.invalidate(); },
+    handleInput(data: string) { settingsList?.handleInput?.(data); },
+  };
+}

package/extensions/opl-input/index.ts

@@ -3,6 +3,7 @@ import type { TUI, EditorTheme } from "@earendil-works/pi-tui";
 import type { KeybindingsManager } from "@earendil-works/pi-coding-agent";
 import { visibleWidth, truncateToWidth } from "@earendil-works/pi-tui";
 import { CONFIG, COMPANION_PADDING, MIN_WIDTH_FOR_COMPANION } from "./config.js";
+import { registerInputConfiguratorTab } from "./configure.js";
 import { resolveModeStyle, type ModeAppearance } from "./mode-style.js";
 import { applyColor, CompanionAnimator, COMPANION_TICK_MS, IDLE_REPAINT_MS, startRenderTimer } from "./utils.js";
 
@@ -13,6 +14,34 @@ function plainText(line: string): string {
 	return line.replace(ANSI_RE, "");
 }
 
+// ─── pi-tui private render format ─────────────────────────────────────────────
+// The box renderers below must tell the editor's horizontal borders from its scroll
+// indicator, and pi-tui exposes neither as an API nor as a stable class: it is plain text.
+// These two markers are the whole contract, so they live here instead of being duplicated in
+// each renderer, and tests/opl-input-pi-tui-markers.test.mjs asserts the installed pi-tui
+// still emits them. Verified byte-identical in pi-tui 0.87.0, 0.99.1 and 1.1.0
+// (dist/components/editor.js: `─── ${direction} ${hiddenLineCount} more `).
+const BORDER_CHAR = "─";
+const SCROLL_INDICATOR_RE = /((?:↑|↓)\s*\d+\s*more)/;
+
+/** Solid border: after stripping ANSI every character is the box-drawing horizontal. */
+export function isSolidBorder(line: string): boolean {
+	return plainText(line).replaceAll(BORDER_CHAR, "").length === 0;
+}
+
+/** The scroll indicator (`─── ↑ 3 more `) is border-like but carries text worth preserving. */
+export function scrollIndicatorText(line: string): string | null {
+	const plain = plainText(line);
+	if (!plain.startsWith(BORDER_CHAR)) return null;
+	const match = plain.match(SCROLL_INDICATOR_RE);
+	return match ? match[1]! : null;
+}
+
+/** Anything that marks the top or bottom edge of the stock editor output. */
+export function isBorderLike(line: string): boolean {
+	return isSolidBorder(line) || scrollIndicatorText(line) !== null;
+}
+
 function activeMode(): { mode: string; appearance?: ModeAppearance } {
 	const state = (globalThis as Record<string, unknown>).__agentMode as
 		| { mode?: string; appearance?: ModeAppearance }
@@ -121,19 +150,6 @@ class ChatInput extends CustomEditor {
 	): string[] {
 		const innerWidth = width - 2;
 
-		// Solid border: after stripping ANSI every char is "─"
-		const isSolidBorder = (line: string) => plainText(line).replace(/─/g, "").length === 0;
-
-		// Scroll indicator: starts with "─" and contains ↑/↓ N more
-		const getScrollText = (line: string): string | null => {
-			const plain = plainText(line);
-			if (!plain.startsWith("─")) return null;
-			const m = plain.match(/((?:↑|↓)\s*\d+\s*more)/);
-			return m ? m[1] : null;
-		};
-
-		const isBorderLike = (line: string) => isSolidBorder(line) || getScrollText(line) !== null;
-
 		const firstIdx = stock.findIndex(isBorderLike);
 		let lastIdx = -1;
 		for (let i = stock.length - 1; i >= 0; i--) {
@@ -158,8 +174,8 @@ class ChatInput extends CustomEditor {
 			return border("└") + border(mid) + border("─".repeat(remaining)) + border("┘");
 		};
 
-		const topScrollText = firstIdx !== -1 ? getScrollText(stock[firstIdx]!) : null;
-		const bottomScrollText = lastIdx !== -1 && lastIdx !== firstIdx ? getScrollText(stock[lastIdx]!) : null;
+		const topScrollText = firstIdx !== -1 ? scrollIndicatorText(stock[firstIdx]!) : null;
+		const bottomScrollText = lastIdx !== -1 && lastIdx !== firstIdx ? scrollIndicatorText(stock[lastIdx]!) : null;
 
 		const top = buildTop(topScrollText);
 		const bottom = buildBottom(bottomScrollText);
@@ -207,19 +223,6 @@ class ChatInput extends CustomEditor {
 		accent: (s: string) => string,
 		prefix: string,
 	): string[] {
-		// Solid border: after stripping ANSI every char is "─"
-		const isSolidBorder = (line: string) => plainText(line).replace(/─/g, "").length === 0;
-
-		// Scroll indicator: starts with "─" and contains ↑/↓ N more
-		const getScrollText = (line: string): string | null => {
-			const plain = plainText(line);
-			if (!plain.startsWith("─")) return null;
-			const m = plain.match(/((?:↑|↓)\s*\d+\s*more)/);
-			return m ? m[1] : null;
-		};
-
-		const isBorderLike = (line: string) => isSolidBorder(line) || getScrollText(line) !== null;
-
 		const firstIdx = stock.findIndex(isBorderLike);
 		let lastIdx = -1;
 		for (let i = stock.length - 1; i >= 0; i--) {
@@ -244,8 +247,8 @@ class ChatInput extends CustomEditor {
 			return border(mid) + border("─".repeat(remaining));
 		};
 
-		const topScrollText = firstIdx !== -1 ? getScrollText(stock[firstIdx]!) : null;
-		const bottomScrollText = lastIdx !== -1 && lastIdx !== firstIdx ? getScrollText(stock[lastIdx]!) : null;
+		const topScrollText = firstIdx !== -1 ? scrollIndicatorText(stock[firstIdx]!) : null;
+		const bottomScrollText = lastIdx !== -1 && lastIdx !== firstIdx ? scrollIndicatorText(stock[lastIdx]!) : null;
 
 		const top = buildTop(topScrollText);
 		const bottom = buildBottom(bottomScrollText);
@@ -304,4 +307,9 @@ export default function (pi: ExtensionAPI) {
 		activeEditor?.dispose();
 		activeEditor = null;
 	});
+
+	// Expose the settings screen to opl-configurator's generic shell; the shell owns the
+	// /configurator command and the tab only writes opl-input.json (a /reload is still
+	// required before the running editor picks the change up).
+	registerInputConfiguratorTab();
 }

package/extensions/opl-input/mode-style.ts

@@ -19,8 +19,12 @@ export interface ResolvedModeStyle {
 	prefix: string;
 }
 
+/** The baseline every unknown mode falls back to, kept as a constant so the fallback is a value
+ *  rather than an index into a record that TypeScript must treat as possibly missing. */
+const OFF_DEFAULT: Required<ModeAppearance> = { prefix: "❯", prefixColor: "accent", borderColor: "border" };
+
 const MODE_DEFAULTS: Record<string, Required<ModeAppearance>> = {
-	off: { prefix: "❯", prefixColor: "accent", borderColor: "border" },
+	off: OFF_DEFAULT,
 	chat: { prefix: "»", prefixColor: "borderAccent", borderColor: "borderAccent" },
 	plan: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
 	execute: { prefix: "⏸", prefixColor: "customMessageLabel", borderColor: "customMessageLabel" },
@@ -28,7 +32,7 @@ const MODE_DEFAULTS: Record<string, Required<ModeAppearance>> = {
 
 /** Precedence: bash > active mode appearance > hardcoded mode fallback. */
 export function resolveModeStyle(state: ModeState): ResolvedModeStyle {
-	const fallback = MODE_DEFAULTS[state.mode] ?? MODE_DEFAULTS.off;
+	const fallback = MODE_DEFAULTS[state.mode] ?? OFF_DEFAULT;
 	if (state.bash) return { borderColor: "bashMode", prefixColor: "bashMode", prefix: fallback.prefix };
 	return {
 		borderColor: state.appearance?.borderColor ?? fallback.borderColor,

package/extensions/opl-modes/README.md

@@ -11,7 +11,7 @@ Unified mode manager for Pi. It provides normal, read-only chat, read-only plann
 - `--chat` and `--plan` start Pi in the corresponding read-only mode.
 - The configured cycle shortcut rotates through enabled visible modes. Execute mode is excluded from cycling because it requires an active plan. The default `ctrl+alt+m` does not collide with any built-in Pi keybinding; set `shortcuts.cycleMode` to rebind.
 
-Plans are Markdown files under `.pi/plans/` with the `plan-` filename prefix. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. Loading a plan appends a TUI-only card (via `registerEntryRenderer`) so the plan text never enters the model context; the execute-mode system prompt is the single model-facing copy of the plan. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically at Pi's `agent_before_settle` boundary (added in Pi 0.87.0) — but only when the run settled as `completed`: an aborted (ESC) or errored run keeps execute mode active so the plan can be resumed. On Pi < 0.87.0 this auto-exit is unavailable because the boundary is never emitted; `plan_complete` still exits the mode on any version.
+Plans are Markdown files under `<session directory>/.pi/plans/` with the `plan-` filename prefix - the directory comes from `ExtensionContext.cwd`, captured at `session_start`, so a session opened in one project never reads or writes another project's plans. A plan name must contain at least one letter or digit, so `/plan .` or `/plan --` is rejected instead of producing an untitled `plan-.md`. Loading a plan appends a TUI-only card (via `registerEntryRenderer`) so the plan text never enters the model context; the execute-mode system prompt is the single model-facing copy of the plan, capped at `plan.maxInjectBytes` (default 24 KB), truncating on a line boundary and ending with a marker that names the plan file — the file on disk stays authoritative and is never rewritten. The card stores at most `plan.maxEntryBytes` (default 4 KB) and shows the same marker. `plan_complete` is available in execute mode and in any mode that sets `allowPlanComplete`. On completion, the plan file is deleted when `cleanup.cleanupOnComplete` is enabled. If execution ends without `plan_complete`, execute mode is exited automatically at Pi's `agent_before_settle` boundary (added in Pi 0.87.0) — but only when the run settled as `completed`: an aborted (ESC) or errored run keeps execute mode active so the plan can be resumed. On Pi < 0.87.0 this auto-exit is unavailable because the boundary is never emitted; `plan_complete` still exits the mode on any version.
 
 ## Extension features
 
@@ -35,7 +35,7 @@ A custom mode with no `tools` array inherits **all** tools, including `write` an
 
 `off` behaves the same way: it restores the tools that were active before the mode (never a wider set). Set `modes.off.tools` to pin the resting tool set instead — for example to keep `subagent`/`browser` out of normal mode entirely. Pinning replaces the snapshot taken on mode entry, so a later mode that lists no `tools` inherits the pinned set rather than the older, wider one. `load_tools` is offered in `off` because withheld lazy tools are otherwise unreachable there.
 
-Model overrides are resolved through Pi's model registry when entering a mode. A blank or partial `model` (for example `{ "provider": "", "id": "" }`) is treated as **no override**, so the mode keeps the current model instead of warning `Model not found: /`. The previously active model is captured once per mode and restored on exit; the restore point is persisted in the mode session entry, so `/reload` and `/resume` inside a mode no longer lose it. If the restore target is gone from the registry it is dropped immediately; if it exists but has no credentials (before `/login`, say) the restore is retried once and then released, so a stale point cannot block future captures indefinitely. `Pi.setModel` is session-scoped: it never rewrites your configured `defaultProvider`/`defaultModel`, but it does append a model change to the session transcript, which is why the restore point is persisted alongside the mode. Changes are serialized, so a rapid mode exit cannot leave a superseded mode model active. Note that setting `modes.off.model` makes OFF a pinned baseline: it is applied on every mode exit *and* at session start, overriding `--model` and the configured default. Use Pi theme color tokens for widget label colors.
+Model overrides are resolved through Pi's model registry when entering a mode. A blank or partial `model` (for example `{ "provider": "", "id": "" }`) is treated as **no override**, so the mode keeps the current model instead of warning `Model not found: /`. The previously active model is captured once per mode and restored on exit; the restore point is persisted in the mode session entry, so `/reload` and `/resume` inside a mode no longer lose it. If the restore target is gone from the registry it is dropped immediately; if it exists but has no credentials (before `/login`, say) the restore is retried once and then released, so a stale point cannot block future captures indefinitely. `pi.setModel` is session-scoped: it never rewrites your configured `defaultProvider`/`defaultModel`, but it does append a model change to the session transcript, which is why the restore point is persisted alongside the mode. Changes are serialized, so a rapid mode exit cannot leave a superseded mode model active. Note that setting `modes.off.model` makes OFF a pinned baseline: it is applied on every mode exit *and* at session start, overriding `--model` and the configured default. Use Pi theme color tokens for widget label colors.
 
 Mode state is persisted in session entries and restored on session resume or branch changes. Pi ignores tool names it does not know, so a `tools` list with a typo would silently lose tools: every mode entry checks the list against the registered tools and warns once per unknown name per session. The `mode-switcher` entry type and legacy chat/plan event identifiers are compatibility contracts. On resume, an unknown mode name in a session entry is ignored (falling back to normal), and plan filenames containing path separators or `..` are dropped, so a stale or foreign branch cannot leave the session unrestricted or point plan reads outside `.pi/plans/`.
 
@@ -83,6 +83,8 @@ Create `~/.pi/agent/configs/opl-modes.json` or copy [`configs/opl-modes.json.sam
 | `ui.hideNotify` / `ui.hideWidget` | Suppress mode notifications or widgets. |
 | `shortcuts.cycleMode` | Keybinding for cycling enabled visible modes. |
 | `cleanup.cleanupOnComplete` | Delete the active plan after successful `plan_complete`. |
+| `plan.maxInjectBytes` | Bytes of plan text allowed into the system prompt for execute or refine (default `24000`). The UTF-8 cap includes the marker and retains complete lines. If the source path cannot fit, the marker refers to the plan file; very small budgets use a shortened notice. The file itself is never modified. Configured ceilings must be positive integers; invalid values fall back to defaults. |
+| `plan.maxEntryBytes` | Bytes of plan text stored in the `plan-mode` session entry (default `4096`). The cap includes the marker; the card retains the full file path separately. |
 | `defaultNotifyTemplate` | Notification template for custom modes; `{Name}` is capitalized mode name. |
 | `modes.chat.tools` / `modes.plan.tools` | Replace the respective built-in read-only tool lists. |
 | `chatAllowedTools` / `planAllowedTools` | **Deprecated compatibility aliases** for the built-in tool lists. They are used only when the corresponding `modes.<name>.tools` is omitted; migrate to `modes.chat.tools` or `modes.plan.tools`. |
@@ -113,8 +115,6 @@ Use `modes.<name>.appearance` to keep any mode's visual identity with its defini
 
 `prefix`, `prefixColor`, and `borderColor` style `opl-input`; omitted fields use its compiled mode defaults. `modeColor` styles the value in `opl-footer`'s `mode_switcher` segment; if omitted, the footer uses hardcoded `muted`. Colors accept Pi theme tokens, six-digit hex, or the three-digit `#abc` shorthand (expanded to `#aabbcc`).
 
-Model overrides are resolved through Pi's model registry when entering a mode and the previously active model is restored on exit when applicable. Changes are serialized, so a rapid mode exit cannot leave a superseded mode model active. Use Pi theme color tokens for widget label colors.
-
 ### Lazy tool loading
 
 `lazyTools` withholds heavy tool schemas from the active set until the model actually needs them, keeping the system-prompt prefix (and its prompt-cache write) smaller every session:
@@ -136,6 +136,18 @@ Behavior:
 
 Caching note: activating a lazy tool mid-session preserves the cached prefix on models with native deferred tool loading (Anthropic 4.5+, OpenAI gpt-5.4+) and otherwise triggers one prompt-cache rewrite from that point. It is most effective for tools you use occasionally (delegation, browser automation, benchmarking).
 
+## Cross-extension seams
+
+Extensions install one directory at a time and load in any combination, so `globalThis` is
+the only channel between them. `opl-modes` publishes `__agentMode`, `__planMode` and
+`__chatMode`; `opl-footer` publishes `__footerRequestRender` while a footer is mounted.
+
+Nothing may assume the other side is present or healthy. The render trigger is checked for
+being a function and called inside a `try`: a footer whose TUI was already torn down must not
+fail a mode transition. `session_start` re-publishes the three mode globals and
+`session_shutdown` deletes them, so a later session in the same process never reads a mode
+that belongs to a dead one.
+
 ## Architecture
 
 `config.ts` registers built-in modes, merges configured overrides, compiles Bash patterns, and publishes the registry. `state.ts` persists and restores mode/plan state (including the persisted model restore point) and is the single publisher of `globalThis.__agentMode`. `index.ts` wires commands, picker, lifecycle hooks, tool replacement, Bash interception, and `plan_complete`; `utils.ts` handles plan files, the per-segment Bash gate, and shared helpers.

package/extensions/opl-modes/config.ts

@@ -1,8 +1,8 @@
 /** Config: tool allowlists, bash patterns, prompt templates, plan file constants, user config. */
 
 import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
 import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import type { ModeSwitcherUserConfig, ModeDefinition, PartialModeDefinition, ModeModelConfig } from "./types.js";
 
 // ─── Plan File Constants ────────────────────────────────────────────────────
@@ -150,7 +150,8 @@ After listing all steps, stop and wait for the user to choose:
 Do NOT attempt to make any file changes, run destructive commands, or modify anything.`;
 
 /** System prompt injected when in EXECUTE mode. */
-export function buildExecutePrompt(planContent: string): string {
+export function buildExecutePrompt(planContent: string, source?: string): string {
+  const capped = capPlan(planContent, USER_CONFIG.plan.maxInjectBytes, source);
   return `\
 You are in EXECUTE MODE. Execute the plan below step by step.
 
@@ -159,16 +160,17 @@ After completing ALL steps, call plan_complete() to signal that execution is fin
 If the \`todo\` tool is available, use it to track progress: add all plan steps at the start of execution, then toggle each one done as you complete it.
 
 Plan:
-${planContent}`;
+${capped.text}`;
 }
 
 /** System prompt injected when refining a plan in PLAN mode. */
-export function buildRefinePrompt(planContent: string): string {
+export function buildRefinePrompt(planContent: string, source?: string): string {
+  const capped = capPlan(planContent, USER_CONFIG.plan.maxInjectBytes, source);
   return `\
 You are in PLAN MODE (refining). The user wants to revise the current plan based on their feedback.
 
 Current plan:
-${planContent}
+${capped.text}
 
 Each step MUST be self-contained — write it as if the executor has no memory of this conversation. Include enough context that it can be carried out with only the plan file and the codebase. Assume the executor will read the relevant files fresh — do not rely on findings you discovered during planning.
 
@@ -196,6 +198,10 @@ const DEFAULT_CONFIG = {
     HIDE_NOTIFY: false,
     HIDE_WIDGET: true,
   },
+  PLAN: {
+    MAX_INJECT_BYTES: 24000,
+    MAX_ENTRY_BYTES: 4096,
+  },
   SHORTCUTS: {
     CYCLE_MODE: "ctrl+alt+m",
   },
@@ -230,15 +236,18 @@ const DEFAULT_CONFIG = {
   },
 };
 
-const CONFIG_PATH = join(homedir(), ".pi", "agent", "configs", "opl-modes.json");
+/** Resolved per call so a custom `PI_AGENT_DIR` (pi's own agent dir) is honoured. */
+export function configPath(): string {
+  return join(getAgentDir(), "configs", "opl-modes.json");
+}
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-export function loadUserConfig(path = CONFIG_PATH): ModeSwitcherUserConfig {
+export function loadUserConfig(file = configPath()): ModeSwitcherUserConfig {
   try {
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const parsed = JSON.parse(readFileSync(file, "utf8"));
     return isRecord(parsed) ? parsed as ModeSwitcherUserConfig : {};
   } catch {
     return {};
@@ -335,10 +344,55 @@ export function lazyToolsToEnable(
   return want.filter((n) => lazy.has(n) && (!allowed || allowed.has(n)) && !active.has(n));
 }
 
+/** Positive integer from user config, else the default. Anything else is ignored rather than trusted. */
+function positiveInt(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : fallback;
+}
+
+export interface CappedPlan {
+  text: string;
+  truncated: boolean;
+  omittedBytes: number;
+}
+
+/**
+ * Bound a plan body before it is injected into a prompt or stored as an entry.
+ * A plan file is user-authored and uncapped: injected whole it is re-sent on
+ * every provider request for the run, and stored whole it lives in the session
+ * file forever. Truncation is announced so the reader can open the file.
+ */
+export function capPlan(plan: string, maxBytes: number, source?: string): CappedPlan {
+  const bytes = Buffer.byteLength(plan, "utf8");
+  if (!Number.isFinite(maxBytes) || maxBytes <= 0 || bytes <= maxBytes) {
+    return { text: plan, truncated: false, omittedBytes: 0 };
+  }
+  const budget = Math.floor(maxBytes);
+  const marker = (shown: number, location: string) =>
+    `\n\n[… plan truncated: showing ${shown} of ${bytes} bytes, ${bytes - shown} omitted - read ${location} for the rest …]`;
+  // Reserve the widest possible counts, including a UTF-8 source path.
+  const reserve = (location: string) => Buffer.byteLength(marker(0, location), "utf8") + String(bytes).length - 1;
+  let location = source ?? "the plan file";
+  if (reserve(location) > budget) location = "the plan file";
+  if (reserve(location) > budget) {
+    return { text: "[plan truncated]".slice(0, budget), truncated: true, omittedBytes: bytes };
+  }
+  const buffer = Buffer.from(plan, "utf8");
+  const limit = budget - reserve(location);
+  const newline = buffer.lastIndexOf(10, limit);
+  // Keep only complete lines. A single line that exceeds the budget stays in the file.
+  const head = newline < 0 ? "" : buffer.subarray(0, newline).toString("utf8");
+  const shown = Buffer.byteLength(head, "utf8");
+  return { text: head + marker(shown, location), truncated: true, omittedBytes: bytes - shown };
+}
+
 export const USER_CONFIG = {
   cleanup: {
     cleanupOnComplete: userConfig.cleanup?.cleanupOnComplete ?? DEFAULT_CONFIG.CLEANUP.CLEANUP_ON_COMPLETE,
   },
+  plan: {
+    maxInjectBytes: positiveInt(userConfig.plan?.maxInjectBytes, DEFAULT_CONFIG.PLAN.MAX_INJECT_BYTES),
+    maxEntryBytes: positiveInt(userConfig.plan?.maxEntryBytes, DEFAULT_CONFIG.PLAN.MAX_ENTRY_BYTES),
+  },
   ui: {
     hideNotify: userConfig.ui?.hideNotify ?? DEFAULT_CONFIG.UI.HIDE_NOTIFY,
     hideWidget: userConfig.ui?.hideWidget ?? DEFAULT_CONFIG.UI.HIDE_WIDGET,