pi-plans 0.1.1 → 0.2.0

package/tests/execute-plan.test.ts

@@ -0,0 +1,65 @@
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { after, before, describe, it } from "node:test";
+
+import { getExecution, startExecution, stopExecution } from "../src/exec.ts";
+
+let tmpRoot: string;
+
+before(() => {
+	tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-execute-test-"));
+});
+
+after(() => {
+	fs.rmSync(tmpRoot, { recursive: true, force: true });
+});
+
+function mkWorkdir(name: string): string {
+	const dir = path.join(tmpRoot, name);
+	fs.mkdirSync(dir, { recursive: true });
+	return dir;
+}
+
+describe("execute handoff", () => {
+	it("starts execution without switching models", async () => {
+		const workdir = mkWorkdir("handoff");
+		const recorded = {
+			messages: [] as string[],
+			entries: [] as Array<{ customType: string; data: unknown }>,
+			setModelCalls: 0,
+		};
+		const pi = {
+			appendEntry: (customType: string, data: unknown) => {
+				recorded.entries.push({ customType, data });
+			},
+			sendMessage: (message: { customType: string; content: string }) => {
+				recorded.messages.push(message.content);
+			},
+			setModel: async () => {
+				recorded.setModelCalls += 1;
+				return true;
+			},
+		};
+		const ctx = {
+			cwd: workdir,
+			ui: {
+				setStatus: () => {},
+				theme: {
+					fg: (_kind: string, text: string) => text,
+					bold: (text: string) => text,
+				},
+			},
+		} as any;
+
+		await startExecution(pi as any, ctx, path.join(workdir, "PLAN_v1.md"), [
+			{ id: "VC-001", text: "first item", done: false },
+		] as any);
+		assert.equal(recorded.setModelCalls, 0);
+		assert.ok(getExecution());
+
+		await stopExecution(pi as any, ctx, "cleanup");
+		assert.equal(getExecution(), null);
+	});
+});

package/tests/plan.test.ts

@@ -5,7 +5,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { after, before, describe, it } from "node:test";
-import { latestPlanVersion, nextPlanVersionPath, parseChecklist, scanDoneMarkers } from "../src/plan.ts";
+import { latestPlanVersion, nextPlanVersionPath, parseChecklist, parseImplItems, resolveImplStatuses, scanCurrentIMarkers, scanDoneMarkers, scanImplMarkers, shortImplDescription, extractCoverage, resolveCurrentI, inferCurrentI } from "../src/plan.ts";
 
 const PLAN = `# PLAN_v1 - demo
 
@@ -103,3 +103,96 @@ describe("nextPlanVersionPath", () => {
 		assert.equal(next.path, path.join(empty, "PLAN_v1.md"));
 	});
 });
+
+describe("implementation items", () => {
+	const IMPL_PLAN = `# PLAN_v1 - demo
+
+## Implementation Items
+
+- \`I-001\`: Add state helpers in src/exec.ts; evaluate percent and coverage. Details follow:
+  - nested sub-bullet ignored
+- \`I-002\`: Wire the turn_end trigger and status bar.
+- not an item line
+- \`I-001\`: duplicate id ignored
+
+## Verifier Checklist
+
+- [ ] \`VC-001\` covers \`I-001\` and \`I-002\`; pass condition: tests green; metric: 0 fail.
+- [ ] \`VC-002\` covers \`I-002\`; pass condition: lint clean; metric: zero findings.
+`;
+
+	it("parses strict top-level single-line items and ignores continuations", () => {
+		const items = parseImplItems(IMPL_PLAN);
+		assert.equal(items.length, 2);
+		assert.equal(items[0]?.id, "I-001");
+		// First line only: the multi-line body and nested sub-bullet are ignored.
+		assert.match(items[0]!.text, /^Add state helpers/);
+		assert.doesNotMatch(items[0]!.text, /nested/);
+		assert.equal(items[1]?.id, "I-002");
+	});
+
+	it("returns empty without an Implementation Items section", () => {
+		assert.equal(parseImplItems("# no items here\n- `I-001`: orphan\n").length, 0);
+	});
+
+	it("shortens descriptions at sentence or semicolon boundaries and caps length", () => {
+		assert.equal(shortImplDescription("Add helpers; evaluate percent. Then more."), "Add helpers");
+		assert.equal(shortImplDescription("First sentence. Second one."), "First sentence.");
+		const long = "x".repeat(120);
+		assert.equal(shortImplDescription(long).length, 80);
+		assert.match(shortImplDescription(long), /…$/);
+	});
+
+	it("extracts coverage refs before the first semicolon only", () => {
+		assert.deepEqual(extractCoverage("`VC-001` covers `I-001` and `I-002`; pass: `I-003` mentioned late"), ["I-001", "I-002"]);
+		assert.deepEqual(extractCoverage("no coverage clause here"), []);
+	});
+
+	it("parses and resolves current-I markers without changing progress marker states", () => {
+		const implItems = [{ id: "I-001", text: "first" }, { id: "I-002", text: "second" }];
+		assert.deepEqual(scanCurrentIMarkers("[I-001:current] [I-999:current] [I-002:current]"), [
+			{ id: "I-001" },
+			{ id: "I-999" },
+			{ id: "I-002" },
+		]);
+		assert.equal(resolveCurrentI(implItems, scanCurrentIMarkers("[I-999:current] [I-002:current]")), "I-002");
+		assert.equal(inferCurrentI(implItems, [], undefined), "I-001");
+	});
+	it("scans impl markers", () => {
+		assert.deepEqual(scanImplMarkers("[I-001:implemented] then [I-002:validating] and [I-003:done]"), [
+			{ id: "I-001", state: "implemented" },
+			{ id: "I-002", state: "validating" },
+		]);
+	});
+
+	it("resolves the status matrix with vc-passed > marker > derivation", () => {
+		const items = parseChecklist(IMPL_PLAN);
+		const implItems = parseImplItems(IMPL_PLAN);
+
+		// No markers, nothing done: frontier I-001 implementing, I-002 pending.
+		assert.deepEqual(resolveImplStatuses(implItems, items, undefined), {
+			"I-001": "implementing",
+			"I-002": "pending",
+		});
+
+		// Explicit marker wins over derivation.
+		assert.deepEqual(resolveImplStatuses(implItems, items, { "I-002": "implemented" }), {
+			"I-001": "implementing",
+			"I-002": "implemented",
+		});
+
+		// Some covering VC done without a marker: deriving validating.
+		items[1]!.done = true;
+		assert.deepEqual(resolveImplStatuses(implItems, items, {}), {
+			"I-001": "implementing",
+			"I-002": "validating",
+		});
+
+		// All covering VCs done → vc-passed beats the marker.
+		items[0]!.done = true;
+		assert.deepEqual(resolveImplStatuses(implItems, items, { "I-002": "validating" }), {
+			"I-001": "vc-passed",
+			"I-002": "vc-passed",
+		});
+	});
+});

package/tests/plans.test.ts

@@ -0,0 +1,37 @@
+/** Tests for the plans tool source wiring. */
+
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as url from "node:url";
+import { describe, it } from "node:test";
+
+const ROOT = path.dirname(path.dirname(url.fileURLToPath(import.meta.url)));
+
+function readPlansSource(): string {
+	return fs.readFileSync(path.join(ROOT, "tools", "plans.ts"), "utf8");
+}
+
+describe("plans tool source", () => {
+	it("declares artifactRootSource in PlansParams", () => {
+		const source = readPlansSource();
+		const start = source.indexOf("const PlansParams = Type.Object({");
+		const end = source.indexOf("});", start);
+		assert.ok(start >= 0, "missing PlansParams block start");
+		assert.ok(end >= 0, "missing PlansParams block end");
+
+		const params = source.slice(start, end);
+		assert.match(params, /artifactRootSource:\s*Type\.Optional/);
+		assert.doesNotMatch(params, /executionModelSelector/);
+		assert.doesNotMatch(params, /executionModelSource/);
+	});
+
+	it("keeps the plans handler wired to artifact root and no separate model-selection action", () => {
+		const source = readPlansSource();
+		assert.match(source, /import \{[\s\S]*setArtifactRoot,[\s\S]*\} from "\.\.\/src\/state\.ts";/);
+		assert.match(source, /case "set-artifact-root"/);
+		assert.doesNotMatch(source, /setExecutionModel/);
+		assert.doesNotMatch(source, /case "set-execution-model"/);
+		assert.match(source, /params\.artifactRootSource/);
+	});
+});

