gentle-pi 3.3.0 → 3.4.0

package/extensions/ask-user-question.ts

@@ -0,0 +1,210 @@
+import type { ExtensionAPI } 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 {
+	QuestionnaireView,
+	type AnswerRow,
+	type QuestionnaireResult,
+} from "../lib/questionnaire/questionnaire-view.ts";
+import { validateQuestionnaire, type QuestionnaireError } from "../lib/questionnaire/validate.ts";
+
+const QUESTION_TOOL_NAME = "ask_user_question";
+const ASK_USER_QUESTION_BLOCKED_EVENT = "gentle-pi:ask-user-question:blocked";
+
+/** Maximum characters kept from a renderCall question summary. */
+const CALL_SUMMARY_LIMIT = 120;
+
+/** Structured details returned by the tool for UI rendering and callers. */
+interface QuestionnaireDetails {
+	cancelled?: boolean;
+	answers?: AnswerRow[];
+	error?: QuestionnaireError;
+	errorKind?: string;
+}
+
+/** Content plus details returned by `execute`. */
+interface QuestionnaireToolResult {
+	content: Array<{ type: "text"; text: string }>;
+	details: QuestionnaireDetails;
+}
+
+/**
+ * Invalid-parameter result. `AgentToolResult` has no `isError` field, so this
+ * follows the repository convention for rejected tool input: a leading error
+ * sentence in `content` plus a machine-readable payload in `details`
+ * (`extensions/gentle-todo.ts` returns `Error: ...` with `details.error`).
+ */
+function invalidQuestionnaireResult(error: QuestionnaireError): QuestionnaireToolResult {
+	return {
+		content: [{ type: "text", text: `Invalid questionnaire: ${error.message}` }],
+		details: { error, errorKind: error.code },
+	};
+}
+
+/** Non-interactive result; parity with ask_user_choice's TUI-only guard. */
+function unavailableResult(): QuestionnaireToolResult {
+	return {
+		content: [{ type: "text", text: "Error: ask_user_question is unavailable outside the interactive TUI" }],
+		details: { errorKind: "unavailable_outside_tui" },
+	};
+}
+
+/**
+ * Human-readable body for one answer. A custom answer on a multiSelect
+ * question keeps the toggled options, so the text must name them explicitly:
+ * the free-text value alone would silently drop the user's selections. Plain
+ * custom answers (no selections) stay concise.
+ */
+function answerBody(answer: AnswerRow): string {
+	if (answer.kind === "multi") return `selected: ${(answer.selected ?? []).join(", ")}`;
+	if (answer.kind === "custom") {
+		const body = `(custom) ${answer.answer ?? ""}`;
+		const selected = answer.selected ?? [];
+		return selected.length > 0 ? `${body} — selected: ${selected.join(", ")}` : body;
+	}
+	return answer.answer ?? "";
+}
+
+/**
+ * Compact LLM-facing transcript of the committed answers. Each row keeps the
+ * original one-based question index so a partially answered questionnaire
+ * (the last question committed early) still reads in order.
+ */
+function answersText(answers: AnswerRow[]): string {
+	if (answers.length === 0) return "The user answered the questionnaire.";
+	const lines: string[] = [];
+	for (const answer of answers) {
+		const prefix = `${answer.questionIndex + 1}. ${answer.question}`;
+		lines.push(`${prefix} — ${answerBody(answer)}`);
+		if (answer.preview !== undefined) lines.push(`   selected preview: ${answer.preview}`);
+	}
+	return lines.join("\n");
+}
+
+/** Single-line summary of one question for the collapsed tool call row. */
+function callSummary(question: unknown, index: number): string {
+	const source = typeof question === "object" && question !== null ? question as { header?: unknown; options?: unknown } : {};
+	const header = typeof source.header === "string" ? source.header : "";
+	const labels = Array.isArray(source.options)
+		? source.options
+			.map((option) => (typeof option === "object" && option !== null && typeof (option as { label?: unknown }).label === "string"
+				? (option as { label: string }).label
+				: ""))
+			.filter((label) => label.length > 0)
+		: [];
+	const labelsPart = labels.length > 0 ? ` (${labels.join(", ")})` : "";
+	return `${index + 1}. ${header}${labelsPart}`;
+}
+
+function truncate(text: string, limit: number): string {
+	return text.length <= limit ? text : `${text.slice(0, Math.max(0, limit - 1))}…`;
+}
+
+/**
+ * Register the first-party questionnaire tool.
+ *
+ * Name-collision semantics (live-verified against the installed Pi runtime):
+ * - Tool names are exclusive across extensions. Pi has no precedence, override,
+ *   or silent shadowing: loading two extensions that register the same tool
+ *   name fails the whole load with a hard error
+ *   (`Tool "ask_user_question" conflicts with <other extension>`; the runtime
+ *   exits non-zero). The name is either free or fatal, full stop.
+ * - `registerTool` writes into the calling extension's own tool map keyed by
+ *   name, so re-registering inside one extension overwrites that entry
+ *   (`loader.js:240`). That same-name write is the only one Pi tolerates.
+ * - This first-party tool ships as THE `ask_user_question` provider. A competing
+ *   provider such as the third-party `@juicesharp/rpiv-ask-user-question`
+ *   package fails the load by design and must be removed from the user's Pi
+ *   settings; that deletion is the documented migration path, not a runtime
+ *   precedence choice.
+ */
+export default function askUserQuestion(pi: ExtensionAPI): void {
+	pi.registerTool({
+		name: QUESTION_TOOL_NAME,
+		renderShell: "self",
+		label: "Ask User Question",
+		description: "Ask one to four structured questions in a single call, each with two to four ordered options, and read the user's answers back in one result.",
+		promptGuidelines: [
+			"Use ask_user_question to collect decisions in one batch: ask one to four questions at a time, each with two to four options.",
+			"Keep each header a short chip of at most 16 characters and each option label at most 60 characters.",
+			"Add a preview to an option when the user needs to compare rich detail side-by-side with the options.",
+			"Set multiSelect when the choices are not mutually exclusive.",
+			"The free-text \"Type something.\" row is always available and is also how the user bails out into a normal conversation; never rely on it as a hidden escape hatch.",
+			"Never use this tool for decisions that must not be delegated to the user.",
+		],
+		parameters: QuestionParamsSchema,
+		executionMode: "sequential",
+		async execute(
+			_toolCallId: string,
+			params: QuestionParams,
+			_signal: AbortSignal | undefined,
+			_onUpdate: undefined,
+			ctx,
+		): Promise<QuestionnaireToolResult> {
+			const error = validateQuestionnaire(params);
+			if (error) return invalidQuestionnaireResult(error);
+			if (ctx.mode !== "tui") return unavailableResult();
+
+			let selection: QuestionnaireResult | undefined;
+			try {
+				pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: true });
+				selection = await ctx.ui.custom<QuestionnaireResult>((tui, theme, keybindings, done) => {
+					const view = new QuestionnaireView({
+						questions: params.questions,
+						theme,
+						keybindings,
+						onComplete: (result) => done(result),
+					});
+					// Native dock swap, never an overlay: the transcript stays scrollable
+					// while the questionnaire owns focus. No `overlay` option is passed.
+					const container = createNativeFullscreenInteraction({
+						keyboardTarget: view,
+						requestRender: () => tui.requestRender(),
+					});
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					container.addChild(view);
+					container.addChild(new DynamicBorder((text: string) => theme.fg("accent", text)));
+					return container;
+				});
+			}
+			finally {
+				pi.events.emit(ASK_USER_QUESTION_BLOCKED_EVENT, { active: false });
+			}
+
+			if (selection === undefined || selection.cancelled) {
+				return {
+					content: [{ type: "text", text: "User cancelled the questionnaire" }],
+					details: { cancelled: true },
+				};
+			}
+			return {
+				content: [{ type: "text", text: answersText(selection.answers) }],
+				details: { answers: selection.answers },
+			};
+		},
+		renderCall(args: QuestionParams, theme) {
+			const questions = Array.isArray(args.questions) ? args.questions : [];
+			const summary = truncate(questions.map((question, index) => callSummary(question, index)).join(" "), CALL_SUMMARY_LIMIT);
+			return new Text(
+				theme.fg("toolTitle", theme.bold("ask_user_question ")) +
+				theme.fg("muted", summary),
+				0,
+				0,
+			);
+		},
+		renderResult(result, _options, theme) {
+			const details = result.details as QuestionnaireDetails | undefined;
+			if (details?.cancelled === true) return new Text(theme.fg("warning", "Cancelled"), 0, 0);
+			const answers = Array.isArray(details?.answers) ? details.answers : [];
+			if (answers.length === 0) return new Text(theme.fg("warning", "No answers"), 0, 0);
+			const lines = answers.map((answer) => {
+				if (answer.kind === "multi") return theme.fg("success", `✓ ${answer.question} — ${(answer.selected ?? []).join(", ")}`);
+				if (answer.kind === "custom") return theme.fg("success", `✓ ${answer.question} — ${answerBody(answer)}`);
+				return theme.fg("success", `✓ ${answer.question} — ${answer.answer ?? ""}`);
+			});
+			return new Text(lines.join("\n"), 0, 0);
+		},
+	});
+}

