pi-plans 0.6.0 → 0.7.0

package/tests/workflow-state.test.ts

@@ -7,14 +7,11 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { after, before, describe, it } from "node:test";
 import {
-	applyCompleted,
 	applyExecutionApproved,
 	applyExecutionCompleted,
 	applyExecutionProgress,
 	applyExecutionHeadChanged,
 	applyExecutionStopped,
-	applyImplementationReviewConfigured,
-	applyImplementationRoundFinished,
 	applyLaneResult,
 	applyMigration,
 	applyPlanWritten,
@@ -331,33 +328,21 @@ describe("state machine reducers", () => {
 		assert.throws(() => applyLaneResult(staged, "r2", "l1", { ok: true }), StateError);
 	});
 
-	it("implementation review: condition first, rounds counted, completed needs evidence (F-004)", () => {
-		const { workdir, runId } = setupRun("sm-impl");
+	it("implementation-review write side is gone; legacy checkpoints stay readable (D-018)", () => {
+		const { workdir, runId } = setupRun("sm-impl-legacy");
 		createCheckpoint(workdir, { runId, originWorkdir: workdir, workdir });
 		let cp = baseCheckpoint(workdir, runId);
-		const planPath = path.join(path.dirname(checkpointFilePath(workdir, runId)!), "PLAN_v1.md");
-		fs.writeFileSync(planPath, "# plan", "utf8");
-		const plan = planIdentityOf(planPath, 1);
-		cp = { ...cp, plan, phase: "implementation-review", nextAction: "ask-question" };
-		assert.throws(
-			() => applyReviewRoundStarted(cp, { roundId: "i1", role: "reviewer", target: "implementation", reviewers: 1, lanes: [{ laneId: "l1" }] }),
-			StateError,
-		);
-		cp = applyImplementationReviewConfigured(cp, "until-no-high");
-		assert.throws(() => applyImplementationReviewConfigured(cp, "again"), StateError);
-		cp = applyReviewRoundStarted(cp, { roundId: "i1", role: "reviewer", target: "implementation", reviewers: 1, lanes: [{ laneId: "l1" }] });
-		const file = writeReviewOutput(workdir, runId, "i1", "l1", "out");
-		cp = applyLaneResult(cp, "i1", "l1", { ok: true, resultFile: file });
-		assert.throws(() => applyImplementationRoundFinished(cp), StateError);
-		cp = applyReviewConsolidated(cp, "i1");
-		cp = applyImplementationRoundFinished(cp);
+		// Simulate a persisted 0.6.0 checkpoint in the legacy phase with its
+		// review bookkeeping — the schema still parses it read-only.
+		cp = {
+			...cp,
+			phase: "implementation-review",
+			nextAction: "run-review",
+			implementationReview: { terminationCondition: "until-no-high", reviewerCount: 2, completedRounds: 1 },
+		};
+		const round = applyReviewRoundStarted(cp, { roundId: "i1", role: "reviewer", target: "implementation", reviewers: 2, lanes: [{ laneId: "l1" }] });
+		assert.equal(round.reviewRounds.length, 1);
 		assert.equal(cp.implementationReview?.completedRounds, 1);
-		// Completion requires evidence AND a termination condition.
-		assert.throws(() => applyCompleted({ ...cp, implementationReview: undefined }, "evidence"), StateError);
-		assert.throws(() => applyCompleted(cp, "   "), StateError);
-		const done = applyCompleted(cp, "no findings in final round");
-		assert.equal(done.phase, "completed");
-		assert.equal(done.nextAction, "none");
 	});
 
 	it("execution approval and progress (D-003/D-011)", () => {
@@ -394,10 +379,12 @@ describe("state machine reducers", () => {
 		assert.equal(cp.execution?.pausedReason, "stopped by user");
 		const resumed = applyExecutionProgress(cp, { pausedReason: null });
 		assert.equal(resumed.execution?.pausedReason, undefined);
-		// Completion hands over to the implementation-review phase (R-005).
+		// Completion: v0.6.1 passes a completed audit straight to the terminal
+		// phase (the implementation-review loop is gone, D-018).
 		const finished = applyExecutionCompleted(cp);
-		assert.equal(finished.phase, "implementation-review");
-		assert.equal(finished.nextAction, "ask-question");
+		assert.equal(finished.phase, "completed");
+		assert.equal(finished.nextAction, "none");
+		assert.equal(finished.execution?.audit?.passed, true);
 	});
 
 	it("migration resets rounds and approval, keeps termination (F-003)", () => {
@@ -431,72 +418,3 @@ describe("state machine reducers", () => {
 	});
 });
 
-describe("implementationReview.reviewerCount (0.5.4)", () => {
-	it("configured persists reviewerCount and survives checkpoint roundtrip", () => {
-		const { workdir, runId } = setupRun("rc-persist");
-		createCheckpoint(workdir, { runId, originWorkdir: workdir, workdir });
-		let cp = baseCheckpoint(workdir, runId);
-		cp = { ...cp, phase: "implementation-review", nextAction: "ask-question" };
-		cp = applyImplementationReviewConfigured(cp, "until-no-high", 2);
-		assert.equal(cp.implementationReview?.reviewerCount, 2);
-		assert.equal(cp.nextAction, "run-review");
-		mutateCheckpoint(workdir, runId, () => cp);
-		const reloaded = loadCheckpoint(workdir, runId);
-		assert.ok(reloaded.status === "ok");
-		assert.equal(reloaded.checkpoint.implementationReview?.reviewerCount, 2);
-	});
-
-	it("omitted reviewerCount stays undefined (legacy checkpoints unchanged)", () => {
-		const { workdir, runId } = setupRun("rc-legacy");
-		createCheckpoint(workdir, { runId, originWorkdir: workdir, workdir });
-		let cp = baseCheckpoint(workdir, runId);
-		cp = { ...cp, phase: "implementation-review", nextAction: "ask-question" };
-		cp = applyImplementationReviewConfigured(cp, "1 round");
-		assert.equal(cp.implementationReview?.reviewerCount, undefined);
-		mutateCheckpoint(workdir, runId, () => cp);
-		assert.ok(loadCheckpoint(workdir, runId).status === "ok");
-	});
-
-	it("rejects out-of-range and non-integer reviewerCount on load", () => {
-		const { workdir, runId } = setupRun("rc-invalid");
-		createCheckpoint(workdir, { runId, originWorkdir: workdir, workdir });
-		const file = checkpointFilePath(workdir, runId)!;
-		const base = JSON.parse(fs.readFileSync(file, "utf8")) as { implementationReview?: unknown };
-		for (const bad of [0, 4, "3", 1.5]) {
-			const doc = {
-				...base,
-				implementationReview: {
-					terminationCondition: "1 round",
-					reviewerCount: bad,
-					completedRounds: 0,
-				},
-			};
-			fs.writeFileSync(file, JSON.stringify(doc), "utf8");
-			const loaded = loadCheckpoint(workdir, runId);
-			assert.ok(loaded.status === "corrupt", `reviewerCount ${JSON.stringify(bad)} rejected`);
-		}
-		// Corrupt bytes refuse overwrite (mutateCheckpoint guard), which is the
-		// intended fail-loud behavior — no restore attempted here.
-	});
-
-	it("applyMigration preserves an explicit reviewerCount (CQ1/D-4)", () => {
-		const { workdir, runId } = setupRun("rc-migrate");
-		createCheckpoint(workdir, { runId, originWorkdir: workdir, workdir });
-		let cp = baseCheckpoint(workdir, runId);
-		cp = { ...cp, phase: "implementation-review", nextAction: "run-review" };
-		cp = applyImplementationReviewConfigured(cp, "until-no-high", 3);
-		cp = applyReviewRoundStarted(cp, { roundId: "i1", role: "reviewer", target: "implementation", reviewers: 3, lanes: [{ laneId: "l1" }] });
-		const migrated = applyMigration(cp, { workdir: "/target/wt", worktreeRoot: "/target/wt", commonDir: "/target/.git" });
-		assert.equal(migrated.implementationReview?.reviewerCount, 3);
-		assert.equal(migrated.implementationReview?.completedRounds, 0);
-	});
-
-	it("second configuration write is rejected even with identical values (replay guard)", () => {
-		const { workdir, runId } = setupRun("rc-replay");
-		createCheckpoint(workdir, { runId, originWorkdir: workdir, workdir });
-		let cp = baseCheckpoint(workdir, runId);
-		cp = { ...cp, phase: "implementation-review", nextAction: "ask-question" };
-		cp = applyImplementationReviewConfigured(cp, "until-no-high", 3);
-		assert.throws(() => applyImplementationReviewConfigured(cp, "until-no-high", 3), StateError);
-	});
-});

package/tools/analyze-refs.ts

@@ -1,9 +1,12 @@
 /**
  * `analyze_refs` tool — plan-with-refs per-reference analysis via read-only Pi
  * subagents with isolated context. One lane per reference (cwd = the ref's own
- * directory), reusing the reviewer role gates from `.git/pi_plans/config.json`
- * and the concurrent refinement overlay (title "Refs"). Batches are capped at
- * three concurrent lanes; larger ref sets run as sequential batches.
+ * directory), reusing the reviewer model confirmation from the GLOBAL config
+ * (`~/.pi/pi-plans/config.json`) and the concurrent overlay (title "Refs").
+ * analyze_refs is spawn-only by nature, so the reviewer MODE is deliberately
+ * not consulted here (Q-4=B): a current-session reviewer still gets spawned
+ * ref-analyst lanes, with a one-time notice in the result. Batches are capped
+ * at three concurrent lanes; larger ref sets run as sequential batches.
  *
  * Recording is best-effort: spawns land in `subagents.jsonl` (role
  * `ref-analyst`) only when an active planning run exists. Analysis output is
@@ -17,7 +20,18 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { loadConfig, normalizeWorkdir, readActive, recordSubagent, resolveStateRootOrNull, StateError } from "../src/state.ts";
+import {
+	loadConfig,
+	normalizeWorkdir,
+	readActive,
+	recordSubagent,
+	resolveEffectiveReviewer,
+	resolveGlobalConfigPath,
+	resolveStateRootOrNull,
+	StateError,
+} from "../src/state.ts";
+import { runFirstUseFlow, firstUseCancelledError, firstUseTextGuidance, availableModels, findModel, type RolePanelHost } from "../src/role-panels.ts";
+import { roleModelLabel } from "../src/thinking-levels.ts";
 import type { SubagentUsage } from "../src/subagent.ts";
 import { resolveActiveRun } from "../src/run-context.ts";
 import { buildRefAnalystTask, type RefAnalystTaskInput } from "../src/refine-prompts.ts";
@@ -45,25 +59,39 @@ const AnalyzeRefsParams = Type.Object({
 	workdir: Type.Optional(Type.String({ description: "Target workspace; default current working directory" })),
 });
 
-function gateError(problem: "state" | "mode" | "current-session" | "confirm"): StateError {
+function gateError(problem: "state" | "confirm", guidance?: string): StateError {
 	if (problem === "state") {
 		return new StateError("no pi-plans state found; run the plans tool (action: init) first");
 	}
-	if (problem === "mode") {
-		return new StateError(
-			"The reviewer role mode is missing or invalid in .git/pi_plans/config.json (analyze_refs reuses the reviewer gates). Ask the role-setting question with ask_choice first: 1. Delegated subagent (recommended; read-only pi subprocess with isolated context) 2. Current session 3. Other 4. Auto-complete — then persist with the plans tool (set-role, role=reviewer).",
-		);
-	}
-	if (problem === "current-session") {
-		return new StateError(
-			"The reviewer role mode is current-session, but analyze_refs only spawns delegated read-only subagents (one per reference). Ask the user to switch the reviewer mode to delegated-subagent via ask_choice, persist with the plans tool (set-role, role=reviewer, mode=delegated-subagent), then retry analyze_refs.",
-		);
-	}
 	return new StateError(
-		"The reviewer model was never confirmed (confirmed_at is null); analyze_refs reuses the reviewer confirmation. Ask the model-confirmation question with ask_choice: 1. Inherit the main agent's model (recommended) 2. Choose a model (list options from the /model picker; persist the exact provider/model selector) 3. Other 4. Auto-complete — then persist with the plans tool (set-role, role=reviewer, confirmed: true, modelSelector: the selector or 'inherit').",
+		guidance ??
+			firstUseTextGuidance([], resolveGlobalConfigPath()),
 	);
 }
 
+/** First-use model confirmation for the spawn-only ref-analyst path: native
+ * panels in TUI, menus for hasUI non-TUI, embedded text guidance otherwise.
+ * The reviewer MODE is not consulted (Q-4=B), but because analysis always
+ * spawns, a confirmed CONCRETE model is required even when the stored mode
+ * is current-session (model confirmation “as usual”). */
+async function ensureRefAnalystModelReady(
+	host: RolePanelHost,
+	role: { mode: string; model_selector: string | null; thinking_level: string | null; confirmed_at: string | null },
+): Promise<{ mode: string; model_selector: string | null; thinking_level: string | null; confirmed_at: string | null; name_prefix: string }> {
+	if (role.confirmed_at !== null && role.model_selector !== null) return role as never;
+	let outcome = await runFirstUseFlow(host, role.thinking_level);
+	if (outcome.status === "confirmed" && outcome.model_selector !== null && availableModels(host).length > 0 && findModel(host, outcome.model_selector) === null) {
+		// F-008: a manually entered selector that the registry does not know —
+		// one re-pick, then let spawn-side errors surface precisely.
+		outcome = await runFirstUseFlow(host, outcome.role.thinking_level);
+	}
+	if (outcome.status === "cancelled") throw firstUseCancelledError("analyze_refs");
+	const guidance = firstUseTextGuidance(availableModels(host), resolveGlobalConfigPath());
+	if (outcome.status === "unavailable") throw gateError("confirm", guidance);
+	if (outcome.role.model_selector === null) throw gateError("confirm", guidance);
+	return outcome.role;
+}
+
 interface AnalysisJob {
 	input: RefAnalystTaskInput;
 	name: string;
@@ -72,14 +100,14 @@ interface AnalysisJob {
 	missing: string | null;
 }
 
-export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void {
+export function registerAnalyzeRefsTool(ext: ExtensionAPI, baseDir: string): void {
 	const agentPrompt = stripFrontmatter(fs.readFileSync(path.join(baseDir, "agents", "ref-analyst.md"), "utf8"));
 
-	pi.registerTool({
+	ext.registerTool({
 		name: "analyze_refs",
 		label: "Analyze Refs",
 		description:
-			"plan-with-refs: analyze downloaded references via independent read-only Pi subagents — one lane per reference (cwd = the ref directory), reusing the reviewer role gates and the concurrent overlay. Batches of at most 3 lanes run sequentially; results are structured per-reference sections for REF_ANALYSIS.md. Recording into subagents.jsonl is best-effort (active run only); refs.jsonl stays owned by the main agent via the plans record-ref action. Refuses until the reviewer mode/model gates pass in .git/pi_plans/config.json.",
+			"plan-with-refs: analyze downloaded references via independent read-only Pi subagents — one lane per reference (cwd = the ref directory), reusing the reviewer model confirmation from the global config and the concurrent overlay. Batches of at most 3 lanes run sequentially; results are structured per-reference sections for REF_ANALYSIS.md. Recording into subagents.jsonl is best-effort (active run only); refs.jsonl stays owned by the main agent via the plans record-ref action. The reviewer mode is not consulted (spawn-only); first use pops native model/effort panels in TUI.",
 		promptSnippet: "Analyze plan-with-refs references with per-ref read-only subagents",
 		parameters: AnalyzeRefsParams,
 
@@ -92,17 +120,22 @@ export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void
 				throw gateError("state");
 			}
 			const config = loadConfig(root);
-			const reviewer = config.reviewer;
-			if (!reviewer || (reviewer.mode !== "delegated-subagent" && reviewer.mode !== "current-session")) {
-				throw gateError("mode");
-			}
-			if (reviewer.mode === "current-session") {
-				throw gateError("current-session");
-			}
-			if (reviewer.confirmed_at === null) {
-				throw gateError("confirm");
+
+			// F-005: cheap validations BEFORE any first-use panel.
+			if (params.refs.length === 0) {
+				throw new StateError("analyze_refs requires at least one reference");
 			}
 
+			// Effective reviewer from the global config (mode NOT consulted —
+			// analyze_refs is spawn-only, Q-4=B; a notice surfaces when the stored
+			// mode is current-session so the switch is never silent).
+			const { reviewer: initialReviewer } = resolveEffectiveReviewer(root);
+			const modeIgnoredNotice =
+				initialReviewer.mode === "current-session"
+					? `note: the reviewer mode is ${initialReviewer.mode}, but analyze_refs always spawns read-only subagents; the mode is ignored here and unchanged.`
+					: null;
+			const reviewer = await ensureRefAnalystModelReady(ctx as unknown as RolePanelHost, initialReviewer);
+
 			// Resolve refs and validate directories up front; missing ones become
 			// FAILED sections instead of aborting the whole batch.
 			const active = resolveActiveRun(ctx.sessionManager, workdir);
@@ -122,7 +155,7 @@ export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void
 			}
 
 			const model = reviewer.model_selector ?? (ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined);
-			const modelLabel = model ?? "inherit";
+			const modelLabel = roleModelLabel(model ?? "inherit", reviewer.thinking_level);
 			let languageTag: string | null = null;
 			if (active) {
 				try {
@@ -140,6 +173,7 @@ export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void
 						role: "ref-analyst",
 						name,
 						model: okModel ?? model ?? null,
+						thinking_level: reviewer.thinking_level,
 						// I-010: meter subagent token/cost for benchmark accounting.
 						usage: usage
 							? { input: usage.input, output: usage.output, cache_read: usage.cacheRead, cache_write: usage.cacheWrite, cost: usage.cost }
@@ -160,6 +194,7 @@ export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void
 						task: buildRefAnalystTask({ ...job.input, languageTag }),
 						cwd: job.dir,
 						model,
+						thinkingLevel: reviewer.thinking_level ?? undefined,
 						tools: READ_ONLY_TOOLS,
 						signal: relay.signal,
 						onProgress: (event) => overlay?.update(job.laneId, event),
@@ -224,7 +259,7 @@ export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void
 
 			if (failures === jobs.length) {
 				throw new Error(
-					`all reference analysis subagents failed (${failures}/${jobs.length})${model ? `\nIf the model selector "${model}" is unavailable, reset the reviewer confirmation (plans set-role, role=reviewer, resetConfirmation: true) and re-ask the model-confirmation question.` : ""}`,
+					`all reference analysis subagents failed (${failures}/${jobs.length})${model ? `\nIf the model selector "${model}" is unavailable, reset the reviewer confirmation (plans set-role, role=reviewer, resetConfirmation: true) — the next analyze_refs opens the native model panel to re-confirm.` : ""}`,
 				);
 			}
 
@@ -237,13 +272,13 @@ export function registerAnalyzeRefsTool(pi: ExtensionAPI, baseDir: string): void
 				content: [
 					{
 						type: "text",
-						text: `${text}\n\n---\nPersist: paste each reference's analysis into REF_ANALYSIS.md, call the plans tool (record-ref) per reference with coverage and gaps filled from the analysis, then ask at least three ref-specific adoption questions per reference with ask_choice before using its ideas in PLAN_v1.md.`,
+						text: `${modeIgnoredNotice ? `${modeIgnoredNotice}\n\n` : ""}${text}\n\n---\nPersist: paste each reference's analysis into REF_ANALYSIS.md, call the plans tool (record-ref) per reference with coverage and gaps filled from the analysis, then ask at least three ref-specific adoption questions per reference with ask_choice before using its ideas in PLAN_v1.md.`,
 					},
 				],
 				details: {
 					mode: "delegated-subagent",
 					role: "ref-analyst",
-					reviewerGates: { mode: reviewer.mode, model },
+					reviewerGates: { mode: initialReviewer.mode, modeIgnored: modeIgnoredNotice !== null, model, thinkingLevel: reviewer.thinking_level },
 					batches: Math.ceil(jobs.length / BATCH_SIZE),
 					model,
 					outputs,

package/tools/ask-choice.ts

@@ -16,13 +16,6 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { disableAutoComplete, enableAutoComplete, isAutoCompleteEnabled, recordAskChoice } from "../src/autocomplete.ts";
 import { assertAutoApprovable, isAutoApproveEnabled } from "../src/auto-approve.ts";
-import {
-	TERMINATION_QUESTION,
-	TERMINATION_OPTIONS,
-	TERMINATION_RECORDING_INSTRUCTIONS,
-	implReviewerCountPromptLine,
-	renderTerminationOptions,
-} from "../src/termination-prompt.ts";
 import { truncateToWidth, visibleWidth } from "../src/refine-ui-helpers.ts";
 import { stripRecommendedMarker } from "../src/ask-form.ts";
 import {
@@ -63,8 +56,8 @@ export const FALLBACK_ROWS = 30;
 /** Minimal-form floor for tiny terminals (stage-3 width). */
 const MINIMAL_LINE_WIDTH = 20;
 /**
- * Truncation floor for fixed tail labels (Other…/Auto-complete/Auto-refine
- * loop): the longest magic prefix ("Auto-refine loop", 16 cols) plus slack.
+ * Truncation floor for fixed tail labels (Other…/Auto-complete): the
+ * longest magic prefix ("Auto-complete", 14 cols) plus slack.
  * These labels drive startsWith() answer routing and must never lose it.
  */
 const FIXED_LABEL_FLOOR = 18;
@@ -74,7 +67,7 @@ export interface PanelItem {
 	core: string;
 	/** Full display label: core + description (degradation stage 0). */
 	display: string;
-	/** Fixed tail labels (Other…/Auto-complete/Auto-refine loop): truncation keeps at least the magic prefix. */
+	/** Fixed tail labels (Other…/Auto-complete): truncation keeps at least the magic prefix. */
 	fixed?: boolean;
 }
 
@@ -213,12 +206,6 @@ export const AskChoiceParams = Type.Object(
 	purpose: Type.Optional(
 		Type.String({ description: "Short machine-readable purpose (e.g. 'scope', 'termination-condition')." }),
 	),
-	trailing: Type.Optional(
-		StringEnum(["auto-refine-loop"] as const, {
-			description:
-				'Replace the trailing Auto-complete option with "Auto-refine loop" (post-execution amelioration prompt). Selecting it returns instructions to ask the rounds/termination follow-up; Auto-complete is suppressed entirely for this question.',
-		}),
-	),
 	workdir: Type.Optional(Type.String({ description: "Target workspace; default current working directory" })),
 	},
 	{ additionalProperties: false },
@@ -589,12 +576,12 @@ function formatBatchAnswers(batch: NonNullable<AskChoiceDetails["batch"]>): stri
 }
 const NL = "\n";
 
-export function registerAskChoiceTool(pi: ExtensionAPI): void {
-	pi.registerTool({
+export function registerAskChoiceTool(ext: ExtensionAPI): void {
+	ext.registerTool({
 		name: "ask_choice",
 		label: "Ask Choice",
 		description:
-			"Ask the user planning or refinement questions as numbered choice prompts: recommended option first, alternatives next, then Other and Auto-complete. Two shapes: questions: [...] (2-8 questions) opens ONE tabbed multiple-choice form with a submit page — use it to batch a round of questions (≤8), then think about the answers and follow up in later calls (phased questioning stays agent-driven); question + options asks one question at a time (classic flow). Use ask_choice for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff. Scope confirmation and the execution handoff MUST stay single-question calls (autoComplete: false); batches reject autoComplete: false items and the termination/questionIds reserved for handoff. The optional trailing parameter swaps the trailing Auto-complete option to Auto-refine loop for the post-execution amelioration prompt. EVERY option you author — including the accept/execute handoff and the implementation-review setup questions — must set description to '✓ <advantage> / ✗ <drawback>' in the configured language, so the user can see what each option gains and what it costs. Other and Auto-complete are appended by this tool and need no description.",
+			"Ask the user planning or refinement questions as numbered choice prompts: recommended option first, alternatives next, then Other and Auto-complete. Two shapes: questions: [...] (2-8 questions) opens ONE tabbed multiple-choice form with a submit page — use it to batch a round of questions (≤8), then think about the answers and follow up in later calls (phased questioning stays agent-driven); question + options asks one question at a time (classic flow). Use ask_choice for every user-facing planning question, the final scope confirmation, refinement-mode questions, language/role/model settings, and the execution handoff. Scope confirmation and the execution handoff MUST stay single-question calls (autoComplete: false); batches reject autoComplete: false items and the questionIds reserved for handoff. EVERY option you author — including the accept/execute handoff — must set description to '✓ <advantage> / ✗ <drawback>' in the configured language, so the user can see what each option gains and what it costs. Other and Auto-complete are appended by this tool and need no description.",
 		promptSnippet: "Ask structured planning questions with recommended/Other/Auto-complete ordering; batch ≤8 questions per form",
 		promptGuidelines: [
 			"Use ask_choice for every pi-plans question to the user instead of plain-text questions; it enforces option ordering and records decisions.",
@@ -605,13 +592,6 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 		executionMode: "sequential",
 
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			// R-13 (defense-in-depth): a delegated executor child has no user to
-			// answer — refuse instead of blocking a headless run on a UI prompt.
-			if (process.env.PI_PLANS_EXECUTOR === "1") {
-				throw new Error(
-					"ask_choice is unavailable in a delegated executor session: no interactive user. Decide autonomously, proceed, and record the deviation in your final summary.",
-				);
-			}
 			// 0.4.0 batch mode: one tabbed form for a whole round of questions
 			// (2-8). The single-question path below is untouched (C-004).
 			// F-005 (impl review r1): ambiguous shapes fail loudly instead of
@@ -620,9 +600,6 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				if (params.question !== undefined || params.options !== undefined) {
 					throw new Error("ask_choice accepts either question+options or questions, not both");
 				}
-				if (params.trailing !== undefined) {
-					throw new Error("ask_choice batch mode does not support trailing (single-question only)");
-				}
 				return executeAskChoiceBatch({ questions: params.questions, workdir: params.workdir }, ctx);
 			}
 			const workdir = normalizeWorkdir(params.workdir ?? ctx.cwd);
@@ -661,10 +638,7 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 					/* the decisions ledger already holds the answer; F-005 reconcile covers the gap */
 				}
 			};
-			// Param normalization: a trailing option replaces Auto-complete entirely,
-			// so an erroneously passed autoComplete flag is suppressed here.
-			const trailing = params.trailing;
-			const autoComplete = (params.autoComplete ?? true) && trailing === undefined;
+			const autoComplete = params.autoComplete ?? true;
 			const options = params.options;
 			if (options.length === 0) throw new Error("ask_choice requires at least one option");
 			const recommended = options.find((option) => option.recommended) ?? options[0];
@@ -764,8 +738,6 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				};
 			}
 
-			const AUTO_REFINE_LOOP_LABEL =
-				"Auto-refine loop  (run refinement rounds until no high-severity finding or the 5-round cap)";
 			const panelItems: PanelItem[] = options.map((option, index) => {
 				const label = stripRecommendedMarker(option.label);
 				const isRec = option === recommended;
@@ -777,7 +749,6 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 			});
 			if (allowOther) panelItems.push({ core: "Other…  (type your own answer)", display: "Other…  (type your own answer)", fixed: true });
 			if (autoComplete) panelItems.push({ core: "Auto-complete  (take the recommended option)", display: "Auto-complete  (take the recommended option)", fixed: true });
-			else if (trailing) panelItems.push({ core: AUTO_REFINE_LOOP_LABEL, display: AUTO_REFINE_LOOP_LABEL, fixed: true });
 
 			const panel = fitAskChoicePanel(
 				params.question,
@@ -820,23 +791,6 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				};
 			}
 
-			if (trailing && selected.startsWith("Auto-refine loop")) {
-				recordAskChoice(ctx, false);
-				record("Auto-refine loop", "user");
-				// Skill-aware reviewer-count default (D-1/D-4): same mapping the
-				// goal-running continuation in src/exec.ts renders.
-				const activeSkill = resolveActiveRun(ctx.sessionManager, workdir)?.skill;
-			return {
-					content: [
-						{
-							type: "text",
-							text: `User selected Auto-refine loop. Immediately ask the follow-up with ask_choice (autoComplete: false, in the session language): "${TERMINATION_QUESTION}" Options (recommended first): ${renderTerminationOptions()}. ${TERMINATION_RECORDING_INSTRUCTIONS} ${implReviewerCountPromptLine(activeSkill)} Then run the loop per the completion instructions: each round calls refine (role: "reviewer", target: "implementation", reviewers: <configured reviewerCount>), accepts findings on evidence, applies fixes, re-runs relevant tests, and continues until the chosen termination condition — the goal-wait option keeps the loop running until no unpassed VCs remain.`,
-						},
-					],
-					details: details("Auto-refine loop", "user"),
-				};
-			}
-
 			if (allowOther && selected.startsWith("Other…")) {
 				const typed = await ctx.ui.input(`${params.question} — your answer:`);
 				if (typed === undefined || !typed.trim()) {

package/tools/code-graph.ts

@@ -128,8 +128,8 @@ export async function ensureRuntime(workdir: string, ctx: CodeGraphContext): Pro
 	return { entry: runtimeCache, status };
 }
 
-export function registerCodeGraphTool(pi: ExtensionAPI): void {
-	pi.registerTool({
+export function registerCodeGraphTool(ext: ExtensionAPI): void {
+	ext.registerTool({
 		name: "code_graph",
 		label: "Code Graph",
 		description: