pi-interactive-shell 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to the `pi-interactive-shell` extension will be documented in this file.
 
+## [0.4.3] - 2026-01-18
+
+### Added
+- **Configurable output limits** - New `outputLines` and `outputMaxChars` parameters when querying sessions:
+  - `outputLines`: Request more lines (default: 20, max: 200)
+  - `outputMaxChars`: Request more content (default: 5KB, max: 50KB)
+  - Example: `interactive_shell({ sessionId: "calm-reef", outputLines: 50 })`
+- **Escape hint feedback** - After pressing first Escape, shows "Press Escape again to detach..." in footer for 300ms
+
+### Fixed
+- **Escape hint not showing** - Fixed bug where `clearEscapeHint()` was immediately resetting `showEscapeHint` to false after setting it to true
+- **Negative output limits** - Added clamping to ensure `outputLines` and `outputMaxChars` are at least 1
+- **Reduced flickering during rapid output** - Three improvements:
+  1. Scroll position calculated at render time via `followBottom` flag (not on each data event)
+  2. Debounced render requests (16ms) to batch rapid updates before drawing
+  3. Explicit scroll-to-bottom after resize to prevent flash to top during dimension changes
+
 ## [0.4.2] - 2026-01-17
 
 ### Added

package/README.md

@@ -55,6 +55,12 @@ This installs the extension to `~/.pi/agent/extensions/interactive-shell/`, runs
 - `sessionId` (string, required): session ID
 - `settings` (object): `{ updateInterval?, quietThreshold? }`
 
+**Query session status:**
+- `sessionId` (string, required): session ID
+- `outputLines` (number): lines to return (default: 20, max: 200)
+- `outputMaxChars` (number): max chars to return (default: 5KB, max: 50KB)
+- `kill` (boolean): kill the session and return final output
+
 ### Command: `/attach`
 
 Reattach to background sessions:

package/SKILL.md

@@ -5,7 +5,7 @@ description: Cheat sheet + workflow for launching interactive coding-agent CLIs
 
 # Interactive Shell (Skill)
 
-Last verified: 2026-01-17
+Last verified: 2026-01-18
 
 ## Foreground vs Background Subagents
 
@@ -122,7 +122,21 @@ interactive_shell({ sessionId: "calm-reef", kill: true })
 
 Kill when you see the task is complete in the output. Returns final status and output.
 
-**Auto-exit:** In hands-free mode, sessions auto-kill when output stops (after ~5 seconds of quiet). This means when an agent finishes its task, the session closes automatically. You can disable this with `handsFree: { autoExitOnQuiet: false }`.
+**Auto-exit (default: enabled):** In hands-free mode, sessions auto-kill when output stops (after ~5 seconds of quiet). This means when an agent finishes its task and returns to its prompt, the session closes automatically.
+
+Since sessions auto-close, **always instruct the subagent to save results to a file** so you can read them:
+
+```typescript
+interactive_shell({
+  command: 'pi "Review this codebase for security issues. Save your findings to /tmp/security-review.md"',
+  mode: "hands-free",
+  reason: "Security review"
+})
+// After session ends, read the results:
+// read("/tmp/security-review.md")
+```
+
+To disable auto-exit (for long-running tasks or when you need to review output): `handsFree: { autoExitOnQuiet: false }`
 
 ### Sending Input
 ```typescript
@@ -133,18 +147,38 @@ interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
 ### Query Output
 
 Status queries return **rendered terminal output** (what's actually on screen), not raw stream:
-- Last 20 lines of the terminal, clean and readable
+- Default: 20 lines, 5KB max per query
 - No TUI animation noise (spinners, progress bars, etc.)
-- Max 5KB per query to keep context manageable
-- Configure via `handsFree.maxTotalChars`
+- Configurable via `outputLines` (max: 200) and `outputMaxChars` (max: 50KB)
+
+```typescript
+// Get more output when reviewing a session
+interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
+
+// Get even more for detailed review
+interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
+```
+
+### Reviewing Long Sessions (autoExitOnQuiet disabled)
+
+When you disable auto-exit for long-running tasks, progressively review more output as needed:
 
 ```typescript
