@vanillagreen/pi-qol 1.2.0 → 1.4.0

package/README.md

@@ -5,7 +5,21 @@
 ![Session search popup](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/session-search.gif)
 ![/context usage breakdown](https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-qol/assets/context-usage.png)
 
-Quality-of-life extension for Pi.
+Quality-of-life extension for Pi: compact statusline, multiline input, session naming and search, notifications, and a permission gate.
+
+## Highlights
+
+- Compact statusline with repo, branch, model, thinking level, and context percent.
+- Shift+Enter inserts a newline. Ctrl+J fallback for terminals that can't distinguish it.
+- Sessions auto-name from your first prompt. `/rename` overrides anytime.
+- `/search` browses previous sessions with snippet previews. F2 opens it instantly.
+- `/context` shows a Claude-style context-window breakdown.
+- `/handoff <goal>` drafts a focused prompt for a new session.
+- Permission gate prompts before risky `bash` commands. Default match: `rm -Rf`.
+- Notifications for ready, questions, blocked states, and task completion.
+- Thinking timer next to collapsed `Thinking...` labels.
+- Caveman badge and Alt+C mode cycling when `pi-caveman` is loaded.
+- Subagent-name badge in `pi-agents-tmux` child panes.
 
 ## Install
 
@@ -24,107 +38,137 @@ vstack add vanillagreencom/vstack --pi-extension pi-qol --harness pi -y
 
 Restart Pi after installation.
 
-## What it provides
-
-- Compact statusline and `π` prompt editor: shows repo/project, branch/dirty state, model, colorized thinking level, optional Caveman badge, context window size, remaining context percent, and (inside `pi-agents-tmux` child panes) an ANSI-background subagent-name badge while replacing Pi's default footer/editor chrome.
-- Reliable multiline input: `Shift+Enter` / `Shift+Return` inserts a newline when the terminal reports it distinctly; `ctrl+j` is the default fallback newline key. `Alt+Enter` is reserved for Pi follow-up messages. QOL can also style Pi's built-in steering/follow-up pending queue preview with an ANSI green left bar while leaving the restore hint muted. When `pi-caveman` is loaded, `Alt+C` cycles Caveman modes.
-- Compact image placeholders: existing pasted image paths can collapse to `[Image #N]` aliases and are attached on submit.
-- Session naming: `/rename [name]` sets or shows the friendly session name; automatic first-prompt naming is enabled by default.
-- Context usage: `/context` prints an inline Claude-style context-window visualization with estimated Pi/model category breakdowns.
-- Previous-session search: `/search` and optional `F2` overlay search prior sessions, preview snippets, resume, inject summarized context, or start a new session with summarized context.
-- Handoff: `/handoff <goal>` drafts a focused prompt for a new session, preserving the latest compaction summary plus retained branch entries.
-- Optional permission gate: when enabled, prompts before configured `bash` tool command fragments run; default match is `rm -Rf`.
-- Notifications: terminal/tmux/native notifications for ready-for-input, questions, direction needed, task completion, and critical/blocked states.
-- Optional custom compaction and idle compaction; disabled by default so Pi's compaction behavior is unchanged until enabled.
-- Thinking timer next to collapsed `Thinking...` labels; enabled by default and falls back to Pi defaults if internals change.
-
 ## Commands
 
 | Command | Action |
 | --- | --- |
