pi-plans 0.6.0 → 0.8.0

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:

package/tools/execute-plan.ts

@@ -1,6 +1,9 @@
 /**
- * `execute_plan` tool — the execution handoff. On explicit user approval (no
- * Auto-complete) the extension enters execution mode with checklist tracking.
+ * `execute_plan` tool — the execution handoff (v0.6.1). On explicit user
+ * approval (no Auto-complete) the extension enters task-tree execution mode:
+ * progress flows through `plans_update_task`, the dashboard tracks every
+ * task, and the execution reviewer gates the final pass. Legacy I-### plans
+ * parse through the fallback with an upgrade notice.
  */
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
@@ -12,15 +15,13 @@ import {
 	getExecution,
 	resumeActiveExecution,
 	startExecution,
-	type ExecutionRuntime,
 } from "../src/exec.ts";
 import { disableAutoComplete } from "../src/autocomplete.ts";
 import { isAutoApproveEnabled } from "../src/auto-approve.ts";
-import { latestPlanVersion, parseChecklist, parseImplItems } from "../src/plan.ts";
-import { normalizeWorkdir, recordDecision, type RunSummary } from "../src/state.ts";
-import { bindRun, resolveActiveRun } from "../src/run-context.ts";
+import { checklistHeaderName, latestPlanVersion, lintPlanTasks, parseChecklist, parsePlanTasks } from "../src/plan.ts";
+import { normalizeWorkdir, type RunSummary } from "../src/state.ts";
+import { bindRun } from "../src/run-context.ts";
 import { executionCandidates, resolveCommandRun } from "../src/run-picker.ts";
-import { collectModelSelectors, modelSelectorOf } from "../src/config-command.ts";
 import { resolveUiLanguage } from "../src/ui-language.ts";
 
 