package/tests/query-hook.test.ts

@@ -0,0 +1,82 @@
+import * as assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	consumeOrdinaryQuery,
+	isOrdinaryExternalQuery,
+	QUERY_INTERVIEW_MESSAGE,
+	QUERY_INTERVIEW_MESSAGE_CUSTOM_TYPE,
+	recordOrdinaryQuery,
+	registerQueryInterviewHooks,
+	resetOrdinaryQueryState,
+} from "../src/query-hook.ts";
+
+function context(sessionManager: object): any {
+	return { cwd: process.cwd(), sessionManager };
+}
+
+function registeredHooks(): { pi: any; handlers: Map<string, Function[]> } {
+	const handlers = new Map<string, Function[]>();
+	const pi = {
+		on(name: string, handler: Function) {
+			handlers.set(name, [...(handlers.get(name) ?? []), handler]);
+		},
+	};
+	return { pi, handlers };
+}
+
+const ordinaryInput = { text: "implement the requested change", source: "interactive" as const };
+
+describe("query interview hook", () => {
+	it("accepts only idle external non-slash input", () => {
+		assert.equal(isOrdinaryExternalQuery(ordinaryInput), true);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, source: "rpc" }), true);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, source: "extension" }), false);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, streamingBehavior: "followUp" }), false);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, streamingBehavior: "steer" }), false);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, text: "   " }), false);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, text: "/planning clarify this" }), false);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, text: "/skill:plan-small implement this" }), false);
+		assert.equal(isOrdinaryExternalQuery({ ...ordinaryInput, text: "/unknown-command" }), false);
+	});
+
+	it("queues multiple queries, consumes one at a time, and isolates sessions", () => {
+		const first = context({});
+		const second = context({});
+		assert.equal(recordOrdinaryQuery(first, ordinaryInput), true);
+		assert.equal(recordOrdinaryQuery(first, { ...ordinaryInput, text: "verify the change" }), true);
+		assert.equal(consumeOrdinaryQuery(second), false);
+		assert.equal(consumeOrdinaryQuery(first), true);
+		assert.equal(consumeOrdinaryQuery(first), true);
+		assert.equal(consumeOrdinaryQuery(first), false);
+		resetOrdinaryQueryState(first);
+		assert.equal(consumeOrdinaryQuery(first), false);
+	});
+
+	it("registers one hidden message per ordinary query and consumes suppressed queries", async () => {
+		const { pi, handlers } = registeredHooks();
+		let suppressed = false;
+		registerQueryInterviewHooks(pi, () => suppressed);
+		const session = {};
+		const ctx = context(session);
+		const input = handlers.get("input")![0]!;
+		const beforeAgentStart = handlers.get("before_agent_start")![0]!;
+		const sessionStart = handlers.get("session_start")![0]!;
+
+		await input({ ...ordinaryInput }, ctx);
+		const first = await beforeAgentStart({ type: "before_agent_start", prompt: ordinaryInput.text }, ctx);
+		assert.equal(first?.message.customType, QUERY_INTERVIEW_MESSAGE_CUSTOM_TYPE);
+		assert.equal(first?.message.display, false);
+		assert.equal(first?.message.content, QUERY_INTERVIEW_MESSAGE);
+		assert.equal(await beforeAgentStart({ type: "before_agent_start", prompt: ordinaryInput.text }, ctx), undefined);
+
+		await input({ ...ordinaryInput, text: "a query inside the planning workflow" }, ctx);
+		suppressed = true;
+		assert.equal(await beforeAgentStart({ type: "before_agent_start", prompt: "expanded workflow prompt" }, ctx), undefined);
+		suppressed = false;
+		assert.equal(await beforeAgentStart({ type: "before_agent_start", prompt: "later ordinary prompt" }, ctx), undefined);
+
+		await input({ ...ordinaryInput, text: "stale input" }, ctx);
+		await sessionStart({ type: "session_start" }, ctx);
+		assert.equal(await beforeAgentStart({ type: "before_agent_start", prompt: "new session" }, ctx), undefined);
+	});
+});

