pi-interactive-shell 0.4.8 → 0.4.9

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.9] - 2026-01-21
+
+### Fixed
+- **Multi-line command overflow in header** - Commands containing newlines (e.g., long prompts passed via `-f` flag) now properly collapse to a single line in the overlay header instead of overflowing and leaking behind the overlay.
+- **Reason field overflow** - The `reason` field in the hint line is also sanitized to prevent newline overflow.
+- **Session list overflow** - The `/attach` command's session list now sanitizes command and reason fields for proper display.
+
 ## [0.4.8] - 2026-01-19
 
 ### Changed

package/index.ts

@@ -573,8 +573,11 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				const options = sessions.map((s) => {
 					const status = s.session.exited ? "exited" : "running";
 					const duration = formatDuration(Date.now() - s.startedAt.getTime());
-					const reason = s.reason ? ` • ${s.reason}` : "";
-					return `${s.id} - ${s.command}${reason} (${status}, ${duration})`;
+					// Sanitize command and reason: collapse newlines and whitespace for display
+					const sanitizedCommand = s.command.replace(/\s+/g, " ").trim();
+					const sanitizedReason = s.reason?.replace(/\s+/g, " ").trim();
+					const reason = sanitizedReason ? ` • ${sanitizedReason}` : "";
+					return `${s.id} - ${sanitizedCommand}${reason} (${status}, ${duration})`;
 				});
 
 				const choice = await ctx.ui.select("Background Sessions", options);

package/key-encoding.ts