-// Custom budget for a long task
+// Start a long session without auto-exit
 interactive_shell({
   command: 'pi "Refactor entire codebase"',
   mode: "hands-free",
-  handsFree: { maxTotalChars: 200000 }  // 200KB budget
+  handsFree: { autoExitOnQuiet: false }
 })
+
+// Query returns last 20 lines by default
+interactive_shell({ sessionId: "calm-reef" })
+
+// Get more lines when you need more context
+interactive_shell({ sessionId: "calm-reef", outputLines: 50 })
+
+// Get even more for detailed review
+interactive_shell({ sessionId: "calm-reef", outputLines: 100, outputMaxChars: 30000 })
 ```
 
 ## Sending Input to Active Sessions
@@ -244,49 +278,17 @@ interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } }
 interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000, quietThreshold: 2000 } })
 ```
 
-## CLI Cheat Sheet
-
-### Claude Code (`claude`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `claude` |
-| Interactive (prompted) | `claude "Explain this project"` |
-| Headless (use bash, not overlay) | `claude -p "Explain this function"` |
-
-### Gemini CLI (`gemini`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `gemini` |
-| Interactive (prompted) | `gemini -i "Explain this codebase"` |
-| Headless (use bash, not overlay) | `gemini -p "What is fine tuning?"` |
-
-### Codex CLI (`codex`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `codex` |
-| Interactive (prompted) | `codex "Explain this codebase"` |
-| Headless (use bash, not overlay) | `codex exec "summarize the repo"` |
-
-### Cursor CLI (`cursor-agent`)
-
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `cursor-agent` |
-| Interactive (prompted) | `cursor-agent "review this repo"` |
-| Headless (use bash, not overlay) | `cursor-agent -p "find issues" --output-format text` |
-
-### Pi (`pi`)
+## CLI Quick Reference
 
-| Mode | Command |
-|------|---------|
-| Interactive (idle) | `pi` |
-| Interactive (prompted) | `pi "List all .ts files"` |
-| Headless (use bash, not overlay) | `pi -p "List all .ts files"` |
+| Agent | Interactive | With Prompt | Headless (bash) |
+|-------|-------------|-------------|-----------------|
+| `claude` | `claude` | `claude "prompt"` | `claude -p "prompt"` |
+| `gemini` | `gemini` | `gemini -i "prompt"` | `gemini "prompt"` |
+| `codex` | `codex` | `codex "prompt"` | `codex exec "prompt"` |
+| `agent` | `agent` | `agent "prompt"` | `agent -p "prompt"` |
+| `pi` | `pi` | `pi "prompt"` | `pi -p "prompt"` |
 
-Note: Delegating pi to pi is recursive - usually prefer `subagent` for pi-to-pi delegation.
+**Gemini model:** `gemini -m gemini-3-flash-preview -i "prompt"`
 
 ## Prompt Packaging Rules
 

package/index.ts

@@ -312,7 +312,9 @@ The user sees the overlay and can:
 - Kill/background via double-Escape
 
 QUERYING SESSION STATUS:
-- interactive_shell({ sessionId: "calm-reef" }) - get status + rendered terminal output (last 20 lines)
+- 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", kill: true }) - end session
 - interactive_shell({ sessionId: "calm-reef", input: "..." }) - send input
 
@@ -362,6 +364,16 @@ Examples:
 					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)",
+				}),
+			),
 			settings: Type.Optional(
 				Type.Object({
 					updateInterval: Type.Optional(
@@ -474,6 +486,8 @@ Examples:
 				command,
 				sessionId,
 				kill,
+				outputLines,
+				outputMaxChars,
 				settings,
 				input,
 				cwd,
@@ -488,6 +502,8 @@ Examples:
 				command?: string;
 				sessionId?: string;
 				kill?: boolean;
+				outputLines?: number;
+				outputMaxChars?: number;
 				settings?: { updateInterval?: number; quietThreshold?: number };
 				input?: string | { text?: string; keys?: string[]; hex?: string[]; paste?: string };
 				cwd?: string;
@@ -520,7 +536,7 @@ Examples:
 
 				// Kill session if requested
 				if (kill) {
-					const { output, truncated, totalBytes } = session.getOutput(true); // skipRateLimit=true for kill
+					const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
 					const status = session.getStatus();
 					const runtime = session.getRuntime();
 					session.kill();
@@ -603,7 +619,7 @@ Examples:
 					// If session completed, always allow query (no rate limiting)
 					// Rate limiting only applies to "checking in" on running sessions
 					if (result) {
-						const { output, truncated, totalBytes } = session.getOutput(true); // skipRateLimit=true
+						const { output, truncated, totalBytes } = session.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
 						const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
 						const hasOutput = output.length > 0;
 
@@ -630,7 +646,7 @@ Examples:
 					}
 
 					// Session still running - check rate limiting
-					const outputResult = session.getOutput();
+					const outputResult = session.getOutput({ lines: outputLines, maxChars: outputMaxChars });
 
 					// If rate limited, wait until allowed then return fresh result
 					// Use Promise.race to detect if session completes during wait
@@ -653,7 +669,7 @@ Examples:
 								};
 							}
 							const earlyResult = earlySession.getResult();
-							const { output, truncated, totalBytes } = earlySession.getOutput(true); // skipRateLimit
+							const { output, truncated, totalBytes } = earlySession.getOutput({ skipRateLimit: true, lines: outputLines, maxChars: outputMaxChars });
 							const earlyStatus = earlySession.getStatus();
 							const earlyRuntime = earlySession.getRuntime();
 							const truncatedNote = truncated ? ` (${totalBytes} bytes total, truncated)` : "";
@@ -702,7 +718,7 @@ Examples:
 							};
 						}
 						// Get fresh output after waiting
-						const freshOutput = session.getOutput();
+						const freshOutput = session.getOutput({ lines: outputLines, maxChars: outputMaxChars });
 						const truncatedNote = freshOutput.truncated ? ` (${freshOutput.totalBytes} bytes total, truncated)` : "";
 						const hasOutput = freshOutput.output.length > 0;
 						const freshStatus = session.getStatus();

package/overlay-component.ts

@@ -98,6 +98,8 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private dialogSelection: DialogChoice = "background";
 	private exitCountdown = 0;
 	private lastEscapeTime = 0;
+	private showEscapeHint = false;
+	private escapeHintTimeout: ReturnType<typeof setTimeout> | null = null;
 	private countdownInterval: ReturnType<typeof setInterval> | null = null;
 	private lastWidth = 0;
 	private lastHeight = 0;
@@ -128,6 +130,8 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private lastQueryTime = 0;
 	// Completion callbacks for waiters
 	private completeCallbacks: Array<() => void> = [];
+	// Simple render throttle to reduce flicker
+	private renderTimeout: ReturnType<typeof setTimeout> | null = null;
 
 	constructor(
 		tui: TUI,
@@ -158,10 +162,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			},
 			{
 				onData: () => {
-					if (!this.session.isScrolledUp()) {
-						this.session.scrollToBottom();
-					}
-					this.tui.requestRender();
+					// Don't call scrollToBottom() here - pty-session handles auto-follow at render time
+					// Debounce render to batch rapid updates and reduce flicker
+					this.debouncedRender();
 
 					// Track activity for on-quiet mode
 					if (this.state === "hands-free" && this.updateMode === "on-quiet") {
@@ -225,7 +228,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				reason: options.reason,
 				write: (data) => this.session.write(data),
 				kill: () => this.killSession(),
-				getOutput: (skipRateLimit) => this.getOutputSinceLastCheck(skipRateLimit),
+				getOutput: (options) => this.getOutputSinceLastCheck(options),
 				getStatus: () => this.getSessionStatus(),
 				getRuntime: () => this.getRuntime(),
 				getResult: () => this.getCompletionResult(),
@@ -246,13 +249,27 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 	// Public methods for non-blocking mode (agent queries)
 
-	// Max output per status query (5KB) - prevents overwhelming agent context
-	private static readonly MAX_STATUS_OUTPUT = 5 * 1024;
-	// Max lines to return per query - keep small, we're just checking in
-	private static readonly MAX_STATUS_LINES = 20;
+	// Default output limits per status query
+	private static readonly DEFAULT_STATUS_OUTPUT = 5 * 1024; // 5KB
+	private static readonly DEFAULT_STATUS_LINES = 20;
+	private static readonly MAX_STATUS_OUTPUT = 50 * 1024; // 50KB max
+	private static readonly MAX_STATUS_LINES = 200; // 200 lines max
 
 	/** Get rendered terminal output (last N lines, truncated if too large) */
-	getOutputSinceLastCheck(skipRateLimit = false): { output: string; truncated: boolean; totalBytes: number; rateLimited?: boolean; waitSeconds?: number } {
+	getOutputSinceLastCheck(options: { skipRateLimit?: boolean; lines?: number; maxChars?: number } | boolean = false): { output: string; truncated: boolean; totalBytes: number; rateLimited?: boolean; waitSeconds?: number } {
+		// Handle legacy boolean parameter
+		const opts = typeof options === "boolean" ? { skipRateLimit: options } : options;
+		const skipRateLimit = opts.skipRateLimit ?? false;
+		// Clamp lines and maxChars to valid ranges (1 to MAX)
+		const requestedLines = Math.max(1, Math.min(
+			opts.lines ?? InteractiveShellOverlay.DEFAULT_STATUS_LINES,
+			InteractiveShellOverlay.MAX_STATUS_LINES
+		));
+		const requestedMaxChars = Math.max(1, Math.min(
+			opts.maxChars ?? InteractiveShellOverlay.DEFAULT_STATUS_OUTPUT,
+			InteractiveShellOverlay.MAX_STATUS_OUTPUT
+		));
+
 		// Check rate limiting (unless skipped, e.g., for completed sessions)
 		if (!skipRateLimit) {
 			const now = Date.now();
@@ -277,14 +294,14 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		// Use rendered terminal output instead of raw stream
 		// This gives clean, readable content without TUI animation garbage
 		const lines = this.session.getTailLines({
-			lines: InteractiveShellOverlay.MAX_STATUS_LINES,
+			lines: requestedLines,
 			ansi: false,
-			maxChars: InteractiveShellOverlay.MAX_STATUS_OUTPUT,
+			maxChars: requestedMaxChars,
 		});
 
 		const output = lines.join("\n");
 		const totalBytes = output.length;
-		const truncated = lines.length >= InteractiveShellOverlay.MAX_STATUS_LINES;
+		const truncated = lines.length >= requestedLines;
 
 		return { output, truncated, totalBytes };
 	}
@@ -334,6 +351,18 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.completeCallbacks = [];
 	}
 
+	/** Debounced render - waits for data to settle before rendering */
+	private debouncedRender(): void {
+		if (this.renderTimeout) {
+			clearTimeout(this.renderTimeout);
+		}
+		// Wait 16ms for more data before rendering
+		this.renderTimeout = setTimeout(() => {
+			this.renderTimeout = null;
+			this.tui.requestRender();
+		}, 16);
+	}
+
 	/** Get the session ID */
 	getSessionId(): string | null {
 		return this.sessionId;
@@ -813,12 +842,31 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const now = Date.now();
 		if (now - this.lastEscapeTime < this.config.doubleEscapeThreshold) {
 			this.lastEscapeTime = 0;
+			this.clearEscapeHint();
 			return true;
 		}
 		this.lastEscapeTime = now;
+		// Show hint after first escape - clear any existing timeout first
+		if (this.escapeHintTimeout) {
+			clearTimeout(this.escapeHintTimeout);
+		}
+		this.showEscapeHint = true;
+		this.escapeHintTimeout = setTimeout(() => {
+			this.showEscapeHint = false;
+			this.tui.requestRender();
+		}, this.config.doubleEscapeThreshold);
+		this.tui.requestRender();
 		return false;
 	}
 
+	private clearEscapeHint(): void {
+		if (this.escapeHintTimeout) {
+			clearTimeout(this.escapeHintTimeout);
+			this.escapeHintTimeout = null;
+		}
+		this.showEscapeHint = false;
+	}
+
 	handleInput(data: string): void {
 		if (this.state === "detach-dialog") {
 			this.handleDialogInput(data);
@@ -953,6 +1001,8 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			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 });
@@ -998,9 +1048,17 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			footerLines.push(row(exitMsg));
 			footerLines.push(row(dim(`Closing in ${this.exitCountdown}s... (any key to close)`)));
 		} else if (this.state === "hands-free") {
-			footerLines.push(row(dim("🤖 Agent controlling • Type to take over • Shift+Up/Down scroll")));
+			if (this.showEscapeHint) {
+				footerLines.push(row(warning("Press Escape again to detach...")));
+			} else {
+				footerLines.push(row(dim("🤖 Agent controlling • Type to take over • Shift+Up/Down scroll")));
+			}
 		} else {
-			footerLines.push(row(dim("Shift+Up/Down scroll • Double-Esc detach • Ctrl+C interrupt")));
+			if (this.showEscapeHint) {
+				footerLines.push(row(warning("Press Escape again to detach...")));
+			} else {
+				footerLines.push(row(dim("Shift+Up/Down scroll • Double-Esc detach • Ctrl+C interrupt")));
+			}
 		}
 
 		while (footerLines.length < FOOTER_LINES) {
@@ -1022,6 +1080,11 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.stopCountdown();
 		this.stopTimeout();
 		this.stopHandsFreeUpdates();
+		this.clearEscapeHint();
+		if (this.renderTimeout) {
+			clearTimeout(this.renderTimeout);
+			this.renderTimeout = null;
+		}
 		// Safety cleanup in case dispose() is called without going through finishWith*
 		// If session hasn't completed yet, kill it to prevent orphaned processes
 		if (!this.completionResult) {
@@ -1368,6 +1431,8 @@ export class ReattachOverlay implements Component, Focusable {
 			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 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-interactive-shell",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Run AI coding agents as foreground subagents in pi TUI overlays with hands-free monitoring",
   "type": "module",
   "bin": {

package/pty-session.ts

@@ -218,6 +218,7 @@ export class PtyTerminalSession {
 	private _exitCode: number | null = null;
 	private _signal: number | undefined;
 	private scrollOffset = 0;
+	private followBottom = true; // Auto-scroll to bottom when new data arrives
 
 	// Raw output buffer for incremental streaming
 	private rawOutput = "";
@@ -458,6 +459,11 @@ export class PtyTerminalSession {
 		const lines: string[] = [];
 
 		const totalLines = buffer.length;
+		// If following bottom, reset scroll offset at render time (not on each data event)
+		// This prevents flickering from scroll position racing with buffer updates
+		if (this.followBottom) {
+			this.scrollOffset = 0;
+		}
 		const viewportStart = Math.max(0, totalLines - this.xterm.rows - this.scrollOffset);
 
 		const useAnsi = !!options.ansi;
@@ -565,14 +571,20 @@ export class PtyTerminalSession {
 		const buffer = this.xterm.buffer.active;
 		const maxScroll = Math.max(0, buffer.length - this.xterm.rows);
 		this.scrollOffset = Math.min(this.scrollOffset + lines, maxScroll);
+		this.followBottom = false; // User scrolled up, stop auto-following
 	}
 
 	scrollDown(lines: number): void {
 		this.scrollOffset = Math.max(0, this.scrollOffset - lines);
+		// If scrolled to bottom, resume auto-following
+		if (this.scrollOffset === 0) {
+			this.followBottom = true;
+		}
 	}
 
 	scrollToBottom(): void {
 		this.scrollOffset = 0;
+		this.followBottom = true;
 	}
 
 	isScrolledUp(): boolean {

package/session-manager.ts

@@ -29,13 +29,19 @@ export interface OutputResult {
 	waitSeconds?: number;
 }
 
+export interface OutputOptions {
+	skipRateLimit?: boolean;
+	lines?: number; // Override default 20 lines
+	maxChars?: number; // Override default 5KB
+}
+
 export interface ActiveSession {
 	id: string;
 	command: string;
 	reason?: string;
 	write: (data: string) => void;
 	kill: () => void;
-	getOutput: (skipRateLimit?: boolean) => OutputResult; // Get output since last check (truncated if large)
+	getOutput: (options?: OutputOptions | boolean) => OutputResult; // Get output since last check (truncated if large)
 	getStatus: () => ActiveSessionStatus;
 	getRuntime: () => number;
 	getResult: () => ActiveSessionResult | undefined; // Available when completed