gentle-pi 3.4.0 → 3.5.1

package/docs/readme-reference.md

@@ -135,15 +135,33 @@ Callers own keyboard policy, theme state, and business actions.
 
 ## Install
 
+Two paths reach the same package. Path A stays standalone; Path B installs into an existing pi.
+
+### Path A: standalone `gentle-shell` (recommended, no pi changes)
+
 ```bash
-pi install npm:gentle-pi@2.6.0
+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
 ```
 
-The stable release is [`v2.6.0`](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0). Restart Pi after installation, then run `gentle-ai sync`. That published release pairs with Gentle AI `v2.8.0` and provider contract `1.2.0`; capabilities `v2.5` are retained. The command above installs that exact published version.
+`gentle-shell` alone starts in its own home, `~/.gentle-shell/agent`. `gentle-shell --link` reuses `~/.pi/agent` as-is. Run `gentle-shell home link` to make `--link` the default. Full flags, env vars, and modes: [gentle-shell launcher](#gentle-shell-launcher).
+
+### Path B: inside an existing pi
+
+```bash
+pi install npm:gentle-pi@3.5.1
+```
+
+The stable release is [`v3.5.1`](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1). Restart Pi after installation, then run `gentle-ai sync`. That published release pairs with Gentle AI `v2.8.0` and provider contract `1.2.0`; capabilities `v2.5` are retained. The command above installs that exact published version.
 
 ### Source checkout
 
-This checkout prepares `gentle-pi` `3.4.0`; it is source state, not a published release. Its package-local native runtime pin is Gentle AI `v3.5.0`, distinct from the published `v2.6.0` pairing.
+This checkout prepares `gentle-pi` `3.5.1`; it is source state, not a published release. Its package-local native runtime pin is Gentle AI `v3.5.0`, distinct from the published `v3.5.1` pairing.
 
 The native SDD status consumer accepts both the pinned producer's legacy
 `apply`/`verify`/`remediate`/`archive` instruction record and the classical
@@ -161,13 +179,13 @@ Classical direct-archive behavior is compatibility-tested with an identified
 upstream development build, not presented as a published fix or version bump.
 The complete classical flow awaits a compatible published native version; this
 change does not bump the pin. Ordinary attempt governance and research/planning simplification remain separate
-work under [SDD parity #1051](https://github.com/Gentleman-Programming/gentle-pi/issues/1051).
+work under [SDD parity #1051](https://github.com/Gentleman-Programming/gentle-shell/issues/1051).
 
 ### Pi compatibility
 
 The current package requires Pi 0.85.1 or newer (development tests pin 0.85.1). Use the latest Pi release; gentle-pi does not update your installed Pi automatically. Children, including any `GENTLE_PI_AGENTS_PI` override, must emit `agent_settled`: `agent_end` records a run's output but is not completion because retries or queued continuations may follow.
 
-The [`v2.6.0` release](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0) adds persistent registered worktrees and grouped `/gentle:changes` views; fuller workspace interaction details are in the [Gentle Shell reference](gentle-shell.md). It also adds named atomic `/gentle:profiles`, parent-confirmed native SDD preflight transport, native review intended-untracked selection and provider continuations, and opt-in custom ask responses. Pi recognizes its global Git-managed package path; subsystems install with explicit recovery guidance when npm lifecycle work was skipped. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
+The [`v2.6.0` release](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v2.6.0) added persistent registered worktrees and grouped `/gentle:changes` views; fuller workspace interaction details are in the [Gentle Shell reference](gentle-shell.md). It also adds named atomic `/gentle:profiles`, parent-confirmed native SDD preflight transport, native review intended-untracked selection and provider continuations, and opt-in custom ask responses. Pi recognizes its global Git-managed package path; subsystems install with explicit recovery guidance when npm lifecycle work was skipped. Windows keeps child consoles hidden and fixes ownership mode; Gentle Todo keeps the next pending task visible when collapsed.
 
 ### Install-time fullscreen
 
@@ -179,18 +197,30 @@ Malformed/nonobject JSON, symlink/nonregular settings, unsafe paths, or a busy s
 
 ### RDD history and opt-in
 
-Native RDD was introduced in `gentle-pi` `v0.15.0` on 2026-07-10 with bounded review transactions. The current stable release, [`v2.6.0`](https://github.com/Gentleman-Programming/gentle-pi/releases/tag/v2.6.0), includes native RDD:
+Native RDD was introduced in `gentle-pi` `v0.15.0` on 2026-07-10 with bounded review transactions. The current stable release, [`v3.5.1`](https://github.com/Gentleman-Programming/gentle-shell/releases/tag/v3.5.1), includes native RDD:
 
 ```bash
 # Stable release
-pi install npm:gentle-pi@2.6.0
+pi install npm:gentle-pi@3.5.1
 ```
 
 RDD remains opt-in. Enable it only through an explicit user decision with `/gentle:review-mode enable`; `status` lets you inspect the mode without changing it.
 
 The source checkout's RDD integration installs Gentle AI only into its private `.gentle-ai/` directory. Darwin and Linux use pinned release assets with asset and executable SHA-256 verification (signed archives for source pin `v3.5.0`; raw prerelease binaries only under a prerelease pin). Windows x64 and arm64 build the exact `v3.5.0` source tag with a local Go 1.25.10+ toolchain, a sealed Go environment, `GOTOOLCHAIN=local`, and `GOSUMDB=sum.golang.org`; it does not download Go automatically. Windows provenance is Go-toolchain plus SumDB evidence and postinstall tamper detection, **not** Authenticode or protection against a malicious joint binary-and-manifest replacement. Package-private locks coordinate cooperative concurrent or crashed installers; their tombstones fail closed. A malicious same-user process with write access to package-private `node_modules` is outside that protocol because it can already replace package code, binary, or manifest, and portable Node has no pathname-delete CAS. It never uses `PATH` or a global `gentle-ai` installation. For development or offline installs only, set `GENTLE_PI_SKIP_GENTLE_AI_INSTALL=1`; native review operations then fail closed with an actionable `package-local-binary-missing` error. To recover explicitly, if `GENTLE_PI_SKIP_GENTLE_AI_INSTALL` is set, remove or unset it before changing to the installed `gentle-pi` package directory. Then run `node scripts/install-gentle-ai.mjs`. This invokes the package-owned installer without relying on a global binary or npm configuration change. A missing binary can result from skipped lifecycle scripts, but does not prove that lifecycle scripts were disabled.
 
-Recommended companion packages:
+Recommended companion packages, into the standalone `gentle-shell` home:
+
+```bash
+gentle-shell install npm:pi-intercom
+gentle-shell install npm:gentle-engram
+gentle-shell install npm:pi-web-access
+gentle-shell install npm:pi-lens
+gentle-shell install npm:@juicesharp/rpiv-ask-user-question
+```
+
+`--link` before the subcommand (for example `gentle-shell --link install npm:pi-intercom`) targets `~/.pi/agent` instead of the isolated home.
+
+Or, when `gentle-pi` is installed inside an existing pi:
 
 ```bash
 pi install npm:pi-intercom
@@ -225,6 +255,94 @@ 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. |
+| `--package-root <dir>` | Force this directory as the gentle-pi package to load, taking over from any conflicting package the target `settings.json` already declares (see "Loading the package" below). |
+| `--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).
+
+`gentle-shell update` and `gentle-shell list` follow that same home selection, so they inspect and update packages in whichever home the effective flag or persisted `home` config points to.
+
+### 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 declares gentle-pi (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 this 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 — and any take-over below — is skipped entirely and pi sees the bare subcommand, e.g. `gentle-shell install npm:x` runs exactly `pi install npm:x`. A subcommand never triggers a take-over, even against a home whose settings declare a conflicting gentle-pi; see "Managing packages" above.
+
+A declaration is recognized either as `npm:gentle-pi[@version]` in the `packages` array, or as a local path package (string or `{"source": "..."}` entry, relative or absolute) whose own `package.json` names it `"gentle-pi"` — the shape produced when gentle-pi is developed from a checkout and referenced by path in `settings.json` instead of installed via `pi install npm:gentle-pi`.
+
+- **A pi subcommand as the first forwarded argument**: no injection and no take-over at all, regardless of any declaration — pi must see the bare subcommand as `argv[0]`.
+- **npm declaration matching this launcher's own install**: no injection — pi already loads gentle-pi from the declared package.
+- **No declaration at all, or a path declaration that resolves (after `realpath`) to this launcher's own package root**: the same plain injection as above.
+- **A declaration that resolves to a *different* gentle-pi** (a different checkout declared by path, for example) **— take-over**: `gentle-shell` prints `taking over gentle-pi from <declared source> for this run (settings unchanged; its skills, prompts, and themes still load alongside this launcher's)` to stderr, then runs pi with `--no-extensions` followed by an explicit `-e <dir>` for every *other* package already in settings (npm entries resolve to `<agent dir>/npm/node_modules/<name>`; path entries resolve relative to the settings file), then loose extension entries for `<agent dir>/extensions` and the project-local `<cwd>/.pi/extensions` (each candidate directory only consulted when it already exists), and finally its own `-e <package root> --theme ... --skill ... --prompt-template ...`. `settings.json` itself is never modified, and every `-e` path — including the launcher's own package root — is injected at most once even if it would otherwise repeat.
+
+  A declared *other* package whose resolved directory does not actually exist (a hand-edited `settings.json`, a failed or interrupted `pi install`, or an npm store laid out anywhere other than `<agent dir>/npm/node_modules`) is skipped with a stderr warning naming the source and the resolved path, instead of being handed to pi as an unresolvable `-e` that would fail the whole launch with "Cannot find module".
+
+  `--no-extensions` disables pi's normal directory-discovery pass, and pi's `-e` flag hands a path straight to its module loader with no discovery of its own — passing a loose extensions directory as-is via `-e <dir>` fails with "Cannot find module" unless that directory is itself a self-contained extension. So each loose candidate directory is resolved before injection: a directory that is itself a self-contained extension (a `package.json` declaring a `pi.extensions` manifest) is passed through as a single `-e <dir>`; otherwise its direct `*.ts`/`*.js`/`*.mjs` files — including a root-level `index.ts`/`index.js`, which is just another loose file — and any `<subdir>/index.ts`/`index.js` are discovered individually — mirroring pi's own directory scan — and each is injected as its own `-e <file>`. Hidden entries (dotfiles) and `*.d.ts` declaration files are skipped, since neither was ever a runnable extension.
+
+  A git-sourced other package is skipped with a stderr warning, since its install directory cannot be derived without pi's own package manager; an object entry with `extensions` or `autoload` filters is still included but warned about, because the take-over cannot honor those filters for extension discovery — that package's skills, prompts, and themes still load normally through settings discovery, which `--no-extensions` does not affect.
+
+  **Known limitation**: the take-over never removes the original declaration from `settings.json`, so its skills, prompt templates, and themes are still discovered alongside this launcher's own — only its extensions are replaced by `--no-extensions` plus the injected `-e` flags above.
+- **`--package-root <dir>`**: forces a take-over using `<dir>` as the package root, even when settings already declare a matching `npm:gentle-pi`, or when there is no declaration at all. Use it to test a different gentle-pi checkout against a home whose settings already point at another one. Has no effect when the forwarded arguments start with a pi subcommand, since a subcommand skips the take-over entirely. The take-over path itself is only ever reached for `--link`: with `--isolated` or `--home <path>`, `--package-root` still changes which directory is injected, but always through the same plain injection as "no declaration at all" above — no `--no-extensions`, and no other-package or loose-extension re-injection — since those homes never carry a `settings.json` declaration to take over from. `--package-root` must also name an existing directory; a missing or non-directory path fails fast with a clear error instead of launching pi with unresolvable flags.
+
+This take-over exists because two gentle-pi copies loaded at once — the declared one plus this launcher's own injection — register the same tools and extensions twice, which pi reports as tool conflicts (for example `Tool ask_user_choice conflicts with ...`).
+
+### 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
@@ -308,7 +426,7 @@ Reconciliation is intentionally narrow: native code may quarantine only the boun
 
 Native lifecycle status remains informational. VALIDATE does not authorize delivery; commit, push, PR, and release commands follow ordinary repository policy. Recovery grants no new budget, and legacy graph bundle export/import is retired.
 
-This is the post-U8 boundary, not the final architecture. [Issue #191](https://github.com/Gentleman-Programming/gentle-pi/issues/191) is the immediate final unit in this same delivery: extract the remaining Pi command-projection and lifecycle-gate surface from `review-transaction.ts`, repoint runtime enforcement, then delete only dependencies proven unreachable without weakening graph-v1 Judgment Day. The branch-wide High-tier 4R runs after that extraction, before the single size-exception PR.
+This is the post-U8 boundary, not the final architecture. [Issue #191](https://github.com/Gentleman-Programming/gentle-shell/issues/191) is the immediate final unit in this same delivery: extract the remaining Pi command-projection and lifecycle-gate surface from `review-transaction.ts`, repoint runtime enforcement, then delete only dependencies proven unreachable without weakening graph-v1 Judgment Day. The branch-wide High-tier 4R runs after that extraction, before the single size-exception PR.
 
 ### Review Lens Selection (architecture reference)
 
@@ -1071,10 +1189,10 @@ tag="v${version}"
 git fetch --no-tags origin "refs/tags/${tag}"
 test "$(git rev-parse 'FETCH_HEAD^{commit}')" = "$(git rev-parse "${tag}^{commit}")"
 gh workflow run publish.yml \
-  --repo Gentleman-Programming/gentle-pi \
+  --repo Gentleman-Programming/gentle-shell \
   --ref main \
   -f tag="${tag}"
-gh run watch <run-id> --repo Gentleman-Programming/gentle-pi --exit-status
+gh run watch <run-id> --repo Gentleman-Programming/gentle-shell --exit-status
 npm view gentle-pi@<version> version --registry=https://registry.npmjs.org/
 npm dist-tag ls gentle-pi --registry=https://registry.npmjs.org/
 ```

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));
 	});
 }

package/extensions/ask-user-question.ts

@@ -1,14 +1,15 @@
-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 { Text } from "@earendil-works/pi-tui";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
-import { type QuestionParams, QuestionParamsSchema } from "../lib/questionnaire/schema.ts";
+import { type QuestionData, type QuestionParams, QuestionParamsSchema } from "../lib/questionnaire/schema.ts";
 import {
 	QuestionnaireView,
 	type AnswerRow,
 	type QuestionnaireResult,
 } from "../lib/questionnaire/questionnaire-view.ts";
 import { validateQuestionnaire, type QuestionnaireError } from "../lib/questionnaire/validate.ts";
+import { isInteractiveRpcHost } from "../lib/rpc-host.ts";
 
 const QUESTION_TOOL_NAME = "ask_user_question";
 const ASK_USER_QUESTION_BLOCKED_EVENT = "gentle-pi:ask-user-question:blocked";
@@ -51,6 +52,124 @@ function unavailableResult(): QuestionnaireToolResult {
 	};
 }
 
+/** Same cancellation shape the TUI questionnaire returns for its Escape key. */
+function cancelledResult(): QuestionnaireToolResult {
+	return {
+		content: [{ type: "text", text: "User cancelled the questionnaire" }],
+		details: { cancelled: true },
+	};
+}
+
+/** Label for the trailing "finish this question" entry in a multiSelect round. */
+const MULTI_SELECT_DONE_LABEL = "Done";
+
+/** One toggle round's select prompt: `[x] label` / `[ ] label` plus Done. */
+function multiSelectRoundOptions(question: QuestionData, toggled: readonly boolean[]): string[] {
+	return [
+		...question.options.map((choiceOption, index) => `${toggled[index] ? "[x]" : "[ ]"} ${choiceOption.label}`),
+		MULTI_SELECT_DONE_LABEL,
+	];
+}
+
+/**
+ * Floor for the toggle-round safety cap so a misbehaving or chatty host
+ * cannot spin this loop forever, and every question -- however few options
+ * it has -- still gets room to toggle, untoggle, and retoggle before Done.
+ */
+const MULTI_SELECT_ROUND_CAP_FLOOR = 32;
+
+/**
+ * Hard bound on toggle rounds for one question: every option must be
+ * toggleable at least once, plus one round for the explicit Done and one
+ * spare round for a single correction (an un-toggle), so the cap scales
+ * with the option count (`options.length + 2`), floored at
+ * `MULTI_SELECT_ROUND_CAP_FLOOR` for small questions.
+ */
+function multiSelectRoundCap(optionsLength: number): number {
+	return Math.max(MULTI_SELECT_ROUND_CAP_FLOOR, optionsLength + 2);
+}
+
+/** Committed multiSelect answer from the current toggle state (explicit Done, or every option toggled on). */
+function finishMultiSelect(question: QuestionData, toggled: readonly boolean[]): AnswerRow {
+	return {
+		questionIndex: -1, // overwritten by the caller with the question's position
+		question: question.question,
+		kind: "multi",
+		answer: null,
+		selected: question.options.filter((_choiceOption, index) => toggled[index]).map((choiceOption) => choiceOption.label),
+	};
+}
+
+/**
+ * Resolves one multiSelect question by looping `ctx.ui.select` over toggle
+ * rounds, bounded by `multiSelectRoundCap`. Returns `undefined` on
+ * cancellation, when the cap is hit without an explicit Done, and when the
+ * host returns an answer that matches none of the current round's options:
+ * a partial toggle state must never commit silently in either case.
+ */
+export async function askMultiSelect(
+	ctx: Pick<ExtensionContext, "ui">,
+	question: QuestionData,
+): Promise<AnswerRow | undefined> {
+	const toggled = question.options.map(() => false);
+	const roundCap = multiSelectRoundCap(question.options.length);
+	for (let round = 0; round < roundCap; round++) {
+		const roundOptions = multiSelectRoundOptions(question, toggled);
+		const picked = await ctx.ui.select(`${question.header}: ${question.question}`, roundOptions);
+		if (picked === undefined) return undefined;
+		const pickedIndex = roundOptions.indexOf(picked);
+		if (pickedIndex === question.options.length) return finishMultiSelect(question, toggled); // explicit Done
+		if (pickedIndex === -1) return undefined; // unrecognised answer: never commit a partial state
+		toggled[pickedIndex] = !toggled[pickedIndex];
+		if (toggled.every(Boolean)) return finishMultiSelect(question, toggled);
+	}
+	// The safety cap was spent without an explicit Done: refuse to commit a
+	// partial selection silently and cancel instead.
+	return undefined;
+}
+
+/** Resolves one single-select question through `ctx.ui.select`. Returns `undefined` on cancellation. */
+async function askSingleSelect(
+	ctx: Pick<ExtensionContext, "ui">,
+	question: QuestionData,
+): Promise<AnswerRow | undefined> {
+	const labels = question.options.map((choiceOption) => choiceOption.label);
+	const picked = await ctx.ui.select(`${question.header}: ${question.question}`, labels);
+	if (picked === undefined) return undefined;
+	const chosen = question.options.find((choiceOption) => choiceOption.label === picked);
+	return {
+		questionIndex: -1, // overwritten by the caller with the question's position
+		question: question.question,
+		kind: "option",
+		answer: picked,
+		...(chosen?.preview !== undefined ? { preview: chosen.preview } : {}),
+	};
+}
+
+/**
+ * Interactive-RPC-host fallback for the TUI questionnaire: one
+ * `ctx.ui.select` dialog per question (looped for multiSelect), keeping the
+ * exact TUI result shapes. A cancel on any question cancels the whole
+ * questionnaire, matching the TUI Escape key. There is no schema-declared
+ * free-text option (`lib/questionnaire/schema.ts` has none), so the
+ * always-available "Type something." row has no RPC-dialog equivalent here.
+ */
+async function askThroughDialogs(
+	ctx: Pick<ExtensionContext, "ui">,
+	params: QuestionParams,
+): Promise<QuestionnaireToolResult> {
+	const answers: AnswerRow[] = [];
+	for (let questionIndex = 0; questionIndex < params.questions.length; questionIndex++) {
+		const question = params.questions[questionIndex]!;
+		const answer = question.multiSelect
+			? await askMultiSelect(ctx, question)
+			: await askSingleSelect(ctx, question);
+		if (answer === undefined) return cancelledResult();
+		answers.push({ ...answer, questionIndex });
+	}
+	return { content: [{ type: "text", text: answersText(answers) }], details: { answers } };
+}
+
 /**
  * Human-readable body for one answer. A custom answer on a multiSelect
  * question keeps the toggled options, so the text must name them explicitly:
@@ -145,7 +264,16 @@ export default function askUserQuestion(pi: ExtensionAPI): void {
 		): Promise<QuestionnaireToolResult> {
 			const error = validateQuestionnaire(params);
 			if (error) return invalidQuestionnaireResult(error);
-			if (ctx.mode !== "tui") return unavailableResult();
+			if (ctx.mode !== "tui") {
+				if (!isInteractiveRpcHost(ctx.mode, process.env)) return unavailableResult();
+				try {
+					pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: true });
+					return await askThroughDialogs(ctx, params);
+				}
+				finally {
+					pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: false });
+				}
+			}
 
 			let selection: QuestionnaireResult | undefined;
 			try {

package/extensions/gentle-agents.ts

@@ -28,6 +28,8 @@ import { historyDir, loadHistory, loadStoredTask, pruneHistory, saveTask } from
 import { sessionToMarkdown } from "../lib/agents-transcript.ts";
 import { AgentsView } from "../lib/agents-view.ts";
 import { PresencePublisher } from "../lib/orchestrator-presence.ts";
+import { createRpcActivityPublisher, type RpcActivityPublisher } from "../lib/agents-rpc-publisher.ts";
+import { isInteractiveRpcHost } from "../lib/rpc-host.ts";
 import { createNativeFullscreenInteraction } from "../lib/native-fullscreen-interaction.ts";
 import { AGENTS_GLYPH, renderAgentsCard, widgetExpiryMs, widgetRows } from "../lib/agents-widget.ts";
 import { CARD_TONE, renderCard } from "../lib/shell-card.ts";
@@ -476,6 +478,12 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 	let sidebarTui: TUI | undefined;
 	let sessions: ExtensionContext["sessionManager"] | undefined;
 	let presence: PresencePublisher | undefined;
+	let rpcActivityPublisher: RpcActivityPublisher | undefined;
+	// Messages already surfaced to the user this session through the RPC
+	// activity publisher's `onError`, so a recurring push failure (the
+	// coalescing window retries every burst) notifies at most once per
+	// session instead of flooding the UI. Reset on every `session_start`.
+	let notifiedRpcActivityErrors: Set<string> | undefined;
 	const overlays = new Set<AgentsView>();
 	const publishActivity = () => {
 		if (!sessions) return;
@@ -1450,12 +1458,37 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 			publishActivity();
 		} catch { presence = undefined; }
 		void startSessionTransport(ctx);
+		// The desktop app's own pi process: publish live subagent state through
+		// setWidget's RPC-mode string[] path. Plain headless RPC (no variable) and
+		// TUI are untouched -- the TUI card above the editor is showWidget's own
+		// factory push, ignored by pi's RPC transport since it is not an array.
+		rpcActivityPublisher?.stop();
+		rpcActivityPublisher = undefined;
+		notifiedRpcActivityErrors = new Set();
+		if (ctx.hasUI && isInteractiveRpcHost(ctx.mode, deps.env)) {
+			rpcActivityPublisher = createRpcActivityPublisher({
+				store,
+				ui: { setWidget: (key, lines) => ctx.ui.setWidget(key, lines) },
+				now: deps.now,
+				schedule: deps.schedule,
+				parentSessionId: activeSessionId(),
+				onError: (error) => {
+					const message = `Gentle Agents activity push failed: ${error instanceof Error ? error.message : String(error)}`;
+					if (notifiedRpcActivityErrors?.has(message)) return;
+					notifiedRpcActivityErrors?.add(message);
+					ctx.ui.notify(message, "warning");
+				},
+			});
+			rpcActivityPublisher.start();
+		}
 	});
 	pi.on("session_shutdown", async () => {
 		completions.dropAll();
 		activeAgentRuns = 0;
 		presence?.dispose();
 		presence = undefined;
+		rpcActivityPublisher?.stop();
+		rpcActivityPublisher = undefined;
 		cancelClock?.();
 		for (const view of overlays) { view.handleInput("q"); view.dispose(); }
 		overlays.clear();