@ilya-lesikov/pi-pi 0.7.0 → 0.8.0

package/3p/pi-plannotator/apps/pi-extension/README.md

@@ -161,14 +161,15 @@ Supported actions and payloads:
 - `annotate-last`: `{ markdown? }`
 - `archive`: `{ customPlanPath? }`
 
-Plan review is asynchronous:
+Plan review and code review are asynchronous:
 
-- callers send `plannotator:request` with action `plan-review`
-- Plannotator opens the browser review and immediately responds with `{ status: "handled", result: { status: "pending", reviewId } }`
-- when the human approves or rejects in the browser, Plannotator emits `plannotator:review-result` with `{ reviewId, approved, feedback, savedPath?, agentSwitch?, permissionMode? }`
+- callers send `plannotator:request` with action `plan-review` or `code-review`
+- Plannotator immediately responds with `{ status: "handled", result: { status: "pending", reviewId } }` — for `code-review` this ack is emitted BEFORE the (potentially slow) browser session and PR/diff/worktree preparation start, so callers can detect an absent extension within the short availability window without waiting for the review itself
+- when the human approves or rejects in the browser (or closes the window), Plannotator emits `plannotator:review-result` with `{ reviewId, approved, feedback, savedPath?, agentSwitch?, permissionMode? }`
+- if `code-review` startup/preparation fails after the pending ack, Plannotator emits `plannotator:review-result` with `{ reviewId, approved: false, error }` so the failure is distinguishable from a legitimate user rejection
 - callers can query `review-status` with the same `reviewId` to recover from startup races or session restarts
 
-The other shared actions remain request/response flows. Payloads are intentionally minimal and only include fields the shared implementation actually uses.
+The remaining shared actions (`annotate`, `annotate-last`, `archive`, `review-status`) are synchronous request/response flows. Payloads are intentionally minimal and only include fields the shared implementation actually uses.
 
 ### Markdown annotation
 

package/3p/pi-plannotator/apps/pi-extension/plannotator-browser.ts

@@ -59,6 +59,19 @@ export interface PlanReviewBrowserSession extends BrowserDecisionSession<PlanRev
 	onDecision: (listener: (result: PlanReviewDecision) => void | Promise<void>) => () => void;
 }
 
+export interface CodeReviewDecision {
+	approved: boolean;
+	feedback?: string;
+	annotations?: unknown[];
+	agentSwitch?: string;
+	exit?: boolean;
+}
+
+export interface CodeReviewBrowserSession extends BrowserDecisionSession<CodeReviewDecision> {
+	reviewId: string;
+	onDecision: (listener: (result: CodeReviewDecision) => void | Promise<void>) => () => void;
+}
+
 const __dirname = dirname(fileURLToPath(import.meta.url));
 let planHtmlContent = "";
 let reviewHtmlContent = "";
