auto-permission-system 3.9.1 → 3.12.0

package/extensions/guard.ts

@@ -91,7 +91,22 @@ async function detectMcpAsk(
 		policy: mcpPolicy,
 	});
 	if (result.decision !== "ask") return null;
-	return askDetection(ctx, "tool", toolName, result.summary);
+
+	// Include detailed call parameters or script preview if present
+	let detailedSummary = result.summary;
+	if (input && Object.keys(input).length > 0) {
+		const rawScript = input.code ?? input.script ?? input.command ?? input.query;
+		if (typeof rawScript === "string" && rawScript.includes("\n")) {
+			detailedSummary += `\n\n${rawScript}`;
+		} else {
+			const formattedArgs = JSON.stringify(input, null, 2);
+			if (formattedArgs.includes("\n")) {
+				detailedSummary += `\n\nArguments:\n${formattedArgs}`;
+			}
+		}
+	}
+
+	return askDetection(ctx, "tool", toolName, detailedSummary);
 }
 
 export default function (pi: ExtensionAPI) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auto-permission-system",
-  "version": "3.9.1",
+  "version": "3.12.0",
   "description": "Claude auto mode for Pi & security for Pi. A zero-trust permission system for Pi coding agent powered by Advanced Secure mode to scan files, content, and tools to prevent data breaches.",
   "type": "module",
   "author": "Navin Kumar",

package/sandbox.claude.json

