feat(btw): retain native side sessions

packages/coding-agent/CHANGELOG.md

@@ -10,6 +10,10 @@
 
 ### Added
 
+- Retained multi-session `/btw` TUI with native transcripts, a Main/numbered-side/New picker,
+  configurable `Ctrl+/`, `Ctrl+_`, and `Ctrl+7` switching, idle Escape-Escape return, and
+  current-side Ctrl+C deletion; non-TUI side queries remain one-shot and parallel.
+
 ### Changed
 
 ### Removed

packages/coding-agent/src/changes.md

@@ -1,5 +1,39 @@
 # changes
 
+## 2026-08-23 - retained BTW sessions and configurable switch routing
+
+### What changed
+
+- The builtin BTW TUI path creates separate retained host sessions and uses native session
+  selection/transcripts instead of the one-shot widget.
+- The fresh replacement context applies a retained side's captured model and thinking level before
+  its first turn. A typed `newSession` policy capability persists the tool ban without crossing the
+  extension/core boundary, forces later extension startup to keep the active set empty, and blocks
+  Cursor exec registered-tool lookup. Final payload enforcement strips provider-native tools after
+  every extension transform.
+- Main-side context snapshots follow Main's selected tree leaf rather than the file's physical
+  tail; retained siblings inherit that persisted leaf, and an oversized newest message is
+  truncated instead of emptying the snapshot. Creation waits for Main to settle before reloading
+  the catalog and snapshotting.
+- Session tool policy is enforced at `ExtensionRunner`'s final payload boundary, covering normal,
+  compaction, and cache-keepalive provider requests after all extension transforms.
+- Extension command contexts expose typed session listing/inspection. `newSession` can opt into
+  flushing initialized metadata before returning, which keeps empty retained sides durable without
+  crossing the extension/core boundary.
+- `app.btw.switch` adds Ctrl+/, Ctrl+_, and Ctrl+7 defaults.
+- Interactive extension UI exposes active key matching and effective-key lookup for configurable
+  terminal routing and visible fallback hints.
+
+### Why
+
+- Side conversations need durable identity, host scrolling, reliable return/close behavior, and a
+  fallback when an editor such as Zed reserves Ctrl+/ before the terminal receives it.
+
+### Expected merge-conflict zones
+
+- MEDIUM: builtin BTW wiring and keybinding definitions.
+- LOW: extension UI context and interactive implementation.
+
 ## 2026-08-22 - emit agent_idle after settlement-deferred turns resolve
 
 ### What changed

packages/coding-agent/src/core/agent-session-runtime.ts

@@ -8,11 +8,13 @@ import type {
 	ReplacedSessionContext,
 	SessionShutdownEvent,
 	SessionStartEvent,
+	SessionToolPolicy,
 } from "./extensions/index.ts";
 import { type ExtensionRunner, emitSessionShutdownEvent } from "./extensions/runner.ts";
 import type { CreateAgentSessionResult } from "./sdk.ts";
 import { assertSessionCwdExists } from "./session-cwd.ts";
 import { SessionManager } from "./session-manager.ts";
+import { SESSION_TOOL_POLICY_ENTRY_TYPE } from "./session-tool-policy.ts";
 
 /**
  * Result returned by runtime creation.
@@ -270,6 +272,8 @@ export class AgentSessionRuntime {
 
 	async newSession(options?: {
 		parentSession?: string;
+		persistInitializedSession?: boolean;
+		sessionToolPolicy?: SessionToolPolicy;
 		setup?: (sessionManager: SessionManager) => Promise<void>;
 		withSession?: (ctx: ReplacedSessionContext) => Promise<void>;
 	}): Promise<{ cancelled: boolean }> {
@@ -286,6 +290,9 @@ export class AgentSessionRuntime {
 		if (options?.parentSession) {
 			sessionManager.newSession({ parentSession: options.parentSession });
 		}
+		if (options?.sessionToolPolicy) {
+			sessionManager.appendCustomEntry(SESSION_TOOL_POLICY_ENTRY_TYPE, options.sessionToolPolicy);
+		}
 
 		await this.teardownCurrent("new", sessionManager.getSessionFile());
 		await this.apply(
@@ -301,6 +308,9 @@ export class AgentSessionRuntime {
 			await options.setup(this.session.sessionManager);
 			this.session.agent.state.messages = this.session.sessionManager.buildSessionContext().messages;
 		}
+		if (options?.persistInitializedSession) {
+			this.session.sessionManager.persistInitializedSession();
+		}
 		await this.finishSessionReplacement(options?.withSession);
 		return { cancelled: false };
 	}

packages/coding-agent/src/core/agent-session.ts

@@ -176,6 +176,7 @@ import {
 	type SessionHeader,
 } from "./session-manager.ts";
 import { generateSessionTitle, sessionTitleRetryPolicy, shouldSkipSessionTitle } from "./session-title-generator.ts";
+import { isSessionToolUseDisabled } from "./session-tool-policy.ts";
 import { SessionWorkBarrier } from "./session-work-barrier.ts";
 import type { SettingsManager, SettingsSourceSelection } from "./settings-manager.ts";
 import type { SlashCommandInfo } from "./slash-commands.ts";
@@ -2830,6 +2831,9 @@ export class AgentSession {
 	 * channel regardless of which tools the request advertised.
 	 */
 	getRegisteredTool(name: string): AgentTool | undefined {
+		if (isSessionToolUseDisabled(this.sessionManager.getEntries())) {
+			return undefined;
+		}
 		return this._toolRegistry.get(name);
 	}
 
@@ -2856,9 +2860,10 @@ export class AgentSession {
 	}
 
 	setActiveToolsByName(toolNames: string[]): void {
+		const effectiveToolNames = isSessionToolUseDisabled(this.sessionManager.getEntries()) ? [] : toolNames;
 		const tools: AgentTool[] = [];
 		const validToolNames: string[] = [];
-		for (const name of toolNames) {
+		for (const name of effectiveToolNames) {
 			const tool = this._toolRegistry.get(name);
 			if (tool) {
 				tools.push(tool);
@@ -7988,6 +7993,13 @@ export class AgentSession {
 		) as ReplacedSessionContext;
 		context.sendMessage = (message, options) => this.sendCustomMessage(message, options);
 		context.sendUserMessage = (content, options) => this.sendUserMessage(content, options);
+		context.setActiveTools = (toolNames) => this.setActiveToolsByName(toolNames);
+		context.setSessionModel = async (model) => {
+			if (!this._modelRuntime.hasConfiguredAuth(model.provider)) return false;
+			await this.setSessionModel(model);
+			return true;
+		};
+		context.setSessionThinkingLevel = (level) => this.setSessionThinkingLevel(level);
 		return context;
 	}
 

packages/coding-agent/src/core/extensions/builtin/AGENTS.md

@@ -39,7 +39,7 @@
 | 31 | `loop` | `loop/` | Scheduled/cron loop runs driven by a loopfile + `/loop` command — see `loop/AGENTS.md` |
 | 32 | `cache-keepalive` | `cache-keepalive/` | Warms the provider prompt cache between turns (`warmPromptCache`, Anthropic-aware TTL) and renders a `cache-keepalive` notice entry |
 | 33 | `ttsr` | `ttsr/` | Stream-rule detection (collapse + control-token-leak) with abort→remediate→retry; ported from oh-my-pi — see `ttsr/changes.md` |
-| 34 | `btw` | `btw/` | `/btw` side-question command that queries in parallel without touching the main session |
+| 34 | `btw` | `btw/` | Retained TUI side sessions with native transcripts, a Main/BTW/New switcher, configurable Ctrl aliases, Escape return, and current-side close; non-TUI keeps the parallel one-shot query |
 | 35 | `claude-sdk-oauth` | `claude-sdk-oauth/` | Claude SDK OAuth provider: multi-account OAuth, resume-first session continuity, stream-safe failover — see `claude-sdk-oauth/AGENTS.md` + `changes.md` |
 | 36 | `cursor-cli-oauth` | `cursor-cli-oauth/` | Cursor CLI OAuth provider lane: multi-account OAuth, spawn/stream parsing, failover; registers unconditionally and reports executable/auth state through its oauth check — see `cursor-cli-oauth/AGENTS.md` |
 | 37 | `config-reload` | `config-reload/` | Hash-gated watcher for trusted global/project config surfaces that defers a full session reload until idle and exposes the `config-watch:*` event protocol; registered after settings-dependent builtins so a reload rebuilds their resolved settings, and before final MCP observation |

packages/coding-agent/src/core/extensions/builtin/btw/changes.md

@@ -1,5 +1,49 @@
 # changes — btw
 
+## 2026-08-23 - Retained native TUI side sessions
+
+### What changed
+
+- In TUI mode, every `/btw <question>` creates a distinct host session with versioned root-parent
+  metadata, stable `BTW #N: <summary>` naming, a hidden bounded Main-context snapshot, no active
+  tools, and a native transcript.
+- Bare `/btw` opens the native selector with Main, numbered retained sides, and New BTW. The popup
+  renders the effective switch keys and always shows `/btw`; defaults are Ctrl+/, Ctrl+_, and
+  Ctrl+7 so editors that reserve Ctrl+/ still have a terminal fallback.
+- A configured switch input opens the same picker. Two idle interrupt keys inside one second return
+  to Main without deleting the side. The configured clear key switches to Main and then deletes
+  only the visible side.
+- Catalog reads revalidate selected paths, skip stale/corrupt rows, recover root scope from side
+  metadata after reload, and keep failed deletions discoverable.
+- The fresh replacement context applies the captured model and thinking level before the first
+  answer. The typed `newSession` policy capability persists a tool ban without crossing the
+  extension/core boundary; it forces later MCP/tool-search activation to an empty effective set
+  and rejects Cursor exec registered-tool lookup. Final provider payload enforcement removes
+  provider-native tool definitions after every extension transform.
+- Parent snapshots use Main's active leaf when Main is visible, so a side never captures an
+  abandoned physical tail after tree navigation. The selected Main leaf is persisted in side
+  metadata and inherited by siblings created from a side.
+- A newest message larger than the 64k snapshot budget is truncated into the snapshot instead of
+  dropping all parent context.
+- Inline and New BTW creation wait for Main to settle, then reload the catalog before snapshotting
+  so the leaf and content describe the same completed turn.
+- The typed `newSession` contract flushes initialized sides before returning, so an empty New BTW
+  remains in the disk catalog. Discovery and parent inspection use typed command-context
+  capabilities instead of importing core session internals.
+- Non-TUI modes retain the existing parallel, read-only, one-shot provider query.
+
+### Why
+
+- One custom widget could not represent multiple retained side conversations, use the host
+  transcript scrollback, survive reload/navigation, or make destructive close unambiguous.
+
+### Expected merge-conflict zones
+
+- MEDIUM: `index.ts` command and session-start wiring.
+- LOW: `session-catalog.ts`, `retained-session.ts`, `tui-command.ts`, `input-controls.ts`, and
+  `session-actions.ts` are extension-local additions.
+- LOW: `core/keybindings.ts`, extension UI context types, and interactive UI context wiring.
+
 ## 2026-08-13 - Preserve provider-header deletion markers
 
 ### What changed

packages/coding-agent/src/core/extensions/builtin/btw/index.ts

@@ -1,8 +1,17 @@
 import { convertToLlm, filterContextExcludedMessages } from "../../../messages.ts";
 import { buildSessionContext } from "../../../session-manager.ts";
 import type { ExtensionAPI, ExtensionContext } from "../../types.ts";
+import { createBtwInputRouter } from "./input-controls.ts";
 import { BtwPanel } from "./panel.ts";
+import { applyBtwSideSessionPolicy } from "./retained-session.ts";
+import {
+	closeRetainedBtwSide,
+	deleteBtwSessionFile,
+	readCurrentBtwSide,
+	returnToBtwParent,
+} from "./session-actions.ts";
 import { buildSideQueryContext, getSideQueryPromptContextWindow, runSideQuery } from "./side-query.ts";
+import { defaultBtwTuiCommandDependencies, runBtwTuiCommand } from "./tui-command.ts";
 
 const WIDGET_KEY = "btw";
 const ESCAPE = "";
@@ -30,6 +39,20 @@ export default function btwExtension(pi: ExtensionAPI) {
 		dismiss(ctx, { abort: true });
 	});
 
+	pi.on("session_start", (_event, ctx) => {
+		applyBtwSideSessionPolicy(pi, ctx);
+		if (ctx.mode !== "tui" || !ctx.ui.matchesKeybinding) return;
+		const router = createBtwInputRouter({
+			isCurrentSide: () => readCurrentBtwSide(ctx.sessionManager) !== undefined,
+			isIdle: () => ctx.isIdle(),
+			matchesKeybinding: (data, keybinding) => ctx.ui.matchesKeybinding?.(data, keybinding) ?? false,
+			dispatch: (command) => {
+				pi.sendUserMessage(command, { expandPromptTemplates: true });
+			},
+		});
+		ctx.ui.onTerminalInput((data) => router.handleInput(data));
+	});
+
 	pi.on("session_before_fork", (_event, ctx) => {
 		dismiss(ctx, { abort: true });
 	});
@@ -42,10 +65,42 @@ export default function btwExtension(pi: ExtensionAPI) {
 		if (active?.settled) dismiss(ctx, { abort: false });
 	});
 
+	pi.registerCommand("btw-main", {
+		description: "Return from the current retained BTW session to Main",
+		handler: async (_args, ctx) => {
+			await returnToBtwParent({
+				ctx,
+				current: readCurrentBtwSide(ctx.sessionManager),
+			});
+		},
+	});
+
+	pi.registerCommand("btw-close", {
+		description: "Delete the current retained BTW session and return to Main",
+		handler: async (_args, ctx) => {
+			await closeRetainedBtwSide({
+				ctx,
+				current: readCurrentBtwSide(ctx.sessionManager),
+				deleteSessionFile: deleteBtwSessionFile,
+			});
+		},
+	});
+
 	pi.registerCommand("btw", {
-		description: "Ask a side question in parallel without touching the main session",
+		description: "Create or switch retained BTW side sessions",
 		argumentHint: "<question>",
 		handler: async (args, ctx) => {
+			if (ctx.mode === "tui" && ctx.hasUI) {
+				dismiss(ctx, { abort: true });
+				try {
+					await runBtwTuiCommand(args, ctx, defaultBtwTuiCommandDependencies);
+				} catch (error) {
+					const message = error instanceof Error ? error.message : String(error);
+					ctx.ui.notify(`/btw failed: ${message}`, "error");
+				}
+				return;
+			}
+
 			const question = args.trim();
 			if (!question) {
 				ctx.ui.notify("Usage: /btw <question>", "warning");

packages/coding-agent/src/core/extensions/builtin/btw/input-controls.ts

@@ -0,0 +1,62 @@
+import type { AppKeybinding } from "../../../keybindings.ts";
+
+export const BTW_SWITCH_KEYBINDING = "app.btw.switch" as const;
+
+export interface BtwInputRouter {
+	handleInput(data: string): { consume?: boolean; data?: string } | undefined;
+}
+
+export function createBtwInputRouter(_input: {
+	isCurrentSide: () => boolean;
+	isIdle: () => boolean;
+	matchesKeybinding: (data: string, binding: AppKeybinding) => boolean;
+	dispatch: (command: string) => void;
+	now?: () => number;
+}): BtwInputRouter {
+	const input = _input;
+	const now = input.now ?? Date.now;
+	let firstIdleInterruptAt: number | undefined;
+
+	function resetInterruptPair(): void {
+		firstIdleInterruptAt = undefined;
+	}
+
+	return {
+		handleInput(data) {
+			if (input.matchesKeybinding(data, BTW_SWITCH_KEYBINDING)) {
+				resetInterruptPair();
+				input.dispatch("/btw");
+				return { consume: true };
+			}
+			if (!input.isCurrentSide()) {
+				resetInterruptPair();
+				return undefined;
+			}
+			if (input.matchesKeybinding(data, "app.clear")) {
+				resetInterruptPair();
+				input.dispatch("/btw-close");
+				return { consume: true };
+			}
+			if (!input.matchesKeybinding(data, "app.interrupt")) {
+				resetInterruptPair();
+				return undefined;
+			}
+			if (!input.isIdle()) {
+				resetInterruptPair();
+				return undefined;
+			}
+			const pressedAt = now();
+			if (
+				firstIdleInterruptAt !== undefined &&
+				pressedAt >= firstIdleInterruptAt &&
+				pressedAt - firstIdleInterruptAt <= 1_000
+			) {
+				resetInterruptPair();
+				input.dispatch("/btw-main");
+				return { consume: true };
+			}
+			firstIdleInterruptAt = pressedAt;
+			return undefined;
+		},
+	};
+}

packages/coding-agent/src/core/extensions/builtin/btw/picker.ts

@@ -0,0 +1,53 @@
+import type { BtwSessionCatalog } from "./session-catalog.ts";
+
+export type BtwPickerChoice = { type: "session"; sessionPath: string } | { type: "new"; parentSessionPath: string };
+
+export interface BtwPickerOption {
+	label: string;
+	choice: BtwPickerChoice;
+}
+
+export async function validateBtwPickerChoice(
+	choice: BtwPickerChoice,
+	exists: (sessionPath: string) => Promise<boolean>,
+): Promise<boolean> {
+	const sessionPath = choice.type === "session" ? choice.sessionPath : choice.parentSessionPath;
+	try {
+		return await exists(sessionPath);
+	} catch {
+		return false;
+	}
+}
+
+export function buildBtwPickerOptions(catalog: BtwSessionCatalog, currentSessionPath: string): BtwPickerOption[] {
+	const options: BtwPickerOption[] = [];
+	if (catalog.main) {
+		options.push({
+			label: `Main — ${catalog.main.name?.trim() || "Main session"}`,
+			choice: {
+				type: "session",
+				sessionPath: catalog.main.path,
+			},
+		});
+	}
+	for (const side of catalog.sides) {
+		const current = side.path === currentSessionPath ? " (current)" : "";
+		options.push({
+			label: `BTW #${side.metadata.ordinal} — ${side.metadata.summary}${current}`,
+			choice: {
+				type: "session",
+				sessionPath: side.path,
+			},
+		});
+	}
+	if (catalog.main) {
+		options.push({
+			label: "New BTW",
+			choice: {
+				type: "new",
+				parentSessionPath: catalog.parentSessionPath,
+			},
+		});
+	}
+	return options;
+}