package/extensions/gentle-agents.ts

@@ -17,6 +17,7 @@ import { invalidateSidebar } from "../lib/shell-sidebar-layout.ts";
 import { createCompletionQueue } from "../lib/agents-completion-delivery.ts";
 import { AGENT_MODE, discoverAgents, parseAgentDefinition, loadAgentsConfig, resolveAgentProfile, withPinnedModelProfiles, type AgentDefinition, type AgentMode } from "../lib/agents-config.ts";
 import { resolveBackgroundSubagentsPolicy } from "../lib/background-subagents-policy.ts";
+import { installBackgroundCacheWarming } from "../lib/background-cache-warming.ts";
 import { isFinished, TASK_EVENT, TASK_STATUS, TaskStore, type AskRequest, type TaskRecord } from "../lib/agents-protocol.ts";
 import { AgentRunner, piCommand, abortReasonText, plannedCommands, type RemediationPlan, type RemediationScope, REMEDIATION_PLAN_ENV, parseRemediationPlan, type AskAnswer, type RunnerDeps, type SddChangeSelection, type TaskRequest } from "../lib/agents-runner.ts";
 import { ChildMessenger, type IpcEndpoint } from "../lib/agents-messaging.ts";
@@ -529,6 +530,12 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 	// started before /new or /resume stays in the store and comes back with
 	// its session. Before the first session_start there is nothing to scope by.
 	const activeSessionId = (): string | undefined => (sessions === undefined ? undefined : sessions.getSessionId() ?? "");
