pi-interactive-shell 0.4.2 → 0.4.4

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

@@ -1,17 +1,31 @@
-# Pi Interactive Shell Overlay
+# Pi Interactive Shell
 
-An extension for [pi-coding-agent](https://github.com/badlogic/pi-mono/) that runs AI coding agents (Claude Code, Gemini CLI, Codex, Aider, etc.) as **foreground subagents** inside a TUI overlay. The user sees the agent working in real-time and can take over control at any time.
+Pi can run any interactive CLI in a TUI overlay - including other AI agents. Drive Claude, Gemini, Codex, Cursor directly from Pi. Watch it work, take over anytime. Real PTY, full terminal emulation, no tmux needed.
 
-This is distinct from **background subagents** (the `subagent` tool) which run pi instances invisibly.
+```typescript
+interactive_shell({ command: 'agent "fix all the bugs"', mode: "hands-free" })
+// Returns immediately with sessionId
+// User watches in overlay, you query for status
+// Session auto-closes when agent finishes
+```
+
+## Why
+
+AI agents delegating to other AI agents is powerful but messy:
+
+- **Visibility** - What's the subagent doing? Is it stuck?
+- **Control** - User needs to intervene. How?
+- **Integration** - When does the parent agent check in?
+
+Interactive Shell solves all three:
 
-## Foreground vs Background Subagents
+**Real-Time Overlay** - User sees the subprocess in a TUI overlay. Full terminal emulation via xterm-headless. ANSI colors, cursor movement, everything.
 
-| | Foreground (`interactive_shell`) | Background (`subagent`) |
-|---|---|---|
-| **Visibility** | User sees overlay | Hidden |
-| **Agents** | Any CLI agent | Pi only |
-| **Output** | Incremental updates | Full capture |
-| **User control** | Can intervene | None |
+**Seamless Takeover** - Type anything to take control. Scroll with Shift+Up/Down. Double-Escape to detach.
+
+**Non-Blocking API** - Start a session, get a sessionId, query for status. Rate-limited to prevent spam. Auto-exits when output stops.
+
+**Any CLI** - Not just AI agents. Run `htop`, `vim`, `psql`, `ssh` - anything interactive.
 
 ## Install
 
@@ -19,147 +33,111 @@ This is distinct from **background subagents** (the `subagent` tool) which run p
 npx pi-interactive-shell
 ```
 
-This installs the extension to `~/.pi/agent/extensions/interactive-shell/`, runs `npm install` for dependencies, and creates the skill symlink.
+Installs to `~/.pi/agent/extensions/interactive-shell/`.
 
-**Requirements:** `node-pty` requires build tools (Xcode Command Line Tools on macOS).
+**Requires:** Node.js, build tools for `node-pty` (Xcode CLI tools on macOS).
 
-**Manual install:** If you prefer, clone/copy the files manually and run `npm install` in the extension directory.
+## Quick Start
 
-## Usage
+### Hands-Free (Agent-to-Agent)
 
-### Tool: `interactive_shell`
+```typescript
+// Start - returns immediately
+interactive_shell({
+  command: 'pi "Refactor the auth module"',
+  mode: "hands-free"
+})
+// → { sessionId: "calm-reef", status: "running" }
 
-**Start a new session:**
-- `command` (string, required): CLI agent command
-- `cwd` (string): working directory
-- `name` (string): session name (used in sessionId)
-- `reason` (string): shown in overlay header (UI-only, not passed to subprocess)
-- `mode` (string): `"interactive"` (default) or `"hands-free"`
-- `timeout` (number): auto-kill after N milliseconds (for TUI commands that don't exit)
-- `handsFree` (object): options for hands-free mode
-  - `updateMode` (string): `"on-quiet"` (default) or `"interval"`
-  - `updateInterval` (number): max ms between updates, fallback for on-quiet (default: 60000)
-  - `quietThreshold` (number): ms of silence before emitting update in on-quiet mode (default: 5000)
-  - `updateMaxChars` (number): max chars per update (default: 1500)
-  - `maxTotalChars` (number): total char budget for all updates (default: 100000)
-- `handoffPreview` (object): tail preview in tool result
-- `handoffSnapshot` (object): write transcript to file
+// Query status (rate-limited to 60s)
+interactive_shell({ sessionId: "calm-reef" })
+// → { status: "running", output: "...", runtime: 45000 }
 
-**Send input to active session:**
-- `sessionId` (string, required): session ID from hands-free updates
-- `input` (string | object): input to send
-  - As string: raw text/keystrokes (e.g., `"/model\n"`)
-  - As object: `{ text?, keys?, hex?, paste? }`
+// Get more output
+interactive_shell({ sessionId: "calm-reef", outputLines: 100 })
 
-**Change settings mid-session:**
-- `sessionId` (string, required): session ID
-- `settings` (object): `{ updateInterval?, quietThreshold? }`
+// Kill when done (or let autoExitOnQuiet handle it)
+interactive_shell({ sessionId: "calm-reef", kill: true })
+```
 
-### Command: `/attach`
+### Interactive (User Control)
 
-Reattach to background sessions:
+```typescript
+interactive_shell({ command: 'vim package.json' })
 ```
-/attach
-/attach <id>
+
+### Send Input
+
+```typescript
+interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
+interactive_shell({ sessionId: "calm-reef", input: { keys: ["ctrl+c"] } })
+interactive_shell({ sessionId: "calm-reef", input: { keys: ["down", "down", "enter"] } })
 ```
 
-## Modes
+## CLI Reference
 
-### Interactive (default)
+| Agent | Interactive | With Prompt | Headless (use 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"` |
 
-User supervises and controls the session directly.
+## Features
 
-```typescript
-interactive_shell({ command: 'pi "Review this code"' })
-```
+### Auto-Exit on Quiet
 
-### Hands-Free (Foreground Subagent)
+Sessions auto-close after 5s of silence. Disable with `handsFree: { autoExitOnQuiet: false }`.
 
-Agent monitors with periodic updates. User sees the overlay and can take over by typing. **Default to `pi`** unless user requests a different agent.
+### Timeout for TUI Capture
 
 ```typescript
 interactive_shell({
-  command: 'pi "Fix all lint errors in src/"',
+  command: "pi --help",
   mode: "hands-free",
-  reason: "Fixing lint errors"
+  timeout: 5000  // Kill after 5s, return captured output
 })
 ```
 
-**Update modes:**
-- `on-quiet` (default): Emit update after 5s of output silence. Perfect for agent-to-agent delegation.
-- `interval`: Emit on fixed schedule (every 60s). Use when continuous output is expected.
-
-**Context budget:**
-- Updates include only NEW output since last update (incremental)
-- Default: 1500 chars per update, 100KB total budget
-- When budget exhausted, updates continue but without content
-
-**Status updates (all include `sessionId`):**
-- Initial update - sent immediately when session starts
-- `status: "running"` - incremental output
-- `status: "user-takeover"` - user typed something
-- `status: "exited"` - process finished
-
-### Sending Input to Active Sessions
-
-Use `sessionId` from updates to send input:
+### Configurable Output
 
 ```typescript
-// Text input
-interactive_shell({ sessionId: "calm-reef", input: "/help\n" })
-
-// Named keys
-interactive_shell({ sessionId: "calm-reef", input: { text: "/model", keys: ["enter"] } })
+// Default: 20 lines, 5KB
+interactive_shell({ sessionId: "calm-reef" })
 
-// Navigate menus
-interactive_shell({ sessionId: "calm-reef", input: { keys: ["down", "down", "enter"] } })
-
-// Hex bytes for raw escape sequences
-interactive_shell({ sessionId: "calm-reef", input: { hex: ["0x1b", "0x5b", "0x41"] } })
+// More lines (max: 200)
+interactive_shell({ sessionId: "calm-reef", outputLines: 100 })
 
-// Bracketed paste (prevents auto-execution)
-interactive_shell({ sessionId: "calm-reef", input: { paste: "multi\nline\ntext" } })
+// More content (max: 50KB)
+interactive_shell({ sessionId: "calm-reef", outputMaxChars: 30000 })
 ```
 
-**Named keys:** `up`, `down`, `left`, `right`, `enter`, `escape`, `tab`, `backspace`, `delete`, `home`, `end`, `pageup`, `pagedown`, `f1`-`f12`, `ctrl+c`, `ctrl+d`, etc.
-
-**Keypad keys:** `kp0`-`kp9`, `kp/`, `kp*`, `kp-`, `kp+`, `kp.`, `kpenter`
+### Input Methods
 
-**tmux-style aliases:** `ppage`/`npage` (PageUp/PageDown), `ic`/`dc` (Insert/Delete), `bspace` (Backspace), `btab` (Shift+Tab)
+| Method | Example |
+|--------|---------|
+| Text | `input: "/model\n"` |
+| Keys | `input: { keys: ["enter", "ctrl+c"] }` |
+| Hex | `input: { hex: ["0x1b", "0x5b", "0x41"] }` |
+| Paste | `input: { paste: "multi\nline" }` |
 
-**Modifiers:** `ctrl+x`, `alt+x`, `shift+tab`, `ctrl+alt+delete` (or shorthand: `c-x`, `m-x`, `s-tab`)
+### Background Sessions
 
-### Change Settings Mid-Session
-
-```typescript
-interactive_shell({ sessionId: "calm-reef", settings: { updateInterval: 30000 } })
-interactive_shell({ sessionId: "calm-reef", settings: { quietThreshold: 3000 } })
-```
+1. Double-Escape → "Run in background"
+2. `/attach` or `/attach <id>` to reattach
 
 ## Config
 
-Global: `~/.pi/agent/interactive-shell.json`
-Project: `<cwd>/.pi/interactive-shell.json`
+`~/.pi/agent/interactive-shell.json`
 
 ```json
 {
-  "doubleEscapeThreshold": 300,
-  "exitAutoCloseDelay": 10,
-  "overlayWidthPercent": 95,
   "overlayHeightPercent": 45,
+  "overlayWidthPercent": 95,
   "scrollbackLines": 5000,
-  "ansiReemit": true,
-  "handoffPreviewEnabled": true,
-  "handoffPreviewLines": 30,
-  "handoffPreviewMaxChars": 2000,
-  "handoffSnapshotEnabled": false,
-  "handoffSnapshotLines": 200,
-  "handoffSnapshotMaxChars": 12000,
-  "handsFreeUpdateMode": "on-quiet",
-  "handsFreeUpdateInterval": 60000,
-  "handsFreeQuietThreshold": 5000,
-  "handsFreeUpdateMaxChars": 1500,
-  "handsFreeMaxTotalChars": 100000
+  "minQueryIntervalSeconds": 60,
+  "handsFreeQuietThreshold": 5000
 }
 ```
 
@@ -167,7 +145,24 @@ Project: `<cwd>/.pi/interactive-shell.json`
 
 | Key | Action |
 |-----|--------|
-| `Esc` twice | Detach dialog (kill/background/cancel) |
-| `Shift+Up/Down` | Scroll (no takeover in hands-free) |
-| `Ctrl+C` | Forwarded to subprocess |
-| Any other key (hands-free) | Triggers user takeover |
+| Double-Escape | Detach dialog |
+| Shift+Up/Down | Scroll history |
+| Any key (hands-free) | Take over control |
+
+## How It Works
+
+```
+interactive_shell → node-pty → subprocess
+                  ↓
+            xterm-headless (terminal emulation)
+                  ↓
+            TUI overlay (pi rendering)
+```
+
+Full PTY. The subprocess thinks it's in a real terminal.
+
+## Limitations
+
+- macOS tested, Linux experimental
+- 60s rate limit between queries (configurable)
+- Some TUI apps may have rendering quirks

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.4",
   "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