@sayknow-cli/coding-agent 0.3.5 → 0.3.7

package/src/modes/components/welcome.ts

@@ -15,6 +15,12 @@ export interface LspServerInfo {
 }
 
 export type WelcomeLogoMode = "unicode" | "square" | "ascii";
+export interface WelcomeComponentOptions {
+	getViewportRows?: () => number | undefined;
+	getReservedBottomRows?: (termWidth: number) => number;
+	changelogMarkdown?: string;
+	collapseChangelog?: boolean;
+}
 
 /**
  * Sayknow-CLI launch surface: a blue-gradient SAYKNOW wordmark, compact
@@ -32,6 +38,7 @@ export class WelcomeComponent implements Component {
 		private recentSessions: RecentSession[] = [],
 		private lspServers: LspServerInfo[] = [],
 		private readonly logoMode: WelcomeLogoMode = "unicode",
+		private readonly options: WelcomeComponentOptions = {},
 	) {}
 
 	invalidate(): void {}
@@ -52,6 +59,11 @@ export class WelcomeComponent implements Component {
 			}
 			requestRender();
 		}, INTRO_TICK_MS);
+		this.#animTimer.unref?.();
+	}
+
+	dispose(): void {
+		this.#stopAnimation();
 	}
 
 	#stopAnimation(): void {
@@ -76,15 +88,20 @@ export class WelcomeComponent implements Component {
 	}
 
 	render(termWidth: number): string[] {
-		// Box dimensions track the live viewport so wide terminals feel intentionally full-screen.
-		const boxWidth = Math.max(0, termWidth - 2);
+		const boxWidth = Math.max(0, termWidth);
 		if (boxWidth < 4) {
 			return [];
 		}
+
+		const targetRows = this.#targetRows(termWidth);
+		if (targetRows !== undefined && targetRows <= 0) {
+			return [];
+		}
+		const targetContentRows = targetRows === undefined ? undefined : Math.max(0, targetRows - 2);
 		const dualContentWidth = boxWidth - 3; // 3 = │ + │ + │
-		const preferredLeftCol = 36;
-		const minLeftCol = 18; // wordmark plus Sayknow identity labels
-		const minRightCol = 20;
+		const preferredLeftCol = 40;
+		const minLeftCol = 20; // wordmark plus Sayknow identity labels
+		const minRightCol = 24;
 		const modelPill = this.#pill(theme.icon.model || "model", this.modelName, "statusLineModel");
 		const providerPill = this.#pill(theme.icon.package || "provider", this.providerName, "statusLinePath");
 		const logoLines = this.#logoLines();
@@ -130,24 +147,23 @@ export class WelcomeComponent implements Component {
 			...identityTail,
 		];
 
-		// Right column separator
-		const separatorWidth = Math.max(0, rightCol - 2); // padding on each side
-		const separator = ` ${theme.fg("dim", theme.boxRound.horizontal.repeat(separatorWidth))}`;
+		const buildSeparator = (columnWidth: number): string =>
+			` ${theme.fg("dim", theme.boxRound.horizontal.repeat(Math.max(0, columnWidth - 2)))}`;
+
+		const rightColumnWidth = showRightColumn ? rightCol : leftCol;
+		const separator = buildSeparator(rightColumnWidth);
+		const changelogBudget = Math.max(1, Math.min(6, Math.floor((targetContentRows ?? 18) * 0.3)));
 
-		// Recent sessions content
 		const sessionLines: string[] = [];
 		if (this.recentSessions.length === 0) {
 			sessionLines.push(` ${theme.fg("dim", t("welcome.noSessions"))}`);
 		} else {
-			// Reserve width for the bullet prefix (" • ") and the trailing " (timeAgo)"
-			// so the relative time is never the part that gets truncated. The name
-			// absorbs whatever space is left.
 			const bulletPrefix = ` ${theme.md.bullet} `;
 			const prefixWidth = visibleWidth(bulletPrefix);
 			for (const session of this.recentSessions.slice(0, 3)) {
 				const timeSuffixRaw = ` (${session.timeAgo})`;
 				const timeWidth = visibleWidth(timeSuffixRaw);
-				const nameBudget = Math.max(1, rightCol - prefixWidth - timeWidth);
+				const nameBudget = Math.max(1, rightColumnWidth - prefixWidth - timeWidth);
 				const nameVis = visibleWidth(session.name);
 				const name = nameVis > nameBudget ? truncateToWidth(session.name, nameBudget) : session.name;
 				sessionLines.push(
@@ -156,12 +172,11 @@ export class WelcomeComponent implements Component {
 			}
 		}
 
-		// LSP servers content
 		const lspLines: string[] = [];
 		if (this.lspServers.length === 0) {
 			lspLines.push(` ${theme.fg("dim", t("welcome.noLsp"))}`);
 		} else {
-			for (const server of this.lspServers) {
+			for (const server of this.lspServers.slice(0, 4)) {
 				const icon =
 					server.status === "ready"
 						? theme.styledSymbol("status.success", "success")
@@ -179,8 +194,11 @@ export class WelcomeComponent implements Component {
 			return ` ${theme.fg("accent", cmd)}${pad}${theme.fg("muted", desc)}`;
 		};
 
-		// Right column
 		const rightLines = [
+			"",
+			` ${theme.bold(theme.fg("accent", "What's New"))}`,
+			...this.#whatsNewLines(rightColumnWidth, changelogBudget),
+			separator,
 			` ${theme.bold(theme.fg("accent", t("welcome.workflows")))}`,
 			wf("/deep-interview", t("welcome.wf.deepInterview")),
 			wf("/ralplan", t("welcome.wf.ralplan")),
@@ -210,7 +228,12 @@ export class WelcomeComponent implements Component {
 			"",
 		];
 
-		// Border characters (dim)
+		const contentRows =
+			targetContentRows ??
+			(showRightColumn ? Math.max(leftLines.length, rightLines.length) : leftLines.length + rightLines.length);
+		const outputRows = targetRows === undefined ? Math.max(3, contentRows + 2) : targetRows;
+		const bodyRows = Math.max(0, outputRows - 2);
+
 		const hChar = theme.boxRound.horizontal;
 		const h = theme.fg("dim", hChar);
 		const v = theme.fg("dim", theme.boxRound.vertical);
@@ -220,8 +243,6 @@ export class WelcomeComponent implements Component {
 		const br = theme.fg("dim", theme.boxRound.bottomRight);
 
 		const lines: string[] = [];
-
-		// Top border with embedded title
 		const title = ` ${APP_NAME} · Sayknow-CLI v${this.version} `;
 		const titlePrefixRaw = hChar.repeat(3);
 		const titleStyled = theme.fg("dim", titlePrefixRaw) + theme.fg("muted", title);
@@ -233,22 +254,32 @@ export class WelcomeComponent implements Component {
 			const afterTitle = titleSpace - titleVisLen;
 			lines.push(tl + titleStyled + theme.fg("dim", hChar.repeat(afterTitle)) + tr);
 		}
+		if (outputRows === 1) {
+			return lines;
+		}
 
-		// Content rows
-		const maxRows = showRightColumn ? Math.max(leftLines.length, rightLines.length) : leftLines.length;
-		for (let i = 0; i < maxRows; i++) {
-			const left = this.#fitToWidth(leftLines[i] ?? "", leftCol);
-			if (showRightColumn) {
-				const right = this.#fitToWidth(rightLines[i] ?? "", rightCol);
+		if (showRightColumn) {
+			const leftBlock = this.#fitBlock(leftLines, bodyRows, "center");
+			const rightBlock = this.#fitBlock(rightLines, bodyRows, "top");
+			for (let i = 0; i < bodyRows; i++) {
+				const left = this.#fitToWidth(leftBlock[i] ?? "", leftCol);
+				const right = this.#fitToWidth(rightBlock[i] ?? "", rightCol);
 				lines.push(v + left + v + right + v);
-			} else {
-				lines.push(v + left + v);
 			}
-		}
-		// Bottom border
-		if (showRightColumn) {
 			lines.push(bl + h.repeat(leftCol) + theme.fg("dim", theme.boxSharp.teeUp) + h.repeat(rightCol) + br);
 		} else {
+			const compactLeftLines =
+				bodyRows < 14
+					? [
+							this.#centerText(theme.bold(theme.fg("accent", "SKC Forge")), leftCol),
+							this.#centerText(this.#loadingLine(), leftCol),
+							this.#centerText(modelPill, leftCol),
+						]
+					: leftLines;
+			const singleBlock = this.#fitBlock([...compactLeftLines, separator, ...rightLines], bodyRows, "top");
+			for (let i = 0; i < bodyRows; i++) {
+				lines.push(v + this.#fitToWidth(singleBlock[i] ?? "", leftCol) + v);
+			}
 			lines.push(bl + h.repeat(leftCol) + br);
 		}
 
@@ -274,6 +305,110 @@ export class WelcomeComponent implements Component {
 		}
 		return str + padding(width - visLen);
 	}
+	#targetRows(termWidth: number): number | undefined {
+		const viewportRows = this.options.getViewportRows?.();
+		if (typeof viewportRows !== "number" || !Number.isFinite(viewportRows) || viewportRows <= 0) {
+			return undefined;
+		}
+		const reservedRows = Math.max(0, Math.floor(this.options.getReservedBottomRows?.(termWidth) ?? 0));
+		return Math.max(0, Math.floor(viewportRows) - reservedRows);
+	}
+
+	#loadingLine(): string {
+		const frames = theme.spinnerFrames;
+		const elapsed = this.#animStart == null ? 0 : performance.now() - this.#animStart;
+		const frame = frames.length > 0 ? (frames[Math.floor(elapsed / 100) % frames.length] ?? "*") : "*";
+		const label = this.#animStart == null ? "ready" : "warming workspace";
+		return `${theme.fg("warning", frame)} ${theme.fg("muted", label)}`;
+	}
+
+	#fitBlock(lines: string[], rows: number, align: "top" | "center"): string[] {
+		if (rows <= 0) return [];
+		const clipped =
+			lines.length > rows
+				? rows === 1
+					? [theme.fg("dim", " …")]
+					: [...lines.slice(0, rows - 1), theme.fg("dim", " …")]
+				: lines;
+		const missingRows = rows - clipped.length;
+		if (missingRows <= 0) return clipped;
+		const topPad = align === "center" ? Math.floor(missingRows / 2) : 0;
+		const bottomPad = missingRows - topPad;
+		return [...Array.from({ length: topPad }, () => ""), ...clipped, ...Array.from({ length: bottomPad }, () => "")];
+	}
+
+	#whatsNewLines(width: number, maxItems: number): string[] {
+		const changelog = this.options.changelogMarkdown?.trim();
+		if (!changelog) {
+			return [` ${theme.fg("dim", "Ready for your next prompt")}`];
+		}
+
+		const version = this.#latestChangelogVersion(changelog);
+		if (this.options.collapseChangelog) {
+			return [
+				` ${theme.fg("muted", `Updated to v${version}`)}`,
+				` ${theme.fg("dim", `Use ${theme.bold("/changelog")} for details`)}`,
+			];
+		}
+
+		const itemLimit = Math.max(1, Math.floor(maxItems));
+		const items = this.#changelogItems(changelog);
+		if (items.length === 0) {
+			return [
+				` ${theme.fg("muted", `Updated to v${version}`)}`,
+				` ${theme.fg("dim", `Use ${theme.bold("/changelog")} for details`)}`,
+			];
+		}
+
+		const prefix = ` ${theme.md.bullet} `;
+		const textWidth = Math.max(1, width - visibleWidth(prefix));
+		const visibleItems = items.slice(0, itemLimit).map(item => {
+			const text = visibleWidth(item) > textWidth ? truncateToWidth(item, textWidth) : item;
+			return `${theme.fg("dim", prefix)}${theme.fg("muted", text)}`;
+		});
+		if (items.length > visibleItems.length) {
+			visibleItems.push(` ${theme.fg("dim", `… ${theme.bold("/changelog")} for full notes`)}`);
+		}
+		return visibleItems;
+	}
+
+	#latestChangelogVersion(markdown: string): string {
+		const versionMatch = markdown.match(/##\s+\[?(\d+\.\d+\.\d+)\]?/);
+		return versionMatch?.[1] ?? this.version;
+	}
+
+	#changelogItems(markdown: string): string[] {
+		const items: string[] = [];
+		let inFence = false;
+		for (const rawLine of markdown.split(/\r?\n/)) {
+			const line = rawLine.trim();
+			if (line.startsWith("```")) {
+				inFence = !inFence;
+				continue;
+			}
+			if (inFence || !line || /^#{1,6}\s+/.test(line) || /^-{3,}$/.test(line)) {
+				continue;
+			}
+			const withoutBullet = line
+				.replace(/^[-*]\s+/, "")
+				.replace(/^\d+\.\s+/, "")
+				.replace(/^>\s*/, "");
+			const cleaned = this.#stripMarkdown(withoutBullet);
+			if (cleaned) items.push(cleaned);
+		}
+		return items;
+	}
+
+	#stripMarkdown(text: string): string {
+		return text
+			.replace(/`([^`]+)`/g, "$1")
+			.replace(/\[([^\]]+)\]\([^)]+\)/g, "$1")
+			.replace(/\*\*([^*]+)\*\*/g, "$1")
+			.replace(/__([^_]+)__/g, "$1")
+			.replace(/\*([^*]+)\*/g, "$1")
+			.replace(/[_~]/g, "")
+			.trim();
+	}
 
 	#pill(icon: string, text: string, color: ThemeColor): string {
 		return `${theme.fg("borderMuted", "[")} ${theme.fg(color, icon)} ${theme.fg("muted", text)} ${theme.fg(

package/src/modes/controllers/command-controller.ts

@@ -556,6 +556,29 @@ export class CommandController {
 		showMarkdownPanel(this.ctx, "Keyboard Shortcuts", hotkeys);
 	}
 
+	handleHelpCommand(): void {
+		const sessionNewKey = this.ctx.keybindings.getDisplayString("app.session.new") || "/new";
+		const markdown = [
+			"**Beginner actions**",
+			"",
+			"| Action | How |",
+			"|---|---|",
+			`| Start a fresh session | \`${sessionNewKey}\` or \`/new\` |`,
+			"| Resume another session | `/resume` |",
+			"| Show session details | `/session info` |",
+			"| Delete current session | `/session delete` |",
+			"| Select a model | `/model` or `Ctrl+L` |",
+			"| Show all shortcuts | `?` on an empty prompt or `/hotkeys` |",
+			"",
+			"**Finding commands**",
+			"",
+			"- Type `/` to browse slash commands, then use arrows and Enter/Tab.",
+			"- Type `#` to browse prompt actions like starting a session, pasting an image, or moving the cursor.",
+			"- Type `!` for shell commands and `$` for Python snippets.",
+		].join("\n");
+		showMarkdownPanel(this.ctx, "SKC Help", markdown);
+	}
+
 	handleToolsCommand(): void {
 		const tools = buildToolsMarkdown({ tools: this.ctx.session.agent.state.tools });
 		showMarkdownPanel(this.ctx, "Available Tools", tools);
@@ -1253,17 +1276,18 @@ export class CommandController {
 	async handleContributionPrepCommand(customInstructions?: string): Promise<void> {
 		this.ctx.editor.setText("");
 		try {
-			const result = await this.ctx.session.prepareContributionPrep({ customInstructions, spawnWorker: true });
+			const result = await this.ctx.session.prepareContributionPrep({ customInstructions, spawnWorker: false });
 			this.ctx.showStatus(
 				[
 					"Contribution prep artifacts written.",
 					`Manifest: ${result.manifestPath}`,
 					`Worker prompt: ${result.workerPromptPath}`,
+					"Open the worker prompt from a separate terminal to keep this TUI session stable.",
 				].join("\n"),
 			);
 			this.ctx.chatContainer.addChild(
 				new Text(
-					`${theme.fg("accent", `${theme.status.success} Contribution prep ready`)}\nManifest: ${result.manifestPath}`,
+					`${theme.fg("accent", `${theme.status.success} Contribution prep ready`)}\nWorker prompt: ${result.workerPromptPath}`,
 					1,
 					1,
 				),

package/src/modes/controllers/event-controller.ts

@@ -3,6 +3,7 @@ import { calculatePromptTokens } from "@sayknow-cli/agent-core/compaction/compac
 import type { AssistantMessage, ImageContent } from "@sayknow-cli/ai";
 import { parseRateLimitReason } from "@sayknow-cli/ai";
 import { type Component, Loader, TERMINAL, Text } from "@sayknow-cli/tui";
+import { logger } from "@sayknow-cli/utils";
 import { settings } from "../../config/settings";
 import { AssistantMessageComponent } from "../../modes/components/assistant-message";
 import {
@@ -15,16 +16,56 @@ import { ToolExecutionComponent } from "../../modes/components/tool-execution";
 import { TtsrNotificationComponent } from "../../modes/components/ttsr-notification";
 import { getSymbolTheme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext, TodoPhase } from "../../modes/types";
+import { summaryFromMessage } from "../../notifications/helpers";
 import type { PlanApprovalDetails } from "../../plan-mode/approved-plan";
 import type { AgentSessionEvent } from "../../session/agent-session";
 import { isSilentAbort, readPendingDisplayTag } from "../../session/messages";
 import type { ResolveToolDetails } from "../../tools/resolve";
 import { interruptHint } from "../shared";
 import { buildAbortDisplayMessage } from "../utils/abort-message";
+import { ringTerminalBell } from "../utils/terminal-bell";
 
 type AgentSessionEventKind = AgentSessionEvent["type"];
 
 const IRC_MESSAGE_VISIBLE_TTL_MS = 10_000;
+const COMPLETION_NOTIFY_COMMAND_TIMEOUT_MS = 10_000;
+
+interface CompletionNotifyPayload {
+	type: "agent-turn-complete";
+	title: string;
+	body: string;
+	cwd: string;
+	sessionId?: string;
+	sessionName?: string;
+	lastAssistantMessage?: string;
+	stopReason?: string;
+}
+
+function completionNotifyShellCommand(command: string): string[] {
+	if (process.platform === "win32") {
+		return ["cmd.exe", "/d", "/s", "/c", command];
+	}
+	return ["/bin/sh", "-c", command];
+}
+
+function cleanNotificationEnvValue(value: string | undefined, max = 4000): string {
+	if (!value) return "";
+	return value.replaceAll("\0", "").slice(0, max);
+}
+
+function buildCompletionNotifyEnv(payload: CompletionNotifyPayload): Record<string, string> {
+	return {
+		SKC_NOTIFICATION_TYPE: payload.type,
+		SKC_NOTIFICATION_TITLE: cleanNotificationEnvValue(payload.title, 500),
+		SKC_NOTIFICATION_BODY: cleanNotificationEnvValue(payload.body),
+		SKC_NOTIFICATION_CWD: cleanNotificationEnvValue(payload.cwd, 2000),
+		SKC_NOTIFICATION_SESSION_ID: cleanNotificationEnvValue(payload.sessionId, 500),
+		SKC_NOTIFICATION_SESSION_NAME: cleanNotificationEnvValue(payload.sessionName, 500),
+		SKC_NOTIFICATION_LAST_ASSISTANT_MESSAGE: cleanNotificationEnvValue(payload.lastAssistantMessage),
+		SKC_NOTIFICATION_STOP_REASON: cleanNotificationEnvValue(payload.stopReason, 100),
+		SKC_NOTIFICATION_JSON: cleanNotificationEnvValue(JSON.stringify(payload), 8000),
+	};
+}
 
 function friendlyRetryReason(errorMessage: string | undefined): string {
 	if (!errorMessage) return "";
@@ -97,6 +138,7 @@ export class EventController {
 			this.ctx.editor.onEscape = this.ctx.retryEscapeHandler;
 			this.ctx.retryEscapeHandler = undefined;
 		}
+		this.ctx.retryEscapePrimed = false;
 		if (this.ctx.retryLoader) {
 			this.ctx.retryLoader.stop();
 			this.ctx.retryLoader = undefined;
@@ -200,6 +242,7 @@ export class EventController {
 			this.ctx.retryLoader = undefined;
 			this.ctx.statusContainer.clear();
 		}
+		this.ctx.retryEscapePrimed = false;
 		this.#cancelIdleCompaction();
 		this.ctx.updateEditorBorderColor();
 		this.ctx.ensureLoadingAnimation();
@@ -727,6 +770,7 @@ export class EventController {
 		if (!this.ctx.retryEscapeHandler) {
 			this.ctx.retryEscapeHandler = this.ctx.editor.onEscape;
 		}
+		this.ctx.retryEscapePrimed = false;
 		let escPressed = false;
 		this.ctx.editor.onEscape = () => {
 			if (!escPressed) {
@@ -777,6 +821,7 @@ export class EventController {
 			this.ctx.retryLoader = undefined;
 			this.ctx.statusContainer.clear();
 		}
+		this.ctx.retryEscapePrimed = false;
 		if (!event.success) {
 			this.ctx.showError(`Retry failed after ${event.attempt} attempts: ${event.finalError || "Unknown error"}`);
 		}
@@ -857,8 +902,46 @@ export class EventController {
 		return lastAssistant?.usage ? calculatePromptTokens(lastAssistant.usage) : 0;
 	}
 
+	#runCompletionNotifyCommand(payload: CompletionNotifyPayload): void {
+		const command = settings.getGlobal("completion.notifyCommand")?.trim();
+		if (!command) return;
+
+		try {
+			const proc = Bun.spawn(completionNotifyShellCommand(command), {
+				cwd: payload.cwd,
+				env: {
+					...process.env,
+					...buildCompletionNotifyEnv(payload),
+				},
+				stdin: "ignore",
+				stdout: "ignore",
+				stderr: "ignore",
+			});
+			proc.unref();
+			const timer = setTimeout(() => {
+				try {
+					proc.kill();
+				} catch {}
+			}, COMPLETION_NOTIFY_COMMAND_TIMEOUT_MS);
+			timer.unref?.();
+			void proc.exited
+				.then(exitCode => {
+					clearTimeout(timer);
+					if (exitCode !== 0) {
+						logger.warn("completion notify command exited non-zero", { exitCode });
+					}
+				})
+				.catch(error => {
+					clearTimeout(timer);
+					logger.warn("completion notify command failed", { error: String(error) });
+				});
+		} catch (error) {
+			logger.warn("completion notify command failed to start", { error: String(error) });
+		}
+	}
+
 	sendCompletionNotification(): void {
-		if (this.ctx.isBackgrounded === false) return;
+		const isBackgrounded = this.ctx.isBackgrounded !== false;
 		const notify = settings.get("completion.notify");
 		if (notify === "off") return;
 
@@ -869,9 +952,24 @@ export class EventController {
 		const last = this.ctx.session.getLastAssistantMessage?.();
 		if (last?.stopReason === "aborted" || last?.stopReason === "error") return;
 
-		const title = this.ctx.sessionManager.getSessionName();
-		const message = title ? `${title}: Complete` : "Complete";
-		TERMINAL.sendNotification(message);
+		const sessionName = this.ctx.sessionManager.getSessionName();
+		const title = sessionName ? `${sessionName}: Complete` : "Complete";
+		const summary = summaryFromMessage(last, 1000);
+		const body = summary ?? "Complete";
+		const sessionManager = this.ctx.sessionManager as { getCwd?: () => string; getSessionId?: () => string };
+		const payload: CompletionNotifyPayload = {
+			type: "agent-turn-complete",
+			title,
+			body,
+			cwd: sessionManager.getCwd?.() ?? settings.getCwd(),
+			sessionId: sessionManager.getSessionId?.(),
+			sessionName: sessionName || undefined,
+			lastAssistantMessage: summary,
+			stopReason: last?.stopReason,
+		};
+		ringTerminalBell("complete");
+		if (isBackgrounded) TERMINAL.sendNotification(title);
+		this.#runCompletionNotifyCommand(payload);
 	}
 
 	async handleBackgroundEvent(event: AgentSessionEvent): Promise<void> {

package/src/modes/controllers/extension-ui-controller.ts

@@ -24,6 +24,7 @@ import { HookSelectorComponent } from "../../modes/components/hook-selector";
 import { getAvailableThemesWithPaths, getThemeByName, setTheme, type Theme, theme } from "../../modes/theme/theme";
 import type { InteractiveModeContext } from "../../modes/types";
 import { setSessionTerminalTitle, setTerminalTitle } from "../../utils/title-generator";
+import { classifyHookSelectorBellEvent, ringTerminalBell } from "../utils/terminal-bell";
 
 const MAX_WIDGET_LINES = 10;
 const HOOK_SELECTOR_CHROME_ROWS = 7;
@@ -617,12 +618,15 @@ export class ExtensionUiController {
 		const listChromeRows = dialogOptions?.outline === true ? HOOK_SELECTOR_OUTLINE_ROWS : 0;
 		// Reserve rows for the inline custom-input editor so opening it doesn't
 		// push the scrollable title past the viewport into terminal scrollback.
-		const inlineInputRows = dialogOptions?.customInput ? HOOK_SELECTOR_INLINE_INPUT_ROWS : 0;
+		const inlineInputRows =
+			dialogOptions?.customInput || dialogOptions?.clarificationInput ? HOOK_SELECTOR_INLINE_INPUT_ROWS : 0;
 		const availableTitleRows =
 			this.ctx.ui.terminal.rows - scrollOptionRows - listChromeRows - inlineInputRows - HOOK_SELECTOR_CHROME_ROWS;
 		const scrollTitleRows =
 			requestedTitleRows === undefined ? undefined : Math.max(1, Math.min(requestedTitleRows, availableTitleRows));
 
+		ringTerminalBell(classifyHookSelectorBellEvent(title));
+
 		this.ctx.hookSelector = new HookSelectorComponent(
 			title,
 			options,
@@ -657,7 +661,10 @@ export class ExtensionUiController {
 				tui: this.ctx.ui,
 				// Share the main prompt editor's autocomplete provider so the
 				// inline "Other (type your own)" editor supports `@` file links.
-				autocompleteProvider: dialogOptions?.customInput ? this.ctx.editor.getAutocompleteProvider() : undefined,
+				autocompleteProvider:
+					dialogOptions?.customInput || dialogOptions?.clarificationInput
+						? this.ctx.editor.getAutocompleteProvider()
+						: undefined,
 				outline: dialogOptions?.outline,
 				wrapFocused: dialogOptions?.wrapFocused,
 				scrollTitleRows,
@@ -673,6 +680,18 @@ export class ExtensionUiController {
 							},
 						}
 					: undefined,
+				clarificationInput: dialogOptions?.clarificationInput
+					? {
+							optionLabel: dialogOptions.clarificationInput.optionLabel,
+							allowEmpty: dialogOptions.clarificationInput.allowEmpty,
+							onSubmit: text => {
+								const optionLabel = dialogOptions.clarificationInput?.optionLabel;
+								this.hideHookSelector();
+								dialogOptions.clarificationInput?.onSubmit(text);
+								finish(optionLabel);
+							},
+						}
+					: undefined,
 			},
 		);
 		// Detach (not dispose) the reusable editor before mounting the transient hook UI, so the