+	// Pi 0.86.1 adds this event; the package's pinned 0.85.1 types predate it.
+	installBackgroundCacheWarming(pi as unknown as Parameters<typeof installBackgroundCacheWarming>[0], () => ({
+		sessionId: activeSessionId(),
+		ownedTaskIds,
+		tasks: store.list(activeSessionId()),
+	}));
 	const visibleTasks = (): TaskRecord[] => store.list(activeSessionId());
 	type SessionTransport = { generation: number; sessionId: string; sessionManager: ExtensionContext["sessionManager"]; client: SessionTransportClient; listener: SessionTransportListener; registry: SessionTransportRegistry; close(): Promise<void> };
 	let transportGeneration = 0;
@@ -1168,7 +1175,7 @@ export default function gentleAgents(pi: ExtensionAPI, env: NodeJS.ProcessEnv =
 		if (observe) metricTasks.set(task.id, metrics);
 		ownedTaskIds.add(task.id);
 		store.subscribe(task.id, () => { publishActivity(); requestRender(); });
-		if (request.mode === AGENT_MODE.BACKGROUND) return text(`Started ${task.agent} in the background as task ${task.id}. Use subagent_status or subagent_result with that id.`, taskDetails(task));
+		if (request.mode === AGENT_MODE.BACKGROUND) return text(`Started ${task.agent} in the background as task ${task.id}. Retain that id; completion is pushed automatically. Never sleep or periodically poll subagent_status/subagent_result for completion or cache maintenance. Inspect status only at a real orchestration decision boundary; never relaunch equivalent queued/running work.`, taskDetails(task));
 		// A tool call aborted by the host (a human interrupting the turn, a timeout)
 		// would otherwise leave the child running and end the call with no result and
 		// no recorded reason. Cancel through the runner so the lifecycle runs and the

package/extensions/gentle-ai.ts

@@ -199,6 +199,7 @@ import {
 	nativeReviewRecoverAuthorization,
 	normalizeNativeReviewCwd,
 	NativeReviewCliError,
+	nativeUntrackedSelection,
 	NativeReviewConsentBindingError,
 	NativeReviewConsentRequiredError,
 	NativeReviewIntegrationError,
@@ -1023,18 +1024,26 @@ async function resolveReviewAssessmentPlan(
 
 	let assessment: ReviewAssessmentV1 | undefined;
 	let unassessableDetail: string | undefined;
+	let unassessableCode = "native-assess-unavailable";
 	if (nativeReviewCli?.assess === undefined) {
 		unassessableDetail = "native review assess is unavailable: the installed gentle-ai binary does not expose the assess command.";
 	} else {
 		try {
 			const request: NativeReviewAssessRequest = {
 				cwd,
+				...nativeUntrackedSelection(input),
 				...(input.baseRef === undefined ? {} : { baseRef: input.baseRef, committedOnly: true as const }),
 				...(signal === undefined ? {} : { signal }),
 			};
 			assessment = await nativeReviewCli.assess(request);
 		} catch (error) {
-			unassessableDetail = `native review assess failed: ${error instanceof Error ? error.message : String(error)}`;
+			const nativeError = asNativeReviewCliError(error);
+			unassessableCode = nativeError?.code ?? unassessableCode;
+			// Only the sanitized process surface may supply native evidence.
+			// Arbitrary thrown messages can contain argv or environment values.
+			unassessableDetail = nativeError?.diagnostics.stderr
+				? `native review assess failed: ${nativeError.diagnostics.stderr}`
+				: "native review assess failed; no sanitized stderr diagnostic is available.";
 		}
 	}
 
@@ -1050,7 +1059,7 @@ async function resolveReviewAssessmentPlan(
 	return {
 		schema: "gentle-pi.review-assessment-plan/v1",
 		risk,
-		reasons: assessment?.reasons ?? (unassessableDetail === undefined ? [] : [{ code: "native-assess-unavailable", path: "", detail: unassessableDetail }]),
+		reasons: assessment?.reasons ?? (unassessableDetail === undefined ? [] : [{ code: unassessableCode, path: "", detail: unassessableDetail }]),
 		changedPaths: assessment?.changedPaths ?? 0,
 		changedLines: assessment?.changedLines ?? 0,
 		candidate: assessment === undefined ? null : { kind: assessment.candidate.kind, baseRef: assessment.candidate.baseRef },
@@ -4826,7 +4835,7 @@ interface ReviewScopeParameters {
 // as `gentle_review` operation `assess` (not a dedicated tool), taking its
 // optional fields through the controller's existing generic `input` JSON
 // string, exactly like START's `{"mode":...,"baseRef":...}`.
-interface ReviewAssessInput {
+interface ReviewAssessInput extends Pick<NativeReviewAssessRequest, "untrackedScope" | "expectedUntrackedInventory" | "intendedUntracked"> {
 	baseRef?: string;
 	committedOnly?: boolean;
 	writerModelId?: string;
@@ -4845,7 +4854,7 @@ function isNativeReviewOutcome(value: unknown): value is NativeReviewOutcome {
 function parseReviewAssessInput(operation: ReviewControllerOperation, raw: string | undefined): ReviewAssessInput {
 	if (raw === undefined) return {};
 	const value = parseControllerJson(raw, operation);
-	const allowed = new Set(["baseRef", "committedOnly", "writerModelId", "writerEffort", "nativeReviewOutcome"]);
+	const allowed = new Set(["baseRef", "committedOnly", "writerModelId", "writerEffort", "nativeReviewOutcome", "untrackedScope", "expectedUntrackedInventory", "intendedUntracked"]);
 	const unexpected = Object.keys(value).find((key) => !allowed.has(key));
 	if (unexpected !== undefined) throw new Error(`Review controller ${operation} input does not accept ${unexpected}`);
 	const { baseRef, committedOnly, writerModelId, writerEffort, nativeReviewOutcome } = value;
@@ -4859,6 +4868,7 @@ function parseReviewAssessInput(operation: ReviewControllerOperation, raw: strin
 	return {
 		...(baseRef === undefined ? {} : { baseRef: baseRef as string }),
 		...(committedOnly === undefined ? {} : { committedOnly: committedOnly as boolean }),
+		...nativeUntrackedSelection(value),
 		...(writerModelId === undefined ? {} : { writerModelId: writerModelId as string }),
 		...(writerEffort === undefined ? {} : { writerEffort: writerEffort as string }),
 		...(nativeReviewOutcome === undefined ? {} : { nativeReviewOutcome: nativeReviewOutcome as NativeReviewOutcome }),
@@ -6754,6 +6764,11 @@ async function executeReviewHostRelayCapture(
 	route: RetainedNativeCaptureRoute | undefined,
 	signal?: AbortSignal,
 	modelRegistry?: InProcessReviewerRegistry,
+	// The caller's live session id: forwarded into the relay request so an
+	// OpenCode-routed reviewer completion carries its x-opencode-session
+	// attribution header. Appended last so every existing positional call site
+	// keeps compiling unchanged.
+	reviewerSessionId?: string,
 ): Promise<Record<string, unknown>> {
 	try {
 		if (slot.submission === undefined) {
@@ -6777,6 +6792,7 @@ async function executeReviewHostRelayCapture(
 				submission: slot.submission,
 				...launch,
 				...(modelRegistry === undefined ? {} : { reviewerRegistry: modelRegistry }),
+				...(reviewerSessionId === undefined ? {} : { reviewerSessionId }),
 				...(signal === undefined ? {} : { signal }),
 			};
 		})());
@@ -7379,6 +7395,11 @@ async function executeReviewCaptureOperation(
 	// inserted) so every existing positional call site — none of which pass an
 	// eighth argument — keeps compiling unchanged.
 	modelRegistry?: InProcessReviewerRegistry,
+	// The caller's live session id, threaded into every relay request this
+	// capture launches so an OpenCode-routed reviewer model carries its
+	// x-opencode-session attribution header. Appended last for the same
+	// positional-call-site reason as modelRegistry above.
+	reviewerSessionId?: string,
 ): Promise<Record<string, unknown>> {
 	const parameters = parseReviewCaptureParameters(parametersValue);
 	if (nativeReviewCli === null || nativeReviewCli.targetStatus === undefined) {
@@ -7438,7 +7459,7 @@ async function executeReviewCaptureOperation(
 				mutation_outcome: "none",
 			};
 		}
-		return withCorrectionTarget(await executeReviewHostRelayCapture(hostRelaySlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry));
+		return withCorrectionTarget(await executeReviewHostRelayCapture(hostRelaySlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry, reviewerSessionId));
 	}
 
 	// gentle-pi#311 P3: gentle-ai's v9 contract renders the refuter and
@@ -7464,7 +7485,7 @@ async function executeReviewCaptureOperation(
 				mutation_outcome: "none",
 			};
 		}
-		return withCorrectionTarget(await executeReviewHostRelayCapture(hostMediatedRoleSlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry));
+		return withCorrectionTarget(await executeReviewHostRelayCapture(hostMediatedRoleSlots[0]!, nativeReviewCli, cwd, selected.binding, retainedUntrackedSelections, route, signal, modelRegistry, reviewerSessionId));
 	}
 
 	if (selected.input.captureOperation === "review.capture-correction-plan") {
@@ -7545,6 +7566,10 @@ async function executeReviewCaptureGroupOperation(
 	requireRegisteredRoute = false,
 	// gentle-pi#311 P2: see executeReviewCaptureOperation's matching parameter.
 	modelRegistry?: InProcessReviewerRegistry,
+	// The caller's live session id, set on every grouped relay request so an
+	// OpenCode-routed reviewer model carries its x-opencode-session attribution
+	// header. Appended last for the same positional-call-site reason as above.
+	reviewerSessionId?: string,
 ): Promise<Record<string, unknown>> {
 	const parameters = parseReviewCaptureGroupParameters(parametersValue);
 	if (nativeReviewCli === null || nativeReviewCli.targetStatus === undefined) return { ...captureGroupRejected("native target STATUS is unavailable"), outcome: "native-status-unsupported" };
@@ -7587,6 +7612,7 @@ async function executeReviewCaptureGroupOperation(
 		submission: slot.submission!,
 		...reviewHostRelaySelection(slot.lens, readModelConfig(cwd)),
 		...(modelRegistry === undefined ? {} : { reviewerRegistry: modelRegistry }),
+		...(reviewerSessionId === undefined ? {} : { reviewerSessionId }),
 		...(signal === undefined ? {} : { signal }),
 	}));
 	let prepared: readonly ReviewHostRelayPreparedResult[];
@@ -8317,11 +8343,13 @@ async function executeReviewControllerOperation(
 				// native START are resolved, and re-derive the target for that range,
 				// so all three agree on one base-diff identity. Adopting the offer
 				// later left the workspace target and the base-diff candidate view
-				// disagreeing, and START failed with identity-mismatch. Both an
-				// explicit caller baseRef and any START with an untracked selection in
-				// play keep today's single-STATUS flow; only an adopted offer pays the
-				// second read-only STATUS.
-				if (canonicalBaseRef === undefined && untrackedSelection.untrackedScope === undefined && untrackedSubmission === undefined) {
+				// disagreeing, and START failed with identity-mismatch. An explicit
+				// caller baseRef still wins (it already is the adopted range), but an
+				// in-play untracked selection now also pays this second read-only
+				// STATUS: the renegotiated target is a base-diff projection, so the
+				// candidate view must be materialized WITH the offered base instead of
+				// the base-less view that tripped candidate-target-projection-drift.
+				if (canonicalBaseRef === undefined) {
 					const offeredBaseRef = offeredCommittedRangeBaseRef(target);
 					if (offeredBaseRef !== undefined) {
 						const renegotiated = await negotiatedStatusForHostTransport(nativeReviewCli, {
@@ -8329,6 +8357,8 @@ async function executeReviewControllerOperation(
 							...(parameters.lineageId === undefined ? {} : { lineageId: parameters.lineageId }),
 							baseRef: offeredBaseRef,
 							committedOnly: true,
+							...(untrackedSelection.untrackedScope === undefined ? {} : untrackedSelection),
+							...(untrackedSubmission === undefined ? {} : { intendedUntrackedSelection: untrackedSubmission }),
 							...(signal === undefined ? {} : { signal }),
 						}, retainedUntrackedSelections, defaultCwd);
 						if (renegotiated.transport !== undefined) return hostTransportUnavailable(parameters.operation, renegotiated.transport);
@@ -8375,11 +8405,7 @@ async function executeReviewControllerOperation(
 			let nativeStartAttempted = false;
 			try {
 				const candidateRequest = { contributorRoot: defaultCwd, replayKey, ...(canonicalBaseRef === undefined ? {} : { baseRef: canonicalBaseRef, committedOnly: true }) };
-				candidateView = candidateViews?.createOrReuse({ ...candidateRequest, ...(candidateIntendedUntracked.length === 0 ? {} : { intendedUntracked: candidateIntendedUntracked }) });
-				if (candidateView !== undefined && candidateIntendedUntracked.length === 0 && candidateView.candidateTree !== target.projection.currentCandidateTree) {
-					candidateView.cleanup();
-					candidateView = candidateViews?.createOrReuse({ ...candidateRequest, intendedUntracked: [] });
-				}
+				candidateView = candidateViews?.createOrReuse({ ...candidateRequest, intendedUntracked: candidateIntendedUntracked });
 				if (candidateView !== undefined) assertNativeStartCandidateBinding(candidateView, target);
 				let result: NativeStartResult;
 				try {
@@ -8860,6 +8886,10 @@ function createGentleAiExtensionForTesting(
 				((sessionKey: PendingReviewConsentSessionKey) => processRetainedNativeStatusSelections.get(sessionKey) ?? processRetainedNativeStatusSelections.set(sessionKey, new Map()).get(sessionKey)!)(pendingReviewConsentSessionKey(ctx, pendingReviewConsentFallbackKey)),
 				true,
 				ctx.modelRegistry,
+				// The live session id rides into the reviewer side-call so an
+				// OpenCode-routed completion carries its attribution headers
+				// (pi adds those inside the main agent loop; this is not that loop).
+				reviewSessionManagerAndId(ctx)?.sessionId,
 			);
 			return { content: [{ type: "text", text: JSON.stringify(details) }], details };
 		},
@@ -8899,6 +8929,10 @@ function createGentleAiExtensionForTesting(
 				((sessionKey: PendingReviewConsentSessionKey) => processRetainedNativeStatusSelections.get(sessionKey) ?? processRetainedNativeStatusSelections.set(sessionKey, new Map()).get(sessionKey)!)(pendingReviewConsentSessionKey(ctx, pendingReviewConsentFallbackKey)),
 				true,
 				ctx.modelRegistry,
+				// The live session id rides into the reviewer side-call so an
+				// OpenCode-routed completion carries its attribution headers
+				// (pi adds those inside the main agent loop; this is not that loop).
+				reviewSessionManagerAndId(ctx)?.sessionId,
 			);
 			return {
 				content: [{ type: "text", text: JSON.stringify(details) }],
@@ -9696,9 +9730,16 @@ function createGentleAiExtensionForTesting(
 	// background subagents may be launched at all, so nothing in Pi may write
 	// it. The only writer is this handler, reached only by explicit invocation.
 	pi.registerCommand("gentle:background-subagents", {
-		description: "Show or set the managed background-subagents policy (status|enable|disable). Every sub-action is user-initiated only; Pi automation never toggles it.",
+		description: "Show or set the managed background-subagents policy; no argument opens a selectable menu (status|enable|disable). Every sub-action is user-initiated only; Pi automation never toggles it.",
+		// No argument opens a selectable menu when an interactive UI is present;
+		// headless callers and fakes without ui.select keep the status fallback.
 		handler: async (args, ctx) => {
-			const subAction = args.trim().length === 0 ? "status" : args.trim();
+			let subAction = args.trim().length === 0 ? "status" : args.trim();
+			if (args.trim().length === 0 && ctx.hasUI && typeof ctx.ui.select === "function") {
+				const selected = await ctx.ui.select("Background subagents policy", ["status", "enable", "disable"]);
+				if (selected === undefined) return;
+				subAction = selected;
+			}
 			if (subAction !== "status" && subAction !== "enable" && subAction !== "disable") {
 				ctx.ui.notify(`Unknown /gentle:background-subagents sub-action "${subAction}". Use status, enable, or disable.`, "warning");
 				return;