pi-interactive-shell 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to the `pi-interactive-shell` extension will be documented i
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-01-27
+
+### Added
+- **Transfer output to agent (Ctrl+T)** - New action to capture subagent output and send it directly to the main agent. When a subagent finishes work, press Ctrl+T to close the overlay and transfer the output as primary content (not buried in details). The main agent immediately has the subagent's response in context.
+- **Transfer option in Ctrl+Q menu** - "Transfer output to agent" is now the first option in the session menu, making it the default selection.
+- **Configurable transfer settings** - `transferLines` (default: 200, range: 10-1000) and `transferMaxChars` (default: 20KB, range: 1KB-100KB) control how much output is captured.
+
+### Changed
+- **Ctrl+Q menu redesigned** - Options are now: Transfer output → Run in background → Kill process → Cancel. Transfer is the default selection since it's the most common action when a subagent finishes.
+- **Footer hints updated** - Now shows "Ctrl+T transfer • Ctrl+Q menu" for discoverability.
+
+## [0.5.3] - 2026-01-26
+
 ### Changed
 - Added `pi-package` keyword for npm discoverability (pi v0.50.0 package system)
 

package/README.md

@@ -132,6 +132,24 @@ interactive_shell({ sessionId: "calm-reef", outputLines: 50, incremental: true }
 interactive_shell({ sessionId: "calm-reef", drain: true })
 ```
 
+### Transfer Output to Agent
+
+When a subagent finishes work, press **Ctrl+T** to capture its output and send it directly to the main agent:
+
+```
+[Subagent finishes work]
+        ↓
+[Press Ctrl+T]
+        ↓
+[Overlay closes, main agent receives full output]
+```
+
+The main agent then has the subagent's response in context and can continue working with that information.
+
+**Configuration:**
+- `transferLines`: Max lines to capture (default: 200)
+- `transferMaxChars`: Max characters (default: 20KB)
+
 ### Background Sessions
 
 1. Ctrl+Q → "Run in background"
@@ -141,7 +159,8 @@ interactive_shell({ sessionId: "calm-reef", drain: true })
 
 | Key | Action |
 |-----|--------|
-| Ctrl+Q | Detach dialog |
+| Ctrl+T | **Transfer & close** - capture output and send to main agent |
+| Ctrl+Q | Session menu (transfer/background/kill/cancel) |
 | Shift+Up/Down | Scroll history |
 | Any key (hands-free) | Take over control |
 
@@ -158,6 +177,8 @@ Configuration files (project overrides global):
   "scrollbackLines": 5000,
   "exitAutoCloseDelay": 10,
   "minQueryIntervalSeconds": 60,
+  "transferLines": 200,
+  "transferMaxChars": 20000,
   "handsFreeUpdateMode": "on-quiet",
   "handsFreeUpdateInterval": 60000,
   "handsFreeQuietThreshold": 5000,
@@ -178,6 +199,8 @@ Configuration files (project overrides global):
 | `scrollbackLines` | 5000 | Terminal scrollback buffer |
 | `exitAutoCloseDelay` | 10 | Seconds before auto-close after exit |
 | `minQueryIntervalSeconds` | 60 | Rate limit between agent queries |
+| `transferLines` | 200 | Lines to capture on Ctrl+T transfer (10-1000) |
+| `transferMaxChars` | 20000 | Max chars for transfer (1KB-100KB) |
 | `handsFreeUpdateMode` | "on-quiet" | "on-quiet" or "interval" |
 | `handsFreeQuietThreshold` | 5000 | Silence duration before update (ms) |
 | `handsFreeUpdateInterval` | 60000 | Max interval between updates (ms) |

package/SKILL.md

@@ -340,6 +340,26 @@ interactive_shell({ command: 'claude "Review the codebase"', reason: 'Code revie
 
 ## Handoff Options
 
+### Transfer (Ctrl+T) - Recommended
+When the subagent finishes, the user presses **Ctrl+T** to transfer output directly to you:
+
+```
+[Subagent finishes work in overlay]
+        ↓
+[User presses Ctrl+T]
+        ↓
+[You receive: "Session output transferred (150 lines):
+  
+  Completing skill integration...
+  Modified files:
+  - skills.ts
+  - agents/types/..."]
+```
+
+This is the cleanest workflow - the subagent's response becomes your context automatically.
+
+**Configuration:** `transferLines` (default: 200), `transferMaxChars` (default: 20KB)
+
 ### Tail Preview (default)
 Last 30 lines included in tool result. Good for seeing errors/final status.
 
@@ -352,7 +372,7 @@ interactive_shell({
 })
 ```
 
-### Artifact Handoff (recommended for complex tasks)
+### Artifact Handoff (for complex tasks)
 Instruct the delegated agent to write a handoff file:
 ```
 Write your findings to .pi/delegation/claude-handoff.md including:

package/config.ts

@@ -14,6 +14,9 @@ export interface InteractiveShellConfig {
 	handoffSnapshotEnabled: boolean;
 	handoffSnapshotLines: number;
 	handoffSnapshotMaxChars: number;
+	// Transfer output settings (Ctrl+T)
+	transferLines: number;
+	transferMaxChars: number;
 	// Hands-free mode defaults
 	handsFreeUpdateMode: "on-quiet" | "interval";
 	handsFreeUpdateInterval: number;
@@ -36,6 +39,9 @@ const DEFAULT_CONFIG: InteractiveShellConfig = {
 	handoffSnapshotEnabled: false,
 	handoffSnapshotLines: 200,
 	handoffSnapshotMaxChars: 12000,
+	// Transfer output settings (Ctrl+T) - generous defaults for full context transfer
+	transferLines: 200,
+	transferMaxChars: 20000,
 	// Hands-free mode defaults
 	handsFreeUpdateMode: "on-quiet" as const,
 	handsFreeUpdateInterval: 60000,
@@ -94,6 +100,9 @@ export function loadConfig(cwd: string): InteractiveShellConfig {
 			0,
 			200000,
 		),
+		// Transfer output settings (Ctrl+T)
+		transferLines: clampInt(merged.transferLines, DEFAULT_CONFIG.transferLines, 10, 1000),
+		transferMaxChars: clampInt(merged.transferMaxChars, DEFAULT_CONFIG.transferMaxChars, 1000, 100000),
 		// Hands-free mode
 		handsFreeUpdateMode: merged.handsFreeUpdateMode === "interval" ? "interval" : "on-quiet",
 		handsFreeUpdateInterval: clampInt(

package/index.ts

@@ -557,7 +557,13 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 			}
 
 			let summary: string;
-			if (result.backgrounded) {
+			if (result.transferred) {
+				// User triggered "Transfer" action - output is the primary content
+				const truncatedNote = result.transferred.truncated
+					? ` (truncated from ${result.transferred.totalLines} total lines)`
+					: "";
+				summary = `Session output transferred (${result.transferred.lines.length} lines${truncatedNote}):\n\n${result.transferred.lines.join("\n")}`;
+			} else if (result.backgrounded) {
 				summary = `Session running in background (id: ${result.backgroundId}). User can reattach with /attach ${result.backgroundId}`;
 			} else if (result.cancelled) {
 				summary = "User killed the interactive session";
@@ -577,7 +583,8 @@ export default function interactiveShellExtension(pi: ExtensionAPI) {
 				summary += `\n\n${warning}`;
 			}
 
-			if (result.handoffPreview?.type === "tail" && result.handoffPreview.lines.length > 0) {
+			// Only include handoff preview if not already transferring (transfer includes full output)
+			if (!result.transferred && result.handoffPreview?.type === "tail" && result.handoffPreview.lines.length > 0) {
 				const tailHeader = `\n\nOverlay tail (${result.handoffPreview.when}, last ${result.handoffPreview.lines.length} lines):\n`;
 				summary += tailHeader + result.handoffPreview.lines.join("\n");
 			}

package/overlay-component.ts

@@ -29,7 +29,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 	private config: InteractiveShellConfig;
 
 	private state: OverlayState = "running";
-	private dialogSelection: DialogChoice = "background";
+	private dialogSelection: DialogChoice = "transfer";
 	private exitCountdown = 0;
 	private countdownInterval: ReturnType<typeof setInterval> | null = null;
 	private lastWidth = 0;
@@ -611,7 +611,43 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.tui.requestRender();
 	}
 
-	private maybeBuildHandoffPreview(when: "exit" | "detach" | "kill" | "timeout"): InteractiveShellResult["handoffPreview"] | undefined {
+	/** Capture output for transfer action (Ctrl+T or dialog) */
+	private captureTransferOutput(): InteractiveShellResult["transferred"] {
+		const maxLines = this.config.transferLines;
+		const maxChars = this.config.transferMaxChars;
+
+		// Use raw output stream for clean content
+		const rawOutput = this.session.getRawStream({ stripAnsi: true });
+		if (!rawOutput) {
+			return { lines: [], totalLines: 0, truncated: false };
+		}
+
+		const allLines = rawOutput.split("\n");
+		const totalLines = allLines.length;
+
+		// Get last N lines, respecting maxChars
+		let capturedLines: string[] = [];
+		let charCount = 0;
+		let truncated = false;
+
+		for (let i = allLines.length - 1; i >= 0 && capturedLines.length < maxLines; i--) {
+			const line = allLines[i]!;
+			if (charCount + line.length > maxChars && capturedLines.length > 0) {
+				truncated = true;
+				break;
+			}
+			capturedLines.unshift(line);
+			charCount += line.length + 1; // +1 for newline
+		}
+
+		if (capturedLines.length < totalLines) {
+			truncated = true;
+		}
+
+		return { lines: capturedLines, totalLines, truncated };
+	}
+
+	private maybeBuildHandoffPreview(when: "exit" | "detach" | "kill" | "timeout" | "transfer"): InteractiveShellResult["handoffPreview"] | undefined {
 		const enabled = this.options.handoffPreviewEnabled ?? this.config.handoffPreviewEnabled;
 		if (!enabled) return undefined;
 
@@ -639,7 +675,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		return { type: "tail", when, lines: tail };
 	}
 
-	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill" | "timeout"): InteractiveShellResult["handoff"] | undefined {
+	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill" | "timeout" | "transfer"): InteractiveShellResult["handoff"] | undefined {
 		const enabled = this.options.handoffSnapshotEnabled ?? this.config.handoffSnapshotEnabled;
 		if (!enabled) return undefined;
 
@@ -775,6 +811,43 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		this.done(result);
 	}
 
+	private finishWithTransfer(): void {
+		if (this.finished) return;
+		this.finished = true;
+		this.stopCountdown();
+		this.stopTimeout();
+		this.stopHandsFreeUpdates();
+
+		// Capture output BEFORE killing the session
+		const transferred = this.captureTransferOutput();
+		const handoffPreview = this.maybeBuildHandoffPreview("transfer");
+		const handoff = this.maybeWriteHandoffSnapshot("transfer");
+
+		this.session.kill();
+		this.session.dispose();
+		const result: InteractiveShellResult = {
+			exitCode: this.session.exitCode,
+			signal: this.session.signal,
+			backgrounded: false,
+			cancelled: false,
+			sessionId: this.sessionId ?? undefined,
+			userTookOver: this.userTookOver,
+			transferred,
+			handoffPreview,
+			handoff,
+		};
+		this.completionResult = result;
+		this.triggerCompleteCallbacks();
+
+		// In non-blocking mode (no onHandsFreeUpdate), keep session registered
+		// so agent can query completion result. Agent's query will unregister.
+		if (this.options.onHandsFreeUpdate) {
+			this.unregisterActiveSession(true);
+		}
+
+		this.done(result);
+	}
+
 	private finishWithTimeout(): void {
 		if (this.finished) return;
 		this.finished = true;
@@ -834,6 +907,16 @@ export class InteractiveShellOverlay implements Component, Focusable {
 			return;
 		}
 
+		// Ctrl+T: Quick transfer - capture output and close (works in all states including "exited")
+		if (matchesKey(data, "ctrl+t")) {
+			// If in hands-free mode, trigger takeover first (notifies agent)
+			if (this.state === "hands-free") {
+				this.triggerUserTakeover();
+			}
+			this.finishWithTransfer();
+			return;
+		}
+
 		if (this.state === "exited") {
 			if (data.length > 0) {
 				this.finishWithExit();
@@ -848,7 +931,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 				this.triggerUserTakeover();
 			}
 			this.state = "detach-dialog";
-			this.dialogSelection = "background";
+			this.dialogSelection = "transfer";
 			this.tui.requestRender();
 			return;
 		}
@@ -882,7 +965,7 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		}
 
 		if (matchesKey(data, "up") || matchesKey(data, "down")) {
-			const options: DialogChoice[] = ["kill", "background", "cancel"];
+			const options: DialogChoice[] = ["transfer", "background", "kill", "cancel"];
 			const currentIdx = options.indexOf(this.dialogSelection);
 			const direction = matchesKey(data, "up") ? -1 : 1;
 			const newIdx = (currentIdx + direction + options.length) % options.length;
@@ -893,6 +976,9 @@ export class InteractiveShellOverlay implements Component, Focusable {
 
 		if (matchesKey(data, "enter")) {
 			switch (this.dialogSelection) {
+				case "transfer":
+					this.finishWithTransfer();
+					break;
 				case "kill":
 					this.finishWithKill();
 					break;
@@ -989,10 +1075,11 @@ export class InteractiveShellOverlay implements Component, Focusable {
 		const footerLines: string[] = [];
 
 		if (this.state === "detach-dialog") {
-			footerLines.push(row(accent("Detach from session:")));
+			footerLines.push(row(accent("Session actions:")));
 			const opts: Array<{ key: DialogChoice; label: string }> = [
-				{ key: "kill", label: "Kill process" },
+				{ key: "transfer", label: "Transfer output to agent" },
 				{ key: "background", label: "Run in background" },
+				{ key: "kill", label: "Kill process" },
 				{ key: "cancel", label: "Cancel (return to session)" },
 			];
 			for (const opt of opts) {
@@ -1008,9 +1095,9 @@ 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")));
+			footerLines.push(row(dim("🤖 Agent controlling • Type to take over • Ctrl+T transfer • Shift+Up/Down scroll")));
 		} else {
-			footerLines.push(row(dim("Shift+Up/Down scroll • Ctrl+Q detach • Ctrl+C interrupt")));
+			footerLines.push(row(dim("Ctrl+T transfer • Ctrl+Q menu • Shift+Up/Down scroll")));
 		}
 
 		while (footerLines.length < FOOTER_LINES) {

package/package.json

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

package/reattach-overlay.ts

@@ -25,7 +25,7 @@ export class ReattachOverlay implements Component, Focusable {
 	private config: InteractiveShellConfig;
 
 	private state: OverlayState = "running";
-	private dialogSelection: DialogChoice = "background";
+	private dialogSelection: DialogChoice = "transfer";
 	private exitCountdown = 0;
 	private countdownInterval: ReturnType<typeof setInterval> | null = null;
 	private initialExitTimeout: ReturnType<typeof setTimeout> | null = null;
@@ -101,7 +101,43 @@ export class ReattachOverlay implements Component, Focusable {
 		}
 	}
 
-	private maybeBuildHandoffPreview(when: "exit" | "detach" | "kill"): InteractiveShellResult["handoffPreview"] | undefined {
+	/** Capture output for transfer action (Ctrl+T or dialog) */
+	private captureTransferOutput(): InteractiveShellResult["transferred"] {
+		const maxLines = this.config.transferLines;
+		const maxChars = this.config.transferMaxChars;
+
+		// Use raw output stream for clean content
+		const rawOutput = this.session.getRawStream({ stripAnsi: true });
+		if (!rawOutput) {
+			return { lines: [], totalLines: 0, truncated: false };
+		}
+
+		const allLines = rawOutput.split("\n");
+		const totalLines = allLines.length;
+
+		// Get last N lines, respecting maxChars
+		let capturedLines: string[] = [];
+		let charCount = 0;
+		let truncated = false;
+
+		for (let i = allLines.length - 1; i >= 0 && capturedLines.length < maxLines; i--) {
+			const line = allLines[i]!;
+			if (charCount + line.length > maxChars && capturedLines.length > 0) {
+				truncated = true;
+				break;
+			}
+			capturedLines.unshift(line);
+			charCount += line.length + 1; // +1 for newline
+		}
+
+		if (capturedLines.length < totalLines) {
+			truncated = true;
+		}
+
+		return { lines: capturedLines, totalLines, truncated };
+	}
+
+	private maybeBuildHandoffPreview(when: "exit" | "detach" | "kill" | "transfer"): InteractiveShellResult["handoffPreview"] | undefined {
 		if (!this.config.handoffPreviewEnabled) return undefined;
 		const lines = this.config.handoffPreviewLines;
 		const maxChars = this.config.handoffPreviewMaxChars;
@@ -127,7 +163,7 @@ export class ReattachOverlay implements Component, Focusable {
 		return { type: "tail", when, lines: tail };
 	}
 
-	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill"): InteractiveShellResult["handoff"] | undefined {
+	private maybeWriteHandoffSnapshot(when: "exit" | "detach" | "kill" | "transfer"): InteractiveShellResult["handoff"] | undefined {
 		if (!this.config.handoffSnapshotEnabled) return undefined;
 		const lines = this.config.handoffSnapshotLines;
 		const maxChars = this.config.handoffSnapshotMaxChars;
@@ -213,12 +249,40 @@ export class ReattachOverlay implements Component, Focusable {
 		});
 	}
 
+	private finishWithTransfer(): void {
+		if (this.finished) return;
+		this.finished = true;
+		this.stopCountdown();
+
+		// Capture output BEFORE removing session
+		const transferred = this.captureTransferOutput();
+		const handoffPreview = this.maybeBuildHandoffPreview("transfer");
+		const handoff = this.maybeWriteHandoffSnapshot("transfer");
+
+		sessionManager.remove(this.bgSession.id);
+		this.done({
+			exitCode: this.session.exitCode,
+			signal: this.session.signal,
+			backgrounded: false,
+			cancelled: false,
+			transferred,
+			handoffPreview,
+			handoff,
+		});
+	}
+
 	handleInput(data: string): void {
 		if (this.state === "detach-dialog") {
 			this.handleDialogInput(data);
 			return;
 		}
 
+		// Ctrl+T: Quick transfer - capture output and close (works in all states including "exited")
+		if (matchesKey(data, "ctrl+t")) {
+			this.finishWithTransfer();
+			return;
+		}
+
 		if (this.state === "exited") {
 			if (data.length > 0) {
 				this.finishAndClose();
@@ -237,7 +301,7 @@ export class ReattachOverlay implements Component, Focusable {
 		// Ctrl+Q opens detach dialog
 		if (matchesKey(data, "ctrl+q")) {
 			this.state = "detach-dialog";
-			this.dialogSelection = "background";
+			this.dialogSelection = "transfer";
 			this.tui.requestRender();
 			return;
 		}
@@ -264,7 +328,7 @@ export class ReattachOverlay implements Component, Focusable {
 		}
 
 		if (matchesKey(data, "up") || matchesKey(data, "down")) {
-			const options: DialogChoice[] = ["kill", "background", "cancel"];
+			const options: DialogChoice[] = ["transfer", "background", "kill", "cancel"];
 			const currentIdx = options.indexOf(this.dialogSelection);
 			const direction = matchesKey(data, "up") ? -1 : 1;
 			const newIdx = (currentIdx + direction + options.length) % options.length;
@@ -275,6 +339,9 @@ export class ReattachOverlay implements Component, Focusable {
 
 		if (matchesKey(data, "enter")) {
 			switch (this.dialogSelection) {
+				case "transfer":
+					this.finishWithTransfer();
+					break;
 				case "kill":
 					this.finishWithKill();
 					break;
@@ -367,10 +434,11 @@ export class ReattachOverlay implements Component, Focusable {
 		const footerLines: string[] = [];
 
 		if (this.state === "detach-dialog") {
-			footerLines.push(row(accent("Detach from session:")));
+			footerLines.push(row(accent("Session actions:")));
 			const opts: Array<{ key: DialogChoice; label: string }> = [
-				{ key: "kill", label: "Kill process" },
+				{ key: "transfer", label: "Transfer output to agent" },
 				{ key: "background", label: "Run in background" },
+				{ key: "kill", label: "Kill process" },
 				{ key: "cancel", label: "Cancel (return to session)" },
 			];
 			for (const opt of opts) {
@@ -386,7 +454,7 @@ export class ReattachOverlay implements Component, Focusable {
 			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")));
+			footerLines.push(row(dim("Ctrl+T transfer • Ctrl+Q menu • Shift+Up/Down scroll")));
 		}
 
 		while (footerLines.length < FOOTER_LINES) {

package/tool-schema.ts

@@ -16,7 +16,8 @@ MODES:
 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
+- Transfer output to you (Ctrl+T) - closes overlay and sends output as your context
+- Detach (Ctrl+Q) for menu: transfer/background/kill
 - In hands-free mode: type anything to take over control
 
 HANDS-FREE MODE (NON-BLOCKING):

package/types.ts

@@ -11,14 +11,20 @@ export interface InteractiveShellResult {
 	timedOut?: boolean;
 	sessionId?: string;
 	userTookOver?: boolean;
+	/** When user triggers "Transfer" action, this contains the captured output */
+	transferred?: {
+		lines: string[];
+		totalLines: number;
+		truncated: boolean;
+	};
 	handoffPreview?: {
 		type: "tail";
-		when: "exit" | "detach" | "kill" | "timeout";
+		when: "exit" | "detach" | "kill" | "timeout" | "transfer";
 		lines: string[];
 	};
 	handoff?: {
 		type: "snapshot";
-		when: "exit" | "detach" | "kill" | "timeout";
+		when: "exit" | "detach" | "kill" | "timeout" | "transfer";
 		transcriptPath: string;
 		linesWritten: number;
 	};
@@ -62,11 +68,11 @@ export interface InteractiveShellOptions {
 	timeout?: number;
 }
 
-export type DialogChoice = "kill" | "background" | "cancel";
+export type DialogChoice = "kill" | "background" | "transfer" | "cancel";
 export type OverlayState = "running" | "exited" | "detach-dialog" | "hands-free";
 
 // UI constants
-export const FOOTER_LINES = 5;
+export const FOOTER_LINES = 6;
 export const HEADER_LINES = 4;
 export const CHROME_LINES = HEADER_LINES + FOOTER_LINES + 2;