package/tests/refine-ui.test.ts

@@ -0,0 +1,127 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { RefineOverlayComponent, chunkDetailForOverlay } from "../src/refine-ui.ts";
+import { applyRefineProgress, applyRefineResult, statusLabel, type RefineLaneState } from "../src/refine-ui-state.ts";
+
+
+function lane(): RefineLaneState {
+	return { id: "lane-1", label: "reviewer-1", status: "queued", phase: "queued", detail: "" };
+}
+
+describe("refine overlay state", () => {
+	it("tracks tool progress and bounds the displayed detail", () => {
+		const state = lane();
+		applyRefineProgress(state, {
+			type: "tool",
+			phase: "update",
+			toolCallId: "call-1",
+			toolName: "read",
+			detail: "x".repeat(500),
+		});
+
+		assert.equal(state.status, "running");
+		assert.equal(state.phase, "tool: read");
+		assert.ok(state.detail.length <= 180);
+		assert.match(state.detail, /\.\.\.$/);
+	});
+
+	it("keeps terminal lane states stable after completion", () => {
+		const state = lane();
+		applyRefineResult(state, { ok: true, output: "final conclusion", stderr: "", turns: 1 });
+		applyRefineProgress(state, { type: "turn", phase: "start" });
+
+		assert.deepEqual(state, {
+			id: "lane-1",
+			label: "reviewer-1",
+			status: "complete",
+			phase: "complete",
+			detail: "final conclusion",
+		});
+	});
+
+	it("distinguishes cancelled and timed out child results", () => {
+		const cancelled = lane();
+		applyRefineResult(cancelled, { ok: false, output: "", stderr: "", turns: 0, cancelled: true, errorMessage: "Esc" });
+		assert.equal(cancelled.status, "cancelled");
+		assert.equal(cancelled.phase, "cancelled");
+
+		const timedOut = lane();
+		applyRefineResult(timedOut, { ok: false, output: "", stderr: "", turns: 0, timedOut: true, errorMessage: "timeout" });
+		assert.equal(timedOut.status, "failed");
+		assert.equal(timedOut.phase, "timed out");
+		assert.equal(statusLabel(timedOut.status), "failed");
+	});
+});
+
+
+describe("refine overlay viewport", () => {
+	const fakeTheme = {
+		fg: (_color: string, text: string) => text,
+		bold: (text: string) => text,
+	} as never;
+
+	function makeLane(): RefineLaneState {
+		return { id: "lane-1", label: "reviewer-1", status: "running", phase: "responding", detail: "" };
+	}
+
+	function makeLanes(detail: string): RefineLaneState[] {
+		return [{ id: "lane-1", label: "reviewer-1", status: "running", phase: "responding", detail }];
+	}
+
+	it("clamps overlay width between min and max regardless of host width", () => {
+		const component = new RefineOverlayComponent(fakeTheme, "reviewer", makeLanes(""), () => {});
+		const narrow = component.render(20);
+		const wide = component.render(240);
+		assert.ok(narrow.some((line) => line.startsWith("┌")));
+		assert.ok(wide.some((line) => line.startsWith("┌")));
+		assert.ok(narrow.every((line) => line.length <= 20));
+	});
+
+	it("draws top and bottom borders with rounded corners and frame lines", () => {
+		const component = new RefineOverlayComponent(fakeTheme, "criticizer", makeLanes(""), () => {});
+		const lines = component.render(80);
+		const first = lines[0] ?? "";
+		const last = lines.at(-1) ?? "";
+		assert.match(first, /^┌─+┐$/);
+		assert.match(last, /^└─+┘$/);
+		assert.ok(lines.some((line) => line.startsWith("├") && line.endsWith("┤")));
+		assert.ok(lines.some((line) => line.startsWith("│") && line.endsWith("│")));
+	});
+
+	it("chunk sentence-sized detail lines so streaming fragments stay readable", () => {
+		const lines = chunkDetailForOverlay(
+			"Reading the file. Found three findings. The fourth line is unrelated.",
+			40,
+			6,
+		);
+		assert.ok(lines.length >= 3);
+		assert.ok(lines.every((line) => line.length <= 40));
+		assert.match(lines[0] ?? "", /Reading the file\./);
+	});
+
+	it("limits chunk length and refuses to overflow the maxLines budget", () => {
+		const text = Array.from({ length: 30 }, (_, i) => `Sentence number ${i + 1}.`).join(" ");
+		const lines = chunkDetailForOverlay(text, 60, 3);
+		assert.equal(lines.length, 3);
+	});
+});
+
+describe("refine overlay wiring", () => {
+	it("uses named public overlays, guards lifecycle edges, and does not depend on pi-btw", () => {
+		const source = fs.readFileSync(path.join(process.cwd(), "src", "refine-ui.ts"), "utf8");
+		assert.match(source, /custom<void>/);
+		assert.match(source, /overlay:\s*true/);
+		assert.match(source, /"Reviewer"/);
+		assert.match(source, /"Criticizer"/);
+		assert.match(source, /truncateToWidth/);
+		assert.match(source, /chunkDetailForOverlay/);
+		assert.match(source, /pickOverlayHeight|pickOverlayWidth/);
+		assert.match(source, /renderBorderLine|renderHorizontalRule|renderRow/);
+		assert.match(source, /if \(this\.closed\) return;/);
+		assert.match(source, /await this\.overlayPromise/);
+		assert.match(source, /if \(!ctx\.hasUI \|\| this\.overlayPromise\) return/);
+		assert.doesNotMatch(source, /pi-btw|createAgentSession|AgentSession/);
+	});
+});

