@geoqiao/pi-ask 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+# [1.2.0](https://github.com/geoqiao/pi-ask/compare/v1.1.0...v1.2.0) (2026-08-16)
+
+
+### Bug Fixes
+
+* preserve RPC yes-no cancellation semantics ([9e5265d](https://github.com/geoqiao/pi-ask/commit/9e5265dec7ef6a990a3ac8a8aca190429a942fb7))
+
+
+### Features
+
+* add portable RPC ask fallback ([6def4ed](https://github.com/geoqiao/pi-ask/commit/6def4ed1c803980b5da89ccfc2de1d56f54bef99))
+
 # [1.1.0](https://github.com/eko24ive/pi-ask/compare/v1.0.2...v1.1.0) (2026-06-22)
 
 

package/README.md

@@ -6,14 +6,21 @@
 [![last commit](https://badgen.net/github/last-commit/geoqiao/pi-ask)](https://github.com/geoqiao/pi-ask/commits/main)
 [![stars](https://badgen.net/github/stars/geoqiao/pi-ask)](https://github.com/geoqiao/pi-ask/stargazers)
 
-`@geoqiao/pi-ask` is an independently maintained continuation of [`eko24ive/pi-ask`](https://github.com/eko24ive/pi-ask). It is an ask tool that cares about your answers.
+> [!IMPORTANT]
+> This is an independently maintained continuation of [`eko24ive/pi-ask`](https://github.com/eko24ive/pi-ask), with portable Pi RPC mode support while preserving the rich TUI experience.
 
-It lets an agent pause, ask structured questions in a terminal UI, and continue with normalized answers instead of guessing.
+`@geoqiao/pi-ask` is an ask tool that cares about your answers.
+
+It lets an agent pause, ask structured questions in a terminal UI or portable Pi RPC dialogs, and continue with normalized answers instead of guessing.
 
 ![pi-ask demo](docs/media/pi-ask-demo.gif)
 
 High-quality video: [demo.mp4](https://github.com/user-attachments/assets/a8503ca9-afcb-4c31-9edc-353b985a0209)
 
+## Upstream and contributions
+
+This project preserves the upstream Git history, MIT license, and author attribution. New development and releases are maintained independently in [`geoqiao/pi-ask`](https://github.com/geoqiao/pi-ask). Issues and contributions are welcome in this repository.
+
 ## Install
 
 ```bash
@@ -34,7 +41,7 @@ pi -e npm:@geoqiao/pi-ask
 
 ## Features
 
-Once installed, this package gives the agent a native way to ask for clarification instead of guessing.
+Once installed, this package gives the agent a native way to ask for clarification instead of guessing. The rich interface is used in TUI mode.
 
 - 🧭 Familiar ask-style interface: tabbed questions, single/multi select, and preview mode
 - ✍️ Inline free-form `Type your own` answers
@@ -42,6 +49,7 @@ Once installed, this package gives the agent a native way to ask for clarificati
 - 📝 Question-level and option-level notes
 - 👀 Review tab with `Submit`, `Elaborate`, and `Cancel`
 - 💬 Elaboration flow to capture note-based clarification before final submission
+- 🔌 Pi RPC fallback using portable sequential dialogs with normalized results
 - ⌨️ Context-aware customizable keymaps with aliases for main flow, editors, and settings
 - ⚙️ Ask settings with persisted behaviour, notifications, keymaps, and `/answer` extraction config
 - 🔔 Optional external notifications when an ask flow is waiting for input
@@ -93,7 +101,7 @@ Capture free-form input inline without leaving the flow.
 
 Open ask settings with `?` during the ask flow, or with the `/ask-settings` command from pi.
 
-Keymaps are context-aware and configurable in `~/.pi/agent/extensions/eko24ive-pi-ask.json`.
+Keymaps are context-aware and configurable in `~/.pi/agent/extensions/eko24ive-pi-ask.json`. The established filename is retained so users can switch from the upstream package without losing settings.
 Each action accepts a key string or an array of aliases.
 
 Default contexts:
@@ -188,6 +196,19 @@ After installation, the extension registers the `ask_user` tool plus `/ask-setti
 
 Agents can auto-discover and call `ask_user` when they need clarification instead of guessing. In interactive sessions, it opens a terminal UI flow for structured answers, supports native pi-style `@` file references while typing answers or notes, and returns normalized answers back to the agent. Ask settings are available both from `?` in the ask flow and from the `/ask-settings` command. Behaviour and notification settings are binary `on`/`off` toggles that save immediately when the config file is writable; save failures revert the toggle and show a manual-edit message. The settings overlay includes a guarded double-press reset-to-defaults action; keymaps, notification channels, and extraction settings are changed by editing the shown config file path.
 
+### Pi RPC fallback
+
+When Pi runs in RPC mode with portable extension UI support, `ask_user` keeps the same normalized result contract but uses sequential dialogs:
+
+- single choices, including Yes/No pairs, use cancellable `select` dialogs
+- short custom answers use `input`; multiline answers use `editor`
+- each question offers explicit Skip and Cancel actions, followed by optional question/selected-option note actions
+- multi-select repeats `select` with `[ ]` / `[x]` markers until `Finish selection` is chosen
+- descriptions and preview content are flattened into readable option strings
+- multiple questions include `[current/total]` progress in each dialog title
+
+RPC intentionally does not reproduce the tabbed same-screen form, native checkbox cards, custom preview pane, question-type hotkeys, settings overlay, or final Submit/Elaborate review tab. The fallback completes in `submit` mode after the sequential questions. `/answer`, `/answer:again`, `/ask:replay`, and `/ask-settings` remain TUI-only.
+
 ### Answer and replay commands
 
 `/answer` is useful when the agent asked questions in plain text instead of using `ask_user`. It extracts questions from the latest completed assistant message and opens the same ask UI.

package/docs/architecture.md

@@ -0,0 +1,98 @@
+# Architecture
+
+The codebase is split so the implementation reads through file boundaries and names, not through large explanatory docs.
+
+## Design goals
+
+- thin pi-specific wiring
+- pure, testable state transitions
+- rendering separated from decision logic
+- a small stable tool contract
+
+## Module map
+
+### Tool surface
+
+- `src/index.ts` — extension entrypoint
+- `src/ask-tool.ts` — tool registration, mode routing, non-interactive fallback, transcript rendering, ask payload capture
+- `src/rpc/controller.ts` — sequential portable-dialog RPC flow and state assembly
+- `src/answer-commands.ts` — `/answer`, `/answer:again`, and `/ask:replay` command wiring
+- `src/answer-extraction.ts` — configured extraction model selection and raw-JSON extraction retries
+- `src/ask-payload-store.ts` — branch-aware persisted ask payload lookup
+- `src/notifications.ts` — best-effort ask notification payload rendering and channel execution
+- `src/remote-ask.ts` — package-prefixed local event contract, active-flow registry, and explicit remote submission validation
+- `src/schema.ts` — TypeBox schema
+- `src/types.ts` — shared types
+
+### State
+
+- `src/state/normalize.ts` — normalize incoming questions
+- `src/state/answers.ts` — mutate and serialize answers
+- `src/state/selectors.ts` — read-only selectors
+- `src/state/transitions.ts` — navigation, selection, notes, input, submit, cancel
+- `src/state/result.ts` — convert UI state to `AskResult`
+- `src/state/view.ts` — view-mode helpers
+- `src/state.ts` — state barrel used by UI and tests
+
+### Config
+
+- `src/config/defaults.ts` — canonical runtime defaults
+- `src/config/schema.ts` — persisted config schema and runtime type
+- `src/config/migrate.ts` — persisted-file validation boundary, including schema migration and context-aware keymap normalization/fallback
+- `src/config/migrations/` — ordered schema-version migration framework for persisted config shape changes
+- `src/config/store.ts` — non-destructive current/legacy config discovery, load, save, notice, and runtime subscription store
+
+### UI
+
+- `src/ui/controller.ts` — connects key input, editor lifecycle, live config subscription, dirty-dismiss confirmation, and pure state transitions
+- `src/ui/input.ts` — raw input to commands using resolved context-aware config-backed keymaps
+- `src/ui/dismiss-guard.ts` — pure helpers for dirty-flow exit confirmation behavior
+- `src/ui/render.ts` and `src/ui/render-*.ts` — screen rendering, including config-backed footer/keymap hints
+- `src/ui/settings-list.ts` / `src/ui/show-settings.ts` — lightweight ask settings list rendering and launcher
+- `src/ui/constants.ts` and `src/ui/render-types.ts` — rendering constants/contracts
+
+### Result formatting
+
+- `src/result-format.ts` — shared summary/result line formatting
+- `src/result.ts` — final result rendering
+- `src/text.ts` / `src/constants.ts` — shared display strings
+
+### Tests
+
+- `tests/state.test.ts` — state transitions and serialization
+- `tests/input.test.ts` — editing/navigation key behavior
+- `tests/result.test.ts` — summaries and transcript output
+- `tests/render-*.test.ts` / `tests/text.test.ts` — rendering helpers
+
+## Invariants worth preserving
+
+- submit is never blocked by unanswered questions
+- TUI state and controller behavior stay isolated from the RPC portable-dialog controller
+- RPC answers are written through shared answer helpers and serialized through the shared result builder
+- single-select answers serialize as arrays
+- when `behaviour.presentSingleAsMulti` is enabled, future single-select questions are handled with multi-select state semantics while result metadata preserves the requested `type` and adds `presentedType`
+- active-flow question type changes are per-question runtime overrides handled in state/controller logic; they do not mutate the stored source payload or global config
+- single-select free-form answers replace selected options for that question
+- multi-select free-form answers augment selected options instead of clearing them
+- preview questions keep their preview-pane behavior while also supporting the synthetic custom-answer option
+- deselected option notes stay in UI state
+- only selected option notes are emitted in the final result
+- editor lifecycle stays in the controller, not in the reducers
+- persisted ask settings are migrated to the current schema version in memory, validated, and normalized before use without rewriting the config file on load
+- config schema migrations preserve user-provided values and add new defaults only when fields are absent
+- replay payload lookup scans only the current session branch and revalidates payloads before use
+- invalid persisted keymaps fall back to default keymaps for the current session without discarding valid behaviour, notification, or answer settings
+- invalid notification channels are skipped and fall back to the default bell channel if none are valid
+- ask settings behaviour and notification enabled changes attempt to persist immediately from the settings list; save failures revert the change and show an error; config reset is guarded by a short double-press confirmation
+- `presentSingleAsMulti` is applied at ask-flow creation; toggling it does not rewrite already-normalized questions in an open flow
+- `main.changeQuestionType` changes the active question type live (non-preview: `single <-> multi`; preview: `preview <-> multi`) and may require confirmation before destructive multi-to-single conversion
+- when the ask config file is missing, the first ask use attempts to write a default persisted config snapshot under `~/.pi/agent/extensions/`; if writing fails, built-in defaults are used for the session
+- legacy root config files are read as a fallback only when the current config file is absent; disk is left untouched
+- invalid config files are left untouched; defaults are loaded for the session with a notice
+- live config updates can affect an in-progress ask flow immediately
+- remote ask submissions must be explicit `answer` or `cancel` responses; pi-ask validates ids/values but never infers approve/deny semantics from labels or option values
+
+## Documentation rule
+
+Docs should explain contracts, responsibilities, and invariants.
+Code and tests should explain the rest.

package/docs/configuration.md

@@ -1,6 +1,6 @@
 # pi-ask configuration
 
-This file is the source of truth for configuring `@eko24ive/pi-ask`.
+This file is the source of truth for configuring `@geoqiao/pi-ask`.
 
 When changing pi-ask settings:
 
@@ -16,6 +16,8 @@ Default path:
 
 `~/.pi/agent/extensions/eko24ive-pi-ask.json`
 
+The established filename is intentionally retained for compatibility with upstream installations.
+
 If the file does not exist yet, pi-ask attempts to create it with the current default settings the first time the ask flow is used. If the config location is read-only or managed outside pi-ask, pi-ask uses built-in defaults for the session and leaves disk unchanged.
 
 Older pi-ask versions wrote this file at `~/.pi/agent/eko24ive-pi-ask.json`. If that legacy file exists and the extensions config does not, pi-ask reads the legacy file as a fallback and leaves disk unchanged. If both files exist, pi-ask uses the extensions config and leaves the legacy root file untouched.

package/docs/contract.md

@@ -193,7 +193,7 @@ This document defines the stable external behavior. It does not explain internal
 - elaborate `content` text and transcript rendering describe each note directly using the full question prompt and option label, and include the current committed answer text when available, instead of a generic elaboration banner
 - when the user selects `Elaborate` without adding notes, elaborate `content` text and transcript rendering still include the committed answer text so the agent can elaborate on that answer directly
 
-## Supported UX
+## Supported TUI UX
 
 - tabbed multi-question flow
 - single-select, multi-select, and preview questions
@@ -255,9 +255,22 @@ Dirty dismiss:
 - when `Confirm dismiss when dirty` is enabled, cancelling or dismissing a dirty ask flow requires the same action a second time
 - the dirty-dismiss warning stays visible until the user changes tabs in the ask flow
 
-## Non-TUI and non-interactive modes
+## Runtime modes
 
-The rich ask flow uses `ctx.ui.custom()` and opens only in TUI mode. In print, JSON, RPC, or any other non-TUI mode, the tool returns a `Needs user input: ask_user requires interactive TUI mode.` message in `content` and a cancelled result in `details` instead of opening custom UI.
+The rich ask flow uses `ctx.ui.custom()` only in TUI mode. RPC mode never calls `custom()`; when portable extension dialogs are available it asks questions sequentially and serializes answers through the same state/result helpers:
+
+- single choices, including Yes/No pairs, use `select` so dismissal remains distinct from choosing `No`
+- short and multiline custom answers use `input` and `editor`
+- every question exposes Skip explicitly; required remains advisory and its Skip label says so
+- after each question, a portable action dialog can add/edit a short or multiline question note, or an editor note for a selected option
+- multi-select repeatedly calls `select`, showing `[ ]` / `[x]` option markers and a `Finish selection` action; selections are collected locally in original option order
+- descriptions and preview content are flattened into option strings instead of using a custom preview pane
+- multiple questions are sequential and every title includes `[current/total]` progress
+- dismissing a value dialog or choosing Cancel returns `cancelled: true`
+
+RPC does not provide the tabbed same-screen form, native checkbox cards, custom preview pane, question-type hotkeys, settings overlay, or final Submit/Elaborate review tab. RPC completion uses `mode: "submit"`. `/answer`, `/answer:again`, `/ask:replay`, and `/ask-settings` remain TUI-only.
+
+In print, JSON, other non-TUI modes, or RPC without portable UI availability, the tool returns a `Needs user input: ask_user requires interactive TUI mode.` message in `content` and a cancelled result in `details` instead of opening UI.
 
 Validation is handled inside the tool so malformed calls produce the same structured error shape as other invalid payloads instead of relying on pre-execution schema failures.
 
@@ -265,20 +278,22 @@ The ask flow subscribes to runtime settings updates while open. In practice, thi
 
 ## Notifications
 
-When enabled, pi-ask emits one best-effort external notification per ask session after the ask UI opens and waits for input. The default title is `pi ask`; the message is `Question waiting: <label or prompt>`. Channels run in configured order and failures never fail or cancel the ask flow.
+When enabled, pi-ask emits one best-effort external notification per TUI ask session after the ask UI opens and waits for input. RPC clients surface the portable dialogs directly. The default title is `pi ask`; the message is `Question waiting: <label or prompt>`. Channels run in configured order and failures never fail or cancel the ask flow.
 
 ## Remote inter-extension events
 
-pi-ask exposes a local `pi.events` contract for trusted Pi extensions. It does not expose a network API and does not automate terminal keystrokes. RPC or headless integrations should use a trusted in-process bridge extension that consumes these events rather than expecting the TUI-only custom surface to open.
+pi-ask exposes a local `pi.events` contract for trusted Pi extensions. It does not expose a network API and does not automate terminal keystrokes. Integrations that need programmatic submissions instead of the normal TUI or RPC portable-dialog flow can use a trusted in-process bridge extension that consumes these events.
 
 Channels:
 
+The established event namespace is retained for compatibility with existing trusted integrations.
+
 - `@eko24ive/pi-ask:started`
 - `@eko24ive/pi-ask:completed`
 - `@eko24ive/pi-ask:submit`
 - `@eko24ive/pi-ask:submit-result`
 
-Remote submissions must be explicit `{ kind: "answer" }` or `{ kind: "cancel" }` responses. Remote answers use question ids and normalized option values from the started event. pi-ask validates ids and values, recomputes labels/indices, and does not infer approval semantics from labels.
+Remote submissions must be explicit `{ kind: "answer" }` or `{ kind: "cancel" }` responses. Remote answers use question ids and normalized option values from the started event. pi-ask validates ids and values, recomputes labels/indices, and does not infer approval semantics from labels. The normal `ask_user` tool uses the portable-dialog fallback in RPC; the event bridge remains available for other trusted in-process integrations.
 
 See [`remote-events.md`](remote-events.md) for payload shapes, examples, and a local smoke test.
 
@@ -292,7 +307,7 @@ See [`remote-events.md`](remote-events.md) for payload shapes, examples, and a l
 - submitted or elaborated command-flow results are sent back with user-message semantics
 - replay commands scan only `ctx.sessionManager.getBranch()`, ignore sibling/future branch payloads, and revalidate stored payloads before opening the UI
 
-The fallback message includes normalized pending questions and options so the caller can re-ask them manually. `details.questions` still contains normalized question metadata, while `details.answers` stays empty until a user responds.
+The non-interactive fallback message includes normalized pending questions and options so the caller can re-ask them manually. `details.questions` still contains normalized question metadata, while `details.answers` stays empty until a user responds.
 
 ## Skill alignment (advisory)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geoqiao/pi-ask",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Pi package that adds an interactive ask_user clarification tool.",
   "license": "MIT",
   "type": "module",
@@ -25,6 +25,7 @@
     "skills/",
     "docs/configuration.md",
     "docs/contract.md",
+    "docs/architecture.md",
     "docs/remote-events.md",
     "README.md",
     "LICENSE",
@@ -53,7 +54,7 @@
   },
   "publishConfig": {
     "access": "public",
-    "provenance": false
+    "provenance": true
   },
   "release": {
     "repositoryUrl": "https://github.com/geoqiao/pi-ask.git",

package/src/ask-tool-helpers.ts

@@ -13,7 +13,7 @@ import type {
 } from "./types.ts";
 
 export const ASK_TOOL_DESCRIPTION =
-	"Interactive clarification tool for cases where the next step depends on user preferences, missing requirements, or choosing between multiple valid directions. Ask a short structured interview, collect normalized answers, and continue using those answers explicitly instead of guessing. Supports single-select, multi-select, and preview-pane questions. Always include a machine-readable `value` for every option. Use `preview` only when every option includes `preview` text; descriptions alone are not enough.";
+	"Interactive clarification tool for cases where the next step depends on user preferences, missing requirements, or choosing between multiple valid directions. Ask a short structured interview, collect normalized answers, and continue using those answers explicitly instead of guessing. TUI mode supports single-select, multi-select, and preview-pane questions; RPC mode presents questions sequentially, implements multi-select with repeated portable dialogs, and flattens preview details into option text. Always include a machine-readable `value` for every option. Use `preview` only when every option includes `preview` text; descriptions alone are not enough.";
 
 export const ASK_TOOL_PROMPT_GUIDELINES = [
 	"Use `ask_user` before making preference-sensitive decisions about scope, tone, UX, naming, architecture, docs, or implementation direction.",
@@ -25,6 +25,7 @@ export const ASK_TOOL_PROMPT_GUIDELINES = [
 	"After an `ask_user` elaboration or follow-up note, prefer another structured `ask_user` follow-up if a choice is still needed instead of switching to plain-text multiple choice in chat.",
 	"When prior `ask_user` answers narrow the branch, bundle the next 2-3 related unresolved decisions into one follow-up `ask_user` call when possible.",
 	"Use one-at-a-time `ask_user` follow-up calls only when the next question materially depends on the previous answer.",
+	"Do not promise same-screen forms, native checkbox cards, or a custom preview pane when `ask_user` is rendered through RPC; the portable fallback asks questions sequentially and uses a repeated-select loop for multi-select.",
 ] as const;
 
 interface ValidateParamsOptions {

package/src/ask-tool.ts

@@ -15,6 +15,7 @@ import {
 } from "./ask-tool-helpers.ts";
 import { getAskConfigStore } from "./config/store.ts";
 import type { RemoteAskRuntime } from "./remote-ask.ts";
+import { runRpcAskFlow } from "./rpc/controller.ts";
 import { AskParamsSchema } from "./schema.ts";
 import type { AskParams } from "./types.ts";
 import { runAskFlow } from "./ui/controller.ts";
@@ -68,6 +69,9 @@ async function executeAskTool(
 		sourceEntryId: toolCallId,
 	});
 	if (ctx.mode !== "tui") {
+		if (ctx.mode === "rpc" && ctx.hasUI) {
+			return successfulResponse(await runRpcAskFlow(ctx, validation.state));
+		}
 		return nonInteractiveResponse(validation.state);
 	}
 	ctx.ui.setWorkingVisible(false);

package/src/index.ts

@@ -13,7 +13,7 @@ const CONFIGURATION_DOC_PATH = resolve(
 	"docs",
 	"configuration.md"
 );
-const PI_ASK_CONFIG_PROMPT = `When the user asks to configure, customize, debug, or explain @eko24ive/pi-ask settings or keymaps, first read ${CONFIGURATION_DOC_PATH} and follow it as the source of truth before editing config files.`;
+const PI_ASK_CONFIG_PROMPT = `When the user asks to configure, customize, debug, or explain @geoqiao/pi-ask settings or keymaps, first read ${CONFIGURATION_DOC_PATH} and follow it as the source of truth before editing config files.`;
 
 export default function askExtension(pi: ExtensionAPI) {
 	resetAskConfigStore();

package/src/rpc/controller.ts

@@ -0,0 +1,602 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+	emptyAnswer,
+	isAnswerEmpty,
+	isOptionSelected,
+	saveCustomText,
+	saveOptionNote,
+	saveQuestionNote,
+	setSingleSelection,
+	toggleSelection,
+} from "../state/answers.ts";
+import { toAskResult } from "../state/result.ts";
+import type {
+	AskDisplayOption,
+	AskQuestion,
+	AskResult,
+	AskState,
+	AskStateAnswer,
+} from "../types.ts";
+
+type RpcUi = Pick<ExtensionContext["ui"], "editor" | "input" | "select">;
+
+interface RpcStepResult {
+	cancelled: boolean;
+	state: AskState;
+}
+
+interface SelectAction {
+	kind:
+		| "cancel"
+		| "custom-editor"
+		| "custom-input"
+		| "finish"
+		| "option"
+		| "skip";
+	label: string;
+	optionIndex?: number;
+}
+
+interface NoteAction {
+	kind:
+		| "cancel"
+		| "continue"
+		| "option-note"
+		| "question-editor"
+		| "question-input";
+	label: string;
+	optionValue?: string;
+}
+
+const CANCEL_LABEL = "Cancel ask";
+const CONTINUE_LABEL = "Continue";
+const CUSTOM_EDITOR_LABEL = "Write or edit a multiline answer…";
+const CUSTOM_INPUT_LABEL = "Type or edit a short answer…";
+const FINISH_SELECTION_LABEL = "Finish selection";
+
+export async function runRpcAskFlow(
+	ctx: { ui: RpcUi },
+	initialState: AskState
+): Promise<AskResult> {
+	let state = initialState;
+
+	for (const [questionIndex] of state.questions.entries()) {
+		const answerStep = await askQuestion(ctx.ui, state, questionIndex);
+		state = answerStep.state;
+		if (answerStep.cancelled) {
+			return cancelledResult(state);
+		}
+
+		const noteStep = await askForOptionalNotes(ctx.ui, state, questionIndex);
+		state = noteStep.state;
+		if (noteStep.cancelled) {
+			return cancelledResult(state);
+		}
+	}
+
+	return toAskResult({
+		...state,
+		activeTabIndex: state.questions.length,
+		completed: true,
+	});
+}
+
+async function askQuestion(
+	ui: RpcUi,
+	state: AskState,
+	questionIndex: number
+): Promise<RpcStepResult> {
+	const question = state.questions[questionIndex];
+	if (!question) {
+		return { cancelled: false, state };
+	}
+	if (question.type === "multi") {
+		return await askMultiQuestion(ui, state, question, questionIndex);
+	}
+	return await askSingleQuestion(ui, state, question, questionIndex);
+}
+
+async function askSingleQuestion(
+	ui: RpcUi,
+	state: AskState,
+	question: AskQuestion,
+	questionIndex: number
+): Promise<RpcStepResult> {
+	const actions: SelectAction[] = question.options
+		.filter((option) => !option.freeform)
+		.map((option, optionIndex) => ({
+			kind: "option" as const,
+			label: formatOption(option, optionIndex),
+			optionIndex,
+		}));
+	appendCommonActions(actions, question);
+
+	const action = await selectAction(
+		ui,
+		formatTitle(state, question, questionIndex),
+		actions
+	);
+	return applySingleAction({
+		action,
+		question,
+		questionIndex,
+		state,
+		ui,
+	});
+}
+
+async function applySingleAction(args: {
+	action: SelectAction | undefined;
+	question: AskQuestion;
+	questionIndex: number;
+	state: AskState;
+	ui: RpcUi;
+}): Promise<RpcStepResult> {
+	const { action, question, questionIndex, state, ui } = args;
+	if (!action || action.kind === "cancel") {
+		return { cancelled: true, state };
+	}
+	if (action.kind === "skip") {
+		return { cancelled: false, state: clearAnswer(state, question.id) };
+	}
+	if (action.kind === "custom-input" || action.kind === "custom-editor") {
+		return await askForCustomAnswer(
+			ui,
+			state,
+			question,
+			questionIndex,
+			action.kind === "custom-editor"
+		);
+	}
+	if (action.kind !== "option") {
+		return { cancelled: true, state };
+	}
+
+	return selectSingleOption(state, question, action.optionIndex);
+}
+
+function selectSingleOption(
+	state: AskState,
+	question: AskQuestion,
+	optionIndex: number | undefined
+): RpcStepResult {
+	const option =
+		optionIndex === undefined ? undefined : question.options[optionIndex];
+	if (!option || optionIndex === undefined) {
+		return { cancelled: true, state };
+	}
+	return {
+		cancelled: false,
+		state: updateAnswer(state, question.id, (answer) =>
+			setSingleSelection(answer, option, optionIndex)
+		),
+	};
+}
+
+async function askMultiQuestion(
+	ui: RpcUi,
+	initialState: AskState,
+	question: AskQuestion,
+	questionIndex: number
+): Promise<RpcStepResult> {
+	let state = initialState;
+	while (true) {
+		const actions = createMultiActions(question, state.answers[question.id]);
+		const action = await selectAction(
+			ui,
+			formatTitle(state, question, questionIndex, "Select all that apply"),
+			actions
+		);
+		const actionResult = await applyMultiAction({
+			action,
+			question,
+			questionIndex,
+			state,
+			ui,
+		});
+		if (actionResult.done) {
+			return actionResult.step;
+		}
+		state = actionResult.state;
+	}
+}
+
+function createMultiActions(
+	question: AskQuestion,
+	answer: AskStateAnswer | undefined
+): SelectAction[] {
+	const actions: SelectAction[] = question.options
+		.filter((option) => !option.freeform)
+		.map((option, optionIndex) => ({
+			kind: "option" as const,
+			label: formatOption(option, optionIndex, {
+				selected: isOptionSelected(answer, option.value),
+			}),
+			optionIndex,
+		}));
+	actions.push({ kind: "finish", label: FINISH_SELECTION_LABEL });
+	actions.push({
+		kind: "custom-input",
+		label: formatCustomAction(CUSTOM_INPUT_LABEL, answer),
+	});
+	actions.push({
+		kind: "custom-editor",
+		label: formatCustomAction(CUSTOM_EDITOR_LABEL, answer),
+	});
+	actions.push({ kind: "skip", label: formatSkipLabel(question) });
+	actions.push({ kind: "cancel", label: CANCEL_LABEL });
+	return actions;
+}
+
+type MultiActionResult =
+	| { done: false; state: AskState }
+	| { done: true; step: RpcStepResult };
+
+async function applyMultiAction(args: {
+	action: SelectAction | undefined;
+	question: AskQuestion;
+	questionIndex: number;
+	state: AskState;
+	ui: RpcUi;
+}): Promise<MultiActionResult> {
+	const { action, question, questionIndex, state, ui } = args;
+	if (!action || action.kind === "cancel") {
+		return { done: true, step: { cancelled: true, state } };
+	}
+	if (action.kind === "finish") {
+		return { done: true, step: { cancelled: false, state } };
+	}
+	if (action.kind === "skip") {
+		return {
+			done: true,
+			step: { cancelled: false, state: clearAnswer(state, question.id) },
+		};
+	}
+	if (action.kind === "custom-input" || action.kind === "custom-editor") {
+		const step = await askForCustomAnswer(
+			ui,
+			state,
+			question,
+			questionIndex,
+			action.kind === "custom-editor"
+		);
+		return step.cancelled
+			? { done: true, step }
+			: { done: false, state: step.state };
+	}
+	return applyMultiOptionAction(state, question, action);
+}
+
+function applyMultiOptionAction(
+	state: AskState,
+	question: AskQuestion,
+	action: SelectAction
+): MultiActionResult {
+	const optionIndex = action.optionIndex;
+	const option =
+		optionIndex === undefined ? undefined : question.options[optionIndex];
+	if (!option || optionIndex === undefined) {
+		return { done: true, step: { cancelled: true, state } };
+	}
+	return {
+		done: false,
+		state: updateAnswer(state, question.id, (currentAnswer) => {
+			const nextAnswer = toggleSelection(currentAnswer, option, optionIndex);
+			return {
+				...nextAnswer,
+				selected: [...nextAnswer.selected].sort(
+					(left, right) => left.index - right.index
+				),
+			};
+		}),
+	};
+}
+
+async function askForCustomAnswer(
+	ui: RpcUi,
+	state: AskState,
+	question: AskQuestion,
+	questionIndex: number,
+	multiline: boolean
+): Promise<RpcStepResult> {
+	const currentText = state.answers[question.id]?.customText;
+	const title = formatTitle(
+		state,
+		question,
+		questionIndex,
+		multiline ? "Multiline answer" : "Short answer"
+	);
+	const value = multiline
+		? await ui.editor(title, currentText ?? "")
+		: await ui.input(title, formatInputPlaceholder(currentText));
+	if (value === undefined) {
+		return { cancelled: true, state };
+	}
+
+	return {
+		cancelled: false,
+		state: updateAnswer(state, question.id, (answer) =>
+			saveCustomText(
+				answer,
+				value,
+				question.type === "multi" ? "multi" : "single"
+			)
+		),
+	};
+}
+
+async function askForOptionalNotes(
+	ui: RpcUi,
+	initialState: AskState,
+	questionIndex: number
+): Promise<RpcStepResult> {
+	let state = initialState;
+	const question = state.questions[questionIndex];
+	if (!question) {
+		return { cancelled: false, state };
+	}
+
+	while (true) {
+		const answer = state.answers[question.id];
+		const actions = createNoteActions(answer);
+		const action = await selectNoteAction(
+			ui,
+			formatTitle(state, question, questionIndex, "Optional notes"),
+			actions
+		);
+		const actionResult = await applyNoteAction({
+			action,
+			question,
+			questionIndex,
+			state,
+			ui,
+		});
+		if (actionResult.done) {
+			return actionResult.step;
+		}
+		state = actionResult.state;
+	}
+}
+
+function appendCommonActions(
+	actions: SelectAction[],
+	question: AskQuestion
+): void {
+	actions.push({ kind: "custom-input", label: CUSTOM_INPUT_LABEL });
+	actions.push({ kind: "custom-editor", label: CUSTOM_EDITOR_LABEL });
+	actions.push({ kind: "skip", label: formatSkipLabel(question) });
+	actions.push({ kind: "cancel", label: CANCEL_LABEL });
+}
+
+function createNoteActions(answer: AskStateAnswer | undefined): NoteAction[] {
+	return [
+		{ kind: "continue", label: CONTINUE_LABEL },
+		{
+			kind: "question-input",
+			label: answer?.note
+				? "Replace or clear the short question note…"
+				: "Add a short question note…",
+		},
+		{
+			kind: "question-editor",
+			label: answer?.note
+				? "Edit the question note in a multiline editor…"
+				: "Add a multiline question note…",
+		},
+		...(answer?.selected ?? []).map((selection) => ({
+			kind: "option-note" as const,
+			optionValue: selection.value,
+			label: answer?.optionNotes?.[selection.value]
+				? `Edit note for selected option: ${compactText(selection.label)}…`
+				: `Add note for selected option: ${compactText(selection.label)}…`,
+		})),
+		{ kind: "cancel", label: CANCEL_LABEL },
+	];
+}
+
+type NoteActionResult =
+	| { done: false; state: AskState }
+	| { done: true; step: RpcStepResult };
+
+async function applyNoteAction(args: {
+	action: NoteAction | undefined;
+	question: AskQuestion;
+	questionIndex: number;
+	state: AskState;
+	ui: RpcUi;
+}): Promise<NoteActionResult> {
+	const { action, question, questionIndex, state, ui } = args;
+	if (!action || action.kind === "cancel") {
+		return { done: true, step: { cancelled: true, state } };
+	}
+	if (action.kind === "continue") {
+		return { done: true, step: { cancelled: false, state } };
+	}
+	if (action.kind === "question-input") {
+		return await editQuestionNote(ui, state, question, questionIndex, false);
+	}
+	if (action.kind === "question-editor") {
+		return await editQuestionNote(ui, state, question, questionIndex, true);
+	}
+	return await editOptionNote(ui, state, question, questionIndex, action);
+}
+
+async function editQuestionNote(
+	ui: RpcUi,
+	state: AskState,
+	question: AskQuestion,
+	questionIndex: number,
+	multiline: boolean
+): Promise<NoteActionResult> {
+	const currentNote = state.answers[question.id]?.note;
+	const title = formatTitle(state, question, questionIndex, "Question note");
+	const value = multiline
+		? await ui.editor(title, currentNote ?? "")
+		: await ui.input(title, formatNotePlaceholder(currentNote));
+	if (value === undefined) {
+		return { done: true, step: { cancelled: true, state } };
+	}
+	return {
+		done: false,
+		state: updateAnswer(state, question.id, (answer) =>
+			saveQuestionNote(answer, value)
+		),
+	};
+}
+
+async function editOptionNote(
+	ui: RpcUi,
+	state: AskState,
+	question: AskQuestion,
+	questionIndex: number,
+	action: NoteAction
+): Promise<NoteActionResult> {
+	const optionValue = action.optionValue;
+	const option = question.options.find(
+		(candidate) => candidate.value === optionValue
+	);
+	if (!(optionValue && option)) {
+		return { done: true, step: { cancelled: true, state } };
+	}
+	const value = await ui.editor(
+		formatTitle(
+			state,
+			question,
+			questionIndex,
+			`Note for ${compactText(option.label)}`
+		),
+		state.answers[question.id]?.optionNotes?.[optionValue] ?? ""
+	);
+	if (value === undefined) {
+		return { done: true, step: { cancelled: true, state } };
+	}
+	return {
+		done: false,
+		state: updateAnswer(state, question.id, (answer) =>
+			saveOptionNote(answer, optionValue, value)
+		),
+	};
+}
+
+async function selectAction(
+	ui: RpcUi,
+	title: string,
+	actions: SelectAction[]
+): Promise<SelectAction | undefined> {
+	const selected = await ui.select(
+		title,
+		actions.map((action) => action.label)
+	);
+	return actions.find((action) => action.label === selected);
+}
+
+async function selectNoteAction(
+	ui: RpcUi,
+	title: string,
+	actions: NoteAction[]
+): Promise<NoteAction | undefined> {
+	const selected = await ui.select(
+		title,
+		actions.map((action) => action.label)
+	);
+	return actions.find((action) => action.label === selected);
+}
+
+function updateAnswer(
+	state: AskState,
+	questionId: string,
+	mutate: (answer: AskStateAnswer) => AskStateAnswer
+): AskState {
+	const nextAnswer = mutate(state.answers[questionId] ?? emptyAnswer());
+	const answers = { ...state.answers };
+	if (isAnswerEmpty(nextAnswer)) {
+		delete answers[questionId];
+	} else {
+		answers[questionId] = nextAnswer;
+	}
+	return { ...state, answers };
+}
+
+function clearAnswer(state: AskState, questionId: string): AskState {
+	if (!state.answers[questionId]) {
+		return state;
+	}
+	const answers = { ...state.answers };
+	delete answers[questionId];
+	return { ...state, answers };
+}
+
+function cancelledResult(state: AskState): AskResult {
+	return toAskResult({
+		...state,
+		cancelled: true,
+		completed: true,
+	});
+}
+
+function formatTitle(
+	state: AskState,
+	question: AskQuestion,
+	questionIndex: number,
+	suffix?: string
+): string {
+	const progress = `[${questionIndex + 1}/${state.questions.length}]`;
+	const flowTitle = state.title ? `${compactText(state.title)} — ` : "";
+	const detail = suffix ? ` — ${suffix}` : "";
+	return `${progress} ${flowTitle}${compactText(question.label)}: ${compactText(question.prompt)}${detail}`;
+}
+
+function formatOption(
+	option: AskDisplayOption,
+	optionIndex: number,
+	options: { selected?: boolean } = {}
+): string {
+	let marker = "";
+	if (options.selected !== undefined) {
+		marker = options.selected ? "[x] " : "[ ] ";
+	}
+	const description = option.description
+		? ` — ${compactText(option.description)}`
+		: "";
+	const preview = option.preview
+		? ` — Preview: ${compactText(option.preview)}`
+		: "";
+	return `${marker}${optionIndex + 1}. ${compactText(option.label)}${description}${preview}`;
+}
+
+function formatCustomAction(
+	baseLabel: string,
+	answer: AskStateAnswer | undefined
+): string {
+	if (!(answer?.customSelected && answer.customText?.trim())) {
+		return `[ ] ${baseLabel}`;
+	}
+	return `[x] ${baseLabel} — Current: ${truncateText(answer.customText)}`;
+}
+
+function formatSkipLabel(question: AskQuestion): string {
+	return question.required
+		? "Skip this question (required is advisory)"
+		: "Skip this question (optional)";
+}
+
+function formatInputPlaceholder(currentText: string | undefined): string {
+	return currentText?.trim()
+		? `Current: ${truncateText(currentText)}. Enter a replacement or leave blank to clear.`
+		: "Enter a short free-form answer";
+}
+
+function formatNotePlaceholder(currentNote: string | undefined): string {
+	return currentNote?.trim()
+		? `Current: ${truncateText(currentNote)}. Enter a replacement or leave blank to clear.`
+		: "Add an optional note or comment";
+}
+
+function compactText(value: string): string {
+	return value.replace(/\s+/g, " ").trim();
+}
+
+function truncateText(value: string): string {
+	const compact = compactText(value);
+	return compact.length > 80 ? `${compact.slice(0, 77)}…` : compact;
+}

package/src/ui/settings-list.ts

@@ -162,7 +162,7 @@ export class AskSettingsList {
 		const lines = [
 			this.topBorder(innerWidth),
 			this.line(
-				center(this.theme.fg("accent", "@eko24ive/pi-ask"), innerWidth),
+				center(this.theme.fg("accent", "@geoqiao/pi-ask"), innerWidth),
 				innerWidth
 			),
 			this.line("", innerWidth),