gentle-pi 3.4.0 → 3.5.0

package/README.md

@@ -229,8 +229,33 @@ See the [v2.6.0 release notes](https://github.com/Gentleman-Programming/gentle-p
 
 > **Fullscreen installation note:** a recognized global installation persists Pi’s `"tuiMode": "fullscreen"` setting. Project-local and other install paths do not receive that change.
 
+> **Interactive RPC hosts:** the desktop app sets `GENTLE_SHELL_INTERACTIVE_HOST=1` automatically, without touching your Pi config — see the [installation reference](docs/readme-reference.md#interactive-rpc-hosts).
+
 For prerequisites, source-checkout instructions, full install behavior, and release policy, use the **[installation reference](docs/readme-reference.md#install)**. For everyday work, describe the outcome and follow [ODD](#odd--the-everyday-workflow).
 
+### Without touching your pi
+
+`gentle-shell` opens Pi with the Gentle Shell package loaded, without installing it into your pi agent or editing its `settings.json`.
+
+```bash
+npm i -g gentle-pi
+
+# Own home, never touches your pi install
+gentle-shell
+
+# Reuse your pi sign-ins, models and chats instead
+gentle-shell --link
+```
+
+`gentle-shell` alone starts in its own home, `~/.gentle-shell/agent`. `gentle-shell --link` reuses `~/.pi/agent` as-is.
+
+```bash
+# Make --link the default
+gentle-shell home link
+```
+
+Every other argument is forwarded to pi unchanged, for example `gentle-shell --mode rpc` or `gentle-shell -p "..."`. Full flags, env vars, and modes: **[launcher reference](docs/readme-reference.md#gentle-shell-launcher)**.
+
 <p align="right"><a href="#top">Back to top ↑</a></p>
 
 <p align="center">

package/bin/gentle-shell.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// Thin process/fs/exec glue around lib/gentle-shell-launcher.ts (built to
+// runtime/gentle-shell-launcher.mjs). All decision logic — argv parsing, home
+// resolution, pi resolution order, the version gate, and the pi invocation —
+// lives in that pure, unit-tested module; this file only wires it to the real
+// process, filesystem, and child process.
+import { accessSync, constants as fsConstants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { constants as osConstants, homedir } from "node:os";
+import { delimiter, dirname, join, resolve as resolvePath } from "node:path";
+import { spawn, spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import {
+	buildPiInvocation,
+	checkPiVersion,
+	describeVersion,
+	helpText,
+	launcherConfigPath,
+	missingPiMessage,
+	parseLauncherArgs,
+	parseLauncherConfig,
+	planSpawn,
+	resolveHome,
+	resolvePiRuntime,
+	settingsDeclareGentlePi,
+} from "../runtime/gentle-shell-launcher.mjs";
+import { installIsolatedTuiModeSetting } from "../scripts/install-tui-mode-setting.mjs";
+
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function fail(message, code) {
+	process.stderr.write(`${message}\n`);
+	process.exit(code);
+}
+
+function readJsonIfExists(path) {
+	try {
+		return readFileSync(path, "utf8");
+	} catch (error) {
+		if (error.code === "ENOENT") return undefined;
+		throw error;
+	}
+}
+
+// @earendil-works/pi-coding-agent ships as an optional peer dependency: it may
+// not be installed at all, so a resolution failure here is expected, not an error.
+function resolveBundledCli() {
+	try {
+		const require = createRequire(import.meta.url);
+		const pkgJsonPath = require.resolve("@earendil-works/pi-coding-agent/package.json");
+		const cliPath = join(dirname(pkgJsonPath), "dist", "bundle", "cli.js");
+		return existsSync(cliPath) ? cliPath : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function findOnPath(name) {
+	const dirs = (process.env.PATH || "").split(delimiter).filter((entry) => entry.length > 0);
+	const extensions = process.platform === "win32" ? (process.env.PATHEXT || ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+	for (const dir of dirs) {
+		for (const extension of extensions) {
+			const candidate = join(dir, `${name}${extension}`);
+			try {
+				accessSync(candidate, fsConstants.X_OK);
+				return candidate;
+			} catch {
+				// keep scanning
+			}
+		}
+	}
+	return undefined;
+}
+
+function signalExitCode(signal) {
+	const number = osConstants.signals[signal];
+	return 128 + (typeof number === "number" ? number : 0);
+}
+
+function ownPackageVersion() {
+	const packageJson = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+	return packageJson.version;
+}
+
+function emptyArgs() {
+	return { link: false, isolated: false, home: undefined, help: false, version: false, command: undefined, commandArgs: [], passthrough: [], error: undefined };
+}
+
+function loadConfig() {
+	const configPath = launcherConfigPath(homedir());
+	const text = readJsonIfExists(configPath);
+	return text === undefined ? undefined : parseLauncherConfig(text);
+}
+
+function handleHomeCommand(commandArgs) {
+	if (commandArgs.length === 0) {
+		const resolved = resolveHome({ args: emptyArgs(), env: process.env, homedir: homedir(), config: loadConfig() });
+		process.stdout.write(`${resolved.mode} ${resolved.dir}\n`);
+		process.exit(0);
+	}
+	if (commandArgs.length > 1) fail("gentle-shell home accepts at most one argument. Run 'gentle-shell --help'.", 2);
+	const [value] = commandArgs;
+	if (value.length === 0) fail("gentle-shell home requires a non-empty argument. Run 'gentle-shell --help'.", 2);
+
+	const configPath = launcherConfigPath(homedir());
+	const configDir = dirname(configPath);
+	if (!existsSync(configDir)) mkdirSync(configDir, { recursive: true, mode: 0o700 });
+
+	if (value === "link" || value === "isolated") {
+		writeFileSync(configPath, `${JSON.stringify({ home: value }, null, 2)}\n`, "utf8");
+		process.stdout.write(`Saved home: ${value}\n`);
+		process.exit(0);
+	}
+	const dir = resolvePath(value);
+	writeFileSync(configPath, `${JSON.stringify({ home: dir }, null, 2)}\n`, "utf8");
+	process.stdout.write(`Saved home: path ${dir}\n`);
+	process.exit(0);
+}
+
+async function main() {
+	const args = parseLauncherArgs(process.argv.slice(2));
+	if (args.error !== undefined) fail(`${args.error}\nRun 'gentle-shell --help' for usage.`, 2);
+	if (args.help) {
+		process.stdout.write(`${helpText()}\n`);
+		process.exit(0);
+	}
+	if (args.command === "home") {
+		handleHomeCommand(args.commandArgs);
+		return;
+	}
+
+	const config = loadConfig();
+	let home = resolveHome({ args, env: process.env, homedir: homedir(), config });
+	if (home.mode === "path") home = { ...home, dir: resolvePath(home.dir) };
+
+	const runtime = resolvePiRuntime({
+		env: process.env,
+		resolveBundledCli,
+		findOnPath,
+		nodeExecPath: process.execPath,
+	});
+	if (runtime === undefined) fail(missingPiMessage(), 1);
+
+	const versionProbePlan = planSpawn({ command: runtime.command, args: [...runtime.args, "--version"], platform: process.platform });
+	const versionProbe = spawnSync(versionProbePlan.command, versionProbePlan.args, {
+		stdio: ["ignore", "pipe", "pipe"],
+		timeout: 15000,
+		encoding: "utf8",
+		shell: versionProbePlan.shell,
+	});
+	if (versionProbe.error) fail(`Could not run the pi runtime at "${runtime.command}": ${versionProbe.error.message}`, 1);
+	const versionCheck = checkPiVersion(versionProbe.stdout ?? "");
+	if (!versionCheck.ok) fail(versionCheck.message, 1);
+
+	if (args.version) {
+		process.stdout.write(`${describeVersion({ gentlePiVersion: ownPackageVersion(), piVersion: versionCheck.version, home })}\n`);
+		process.exit(0);
+	}
+
+	// Isolated-home bootstrap: only on a home gentle-shell has not seen before
+	// (link never bootstraps — it reuses the user's own pi agent home as-is).
+	if ((home.mode === "isolated" || home.mode === "path") && !existsSync(home.dir)) {
+		mkdirSync(home.dir, { recursive: true });
+		await installIsolatedTuiModeSetting(home.dir);
+		process.stderr.write(`gentle-shell: using a separate home at ${home.dir}. Run 'gentle-shell --link' to reuse your pi sign-ins and chats.\n`);
+	}
+
+	let linkDeclaresGentlePi = false;
+	if (home.mode === "link") {
+		const settingsText = readJsonIfExists(join(home.dir, "settings.json"));
+		linkDeclaresGentlePi = settingsDeclareGentlePi(settingsText);
+	}
+
+	const invocation = buildPiInvocation({
+		runtime,
+		home,
+		packageRoot,
+		settingsDeclareGentlePi: home.mode === "link" ? linkDeclaresGentlePi : false,
+		passthrough: args.passthrough,
+		piSubcommand: args.piSubcommand,
+		baseEnv: process.env,
+	});
+
+	const launchPlan = planSpawn({ command: invocation.command, args: invocation.args, platform: process.platform });
+	const child = spawn(launchPlan.command, launchPlan.args, { stdio: "inherit", env: invocation.env, shell: launchPlan.shell });
+	for (const signal of ["SIGINT", "SIGTERM", "SIGHUP"]) {
+		process.on(signal, () => child.kill(signal));
+	}
+	child.on("error", (error) => fail(`Could not start pi: ${error.message}`, 1));
+	child.on("exit", (code, signal) => {
+		process.exit(signal ? signalExitCode(signal) : (code ?? 1));
+	});
+}
+
+main().catch((error) => {
+	process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+	process.exit(1);
+});

package/docs/gentle-agents-activity.md

@@ -0,0 +1,95 @@
+# Gentle Agents activity schema (`gentle-agents.activity/v1`)
+
+An interactive RPC host — a client that runs `pi --mode rpc` itself, such as the Gentle Shell desktop app — receives live Gentle Agents subagent state as one bounded JSON document per coalescing window, so it can render a per-chat Helpers view without polling `subagent_status`.
+
+Source map: [publisher](../lib/agents-rpc-publisher.ts), [wiring](../extensions/gentle-agents.ts), [store](../lib/agents-protocol.ts).
+
+## Turning it on
+
+Set `GENTLE_SHELL_INTERACTIVE_HOST=1` on the `pi --mode rpc` process the host spawns directly. `lib/rpc-host.ts`'s `isInteractiveRpcHost(mode, env)` gates the feature on that exact value; any other value, or its absence, keeps RPC headless — the existing subagent-child behavior is byte-identical. `lib/agents-runner.ts` strips the variable from every subagent child's environment, so a subagent spawned by an interactive host never inherits it and stays headless itself.
+
+## Transport
+
+Pi's `setWidget` is the only fire-and-forget RPC push structured enough to carry this: in RPC mode it accepts a `string[]` (sent as `extension_ui_request`) and silently ignores a component-factory function (the shape the TUI card above the editor uses). The publisher and the TUI card therefore share one widget key without colliding on the wire — a plain RPC host or a TUI session only ever sees the factory call, which its own transport ignores or renders locally.
+
+```json
+{
+  "type": "extension_ui_request",
+  "method": "setWidget",
+  "widgetKey": "gentle-agents",
+  "widgetLines": ["{\"schema\":\"gentle-agents.activity/v1\", ...}"]
+}
+```
+
+`widgetLines` is always exactly one line: one JSON document, `JSON.stringify`'d, never pretty-printed. Parse it as `gentle-agents.activity/v1`.
+
+## Payload shape
+
+```jsonc
+{
+  "schema": "gentle-agents.activity/v1",
+  "summary": { "running": 1, "queued": 0, "waiting": 0, "finished": 2 },
+  "tasks": [
+    {
+      "summary": {
+        "id": "t_abc123",
+        "agent": "explore",
+        "label": "Map the auth module",
+        "prompt": "Explore how authentication works…",
+        "status": "running",
+        "createdAt": 1732000000000,
+        "startedAt": 1732000000100,
+        "endedAt": null,
+        "lastStep": "reading lib/auth.ts",
+        "lastActivityAt": 1732000005000,
+        "turns": 2,
+        "toolCalls": 3,
+        "error": null
+      },
+      "thread": {
+        "version": 7,
+        "dropped": 0,
+        "items": [
+          { "kind": "text", "text": "Looking at the auth flow first." },
+          { "kind": "tool", "name": "read", "args": "{\"path\":\"lib/auth.ts\"}", "running": false, "isError": false, "output": "…file contents…" }
+        ]
+      }
+    }
+  ]
+}
+```
+
+`summary` is `TaskSummary` from `lib/agents-protocol.ts`, unchanged. Each task's `summary` is a field whitelist of its `TaskRecord`: `id`, `agent`, `label`, `prompt`, `status`, `createdAt`, `startedAt`, `endedAt`, `lastStep`, `lastActivityAt`, `turns`, `toolCalls`, `error`. Every other `TaskRecord` field — `cwd`, `parentSessionId`, `mode`, `model`, `thinking`, `sessionPath`, `result`, `tokens`, `cost` — is deliberately left out, the same discipline `lib/orchestrator-presence.ts`'s `projectActivity` already applies to same-profile peer discovery.
+
+`thread.items` is a `ThreadItem[]` whitelist too: text/thinking/note items keep `{ kind, text }` (`text` bounded, see below); tool items carry `{ kind: "tool", name, args, running, isError, output }`, where `args` is the tool's argument object `JSON.stringify`'d (never the raw object). `thread.dropped` is the store's own ring-buffer drop counter (unrelated to the per-push item cap below); `thread.version` increments on every thread mutation.
+
+Tasks are ordered `running`, `waiting`, `queued`, then finished tasks by `endedAt` descending (most recently finished first).
+
+## Bounds
+
+Every bound below fails closed: a value that cannot fit is truncated or dropped, and `lib/agents-rpc-publisher.ts`'s `encodeActivityLines` never throws.
+
+| Field | Bound |
+|---|---|
+| `summary.prompt` | 200 characters, trailing `…` |
+| `summary.error`, `summary.label`, `summary.lastStep` | 500 characters, trailing `…` |
+| tool `args` (stringified) | 500 characters, trailing `…` |
+| tool `output` | 500 characters, trailing `…` |
+| text/thinking/note item `text` | 2000 characters, trailing `…` |
+| `thread.items` per task | last 40, most recent last |
+| whole payload | 256 KiB |
+
+Truncation always keeps the field's prefix and marks the cut with a trailing `…` (never a separate `truncated` flag) — the same convention `projectRpcActivity`'s other bounded fields already use.
+
+When the whole-payload bound is still exceeded after the field- and item-level truncations above, `encodeActivityLines` shrinks the payload in this order:
+
+1. Halve every task's kept `thread.items` (repeatedly, down to one item each).
+2. Empty finished tasks' threads entirely.
+3. Drop whole finished tasks — oldest-finished first, by `endedAt`.
+4. Last resort: once only active (running/waiting/queued) tasks remain, each already down to one thread item, empty every remaining task's thread too — a summary-only payload.
+
+An active task's `summary` (running, waiting or queued) is never dropped; only its `thread.items` shrink. Finished tasks can be dropped whole by step 3, oldest first.
+
+## Coalescing
+
+`createRpcActivityPublisher` subscribes to `TaskStore#subscribeSummary` (task added, removed, or changed status) and to `TaskStore#subscribe(id)` for every known task, including ones added after `start()`. Changes inside a 150 ms window collapse into exactly one `setWidget("gentle-agents", [line])` call; `stop()` tears down every subscription and publishes one final frame.

package/docs/readme-reference.md

@@ -225,6 +225,73 @@ An orphan branch with commits and no parent has no branch point to name as `base
 - Create an empty root commit to open the branch: `git commit --allow-empty -m "chore: open the feature branch"`. The next commit can then use that root commit as its `baseRef`.
 - Omit `baseRef` while the branch is still unborn (no commits yet); the review uses Git's empty tree as the base automatically.
 
+## gentle-shell launcher
+
+`gentle-shell` (installed by `npm i -g gentle-pi`, exposed as the package's `bin`) opens pi with the Gentle Shell package loaded, without installing it into your pi agent or touching its `settings.json`. It is a thin `bin/gentle-shell.mjs` wrapper around the pure, unit-tested `lib/gentle-shell-launcher.ts` (built to `runtime/gentle-shell-launcher.mjs`); the wrapper owns process, filesystem, and child-process wiring only.
+
+```bash
+gentle-shell [options] [-- pi-args...]
+gentle-shell home [link|isolated|<path>]
+```
+
+### Flags
+
+| Flag | Effect |
+| --- | --- |
+| `--link` | Home is `PI_CODING_AGENT_DIR` or `~/.pi/agent`. Reuses your existing pi sign-ins, models, and chats; never writes to its `settings.json`. |
+| `--isolated` | Home is `GENTLE_SHELL_HOME` or `~/.gentle-shell/agent`. No credential seeding. Default when nothing else is configured. |
+| `--home <path>` | Home is the given directory. |
+| `--help`, `-h` | Print usage (flags, commands, env vars) and exit 0. |
+| `--version` | Print `gentle-shell <version>`, `pi <version>`, and `home <mode> <dir>`, then exit 0. |
+| `--` | Everything after is forwarded to pi verbatim, even text that looks like a `gentle-shell` flag. |
+
+`--link`, `--isolated`, and `--home` are mutually exclusive; combining two is a usage error, as is `--home` or `--home=` with an empty value. Effective-home precedence: an explicit flag wins, then the persisted `home` subcommand choice, then the `--isolated` default. Every argument gentle-shell does not recognize — `--mode rpc`, `-p "..."`, etc. — is forwarded to pi unchanged.
+
+### `home` subcommand and `~/.gentle-shell/config.json`
+
+`gentle-shell home` alone prints the effective mode and directory (`<mode> <dir>`) without persisting anything. `gentle-shell home link`, `gentle-shell home isolated`, or `gentle-shell home <path>` persists that choice to `~/.gentle-shell/config.json` as `{"home": "link" | "isolated" | "<path>"}`, so a later plain `gentle-shell` picks it up; a flag on a given invocation still overrides the persisted config without rewriting it.
+
+### Managing packages
+
+`gentle-shell install npm:<pkg>`, `gentle-shell remove ...`, `gentle-shell list`, `gentle-shell update ...`, `gentle-shell config`, and `gentle-shell auth ...` run pi's own commands against the resolved home — the `--isolated` home by default, or your own pi home with `--link`. A launcher flag before the subcommand (`--link`, `--isolated`, `--home <path>`) still selects which home the subcommand runs against. Running `gentle-shell install npm:gentle-pi` inside the isolated home is unnecessary: the launcher already loads the Gentle Shell package itself (see "Loading the package" below).
+
+### pi runtime resolution
+
+1. `GENTLE_SHELL_PI` — path to a pi executable, when set to a non-empty value.
+2. The bundled `@earendil-works/pi-coding-agent` resolved next to gentle-pi (`dist/bundle/cli.js`, run with the current `node`), when installed as its optional peer dependency.
+3. `pi` on `PATH`.
+
+If none resolve, `gentle-shell` exits 1 naming all three options. Once a runtime is found, its `pi --version` must be at least `0.85.1` (the pinned peer minimum): an older version exits 1 naming the found and required versions, and unparsable `--version` output exits 1 naming the required minimum.
+
+### Environment variables
+
+| Variable | Effect |
+| --- | --- |
+| `GENTLE_SHELL_PI` | Overrides pi runtime resolution (see above). |
+| `GENTLE_SHELL_HOME` | Overrides the isolated home directory (default `~/.gentle-shell/agent`). |
+| `PI_CODING_AGENT_DIR` | Read to resolve the `--link` home; also set on the pi child process to the effective home. |
+| `GENTLE_PI_AGENT_HOME` | Set on the pi child process to the effective home; gentle-pi's own home resolution reads it back. |
+
+### Loading the package
+
+Unless the target home's `settings.json` already lists `npm:gentle-pi` in its `packages` array (checked only for `--link`), every invocation injects `-e <package root> --theme <root>/themes --skill <root>/skills --prompt-template <root>/prompts` ahead of the forwarded arguments, so the Gentle Shell extensions, themes, skills, and prompt templates load without a separate `pi install`. Isolated and `--home <path>` homes never declare the package, so they always get the injection — except when the forwarded arguments start with one of pi's own subcommands (`install`, `remove`, `uninstall`, `update`, `list`, `config`, `auth`): pi dispatches those on `argv[0]` before it parses any flags, so the injection is skipped entirely and pi sees the bare subcommand, e.g. `gentle-shell install npm:x` runs exactly `pi install npm:x`.
+
+### First run in an isolated or custom home
+
+The first time `gentle-shell` resolves to an isolated or `--home <path>` home that does not already exist, it creates the directory, writes `"tuiMode": "fullscreen"` into its `settings.json`, and prints one hint to stderr pointing at `--link`. A `--link` home is never bootstrapped this way — it is assumed to already exist as your pi agent home. Later runs against the same home skip both the write and the hint.
+
+### Windows shims
+
+On win32, when the resolved pi command ends in `.cmd` or `.bat` — the shape an npm-installed `pi` or a `GENTLE_SHELL_PI` override commonly takes — `gentle-shell` runs it through `cmd.exe` as one quoted command line instead of spawning it directly, because current Node releases refuse to spawn a batch file without `shell: true`. This applies to both the version probe and the real launch.
+
+### Postinstall fullscreen guard
+
+gentle-pi's postinstall only writes the global `tuiMode: fullscreen` setting when the running package directory is a pi-managed install: under an `npm/node_modules` segment, or the exact `git/github.com/Gentleman-Programming` Git layout. `npm i -g gentle-pi`, a development checkout, and other layouts are recognized and skipped, logging `gentle-pi skipped enabling fullscreen in global Pi settings: <dir> is not a pi-managed install (npm install -g, a git checkout, and npx all land here).`
+
+### Interactive RPC hosts
+
+Setting `GENTLE_SHELL_INTERACTIVE_HOST=1` on a `pi --mode rpc` process turns on two things a plain headless RPC host does not get: dialogs for `ask_user_question` and `ask_user_choice` (one `ctx.ui.select` prompt per question, looped for multiSelect), and Gentle Agents' helper activity pushed live through `setWidget`. A subagent child spawned by such a host never inherits the variable, so nested children stay headless regardless of their parent. See the [activity payload reference](gentle-agents-activity.md) for the exact schema, field bounds, and shrink order.
+
 ## Quick start
 
 ```text

package/extensions/ask-user-choice.ts

@@ -1,9 +1,10 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { DynamicBorder } from "@earendil-works/pi-coding-agent";
 import { Container, Input, isKeyRelease, matchesKey, Text, type KeybindingsManager, type TuiMouseEvent } from "@earendil-works/pi-tui";
 import { type Static, Type } from "typebox";
 import { NativeChoiceList } from "../lib/native-choice-list.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
+import { isInteractiveMode, isInteractiveRpcHost } from "../lib/rpc-host.ts";
 
 const CHOICE_TOOL_NAME = "ask_user_choice";
 const ASK_USER_CHOICE_BLOCKED_EVENT = "gentle-pi:ask-user-choice:blocked";
@@ -147,11 +148,11 @@ class ChoiceModeView extends Container {
 	}
 }
 
-function reconcileToolAvailability(pi: ExtensionAPI, interactiveTui: boolean): void {
+function reconcileToolAvailability(pi: ExtensionAPI, interactive: boolean): void {
 	const active = pi.getActiveTools();
 	const isActive = active.includes(CHOICE_TOOL_NAME);
-	if (interactiveTui === isActive) return;
-	const next = interactiveTui
+	if (interactive === isActive) return;
+	const next = interactive
 		? [...new Set([...active, CHOICE_TOOL_NAME])]
 		: active.filter((name) => name !== CHOICE_TOOL_NAME);
 	pi.setActiveTools(next);
@@ -161,6 +162,57 @@ function resultDetails(params: ChoiceParams): ChoiceDetails {
 	return { question: params.question, options: params.options };
 }
 
+interface ChoiceToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: ChoiceDetails;
+}
+
+/** Same result shapes for both the TUI and the RPC-dialog fallback. */
+function choiceToolResult(params: ChoiceParams, selection: ChoiceResult | undefined): ChoiceToolResult {
+	if (selection === undefined) {
+		return {
+			content: [{ type: "text", text: "User cancelled the choice" }],
+			details: { ...resultDetails(params), cancelled: true },
+		};
+	}
+	if ("customResponse" in selection) {
+		return {
+			content: [{ type: "text", text: `User responded: ${selection.customResponse}` }],
+			details: { ...resultDetails(params), customResponse: selection.customResponse },
+		};
+	}
+	return {
+		content: [{ type: "text", text: `User selected: ${selection.index}. ${selection.label} (value: ${selection.value})` }],
+		details: { ...resultDetails(params), selection },
+	};
+}
+
+/** Label for the opt-in free-text entry appended to the RPC-dialog select options. */
+const OTHER_OPTION_LABEL = "Other…";
+
+/**
+ * Interactive-RPC-host fallback: one `ctx.ui.select` over the option labels
+ * (plus "Other…" when `allowCustomResponse`), then `ctx.ui.input` for the
+ * free-text response. Keeps the exact TUI result shapes; a cancel at either
+ * step cancels the choice, matching the TUI Escape key.
+ */
+async function askThroughDialogs(
+	ctx: Pick<ExtensionContext, "ui">,
+	params: ChoiceParams,
+): Promise<ChoiceResult | undefined> {
+	const labels = params.options.map((choiceOption) => choiceOption.label);
+	const dialogOptions = params.allowCustomResponse === true ? [...labels, OTHER_OPTION_LABEL] : labels;
+	const picked = await ctx.ui.select(params.question, dialogOptions);
+	if (picked === undefined) return undefined;
+	if (params.allowCustomResponse === true && picked === OTHER_OPTION_LABEL) {
+		const customResponse = await ctx.ui.input(params.question, "Type your response");
+		return customResponse === undefined ? undefined : { customResponse };
+	}
+	const index = params.options.findIndex((choiceOption) => choiceOption.label === picked);
+	const option = params.options[index];
+	return option === undefined ? undefined : { value: option.value, label: option.label, index: index + 1 };
+}
+
 export default function askUserChoice(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: CHOICE_TOOL_NAME,
@@ -175,7 +227,18 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 		executionMode: "sequential",
 		async execute(_toolCallId, params: ChoiceParams, _signal, _onUpdate, ctx) {
 			if (ctx.mode !== "tui") {
-				throw new Error("ask_user_choice is unavailable outside the interactive TUI");
+				if (!isInteractiveRpcHost(ctx.mode, process.env)) {
+					throw new Error("ask_user_choice is unavailable outside the interactive TUI");
+				}
+				let rpcSelection: ChoiceResult | undefined;
+				try {
+					pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: true });
+					rpcSelection = await askThroughDialogs(ctx, params);
+				}
+				finally {
+					pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: false });
+				}
+				return choiceToolResult(params, rpcSelection);
 			}
 
 			const items = params.options.map((option, index) => ({
@@ -239,22 +302,7 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 				pi.events.emit(ASK_USER_CHOICE_BLOCKED_EVENT, { active: false });
 			}
 
-			if (selection === undefined) {
-				return {
-					content: [{ type: "text", text: "User cancelled the choice" }],
-					details: { ...resultDetails(params), cancelled: true },
-				};
-			}
-			if ("customResponse" in selection) {
-				return {
-					content: [{ type: "text", text: `User responded: ${selection.customResponse}` }],
-					details: { ...resultDetails(params), customResponse: selection.customResponse },
-				};
-			}
-			return {
-				content: [{ type: "text", text: `User selected: ${selection.index}. ${selection.label} (value: ${selection.value})` }],
-				details: { ...resultDetails(params), selection },
-			};
+			return choiceToolResult(params, selection);
 		},
 		renderCall(args, theme) {
 			const options = Array.isArray(args.options) ? args.options : [];
@@ -280,6 +328,6 @@ export default function askUserChoice(pi: ExtensionAPI): void {
 	});
 
 	pi.on("before_agent_start", (_event, ctx) => {
-		reconcileToolAvailability(pi, ctx.mode === "tui");
+		reconcileToolAvailability(pi, isInteractiveMode(ctx.mode, process.env));
 	});
 }