@narumitw/pi-btw 0.57.1 → 0.58.0

package/docs/workflows.md

@@ -39,7 +39,8 @@ Click it or use Pi's effective `tui.altScreen.bottom` binding (`End` by default)
 ## Thinking and queued questions
 
 The header shows the current side-thread thinking level.
-Use Pi's `app.thinking.cycle` shortcut (`Shift+Tab` by default) in the composer to cycle supported levels for later questions.
+Use the thinking-cycle shortcut shown in the composer to cycle supported levels for later questions.
+It inherits Pi's `app.thinking.cycle` (`Shift+Tab` by default) unless overridden in [Keybindings](../README.md#keybindings).
 Whether that change is remembered depends on [Settings](../README.md#-settings); it never changes the main session's thinking level.
 
 During a response, submit another question to queue it as `Steering`.
@@ -47,12 +48,12 @@ Queued questions run in order after the current response, using the thinking lev
 A failed response remains visible without discarding later queued questions.
 Steering does not append to the main conversation or editor.
 
-Ctrl+C cancels the active response and discards the current draft and steering queue.
+The configured exit shortcut, or the permanent Ctrl+C hard-cancel key, cancels the active response and discards the current draft and steering queue.
 Completed questions, answers, and visible errors remain resumable until the extension instance ends.
 
 ## Bring context to the main editor
 
-After a successful answer, press `Ctrl+R` to choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
+After a successful answer, use the bring-to-main shortcut (`Ctrl+R` by default) to choose the latest question and answer, everything from one question onward, an exact range, or the full thread.
 The scope chooser reports the latest exchange and full-thread sizes.
 Question-suffix, exact-range, and full-thread choices preview an editable context block before closing the side thread.
 Escape returns; Ctrl+C closes without bringing context back.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-btw",
-	"version": "0.57.1",
+	"version": "0.58.0",
 	"description": "Pi extension that adds a /btw side-question command.",
 	"type": "module",
 	"license": "MIT",

package/src/btw.ts

@@ -223,6 +223,9 @@ function notifySafely(
 	}
 }
 
+// Keep this slightly-over-1,000-line command coordinator intact: its injectable menu,
+// request, resume, and delivery flows share the same thread-state and test seams;
+// settings, keybinding policy, terminal ownership, and rendering live in separate modules.
 export interface BtwExtensionDependencies {
 	showCommandMenu?: (
 		pi: ExtensionAPI,
@@ -349,7 +352,10 @@ export default function btw(pi: ExtensionAPI, dependencies: BtwExtensionDependen
 							ctx: fullscreenCtx,
 						});
 					},