-| `/qol` | Open the extension-manager settings popup (falls back to inline status when the manager is not installed). |
+| `/qol` | Open settings (or print status if extension-manager isn't installed). |
 | `/qol notify-test` | Send a test notification. |
-| `/qol:rename` | Regenerate the current session name from the first user prompt. |
-| `/qol:rename:full` | Regenerate the session name from the full conversation. |
-| `/rename [name]` | Set or show the current session's friendly name. |
-| `/context` | Show inline context-window usage, model/context limit, and estimated category breakdowns. |
-| `/search [query]` | Open previous-session search, optionally prefilled with a query. |
+| `/rename [name]` | Set or show the current session's name. |
+| `/qol:rename` | Regenerate the session name from the first prompt. |
+| `/qol:rename:full` | Regenerate from the full conversation. |
+| `/context` | Show context-window usage with category breakdown. |
+| `/search [query]` | Open previous-session search. |
 | `/search:refresh` | Refresh the session search cache. |
-| `/handoff <goal>` | Draft a focused handoff prompt for a new session. |
+| `/handoff <goal>` | Draft a handoff prompt for a new session. |
 
-`/qol` and `/search` arguments support autocomplete.
+Arguments support autocomplete.
 
 ## Settings
 
-Settings are exposed through `pi-extension-manager` under **QOL**.
+All settings live in the extension manager under **QOL**. Names below match the labels shown there.
 
-### Statusline and prompt
+### Statusline
 
-- `replaceFooter`: hide Pi's default footer while QOL's compact statusline is active; default on.
-- `compactPrompt`: use the compact `π` prompt editor; default on.
-- `showSessionNameTitle`: show the named session above the prompt, or in tmux's pane title/border; default on.
-- `showSessionNameWindow`: also rename the current tmux window to `π <session>` so it appears in the tmux status line. Disables `automatic-rename` for the window while active and restores it on shutdown. Requires `showSessionNameTitle`; default on.
-- `inputBottomPaddingLines`: blank lines below the compact prompt; default `0`.
-- Git display knobs: `gitRefreshTimeoutMs`, `showDirtyMarker`.
-- If `pi-caveman` is loaded, QOL reads its bridge to show a Caveman icon in the statusline and to make `Alt+C` cycle Caveman modes. The Caveman package's `showStatusBadge` setting also controls this QOL badge.
-- If `pi-agents-tmux` is loaded inside a child pane, QOL reads its bridge/env metadata to show a trailing subagent-name badge after the context percent. The badge uses the agent `color:` frontmatter (`red`, `green`, `yellow`, `blue`, `magenta`, `cyan`; aliases `orange`, `purple`/`violet`, `teal`) or falls back to automatic color cycling.
+| Setting | What it does |
+| --- | --- |
+| Enable QOL editor helpers | Master toggle for QOL statusline, commands, notifications, search, compaction, and editor helpers. |
+| Replace built-in footer | Hide Pi's default footer while the QOL statusline is active. |
+| Use π prompt editor | Use the compact prompt editor. |
+| Show session name title | Show the session name above the prompt and in the tmux pane title. |
+| Sync session name to tmux window name | Rename the tmux window to `π <session>`. |
+| Input bottom padding | Blank lines below the prompt. |
+| Show dirty marker | Append `*` to the branch when the worktree is dirty. |
 
 ### Input
 
-- `newlineOnShiftEnter`: intercept distinguishable `Shift+Enter` / `Shift+Return` and insert a newline; default on.
-- `newlineFallbackKey`: alternate newline key for terminals that cannot distinguish shifted enter; default `ctrl+j`, or `none` to disable.
-- `pendingQueue.asciiGreen`: style Pi's built-in steering/follow-up pending queue preview with an ANSI green heavy left bar while keeping the Alt+Up restore hint in the theme hint color with a two-space indent; default on.
+| Setting | What it does |
+| --- | --- |
+| Shift+Enter inserts newline | Insert a newline instead of submitting on Shift+Enter. |
+| Fallback newline key | Alternate newline key for terminals that can't send Shift+Enter. |
+| Style pending queue preview | Highlight Pi's pending-queue preview with a green left bar. |
+| Style image chips | Render `[Image #N]` placeholders as distinct chips. |
+| Show attachment count | Show a status badge when the draft has image placeholders. |
 
-### Session auto-rename
+### Session naming
 
-- `sessionAutoRename.enabled`: automatically name unnamed sessions after the first prompt/agent turn; default on.
-- `sessionAutoRename.model`: naming model (`provider/model`, `current`, or `cheapest`); default `openai-codex/gpt-5.4-mini`.
-- `sessionAutoRename.fallbackModel`: fallback model; default `current`, or `none`/`off` to skip.
-- `sessionAutoRename.fallback`: deterministic fallback when model naming fails: `words`, `truncate`, or `none`.
-- Advanced knobs: `prefix`, `maxInputChars`, `maxNameChars`, `maxTokens`, `timeoutMs`, `prompt`, `notify`, and `debug`.
+| Setting | What it does |
+| --- | --- |
+| Enable /rename command | Register the `/rename` command. |
+| Auto-name new sessions | Generate a friendly session name from the first prompt. |
+| Auto-rename model | Model used for title generation. |
+| Auto-rename fallback model | Model tried when the primary fails. |
+| Deterministic fallback | Title-case words, truncated prompt, or none if all model calls fail. |
+| Auto-rename prefix | Optional static prefix on every generated name. |
+| Notify on auto-rename | Show a notification when auto-renaming. |
 
-### Session search
+Advanced: input cap, title length, output tokens, timeout, custom prompt template, and debug logging.
 
-- `sessionSearch.enabled`: register `/search` and the overlay.
-- `sessionSearch.shortcutKey`: shortcut to open search; default `f2`, set `none` to disable.
-- Search ordering: empty search shows prompts by recency; typed search sorts by match quality, then prompt recency.
-- Result/layout knobs: `resultLimit`, `maxVisible`, `messageMaxVisible`, `previewSnippets`, `overlayWidth`, `cacheTtlSeconds`.
-- Summary knobs: `summaryModel`, `summaryMaxTokens`, `summaryInputMaxChars`.
+### Handoff
 
-Search rows use Pi's `/resume`-style title: explicit session name, otherwise first user prompt, otherwise filename. The session cache is warmed on session start/first use and, by default, kept until `/search:refresh`; set `cacheTtlSeconds` above `0` if you want automatic time-based refreshes.
+| Setting | What it does |
+| --- | --- |
+| Enable /handoff command | Register the `/handoff` command. |
+| Review handoff prompt | Open an editor to edit the generated prompt before creating the session. |
+
+### Context window
+
+| Setting | What it does |
+| --- | --- |
+| Enable /context command | Register `/context`. |
 
-### Context usage
+### Session search
 
-- `enableContextCommand`: register `/context`; default on. The display uses Pi's `ctx.getContextUsage()` for total tokens/context window, then estimates the category split from the current system prompt, active tool definitions, session messages, compact summaries, context files, skills, and custom agents when Pi exposes that structured data.
+| Setting | What it does |
+| --- | --- |
+| Enable session search | Register `/search` and the overlay. |
+| Session search shortcut | Shortcut to open search. Default `f2`; set to `none` to disable. |
+| Result limit | Max matching prompts returned. |
+| Visible session rows | Rows shown before scrolling. |
+| Preview snippets | Matching snippets shown on the preview screen. |
+| Session cache TTL | Seconds before the session list refreshes; `0` keeps it until you run `/search:refresh`. |
+
+Summary settings (model, max tokens, input cap) tune the summarizer when you import context from a previous session.
 
 ### Notifications
 
-- Master and trigger toggles: `notification.enabled`, `onAgentReady`, `onDirectionNeeded`, `onQuestion`, `onTaskComplete`, `onCritical`.
-- Channels: BEL, native terminal notifications, tmux client TTY writes, tmux messages, optional tmux window marking, and Pi UI notifications.
-- `notification.oscProtocol`: `auto`, `osc777`, `osc99`, or `off`; `auto` uses Kitty OSC 99 when available, otherwise OSC 777.
-- Tuning: `cooldownSeconds`, `title`, `readyMessage`, `bodyMaxChars`, `tmuxMessageDurationMs`, and tmux mark text/duration.
+Master toggle: **Enable notifications**.
+
+Triggers (notify when): ready, direction needed, question popups, all tasks complete, critical/blocked.
+
+Channels: terminal bell, native terminal notifications (OSC 777/99 or Windows toast), tmux `display-message`, tmux window marking, OSC passthrough, and an optional in-Pi UI notice.
+
+Tuning: cooldown seconds, title, ready message, body length, tmux durations.
+
+Notes:
+
+- **Terminal notification protocol** picks between OSC 99 (Kitty) and OSC 777 automatically.
+- **Bell when tmux window active** is off so you don't get bells while looking at Pi.
+- **tmux native via client TTY** sends OSC notifications to attached tmux clients so notifications still appear when the Pi window is inactive.
 
-Use `/qol notify-test` to verify your terminal/tmux notification path.
+Use `/qol notify-test` to verify your terminal/tmux setup.
 
 ### Permission gate
 
-- `permissionGate.enabled`: ask before matching `bash` tool calls; default off. When enabled, non-interactive matches are blocked.
-- `permissionGate.commands`: comma-separated literal fragments or `/pattern/flags` regexes; default `rm -Rf`.
-- `permissionGate.previewLines` / `permissionGate.previewChars`: cap the approval prompt preview; long commands show a compact head/tail preview while the full command still runs only if approved.
+| Setting | What it does |
+| --- | --- |
+| Prompt before risky bash commands | Ask before bash commands matching the command list. |
+| Commands to prompt for | Comma-separated literal fragments or `/regex/flags`. |
+| Approval preview lines | Cap the approval-prompt preview height. |
+| Approval preview characters | Cap the approval-prompt preview width. |
 
-### Compaction
+Off by default. When enabled, non-interactive matches are blocked.
 
-- `compaction.customEnabled`: use QOL custom summaries for Pi compaction events; default off.
-- `compaction.model`: summarizer model; default `google/gemini-2.5-flash`.
-- `compaction.profile`: `concise`, `balanced`, or `exhaustive`.
-- `compaction.remoteEnabled` / `compaction.remoteEndpoint`: call a remote summarizer with `{ systemPrompt, prompt, maxTokens }` and expect `{ summary }`.
-- `compaction.branchSummaryEnabled`: use the same summarizer for requested `/tree` branch summaries.
-- `compaction.idleEnabled` and related thresholds: extension-managed idle compaction trigger.
+### Compaction
 
-### Thinking timer
+| Setting | What it does |
+| --- | --- |
+| Custom compaction summaries | Use QOL summaries instead of Pi's default. |
+| Compaction model | Summarizer model. |
+| Compaction detail profile | `concise`, `balanced`, or `exhaustive`. |
+| Include previous summary | Pass the previous summary for iterative continuity. |
+| Fallback to Pi default compaction | Run Pi's default compaction if QOL's fails. |
+| Show compaction notifications | Notify on compaction start/fail/complete. |
+| Custom branch summaries | Use the QOL summarizer for `/tree` branch summaries. |
+| Remote compaction endpoint | Call a remote HTTP summarizer instead of a model. |
+| Idle compaction trigger | Auto-compact after the session sits idle above a token threshold. |
 
-- `thinkingTimer.enabled`: show elapsed time next to collapsed `Thinking...` labels when the model emits thinking blocks.
+Idle thresholds (token threshold, idle delay, fixed token limit, percent limit) tune when idle compaction fires.
 
-## Notes
+### Thinking
 
-Pi owns native pending image attachment state and does not expose it to extensions. QOL can attach image paths it collapses itself; native Pi paste/drag attachments remain Pi-owned.
+| Setting | What it does |
+| --- | --- |
+| Hidden thinking label | Label shown when thinking blocks are hidden. |
+| Show thinking timer | Show elapsed time next to collapsed `Thinking...` labels. |
+| Working indicator mode | `animated` ticks every 80ms; switch to `static` if you see flashes when the chat overflows. |

package/extensions/qol/agent-end.ts

@@ -0,0 +1,48 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+export function textFromContent(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	return content
+		.map((part) => {
+			if (typeof part === "string") return part;
+			if (part && typeof part === "object" && (part as any).type === "text" && typeof (part as any).text === "string") return (part as any).text;
+			return "";
+		})
+		.filter(Boolean)
+		.join("\n");
+}
+
+export function lastAssistantTextFromAgentEnd(event: any, ctx: ExtensionContext): string {
+	const eventMessages = Array.isArray(event?.messages) ? event.messages : [];
+	for (let index = eventMessages.length - 1; index >= 0; index -= 1) {
+		const message = eventMessages[index];
+		if (message?.role === "assistant") return textFromContent(message.content);
+	}
+	const branch = ctx.sessionManager.getBranch?.() ?? [];
+	for (let index = branch.length - 1; index >= 0; index -= 1) {
+		const entry = branch[index] as any;
+		if (entry?.type === "message" && entry.message?.role === "assistant") return textFromContent(entry.message.content);
+	}
+	return "";
+}
+
+export function needsDirection(text: string): boolean {
+	return /\?\s*$|\b(let me know|tell me|which (one|option)|choose|confirm|approve|should i|would you like|do you want|need your input|awaiting|next step)\b/i.test(text);
+}
+
+export function criticalInfo(text: string): string | undefined {
+	const match = text.match(/\b(critical|urgent|warning|blocked|cannot proceed|security|vulnerab|secret|credential|rate limit|context (overflow|full)|manual action required)\b/i);
+	if (!match) return undefined;
+	const line = text.split(/\r?\n/).find((candidate) => candidate.toLowerCase().includes(match[0].toLowerCase())) ?? text;
+	return line.trim();
+}
+
+export function taskStats(state: any): { completed: number; remaining: number; total: number } | undefined {
+	const tasks = Array.isArray(state?.tasks) ? state.tasks : undefined;
+	if (!tasks) return undefined;
+	const total = tasks.length;
+	const completed = tasks.filter((task: any) => task?.status === "completed").length;
+	const remaining = tasks.filter((task: any) => task?.status === "pending" || task?.status === "in_progress").length;
+	return { completed, remaining, total };
+}

package/extensions/qol/agent-statusline.ts

@@ -0,0 +1,52 @@
+import { truncateToWidth } from "@earendil-works/pi-tui";
+import { readPiAgentsStatuslineBridge } from "./bridges.js";
+
+type AgentAsciiColor = "red" | "green" | "yellow" | "blue" | "magenta" | "cyan";
+
+const AGENT_ASCII_COLOR_SEQUENCE: AgentAsciiColor[] = ["magenta", "green", "blue", "cyan", "yellow", "red"];
+const AGENT_ASCII_BG: Record<AgentAsciiColor, number> = {
+	red: 41,
+	green: 42,
+	yellow: 43,
+	blue: 44,
+	magenta: 45,
+	cyan: 46,
+};
+
+function normalizeAgentAsciiColor(value: string | undefined): AgentAsciiColor | undefined {
+	const normalized = value?.trim().toLowerCase().replace(/[^a-z]/g, "");
+	switch (normalized) {
+		case "red": return "red";
+		case "green": return "green";
+		case "yellow":
+		case "orange": return "yellow";
+		case "blue": return "blue";
+		case "magenta":
+		case "purple":
+		case "violet": return "magenta";
+		case "cyan":
+		case "teal": return "cyan";
+		default: return undefined;
+	}
+}
+
+function fallbackAgentAsciiColor(name: string): AgentAsciiColor {
+	let hash = 0;
+	for (const char of name) hash = ((hash * 31) + char.charCodeAt(0)) >>> 0;
+	return AGENT_ASCII_COLOR_SEQUENCE[hash % AGENT_ASCII_COLOR_SEQUENCE.length] ?? "magenta";
+}
+
+function ansiAgentBg(color: AgentAsciiColor, text: string): string {
+	return `\x1b[30;${AGENT_ASCII_BG[color]}m${text}\x1b[39;49m`;
+}
+
+export function subagentStatuslineMarker(cwd: string, maxInnerWidth = 24): { plain: string; styled: string } | undefined {
+	const bridgeInfo = readPiAgentsStatuslineBridge()?.getCurrentSubagent(cwd);
+	const envName = process.env.PI_SUBAGENT_CHILD_AGENT?.trim();
+	const rawName = bridgeInfo?.name?.trim() || envName;
+	if (!rawName) return undefined;
+	const color = normalizeAgentAsciiColor(bridgeInfo?.color) ?? normalizeAgentAsciiColor(process.env.PI_SUBAGENT_CHILD_COLOR) ?? fallbackAgentAsciiColor(rawName);
+	const inner = truncateToWidth(rawName, Math.max(1, maxInnerWidth), "…");
+	const plain = ` ${inner} `;
+	return { plain, styled: ansiAgentBg(color, plain) };
+}

package/extensions/qol/ansi.ts

@@ -0,0 +1,115 @@
+const ANSI_PATTERN = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\))/g;
+
+export const ANSI_ESCAPE_RE = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+export const ANSI_GREEN_FG = "\x1b[32m";
+export const ANSI_RED_FG = "\x1b[31m";
+export const ANSI_YELLOW_FG = "\x1b[33m";
+export const ANSI_FG_RESET = "\x1b[39m";
+
+export function stripAnsi(text: string): string {
+	return text.replace(ANSI_PATTERN, "");
+}
+
+export function ansiGreen(text: string): string {
+	return `${ANSI_GREEN_FG}${text}${ANSI_FG_RESET}`;
+}
+
+export function ansiRed(text: string): string {
+	return `${ANSI_RED_FG}${text}${ANSI_FG_RESET}`;
+}
+
+export function ansiYellow(text: string): string {
+	return `${ANSI_YELLOW_FG}${text}${ANSI_FG_RESET}`;
+}
+
+export function oneLine(text: string): string {
+	return text
+		.replace(ANSI_ESCAPE_RE, "")
+		.replace(/[\r\n\t]+/g, " ")
+		.replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, " ")
+		.replace(/\s+/g, " ")
+		.trim();
+}
+
+export interface VisibleMap {
+	text: string;
+	rawIndexByVisibleIndex: number[];
+}
+
+export interface VisibleReplacement {
+	start: number;
+	end: number;
+	text: string;
+}
+
+export function ansiSequenceEnd(input: string, start: number): number {
+	const introducer = input[start + 1];
+	if (introducer == null) return start + 1;
+
+	// OSC, DCS, APC, PM, SOS strings are zero-width and end in ST (ESC \\).
+	// OSC may also end in BEL.
+	if (introducer === "]" || introducer === "P" || introducer === "_" || introducer === "^" || introducer === "X") {
+		const st = input.indexOf("\x1b\\", start + 2);
+		const bell = introducer === "]" ? input.indexOf("\x07", start + 2) : -1;
+		if (bell >= 0 && (st < 0 || bell < st)) return bell + 1;
+		return st >= 0 ? st + 2 : input.length;
+	}
+
+	if (introducer === "[") {
+		let index = start + 2;
+		while (index < input.length) {
+			const code = input.charCodeAt(index);
+			if (code >= 0x40 && code <= 0x7e) return index + 1;
+			index += 1;
+		}
+		return input.length;
+	}
+
+	return Math.min(start + 2, input.length);
+}
+
+export function buildVisibleMap(input: string): VisibleMap {
+	const rawIndexByVisibleIndex: number[] = [0];
+	let text = "";
+	let index = 0;
+
+	while (index < input.length) {
+		if (input.charCodeAt(index) === 0x1b) {
+			index = ansiSequenceEnd(input, index);
+			continue;
+		}
+
+		if (rawIndexByVisibleIndex[text.length] === undefined) rawIndexByVisibleIndex[text.length] = index;
+		text += input[index] ?? "";
+		index += 1;
+		rawIndexByVisibleIndex[text.length] = index;
+	}
+
+	if (rawIndexByVisibleIndex[text.length] === undefined) rawIndexByVisibleIndex[text.length] = index;
+	return { rawIndexByVisibleIndex, text };
+}
+
+export function applyVisibleReplacements(input: string, map: VisibleMap, replacements: VisibleReplacement[]): string {
+	if (replacements.length === 0) return input;
+
+	const sorted = replacements
+		.filter((replacement) => replacement.end > replacement.start)
+		.sort((a, b) => a.start - b.start || b.end - a.end);
+
+	let output = "";
+	let lastRawIndex = 0;
+	let lastVisibleIndex = 0;
+
+	for (const replacement of sorted) {
+		if (replacement.start < lastVisibleIndex) continue;
+		const rawStart = map.rawIndexByVisibleIndex[replacement.start];
+		const rawEnd = map.rawIndexByVisibleIndex[replacement.end];
+		if (rawStart == null || rawEnd == null || rawStart < lastRawIndex) continue;
+
+		output += input.slice(lastRawIndex, rawStart) + replacement.text;
+		lastRawIndex = rawEnd;
+		lastVisibleIndex = replacement.end;
+	}
+
+	return output + input.slice(lastRawIndex);
+}

