@yandy0725/pi-ask-user 0.3.0 → 0.4.1

package/README.md

@@ -11,7 +11,7 @@ A Pi package that adds an interactive `ask_user` tool for collecting user decisi
 - User-toggleable extra context on structured selections
 - Context display support
 - Configurable display mode: `overlay` (modal, default) or `inline` (rendered directly in the flow)
-- Runtime overlay toggle: press the configured overlay-toggle key (`alt+o` by default, configurable per call or via env var) while the prompt is open to temporarily hide/show the popup so you can read prior agent output, then press it again to bring it back
+- Runtime overlay toggle: press the configured overlay-toggle key (`alt+o` by default, configurable via env var or `ask-user.json`) while the prompt is open to temporarily hide/show the popup so you can read prior agent output, then press it again to bring it back
 - Pi-TUI-aligned keybinding and editor behavior
 - Custom TUI rendering for tool calls and results
 - System prompt integration via `promptSnippet` and `promptGuidelines`
@@ -59,11 +59,10 @@ The registered tool name is:
 | `allowMultiple` | `boolean?` | `false` | Enable multi-select mode |
 | `allowFreeform` | `boolean?` | `true` | Add a "Type something" freeform option |
 | `allowComment` | `boolean?` | `true` | Expose a user-toggleable extra-context option in the custom UI (`ctrl+g` or the toggle row) and collect an optional comment in fallback dialogs |
-| `displayMode` | `"overlay" \| "inline"?` | env var or `"overlay"` | Controls custom UI rendering: `overlay` shows the centered modal (current behavior), `inline` renders without overlay framing |
-| `overlayToggleKey` | `string?` | env var or `"alt+o"` | Shortcut for hiding/showing the overlay popup (overlay mode only). Pi-TUI key spec, e.g. `"alt+o"`, `"ctrl+shift+h"`. Pass `"off"` to disable. |
-| `commentToggleKey` | `string?` | env var or `"ctrl+g"` | Shortcut for toggling the optional comment/extra-context row when `allowComment: true`. Pass `"off"` to disable. |
 | `timeout` | `number?` | — | Auto-dismiss after N ms and return `null` if the prompt times out |
 