@@ -0,0 +1,270 @@
+/**
+ * Terminal key encoding utilities for translating named keys and modifiers
+ * into terminal escape sequences.
+ */
+
+// Named key sequences (without modifiers)
+const NAMED_KEYS: Record<string, string> = {
+	// Arrow keys
+	up: "\x1b[A",
+	down: "\x1b[B",
+	left: "\x1b[D",
+	right: "\x1b[C",
+
+	// Common keys
+	enter: "\r",
+	return: "\r",
+	escape: "\x1b",
+	esc: "\x1b",
+	tab: "\t",
+	space: " ",
+	backspace: "\x7f",
+	bspace: "\x7f", // tmux-style alias
+
+	// Editing keys
+	delete: "\x1b[3~",
+	del: "\x1b[3~",
+	dc: "\x1b[3~", // tmux-style alias
+	insert: "\x1b[2~",
+	ic: "\x1b[2~", // tmux-style alias
+
+	// Navigation
+	home: "\x1b[H",
+	end: "\x1b[F",
+	pageup: "\x1b[5~",
+	pgup: "\x1b[5~",
+	ppage: "\x1b[5~", // tmux-style alias
+	pagedown: "\x1b[6~",
+	pgdn: "\x1b[6~",
+	npage: "\x1b[6~", // tmux-style alias
+
+	// Shift+Tab (backtab)
+	btab: "\x1b[Z",
+
+	// Function keys
+	f1: "\x1bOP",
+	f2: "\x1bOQ",
+	f3: "\x1bOR",
+	f4: "\x1bOS",
+	f5: "\x1b[15~",
+	f6: "\x1b[17~",
+	f7: "\x1b[18~",
+	f8: "\x1b[19~",
+	f9: "\x1b[20~",
+	f10: "\x1b[21~",
+	f11: "\x1b[23~",
+	f12: "\x1b[24~",
+
+	// Keypad keys (application mode)
+	kp0: "\x1bOp",
+	kp1: "\x1bOq",
+	kp2: "\x1bOr",
+	kp3: "\x1bOs",
+	kp4: "\x1bOt",
+	kp5: "\x1bOu",
+	kp6: "\x1bOv",
+	kp7: "\x1bOw",
+	kp8: "\x1bOx",
+	kp9: "\x1bOy",
+	"kp/": "\x1bOo",
+	"kp*": "\x1bOj",
+	"kp-": "\x1bOm",
+	"kp+": "\x1bOk",
+	"kp.": "\x1bOn",
+	kpenter: "\x1bOM",
+};
+
+// Ctrl+key combinations (ctrl+a through ctrl+z, plus some special)
+const CTRL_KEYS: Record<string, string> = {};
+for (let i = 0; i < 26; i++) {
+	const char = String.fromCharCode(97 + i); // a-z
+	CTRL_KEYS[`ctrl+${char}`] = String.fromCharCode(i + 1);
+}
+// Special ctrl combinations
+CTRL_KEYS["ctrl+["] = "\x1b"; // Same as Escape
+CTRL_KEYS["ctrl+\\"] = "\x1c";
+CTRL_KEYS["ctrl+]"] = "\x1d";
+CTRL_KEYS["ctrl+^"] = "\x1e";
+CTRL_KEYS["ctrl+_"] = "\x1f";
+CTRL_KEYS["ctrl+?"] = "\x7f"; // Same as Backspace
+
+// Alt+key sends ESC followed by the key
+function altKey(char: string): string {
+	return `\x1b${char}`;
+}
+
+// Keys that support xterm modifier encoding (CSI sequences)
+const MODIFIABLE_KEYS = new Set([
+	"up", "down", "left", "right", "home", "end",
+	"pageup", "pgup", "ppage", "pagedown", "pgdn", "npage",
+	"insert", "ic", "delete", "del", "dc",
+]);
+
+// Calculate xterm modifier code: 1 + (shift?1:0) + (alt?2:0) + (ctrl?4:0)
+function xtermModifier(shift: boolean, alt: boolean, ctrl: boolean): number {
+	let mod = 1;
+	if (shift) mod += 1;
+	if (alt) mod += 2;
+	if (ctrl) mod += 4;
+	return mod;
+}
+
+// Apply xterm modifier to CSI sequence: ESC[A -> ESC[1;modA
+function applyXtermModifier(sequence: string, modifier: number): string | null {
+	// Arrow keys: ESC[A -> ESC[1;modA
+	const arrowMatch = sequence.match(/^\x1b\[([A-D])$/);
+	if (arrowMatch) {
+		return `\x1b[1;${modifier}${arrowMatch[1]}`;
+	}
+	// Numbered sequences: ESC[5~ -> ESC[5;mod~
+	const numMatch = sequence.match(/^\x1b\[(\d+)~$/);
+	if (numMatch) {
+		return `\x1b[${numMatch[1]};${modifier}~`;
+	}
+	// Home/End: ESC[H -> ESC[1;modH, ESC[F -> ESC[1;modF
+	const hfMatch = sequence.match(/^\x1b\[([HF])$/);
+	if (hfMatch) {
+		return `\x1b[1;${modifier}${hfMatch[1]}`;
+	}
+	return null;
+}
+
+// Bracketed paste mode sequences
+const BRACKETED_PASTE_START = "\x1b[200~";
+const BRACKETED_PASTE_END = "\x1b[201~";
+
+function encodePaste(text: string, bracketed = true): string {
+	if (!bracketed) return text;
+	return `${BRACKETED_PASTE_START}${text}${BRACKETED_PASTE_END}`;
+}
+
+/** Parse a key token and return the escape sequence */
+function encodeKeyToken(token: string): string {
+	const normalized = token.trim().toLowerCase();
+	if (!normalized) return "";
+
+	// Check for direct match in named keys
+	if (NAMED_KEYS[normalized]) {
+		return NAMED_KEYS[normalized];
+	}
+
+	// Check for ctrl+key
+	if (CTRL_KEYS[normalized]) {
+		return CTRL_KEYS[normalized];
+	}
+
+	// Parse modifier prefixes: ctrl+alt+shift+key, c-m-s-key, etc.
+	let rest = normalized;
+	let ctrl = false, alt = false, shift = false;
+
+	// Support both "ctrl+alt+x" and "c-m-x" syntax
+	while (rest.length > 2) {
+		if (rest.startsWith("ctrl+") || rest.startsWith("ctrl-")) {
+			ctrl = true;
+			rest = rest.slice(5);
+		} else if (rest.startsWith("alt+") || rest.startsWith("alt-")) {
+			alt = true;
+			rest = rest.slice(4);
+		} else if (rest.startsWith("shift+") || rest.startsWith("shift-")) {
+			shift = true;
+			rest = rest.slice(6);
+		} else if (rest.startsWith("c-")) {
+			ctrl = true;
+			rest = rest.slice(2);
+		} else if (rest.startsWith("m-")) {
+			alt = true;
+			rest = rest.slice(2);
+		} else if (rest.startsWith("s-")) {
+			shift = true;
+			rest = rest.slice(2);
+		} else {
+			break;
+		}
+	}
+
+	// Handle shift+tab specially
+	if (shift && rest === "tab") {
+		return "\x1b[Z";
+	}
+
+	// Check if base key is a named key that supports modifiers
+	const baseSeq = NAMED_KEYS[rest];
+	if (baseSeq && MODIFIABLE_KEYS.has(rest) && (ctrl || alt || shift)) {
+		const mod = xtermModifier(shift, alt, ctrl);
+		if (mod > 1) {
+			const modified = applyXtermModifier(baseSeq, mod);
+			if (modified) return modified;
+		}
+	}
+
+	// For single character with modifiers
+	if (rest.length === 1) {
+		let char = rest;
+		if (shift && /[a-z]/.test(char)) {
+			char = char.toUpperCase();
+		}
+		if (ctrl) {
+			const ctrlChar = CTRL_KEYS[`ctrl+${char.toLowerCase()}`];
+			if (ctrlChar) char = ctrlChar;
+		}
+		if (alt) {
+			return altKey(char);
+		}
+		return char;
+	}
+
+	// Named key with alt modifier
+	if (baseSeq && alt) {
+		return `\x1b${baseSeq}`;
+	}
+
+	// Return base sequence if found
+	if (baseSeq) {
+		return baseSeq;
+	}
+
+	// Unknown key, return as literal
+	return token;
+}
+
+/** Translate input specification to terminal escape sequences */
+export function translateInput(input: string | { text?: string; keys?: string[]; paste?: string; hex?: string[] }): string {
+	if (typeof input === "string") {
+		return input;
+	}
+
+	let result = "";
+
+	// Hex bytes (raw escape sequences)
+	if (input.hex?.length) {
+		for (const raw of input.hex) {
+			const trimmed = raw.trim().toLowerCase();
+			const normalized = trimmed.startsWith("0x") ? trimmed.slice(2) : trimmed;
+			if (/^[0-9a-f]{1,2}$/.test(normalized)) {
+				const value = Number.parseInt(normalized, 16);
+				if (!Number.isNaN(value) && value >= 0 && value <= 0xff) {
+					result += String.fromCharCode(value);
+				}
+			}
+		}
+	}
+
+	// Literal text
+	if (input.text) {
+		result += input.text;
+	}
+
+	// Named keys with modifier support
+	if (input.keys) {
+		for (const key of input.keys) {
+			result += encodeKeyToken(key);
+		}
+	}
+
+	// Bracketed paste
+	if (input.paste) {
+		result += encodePaste(input.paste);
+	}
+
+	return result;
+}

package/overlay-component.ts

@@ -924,7 +924,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 		const lines: string[] = [];
 
-		const title = truncateToWidth(this.options.command, innerWidth - 20, "...");
+		// Sanitize command: collapse newlines and whitespace to single spaces for display
+		const sanitizedCommand = this.options.command.replace(/\s+/g, " ").trim();
+		const title = truncateToWidth(sanitizedCommand, innerWidth - 20, "...");
 		const pid = `PID: ${this.session.pid}`;
 		lines.push(border("╭" + "─".repeat(width - 2) + "╮"));
 		lines.push(
@@ -935,16 +937,18 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			),
 		);
 		let hint: string;
+		// Sanitize reason: collapse newlines and whitespace to single spaces for display
+		const sanitizedReason = this.options.reason?.replace(/\s+/g, " ").trim();
 		if (this.state === "hands-free") {
 			const elapsed = formatDuration(Date.now() - this.startTime);
 			hint = `🤖 Hands-free (${elapsed}) • Type anything to take over`;
 		} else if (this.userTookOver) {
-			hint = this.options.reason
-				? `You took over • ${this.options.reason} • Ctrl+Q to detach`
+			hint = sanitizedReason
+				? `You took over • ${sanitizedReason} • Ctrl+Q to detach`
 				: "You took over • Ctrl+Q to detach";
 		} else {
-			hint = this.options.reason
-				? `Ctrl+Q to detach • ${this.options.reason}`
+			hint = sanitizedReason
+				? `Ctrl+Q to detach • ${sanitizedReason}`
 				: "Ctrl+Q to detach";
 		}
 		lines.push(row(dim(truncateToWidth(hint, innerWidth, "..."))));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.4.8",
+  "version": "0.4.9",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {
@@ -9,9 +9,13 @@
   "files": [
     "index.ts",
     "config.ts",
+    "key-encoding.ts",
     "overlay-component.ts",
     "pty-session.ts",
+    "reattach-overlay.ts",
     "session-manager.ts",
+    "tool-schema.ts",
+    "types.ts",
     "scripts/",
     "README.md",
     "SKILL.md",

package/reattach-overlay.ts

@@ -0,0 +1,415 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { Component, Focusable, TUI } from "@mariozechner/pi-tui";
+import { matchesKey, truncateToWidth, visibleWidth } from "@mariozechner/pi-tui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { PtyTerminalSession } from "./pty-session.js";
+import { sessionManager } from "./session-manager.js";
+import type { InteractiveShellConfig } from "./config.js";
+import {
+	type InteractiveShellResult,
+	type DialogChoice,
+	type OverlayState,
+	CHROME_LINES,
+	FOOTER_LINES,
+} from "./types.js";
+
+export class ReattachOverlay implements Component, Focusable {
+	focused = false;
+
+	private tui: TUI;
+	private theme: Theme;
+	private done: (result: InteractiveShellResult) => void;
+	private bgSession: { id: string; command: string; reason?: string; session: PtyTerminalSession };
+	private config: InteractiveShellConfig;
+
+	private state: OverlayState = "running";
+	private dialogSelection: DialogChoice = "background";
+	private exitCountdown = 0;
+	private countdownInterval: ReturnType<typeof setInterval> | null = null;
+	private initialExitTimeout: ReturnType<typeof setTimeout> | null = null;
+	private lastWidth = 0;
+	private lastHeight = 0;
+	private finished = false;
+
+	constructor(
+		tui: TUI,
+		theme: Theme,
+		bgSession: { id: string; command: string; reason?: string; session: PtyTerminalSession },
+		config: InteractiveShellConfig,
+		done: (result: InteractiveShellResult) => void,
+	) {
+		this.tui = tui;
+		this.theme = theme;
+		this.bgSession = bgSession;
+		this.config = config;
+		this.done = done;
+
+		bgSession.session.setEventHandlers({
+			onData: () => {
+				if (!bgSession.session.isScrolledUp()) {
+					bgSession.session.scrollToBottom();
+				}
+				this.tui.requestRender();
+			},
+			onExit: () => {
+				if (this.finished) return;
+				this.state = "exited";
+				this.exitCountdown = this.config.exitAutoCloseDelay;
+				this.startExitCountdown();
+				this.tui.requestRender();
+			},
+		});
+
+		if (bgSession.session.exited) {
+			this.state = "exited";
+			this.exitCountdown = this.config.exitAutoCloseDelay;
+			this.initialExitTimeout = setTimeout(() => {
+				this.initialExitTimeout = null;
+				this.startExitCountdown();
+			}, 0);
+		}
+
+		const overlayWidth = Math.floor((tui.terminal.columns * this.config.overlayWidthPercent) / 100);
+		const overlayHeight = Math.floor((tui.terminal.rows * this.config.overlayHeightPercent) / 100);
+		const cols = Math.max(20, overlayWidth - 4);
+		const rows = Math.max(3, overlayHeight - CHROME_LINES);
+		bgSession.session.resize(cols, rows);
+	}
+
+	private get session(): PtyTerminalSession {
+		return this.bgSession.session;
+	}
+
+	private startExitCountdown(): void {
+		this.stopCountdown();
+		this.countdownInterval = setInterval(() => {
+			this.exitCountdown--;
+			if (this.exitCountdown <= 0) {
+				this.finishAndClose();
+			} else {
+				this.tui.requestRender();
+			}
+		}, 1000);
+	}
+
+	private stopCountdown(): void {
+		if (this.countdownInterval) {
+			clearInterval(this.countdownInterval);
+			this.countdownInterval = null;
+		}
+	}
+
+	private maybeBuildHandoffPreview(when: "exit" | "detach" | "kill"): InteractiveShellResult["handoffPreview"] | undefined {
+		if (!this.config.handoffPreviewEnabled) return undefined;
+		const lines = this.config.handoffPreviewLines;
+		const maxChars = this.config.handoffPreviewMaxChars;
+		if (lines <= 0 || maxChars <= 0) return undefined;
+
+		// Use raw output stream instead of xterm buffer - TUI apps using alternate
+		// screen buffer can have misleading content in getTailLines()
+		const rawOutput = this.session.getRawStream({ stripAnsi: true });
+		if (!rawOutput) return { type: "tail", when, lines: [] };
+		
+		const outputLines = rawOutput.split("\n");
+
+		// Get last N lines, respecting maxChars
+		let tail: string[] = [];
+		let charCount = 0;
+		for (let i = outputLines.length - 1; i >= 0 && tail.length < lines; i--) {
+			const line = outputLines[i];
+			if (charCount + line.length > maxChars && tail.length > 0) break;
+			tail.unshift(line);
+			charCount += line.length + 1; // +1 for newline
+		}
+
+		return { type: "tail", when, lines: tail };
+	}
+
+	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill"): InteractiveShellResult["handoff"] | undefined {
+		if (!this.config.handoffSnapshotEnabled) return undefined;
+		const lines = this.config.handoffSnapshotLines;
+		const maxChars = this.config.handoffSnapshotMaxChars;
+		if (lines <= 0 || maxChars <= 0) return undefined;
+
+		const baseDir = join(homedir(), ".pi", "agent", "cache", "interactive-shell");
+		mkdirSync(baseDir, { recursive: true });
+
+		const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
+		const pid = this.session.pid;
+		const filename = `snapshot-${timestamp}-pid${pid}.log`;
+		const transcriptPath = join(baseDir, filename);
+
+		const tailResult = this.session.getTailLines({
+			lines,
+			ansi: this.config.ansiReemit,
+			maxChars,
+		});
+
+		const header = [
+			`# interactive-shell snapshot (${when})`,
+			`time: ${new Date().toISOString()}`,
+			`command: ${this.bgSession.command}`,
+			`pid: ${pid}`,
+			`exitCode: ${this.session.exitCode ?? ""}`,
+			`signal: ${this.session.signal ?? ""}`,
+			`lines: ${tailResult.lines.length} (requested ${lines}, maxChars ${maxChars})`,
+			"",
+		].join("\n");
+
+		writeFileSync(transcriptPath, header + tailResult.lines.join("\n") + "\n", { encoding: "utf-8" });
+
+		return { type: "snapshot", when, transcriptPath, linesWritten: tailResult.lines.length };
+	}
+
+	private finishAndClose(): void {
+		if (this.finished) return;
+		this.finished = true;
+		this.stopCountdown();
+		const handoffPreview = this.maybeBuildHandoffPreview("exit");
+		const handoff = this.maybeWriteHandoffSnapshot("exit");
+		sessionManager.remove(this.bgSession.id);
+		this.done({
+			exitCode: this.session.exitCode,
+			signal: this.session.signal,
+			backgrounded: false,
+			cancelled: false,
+			handoffPreview,
+			handoff,
+		});
+	}
+
+	private finishWithBackground(): void {
+		if (this.finished) return;
+		this.finished = true;
+		this.stopCountdown();
+		const handoffPreview = this.maybeBuildHandoffPreview("detach");
+		const handoff = this.maybeWriteHandoffSnapshot("detach");
+		this.session.setEventHandlers({});
+		this.done({
+			exitCode: null,
+			backgrounded: true,
+			backgroundId: this.bgSession.id,
+			cancelled: false,
+			handoffPreview,
+			handoff,
+		});
+	}
+
+	private finishWithKill(): void {
+		if (this.finished) return;
+		this.finished = true;
+		this.stopCountdown();
+		const handoffPreview = this.maybeBuildHandoffPreview("kill");
+		const handoff = this.maybeWriteHandoffSnapshot("kill");
+		sessionManager.remove(this.bgSession.id);
+		this.done({
+			exitCode: null,
+			backgrounded: false,
+			cancelled: true,
+			handoffPreview,
+			handoff,
+		});
+	}
+
+	handleInput(data: string): void {
+		if (this.state === "detach-dialog") {
+			this.handleDialogInput(data);
+			return;
+		}
+
+		if (this.state === "exited") {
+			if (data.length > 0) {
+				this.finishAndClose();
+			}
+			return;
+		}
+
+		if (this.session.exited && this.state === "running") {
+			this.state = "exited";
+			this.exitCountdown = this.config.exitAutoCloseDelay;
+			this.startExitCountdown();
+			this.tui.requestRender();
+			return;
+		}
+
+		// Ctrl+Q opens detach dialog
+		if (matchesKey(data, "ctrl+q")) {
+			this.state = "detach-dialog";
+			this.dialogSelection = "background";
+			this.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "shift+up")) {
+			this.session.scrollUp(Math.max(1, this.session.rows - 2));
+			this.tui.requestRender();
+			return;
+		}
+		if (matchesKey(data, "shift+down")) {
+			this.session.scrollDown(Math.max(1, this.session.rows - 2));
+			this.tui.requestRender();
+			return;
+		}
+
+		this.session.write(data);
+	}
+
+	private handleDialogInput(data: string): void {
+		if (matchesKey(data, "escape")) {
+			this.state = "running";
+			this.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "up") || matchesKey(data, "down")) {
+			const options: DialogChoice[] = ["kill", "background", "cancel"];
+			const currentIdx = options.indexOf(this.dialogSelection);
+			const direction = matchesKey(data, "up") ? -1 : 1;
+			const newIdx = (currentIdx + direction + options.length) % options.length;
+			this.dialogSelection = options[newIdx]!;
+			this.tui.requestRender();
+			return;
+		}
+
+		if (matchesKey(data, "enter")) {
+			switch (this.dialogSelection) {
+				case "kill":
+					this.finishWithKill();
+					break;
+				case "background":
+					this.finishWithBackground();
+					break;
+				case "cancel":
+					this.state = "running";
+					this.tui.requestRender();
+					break;
+			}
+		}
+	}
+
+	render(width: number): string[] {
+		const th = this.theme;
+		const border = (s: string) => th.fg("border", s);
+		const accent = (s: string) => th.fg("accent", s);
+		const dim = (s: string) => th.fg("dim", s);
+		const warning = (s: string) => th.fg("warning", s);
+
+		const innerWidth = width - 4;
+		const pad = (s: string, w: number) => {
+			const vis = visibleWidth(s);
+			return s + " ".repeat(Math.max(0, w - vis));
+		};
+		const row = (content: string) => border("│ ") + pad(content, innerWidth) + border(" │");
+		const emptyRow = () => row("");
+
+		const lines: string[] = [];
+
+		// Sanitize command: collapse newlines and whitespace to single spaces for display
+		const sanitizedCommand = this.bgSession.command.replace(/\s+/g, " ").trim();
+		const title = truncateToWidth(sanitizedCommand, innerWidth - 30, "...");
+		const idLabel = `[${this.bgSession.id}]`;
+		const pid = `PID: ${this.session.pid}`;
+
+		lines.push(border("╭" + "─".repeat(width - 2) + "╮"));
+		lines.push(
+			row(
+				accent(title) +
+					" " +
+					dim(idLabel) +
+					" ".repeat(
+						Math.max(1, innerWidth - visibleWidth(title) - idLabel.length - pid.length - 1),
+					) +
+					dim(pid),
+			),
+		);
+		// Sanitize reason: collapse newlines and whitespace to single spaces for display
+		const sanitizedReason = this.bgSession.reason?.replace(/\s+/g, " ").trim();
+		const hint = sanitizedReason
+			? `Reattached • ${sanitizedReason} • Ctrl+Q to detach`
+			: "Reattached • Ctrl+Q to detach";
+		lines.push(row(dim(truncateToWidth(hint, innerWidth, "..."))));
+		lines.push(border("├" + "─".repeat(width - 2) + "┤"));
+
+		const overlayHeight = Math.floor((this.tui.terminal.rows * this.config.overlayHeightPercent) / 100);
+		const termRows = Math.max(3, overlayHeight - CHROME_LINES);
+
+		if (innerWidth !== this.lastWidth || termRows !== this.lastHeight) {
+			this.session.resize(innerWidth, termRows);
+			this.lastWidth = innerWidth;
+			this.lastHeight = termRows;
+			// After resize, ensure we're at the bottom to prevent flash to top
+			this.session.scrollToBottom();
+		}
+
+		const viewportLines = this.session.getViewportLines({ ansi: this.config.ansiReemit });
+		for (const line of viewportLines) {
+			lines.push(row(truncateToWidth(line, innerWidth, "")));
+		}
+
+		if (this.session.isScrolledUp()) {
+			const hintText = "── ↑ scrolled ──";
+			const padLen = Math.max(0, Math.floor((width - 2 - visibleWidth(hintText)) / 2));
+			lines.push(
+				border("├") +
+					dim(
+						" ".repeat(padLen) +
+							hintText +
+							" ".repeat(width - 2 - padLen - visibleWidth(hintText)),
+					) +
+					border("┤"),
+			);
+		} else {
+			lines.push(border("├" + "─".repeat(width - 2) + "┤"));
+		}
+
+		const footerLines: string[] = [];
+
+		if (this.state === "detach-dialog") {
+			footerLines.push(row(accent("Detach from session:")));
+			const opts: Array<{ key: DialogChoice; label: string }> = [
+				{ key: "kill", label: "Kill process" },
+				{ key: "background", label: "Run in background" },
+				{ key: "cancel", label: "Cancel (return to session)" },
+			];
+			for (const opt of opts) {
+				const sel = this.dialogSelection === opt.key;
+				footerLines.push(row((sel ? accent("▶ ") : "  ") + (sel ? accent(opt.label) : opt.label)));
+			}
+			footerLines.push(row(dim("↑↓ select • Enter confirm • Esc cancel")));
+		} else if (this.state === "exited") {
+			const exitMsg =
+				this.session.exitCode === 0
+					? th.fg("success", "✓ Exited successfully")
+					: warning(`✗ Exited with code ${this.session.exitCode}`);
+			footerLines.push(row(exitMsg));
+			footerLines.push(row(dim(`Closing in ${this.exitCountdown}s... (any key to close)`)));
+		} else {
+			footerLines.push(row(dim("Shift+Up/Down scroll • Ctrl+Q detach")));
+		}
+
+		while (footerLines.length < FOOTER_LINES) {
+			footerLines.push(emptyRow());
+		}
+		lines.push(...footerLines);
+
+		lines.push(border("╰" + "─".repeat(width - 2) + "╯"));
+
+		return lines;
+	}
+
+	invalidate(): void {
+		this.lastWidth = 0;
+		this.lastHeight = 0;
+	}
+
+	dispose(): void {
+		if (this.initialExitTimeout) {
+			clearTimeout(this.initialExitTimeout);
+			this.initialExitTimeout = null;
+		}
+		this.stopCountdown();
+		this.session.setEventHandlers({});
+	}
+}

package/tool-schema.ts

@@ -0,0 +1,254 @@
+import { Type } from "@sinclair/typebox";
+
+export const TOOL_NAME = "interactive_shell";
+export const TOOL_LABEL = "Interactive Shell";
+
+export const TOOL_DESCRIPTION = `Run an interactive CLI coding agent in an overlay.
+
+Use this ONLY for delegating tasks to other AI coding agents (Claude Code, Gemini CLI, Codex, etc.) that have their own TUI and benefit from user interaction.
+
+DO NOT use this for regular bash commands - use the standard bash tool instead.
+
+MODES:
+- interactive (default): User supervises and controls the session
+- hands-free: Agent monitors with periodic updates, user can take over anytime by typing
+
+The user will see the process in an overlay. They can:
+- Watch output in real-time
+- Scroll through output (Shift+Up/Down)
+- Detach (Ctrl+Q) to kill or run in background
+- In hands-free mode: type anything to take over control
+
+HANDS-FREE MODE (NON-BLOCKING):
+When mode="hands-free", the tool returns IMMEDIATELY with a sessionId.
+The overlay opens for the user to watch, but you (the agent) get control back right away.
+
+Workflow:
+1. Start session: interactive_shell({ command: 'pi "Fix bugs"', mode: "hands-free" })
+   -> Returns immediately with sessionId
+2. Check status/output: interactive_shell({ sessionId: "calm-reef" })
+   -> Returns current status and any new output since last check
+3. When task is done: interactive_shell({ sessionId: "calm-reef", kill: true })
+   -> Kills session and returns final output
+
+The user sees the overlay and can:
+- Watch output in real-time
+- Take over by typing (you'll see "user-takeover" status on next query)
+- Kill/background via Ctrl+Q
+
+QUERYING SESSION STATUS:
+- interactive_shell({ sessionId: "calm-reef" }) - get status + rendered terminal output (default: 20 lines, 5KB)
+- interactive_shell({ sessionId: "calm-reef", outputLines: 50 }) - get more lines (max: 200)
+- interactive_shell({ sessionId: "calm-reef", outputMaxChars: 20000 }) - get more content (max: 50KB)
+- interactive_shell({ sessionId: "calm-reef", outputOffset: 0, outputLines: 50 }) - pagination (lines 0-49)
+- interactive_shell({ sessionId: "calm-reef", incremental: true }) - get next N unseen lines (server tracks position)
+- interactive_shell({ sessionId: "calm-reef", drain: true }) - only NEW output since last query (raw stream)
+- interactive_shell({ sessionId: "calm-reef", kill: true }) - end session
+- interactive_shell({ sessionId: "calm-reef", input: "..." }) - send input
+
+IMPORTANT: Don't query too frequently! Wait 30-60 seconds between status checks.
+The user is watching the overlay in real-time - you're just checking in periodically.
+
+RATE LIMITING:
+Queries are limited to once every 60 seconds (configurable). If you query too soon,
+the tool will automatically wait until the limit expires before returning.
+
+SENDING INPUT:
+- interactive_shell({ sessionId: "calm-reef", input: "/help\\n" })
+- interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
+
+Named keys: up, down, left, right, enter, escape, tab, backspace, ctrl+c, ctrl+d, etc.
+Modifiers: ctrl+x, alt+x, shift+tab, ctrl+alt+delete (or c-x, m-x, s-tab syntax)
+Hex bytes: input: { hex: ["0x1b", "0x5b", "0x41"] } for raw escape sequences
+Bracketed paste: input: { paste: "multiline\\ntext" } prevents auto-execution
+
+TIMEOUT (for TUI commands that don't exit cleanly):
+Use timeout to auto-kill after N milliseconds. Useful for capturing output from commands like "pi --help":
+- interactive_shell({ command: "pi --help", mode: "hands-free", timeout: 5000 })
+
+Important: this tool does NOT inject prompts. If you want to start with a prompt,
+include it in the command using the CLI's own prompt flags.
+
+Examples:
+- pi "Scan the current codebase"
+- claude "Check the current directory and summarize"
+- gemini (interactive, idle)
+- aider --yes-always (hands-free, auto-approve)
+- pi --help (with timeout: 5000 to capture help output)`;
+
+export const toolParameters = Type.Object({
+	command: Type.Optional(
+		Type.String({
+			description: "The CLI agent command (e.g., 'pi \"Fix the bug\"'). Required to start a new session.",
+		}),
+	),
+	sessionId: Type.Optional(
+		Type.String({
+			description: "Session ID to interact with an existing hands-free session",
+		}),
+	),
+	kill: Type.Optional(
+		Type.Boolean({
+			description: "Kill the session (requires sessionId). Use when task appears complete.",
+		}),
+	),
+	outputLines: Type.Optional(
+		Type.Number({
+			description: "Number of lines to return when querying (default: 20, max: 200)",
+		}),
+	),
+	outputMaxChars: Type.Optional(
+		Type.Number({
+			description: "Max chars to return when querying (default: 5KB, max: 50KB)",
+		}),
+	),
+	outputOffset: Type.Optional(
+		Type.Number({
+			description: "Line offset for pagination (0-indexed). Use with outputLines to read specific ranges.",
+		}),
+	),
+	drain: Type.Optional(
+		Type.Boolean({
+			description: "If true, return only NEW output since last query (raw stream). More token-efficient for repeated polling.",
+		}),
+	),
+	incremental: Type.Optional(
+		Type.Boolean({
+			description: "If true, return next N lines not yet seen. Server tracks position - just keep calling to paginate through output.",
+		}),
+	),
+	settings: Type.Optional(
+		Type.Object({
+			updateInterval: Type.Optional(
+				Type.Number({ description: "Change max update interval for existing session (ms)" }),
+			),
+			quietThreshold: Type.Optional(
+				Type.Number({ description: "Change quiet threshold for existing session (ms)" }),
+			),
+		}),
+	),
+	input: Type.Optional(
+		Type.Union(
+			[
+				Type.String({ description: "Raw text/keystrokes to send" }),
+				Type.Object({
+					text: Type.Optional(Type.String({ description: "Text to type" })),
+					keys: Type.Optional(
+						Type.Array(Type.String(), {
+							description:
+								"Named keys with modifier support: up, down, enter, ctrl+c, alt+x, shift+tab, ctrl+alt+delete, etc.",
+						}),
+					),
+					hex: Type.Optional(
+						Type.Array(Type.String(), {
+							description: "Hex bytes to send (e.g., ['0x1b', '0x5b', '0x41'] for ESC[A)",
+						}),
+					),
+					paste: Type.Optional(
+						Type.String({
+							description: "Text to paste with bracketed paste mode (prevents auto-execution)",
+						}),
+					),
+				}),
+			],
+			{ description: "Input to send to an existing session (requires sessionId)" },
+		),
+	),
+	cwd: Type.Optional(
+		Type.String({
+			description: "Working directory for the command",
+		}),
+	),
+	name: Type.Optional(
+		Type.String({
+			description: "Optional session name (used for session IDs)",
+		}),
+	),
+	reason: Type.Optional(
+		Type.String({
+			description:
+				"Brief explanation shown in the overlay header only (not passed to the subprocess)",
+		}),
+	),
+	mode: Type.Optional(
+		Type.Union([Type.Literal("interactive"), Type.Literal("hands-free")], {
+			description: "interactive (default): user controls. hands-free: agent monitors, user can take over",
+		}),
+	),
+	handsFree: Type.Optional(
+		Type.Object({
+			updateMode: Type.Optional(
+				Type.Union([Type.Literal("on-quiet"), Type.Literal("interval")], {
+					description: "on-quiet (default): emit when output stops. interval: emit on fixed schedule.",
+				}),
+			),
+			updateInterval: Type.Optional(
+				Type.Number({ description: "Max interval between updates in ms (default: 60000)" }),
+			),
+			quietThreshold: Type.Optional(
+				Type.Number({ description: "Silence duration before emitting update in on-quiet mode (default: 5000ms)" }),
+			),
+			updateMaxChars: Type.Optional(
+				Type.Number({ description: "Max chars per update (default: 1500)" }),
+			),
+			maxTotalChars: Type.Optional(
+				Type.Number({ description: "Total char budget for all updates (default: 100000). Updates stop including content when exhausted." }),
+			),
+			autoExitOnQuiet: Type.Optional(
+				Type.Boolean({
+					description: "Auto-kill session when output stops (after quietThreshold). Defaults to false. Set to true for fire-and-forget single-task delegations.",
+				}),
+			),
+		}),
+	),
+	handoffPreview: Type.Optional(
+		Type.Object({
+			enabled: Type.Optional(Type.Boolean({ description: "Include last N lines in tool result details" })),
+			lines: Type.Optional(Type.Number({ description: "Tail lines to include (default from config)" })),
+			maxChars: Type.Optional(
+				Type.Number({ description: "Max chars to include in tail preview (default from config)" }),
+			),
+		}),
+	),
+	handoffSnapshot: Type.Optional(
+		Type.Object({
+			enabled: Type.Optional(Type.Boolean({ description: "Write a transcript snapshot on detach/exit" })),
+			lines: Type.Optional(Type.Number({ description: "Tail lines to capture (default from config)" })),
+			maxChars: Type.Optional(Type.Number({ description: "Max chars to write (default from config)" })),
+		}),
+	),
+	timeout: Type.Optional(
+		Type.Number({
+			description: "Auto-kill process after N milliseconds. Useful for TUI commands that don't exit cleanly (e.g., 'pi --help')",
+		}),
+	),
+});
+
+/** Parsed tool parameters type */
+export interface ToolParams {
+	command?: string;
+	sessionId?: string;
+	kill?: boolean;
+	outputLines?: number;
+	outputMaxChars?: number;
+	outputOffset?: number;
+	drain?: boolean;
+	incremental?: boolean;
+	settings?: { updateInterval?: number; quietThreshold?: number };
+	input?: string | { text?: string; keys?: string[]; hex?: string[]; paste?: string };
+	cwd?: string;
+	name?: string;
+	reason?: string;
+	mode?: "interactive" | "hands-free";
+	handsFree?: {
+		updateMode?: "on-quiet" | "interval";
+		updateInterval?: number;
+		quietThreshold?: number;
+		updateMaxChars?: number;
+		maxTotalChars?: number;
+		autoExitOnQuiet?: boolean;
+	};
+	handoffPreview?: { enabled?: boolean; lines?: number; maxChars?: number };
+	handoffSnapshot?: { enabled?: boolean; lines?: number; maxChars?: number };
+	timeout?: number;
+}

package/types.ts

@@ -0,0 +1,92 @@
+/**
+ * Shared types and interfaces for the interactive shell extension.
+ */
+
+export interface InteractiveShellResult {
+	exitCode: number | null;
+	signal?: number;
+	backgrounded: boolean;
+	backgroundId?: string;
+	cancelled: boolean;
+	timedOut?: boolean;
+	sessionId?: string;
+	userTookOver?: boolean;
+	handoffPreview?: {
+		type: "tail";
+		when: "exit" | "detach" | "kill" | "timeout";
+		lines: string[];
+	};
+	handoff?: {
+		type: "snapshot";
+		when: "exit" | "detach" | "kill" | "timeout";
+		transcriptPath: string;
+		linesWritten: number;
+	};
+}
+
+export interface HandsFreeUpdate {
+	status: "running" | "user-takeover" | "exited" | "killed";
+	sessionId: string;
+	runtime: number;
+	tail: string[];
+	tailTruncated: boolean;
+	userTookOver?: boolean;
+	// Budget tracking
+	totalCharsSent?: number;
+	budgetExhausted?: boolean;
+}
+
+export interface InteractiveShellOptions {
+	command: string;
+	cwd?: string;
+	name?: string;
+	reason?: string;
+	handoffPreviewEnabled?: boolean;
+	handoffPreviewLines?: number;
+	handoffPreviewMaxChars?: number;
+	handoffSnapshotEnabled?: boolean;
+	handoffSnapshotLines?: number;
+	handoffSnapshotMaxChars?: number;
+	// Hands-free mode
+	mode?: "interactive" | "hands-free";
+	sessionId?: string; // Pre-generated sessionId for hands-free mode
+	handsFreeUpdateMode?: "on-quiet" | "interval";
+	handsFreeUpdateInterval?: number;
+	handsFreeQuietThreshold?: number;
+	handsFreeUpdateMaxChars?: number;
+	handsFreeMaxTotalChars?: number;
+	onHandsFreeUpdate?: (update: HandsFreeUpdate) => void;
+	// Auto-exit when output stops (for agents that don't exit on their own)
+	autoExitOnQuiet?: boolean;
+	// Auto-kill timeout
+	timeout?: number;
+}
+
+export type DialogChoice = "kill" | "background" | "cancel";
+export type OverlayState = "running" | "exited" | "detach-dialog" | "hands-free";
+
+// UI constants
+export const FOOTER_LINES = 5;
+export const HEADER_LINES = 4;
+export const CHROME_LINES = HEADER_LINES + FOOTER_LINES + 2;
+
+/** Format milliseconds to human-readable duration */
+export function formatDuration(ms: number): string {
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+	const hours = Math.floor(minutes / 60);
+	return `${hours}h ${minutes % 60}m`;
+}
+
+/** Format milliseconds with ms precision for shorter durations */
+export function formatDurationMs(ms: number): string {
+	if (ms < 1000) return `${ms}ms`;
+	const seconds = Math.floor(ms / 1000);
+	if (seconds < 60) return `${seconds}s`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+	const hours = Math.floor(minutes / 60);
+	return `${hours}h ${minutes % 60}m`;
+}