package/extensions/qol/bridges.ts

@@ -0,0 +1,78 @@
+import {
+	CAVEMAN_BRIDGE_SYMBOL,
+	PI_AGENTS_STATUSLINE_SYMBOL,
+	QUESTION_SERVICE_SYMBOL,
+	VSTACK_MODAL_LOCK_SYMBOL,
+} from "./constants.js";
+
+export interface CavemanBridge {
+	isActive(): boolean;
+	getMode(): string;
+	getConfiguredMode?(cwd?: string): string;
+	getLastActiveMode(): string;
+	hasSessionOverride?(): boolean;
+	isStatusBadgeEnabled?(cwd?: string): boolean;
+	cycleMode?(cwd?: string): string;
+	setMode?(mode: string, cwd?: string): string | undefined;
+	subscribe(listener: () => void): () => void;
+}
+
+export interface PiAgentsStatuslineBridge {
+	getCurrentSubagent(cwd?: string): { name: string; color?: string } | undefined;
+}
+
+export interface QuestionRequestLike {
+	header?: string;
+	question?: string;
+}
+
+export interface QuestionOpenedEventLike {
+	requestId?: string;
+	request?: QuestionRequestLike;
+	source?: string;
+}
+
+export interface QuestionServiceLike {
+	listPending(): unknown[];
+	subscribe(listener: (event: any) => void): () => void;
+}
+
+interface VstackModalLock {
+	depth: number;
+}
+
+export function readCavemanBridge(): CavemanBridge | undefined {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const value = host[CAVEMAN_BRIDGE_SYMBOL];
+	return value && typeof value === "object" ? (value as CavemanBridge) : undefined;
+}
+
+export function readPiAgentsStatuslineBridge(): PiAgentsStatuslineBridge | undefined {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const value = host[PI_AGENTS_STATUSLINE_SYMBOL];
+	return value && typeof value === "object" && typeof (value as PiAgentsStatuslineBridge).getCurrentSubagent === "function"
+		? (value as PiAgentsStatuslineBridge)
+		: undefined;
+}
+
+export function getQuestionService(): QuestionServiceLike | undefined {
+	const service = (globalThis as unknown as Record<PropertyKey, unknown>)[QUESTION_SERVICE_SYMBOL];
+	if (!service || typeof service !== "object") return undefined;
+	const candidate = service as Partial<QuestionServiceLike>;
+	if (typeof candidate.subscribe === "function" && typeof candidate.listPending === "function") return candidate as QuestionServiceLike;
+	return undefined;
+}
+
+export function acquireVstackModalLock(): () => void {
+	const host = globalThis as unknown as Record<PropertyKey, unknown>;
+	const existing = host[VSTACK_MODAL_LOCK_SYMBOL] as VstackModalLock | undefined;
+	const lock = existing && typeof existing.depth === "number" ? existing : { depth: 0 };
+	host[VSTACK_MODAL_LOCK_SYMBOL] = lock;
+	lock.depth += 1;
+	let released = false;
+	return () => {
+		if (released) return;
+		released = true;
+		lock.depth = Math.max(0, lock.depth - 1);
+	};
+}