+Appearance options (`displayMode`, `overlayToggleKey`, `commentToggleKey`) are **not** model-visible parameters. They are user preferences resolved from env vars and `ask-user.json` — see [Display mode](#display-mode) and [Shortcuts](#shortcuts). They remain accepted by the internal `AskParams` type for SDK/direct callers, but an LLM tool call cannot set them.
+
 ## Example usage shape
 
 ```json
@@ -76,8 +75,7 @@ The registered tool name is:
   ],
   "allowMultiple": false,
   "allowFreeform": true,
-  "allowComment": true,
-  "displayMode": "inline"
+  "allowComment": true
 }
 ```
 
@@ -95,11 +93,12 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 Effective order:
 
-1. Per-call `displayMode` parameter (if provided)
-2. `PI_ASK_USER_DISPLAY_MODE` (if set to `"overlay"` or `"inline"`)
-3. Project config file `.pi/ask-user.json` `displayMode` field (if exists)
-4. User config file `~/.pi/agent/ask-user.json` `displayMode` field (if exists)
-5. Fallback default: `"overlay"`
+1. `PI_ASK_USER_DISPLAY_MODE` (if set to `"overlay"` or `"inline"`)
+2. Project config file `.pi/ask-user.json` `displayMode` field (if exists)
+3. User config file `~/.pi/agent/ask-user.json` `displayMode` field (if exists)
+4. Fallback default: `"overlay"`
+
+(A per-call `displayMode` still wins over all of the above for SDK/direct callers, but the field is no longer part of the model-visible tool schema.)
 
 Unrecognised values are silently ignored and fall back to `"overlay"`.
 
@@ -111,7 +110,7 @@ In addition to environment variables, you can use JSON config files:
 - User-level (global): `~/.pi/agent/ask-user.json`
 - Project-level: `.pi/ask-user.json`
 
-Fields in the project-level file override same-named fields in the user-level file. Priority: call param > env var > project config > user config > default.
+Fields in the project-level file override same-named fields in the user-level file. Priority: env var > project config > user config > default.
 
 **Example `~/.pi/agent/ask-user.json`:**
 
@@ -129,11 +128,12 @@ All fields are optional. Missing files or malformed JSON are silently ignored, e
 
 Effective order for both `overlayToggleKey` and `commentToggleKey`:
 
-1. Per-call parameter (if provided)
-2. Matching env var (`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`)
-3. Project config file `.pi/ask-user.json` (if exists)
-4. User config file `~/.pi/agent/ask-user.json` (if exists)
-5. Built-in defaults: `alt+o` and `ctrl+g`
+1. Matching env var (`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`)
+2. Project config file `.pi/ask-user.json` (if exists)
+3. User config file `~/.pi/agent/ask-user.json` (if exists)
+4. Built-in defaults: `alt+o` and `ctrl+g`
+
+(A per-call parameter still wins for SDK/direct callers, but these fields are no longer part of the model-visible tool schema.)
 
 Pass `"off"`, `"none"`, or `"disabled"` (at any level) to disable the shortcut entirely. Invalid specs are silently dropped and the next source is used. Specs follow the Pi-TUI [`KeyId`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) format: `[mod+]...key` where modifiers are `ctrl`, `shift`, `alt`, `super`, in any order, joined by `+` (e.g. `ctrl+g`, `alt+shift+x`, `escape`, `tab`).
 
@@ -148,8 +148,9 @@ While an `ask_user` prompt is open:
 | `enter` | Confirm the focused option, submit a freeform response, or submit/skip an optional comment. |
 | `esc` | Clear the search filter, exit freeform/comment mode, or cancel the prompt. |
 | `↑` / `↓`, `ctrl+k` / `ctrl+j` | Navigate options. `ctrl+k` / `ctrl+j` (vim-style) work while typing in searchable prompts without disturbing the filter. |
+| `pgup` / `pgdn` | Scroll the question/context region when it is taller than the popup. The popup never exceeds 85% of the terminal height, so options and the help line always stay visible; a `↑ n lines above` / `↓ n lines below` indicator marks the hidden content. Only in option-select mode (the editor owns these keys in freeform/comment mode). |
 
-If you prefer never to see the overlay, set `displayMode: "inline"` per call or `PI_ASK_USER_DISPLAY_MODE=inline` globally.
+If you prefer never to see the overlay, set `PI_ASK_USER_DISPLAY_MODE=inline` globally or `"displayMode": "inline"` in `ask-user.json`.
 
 ## Result details
 

package/README.zh.md

@@ -11,7 +11,7 @@
 - 选择后可切换添加额外上下文（可选注释）
 - 上下文展示支持
 - 可配置的显示模式：`overlay`（模态，默认）或 `inline`（直接内联渲染）
-- 运行时浮层切换：当提示窗口打开时，按下配置的叠加层切换键（默认 `alt+o`，可每次调用配置或通过环境变量设置）临时隐藏/显示弹窗，以便阅读之前的 Agent 输出
+- 运行时浮层切换：当提示窗口打开时，按下配置的叠加层切换键（默认 `alt+o`，可通过环境变量或 `ask-user.json` 配置）临时隐藏/显示弹窗，以便阅读之前的 Agent 输出
 - Pi-TUI 对齐的按键绑定和编辑器行为
 - 工具调用和结果的自定义 TUI 渲染
 - 通过 `promptSnippet` 和 `promptGuidelines` 集成系统提示词
@@ -59,11 +59,10 @@ pi install npm:@yandy0725/pi-ask-user
 | `allowMultiple` | `boolean?` | `false` | 启用多选模式 |
 | `allowFreeform` | `boolean?` | `true` | 添加"自定义输入"自由文本选项 |
 | `allowComment` | `boolean?` | `true` | 在自定义 UI 中提供可切换的额外上下文选项（`ctrl+g` 或切换行），并在回退对话框中收集可选注释 |
-| `displayMode` | `"overlay" \| "inline"?` | 环境变量或 `"overlay"` | 控制自定义 UI 渲染：`overlay` 显示居中模态框（当前行为），`inline` 不显示叠加框架渲染 |
-| `overlayToggleKey` | `string?` | 环境变量或 `"alt+o"` | 隐藏/显示叠加弹窗的快捷键（仅 overlay 模式）。Pi-TUI 键位格式，例如 `"alt+o"`、`"ctrl+shift+h"`。传入 `"off"` 禁用。 |
-| `commentToggleKey` | `string?` | 环境变量或 `"ctrl+g"` | 当 `allowComment: true` 时切换可选注释/额外上下文行的快捷键。传入 `"off"` 禁用。 |
 | `timeout` | `number?` | — | N 毫秒后自动关闭，超时返回 `null` |
 
+外观类选项（`displayMode`、`overlayToggleKey`、`commentToggleKey`）**不是**模型可见参数：它们是用户偏好，由环境变量与 `ask-user.json` 解析（见[显示模式](#显示模式)与[快捷键](#快捷键)）。内部 `AskParams` 类型仍接受它们（供 SDK/直接调用），但 LLM 的工具调用无法设置。
+
 ## 通过环境变量设置个人偏好
 
 在你的 shell 配置（`~/.zshrc`、`~/.bash_profile` 等）中设置以下变量来全局配置默认值：
@@ -78,11 +77,12 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 生效优先级：
 
-1. 每次调用时的 `displayMode` 参数（如提供）
-2. `PI_ASK_USER_DISPLAY_MODE`（如设置为 `"overlay"` 或 `"inline"`）
-3. 项目配置文件 `.pi/ask-user.json`（如存在）中的 `displayMode`
-4. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）中的 `displayMode`
-5. 回退默认值：`"overlay"`
+1. `PI_ASK_USER_DISPLAY_MODE`（如设置为 `"overlay"` 或 `"inline"`）
+2. 项目配置文件 `.pi/ask-user.json`（如存在）中的 `displayMode`
+3. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）中的 `displayMode`
+4. 回退默认值：`"overlay"`
+
+（SDK/直接调用传入的 `displayMode` 仍会覆盖以上所有层级，但该字段已不在模型可见的 tool schema 里。）
 
 无法识别的值会被静默忽略并回退到 `"overlay"`。
 
@@ -94,7 +94,7 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 - 用户级（全局）：`~/.pi/agent/ask-user.json`
 - 项目级：`.pi/ask-user.json`
 
-项目级文件中的字段会覆盖用户级文件中同名字段。配置优先级：调用参数 > 环境变量 > 项目配置 > 用户配置 > 默认值。
+项目级文件中的字段会覆盖用户级文件中同名字段。配置优先级：环境变量 > 项目配置 > 用户配置 > 默认值。
 
 **示例 `~/.pi/agent/ask-user.json`：**
 
@@ -112,10 +112,9 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 
 `overlayToggleKey` 和 `commentToggleKey` 的生效优先级：
 
-1. 每次调用时的参数（如提供）
-2. 对应的环境变量（`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`）
-3. 项目配置文件 `.pi/ask-user.json`（如存在）
-4. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）
+1. 对应的环境变量（`PI_ASK_USER_OVERLAY_TOGGLE_KEY` / `PI_ASK_USER_COMMENT_TOGGLE_KEY`）
+2. 项目配置文件 `.pi/ask-user.json`（如存在）
+3. 用户配置文件 `~/.pi/agent/ask-user.json`（如存在）
 5. 内置默认值：`alt+o` 和 `ctrl+g`
 
 传入 `"off"`、`"none"` 或 `"disabled"`（任意级别）可以完全禁用快捷键。无效的键位格式会被静默丢弃，使用下一个来源。键位格式遵循 Pi-TUI 的 [`KeyId`](https://github.com/earendil-works/pi-mono/blob/main/packages/tui/src/keys.ts) 格式：`[mod+]...key`，修饰键为 `ctrl`、`shift`、`alt`、`super`，可任意顺序用 `+` 连接（如 `ctrl+g`、`alt+shift+x`、`escape`、`tab`）。
@@ -131,8 +130,9 @@ export PI_ASK_USER_COMMENT_TOGGLE_KEY=alt+c
 | `enter` | 确认聚焦的选项、提交自由文本回复、或提交/跳过可选注释。 |
 | `esc` | 清除搜索过滤、退出自由文本/注释模式、或取消提示。 |
 | `↑` / `↓`、`ctrl+k` / `ctrl+j` | 导航选项。`ctrl+k` / `ctrl+j`（vim 风格）可在可搜索提示中打字时不干扰过滤输入。 |
+| `pgup` / `pgdn` | 当问题/背景内容超出弹窗高度时滚动该区域。弹窗总高度不会超过终端的 85%，选项和帮助行始终可见；被隐藏的内容会用 `↑ n lines above` / `↓ n lines below` 指示行标注。仅在选项选择模式下可用（自由文本/注释模式下这两个按键归编辑器所有）。 |
 
-如果你始终不希望看到叠加层，请每次调用时设置 `displayMode: "inline"`，或全局设置 `PI_ASK_USER_DISPLAY_MODE=inline`。
+如果你始终不希望看到叠加层，请全局设置 `PI_ASK_USER_DISPLAY_MODE=inline`，或在 `ask-user.json` 中设置 `"displayMode": "inline"`。
 
 ## 结果详情
 

package/index.ts

@@ -32,30 +32,17 @@ import {
 	truncateToWidth,
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
-import { type TUnsafe, Type } from "typebox";
-import { type QuestionOption, renderSingleSelectRows } from "./src/single-select-layout.js";
+import { Type } from "typebox";
+import {
+	type QuestionOption,
+	renderSingleSelectRows,
+	type SelectableBlock,
+	windowSelectedBlocks,
+} from "./src/single-select-layout.js";
 
 const _require = createRequire(import.meta.url);
 const ASK_USER_VERSION: string = (_require("./package.json") as { version: string }).version;
 
-/**
- * Emit a flat `{ type: "string", enum: [...] }` JSON Schema instead of the
- * `anyOf`/`oneOf` shape that `Type.Union([Type.Literal()])` produces. Google's
- * function-calling API rejects the union form. Local copy of pi-ai's StringEnum
- * to avoid a peer dependency for one helper.
- */
-function StringEnum<const T extends readonly string[]>(
-	values: T,
-	options?: { description?: string; default?: T[number] },
-): TUnsafe<T[number]> {
-	return Type.Unsafe<T[number]>({
-		type: "string",
-		enum: [...values],
-		...(options?.description ? { description: options.description } : {}),
-		...(options?.default !== undefined ? { default: options.default } : {}),
-	});
-}
-
 /**
  * `getMarkdownTheme()` returns a bag of closures that read through a Proxy
  * over the host's theme singleton. The Proxy only throws on property access,
@@ -386,6 +373,14 @@ function resolveShortcut(
 type AskMode = "select" | "freeform" | "comment";
 
 const ASK_OVERLAY_MAX_HEIGHT_RATIO = 0.85;
+/** Fixed lines in the box: 2 borders + 5 spacers (title/help measured at render time). */
+const ASK_OVERLAY_FIXED_LINES = 7;
+/** Maximum share of the available rows the header (question+context) may claim. */
+const ASK_HEADER_MAX_SHARE = 0.5;
+/** Minimum header rows (question) kept visible when space is tight. */
+const MIN_HEADER_ROWS = 1;
+/** Minimum interactive-region rows (option list) kept visible when tight. */
+const MIN_MODE_ROWS = 4;
 // biome-ignore lint/suspicious/noExplicitAny: SizeValue compatibility with pi-tui
 const ASK_OVERLAY_WIDTH: any = "92%";
 const ASK_OVERLAY_MIN_WIDTH = 40;
@@ -465,6 +460,7 @@ class MultiSelectList implements Component {
 	private selectedIndex = 0;
 	private checked = new Set<number>();
 	private commentEnabled = false;
+	private maxVisibleRows = 10;
 	private cachedWidth?: number;
 	private cachedLines?: string[];
 
@@ -492,6 +488,14 @@ class MultiSelectList implements Component {
 		return this.commentEnabled;
 	}
 
+	setMaxVisibleRows(rows: number): void {
+		const next = Math.max(1, Math.floor(rows));
+		if (next !== this.maxVisibleRows) {
+			this.maxVisibleRows = next;
+			this.invalidate();
+		}
+	}
+
 	invalidate(): void {
 		this.cachedWidth = undefined;
 		this.cachedLines = undefined;
@@ -614,7 +618,6 @@ class MultiSelectList implements Component {
 
 		const theme = this.theme;
 		const count = this.getItemCount();
-		const maxVisible = Math.min(count, 10);
 
 		if (count === 0) {
 			this.cachedLines = [theme.fg("warning", "No options")];
@@ -622,56 +625,55 @@ class MultiSelectList implements Component {
 			return this.cachedLines;
 		}
 
-		const startIndex = Math.max(0, Math.min(this.selectedIndex - Math.floor(maxVisible / 2), count - maxVisible));
-		const endIndex = Math.min(startIndex + maxVisible, count);
-
-		const lines: string[] = [];
-
-		for (let i = startIndex; i < endIndex; i++) {
+		const pointerWidth = 2; // "→ " / "  "
+		const blocks: SelectableBlock[] = [];
+		for (let i = 0; i < count; i++) {
 			const isSelected = i === this.selectedIndex;
-			const prefix = isSelected ? theme.fg("accent", "→") : " ";
+			const pointer = isSelected ? theme.fg("accent", "→ ") : "  ";
+			const continuation = " ".repeat(pointerWidth);
+			const lines: string[] = [];
 
 			if (this.isCommentToggleRow(i)) {
 				const checkbox = this.commentEnabled ? theme.fg("success", "[✓]") : theme.fg("dim", "[ ]");
 				const label = isSelected
 					? theme.fg("accent", theme.bold(COMMENT_TOGGLE_LABEL))
 					: theme.fg("text", theme.bold(COMMENT_TOGGLE_LABEL));
-				lines.push(truncateToWidth(`${prefix}   ${checkbox} ${label}`, width, ""));
-				continue;
-			}
-
-			if (this.isFreeformRow(i)) {
+				lines.push(`${pointer}  ${checkbox} ${label}`);
+			} else if (this.isFreeformRow(i)) {
 				const label = theme.fg("text", theme.bold("Type something."));
 				const desc = theme.fg("muted", "Enter a custom response");
-				const line = `${prefix}   ${label} ${theme.fg("dim", "—")} ${desc}`;
-				lines.push(truncateToWidth(line, width, ""));
-				continue;
-			}
-
-			const option = this.options[i];
-			if (!option) continue;
-
-			const checkbox = this.checked.has(i) ? theme.fg("success", "[✓]") : theme.fg("dim", "[ ]");
-			const num = theme.fg("dim", `${i + 1}.`);
-			const title = isSelected ? theme.fg("accent", theme.bold(option.title)) : theme.fg("text", theme.bold(option.title));
-
-			const firstLine = `${prefix} ${num} ${checkbox} ${title}`;
-			lines.push(truncateToWidth(firstLine, width, ""));
-
-			if (option.description) {
-				const indent = "      ";
-				const wrapWidth = Math.max(10, width - indent.length);
-				const wrapped = wrapTextWithAnsi(option.description, wrapWidth);
-				for (const w of wrapped) {
-					lines.push(truncateToWidth(indent + theme.fg("muted", w), width, ""));
+				lines.push(`${pointer}  ${label} ${theme.fg("dim", "—")} ${desc}`);
+			} else {
+				const option = this.options[i];
+				if (!option) continue;
+
+				const checkbox = this.checked.has(i) ? theme.fg("success", "[✓]") : theme.fg("dim", "[ ]");
+				const num = theme.fg("dim", `${i + 1}.`);
+				const title = isSelected
+					? theme.fg("accent", theme.bold(option.title))
+					: theme.fg("text", theme.bold(option.title));
+				lines.push(`${pointer}${num} ${checkbox} ${title}`);
+
+				if (option.description) {
+					const indent = `${continuation}    `;
+					const wrapWidth = Math.max(10, width - indent.length);
+					const wrapped = wrapTextWithAnsi(option.description, wrapWidth);
+					for (const w of wrapped) {
+						lines.push(indent + theme.fg("muted", w));
+					}
 				}
 			}
-		}
 
-		if (startIndex > 0 || endIndex < count) {
-			lines.push(theme.fg("dim", truncateToWidth(`  (${this.selectedIndex + 1}/${count})`, width, "")));
+			blocks.push({ lines, selected: isSelected });
 		}
 
+		const rows = windowSelectedBlocks({
+			blocks,
+			maxRows: this.maxVisibleRows,
+			indicator: theme.fg("dim", `(${this.selectedIndex + 1}/${count})`),
+		});
+		const lines = rows.map((row) => truncateToWidth(row.line, width, ""));
+
 		this.cachedWidth = width;
 		this.cachedLines = lines;
 		return lines;
@@ -1050,14 +1052,22 @@ class AskComponent extends Container {
 	private titleText: Text;
 	private questionText: Text;
 	private contextComponent?: Component;
-	private modeContainer: Container;
 	private helpText: Text;
 
-	// Mode components
+	// Mode components (rendered in order; tracked separately from the static
+	// children so the budget-aware render can measure and clamp them directly)
+	private modeComponents: Component[] = [];
 	private singleSelectList?: WrappedSingleSelectList;
 	private multiSelectList?: MultiSelectList;
 	private editor?: Editor;
 
+	// Header (question + context) scroll state. The overlay is hard-clamped by
+	// pi-tui at maxHeight (85% of terminal rows), and lines beyond that are
+	// silently sliced off — so the component must budget its own height and
+	// scroll the header region when question+context exceed their share.
+	private headerScrollOffset = 0;
+	private headerScrollState = { scrollable: false, pageSize: 0 };
+
 	// Focusable - propagate to Editor for IME cursor positioning
 	private _focused = false;
 	get focused(): boolean {
@@ -1130,10 +1140,6 @@ class AskComponent extends Container {
 
 		this.addChild(new Spacer(1));
 
-		this.modeContainer = new Container();
-		this.addChild(this.modeContainer);
-
-		this.addChild(new Spacer(1));
 		this.helpText = new Text("", 1, 0);
 		this.addChild(this.helpText);
 
@@ -1156,48 +1162,146 @@ class AskComponent extends Container {
 		this.updateHelpText();
 	}
 
+	/**
+	 * Budget-aware render. pi-tui slices any overlay lines beyond maxHeight
+	 * (85% of terminal rows, minus margins) without scrolling, so the component
+	 * must never emit more lines than that. The available height is split
+	 * between the header (question + context) and the interactive region; the
+	 * interactive region keeps a floor of a few rows so options stay visible,
+	 * and the header becomes a scrollable viewport (pageUp/pageDown) whenever it
+	 * does not fit.
+	 */
 	override render(width: number): string[] {
 		const innerWidth = Math.max(1, width - BOX_BORDER_OVERHEAD);
-
-		if (this.mode === "select" && !this.allowMultiple) {
-			const overlayMaxHeight = Math.max(12, Math.floor(this.tui.terminal.rows * ASK_OVERLAY_MAX_HEIGHT_RATIO));
-			const staticLines = this.countStaticLines(innerWidth);
-			const availableOptionRows = Math.max(4, overlayMaxHeight - staticLines);
-			this.ensureSingleSelectList().setMaxVisibleRows(availableOptionRows);
+		const termRows = this.tui.terminal?.rows ?? 24;
+		// Mirrors the overlay options: maxHeight "85%" clamped by margin 1.
+		const budgetHeight = Math.max(1, Math.min(Math.floor(termRows * ASK_OVERLAY_MAX_HEIGHT_RATIO), termRows - 2));
+
+		// Measure the fixed chrome — the title and help lines can wrap (real
+		// keybinding hints span two rows at common widths), so they must be
+		// counted, not assumed: 2 borders + 5 spacers + measured rows.
+		const titleLines = this.titleText.render(innerWidth);
+		const helpLines = this.helpText.render(innerWidth);
+		const chromeLines = ASK_OVERLAY_FIXED_LINES + titleLines.length + helpLines.length;
+
+		const headerLines = this.buildHeaderLines(innerWidth);
+
+		// Measure the interactive region at its natural (unclamped) height.
+		const modeDesired = this.measureModeRegion(innerWidth);
+
+		// Allocate the remaining rows between header and interactive region:
+		// the header may claim at most ~half the available rows, the interactive
+		// region takes the rest (with a floor so options stay usable), and any
+		// rows the interactive region cannot use flow back to the header.
+		const available = Math.max(2, budgetHeight - chromeLines);
+		const headerCap = Math.max(MIN_HEADER_ROWS, Math.floor(available * ASK_HEADER_MAX_SHARE));
+		let headerBudget = Math.min(headerLines.length, headerCap);
+		let modeBudget = Math.min(modeDesired, Math.max(MIN_MODE_ROWS, available - headerBudget));
+		headerBudget = Math.min(headerLines.length, Math.max(MIN_HEADER_ROWS, available - modeBudget));
+		// Hard clamp for tiny terminals where even the floors exceed the budget.
+		if (headerBudget + modeBudget > available) {
+			modeBudget = Math.max(1, available - headerBudget);
 		}
 
-		// Render children at the inner width (excluding side border characters)
-		const rawLines = super.render(innerWidth);
+		const modeLines = this.renderModeRegion(innerWidth, modeBudget).slice(0, Math.max(1, modeBudget));
+		const headerViewport = this.renderHeaderViewport(headerLines, headerBudget, innerWidth);
+
+		// Assemble: borders, title, header viewport, interactive region, help.
+		const inner: string[] = [];
+		inner.push("");
+		inner.push(...titleLines);
+		inner.push("");
+		inner.push(...headerViewport);
+		inner.push("");
+		inner.push(...modeLines);
+		inner.push("");
+		inner.push(...helpLines);
 
-		// First and last lines are the top/bottom box borders — pass through at full width.
-		// All inner lines get wrapped with side borders.
 		const borderColor = (s: string) => this.theme.fg("accent", s);
 		const titleColor = (s: string) => this.theme.fg("dim", this.theme.bold(s));
-		return rawLines.map((line, index) => {
-			if (index === 0 || index === rawLines.length - 1) {
-				// Box top/bottom borders already rendered at innerWidth — re-render at full width
-				if (index === 0) return new BoxBorderTop(borderColor, "ask_user", titleColor).render(width)[0];
-				return new BoxBorderBottom(borderColor, `v${ASK_USER_VERSION}`, (s: string) => this.theme.fg("dim", s)).render(
-					width,
-				)[0];
-			}
+		const lines: string[] = [new BoxBorderTop(borderColor, "ask_user", titleColor).render(width)[0] ?? ""];
+		for (const line of inner) {
 			const padded = truncateToWidth(line, innerWidth, "", true);
-			return `${borderColor(BOX_BORDER_LEFT)}${padded}${borderColor(BOX_BORDER_RIGHT)}`;
-		});
+			lines.push(`${borderColor(BOX_BORDER_LEFT)}${padded}${borderColor(BOX_BORDER_RIGHT)}`);
+		}
+		lines.push("");
+		lines.push(
+			new BoxBorderBottom(borderColor, `v${ASK_USER_VERSION}`, (s: string) => this.theme.fg("dim", s)).render(width)[0] ??
+				"",
+		);
+
+		// Hard guarantee: never exceed the overlay budget (tiny terminals).
+		return lines.slice(0, Math.max(budgetHeight, 3));
+	}
+
+	private buildHeaderLines(width: number): string[] {
+		const lines: string[] = [];
+		lines.push(...this.questionText.render(width));
+		if (this.contextComponent && this.context) {
+			lines.push("");
+			lines.push(...this.contextComponent.render(width));
+		}
+		return lines;
+	}
+
+	private renderHeaderViewport(content: string[], budget: number, width: number): string[] {
+		if (budget <= 0) {
+			this.headerScrollState = { scrollable: false, pageSize: 0 };
+			return [];
+		}
+		if (content.length <= budget) {
+			this.headerScrollOffset = 0;
+			this.headerScrollState = { scrollable: false, pageSize: 0 };
+			return content;
+		}
+
+		// Reserve one line for the scroll indicator.
+		const visible = Math.max(1, budget - 1);
+		const maxOffset = Math.max(0, content.length - visible);
+		const offset = Math.max(0, Math.min(this.headerScrollOffset, maxOffset));
+		this.headerScrollOffset = offset;
+		this.headerScrollState = { scrollable: true, pageSize: Math.max(1, visible - 1) };
+
+		const window = content.slice(offset, offset + visible);
+		const aboveCount = offset;
+		const belowCount = content.length - (offset + visible);
+		const parts: string[] = [];
+		if (aboveCount > 0) {
+			parts.push(`↑ ${aboveCount} line${aboveCount === 1 ? "" : "s"} above`);
+		}
+		if (belowCount > 0) {
+			parts.push(`↓ ${belowCount} line${belowCount === 1 ? "" : "s"} below`);
+		}
+		parts.push("pgup/pgdn scroll");
+		const indicator = this.theme.fg("dim", truncateToWidth(`  ${parts.join(" · ")}`, width, ""));
+		return [...window, indicator];
+	}
+
+	private measureModeRegion(width: number): number {
+		if (this.mode === "select") {
+			// Unclamped measurement: let the list render every row it wants.
+			const list = this.allowMultiple ? this.ensureMultiSelectList() : this.ensureSingleSelectList();
+			list.setMaxVisibleRows(Number.POSITIVE_INFINITY);
+			return list.render(width).length;
+		}
+		return this.modeComponents.reduce((count, component) => count + component.render(width).length, 0);
 	}
 
-	private countWrappedLines(text: string, width: number): number {
-		return Math.max(1, wrapTextWithAnsi(text, Math.max(10, width - 2)).length);
+	private renderModeRegion(width: number, budget: number): string[] {
+		if (this.mode === "select") {
+			const list = this.allowMultiple ? this.ensureMultiSelectList() : this.ensureSingleSelectList();
+			list.setMaxVisibleRows(Math.max(1, budget));
+			return list.render(width);
+		}
+		return this.modeComponents.flatMap((component) => component.render(width));
 	}
 
-	private countStaticLines(width: number): number {
-		const titleLines = 1;
-		const questionLines = this.countWrappedLines(this.question, width);
-		const contextLines = this.context ? 1 + this.countWrappedLines(this.context, width) : 0;
-		const helpLines = 1;
-		const borderLines = 2;
-		const spacerLines = this.context ? 6 : 5;
-		return borderLines + spacerLines + titleLines + questionLines + contextLines + helpLines;
+	private scrollHeader(delta: number): void {
+		if (!this.headerScrollState.scrollable) return;
+		this.headerScrollOffset = Math.max(0, this.headerScrollOffset + delta);
+		// Re-clamped to the valid range on the next render.
+		this.invalidate();
+		this.tui.requestRender();
 	}
 
 	private updateStaticText(): void {
@@ -1370,6 +1474,16 @@ class AskComponent extends Container {
 		}
 	}
 
+	private setModeComponents(components: Component[]): void {
+		for (const component of this.modeComponents) {
+			this.removeChild(component);
+		}
+		this.modeComponents = components;
+		for (const component of components) {
+			this.addChild(component);
+		}
+	}
+
 	private showSelectMode(): void {
 		if (this.mode === "freeform" || this.mode === "comment") {
 			this.saveEditorDraft();
@@ -1377,12 +1491,11 @@ class AskComponent extends Container {
 
 		this.mode = "select";
 		this.pendingSelections = [];
-		this.modeContainer.clear();
 
 		if (this.allowMultiple) {
-			this.modeContainer.addChild(this.ensureMultiSelectList());
+			this.setModeComponents([this.ensureMultiSelectList()]);
 		} else {
-			this.modeContainer.addChild(this.ensureSingleSelectList());
+			this.setModeComponents([this.ensureSingleSelectList()]);
 		}
 
 		this.updateHelpText();
@@ -1396,16 +1509,17 @@ class AskComponent extends Container {
 		}
 
 		this.mode = "freeform";
-		this.modeContainer.clear();
 
 		const editor = this.ensureEditor();
 		this.setEditorText(this.freeformDraft);
 		// biome-ignore lint/suspicious/noExplicitAny: Editor.focused setter is internal
 		(editor as any).focused = this._focused;
 
-		this.modeContainer.addChild(new Text(this.theme.fg("accent", this.theme.bold("Custom response")), 1, 0));
-		this.modeContainer.addChild(new Spacer(1));
-		this.modeContainer.addChild(editor);
+		this.setModeComponents([
+			new Text(this.theme.fg("accent", this.theme.bold("Custom response")), 1, 0),
+			new Spacer(1),
+			editor,
+		]);
 
 		this.updateHelpText();
 		this.invalidate();
@@ -1418,7 +1532,6 @@ class AskComponent extends Container {
 		}
 
 		this.mode = "comment";
-		this.modeContainer.clear();
 
 		const editor = this.ensureEditor();
 		this.setEditorText(this.commentDraft);
@@ -1426,10 +1539,12 @@ class AskComponent extends Container {
 		(editor as any).focused = this._focused;
 
 		const selectedLabel = this.pendingSelections.length === 1 ? "Selected option:" : "Selected options:";
-		this.modeContainer.addChild(new Text(this.theme.fg("accent", this.theme.bold(selectedLabel)), 1, 0));
-		this.modeContainer.addChild(new Text(this.theme.fg("text", this.pendingSelections.join(", ")), 1, 0));
-		this.modeContainer.addChild(new Spacer(1));
-		this.modeContainer.addChild(editor);
+		this.setModeComponents([
+			new Text(this.theme.fg("accent", this.theme.bold(selectedLabel)), 1, 0),
+			new Text(this.theme.fg("text", this.pendingSelections.join(", ")), 1, 0),
+			new Spacer(1),
+			editor,
+		]);
 
 		this.updateHelpText();
 		this.invalidate();
@@ -1437,6 +1552,19 @@ class AskComponent extends Container {
 	}
 
 	handleInput(data: string): void {
+		// Scroll the clamped question/context viewport. Only in select mode:
+		// the editor owns pageUp/pageDown in freeform/comment modes.
+		if (this.mode === "select" && this.headerScrollState.scrollable) {
+			if (matchesKey(data, Key.pageUp)) {
+				this.scrollHeader(-this.headerScrollState.pageSize);
+				return;
+			}
+			if (matchesKey(data, Key.pageDown)) {
+				this.scrollHeader(this.headerScrollState.pageSize);
+				return;
+			}
+		}
+
 		if (this.mode === "freeform" || this.mode === "comment") {
 			if (matchesKey(data, Key.escape)) {
 				this.showSelectMode();
@@ -1534,15 +1662,12 @@ export default function (pi: ExtensionAPI) {
 	pi.registerTool({
 		name: "ask_user",
 		label: "Ask User",
-		description:
-			"Ask the user a question with optional multiple-choice answers. Use this to gather information interactively. Ask exactly one focused question per call. Before calling, gather context with tools (read/web/ref) and pass a short summary via the context field.",
-		promptSnippet:
-			"Ask the user one focused question with optional multiple-choice answers to gather information interactively",
+		description: "Ask the user one focused question with optional multiple-choice answers.",
+		promptSnippet: "Ask the user one focused question with optional multiple-choice answers",
 		promptGuidelines: [
-			"Before calling ask_user, gather context with tools (read/web/ref) and pass a short summary via the context field.",
+			"Before calling ask_user, gather context with your read/search/web tools and pass a short summary via the context field.",
 			"Use ask_user when the user's intent is ambiguous, when a decision requires explicit user input, or when multiple valid options exist.",
-			"Ask exactly one focused question per ask_user call.",
-			"Do not combine multiple numbered, multipart, or unrelated questions into one ask_user prompt.",
+			"Ask exactly one focused question per ask_user call — never combine multiple, numbered, or unrelated questions in one prompt.",
 		],
 		// Block other tool calls in the same assistant turn until the user answers,
 		// so the model can't batch ask_user with bash/edit/write and let those run
@@ -1572,27 +1697,11 @@ export default function (pi: ExtensionAPI) {
 			allowComment: Type.Optional(
 				Type.Boolean({ description: "Collect an optional comment after selecting one or more options. Default: true" }),
 			),
-			displayMode: Type.Optional(
-				StringEnum(["overlay", "inline"] as const, {
-					description:
-						"UI rendering mode. 'overlay' shows a centered modal, 'inline' renders in-place. Default: PI_ASK_USER_DISPLAY_MODE env var if set, otherwise 'overlay'. Omit to respect the user's configured preference.",
-				}),
-			),
-			overlayToggleKey: Type.Optional(
-				Type.String({
-					description:
-						"Shortcut for hiding/showing the overlay popup (overlay mode only), e.g. 'alt+o' or 'ctrl+shift+h'. Pass 'off' to disable. Default: PI_ASK_USER_OVERLAY_TOGGLE_KEY env var if set, otherwise 'alt+o'.",
-				}),
-			),
-			commentToggleKey: Type.Optional(
-				Type.String({
-					description:
-						"Shortcut for toggling the optional comment/extra-context row when allowComment is true, e.g. 'ctrl+g'. Pass 'off' to disable. Default: PI_ASK_USER_COMMENT_TOGGLE_KEY env var if set, otherwise 'ctrl+g'.",
-				}),
-			),
-			timeout: Type.Optional(
-				Type.Number({ description: "Auto-dismiss after N milliseconds. Returns null (cancelled) when expired." }),
-			),
+			// 外观类选项（displayMode / overlayToggleKey / commentToggleKey）不再暴露给模型：
+			// 它们是**用户偏好**，优先级为 模型参数 > env > ask-user.json > 默认值，模型能直接
+			// 盖掉用户的设置，且占了 782 字符的 schema。取值改由 env（PI_ASK_USER_DISPLAY_MODE 等）
+			// 与 ask-user.json 提供，内部解析链与 `AskParams` 类型保留（SDK/内部调用仍可传）。
+			timeout: Type.Optional(Type.Number({ description: "Auto-dismiss after N ms; returns null when expired." })),
 		}),
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {

package/package.json

@@ -3,7 +3,7 @@
 	"publishConfig": {
 		"access": "public"
 	},
-	"version": "0.3.0",
+	"version": "0.4.1",
 	"description": "Interactive ask_user tool for pi-coding-agent with searchable split-pane selection UI, multi-select, and freeform input",
 	"license": "MIT",
 	"repository": {
@@ -41,10 +41,10 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@biomejs/biome": "^2.5.14",
-		"@types/node": "^26.6.2",
-		"typebox": "^1.3.34",
+		"@biomejs/biome": "^2.6.4",
+		"@types/node": "^26.6.6",
+		"typebox": "^1.4.3",
 		"typescript": "~7.0.2",
-		"vitest": "^5.0.1"
+		"vitest": "^5.0.5"
 	}
 }

package/src/single-select-layout.ts

@@ -66,7 +66,6 @@ function wrapText(text: string, width: number): string[] {
 function padLine(prefix: string, content: string): string {
 	return `${prefix}${content}`.trimEnd();
 }
-
 interface ItemBlock {
 	itemIndex: number;
 	lines: string[];
@@ -129,46 +128,37 @@ function buildItemBlocks(
 	});
 }
 
-function flatten(blocks: ItemBlock[], selectedIndex: number): AnnotatedRow[] {
-	return blocks.flatMap((block) =>
-		block.lines.map((line) => ({
-			line,
-			selected: block.itemIndex === selectedIndex,
-		})),
-	);
+export interface SelectableBlock {
+	lines: string[];
+	selected: boolean;
 }
 
-export function renderSingleSelectRows({
-	options,
-	selectedIndex,
-	width,
-	allowFreeform,
-	allowComment = false,
-	commentEnabled = false,
-	maxRows,
-	hideDescriptions,
-}: RenderSingleSelectRowsParams): AnnotatedRow[] {
-	const itemCount = options.length + (allowComment ? 1 : 0) + (allowFreeform ? 1 : 0);
-	const blocks = buildItemBlocks(
-		options,
-		width,
-		allowFreeform,
-		allowComment,
-		commentEnabled,
-		selectedIndex,
-		hideDescriptions,
-	);
-	const allRows = flatten(blocks, selectedIndex);
+export interface WindowSelectedBlocksParams {
+	blocks: SelectableBlock[];
+	maxRows: number;
+	indicator: string;
+}
 
-	if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || allRows.length <= maxRows) {
-		return allRows;
+/**
+ * Window pre-rendered blocks around the selected one so the total row count
+ * stays within `maxRows`. When everything fits, all rows are returned as-is;
+ * otherwise the selected block is kept visible, neighbouring blocks fill the
+ * remaining space, and a single indicator row (e.g. "  (3/12)") is appended.
+ */
+export function windowSelectedBlocks({ blocks, maxRows, indicator }: WindowSelectedBlocksParams): AnnotatedRow[] {
+	const totalRows = blocks.reduce((count, block) => count + block.lines.length, 0);
+	if (!Number.isFinite(maxRows) || !maxRows || maxRows <= 0 || totalRows <= maxRows) {
+		return blocks.flatMap((block) => block.lines.map((line) => ({ line, selected: block.selected })));
 	}
 
 	const safeMaxRows = Math.max(1, Math.floor(maxRows));
-	const selectedBlock = blocks[selectedIndex] ?? blocks[0];
+	const selectedIndex = Math.max(
+		blocks.findIndex((block) => block.selected),
+		0,
+	);
+	const selectedBlock = blocks[selectedIndex];
 	if (!selectedBlock) return [];
 
-	const indicator = `  (${selectedIndex + 1}/${itemCount})`;
 	const availableRows = safeMaxRows > 1 ? safeMaxRows - 1 : 1;
 
 	if (selectedBlock.lines.length >= availableRows) {
@@ -181,7 +171,7 @@ export function renderSingleSelectRows({
 	}
 
 	let start = selectedIndex;
-	let end = selectedIndex + 1;
+	let end = start + 1;
 	let usedRows = selectedBlock.lines.length;
 
 	while (true) {
@@ -202,7 +192,37 @@ export function renderSingleSelectRows({
 		break;
 	}
 
-	const visible = flatten(blocks.slice(start, end), selectedIndex);
+	const visible = blocks
+		.slice(start, end)
+		.flatMap((block) => block.lines.map((line) => ({ line, selected: block.selected })));
 	visible.push({ line: indicator, selected: false });
 	return visible.slice(0, safeMaxRows);
 }
+
+export function renderSingleSelectRows({
+	options,
+	selectedIndex,
+	width,
+	allowFreeform,
+	allowComment = false,
+	commentEnabled = false,
+	maxRows,
+	hideDescriptions,
+}: RenderSingleSelectRowsParams): AnnotatedRow[] {
+	const itemCount = options.length + (allowComment ? 1 : 0) + (allowFreeform ? 1 : 0);
+	const blocks = buildItemBlocks(
+		options,
+		width,
+		allowFreeform,
+		allowComment,
+		commentEnabled,
+		selectedIndex,
+		hideDescriptions,
+	);
+
+	return windowSelectedBlocks({
+		blocks: blocks.map((block) => ({ lines: block.lines, selected: block.itemIndex === selectedIndex })),
+		maxRows: maxRows ?? Number.POSITIVE_INFINITY,
+		indicator: `  (${selectedIndex + 1}/${itemCount})`,
+	});
+}