package/tests/state.test.ts

@@ -68,6 +68,7 @@ describe("init", () => {
 		assert.equal(config.reviewer.mode, "delegated-subagent");
 		assert.equal(config.reviewer.confirmed_at, null);
 		assert.equal(config.criticizer.confirmed_at, null);
+		assert.equal("execution" in config, false);
 		assert.equal(config.artifact_root, "./docs/pi-plans");
 		assert.equal(config.artifact_root_source, "unset");
 		assert.equal(config.artifact_root_updated_at, null);
@@ -194,6 +195,62 @@ describe("runs", () => {
 		assert.equal(getRun(workdir, run.run_id)?.status, "accepted");
 		assert.throws(() => setRunStatus(workdir, run.run_id, "bogus"), StateError);
 	});
+
+	it("invokes the onStart callback exactly once when startRun succeeds", () => {
+		const workdir = mkWorkdir("onstart");
+		git(workdir, "init", "-q");
+		const calls: string[] = [];
+		const { run } = startRun(workdir, {
+			topic: "marker demo",
+			skill: "plan-normal",
+			requestText: "x",
+			onStart: (current) => {
+				calls.push(current.run_id);
+			},
+		});
+		assert.deepEqual(calls, [run.run_id]);
+	});
+
+	it("does not invoke the onStart callback when startRun throws", () => {
+		const workdir = mkWorkdir("onstart-throw");
+		git(workdir, "init", "-q");
+		const calls: string[] = [];
+		assert.throws(() =>
+			startRun({
+				workdir: path.resolve(workdir),
+				artifact_root: "./docs/pi-plans",
+				artifact_root_source: "user",
+				artifact_root_updated_at: new Date().toISOString(),
+				schema: 1,
+				language: { tag: null, source: "unset", updated_at: null },
+				reviewer: { mode: "delegated-subagent", model_selector: null, name_prefix: "pi-plans-reviewer", confirmed_at: null },
+				criticizer: { mode: "delegated-subagent", model_selector: null, name_prefix: "pi-plans-criticizer", confirmed_at: null },
+				execution: { model_selector: null, source: "unset", updated_at: null },
+			}, {
+				topic: "" as string,
+				skill: "plan-normal",
+				requestText: "x",
+				onStart: () => calls.push("called"),
+			} as any),
+		);
+		assert.equal(calls.length, 0);
+	});
+});
+
+describe("legacy execution config", () => {
+	it("strips legacy execution config on load and rewrite", () => {
+		const workdir = mkWorkdir("legacy-exec");
+		git(workdir, "init", "-q");
+		initState(workdir);
+		const configPath = path.join(commonDir(workdir), "pi_plans", "config.json");
+		const config = JSON.parse(fs.readFileSync(configPath, "utf8"));
+		config.execution = { model_selector: "zai/glm-5.3-flash:high", source: "user", updated_at: null };
+		fs.writeFileSync(configPath, `${JSON.stringify(config, null, "\t")}\n`, "utf8");
+		const shown = showConfig(workdir) as any;
+		assert.equal(shown.execution, undefined);
+		setLanguage(workdir, "zh-Hans", "user");
+		assert.equal(readConfig(workdir).execution, undefined);
+	});
 });
 
 describe("set-role invariants", () => {

package/tests/subagent.test.ts

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { normalizeSubagentEvent, runPiSubagent, type SubagentProgressEvent } from "../src/subagent.ts";
+
+async function withFakePi(
+	task: string,
+	options: { signal?: AbortSignal; timeoutMs?: number; onProgress?: (event: SubagentProgressEvent) => void } = {},
+) {
+	const dir = fs.mkdtempSync(path.join(os.tmpdir(), "pi-plans-fake-pi-"));
+	const script = path.join(dir, "fake-pi.mjs");
+	fs.writeFileSync(
+		script,
+		[
+			'const emit = (event) => process.stdout.write(JSON.stringify(event) + "\\n");',
+			'emit({ type: "turn_start" });',
+			'if (process.argv.includes("Task: slow")) await new Promise((resolve) => setTimeout(resolve, 5000));',
+			'else {',
+			'  emit({ type: "message_start", message: { role: "assistant", content: [] } });',
+			'  emit({ type: "message_update", assistantMessageEvent: { type: "text_delta", delta: "working" } });',
+			'  emit({ type: "tool_execution_start", toolCallId: "call-1", toolName: "read", args: { path: "PLAN_v1.md" } });',
+			'  emit({ type: "message_end", message: { role: "assistant", model: "fake/model", content: [{ type: "text", text: "final conclusion" }] } });',
+			'}',
+		].join("\n"),
+	);
+
+	const previousScript = process.argv[1];
+	process.argv[1] = script;
+	try {
+		return await runPiSubagent({
+			systemPrompt: "test system prompt",
+			task,
+			cwd: process.cwd(),
+			signal: options.signal,
+			timeoutMs: options.timeoutMs ?? 2000,
+			onProgress: options.onProgress,
+		});
+	} finally {
+		process.argv[1] = previousScript;
+		fs.rmSync(dir, { recursive: true, force: true });
+	}
+}
+
+
+describe("subagent runner lifecycle", () => {
+	it("waits for JSONL completion and forwards progress", async () => {
+		const progress: string[] = [];
+		const result = await withFakePi("normal", {
+			timeoutMs: 2000,
+			onProgress: (event) => progress.push(`${event.type}:${event.phase ?? ""}`),
+		});
+		assert.equal(result.ok, true);
+		assert.equal(result.output, "final conclusion");
+		assert.equal(result.model, "fake/model");
+		assert.ok(progress.includes("process:started"));
+		assert.ok(progress.includes("tool:start"));
+		assert.ok(progress.includes("process:exited"));
+		assert.equal(result.turns, 1);
+	});
+
+	it("returns a cancelled result after aborting the child", async () => {
+		const abort = new AbortController();
+		const promise = withFakePi("slow", { signal: abort.signal, timeoutMs: 2000 });
+		setTimeout(() => abort.abort(), 40);
+		const result = await promise;
+		assert.equal(result.ok, false);
+		assert.equal(result.cancelled, true);
+		assert.equal(result.timedOut, undefined);
+	});
+
+	it("returns a timed out result after terminating a slow child", async () => {
+		const result = await withFakePi("slow", { timeoutMs: 40 });
+		assert.equal(result.ok, false);
+		assert.equal(result.timedOut, true);
+		assert.equal(result.cancelled, undefined);
+	});
+});
+
+describe("subagent progress events", () => {
+	it("normalizes turn and message lifecycle events", () => {
+		assert.deepEqual(normalizeSubagentEvent({ type: "turn_start" }), { type: "turn", phase: "start" });
+		assert.deepEqual(
+			normalizeSubagentEvent({
+				type: "message_update",
+				assistantMessageEvent: { type: "text_delta", delta: "checking the plan" },
+			}),
+			{ type: "message", phase: "update", role: "assistant", text: "checking the plan" },
+		);
+	});
+
+	it("normalizes tool progress without exposing unbounded arguments", () => {
+		const event = normalizeSubagentEvent({
+			type: "tool_execution_start",
+			toolCallId: "call-1",
+			toolName: "read",
+			args: { path: "/tmp/plan.md" },
+		});
+		assert.deepEqual(event, {
+			type: "tool",
+			phase: "start",
+			toolCallId: "call-1",
+			toolName: "read",
+			detail: '{"path":"/tmp/plan.md"}',
+		});
+	});
+
+	it("ignores unknown or malformed events", () => {
+		assert.equal(normalizeSubagentEvent(undefined), undefined);
+		assert.equal(normalizeSubagentEvent({ type: "future_event" }), undefined);
+		assert.equal(normalizeSubagentEvent({ type: "message_end" }), undefined);
+	});
+});

package/tools/ask-choice.ts

@@ -14,6 +14,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { disableAutoComplete, enableAutoComplete, isAutoCompleteEnabled, recordAskChoice } from "../src/autocomplete.ts";
 import { normalizeWorkdir, readActive, recordDecision } from "../src/state.ts";
 
 const Option = Type.Object({
@@ -85,14 +86,28 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 				source,
 			});
 
+			// Once enabled for this planning run, eligible questions answer with the
+			// recommendation without opening another UI prompt.
+			if (autoComplete && isAutoCompleteEnabled(ctx)) {
+				recordAskChoice(ctx, true);
+				record(recommended.label, "auto-complete");
+				return {
+					content: [{ type: "text", text: `Auto-complete selected the recommended option: ${recommended.label}` }],
+					details: details(recommended.label, "auto-complete"),
+				};
+			}
+
 			// No UI (print/json mode): planning questions may auto-complete;
 			// questions without Auto-complete must stop and wait for the user.
 			if (!ctx.hasUI) {
 				if (!autoComplete) {
+					disableAutoComplete(ctx, "non-interactive boundary");
 					throw new Error(
 						"No UI available and this question must not be auto-completed (execution handoff or external-state change). Stop and wait for the user.",
 					);
 				}
+				enableAutoComplete(ctx);
+				recordAskChoice(ctx, true);
 				record(recommended.label, "auto-complete");
 				return {
 					content: [
@@ -116,6 +131,7 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 
 			const selected = await ctx.ui.select(params.question, displayLabels);
 			if (selected === undefined) {
+				disableAutoComplete(ctx, "question cancelled");
 				return {
 					content: [
 						{
@@ -128,6 +144,8 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 			}
 
 			if (autoComplete && selected.startsWith("Auto-complete")) {
+				enableAutoComplete(ctx);
+				recordAskChoice(ctx, true);
 				record(recommended.label, "auto-complete");
 				return {
 					content: [
@@ -143,11 +161,13 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 			if (allowOther && selected.startsWith("Other…")) {
 				const typed = await ctx.ui.input(`${params.question} — your answer:`);
 				if (typed === undefined || !typed.trim()) {
+					disableAutoComplete(ctx, "free-form answer cancelled");
 					return {
 						content: [{ type: "text", text: "User cancelled the free-form answer. Ask again or stop." }],
 						details: details(null, "cancelled"),
 					};
 				}
+				recordAskChoice(ctx, false);
 				const answer = typed.trim();
 				record(answer, "user");
 				return {
@@ -159,11 +179,13 @@ export function registerAskChoiceTool(pi: ExtensionAPI): void {
 			const index = displayLabels.indexOf(selected);
 			const option = index >= 0 && index < options.length ? options[index] : undefined;
 			if (!option) {
+				recordAskChoice(ctx, false);
 				return {
 					content: [{ type: "text", text: `User selected: ${selected}` }],
 					details: details(selected, "user"),
 				};
 			}
+			recordAskChoice(ctx, false);
 			record(option.label, "user");
 			return {
 				content: [{ type: "text", text: `User selected: ${index + 1}. ${option.label}` }],