@@ -2,6 +2,7 @@
   "enabled": true,
   "mode": "advanced-secure",
   "network": {
+    "allowLocalhost": false,
     "strictAllowlist": true,
     "allowedDomains": [
       "registry.npmjs.org",

package/sandbox.default.json

@@ -2,6 +2,7 @@
   "enabled": true,
   "mode": "advanced-secure",
   "network": {
+    "allowLocalhost": true,
     "allowedDomains": [
       "registry.npmjs.org",
       "registry.yarnpkg.com",
@@ -24,13 +25,22 @@
       "rubygems.org",
       "api.nuget.org",
       "deno.land",
-      "jsr.io"
+      "jsr.io",
+      "api.openai.com",
+      "huggingface.co",
+      "*.huggingface.co",
+      "cdn-lfs.huggingface.co",
+      "*.diffusion.studio",
+      "diffusion.studio"
     ]
   },
   "filesystem": {
     "outsideProject": {
       "read": "allow",
-      "allowRead": []
+      "allowRead": [
+        "~/Downloads",
+        "~/.cache"
+      ]
     },
     "denyRead": [],
     "askRead": [

package/skills/auto-permission-system/SKILL.md

@@ -39,6 +39,7 @@ A higher layer only states what it changes; absent keys keep the layer below. A
   "enabled": true,
   "mode": "default",                     // "default" (rules) | "advanced-secure" (secret detection, ADR-018)
   "network": {
+    "allowLocalhost": true,                // true (default): localhost on all ports allowed; false: strict network isolation
     "allowedDomains": ["github.com", "*.github.com"],  // empty = allow all
     "deniedDomains": [],                   // hard deny, never ask-able
     "strictAllowlist": false               // true = deny unknown hosts instead of asking

package/src/core/policy/patterns.ts

@@ -31,6 +31,63 @@ export function isWriteBlockError(output: string): boolean {
 	return WRITE_BLOCK_RE.test(output);
 }
 
+/**
+ * Loopback / localhost connection refusal evidence in a sandboxed command's output.
+ * On Linux, bubblewrap runs with --unshare-net which isolates network namespaces.
+ * Host services listening on 127.0.0.1/localhost (like Diffusion Studio on port 3274,
+ * or local dev servers) are not reachable from inside the container namespace.
+ */
+const LOOPBACK_REFUSAL_RE =
+	/(?:Failed to connect to (?:127\.0\.0\.1|localhost|::1)|(?:connect|connection refused).*?(?:127\.0\.0\.1|localhost|::1)|(?:127\.0\.0\.1|localhost|::1).*?(?:connection refused|ECONNREFUSED)|ECONNREFUSED.*?(?:127\.0\.0\.1|localhost|::1)|Diffusion Studio is not running)/i;
+
+/** True when the command failed due to connecting to a loopback/localhost address in the sandbox. */
+export function isLoopbackConnectionRefused(output: string): boolean {
+	return LOOPBACK_REFUSAL_RE.test(output);
+}
+
+export interface LoopbackEndpointInfo {
+	host: string;
+	port?: string;
+	service?: string;
+}
+
+/**
+ * Extract endpoint metadata (host, port, service name) from a loopback connection failure.
+ */
+export function extractLoopbackEndpoint(output: string, command?: string): LoopbackEndpointInfo | undefined {
+	if (!isLoopbackConnectionRefused(output)) return undefined;
+
+	// Check for Diffusion Studio specific error or command
+	const isDiffusion = /diffusion studio is not running/i.test(output) || (command && /\b(?:dapi|diffusion)\b/i.test(command));
+	if (isDiffusion) {
+		return { host: "127.0.0.1", port: "3274", service: "Diffusion Studio" };
+	}
+
+	// Match "Failed to connect to 127.0.0.1 port 3274" or "localhost port 8080"
+	const curlMatch = output.match(/Failed to connect to (127\.0\.0\.1|localhost|::1) port (\d+)/i);
+	if (curlMatch) {
+		return {
+			host: curlMatch[1],
+			port: curlMatch[2],
+			service: curlMatch[2] === "3274" ? "Diffusion Studio" : undefined,
+		};
+	}
+
+	// Match "connect ECONNREFUSED 127.0.0.1:3274"
+	const nodeMatch = output.match(/(?:ECONNREFUSED|connect to)\s+(127\.0\.0\.1|localhost|::1)(?::| port )(\d+)/i);
+	if (nodeMatch) {
+		return {
+			host: nodeMatch[1],
+			port: nodeMatch[2],
+			service: nodeMatch[2] === "3274" ? "Diffusion Studio" : undefined,
+		};
+	}
+
+	// Generic host match
+	const hostMatch = output.match(/(127\.0\.0\.1|localhost|::1)/i);
+	return { host: hostMatch ? hostMatch[1] : "127.0.0.1" };
+}
+
 /** A shell-name/empty token is not a path; everything else resolves against cwd unless absolute. */
 function toAbsolutePath(rawToken: string, cwd: string, home: string): string | undefined {
 	let token = rawToken.trim().replace(/[.,;]+$/, "");

package/src/detect/sensitive-file-scanner/patterns.ts

@@ -181,6 +181,33 @@ export const COMMON_NON_SECRET_VALUES = new Set([
   "secretvalue",
   "somevalue",
   "myvalue",
+  // Common keyboard keys / UI events (e.g. `Successfully pressed key: Backspace`)
+  "backspace",
+  "tab",
+  "enter",
+  "return",
+  "escape",
+  "esc",
+  "space",
+  "pageup",
+  "pagedown",
+  "end",
+  "home",
+  "arrowleft",
+  "arrowup",
+  "arrowright",
+  "arrowdown",
+  "left",
+  "up",
+  "right",
+  "down",
+  "delete",
+  "insert",
+  "capslock",
+  "numlock",
+  "scrolllock",
+  "printscreen",
+  "pause",
 ]);
 
 /**

package/src/l1-sandbox/bash-ops.ts

@@ -9,11 +9,12 @@ import { homedir } from "node:os";
 import { dirname } from "node:path";
 import { SandboxManager, type SandboxRuntimeConfig } from "@anthropic-ai/sandbox-runtime";
 import { type BashOperations } from "@earendil-works/pi-coding-agent";
-import { askReadCandidates, extractBlockedPath, isBlockedAccessError, isSafeFolderGrant, isWriteBlockError, matchedAskCommands, matchesPolicyPattern, outsideProjectMode, outsideProjectReadCandidates, outsideProjectReadDenied, sandboxFilesystem } from "../core/index";
+import { askReadCandidates, extractBlockedPath, extractLoopbackEndpoint, isBlockedAccessError, isLoopbackConnectionRefused, isSafeFolderGrant, isWriteBlockError, matchedAskCommands, matchesPolicyPattern, outsideProjectMode, outsideProjectReadCandidates, outsideProjectReadDenied, sandboxFilesystem } from "../core/index";
 import { audit } from "../shared/audit";
 import { canonicalize } from "../shared/canonicalize";
 import { askMain, askMainWithRemember, askRememberFile, MainChoice, type AskCtx } from "../ui/ask-flow";
 import { loadConfig, projectTrusted } from "./config";
+import { injectBridgesIntoBwrap, startHostPortBridges, type HostPortBridge } from "./host-bridge";
 
 /** First whitespace-separated token of a bash command — used to name the binary in prompt titles. */
 function firstWord(command: string): string {
@@ -76,11 +77,15 @@ async function preflightSensitiveCommands(
 	const matched = matchedAskCommands(command, ask, cwd, homedir());
 	if (!matched.length) return undefined;
 	const ui = opts.ctx as AskCtx;
-	const body = [
+	const bodyLines: string[] = [
 		`Command  ${matched.join(", ")}`,
 		`Risk     environment variables often hold API keys and tokens`,
 		`Note     can only be allowed one run at a time`,
-	].join("\n");
+	];
+	if (command.includes("\n")) {
+		bodyLines.push(`\nScript:\n${command}`);
+	}
+	const body = bodyLines.join("\n");
 	const choice = await askMain(ui, `Let ${matched[0]} print your environment variables?`, body, { once: true, remember: false, icon: "cred" });
 	const subject = matched.join(", ");
 	if (choice === "once") {
@@ -215,7 +220,26 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 			const grantedWriteFolders = new Set<string>();
 			const grantedWriteFiles = new Set<string>();
 			const attempt = async (writeOnce: string[]): Promise<{ exitCode: number | null }> => {
-				const wrappedCommand = await SandboxManager.wrapWithSandbox(command, undefined, buildCustom(writeOnce));
+				const cfg = loadConfig(cwd);
+				const allowLocalhost = cfg.allowLocalhost ?? cfg.network?.allowLocalhost ?? true;
+				let bridges: HostPortBridge[] = [];
+				if (!allowLocalhost && process.platform === "linux") {
+					const hostPorts = cfg.bridgeHostPorts ?? [3274];
+					bridges = await startHostPortBridges(hostPorts);
+				}
+				const rawWrapped = await SandboxManager.wrapWithSandbox(command, undefined, buildCustom(writeOnce));
+				let wrappedCommand = rawWrapped;
+				if (process.platform === "linux") {
+					if (allowLocalhost) {
+						wrappedCommand = wrappedCommand.replace(" --unshare-net ", " ");
+					} else if (bridges.length > 0) {
+						wrappedCommand = injectBridgesIntoBwrap(wrappedCommand, bridges);
+					}
+				}
+
+				const cleanupBridges = () => {
+					bridges.forEach((b) => b.close());
+				};
 
 				return new Promise((resolve, reject) => {
 					const child = spawn("bash", ["-c", wrappedCommand], {
@@ -251,11 +275,13 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 
 					child.on("error", (err) => {
 						if (timeoutHandle) clearTimeout(timeoutHandle);
+						cleanupBridges();
 						SandboxManager.cleanupAfterCommand();
 						reject(err);
 					});
 
 					const onAbort = () => {
+						cleanupBridges();
 						if (child.pid) {
 							try {
 								process.kill(-child.pid, "SIGKILL");
@@ -270,6 +296,7 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 					child.on("close", async (code) => {
 						if (timeoutHandle) clearTimeout(timeoutHandle);
 						signal?.removeEventListener("abort", onAbort);
+						cleanupBridges();
 
 						SandboxManager.cleanupAfterCommand();
 
@@ -326,6 +353,50 @@ export function createSandboxedBashOps(opts?: SandboxedBashOpts): BashOperations
 									`   or write inside the project directory (${cwd}).\n`;
 							}
 							blockedHint += `   Policy: ~/.pi/agent/extensions/sandbox.json (+ <cwd>/.pi/sandbox.json overrides).\n`;
+						} else if (code !== 0 && isLoopbackConnectionRefused(outputTail)) {
+							const endpointInfo = extractLoopbackEndpoint(outputTail, command);
+							const endpointStr = endpointInfo?.port ? `${endpointInfo.host}:${endpointInfo.port}` : (endpointInfo?.host ?? "127.0.0.1");
+							const serviceName = endpointInfo?.service;
+
+							auditL1({
+								subject: endpointStr,
+								decision: "loopback-refused",
+								reason: "Linux sandbox network namespace (--unshare-net) isolates host loopback",
+								cwd: opts?.ctx?.cwd,
+								note: serviceName ? `service:${serviceName}` : undefined,
+							});
+
+							const notifyMsg = serviceName === "Diffusion Studio"
+								? "pi-sandbox: Diffusion Studio is running on host port 3274, but sandboxed bash cannot reach host localhost. Connect it via MCP in ~/.pi/agent/mcp.json."
+								: `pi-sandbox: connection to host ${endpointStr} refused. Sandboxed bash cannot reach host localhost.`;
+							opts?.ctx?.ui?.notify?.(notifyMsg, "warning");
+
+							blockedHint = `\n💡 pi-sandbox: localhost / loopback connection refused.\n` +
+								`   Target: ${endpointStr}${serviceName ? ` (${serviceName})` : ""}\n` +
+								`   Why: The Linux sandbox runs inside an isolated network namespace (--unshare-net).\n` +
+								`        Services running on your HOST's 127.0.0.1/localhost are isolated and cannot\n` +
+								`        be reached directly from sandboxed bash commands.\n`;
+
+							if (serviceName === "Diffusion Studio" || /dapi|diffusion|3274/i.test(command)) {
+								blockedHint +=
+									`   Resolution for Diffusion Studio:\n` +
+									`   • Diffusion Studio exposes an MCP server on http://127.0.0.1:3274/mcp\n` +
+									`   • Add it to ~/.pi/agent/mcp.json so Pi connects directly on the host:\n` +
+									`       {\n` +
+									`         "mcpServers": {\n` +
+									`           "diffusion-studio": { "url": "http://127.0.0.1:3274/mcp" }\n` +
+									`         }\n` +
+									`       }\n` +
+									`   • Once added, restart or reload Pi: the agent gets native MCP tools\n` +
+									`     (context, check, capture, probe) with Layer 2 security, no bash needed.\n` +
+									`   • Or run pi with --yolo for one-off host access.\n`;
+							} else {
+								blockedHint +=
+									`   Resolution:\n` +
+									`   • If this is an MCP service, configure it in ~/.pi/agent/mcp.json.\n` +
+									`   • Pi runs on the host and can communicate with local MCP servers directly.\n` +
+									`   • Or run pi with --yolo if this task requires interacting with host network services.\n`;
+							}
 						}
 						/**
 						 * Emit the block explanation only when the command is not re-run with a

package/src/l1-sandbox/config.ts

@@ -22,10 +22,18 @@ export interface SandboxFilesystem extends NonNullable<SandboxRuntimeConfig["fil
 	outsideProject?: { read?: ReadPosture; allowRead?: string[] };
 }
 
-export interface SandboxConfig extends Omit<SandboxRuntimeConfig, "filesystem"> {
+export interface SandboxNetwork extends Partial<NonNullable<SandboxRuntimeConfig["network"]>> {
+	/** Whether to allow localhost / loopback on all ports (default: true). Set false to strictly isolate network. */
+	allowLocalhost?: boolean;
+	/** Host TCP ports to bridge into the Linux sandbox namespace when allowLocalhost is false. */
+	bridgeHostPorts?: number[];
+}
+
+export interface SandboxConfig extends Omit<SandboxRuntimeConfig, "filesystem" | "network"> {
 	enabled?: boolean;
 	/** `default` = rules only; `advanced-secure` adds secret/credential detection (ADR-018). */
 	mode?: PermissionMode;
+	network?: SandboxNetwork;
 	filesystem?: SandboxFilesystem;
 	/**
 	 * Additive project-local overrides written by the ask-tier prompts (Layer 1
@@ -40,6 +48,14 @@ export interface SandboxConfig extends Omit<SandboxRuntimeConfig, "filesystem">
 	};
 	/** Commands/paths that can print secrets (env, proc environ) and must ask first. */
 	commands?: { ask?: string[] };
+	/** Allow all Unix domain sockets on Linux (disables seccomp socket blocking). */
+	allowAllUnixSockets?: boolean;
+	/** Allow local port binding. */
+	allowLocalBinding?: boolean;
+	/** Whether to allow localhost / loopback on all ports (default: true). Set false to strictly isolate network. */
+	allowLocalhost?: boolean;
+	/** Host TCP ports to bridge into the Linux sandbox namespace when allowLocalhost is false. */
+	bridgeHostPorts?: number[];
 }
 
 const BUILTIN_CONFIG: SandboxConfig = {
@@ -48,6 +64,7 @@ const BUILTIN_CONFIG: SandboxConfig = {
 	network: {
 		allowedDomains: [...BUILTIN_NETWORK_ALLOWED],
 		deniedDomains: [],
+		allowLocalhost: true,
 	},
 	filesystem: {
 		denyRead: [...DEFAULT_DENY_READ],

package/src/l1-sandbox/host-bridge.ts

@@ -0,0 +1,99 @@
+/**
+ * Host loopback port bridge for Linux sandbox.
+ *
+ * Bubblewrap on Linux isolates the network namespace via `--unshare-net`.
+ * In that isolated namespace, loopback `127.0.0.1` is disconnected from the host,
+ * preventing tools (like Diffusion Studio CLI `dapi` or local dev servers) from
+ * reaching services running on the host's localhost (e.g. port 3274).
+ *
+ * This module creates a lightweight Unix domain socket bridge on the host
+ * (using Node's built-in `node:net`), bind-mounts the socket into bwrap,
+ * and starts a `socat` listener inside the container forwarding container
+ * `127.0.0.1:${port}` to the host service.
+ */
+
+import { randomBytes } from "node:crypto";
+import { existsSync, unlinkSync } from "node:fs";
+import net from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface HostPortBridge {
+	port: number;
+	sockPath: string;
+	close: () => void;
+}
+
+/**
+ * Start a Unix domain socket bridge on the host forwarding to host 127.0.0.1:port.
+ */
+export async function startHostPortBridge(port: number): Promise<HostPortBridge> {
+	const id = randomBytes(6).toString("hex");
+	const sockPath = join(tmpdir(), `pi-host-bridge-${port}-${id}.sock`);
+
+	const server = net.createServer((client) => {
+		const target = net.connect(port, "127.0.0.1");
+		client.pipe(target).pipe(client);
+		client.on("error", () => target.destroy());
+		target.on("error", () => client.destroy());
+	});
+
+	await new Promise<void>((resolve, reject) => {
+		server.listen(sockPath, () => resolve());
+		server.on("error", reject);
+	});
+
+	return {
+		port,
+		sockPath,
+		close: () => {
+			try {
+				server.close();
+			} catch (err) {
+				void err;
+			}
+			try {
+				if (existsSync(sockPath)) unlinkSync(sockPath);
+			} catch (err) {
+				void err;
+			}
+		},
+	};
+}
+
+/**
+ * Start bridges for multiple ports concurrently.
+ */
+export async function startHostPortBridges(ports: number[]): Promise<HostPortBridge[]> {
+	if (process.platform !== "linux" || !ports.length) return [];
+	return Promise.all(ports.map((p) => startHostPortBridge(p)));
+}
+
+/**
+ * Inject the bridges into the bwrap command invocation on Linux.
+ */
+export function injectBridgesIntoBwrap(wrappedCommand: string, bridges: HostPortBridge[]): string {
+	if (process.platform !== "linux" || !bridges.length) return wrappedCommand;
+
+	const dashIndex = wrappedCommand.indexOf(" -- ");
+	if (dashIndex === -1) return wrappedCommand;
+
+	// 1. Add --bind for each socket before " -- "
+	const binds = bridges.map((b) => `--bind ${b.sockPath} ${b.sockPath}`).join(" ");
+	const bwrapPart = `${wrappedCommand.slice(0, dashIndex)} ${binds}`;
+	let shellPart = wrappedCommand.slice(dashIndex + 4);
+
+	// 2. Start socat listeners inside the container
+	const socatStarters = bridges
+		.map((b) => `socat TCP-LISTEN:${b.port},fork,reuseaddr UNIX-CONNECT:${b.sockPath} >/dev/null 2>&1 &\n_pi_bridge_pids="$_pi_bridge_pids $!"`)
+		.join("\n");
+
+	if (shellPart.includes("socat TCP-LISTEN:3128")) {
+		shellPart = shellPart.replace("socat TCP-LISTEN:3128", `${socatStarters}\nsocat TCP-LISTEN:3128`);
+		// Include our bridge pids in the script EXIT trap cleanup
+		shellPart = shellPart.replace("kill %1 %2 2>/dev/null;", "kill %1 %2 $_pi_bridge_pids 2>/dev/null;");
+		return `${bwrapPart} -- ${shellPart}`;
+	}
+
+	return wrappedCommand;
+}

package/src/l1-sandbox/manager.ts

@@ -36,11 +36,13 @@ const SUPPRESSED_PROJECT_FILES = new Set([
  */
 export function suppressGhostDotfiles(): void {
 	try {
+		/* SAFETY: DANGEROUS_FILES is an array of strings in sandbox-runtime. */
 		const files = DANGEROUS_FILES as unknown as string[];
 		const filteredFiles = files.filter((f) => !SUPPRESSED_PROJECT_FILES.has(f));
 		files.length = 0;
 		files.push(...filteredFiles);
 
+		/* SAFETY: DANGEROUS_DIRECTORIES is an array of strings in sandbox-runtime. */
 		const dirs = DANGEROUS_DIRECTORIES as unknown as string[];
 		const filteredDirs = dirs.filter((d) => d === ".git");
 		dirs.length = 0;
@@ -64,8 +66,17 @@ type Layer1FilesystemKind = typeof OverrideKind.AllowWrite | typeof OverrideKind
  * filesystem.outsideProject.read gates reads.
  */
 function runtimeConfig(cwd: string, config: SandboxConfig): SandboxRuntimeConfig {
+	const allowLocalhost = config.allowLocalhost ?? config.network?.allowLocalhost ?? true;
+	const network = config.network
+		? {
+				...config.network,
+				allowAllUnixSockets: config.allowAllUnixSockets ?? config.network.allowAllUnixSockets,
+				allowLocalBinding: config.allowLocalBinding ?? config.network.allowLocalBinding ?? allowLocalhost,
+			}
+		: undefined;
+
 	return {
-		network: config.network,
+		network: network as NonNullable<SandboxRuntimeConfig["network"]>,
 		filesystem: config.filesystem
 			? sandboxFilesystem(config.filesystem, { cwd, home: homedir() })
 			: { denyRead: [], allowRead: [], allowWrite: [], denyWrite: [], disabled: true },
@@ -87,7 +98,8 @@ export async function initSandbox(cwd: string, config: SandboxConfig, deps?: Net
 export async function resetSandbox(): Promise<void> {
 	try {
 		await SandboxManager.reset();
-	} catch {
+	} catch (err) {
+		void err;
 	}
 }
 

package/src/ui/ask-flow.ts

@@ -214,7 +214,17 @@ async function askWithSelect(
 	timeoutMs: number,
 	footer: string | null,
 ): Promise<{ picked: string | undefined; expired: boolean }> {
-	const selectTitle = footer ? `${title}\n\n${footer}` : title;
+	// Guard against terminal overflow in non-custom/RPC mode for long scripts
+	let boundedTitle = title;
+	const lines = title.split("\n");
+	const MAX_FALLBACK_LINES = 16;
+	if (lines.length > MAX_FALLBACK_LINES) {
+		const header = lines[0];
+		const preview = lines.slice(1, MAX_FALLBACK_LINES).join("\n");
+		boundedTitle = `${header}\n${preview}\n\n[... ${lines.length - MAX_FALLBACK_LINES} more lines truncated]`;
+	}
+
+	const selectTitle = footer ? `${boundedTitle}\n\n${footer}` : boundedTitle;
 	if (timeoutMs === 0) {
 		const picked = await ctx.ui.select(selectTitle, options);
 		return { picked, expired: false };

package/src/ui/ask-selector.ts

@@ -54,6 +54,8 @@ export type AskSelectorOptions = {
 	onExpire: () => void;
 	/** Countdown tick, default 1000 ms. Test seam. */
 	tickMs?: number;
+	/** Maximum body lines shown in viewport before scrolling engages. Default 12. */
+	maxBodyLines?: number;
 };
 
 /** A one-line horizontal rule, like pi's DynamicBorder but without the
@@ -70,6 +72,9 @@ class Border implements Component {
 	}
 }
 
+const SCROLL_UP_KEYS = new Set(["\x1b[5~", "[", "\x1b[1;2A"]);
+const SCROLL_DOWN_KEYS = new Set(["\x1b[6~", "]", "\x1b[1;2B"]);
+
 export class AskSelector extends Container {
 	private readonly theme: AskTheme;
 	private readonly tui: { requestRender(): void };
@@ -90,6 +95,14 @@ export class AskSelector extends Container {
 	private finished = false;
 	private engaged = false;
 
+	private readonly isMultiLine: boolean;
+	private readonly headerText: string;
+	private readonly bodyLines: string[];
+	private readonly maxBodyLines: number;
+	private readonly bodyComponent: Text | null = null;
+	private readonly indicatorComponent: Text | null = null;
+	private bodyScrollOffset = 0;
+
 	constructor(o: AskSelectorOptions) {
 		super();
 		this.theme = o.theme;
@@ -103,10 +116,35 @@ export class AskSelector extends Container {
 		this.labels = o.options;
 		this.footerVisible = o.footer !== null && o.footer !== "";
 		this.remaining = Math.ceil(o.timeoutMs / 1000);
+		this.maxBodyLines = o.maxBodyLines ?? 12;
+
+		const allLines = o.title.split("\n");
+		this.isMultiLine = allLines.length > 1;
+
+		if (this.isMultiLine) {
+			this.headerText = allLines[0] ?? "";
+			this.bodyLines = allLines.slice(1);
+		} else {
+			this.headerText = o.title;
+			this.bodyLines = [];
+		}
 
 		this.addChild(new Border((t) => this.theme.fg("border", t)));
 		this.addChild(new Spacer(1));
-		this.addChild(new Text(this.theme.fg("accent", this.theme.bold(o.title)), 0, 0));
+
+		if (!this.isMultiLine) {
+			this.addChild(new Text(this.theme.fg("accent", this.theme.bold(o.title)), 0, 0));
+		} else if (this.bodyLines.length <= this.maxBodyLines) {
+			this.addChild(new Text(this.theme.fg("accent", this.theme.bold(o.title)), 0, 0));
+		} else {
+			this.addChild(new Text(this.theme.fg("accent", this.theme.bold(this.headerText)), 0, 0));
+			this.addChild(new Spacer(1));
+			this.bodyComponent = new Text(this.renderBodySlice(), 0, 0);
+			this.addChild(this.bodyComponent);
+			this.indicatorComponent = new Text(this.renderScrollIndicator(), 0, 0);
+			this.addChild(this.indicatorComponent);
+		}
+
 		this.addChild(new Spacer(1));
 		if (this.footerVisible) {
 			this.footerText = new Text(this.footerValue(), 0, 0);
@@ -146,6 +184,17 @@ export class AskSelector extends Container {
 	}
 
 	handleInput(data: string): void {
+		if (this.bodyLines.length > this.maxBodyLines) {
+			const pageSize = Math.max(1, this.maxBodyLines - 2);
+			if (this.keybindings.matches(data, "tui.select.pageUp") || SCROLL_UP_KEYS.has(data)) {
+				this.scrollBody(-pageSize);
+				return;
+			}
+			if (this.keybindings.matches(data, "tui.select.pageDown") || SCROLL_DOWN_KEYS.has(data)) {
+				this.scrollBody(pageSize);
+				return;
+			}
+		}
 		if (this.keybindings.matches(data, "tui.select.up")) {
 			this.move(-1);
 			return;
@@ -157,15 +206,39 @@ export class AskSelector extends Container {
 		this.list.handleInput(data);
 	}
 
-	/**
-	 * Keyboard-only prompt (ADR-036). Deliberately does not call the inherited
-	 * Container dispatch: that would forward the event to the SelectList, which
-	 * picks the row a left click lands on and moves the highlight on wheel — a
-	 * stray click on the terminal could allow a call the user never chose.
-	 * Returning `undefined` means "not handled here"; the renderer may still use
-	 * the gesture for its own text selection, which cannot pick an answer.
-	 */
-	handleMouse(): undefined {
+	private renderBodySlice(): string {
+		const slice = this.bodyLines.slice(this.bodyScrollOffset, this.bodyScrollOffset + this.maxBodyLines);
+		return this.theme.fg("accent", this.theme.bold(slice.join("\n")));
+	}
+
+	private renderScrollIndicator(): string {
+		const total = this.bodyLines.length;
+		const start = this.bodyScrollOffset + 1;
+		const end = Math.min(total, this.bodyScrollOffset + this.maxBodyLines);
+		return this.theme.fg("muted", `[${start}–${end} of ${total} lines | [/] or Shift+↑/↓ or Scroll Wheel]`);
+	}
+
+	private scrollBody(delta: number): void {
+		if (this.bodyLines.length <= this.maxBodyLines) return;
+		const maxOffset = this.bodyLines.length - this.maxBodyLines;
+		const next = Math.max(0, Math.min(maxOffset, this.bodyScrollOffset + delta));
+		if (next === this.bodyScrollOffset) return;
+		this.bodyScrollOffset = next;
+		this.bodyComponent?.setText(this.renderBodySlice());
+		this.indicatorComponent?.setText(this.renderScrollIndicator());
+		this.onActivity();
+		this.tui.requestRender();
+	}
+
+	handleMouse(event: { type?: string; wheelDelta?: number }): undefined {
+		if (event?.type === "wheel" && Number.isFinite(event.wheelDelta)) {
+			if (this.bodyLines.length > this.maxBodyLines) {
+				const delta = event.wheelDelta;
+				if (delta !== undefined) {
+					this.scrollBody(delta > 0 ? 2 : -2);
+				}
+			}
+		}
 		return undefined;
 	}