@gajae-code/coding-agent 0.7.6 → 0.7.8

package/src/modes/components/status-line.ts

@@ -40,6 +40,7 @@ export interface StatusLineSettings {
 	rightSegments?: StatusLineSegmentId[];
 	separator?: StatusLineSeparatorStyle;
 	segmentOptions?: StatusLineSegmentOptions;
+	previewHighlightSegment?: StatusLineSegmentId;
 	showHookStatus?: boolean;
 	showSkillHud?: boolean;
 	sessionAccent?: boolean;
@@ -181,11 +182,8 @@ export class StatusLineComponent implements Component {
 	#lastTokensPerSecond: number | null = null;
 	#lastTokensPerSecondTimestamp: number | null = null;
 
-	// Anthropic usage caching (5-min TTL, OAuth/sub only)
-	#cachedUsage: {
-		fiveHour?: { percent: number; resetMinutes?: number };
-		sevenDay?: { percent: number; resetHours?: number };
-	} | null = null;
+	// Provider usage caching (5-min TTL, OAuth/sub only)
+	#cachedUsage: SegmentContext["usage"] = null;
 	#usageFetchedAt = 0;
 	#usageInFlight = false;
 	// Context breakdown — incremental cache. Replaces the previous 2-second
@@ -221,7 +219,7 @@ export class StatusLineComponent implements Component {
 	}
 
 	updateSettings(settings: StatusLineSettings): void {
-		this.#settings = { ...this.#settings, ...settings };
+		this.#settings = { ...this.#settings, previewHighlightSegment: undefined, ...settings };
 	}
 
 	setAutoCompactEnabled(enabled: boolean): void {
@@ -462,9 +460,9 @@ export class StatusLineComponent implements Component {
 	}
 
 	/**
-	 * Background-refresh the Anthropic OAuth quota report. Guarded by a 5-min
-	 * TTL on both success (cache lifetime) and error (backoff). Exposed
-	 * (non-private) so unit tests can verify the backoff invariant.
+	 * Background-refresh the OAuth quota report. Guarded by a 5-min TTL on both
+	 * success (cache lifetime) and error (backoff). Exposed (non-private) so
+	 * unit tests can verify the backoff invariant.
 	 */
 	refreshUsageInBackground(): void {
 		const now = Date.now();
@@ -478,6 +476,9 @@ export class StatusLineComponent implements Component {
 			.then(reports => {
 				this.#cachedUsage = this.#normalizeUsageReports(reports);
 				this.#usageFetchedAt = Date.now();
+				if (this.#onBranchChange) {
+					this.#onBranchChange();
+				}
 			})
 			.catch(() => {
 				// Backoff on error: stamp the fetch time so the 5-min TTL guard
@@ -491,47 +492,77 @@ export class StatusLineComponent implements Component {
 			});
 	}
 
-	#normalizeUsageReports(reports: unknown): {
-		fiveHour?: { percent: number; resetMinutes?: number };
-		sevenDay?: { percent: number; resetHours?: number };
-	} | null {
+	#normalizeUsageReports(reports: unknown): SegmentContext["usage"] {
 		if (!Array.isArray(reports)) return null;
-		let fiveHour: { percent: number; resetMinutes?: number } | undefined;
-		let sevenDay: { percent: number; resetHours?: number } | undefined;
+		const windows: NonNullable<SegmentContext["usage"]>["windows"] = [];
+		const seen = new Set<string>();
 		const now = Date.now();
+
+		const codexWindowLabel = (windowId: string | undefined, fallback: string): string => {
+			if (windowId && /^\d+[hd]$/.test(windowId)) return windowId;
+			return fallback;
+		};
+		const codexResetUnit = (label: string): "m" | "h" => (label.endsWith("d") ? "h" : "m");
+
+		const pushWindow = (
+			key: string,
+			label: string,
+			fraction: number,
+			resetsAt: number | undefined,
+			resetUnit: "m" | "h",
+		) => {
+			if (seen.has(key)) return;
+			seen.add(key);
+			windows.push({
+				label,
+				percent: fraction * 100,
+				resetValue:
+					typeof resetsAt === "number"
+						? Math.max(0, Math.round((resetsAt - now) / (resetUnit === "m" ? 60_000 : 3_600_000)))
+						: undefined,
+				resetUnit,
+			});
+		};
+
 		for (const report of reports) {
 			if (!report || typeof report !== "object") continue;
+			const provider = (report as { provider?: unknown }).provider;
+			const providerId = typeof provider === "string" ? provider : undefined;
 			const limits = (report as { limits?: unknown }).limits;
 			if (!Array.isArray(limits)) continue;
 			for (const limit of limits) {
 				if (!limit || typeof limit !== "object") continue;
 				const l = limit as {
-					scope?: { windowId?: string; tier?: string };
-					window?: { resetsAt?: number };
+					id?: unknown;
+					scope?: { windowId?: string; tier?: string; modelId?: string };
+					window?: { id?: string; resetsAt?: number };
 					amount?: { usedFraction?: number };
 				};
 				const fraction = l.amount?.usedFraction;
 				if (typeof fraction !== "number") continue;
-				const windowId = l.scope?.windowId;
+				const id = typeof l.id === "string" ? l.id : "";
+				const windowId = l.scope?.windowId ?? l.window?.id;
 				const tier = l.scope?.tier;
+				const modelId = l.scope?.modelId;
 				const resetsAt = l.window?.resetsAt;
-				if (windowId === "5h" && !tier && !fiveHour) {
-					fiveHour = {
-						percent: fraction * 100,
-						resetMinutes:
-							typeof resetsAt === "number" ? Math.max(0, Math.round((resetsAt - now) / 60_000)) : undefined,
-					};
-				} else if (windowId === "7d" && !tier && !sevenDay) {
-					sevenDay = {
-						percent: fraction * 100,
-						resetHours:
-							typeof resetsAt === "number" ? Math.max(0, Math.round((resetsAt - now) / 3_600_000)) : undefined,
-					};
+
+				if (providerId === "openai-codex") {
+					if (id === "openai-codex:primary" || (!id && !!windowId && windowId !== "7d" && !modelId)) {
+						const label = codexWindowLabel(windowId, "primary");
+						pushWindow("codex:primary", label, fraction, resetsAt, codexResetUnit(label));
+					} else if (id === "openai-codex:secondary" || (!id && windowId === "7d" && !modelId)) {
+						const label = codexWindowLabel(windowId, "secondary");
+						pushWindow("codex:secondary", label, fraction, resetsAt, codexResetUnit(label));
+					}
+				} else if (windowId === "5h" && !tier) {
+					pushWindow(`${providerId ?? "provider"}:5h`, "5h", fraction, resetsAt, "m");
+				} else if (windowId === "7d" && !tier) {
+					pushWindow(`${providerId ?? "provider"}:7d`, "7d", fraction, resetsAt, "h");
 				}
 			}
 		}
-		if (!fiveHour && !sevenDay) return null;
-		return { fiveHour, sevenDay };
+
+		return windows.length > 0 ? { windows } : null;
 	}
 
 	/**
@@ -684,12 +715,15 @@ export class StatusLineComponent implements Component {
 		const sepAnsi = theme.getFgAnsi("statusLineSep");
 
 		// Collect visible segment contents
+		const highlightSegment = (segId: StatusLineSegmentId, content: string): string =>
+			effectiveSettings.previewHighlightSegment === segId ? `\x1b[7m${content}\x1b[27m` : content;
+
 		const leftParts: string[] = [];
 		const leftSegIds: StatusLineSegmentId[] = [];
 		for (const segId of effectiveSettings.leftSegments) {
 			const rendered = renderSegment(segId, ctx);
 			if (rendered.visible && rendered.content) {
-				leftParts.push(rendered.content);
+				leftParts.push(highlightSegment(segId, rendered.content));
 				leftSegIds.push(segId);
 			}
 		}
@@ -698,7 +732,7 @@ export class StatusLineComponent implements Component {
 		for (const segId of effectiveSettings.rightSegments) {
 			const rendered = renderSegment(segId, ctx);
 			if (rendered.visible && rendered.content) {
-				rightParts.push(rendered.content);
+				rightParts.push(highlightSegment(segId, rendered.content));
 			}
 		}
 
@@ -765,7 +799,7 @@ export class StatusLineComponent implements Component {
 							if (!adjusted.visible || !adjusted.content) break;
 							reRendered = adjusted;
 						}
-						left[pathIdx] = reRendered.content;
+						left[pathIdx] = highlightSegment("path", reRendered.content);
 						leftWidth = groupWidth(left, leftCapWidth, leftSepWidth);
 					}
 				}

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

@@ -3,6 +3,7 @@ import { calculatePromptTokens } from "@gajae-code/agent-core/compaction/compact
 import type { AssistantMessage, ImageContent } from "@gajae-code/ai";
 import { parseRateLimitReason } from "@gajae-code/ai";
 import { type Component, Loader, TERMINAL, Text } from "@gajae-code/tui";
+import { logger } from "@gajae-code/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 {
+		GJC_NOTIFICATION_TYPE: payload.type,
+		GJC_NOTIFICATION_TITLE: cleanNotificationEnvValue(payload.title, 500),
+		GJC_NOTIFICATION_BODY: cleanNotificationEnvValue(payload.body),
+		GJC_NOTIFICATION_CWD: cleanNotificationEnvValue(payload.cwd, 2000),
+		GJC_NOTIFICATION_SESSION_ID: cleanNotificationEnvValue(payload.sessionId, 500),
+		GJC_NOTIFICATION_SESSION_NAME: cleanNotificationEnvValue(payload.sessionName, 500),
+		GJC_NOTIFICATION_LAST_ASSISTANT_MESSAGE: cleanNotificationEnvValue(payload.lastAssistantMessage),
+		GJC_NOTIFICATION_STOP_REASON: cleanNotificationEnvValue(payload.stopReason, 100),
+		GJC_NOTIFICATION_JSON: cleanNotificationEnvValue(JSON.stringify(payload), 8000),
+	};
+}
 
 function friendlyRetryReason(errorMessage: string | undefined): string {
 	if (!errorMessage) return "";
@@ -857,8 +898,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 +948,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

@@ -23,6 +23,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;
@@ -622,6 +623,8 @@ export class ExtensionUiController {
 		const scrollTitleRows =
 			requestedTitleRows === undefined ? undefined : Math.max(1, Math.min(requestedTitleRows, availableTitleRows));
 
+		ringTerminalBell(classifyHookSelectorBellEvent(title));
+
 		this.ctx.hookSelector = new HookSelectorComponent(
 			title,
 			options,

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

@@ -9,6 +9,7 @@ import { buildSkillPromptMessage, parseSkillInvocations } from "../../extensibil
 import { expandEmoticons } from "../../modes/emoji-autocomplete";
 import { createPromptActionAutocompleteProvider } from "../../modes/prompt-action-autocomplete";
 import { theme } from "../../modes/theme/theme";
+import { scrollTmuxToPreviousUserInput as scrollTmuxPaneToPreviousUserInput } from "../../modes/tmux-scroll";
 import type { InteractiveModeContext } from "../../modes/types";
 import type { AgentSessionEvent } from "../../session/agent-session";
 import { SKILL_PROMPT_MESSAGE_TYPE, type SkillPromptDetails } from "../../session/messages";
@@ -858,6 +859,7 @@ export class InputController {
 			copyCurrentLine: () => this.handleCopyCurrentLine(),
 			copyPrompt: () => this.handleCopyPrompt(),
 			pasteImage: () => void this.handleImagePaste(),
+			scrollTmuxToPreviousUserInput: () => this.scrollTmuxToPreviousUserInput(),
 			undo: prefix => this.ctx.editor.undoPastTransientText(prefix),
 			moveCursorToMessageEnd: () => this.ctx.editor.moveToMessageEnd(),
 			moveCursorToMessageStart: () => this.ctx.editor.moveToMessageStart(),
@@ -952,6 +954,19 @@ export class InputController {
 		this.setToolsExpanded(!this.ctx.toolOutputExpanded);
 	}
 
+	scrollTmuxToPreviousUserInput(): void {
+		const result = scrollTmuxPaneToPreviousUserInput();
+		if (result.ok) return;
+
+		if (result.reason === "not_inside_tmux") {
+			this.ctx.showWarning("Previous-input scroll works only inside tmux.");
+			return;
+		}
+
+		const detail = result.error ? `: ${result.error}` : ".";
+		this.ctx.showWarning(`Failed to scroll tmux to previous user input${detail}`);
+	}
+
 	setToolsExpanded(expanded: boolean): void {
 		this.ctx.toolOutputExpanded = expanded;
 		for (const child of this.ctx.chatContainer.children) {

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

@@ -8,6 +8,7 @@ import { activateModelProfile, materializeActiveModelProfileAssignment } from ".
 import { recommendModelProfileForProvider } from "../../config/model-profiles";
 import { GJC_MODEL_ASSIGNMENT_TARGETS } from "../../config/model-registry";
 import { formatModelSelectorValue } from "../../config/model-resolver";
+import type { ModelProfileConfig } from "../../config/models-config-schema";
 import { settings } from "../../config/settings";
 import { DebugSelectorComponent } from "../../debug";
 import { disableProvider, enableProvider } from "../../discovery";
@@ -51,6 +52,7 @@ import {
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
+	setSearchHardTimeoutMs,
 } from "../../tools";
 import { setSessionTerminalTitle } from "../../utils/title-generator";
 import { AgentDashboard } from "../components/agent-dashboard";
@@ -238,7 +240,7 @@ export class SelectorController {
 		this.ctx.ui.requestRender();
 	}
 
-	showCustomModelPresetWizard(): void {
+	showCustomModelPresetWizard(snapshot: ModelProfileConfig): void {
 		this.showSelector(done => {
 			let wizard: CustomModelPresetWizardComponent;
 			const submit = async (input: CustomModelPresetWizardSubmit): Promise<void> => {
@@ -255,6 +257,7 @@ export class SelectorController {
 				}
 			};
 			wizard = new CustomModelPresetWizardComponent(
+				snapshot,
 				input => {
 					void submit(input);
 				},
@@ -335,14 +338,16 @@ export class SelectorController {
 								separator: settings.get("statusLine.separator"),
 								showHookStatus: settings.get("statusLine.showHookStatus"),
 								sessionAccent: settings.get("statusLine.sessionAccent"),
+								segmentOptions: settings.get("statusLine.segmentOptions"),
 								...previewSettings,
 							});
 							this.ctx.updateEditorTopBorder();
 							this.ctx.ui.requestRender();
 						},
-						getStatusLinePreview: () => {
+						getStatusLinePreview: (width?: number) => {
 							// Return the rendered status line for inline preview
-							const availableWidth = this.ctx.editor.getTopBorderAvailableWidth(this.ctx.ui.terminal.columns);
+							const availableWidth =
+								width ?? this.ctx.editor.getTopBorderAvailableWidth(this.ctx.ui.terminal.columns);
 							return this.ctx.statusLine.getTopBorder(availableWidth).content;
 						},
 						onPluginsChanged: () => {
@@ -358,6 +363,7 @@ export class SelectorController {
 								separator: settings.get("statusLine.separator"),
 								showHookStatus: settings.get("statusLine.showHookStatus"),
 								sessionAccent: settings.get("statusLine.sessionAccent"),
+								segmentOptions: settings.get("statusLine.segmentOptions"),
 							});
 							this.ctx.updateEditorTopBorder();
 							this.ctx.ui.requestRender();
@@ -602,6 +608,9 @@ export class SelectorController {
 			case "statusLineShowHooks":
 			case "statusLine.showHookStatus":
 			case "statusLine.sessionAccent":
+			case "statusLine.leftSegments":
+			case "statusLine.rightSegments":
+			case "statusLine.segmentOptions":
 			case "statusLineSegments":
 			case "statusLineModelThinking":
 			case "statusLinePathAbbreviate":
@@ -641,6 +650,11 @@ export class SelectorController {
 					);
 				}
 				break;
+			case "web_search.timeout":
+				if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+					setSearchHardTimeoutMs(value * 1000);
+				}
+				break;
 			case "providers.image":
 				if (
 					value === "auto" ||
@@ -676,7 +690,7 @@ export class SelectorController {
 					try {
 						if (selection.kind === "createProfile") {
 							done();
-							this.showCustomModelPresetWizard();
+							this.showCustomModelPresetWizard(selection.profile);
 							return;
 						}
 						if (selection.kind === "profile") {

package/src/modes/prompt-action-autocomplete.ts

@@ -29,6 +29,7 @@ interface PromptActionAutocompleteOptions {
 	copyCurrentLine: () => void;
 	copyPrompt: () => void;
 	pasteImage: () => void;
+	scrollTmuxToPreviousUserInput: () => void;
 	undo: (prefix: string) => void;
 	moveCursorToMessageEnd: () => void;
 	moveCursorToMessageStart: () => void;
@@ -378,6 +379,13 @@ export function createPromptActionAutocompleteProvider(
 			keywords: ["paste", "image", "clipboard", "screenshot", "attach", "vision"],
 			execute: options.pasteImage,
 		},
+		{
+			id: "tmux-previous-user-input",
+			label: "Scroll to previous user input",
+			description: "tmux copy-mode",
+			keywords: ["scroll", "tmux", "previous", "user", "input", "prompt", "history"],
+			execute: options.scrollTmuxToPreviousUserInput,
+		},
 		{
 			id: "undo",
 			label: "Undo",

package/src/modes/tmux-scroll.ts

@@ -0,0 +1,92 @@
+import { resolveGjcTmuxCommand } from "../gjc-runtime/tmux-common";
+
+// tmux copy-mode pads lines to the pane width, so allow trailing spaces before
+// the line end while keeping the match scoped to the standalone `user` label.
+export const TMUX_PREVIOUS_USER_INPUT_SEARCH_PATTERN = "^ *user *$";
+
+type TmuxScrollFailureReason =
+	| "not_inside_tmux"
+	| "tmux_command_failed"
+	| "copy_mode_failed"
+	| "history_bottom_failed"
+	| "search_failed";
+
+export type TmuxScrollToPreviousUserInputResult =
+	| { ok: true }
+	| { ok: false; reason: TmuxScrollFailureReason; error?: string };
+
+interface TmuxSpawnResult {
+	exitCode: number | null;
+	stderr?: { toString(): string };
+}
+
+type TmuxSpawnSync = (command: string, args: string[], env: NodeJS.ProcessEnv) => TmuxSpawnResult;
+
+function defaultSpawnSync(command: string, args: string[], env: NodeJS.ProcessEnv): TmuxSpawnResult {
+	return Bun.spawnSync([command, ...args], {
+		env,
+		stdout: "ignore",
+		stderr: "pipe",
+	});
+}
+
+function getErrorText(result: TmuxSpawnResult): string | undefined {
+	const text = result.stderr?.toString().trim();
+	return text ? text : undefined;
+}
+
+function runTmuxStep(
+	command: string,
+	args: string[],
+	env: NodeJS.ProcessEnv,
+	spawnSync: TmuxSpawnSync,
+	reason: TmuxScrollFailureReason,
+): TmuxScrollToPreviousUserInputResult {
+	try {
+		const result = spawnSync(command, args, env);
+		if (result.exitCode === 0) return { ok: true };
+		return { ok: false, reason, error: getErrorText(result) };
+	} catch (error) {
+		return { ok: false, reason, error: error instanceof Error ? error.message : String(error) };
+	}
+}
+
+export function scrollTmuxToPreviousUserInput(
+	env: NodeJS.ProcessEnv = process.env,
+	spawnSync: TmuxSpawnSync = defaultSpawnSync,
+): TmuxScrollToPreviousUserInputResult {
+	if (!env.TMUX) return { ok: false, reason: "not_inside_tmux" };
+
+	let tmuxCommand: string;
+	try {
+		tmuxCommand = resolveGjcTmuxCommand(env);
+	} catch (error) {
+		return {
+			ok: false,
+			reason: "tmux_command_failed",
+			error: error instanceof Error ? error.message : String(error),
+		};
+	}
+
+	const targetPane = env.TMUX_PANE?.trim();
+	const targetArgs = targetPane ? ["-t", targetPane] : [];
+	const copyModeResult = runTmuxStep(tmuxCommand, ["copy-mode", ...targetArgs], env, spawnSync, "copy_mode_failed");
+	if (!copyModeResult.ok) return copyModeResult;
+
+	const historyBottomResult = runTmuxStep(
+		tmuxCommand,
+		["send-keys", ...targetArgs, "-X", "history-bottom"],
+		env,
+		spawnSync,
+		"history_bottom_failed",
+	);
+	if (!historyBottomResult.ok) return historyBottomResult;
+
+	return runTmuxStep(
+		tmuxCommand,
+		["send-keys", ...targetArgs, "-X", "search-backward", TMUX_PREVIOUS_USER_INPUT_SEARCH_PATTERN],
+		env,
+		spawnSync,
+		"search_failed",
+	);
+}

package/src/modes/utils/terminal-bell.ts

@@ -0,0 +1,48 @@
+import { settings } from "../../config/settings";
+
+export type TerminalBellEvent = "complete" | "approval" | "ask";
+
+const BEL = "\x07";
+
+function getBellSetting(key: Parameters<typeof settings.get>[0]): boolean {
+	try {
+		return Boolean(settings.get(key));
+	} catch {
+		// Some component-level tests exercise UI helpers before Settings.init().
+		// Terminal bells are purely best-effort, so an unavailable settings store
+		// must not make the UI path throw.
+		return false;
+	}
+}
+
+function enabledForEvent(event: TerminalBellEvent): boolean {
+	if (!getBellSetting("notifications.terminalBell")) return false;
+	switch (event) {
+		case "complete":
+			return getBellSetting("notifications.bellOnComplete");
+		case "approval":
+			return getBellSetting("notifications.bellOnApproval");
+		case "ask":
+			return getBellSetting("notifications.bellOnAsk");
+	}
+}
+
+export function ringTerminalBell(
+	event: TerminalBellEvent,
+	output: Pick<NodeJS.WriteStream, "write"> = process.stdout,
+): void {
+	if (!enabledForEvent(event)) return;
+	try {
+		output.write(BEL);
+	} catch {
+		// Best-effort local notification only.
+	}
+}
+
+export function classifyHookSelectorBellEvent(title: string): TerminalBellEvent {
+	const normalized = title.toLowerCase();
+	if (normalized.includes("approval") || normalized.includes("approve") || normalized.includes("plan ready")) {
+		return "approval";
+	}
+	return "ask";
+}