@@ -43,7 +44,7 @@ export async function executeHandoff(
 	ctx: ExtensionContext,
 	planPathArg?: string,
 	workdirArg?: string,
-	signal?: AbortSignal,
+	_signal?: AbortSignal,
 ): Promise<HandoffOutcome> {
 	const workdir = normalizeWorkdir(workdirArg ?? ctx.cwd);
 
@@ -79,10 +80,28 @@ export async function executeHandoff(
 	if (items.length === 0) {
 		return {
 			status: "error",
-			message: `${planPath} has no parsable \`## Verifier Checklist\` with \`- [ ] \`VC-###\` ...\` items. Fix the plan before execution.`,
+			message: `${planPath} has no parsable \`## Verification Checks\` (or legacy \`## Verifier Checklist\`) with \`- [ ] \`VC-###\` ...\` items. Fix the plan before execution.`,
 		};
 	}
-	const implItems = parseImplItems(planText);
+	const planTasks = parsePlanTasks(planText);
+	if (planTasks.tasks.length === 0) {
+		return {
+			status: "error",
+			message: `${planPath} has no parsable tasks: add a \`## Tasks\` section (\`- \`Task-1\`: title — deps: …; files: …; wave: 1\`).`,
+		};
+	}
+	// I-001/R-001: task-tree consistency is advisory while planning and
+	// hard-rejected at this gate. Legacy I-### fallback plans are exempt
+	// (their shape predates the microsyntax).
+	if (!planTasks.legacy) {
+		const lint = lintPlanTasks(planText);
+		if (lint !== null) {
+			return {
+				status: "error",
+				message: `${planPath} failed the task-tree consistency gate; fix these before execution:\n${lint}`,
+			};
+		}
+	}
 
 	disableAutoComplete(ctx, "execution handoff");
 	// I-004/D-019: PI_PLANS_AUTO_APPROVE=1 short-circuits the confirm BEFORE
@@ -96,14 +115,22 @@ export async function executeHandoff(
 		};
 	}
 
+	const legacyPlan = planTasks.legacy || checklistHeaderName(planText) === "Verifier Checklist";
+
 	let approved: boolean;
 	if (autoApprove) {
 		approved = true;
 	} else {
+		const lang = resolveUiLanguage(workdir);
 		const preview = items.map((item) => `- ${item.done ? "☑" : "☐"} ${item.id}`).join("\n");
+		const legacyNote = legacyPlan
+			? (lang === "zh"
+				? "\n\n注意：该计划使用旧版 I-### 格式，将以兼容映射执行；建议在下次修订时升级为 ## Tasks 新格式。"
+				: "\n\nNote: this plan uses the legacy I-### format and executes through the compatibility mapping; upgrade it to the ## Tasks format at the next revision.")
+			: "";
 		approved = await ctx.ui.confirm(
 			"Execute this plan now?",
-			`${planPath}\n${items.length} verifier item(s):\n${preview}\n\nExecution mode enables write access and tracks [DONE:VC-xxx] progress.`,
+			`${planPath}\n${items.length} verification check(s) over ${planTasks.tasks.length} task(s):\n${preview}${legacyNote}\n\nExecution mode enables write access; task progress is reported with the plans_update_task tool and gated by the execution reviewer.`,
 		);
 	}
 	if (!approved) {
@@ -114,81 +141,15 @@ export async function executeHandoff(
 	// the approval checkpoint and status flip land on the run the user chose.
 	if (chosenRun) bindRun(ctx.sessionManager, workdir, chosenRun.run_id);
 
-	// v0.6.0 (R-8): runtime question — current session (recommended) or a
-	// delegated executor on another model. Skipped under auto-approve/no-UI.
-	const runtime = await chooseExecutionRuntime(ctx, workdir, autoApprove, chosenRun);
-
-	await startExecution(getCurrentApi(), ctx, planPath, items, implItems, { runtime, signal });
-	const scopeNote = implItems.length ? ` Tracking ${implItems.length} implementation item(s).` : "";
+	await startExecution(ctx, { planPath, planTasks, items });
 	const autoNote = autoApprove ? "[auto-approve] " : "";
-	const runtimeNote = runtime === "current-session" ? "" : ` Delegated to executor model ${runtime.modelSelector}; progress mirrors in the overlay.`;
+	const legacyNote = legacyPlan ? " Legacy I-### mapping active; upgrade the plan at the next revision." : "";
 	return {
 		status: "executing",
 		planPath,
 		itemCount: items.length,
-		message: `${autoNote}Execution approved. ${items.length} verifier item(s) queued; implement in dependency order and mark verified items with [DONE:VC-xxx].${scopeNote}${runtimeNote}`,
-	};
-}
-
-const MODEL_SELECTOR_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*\/[A-Za-z0-9][A-Za-z0-9._-]*$/;
-
-/**
- * R-8: ask where the execution runs. Uses ctx.ui.select directly (ask_choice
- * is a tool and cannot be invoked from tool/command context). Under
- * auto-approve or no-UI the question is skipped: current session, decision
- * recorded with the [auto-approve] annotation convention.
- */
-async function chooseExecutionRuntime(
-	ctx: ExtensionContext,
-	workdir: string,
-	autoApprove: boolean,
-	chosenRun: RunSummary | null,
-): Promise<ExecutionRuntime> {
-	const record = (answer: string, source: "user" | "auto-complete", question: string, options: string[]): void => {
-		const runId = chosenRun?.run_id ?? resolveActiveRun(ctx.sessionManager, workdir)?.run_id ?? null;
-		if (!runId) return;
-		try {
-			recordDecision(workdir, runId, {
-				question,
-				options,
-				answer,
-				answer_source: source,
-			});
-		} catch {
-			/* decision audit trail is best-effort */
-		}
+		message: `${autoNote}Execution approved. ${planTasks.tasks.length} task(s) queued in wave order; report progress with the plans_update_task tool (status + evidence); the execution reviewer verifies every check before the run completes.${legacyNote}`,
 	};
-	if (autoApprove || !ctx.hasUI) {
-		record("current session [auto-approve]", "auto-complete", "Execution runtime", ["current session", "switch model"]);
-		return "current-session";
-	}
-	const lang = resolveUiLanguage(workdir);
-	const currentLabel = lang === "zh" ? "使用当前会话（推荐）" : "Use the current session (recommended)";
-	const switchLabel = lang === "zh" ? "切换至其他模型…" : "Switch to another model…";
-	const title = lang === "zh" ? "执行运行时" : "Execution runtime";
-	const first = await ctx.ui.select(title, [currentLabel, switchLabel]);
-	if (first === undefined || first === currentLabel) {
-		record("current session", "user", "Execution runtime", [currentLabel, switchLabel]);
-		return "current-session";
-	}
-	// Model picker: switch targets exclude the current selector by design
-	// (option 1 IS the current session).
-	const currentSelector = modelSelectorOf(ctx.model);
-	const targets = collectModelSelectors(ctx, currentSelector);
-	const otherLabel = lang === "zh" ? "其他（输入 provider/model）…" : "Other (type provider/model)…";
-	const modelTitle = lang === "zh" ? "切换至哪个模型执行？" : "Switch to which model?";
-	let modelPick = await ctx.ui.select(modelTitle, [...targets, otherLabel]);
-	if (modelPick === otherLabel) {
-		const typed = await ctx.ui.input(modelTitle, "provider/model");
-		modelPick = typed && MODEL_SELECTOR_RE.test(typed.trim()) ? typed.trim() : undefined;
-	}
-	if (modelPick === undefined || !MODEL_SELECTOR_RE.test(modelPick)) {
-		// Cancelled or invalid: fall back to the current session, recorded.
-		record("current session (model switch cancelled)", "user", "Execution runtime", [currentLabel, switchLabel]);
-		return "current-session";
-	}
-	record(`switch model: ${modelPick}`, "user", "Execution runtime", [currentLabel, switchLabel, ...targets, otherLabel]);
-	return { modelSelector: modelPick };
 }
 
 /** The user command may resume an approved execution; the tool always asks. */
@@ -196,40 +157,35 @@ export async function executeCommand(ctx: ExtensionContext, planPathArg?: string
 	const activeExecution = getExecution();
 	const planPath = planPathArg ? path.resolve(ctx.cwd, planPathArg.replace(/^@/, "")) : activeExecution?.planPath;
 	if (activeExecution && planPath && path.resolve(activeExecution.planPath) === path.resolve(planPath)) {
-		const resumed = resumeActiveExecution(getCurrentApi(), ctx);
+		const resumed = resumeActiveExecution(ctx);
+		// v0.8 phase-aware response: a verifying run continues its review loop
+		// (this tool is also the ONLY budget-granting surface at a cap pause).
+		const statusText = activeExecution.review?.inFlight
+			? "Execution review in progress (status verifying); the reviewer round runs in the overlay."
+			: (getExecution()?.stall.paused ?? false)
+				? "Execution review paused at the round cap — this confirmation granted a fresh five-round budget; the review resumes now."
+				: "Execution resumed; task progress preserved.";
 		return {
 			status: "executing",
 			planPath,
 			itemCount: activeExecution.items.length,
-			message: resumed ? "Execution resumed; verified progress preserved." : "This plan is already executing.",
+			message: resumed ? statusText : "This plan is already executing.",
 		};
 	}
 	return executeHandoff(ctx, planPathArg);
 }
 
-// The tool registers with the ExtensionAPI in scope; keep a module-level
-// reference so the shared handoff helper can reach appendEntry/sendMessage.
-let currentApi: ExtensionAPI | null = null;
-export function setCurrentApi(api: ExtensionAPI): void {
-	currentApi = api;
-}
-function getCurrentApi(): ExtensionAPI {
-	if (!currentApi) throw new Error("execute_plan used before extension initialization");
-	return currentApi;
-}
-
-export function registerExecutePlanTool(pi: ExtensionAPI): void {
-	setCurrentApi(pi);
-	pi.registerTool({
+export function registerExecutePlanTool(ext: ExtensionAPI): void {
+	ext.registerTool({
 		name: "execute_plan",
 		label: "Execute Plan",
 		description:
-			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then asks which runtime executes the plan — the current session (recommended) or a delegated executor subagent on another model (>=3 switch targets listed; the child writes natively and reports [DONE:VC-xxx] markers the parent tracks). Either way the extension tracks Verifier-Checklist progress. When several runs with plans exist, a run-picker form selects the target run first. Only call after the user chose 'Execute this plan now' at the handoff question.",
+			"Execution handoff for an accepted plan. Asks the user for explicit approval (never auto-completed), then enters task-tree execution mode: every task's progress is reported via the plans_update_task tool (status + evidence), the task dashboard tracks the tree (Ctrl+Shift+T expands it), and an independent execution reviewer verifies the verification checks before the run completes. Legacy I-### plans parse through the compatibility mapping with an upgrade notice. When several runs with plans exist, a run-picker form selects the target run first. Only call after the user chose 'Execute this plan now' at the handoff question.",
 		promptSnippet: "Hand an accepted plan off to the tracked execution loop",
 		parameters: ExecutePlanParams,
 
-		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-			const outcome = await executeHandoff(ctx, params.planPath, params.workdir, signal);
+		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+			const outcome = await executeHandoff(ctx, params.planPath, params.workdir);
 			if (outcome.status === "error") throw new Error(outcome.message);
 			return {
 				content: [{ type: "text", text: outcome.message }],

package/tools/graph-aware-file-tools.ts

@@ -277,10 +277,6 @@ function createGraphReadTool(cwd: string) {
 				};
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
-			// Delegated executor children (PI_PLANS_EXECUTOR=1) always use the
-			// native tools: DB-first staging would never be materialized inside
-			// the child (no code_graph in its allowlist), so writes must hit disk.
-			if (process.env.PI_PLANS_EXECUTOR === "1") return native(null);
 			if (mode === "off") return native(null);
 			if (mode === "config-unavailable") return native("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -331,7 +327,6 @@ function createGraphWriteTool(cwd: string) {
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
 			// Delegated executor children bypass DB-first staging (see read tool).
-			if (process.env.PI_PLANS_EXECUTOR === "1") return stage(null);
 			if (mode === "off") return stage(null);
 			if (mode === "config-unavailable") return stage("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -382,7 +377,6 @@ function createGraphEditTool(cwd: string) {
 			};
 			const mode: GraphMode = resolveGraphMode(ctx.cwd);
 			// Delegated executor children bypass DB-first staging (see read tool).
-			if (process.env.PI_PLANS_EXECUTOR === "1") return stage(null);
 			if (mode === "off") return stage(null);
 			if (mode === "config-unavailable") return stage("config read failed");
 			const ensured = await ensureRuntime(ctx.cwd, ctx);
@@ -453,9 +447,9 @@ export function createGraphAwareFileTools(cwd: string) {
 	return tools;
 }
 
-export function registerGraphAwareFileTools(pi: ExtensionAPI, cwd = process.cwd()): void {
+export function registerGraphAwareFileTools(ext: ExtensionAPI, cwd = process.cwd()): void {
 	const tools = createGraphAwareFileTools(cwd);
-	pi.registerTool(tools.read);
-	pi.registerTool(tools.write);
-	pi.registerTool(tools.edit);
+	ext.registerTool(tools.read);
+	ext.registerTool(tools.write);
+	ext.registerTool(tools.edit);
 }