@@ -230,15 +243,7 @@ export async function openCodeReview(
 export async function startCodeReviewBrowserSession(
 	ctx: ExtensionContext,
 	options: { cwd?: string; defaultBranch?: string; diffType?: DiffType; prUrl?: string; vcsType?: VcsSelection; useLocal?: boolean } = {},
-): Promise<
-	BrowserDecisionSession<{
-		approved: boolean;
-		feedback?: string;
-		annotations?: unknown[];
-		agentSwitch?: string;
-		exit?: boolean;
-	}>
-> {
+): Promise<CodeReviewBrowserSession> {
 	if (!ctx.hasUI || !reviewHtmlContent) {
 		throw new Error("Plannotator code review browser is unavailable in this session.");
 	}
@@ -477,9 +482,19 @@ export async function startCodeReviewBrowserSession(
 		shareBaseUrl: process.env.PLANNOTATOR_SHARE_URL || undefined,
 		pasteApiUrl: process.env.PLANNOTATOR_PASTE_URL || undefined,
 		onCleanup: worktreeCleanup,
+		repoCwd: agentCwd ?? options.cwd ?? ctx.cwd,
 	});
 
-	return startBrowserDecisionSession(server, ctx, server.waitForDecision);
+	const session = startBrowserDecisionSession(server, ctx, server.waitForDecision);
+	server.onDecision(() => {
+		setTimeout(() => session.stop(), 1500);
+	});
+
+	return {
+		...session,
+		reviewId: server.reviewId,
+		onDecision: server.onDecision,
+	};
 }
 
 export async function openMarkdownAnnotation(

package/3p/pi-plannotator/apps/pi-extension/plannotator-events.code-review.test.ts

@@ -0,0 +1,172 @@
+import { describe, expect, test, mock, beforeEach } from "bun:test";
+
+type DecisionListener = (result: { approved: boolean; feedback?: string; agentSwitch?: string }) => void;
+
+let sessionBehavior: {
+	throwOnStart?: Error;
+	decision?: { approved: boolean; feedback?: string };
+	resolveWaitImmediately?: boolean;
+} = {};
+let startCalls = 0;
+let decisionListeners: DecisionListener[] = [];
+
+mock.module("./plannotator-browser.js", () => ({
+	getLastAssistantMessageText: () => "",
+	getStartupErrorMessage: (err: unknown) => (err instanceof Error ? err.message : "Unknown error"),
+	hasPlanBrowserHtml: () => true,
+	hasReviewBrowserHtml: () => true,
+	shouldUseLocalPrCheckout: (options: { useLocal?: boolean }) => options.useLocal !== false,
+	openArchiveBrowserAction: async () => ({ opened: false }),
+	openCodeReview: async () => ({ approved: false }),
+	openPlanReviewBrowser: async () => ({ approved: false }),
+	openLastMessageAnnotation: async () => ({ feedback: "" }),
+	openMarkdownAnnotation: async () => ({ feedback: "" }),
+	startCodeReviewBrowserSession: async () => {
+		startCalls += 1;
+		if (sessionBehavior.throwOnStart) throw sessionBehavior.throwOnStart;
+		return {
+			url: "http://localhost:0",
+			reviewId: "server-review-id",
+			onDecision: (listener: DecisionListener) => {
+				decisionListeners.push(listener);
+				return () => {};
+			},
+			waitForDecision: () =>
+				new Promise((resolve) => {
+					if (sessionBehavior.resolveWaitImmediately && sessionBehavior.decision) {
+						resolve(sessionBehavior.decision as any);
+					}
+				}),
+			stop: () => {},
+		};
+	},
+	startLastMessageAnnotationSession: async () => ({}),
+	startMarkdownAnnotationSession: async () => ({}),
+	startPlanReviewBrowserSession: async () => ({}),
+}));
+
+const { registerPlannotatorEventListeners, PLANNOTATOR_REQUEST_CHANNEL, PLANNOTATOR_REVIEW_RESULT_CHANNEL } =
+	await import("./plannotator-events.js");
+
+interface FakePi {
+	on: (event: string, handler: (event: any, ctx: any) => void | Promise<void>) => void;
+	events: {
+		on: (channel: string, handler: (data: any) => void) => () => void;
+		emit: (channel: string, data: any) => void;
+		_handlers: Record<string, Array<(data: any) => void>>;
+		_sessionStart?: (event: any, ctx: any) => void | Promise<void>;
+	};
+}
+
+function makeFakePi(): FakePi {
+	const handlers: Record<string, Array<(data: any) => void>> = {};
+	const pi: FakePi = {
+		on: (event, handler) => {
+			if (event === "session_start") pi.events._sessionStart = handler;
+		},
+		events: {
+			_handlers: handlers,
+			on: (channel, handler) => {
+				(handlers[channel] ??= []).push(handler);
+				return () => {
+					handlers[channel] = (handlers[channel] ?? []).filter((h) => h !== handler);
+				};
+			},
+			emit: (channel, data) => {
+				for (const h of handlers[channel] ?? []) h(data);
+			},
+		},
+	};
+	return pi;
+}
+
+async function emitCodeReviewRequest(pi: FakePi): Promise<{
+	response: any;
+	results: any[];
+}> {
+	const results: any[] = [];
+	pi.events.on(PLANNOTATOR_REVIEW_RESULT_CHANNEL, (data) => results.push(data));
+
+	let response: any;
+	pi.events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
+		requestId: "req-1",
+		action: "code-review",
+		payload: { cwd: "/tmp/repo" },
+		respond: (r: any) => {
+			response = r;
+		},
+	});
+	// Let the synchronous respond + microtasks settle.
+	await new Promise((r) => setTimeout(r, 10));
+	return { response, results };
+}
+
+beforeEach(() => {
+	sessionBehavior = {};
+	startCalls = 0;
+	decisionListeners = [];
+});
+
+describe("code-review two-phase handler", () => {
+	test("acks pending with a reviewId synchronously, before any heavy prep resolves", async () => {
+		const pi = makeFakePi();
+		registerPlannotatorEventListeners(pi as any);
+		await pi.events._sessionStart?.({}, { cwd: "/tmp/repo", hasUI: true });
+
+		let respondedSynchronously = false;
+		let ackReviewId: string | undefined;
+		pi.events.emit(PLANNOTATOR_REQUEST_CHANNEL, {
+			requestId: "req-1",
+			action: "code-review",
+			payload: { cwd: "/tmp/repo" },
+			respond: (r: any) => {
+				respondedSynchronously = true;
+				ackReviewId = r?.result?.reviewId;
+				expect(r.status).toBe("handled");
+				expect(r.result.status).toBe("pending");
+			},
+		});
+
+		// The ack must fire in the same tick as the request handler's first
+		// awaited boundary — before startCodeReviewBrowserSession is invoked.
+		expect(respondedSynchronously).toBe(true);
+		expect(typeof ackReviewId).toBe("string");
+		expect(ackReviewId!.length).toBeGreaterThan(0);
+	});
+
+	test("emits a review-result on the pending reviewId when the user decides", async () => {
+		const pi = makeFakePi();
+		registerPlannotatorEventListeners(pi as any);
+		await pi.events._sessionStart?.({}, { cwd: "/tmp/repo", hasUI: true });
+
+		const { response, results } = await emitCodeReviewRequest(pi);
+		const reviewId = response.result.reviewId;
+
+		expect(startCalls).toBe(1);
+		expect(decisionListeners.length).toBe(1);
+
+		decisionListeners[0]({ approved: true, feedback: "looks good" });
+
+		expect(results.length).toBe(1);
+		expect(results[0].reviewId).toBe(reviewId);
+		expect(results[0].approved).toBe(true);
+		expect(results[0].feedback).toBe("looks good");
+		expect(results[0].error).toBeUndefined();
+	});
+
+	test("emits a review-result with an error when startup/prep fails after the pending ack", async () => {
+		sessionBehavior = { throwOnStart: new Error("worktree prep failed") };
+		const pi = makeFakePi();
+		registerPlannotatorEventListeners(pi as any);
+		await pi.events._sessionStart?.({}, { cwd: "/tmp/repo", hasUI: true });
+
+		const { response, results } = await emitCodeReviewRequest(pi);
+		const reviewId = response.result.reviewId;
+
+		expect(response.result.status).toBe("pending");
+		expect(results.length).toBe(1);
+		expect(results[0].reviewId).toBe(reviewId);
+		expect(results[0].approved).toBe(false);
+		expect(results[0].error).toBe("worktree prep failed");
+	});
+});

package/3p/pi-plannotator/apps/pi-extension/plannotator-events.ts

@@ -8,7 +8,6 @@ import {
 	getLastAssistantMessageText,
 	getStartupErrorMessage,
 	openArchiveBrowserAction,
-	openCodeReview,
 	openLastMessageAnnotation,
 	openMarkdownAnnotation,
 	startCodeReviewBrowserSession,
@@ -74,6 +73,12 @@ export interface PlannotatorReviewResultEvent {
 	savedPath?: string;
 	agentSwitch?: string;
 	permissionMode?: string;
+	/**
+	 * Set when the review could not be produced (e.g. code-review startup/prep
+	 * failed after the pending ack). Distinguishes a failure from a legitimate
+	 * user rejection (`approved: false` with feedback).
+	 */
+	error?: string;
 }
 
 export interface PlannotatorReviewStatusPayload {
@@ -101,6 +106,11 @@ export interface PlannotatorCodeReviewResult {
 	agentSwitch?: string;
 }
 
+export interface PlannotatorCodeReviewStartResult {
+	status: "pending";
+	reviewId: string;
+}
+
 export interface PlannotatorAnnotatePayload {
 	filePath: string;
 	markdown?: string;
@@ -129,7 +139,7 @@ export interface PlannotatorArchiveResult {
 export type PlannotatorRequestMap = {
 	"plan-review": PlannotatorRequestBase<"plan-review", PlannotatorPlanReviewPayload, PlannotatorPlanReviewStartResult>;
 	"review-status": PlannotatorRequestBase<"review-status", PlannotatorReviewStatusPayload, PlannotatorReviewStatusResult>;
-	"code-review": PlannotatorRequestBase<"code-review", PlannotatorCodeReviewPayload, PlannotatorCodeReviewResult>;
+	"code-review": PlannotatorRequestBase<"code-review", PlannotatorCodeReviewPayload, PlannotatorCodeReviewStartResult>;
 	annotate: PlannotatorRequestBase<"annotate", PlannotatorAnnotatePayload, PlannotatorAnnotationResult>;
 	"annotate-last": PlannotatorRequestBase<"annotate-last", PlannotatorAnnotatePayload, PlannotatorAnnotationResult>;
 	archive: PlannotatorRequestBase<"archive", PlannotatorArchivePayload, PlannotatorArchiveResult>;
@@ -138,7 +148,7 @@ export type PlannotatorRequest = PlannotatorRequestMap[PlannotatorAction];
 export type PlannotatorResponseMap = {
 	"plan-review": PlannotatorResponse<PlannotatorPlanReviewStartResult>;
 	"review-status": PlannotatorResponse<PlannotatorReviewStatusResult>;
-	"code-review": PlannotatorResponse<PlannotatorCodeReviewResult>;
+	"code-review": PlannotatorResponse<PlannotatorCodeReviewStartResult>;
 	annotate: PlannotatorResponse<PlannotatorAnnotationResult>;
 	"annotate-last": PlannotatorResponse<PlannotatorAnnotationResult>;
 	archive: PlannotatorResponse<PlannotatorArchiveResult>;
@@ -263,15 +273,43 @@ export function registerPlannotatorEventListeners(pi: ExtensionAPI): void {
 					return;
 				}
 				case "code-review": {
-					const result = await openCodeReview(ctx, {
-						cwd: request.payload?.cwd,
-						defaultBranch: request.payload?.defaultBranch,
-						diffType: request.payload?.diffType,
-						vcsType: request.payload?.vcsType,
-						useLocal: request.payload?.useLocal,
-						prUrl: request.payload?.prUrl,
-					});
-					request.respond({ status: "handled", result });
+					const reviewId = crypto.randomUUID();
+					setStoredReviewStatus(reviewId, { status: "pending" });
+					request.respond({ status: "handled", result: { status: "pending", reviewId } });
+
+					const payload = request.payload;
+					void (async () => {
+						try {
+							const session = await startCodeReviewBrowserSession(ctx, {
+								cwd: payload?.cwd,
+								defaultBranch: payload?.defaultBranch,
+								diffType: payload?.diffType,
+								vcsType: payload?.vcsType,
+								useLocal: payload?.useLocal,
+								prUrl: payload?.prUrl,
+							});
+							session.onDecision((result) => {
+								const reviewResult = {
+									reviewId,
+									approved: result.approved,
+									feedback: result.feedback,
+									agentSwitch: result.agentSwitch,
+								} satisfies PlannotatorReviewResultEvent;
+								setStoredReviewStatus(reviewId, { status: "completed", ...reviewResult });
+								pi.events.emit(PLANNOTATOR_REVIEW_RESULT_CHANNEL, reviewResult);
+							});
+							await session.waitForDecision();
+						} catch (err) {
+							const message = getStartupErrorMessage(err);
+							const reviewResult = {
+								reviewId,
+								approved: false,
+								error: message,
+							} satisfies PlannotatorReviewResultEvent;
+							setStoredReviewStatus(reviewId, { status: "completed", ...reviewResult });
+							pi.events.emit(PLANNOTATOR_REVIEW_RESULT_CHANNEL, reviewResult);
+						}
+					})();
 					return;
 				}
 				case "annotate": {

package/3p/pi-plannotator/apps/pi-extension/server/project.test.ts

@@ -0,0 +1,45 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { execSync } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { getRepoInfo } from "./project";
+
+const cleanup: string[] = [];
+
+function makeRepo(branch: string): string {
+	const dir = mkdtempSync(join(tmpdir(), "plannotator-project-test-"));
+	cleanup.push(dir);
+	const run = (cmd: string) => execSync(cmd, { cwd: dir, stdio: ["pipe", "pipe", "pipe"] });
+	run(`git init -q -b ${branch}`);
+	run("git config user.email test@test.local");
+	run("git config user.name test");
+	run("git remote add origin https://github.com/acme/widget.git");
+	run("git commit -q --allow-empty -m init");
+	return dir;
+}
+
+afterAll(() => {
+	for (const dir of cleanup) {
+		try {
+			rmSync(dir, { recursive: true, force: true });
+		} catch {}
+	}
+});
+
+describe("getRepoInfo(cwd)", () => {
+	test("reports the repo at the given cwd, not process.cwd()", () => {
+		const repo = makeRepo("feature-x");
+		const info = getRepoInfo(repo);
+		expect(info).not.toBeNull();
+		expect(info!.display).toBe("acme/widget");
+		expect(info!.branch).toBe("feature-x");
+	});
+
+	test("two different cwds resolve to their own repos", () => {
+		const a = makeRepo("branch-a");
+		const b = makeRepo("branch-b");
+		expect(getRepoInfo(a)!.branch).toBe("branch-a");
+		expect(getRepoInfo(b)!.branch).toBe("branch-b");
+	});
+});

package/3p/pi-plannotator/apps/pi-extension/server/project.ts

@@ -9,11 +9,12 @@ import { sanitizeTag } from "../generated/project.js";
 import { parseRemoteUrl, getDirName } from "../generated/repo.js";
 
 /** Run a git command and return stdout (empty string on error). */
-function git(cmd: string): string {
+function git(cmd: string, cwd?: string): string {
 	try {
 		return execSync(`git ${cmd}`, {
 			encoding: "utf-8",
 			stdio: ["pipe", "pipe", "pipe"],
+			cwd,
 		}).trim();
 	} catch {
 		return "";
@@ -39,23 +40,23 @@ export function detectProjectName(): string {
 	}
 }
 
-export function getRepoInfo(): { display: string; branch?: string } | null {
-	const branch = git("rev-parse --abbrev-ref HEAD");
+export function getRepoInfo(cwd?: string): { display: string; branch?: string } | null {
+	const branch = git("rev-parse --abbrev-ref HEAD", cwd);
 	const safeBranch = branch && branch !== "HEAD" ? branch : undefined;
 
-	const originUrl = git("remote get-url origin");
+	const originUrl = git("remote get-url origin", cwd);
 	const orgRepo = parseRemoteUrl(originUrl);
 	if (orgRepo) {
 		return { display: orgRepo, branch: safeBranch };
 	}
 
-	const topLevel = git("rev-parse --show-toplevel");
+	const topLevel = git("rev-parse --show-toplevel", cwd);
 	const repoName = getDirName(topLevel);
 	if (repoName) {
 		return { display: repoName, branch: safeBranch };
 	}
 
-	const cwdName = getDirName(process.cwd());
+	const cwdName = getDirName(cwd ?? process.cwd());
 	if (cwdName) {
 		return { display: cwdName };
 	}

package/3p/pi-plannotator/apps/pi-extension/server/serverReview.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
 import { readFileSync, existsSync } from "node:fs";
 import { createServer } from "node:http";
 import os from "node:os";
@@ -161,18 +162,22 @@ function detectWSL(): boolean {
 	return false;
 }
 
+export interface ReviewDecision {
+	approved: boolean;
+	feedback: string;
+	annotations: unknown[];
+	agentSwitch?: string;
+	exit?: boolean;
+}
+
 export interface ReviewServerResult {
+	reviewId: string;
 	port: number;
 	portSource: "env" | "remote-default" | "random";
 	url: string;
 	isRemote: boolean;
-	waitForDecision: () => Promise<{
-		approved: boolean;
-		feedback: string;
-		annotations: unknown[];
-		agentSwitch?: string;
-		exit?: boolean;
-	}>;
+	waitForDecision: () => Promise<ReviewDecision>;
+	onDecision: (listener: (result: ReviewDecision) => void | Promise<void>) => () => void;
 	stop: () => void;
 }
 
@@ -206,6 +211,8 @@ export async function startReviewServer(options: {
 	onCleanup?: () => void | Promise<void>;
 	/** Called when server starts with the URL, remote status, and port */
 	onReady?: (url: string, isRemote: boolean, port: number) => void;
+	/** Working directory of the reviewed repo, used for repo-info (title/header) detection. */
+	repoCwd?: string;
 }): Promise<ReviewServerResult> {
 	const gitUser = detectGitUser();
 	let draftKey = contentHash(options.rawPatch);
@@ -266,7 +273,7 @@ export async function startReviewServer(options: {
 			}
 		: workspace
 			? { display: basename(workspace.root), branch: "Workspace" }
-		: getRepoInfo();
+		: getRepoInfo(options.repoCwd);
 	const editorAnnotations = createEditorAnnotationHandler();
 	const externalAnnotations = createExternalAnnotationHandler("review");
 
@@ -538,22 +545,24 @@ export async function startReviewServer(options: {
 		(options.shareBaseUrl ?? process.env.PLANNOTATOR_SHARE_URL) || undefined;
 	const pasteApiUrl =
 		(options.pasteApiUrl ?? process.env.PLANNOTATOR_PASTE_URL) || undefined;
-	let resolveDecision!: (result: {
-		approved: boolean;
-		feedback: string;
-		annotations: unknown[];
-		agentSwitch?: string;
-		exit?: boolean;
-	}) => void;
-	const decisionPromise = new Promise<{
-		approved: boolean;
-		feedback: string;
-		annotations: unknown[];
-		agentSwitch?: string;
-		exit?: boolean;
-	}>((r) => {
+	const reviewId = randomUUID();
+	let resolveDecision!: (result: ReviewDecision) => void;
+	const decisionListeners = new Set<(result: ReviewDecision) => void | Promise<void>>();
+	let decisionSettled = false;
+	const decisionPromise = new Promise<ReviewDecision>((r) => {
 		resolveDecision = r;
 	});
+	const publishDecision = (result: ReviewDecision): boolean => {
+		if (decisionSettled) return false;
+		decisionSettled = true;
+		resolveDecision(result);
+		for (const listener of decisionListeners) {
+			Promise.resolve(listener(result)).catch((error) => {
+				console.error("[Code Review] Decision listener failed:", error);
+			});
+		}
+		return true;
+	};
 
 	const aiRuntime = await createPiAIRuntime({ getCwd: resolveAgentCwd });
 
@@ -1175,13 +1184,13 @@ export async function startReviewServer(options: {
 			return;
 		} else if (url.pathname === "/api/exit" && req.method === "POST") {
 			deleteDraft(draftKey);
-			resolveDecision({ approved: false, feedback: '', annotations: [], exit: true });
-			json(res, { ok: true });
+			const duplicate = !publishDecision({ approved: false, feedback: '', annotations: [], exit: true });
+			json(res, { ok: true, ...(duplicate && { duplicate: true }) });
 		} else if (url.pathname === "/api/feedback" && req.method === "POST") {
 			try {
 				const body = await parseBody(req);
 				deleteDraft(draftKey);
-				resolveDecision({
+				publishDecision({
 					approved: (body.approved as boolean) ?? false,
 					feedback: (body.feedback as string) || "",
 					annotations: (body.annotations as unknown[]) || [],
@@ -1207,11 +1216,18 @@ export async function startReviewServer(options: {
 	}
 
 	return {
+		reviewId,
 		port,
 		portSource,
 		url: serverUrl,
 		isRemote,
 		waitForDecision: () => decisionPromise,
+		onDecision: (listener) => {
+			decisionListeners.add(listener);
+			return () => {
+				decisionListeners.delete(listener);
+			};
+		},
 		stop: () => {
 			process.removeListener("exit", exitHandler);
 			agentJobs.killAll();

package/3p/pi-subagents/src/agent-manager.ts

@@ -123,6 +123,10 @@ export class AgentManager {
     record.status = "running";
     record.startedAt = Date.now();
     if (options.toolCallId && !record.toolCallId) record.toolCallId = options.toolCallId;
+    // Reset first-progress flags: a re-started (e.g. dequeued) record must be able
+    // to emit first_tool/first_turn again for its fresh run.
+    record.firstToolEmitted = false;
+    record.firstTurnEmitted = false;
     if (options.isBackground) this.runningBackground++;
     this.onStart?.(record);
 
@@ -153,9 +157,38 @@ export class AgentManager {
       signal: record.abortController!.signal,
       onToolActivity: (activity) => {
         if (activity.type === "end") record.toolUses++;
+        // Emit first_tool once per run from this single choke point, so ALL spawn
+        // paths (RPC panels, Agent-tool background, foreground) report it — not
+        // just the Agent tool's background branch. Panels spawn via RPC and were
+        // previously silent, making it impossible to tell if a reviewer actually
+        // investigated (ran tools) or wrote from context alone.
+        if (activity.type === "start" && !record.firstToolEmitted) {
+          record.firstToolEmitted = true;
+          try {
+            pi.events.emit("subagents:first_tool", {
+              id,
+              type,
+              description: options.description,
+              toolName: activity.toolName,
+            });
+          } catch { /* ignore */ }
+        }
         options.onToolActivity?.(activity);
       },
-      onTurnEnd: options.onTurnEnd,
+      onTurnEnd: (turnCount) => {
+        if (!record.firstTurnEmitted) {
+          record.firstTurnEmitted = true;
+          try {
+            pi.events.emit("subagents:first_turn", {
+              id,
+              type,
+              description: options.description,
+              turnCount,
+            });
+          } catch { /* ignore */ }
+        }
+        options.onTurnEnd?.(turnCount);
+      },
       onTextDelta: options.onTextDelta,
       validateCompletion: options.validateCompletion,
       maxValidationRetries: options.maxValidationRetries,