-					{ copyOnSelect: effectiveFullscreenCopyOnSelect(settings) },
+					{
+						copyOnSelect: effectiveFullscreenCopyOnSelect(settings),
+						...(settings.keybindings ? { keybindings: settings.keybindings } : {}),
+					},
 				);
 			} finally {
 				if (state?.title && state.thread.turns.length > 0) {

package/src/fullscreen-ui.ts

@@ -10,7 +10,6 @@ import {
 	isKeyRelease,
 	isKittyProtocolActive,
 	Key,
-	matchesKey,
 	type OverlayHandle,
 	parseKey,
 	type TUI,
@@ -19,6 +18,12 @@ import {
 	type TuiInputListenerResult,
 	truncateToWidth,
 } from "@earendil-works/pi-tui";
+import {
+	type BtwKeybindingOverrides,
+	BtwPasteGuard,
+	resolveBtwShortcuts,
+	setBtwShortcuts,
+} from "./keybindings.js";
 import { formatKeyLabel, sanitizeSingleLine } from "./text.js";
 
 type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
@@ -41,6 +46,7 @@ export interface BtwFullscreenLayoutComponent extends Component {
 }
 
 export interface BtwFullscreenOptions {
+	keybindings?: BtwKeybindingOverrides;
 	copyOnSelect?: boolean;
 }
 
@@ -473,13 +479,37 @@ class BtwFullscreenHost<T> implements Component {
 			this.fullscreen = this.createTui(this.parent, this.theme, this.keybindings, this.options);
 			this.fullscreenCreated = true;
 			this.fullscreen.start();
+			const shortcuts = resolveBtwShortcuts(
+				this.options.keybindings,
+				this.keybindings,
+				this.options.copyOnSelect ?? true,
+			);
+			setBtwShortcuts(this.fullscreen, shortcuts);
+			// Negotiate before warning when possible: the first dispatched user input uses
+			// the current mode. Recheck each input, including later mode transitions.
+			let previousWarnings: readonly string[] = [];
+			const reportWarnings = () => {
+				const warnings = shortcuts.warnings;
+				for (const warning of warnings) {
+					if (previousWarnings.includes(warning)) continue;
+					try {
+						this.ctx.ui.notify(`Pi BTW: ${warning}`, "warning");
+					} catch {
+						/* A replaced context must not prevent terminal cleanup. */
+					}
+				}
+				previousWarnings = warnings;
+			};
+			const pasteGuard = new BtwPasteGuard();
 			// Waiting for the custom promise would leave follow-up keys bound to the side TUI.
 			const addHardCancelListener =
 				this.fullscreen.addInputListenerBeforeAll?.bind(this.fullscreen) ??
 				this.fullscreen.addInputListenerBeforeViewport?.bind(this.fullscreen) ??
 				this.fullscreen.addInputListener.bind(this.fullscreen);
 			this.removeHardCancelListener = addHardCancelListener((data) => {
-				if (isKeyRelease(data) || !matchesKey(data, Key.ctrl("c"))) return undefined;
+				reportWarnings();
+				if (pasteGuard.consume(data) || !shortcuts.matches(data, "exit")) return undefined;
+				this.disposed = true;
 				try {
 					this.hardCancelActiveCustom?.();
 				} finally {

package/src/keybindings.ts

@@ -0,0 +1,330 @@
+import {
+	isKeyRelease,
+	isKittyProtocolActive,
+	KeybindingsManager,
+	type KeyId,
+	matchesKey,
+	type TUI,
+	TUI_KEYBINDINGS,
+} from "@earendil-works/pi-tui";
+import { formatKeyLabel } from "./text.js";
+
+export const BTW_SHORTCUT_ACTIONS = ["exit", "cycleThinkingLevel", "bringToMain"] as const;
+export type BtwShortcutAction = (typeof BTW_SHORTCUT_ACTIONS)[number];
+export type BtwKeybindingOverrides = Partial<Record<BtwShortcutAction, string>>;
+
+const MODIFIERS = ["shift", "alt", "ctrl", "super"] as const;
+const SYMBOLS = "`-=[]\\;',./!@#$%^&*()_|~{}:<>?";
+const SPECIAL: Record<string, number> = {
+	escape: 27,
+	tab: 9,
+	enter: 13,
+	space: 32,
+	backspace: 127,
+	insert: 57425,
+	delete: 57426,
+	home: 57423,
+	end: 57424,
+	pageup: 57421,
+	pagedown: 57422,
+	left: 57417,
+	right: 57418,
+	up: 57419,
+	down: 57420,
+};
+const FUNCTION_INPUTS = [
+	"OP",
+	"OQ",
+	"OR",
+	"OS",
+	"[15~",
+	"[17~",
+	"[18~",
+	"[19~",
+	"[20~",
+	"[21~",
+	"[23~",
+	"[24~",
+];
+// All cross-identity legacy collisions in Pi's matchesKey(): raw Ctrl bytes,
+// ESC-prefixed bytes (including Alt+arrows), BS/DEL, Enter and Shift+Tab.
+// CSI-u, keypad, lock bits, shifted letters and modifyOtherKeys normalize to
+// the same key+modifiers; probe that identity instead of duplicating the parser.
+const LEGACY_INPUTS = [
+	...Array.from({ length: 128 }, (_, code) => String.fromCharCode(code)),
+	...Array.from({ length: 128 }, (_, code) => `\u001b${String.fromCharCode(code)}`),
+	"\u001b[Z",
+	"\u001bOM",
+	"\u001b[E",
+	"\u001b[e",
+	"\u001bOe",
+	...FUNCTION_INPUTS.map((suffix) => `\u001b${suffix}`),
+];
+
+/** Strict settings syntax; Pi itself ignores unknown/duplicate modifier tokens. */
+export function normalizeBtwKey(value: unknown): string | undefined {
+	if (typeof value !== "string" || value.length > 80 || /[\s\p{Cc}]/u.test(value)) return undefined;
+	const parts = value.toLowerCase().split("+");
+	let base = parts.pop();
+	if (!base) return undefined;
+	if (base === "esc") base = "escape";
+	if (base === "return") base = "enter";
+	if (
+		new Set(parts).size !== parts.length ||
+		parts.some((part) => !MODIFIERS.includes(part as never))
+	)
+		return undefined;
+	if (
+		!Object.hasOwn(SPECIAL, base) &&
+		base !== "clear" &&
+		!/^f(?:[1-9]|1[0-2])$/u.test(base) &&
+		!(base.length === 1 && (/^[a-z0-9]$/u.test(base) || SYMBOLS.includes(base)))
+	)
+		return undefined;
+	if ((base === "escape" || (base.startsWith("f") && base.length > 1)) && parts.length)
+		return undefined;
+	if (
+		base === "clear" &&
+		(parts.length > 1 || (parts.length === 1 && !["ctrl", "shift"].includes(parts[0] ?? "")))
+	)
+		return undefined;
+	return [...MODIFIERS.filter((part) => parts.includes(part)), base].join("+");
+}
+
+/** Representative inputs are checked by Pi, including its live terminal-mode branches. */
+function inputsFor(key: string): string[] {
+	const parts = key.split("+");
+	const base = parts.pop() ?? "";
+	const modifier = MODIFIERS.reduce(
+		(mask, part, bit) => mask | (parts.includes(part) ? 1 << bit : 0),
+		0,
+	);
+	const code = SPECIAL[base] ?? (base.length === 1 ? base.charCodeAt(0) : undefined);
+	const inputs =
+		code === undefined ? LEGACY_INPUTS : [...LEGACY_INPUTS, `\u001b[${code};${modifier + 1}u`];
+	return inputs.filter((input) => matchesKey(input, key as KeyId));
+}
+
+export function btwKeysOverlap(first: string, second: string): boolean {
+	const normalized = normalizeBtwKey(first);
+	return (
+		normalized !== undefined &&
+		inputsFor(normalized).some((input) => matchesKey(input, second as KeyId))
+	);
+}
+
+export interface BtwShortcuts {
+	keys: Record<BtwShortcutAction, readonly string[]>;
+	warnings: readonly string[];
+	matches(data: string, action: BtwShortcutAction): boolean;
+	label(action: BtwShortcutAction): string;
+}
+
+function reservedKeys(keybindings: KeybindingsManager, copyOnSelect: boolean): string[] {
+	// Editor has no autocomplete provider here. Select bindings are still reserved
+	// because exit also applies to BTW-owned nested review/menu components.
+	return [
+		"ctrl+c",
+		"shift+backspace",
+		"shift+delete",
+		"shift+space",
+		// Exact-range review uses these fixed selection actions even if Editor is remapped.
+		"shift+left",
+		"shift+right",
+		"shift+up",
+		"shift+down",
+		"left",
+		"right",
+		"enter",
+		"alt+enter",
+		"ctrl+j",
+		"pageUp",
+		"pageDown",
+		...Object.keys(TUI_KEYBINDINGS).flatMap((id) =>
+			keybindings.getKeys(id as keyof typeof TUI_KEYBINDINGS),
+		),
+		...(!copyOnSelect ? keybindings.getKeys("app.message.copy") : []),
+	];
+}
+
+function isTextKey(key: string): boolean {
+	const parts = key.split("+");
+	const base = parts.at(-1) ?? "";
+	return (
+		(base.length === 1 || base === "space") &&
+		!parts.some((part) => ["ctrl", "alt", "super"].includes(part))
+	);
+}
+
+export function resolveBtwShortcuts(
+	overrides: BtwKeybindingOverrides = {},
+	keybindings: KeybindingsManager,
+	copyOnSelect = true,
+): BtwShortcuts {
+	let mode = isKittyProtocolActive();
+	let snapshot = resolveShortcutSnapshot(overrides, keybindings, copyOnSelect);
+	const current = () => {
+		if (mode !== isKittyProtocolActive()) {
+			mode = isKittyProtocolActive();
+			snapshot = resolveShortcutSnapshot(overrides, keybindings, copyOnSelect);
+		}
+		return snapshot;
+	};
+	// ProcessTerminal negotiates Kitty asynchronously after the dedicated TUI starts.
+	// Hints and matching must use the same policy after that mode transition.
+	return {
+		get keys() {
+			return current().keys;
+		},
+		get warnings() {
+			return current().warnings;
+		},
+		matches: (data, action) => current().matches(data, action),
+		label: (action) => current().label(action),
+	};
+}
+
+function resolveShortcutSnapshot(
+	overrides: BtwKeybindingOverrides = {},
+	keybindings: KeybindingsManager,
+	copyOnSelect = true,
+): BtwShortcuts {
+	const reserved = reservedKeys(keybindings, copyOnSelect);
+	const keys: BtwShortcuts["keys"] = { exit: ["ctrl+c"], cycleThinkingLevel: [], bringToMain: [] };
+	const warnings: string[] = [];
+	const defaults: Record<BtwShortcutAction, readonly string[]> = {
+		exit: ["ctrl+c"],
+		cycleThinkingLevel: keybindings.getKeys("app.thinking.cycle"),
+		bringToMain: ["ctrl+r"],
+	};
+	const usable = (
+		action: BtwShortcutAction,
+		candidate: string,
+		inherited = false,
+	): string | undefined => {
+		const key = normalizeBtwKey(candidate);
+		if (!key || (!inherited && isTextKey(key))) return undefined;
+		const inputs = inputsFor(key);
+		if (!inputs.length) return undefined;
+		if (action === "exit" && key === "ctrl+c") return key;
+		if (
+			reserved.some(
+				(other) =>
+					typeof other === "string" && inputs.some((input) => matchesKey(input, other as KeyId)),
+			)
+		)
+			return undefined;
+		return key;
+	};
+	const candidates: BtwKeybindingOverrides = {};
+	const availableDefaults = { ...defaults };
+	for (const action of BTW_SHORTCUT_ACTIONS) {
+		availableDefaults[action] = defaults[action]
+			.map((key) => usable(action, key, action === "cycleThinkingLevel"))
+			.filter((key): key is string => key !== undefined);
+		const override = overrides[action];
+		if (override !== undefined) candidates[action] = usable(action, override);
+	}
+	// Compare the complete proposal, not only actions visited earlier. Reject conflicts
+	// together, then repeat because a rejected override restores its default bindings.
+	for (;;) {
+		const rejected = BTW_SHORTCUT_ACTIONS.filter((action) => {
+			const candidate = candidates[action];
+			return (
+				candidate !== undefined &&
+				BTW_SHORTCUT_ACTIONS.some(
+					(other) =>
+						other !== action &&
+						(candidates[other] ? [candidates[other]] : availableDefaults[other]).some((key) =>
+							btwKeysOverlap(candidate, key),
+						),
+				)
+			);
+		});
+		if (!rejected.length) break;
+		for (const action of rejected) delete candidates[action];
+	}
+	for (const action of BTW_SHORTCUT_ACTIONS) {
+		const override = overrides[action];
+		const selected = candidates[action];
+		if (override !== undefined && !selected)
+			warnings.push(
+				`${action}: configured shortcut is invalid or conflicts with a reserved action; using an available default.`,
+			);
+		const effective = selected
+			? [selected]
+			: availableDefaults[action].filter(
+					(key) =>
+						!BTW_SHORTCUT_ACTIONS.some(
+							(other) => other !== action && keys[other].some((used) => btwKeysOverlap(key, used)),
+						),
+				);
+		keys[action] = action === "exit" ? [...new Set([...effective, "ctrl+c"])] : effective;
+		if (!keys[action].length && (override !== undefined || defaults[action].length > 0))
+			warnings.push(`${action}: no usable shortcut; change Pi BTW Settings or Pi keybindings.`);
+	}
+	return {
+		keys,
+		warnings,
+		matches: (data, action) =>
+			!isKeyRelease(data) && keys[action].some((key) => matchesKey(data, key as KeyId)),
+		label: (action) =>
+			keys[action].length ? formatKeyLabel(keys[action][0] ?? "") : "Unavailable",
+	};
+}
+
+export function validateBtwShortcutEdit(
+	action: BtwShortcutAction,
+	value: string | undefined,
+	overrides: BtwKeybindingOverrides,
+	keybindings: KeybindingsManager,
+	copyOnSelect: boolean,
+): string | undefined {
+	// Reset must remain available even when several existing overrides conflict.
+	if (value === undefined) return undefined;
+	if (!normalizeBtwKey(value))
+		return "Invalid key combination. Use a Pi key name such as ctrl+q or f6.";
+	const next = { ...overrides, [action]: value };
+	const resolved = resolveBtwShortcuts(next, keybindings, copyOnSelect);
+	const previous = resolveBtwShortcuts(overrides, keybindings, copyOnSelect);
+	// Reject edits that disable another binding as well as the edited binding.
+	for (const item of BTW_SHORTCUT_ACTIONS) {
+		if (
+			(item === action && !resolved.keys[item].includes(normalizeBtwKey(value) ?? "")) ||
+			(item !== action && previous.keys[item].some((key) => !resolved.keys[item].includes(key)))
+		) {
+			return `${item} conflicts with another BTW shortcut, editing, selection, search, scrolling, or copying. Choose a different key.`;
+		}
+	}
+	return undefined;
+}
+
+const bindingsByTui = new WeakMap<TUI, BtwShortcuts>();
+export function setBtwShortcuts(tui: TUI, shortcuts: BtwShortcuts): void {
+	bindingsByTui.set(tui, shortcuts);
+}
+export function getBtwShortcuts(tui: TUI, keybindings?: KeybindingsManager): BtwShortcuts {
+	return (
+		bindingsByTui.get(tui) ??
+		resolveBtwShortcuts(
+			{},
+			keybindings ??
+				new KeybindingsManager({
+					...TUI_KEYBINDINGS,
+					"app.thinking.cycle": { defaultKeys: "shift+tab" },
+				}),
+		)
+	);
+}
+
+/** Keep split bracketed-paste payloads away from screen-level shortcuts. */
+export class BtwPasteGuard {
+	private active = false;
+	consume(data: string): boolean {
+		const wasActive = this.active;
+		const starts = data.includes("\u001b[200~");
+		if (starts) this.active = true;
+		if (this.active && data.includes("\u001b[201~")) this.active = false;
+		return wasActive || starts;
+	}
+}

package/src/menu.ts

@@ -5,6 +5,13 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import type { Component, TUI } from "@earendil-works/pi-tui";
 import type { MenuContext, RunMenuResult } from "@narumitw/pi-tui-kit";
+import {
+	BTW_SHORTCUT_ACTIONS,
+	type BtwShortcutAction,
+	normalizeBtwKey,
+	resolveBtwShortcuts,
+	validateBtwShortcutEdit,
+} from "./keybindings.js";
 import {
 	type BtwSettings,
 	type BtwSettingsPatch,
@@ -16,7 +23,7 @@ import {
 	updateBtwSettings,
 } from "./settings.js";
 import { BTW_THINKING_LEVELS, type BtwThinkingLevel } from "./side-thread.js";
-import { sanitizeSingleLine } from "./text.js";
+import { formatKeyLabel, sanitizeSingleLine } from "./text.js";
 
 interface BtwMenuState {
 	kind: "valid" | "invalid";
@@ -48,14 +55,17 @@ export type BtwCommandMenuResult =
 	| "closed"
 	| { kind: "resume"; threadId: string };
 
-type BtwMenuScreen = "main" | "resume" | "settings" | "invalid";
+type BtwMenuScreen = "main" | "resume" | "settings" | "invalid" | "shortcut" | "shortcut-input";
 type BtwMenuAction =
 	| "start"
 	| "start-tree"
 	| "resume"
 	| "set-thinking"
 	| "set-remember"
-	| "set-fullscreen-copy";
+	| "set-fullscreen-copy"
+	| "edit-shortcut"
+	| "save-shortcut"
+	| "reset-shortcut";
 const SAME_AS_MAIN_THREAD = "Same as main thread";
 type BtwCustomOptions = Parameters<ExtensionCommandContext["ui"]["custom"]>[1];
 
@@ -85,6 +95,74 @@ export async function showBtwCommandMenu(
 	let startSelected = false;
 	let treeSelected = false;
 	let resumedThreadId: string | undefined;
+	let keybindings: KeybindingsManager | undefined;
+	let shortcut: BtwShortcutAction = "exit";
+	const shortcutLabels: Record<BtwShortcutAction, string> = {
+		exit: "Exit shortcut",
+		cycleThinkingLevel: "Cycle thinking level shortcut",
+		bringToMain: "Bring to main shortcut",
+	};
+	const shortcutValue = (settings: BtwSettings, action: BtwShortcutAction): string => {
+		if (!keybindings) return "Default";
+		const effective = resolveBtwShortcuts(
+			settings.keybindings,
+			keybindings,
+			effectiveFullscreenCopyOnSelect(settings),
+		);
+		const configured = settings.keybindings?.[action];
+		if (configured !== undefined && !effective.keys[action].includes(configured)) {
+			return `Fallback (${effective.label(action)}; saved ${formatKeyLabel(configured)})`;
+		}
+		const source =
+			configured === undefined
+				? action === "cycleThinkingLevel"
+					? "Inherit Pi"
+					: "Default"
+				: "Custom";
+		return `${source} (${effective.label(action)})`;
+	};
+	const saveShortcut = async (
+		state: BtwMenuState,
+		value: string | undefined,
+		signal: AbortSignal,
+	) => {
+		if (!keybindings || state.kind !== "valid" || signal.aborted)
+			return { kind: "rejected" } as const;
+		const action = shortcut;
+		const manager = keybindings;
+		const validate = (settings: BtwSettings) =>
+			validateBtwShortcutEdit(
+				action,
+				value,
+				settings.keybindings ?? {},
+				manager,
+				effectiveFullscreenCopyOnSelect(settings),
+			);
+		const error = validate(state.settings);
+		if (error) {
+			notifySafely(ctx, error, "error");
+			return { kind: "rejected" } as const;
+		}
+		try {
+			await updateSettings(
+				{ keybindings: { [action]: value === undefined ? undefined : normalizeBtwKey(value) } },
+				{
+					settingsPath,
+					signal,
+					validateCurrent: (settings) => {
+						const conflict = validate(settings);
+						if (conflict) throw new Error(conflict);
+					},
+				},
+			);
+			if (signal.aborted) return { kind: "rejected" } as const;
+			notifySafely(ctx, "Pi BTW shortcut saved; applies when opening or resuming BTW.", "info");
+			return { kind: "back" } as const;
+		} catch (error) {
+			if (!signal.aborted) notifySaveFailure(ctx, error);
+			return { kind: "rejected" } as const;
+		}
+	};
 
 	const loadState = async (): Promise<BtwMenuState> => {
 		const loaded = await readSettings(settingsPath);
@@ -146,7 +224,7 @@ export async function showBtwCommandMenu(
 					{
 						id: "settings",
 						label: "Settings",
-						description: "Choose thinking, shortcut memory, and selection copying",
+						description: "Choose thinking, keybindings, and selection copying",
 						to: state.kind === "invalid" ? "invalid" : "settings",
 					},
 				],
@@ -195,7 +273,33 @@ export async function showBtwCommandMenu(
 						values: ["On", "Off"],
 						action: "set-fullscreen-copy",
 					},
+					...BTW_SHORTCUT_ACTIONS.map((action) => ({
+						id: action,
+						label: shortcutLabels[action],
+						description:
+							"Edit a BTW-only key combination or restore its default. Ctrl+C always hard-cancels.",
+						currentValue: shortcutValue(state.settings, action),
+						action: "edit-shortcut" as const,
+					})),
+				],
+			}),
+			shortcut: ({ state }) => ({
+				kind: "actions",
+				title: shortcutLabels[shortcut],
+				lines: [shortcutValue(state.settings, shortcut), "Ctrl+C always hard-cancels BTW."],
+				items: [
+					{ id: "edit", label: "Edit key combination…", to: "shortcut-input" },
+					{ id: "reset", label: "Restore default", action: "reset-shortcut" },
 				],
+				hint: "back",
+			}),
+			"shortcut-input": () => ({
+				kind: "input",
+				title: shortcutLabels[shortcut],
+				lines: ["Type a key name, not the shortcut itself. For example: ctrl+q or f6."],
+				placeholder: "Key combination",
+				action: "save-shortcut",
+				hint: "back",
 			}),
 			invalid: ({ state }) => ({
 				kind: "detail",
@@ -208,6 +312,15 @@ export async function showBtwCommandMenu(
 			}),
 		},
 		actions: {
+			"edit-shortcut": ({ itemId }) => {
+				if (!BTW_SHORTCUT_ACTIONS.includes(itemId as BtwShortcutAction))
+					return { kind: "rejected" };
+				shortcut = itemId as BtwShortcutAction;
+				return { kind: "to", screen: "shortcut" };
+			},
+			"save-shortcut": ({ state, value, signal }) =>
+				saveShortcut(state, value?.trim() ?? "", signal),
+			"reset-shortcut": ({ state, signal }) => saveShortcut(state, undefined, signal),
 			start: async () => {
 				startSelected = true;
 				return { kind: "close" };
@@ -275,8 +388,12 @@ export async function showBtwCommandMenu(
 		},
 	});
 
-	const result = await runBtwMenuPreservingEditor(ctx, (menuContext) =>
-		runMenu(menuContext, menu, { getState: loadState }),
+	const result = await runBtwMenuPreservingEditor(
+		ctx,
+		(menuContext) => runMenu(menuContext, menu, { getState: loadState }),
+		(manager) => {
+			keybindings = manager;
+		},
 	);
 	if (result.kind !== "closed" || result.reason !== "close") return "closed";
 	if (resumedThreadId) return { kind: "resume", threadId: resumedThreadId };
@@ -314,6 +431,7 @@ export async function showBtwCustomPreservingEditor<T>(
 export async function runBtwMenuPreservingEditor(
 	ctx: ExtensionCommandContext,
 	run: (menuContext: MenuContext) => Promise<RunMenuResult>,
+	onKeybindings?: (keybindings: KeybindingsManager) => void,
 ): Promise<RunMenuResult> {
 	let liveEditorText = ctx.ui.getEditorText();
 	let completed = false;
@@ -321,19 +439,18 @@ export async function runBtwMenuPreservingEditor(
 		get(target, property) {
 			if (property === "custom") {
 				return <Value>(factory: BtwCustomFactory<Value>, customOptions?: BtwCustomOptions) =>
-					target.custom<Value>(
-						(tui, theme, keybindings, done) =>
-							factory(tui, theme, keybindings, (value) => {
-								try {
-									liveEditorText = target.getEditorText();
-								} catch {
-									// Keep completion finite if session replacement invalidates the editor context.
-								}
-								completed = true;
-								done(value);
-							}),
-						customOptions,
-					);
+					target.custom<Value>((tui, theme, keybindings, done) => {
+						onKeybindings?.(keybindings);
+						return factory(tui, theme, keybindings, (value) => {
+							try {
+								liveEditorText = target.getEditorText();
+							} catch {
+								// Keep completion finite if session replacement invalidates the editor context.
+							}
+							completed = true;
+							done(value);
+						});
+					}, customOptions);
 			}
 			const value = Reflect.get(target, property, target) as unknown;
 			return typeof value === "function" ? value.bind(target) : value;