pi-plans 0.5.7 → 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;
 }
 
@@ -156,7 +149,12 @@ export function fitAskChoicePanel(question: string, items: PanelItem[], columns:
 export const Option = Type.Object(
 	{
 		label: Type.String({ description: "Option label" }),
-		description: Type.Optional(Type.String({ description: "Short tradeoff that matters, shown to the user" })),
+		description: Type.Optional(
+			Type.String({
+				description:
+					"REQUIRED on every option you author: '✓ <advantage> / ✗ <drawback>' — the user compares options side by side, so each one must state what it gains AND what it costs. Write BOTH halves in this single description string, in the configured language, tersely (≈8 words per half). If a side is genuinely absent write '—' rather than dropping it. Do NOT invent separate pros/cons fields: Option accepts no other keys.",
+			}),
+		),
 		recommended: Type.Optional(Type.Boolean({ description: "Mark exactly one recommended option; put it first. Never embed (推荐)/(recommended) text in labels — the UI renders the ★ marker automatically" })),
 	},
 	{ additionalProperties: false },
@@ -165,7 +163,10 @@ export const Option = Type.Object(
 export const BatchQuestionParams = Type.Object(
 	{
 		question: Type.String({ description: "The question to ask, in the configured language" }),
-		options: Type.Array(Option, { description: "Ordered options: recommended first, alternatives next. Do not include Other or Auto-complete yourself." }),
+		options: Type.Array(Option, {
+			description:
+				"Ordered options: recommended first, alternatives next. Every option's description states its advantage AND its drawback as '✓ <advantage> / ✗ <drawback>' in the configured language. Do not include Other or Auto-complete yourself.",
+		}),
 		allowOther: Type.Optional(Type.Boolean({ description: "Offer free-form input for this question (default true)" })),
 		autoComplete: Type.Optional(
 			Type.Boolean({
@@ -182,7 +183,7 @@ export const BatchQuestionParams = Type.Object(
 export const AskChoiceParams = Type.Object(
 	{
 		question: Type.Optional(Type.String({ description: "The single question to ask, in the configured language (mutually exclusive with questions)." })),
-	options: Type.Optional(Type.Array(Option, { description: "Ordered options (single-question form): recommended first, alternatives next. Do not include Other or Auto-complete yourself." })),
+	options: Type.Optional(Type.Array(Option, { description: "Ordered options (single-question form): recommended first, alternatives next. Every option's description states its advantage AND its drawback as '✓ <advantage> / ✗ <drawback>' in the configured language. Do not include Other or Auto-complete yourself." })),
 	questions: Type.Optional(
 		Type.Array(BatchQuestionParams, {
 			description:
@@ -205,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 },
@@ -581,16 +576,17 @@ 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.",
+			"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.",
 			"Batch a round's questions into one ask_choice call (questions: [...], 2-8 items) instead of asking one at a time, then think after the answers and follow up with later calls. Scope confirmation and execution handoff are always separate single-question calls (autoComplete: false).",
+			"Give every option you author a description of the form '✓ <advantage> / ✗ <drawback>' — the user's whole point is seeing what each option wins and what it costs, in the configured language. Keep each half terse (~8 words). Put both halves in the description string; there are no separate pros/cons fields, and Other/Auto-complete are added by the tool.",
 		],
 		parameters: AskChoiceParams,
 		executionMode: "sequential",
@@ -604,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);
@@ -645,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];
@@ -748,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;
@@ -761,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,
@@ -804,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: