@maxiaochao/pi-toolkit 0.10.21 → 0.10.23

package/packages/herdr-subagents/src/history.ts

@@ -1,18 +1,11 @@
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { appendFile, mkdir, readFile, rm, rmdir } from "node:fs/promises";
+import { appendFile, mkdir, readFile, rm } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
-import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
-import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
-import { writeJsonAtomic, writeTextAtomic } from "./state.ts";
-import { cleanupRunTab } from "./tab-cleanup.ts";
+import type { HerdrAutomation } from "./herdr.ts";
 import type { OwnerIdentity } from "./ownership.ts";
-import { ownerRecord } from "./ownership.ts";
-import { aggregateTaskStatus, applyRunStatus } from "./run-status.ts";
-import { applyReport, applyTaskStatus, isActiveStatus, normalizeNeedsInputReport, projectTaskActivity, readReport, readRunRecord, readTaskRecord, settleAttemptFailure, type PersistedDocument, type PersistedReport, type RunRecord, type RunStatus, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
-import { attemptReportPath } from "./attempts.ts";
-import { continuationSystemPrompt } from "./protocol.ts";
-import { isAbortError } from "./errors.ts";
+import { isActiveStatus, readReport, readRunRecord, readTaskRecord, type PersistedDocument, type RunStatus, type TaskActivity, type TaskRecord, type TaskStatus } from "./records.ts";
 import { findRunDirectory } from "./run-locator.ts";
+import { resumeHistoricalTaskConcurrent } from "./historical-resume.ts";
 
 export interface HistoricalTask { order: number; id: string; name: string; agent: string; status: TaskStatus; summary?: string; question?: string; documents: PersistedDocument[]; recordDirectory: string; sessionFile: string; model?: string; thinking?: string; tools?: string[]; skills: string[]; access?: string; }
 export interface HistoricalRun { id: string; label: string; status: RunStatus; startedAt: string; completedAt?: string; effectiveConcurrency?: number; cleanupPendingTabIds?: string[]; tasks: HistoricalTask[]; recordDirectory: string; }
@@ -104,124 +97,5 @@ export interface ResumeHistoricalTaskOptions { herdr?: HerdrAutomation; signal?:
 export interface ResumeHistoricalTaskResult { runId: string; label: string; status: TaskStatus; summary: string; documents: PersistedDocument[]; tabId: string; paneId: string; sessionFile: string; activity: TaskActivity[]; }
 
 export async function resumeHistoricalTask(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions = {}): Promise<ResumeHistoricalTaskResult> {
-	const runDirectory = await findRunDirectory(join(cwd, ".pi", "herdr-subagents", "runs"), runId);
-	if (!runDirectory) throw new Error(`Unknown Subagent run '${runId}'.`);
-	const canonicalRunId = (await readRunRecord(join(runDirectory, "run.json"))).id;
-	const lockDirectory = join(runDirectory, ".resume.lock");
-	try { await mkdir(lockDirectory); }
-	catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "EEXIST") throw new Error(`Subagent run '${runId}' already has a historical resume in progress (lock: ${lockDirectory}).`);
-		throw error;
-	}
-	try { return await resumeHistoricalTaskLocked(cwd, canonicalRunId, taskNumber, prompt, options); }
-	finally { await rmdir(lockDirectory); }
-}
-
-async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber: number, prompt: string, options: ResumeHistoricalTaskOptions): Promise<ResumeHistoricalTaskResult> {
-	const herdr = options.herdr ?? new CliHerdrAutomation();
-	const { signal, onCleanupError } = options;
-	const run = (await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId);
-	const historical = run?.tasks.find((task) => task.order === taskNumber);
-	if (!run || !historical) throw new Error(`Unknown historical task ${runId}#${taskNumber}.`);
-	if (isActiveStatus(run.status)) throw new Error(`Subagent run '${runId}' is still active. Use action 'respond' for blocked work or wait for it to settle before resuming history.`);
-	if (run.cleanupPendingTabIds?.length) throw new Error(`Subagent run '${runId}' is still waiting to clean up Herdr tabs ${run.cleanupPendingTabIds.join(", ")}.`);
-	if (!existsSync(historical.sessionFile)) throw new Error(`Historical task ${runId}#${taskNumber} has no saved Pi session.`);
-	const taskFile = join(historical.recordDirectory, "task.json");
-	const task = await readTaskRecord(taskFile);
-	const attempt = Number(task.attempt ?? 1) + 1;
-	const turnsDirectory = join(historical.recordDirectory, "turns");
-	await mkdir(turnsDirectory, { recursive: true, mode: 0o700 });
-	const initialTurnFile = join(turnsDirectory, "01.json");
-	if (!existsSync(initialTurnFile)) {
-		const initialReportFile = join(historical.recordDirectory, "report.json");
-		let initialReport;
-		try { initialReport = await readReport(initialReportFile); }
-		catch (error) { initialReport = { status: "failed" as const, summary: `Previous structured report was unavailable: ${error instanceof Error ? error.message : String(error)}`, documents: [] }; }
-		await writeJsonAtomic(initialTurnFile, { attempt: 1, prompt: task.prompt, status: task.status, summary: initialReport.summary, question: initialReport.question, error: initialReport.error, documents: initialReport.documents ?? [], sessionFile: historical.sessionFile, startedAt: task.startedAt, completedAt: task.completedAt });
-	}
-	const turnFile = join(turnsDirectory, `${String(attempt).padStart(2, "0")}.json`);
-	const followupPrompt = join(historical.recordDirectory, "followup-system-prompt.md");
-	await writeTextAtomic(followupPrompt, `${continuationSystemPrompt(task.systemPrompt, "Continue the requested historical work.", "followup")}\n`);
-	let tab: { tabId: string; paneId: string } | undefined;
-	let failedAttempt: { status: "cancelled" | "failed"; report: PersistedReport; error: unknown } | undefined;
-	const agentName = liveAgentName(historical.id, attempt);
-	try {
-		let report: PersistedReport;
-		let status: "blocked" | "completed" | "failed";
-		try {
-			const env = childEnvironment(historical.recordDirectory);
-			tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd, label: `SA · ${run.label}`, env, focus: false, signal: options.signal });
-			const paneLabel = `${String(historical.order).padStart(2, "0")} · ${historical.name}`;
-			await herdr.renamePane(tab.paneId, paneLabel, options.signal);
-			applyTaskStatus(task, "running");
-			Object.assign(task, { attempt, currentTurnFile: turnFile, tabId: tab.tabId, paneId: tab.paneId, paneLabel, agentName });
-			const activeRunFile = join(run.recordDirectory, "run.json");
-			const activeRunRecord = await readRunRecord(activeRunFile);
-			applyRunStatus(activeRunRecord, "running");
-			Object.assign(activeRunRecord, { ...ownerRecord(options.owner), tabId: tab.tabId, paneIds: [...new Set([...(activeRunRecord.paneIds ?? []), tab.paneId])] });
-			await Promise.all([
-				writeJsonAtomic(taskFile, task),
-				writeJsonAtomic(turnFile, { attempt, prompt, status: "running", sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, startedAt: new Date().toISOString() }),
-				writeJsonAtomic(activeRunFile, activeRunRecord),
-			]);
-			const runningActivity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
-			options.onUpdate?.({ runId, label: run.label, status: "running", summary: `${historical.name} is continuing.`, documents: [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity: runningActivity });
-			const prompted = await promptLiveAgent({ herdr, task: { ...task, id: historical.id, sessionFile: historical.sessionFile }, paneId: tab.paneId, prompt, systemPromptFile: followupPrompt, agentName, signal, stalledWarningMs: options.stalledWarningSeconds ? options.stalledWarningSeconds * 1000 : undefined, onStalled: () => options.onStalled?.(`${historical.name} appears stalled; it is still running.`) });
-			task.currentAttemptId = prompted.attemptId;
-			report = normalizeNeedsInputReport(prompted.report, Number.POSITIVE_INFINITY);
-			if (report !== prompted.report) await Promise.all([
-				writeJsonAtomic(join(historical.recordDirectory, "report.json"), report),
-				writeJsonAtomic(attemptReportPath(historical.recordDirectory, prompted.attemptId), report),
-			]);
-			status = applyReport(task, report);
-		} catch (error) {
-			const settled = await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
-				cancelled: isAbortError(error, signal),
-				error: error instanceof Error ? error.message : String(error),
-				name: `${historical.name} follow-up`,
-				replaceReport: true,
-			});
-			failedAttempt = { ...settled, error };
-			throw error;
-		}
-		await Promise.all([
-			writeJsonAtomic(taskFile, task),
-			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents ?? [], sessionFile: historical.sessionFile, tabId: tab.tabId, paneId: tab.paneId, agentName, completedAt: new Date().toISOString(), ...(report.question ? { question: report.question } : {}), ...(report.error ? { error: report.error } : {}) }),
-		]);
-		const runRecord = await readRunRecord(join(run.recordDirectory, "run.json"));
-		const aggregateStatus = aggregateTaskStatus((await listSubagentHistory(cwd)).find((candidate) => candidate.id === runId)?.tasks.map((entry) => entry.status) ?? [status]);
-		applyRunStatus(runRecord, aggregateStatus, { question: report.question });
-		Object.assign(runRecord, { ...ownerRecord(options.owner), tabId: tab.tabId });
-		await writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord);
-		if (status !== "blocked") {
-			await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError });
-		}
-		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
-		return { runId, label: run.label, status, summary: report.summary, documents: report.documents ?? [], tabId: tab.tabId, paneId: tab.paneId, sessionFile: historical.sessionFile, activity };
-	} catch (error) {
-		const message = error instanceof Error ? error.message : String(error);
-		const completedAt = new Date().toISOString();
-		const settled = failedAttempt ?? await settleAttemptFailure(task, join(historical.recordDirectory, "report.json"), {
-			cancelled: isAbortError(error, signal),
-			error: message,
-			name: `${historical.name} follow-up`,
-			at: completedAt,
-			replaceReport: true,
-		});
-		const { status, report } = settled;
-		task.attempt = attempt;
-		const runRecord = await readRunRecord(join(run.recordDirectory, "run.json"));
-		const aggregateStatus = status === "cancelled" ? "cancelled" : aggregateTaskStatus(run.tasks.map((entry) => entry.id === historical.id ? status : entry.status));
-		applyRunStatus(runRecord, aggregateStatus, { error: message });
-		Object.assign(runRecord, { ...ownerRecord(options.owner), ...(tab ? { tabId: tab.tabId } : {}) });
-		await Promise.all([
-			writeJsonAtomic(taskFile, task),
-			writeJsonAtomic(turnFile, { attempt, prompt, status, summary: report.summary, documents: report.documents, error: message, sessionFile: historical.sessionFile, ...(tab ? { tabId: tab.tabId, paneId: tab.paneId } : {}), completedAt }),
-			writeJsonAtomic(join(run.recordDirectory, "run.json"), runRecord),
-		]);
-		const activity = await Promise.all(run.tasks.map(async (entry, index) => projectTaskActivity(await readTaskRecord(join(entry.recordDirectory, "task.json")), index)));
-		options.onUpdate?.({ runId, label: run.label, status, summary: report.summary, documents: report.documents, tabId: tab?.tabId ?? "", paneId: tab?.paneId ?? "", sessionFile: historical.sessionFile, activity });
-		if (tab) await cleanupRunTab({ herdr, tabId: tab.tabId, runFile: join(run.recordDirectory, "run.json"), runRecord, signal, onError: onCleanupError });
-		throw error;
-	}
+	return resumeHistoricalTaskConcurrent(cwd, runId, taskNumber, prompt, options);
 }

package/packages/herdr-subagents/src/live-agent.ts

@@ -2,9 +2,8 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import type { HerdrAutomation } from "./herdr.ts";
-import type { HerdrSubagentsReport } from "./runner.ts";
-import { parseReport } from "./records.ts";
+import type { HerdrAgentState, HerdrAutomation } from "./herdr.ts";
+import { applyTaskRuntime, parseReport, readTaskRecord, type PersistedReport, type TaskRecord, type TaskRuntimeState } from "./records.ts";
 import { attemptReportPath, attemptStatePath, createAttemptId, type AttemptState } from "./attempts.ts";
 import { writeJsonAtomic } from "./state.ts";
 
@@ -64,11 +63,13 @@ export async function promptLiveAgent(options: {
 	start?: boolean;
 	stalledWarningMs?: number;
 	onStalled?: () => void;
-}): Promise<{ report: HerdrSubagentsReport; agentName: string; attemptId: string }> {
+	onRuntimeUpdate?: (task: TaskRecord) => void | Promise<void>;
+	attemptId?: string;
+}): Promise<{ report: PersistedReport; agentName: string; attemptId: string }> {
 	const taskDirectory = dirname(options.task.sessionFile);
 	const reportFile = join(taskDirectory, "report.json");
 	const taskFile = join(taskDirectory, "task.json");
-	const attemptId = createAttemptId();
+	const attemptId = options.attemptId ?? createAttemptId();
 	const attemptReportFile = attemptReportPath(taskDirectory, attemptId);
 	const attemptStateFile = attemptStatePath(taskDirectory, attemptId);
 	await Promise.all([mkdir(dirname(attemptReportFile), { recursive: true, mode: 0o700 }), mkdir(dirname(attemptStateFile), { recursive: true, mode: 0o700 })]);
@@ -85,39 +86,102 @@ export async function promptLiveAgent(options: {
 			signal: options.signal,
 		});
 	}
-	const stalledTimer = options.stalledWarningMs ? setTimeout(() => options.onStalled?.(), options.stalledWarningMs) : undefined;
+	const persistRuntime = async (state: TaskRuntimeState, diagnostic?: string) => {
+		const task = await readTaskRecord(taskFile);
+		if (task.currentAttemptId !== attemptId || (task.status !== "running" && task.status !== "starting")) return;
+		if (task.runtimeState === state && task.runtimeDiagnostic === diagnostic) return;
+		applyTaskRuntime(task, state, diagnostic);
+		await writeJsonAtomic(taskFile, task);
+		await options.onRuntimeUpdate?.(task);
+	};
+	const readAttemptState = async (): Promise<AttemptState | undefined> => {
+		if (!existsSync(attemptStateFile)) return undefined;
+		try {
+			const value = JSON.parse(await readFile(attemptStateFile, "utf8")) as { attemptId?: unknown; state?: unknown };
+			if (value.attemptId === attemptId && (value.state === "working" || value.state === "settled")) return value.state;
+		} catch { /* a concurrent atomic replacement will be retried */ }
+		return undefined;
+	};
+	const wait = () => new Promise<void>((resolve, reject) => {
+		const onAbort = () => {
+			clearTimeout(timer);
+			if (existsSync(attemptReportFile)) resolve();
+			else reject(options.signal?.reason ?? new Error("Subagent attempt aborted."));
+		};
+		const timer = setTimeout(() => { options.signal?.removeEventListener("abort", onAbort); resolve(); }, 100);
+		if (options.signal?.aborted) onAbort();
+		else options.signal?.addEventListener("abort", onAbort, { once: true });
+	});
+	const promptController = new AbortController();
+	const abortPrompt = () => promptController.abort(options.signal?.reason ?? new Error("Subagent prompt wait stopped."));
+	if (options.signal?.aborted) abortPrompt();
+	else options.signal?.addEventListener("abort", abortPrompt, { once: true });
+	const promptOutcome = options.herdr.promptAgent({ target: agentName, prompt: options.prompt, signal: promptController.signal })
+		.then((result) => ({ result }), (error: unknown) => ({ error }));
+	let promptSettled = false;
+	let promptStatus: HerdrAgentState | undefined;
 	let promptError: unknown;
-	try { await options.herdr.promptAgent({ target: agentName, prompt: options.prompt, signal: options.signal }); }
-	catch (error) { promptError = error; }
-	finally { if (stalledTimer) clearTimeout(stalledTimer); }
-	while (!existsSync(attemptReportFile)) {
-		let state: AttemptState | undefined;
-		if (existsSync(attemptStateFile)) {
-			try {
-				const value = JSON.parse(await readFile(attemptStateFile, "utf8")) as { attemptId?: unknown; state?: unknown };
-				if (value.attemptId === attemptId && (value.state === "working" || value.state === "settled")) state = value.state;
-			} catch { /* a concurrent atomic replacement will be retried */ }
-		}
-		if (state === "working") {
-			try {
-				if (!(await options.herdr.isTaskRunning(options.paneId, options.signal))) {
-					if (promptError) throw promptError;
-					throw new Error("Child Pi stopped while its authoritative attempt state was still working and did not submit a subagent_report.");
+	const promptSettlementWork = promptOutcome.then(async (outcome) => {
+		promptSettled = true;
+		if ("error" in outcome) {
+			promptError = outcome.error;
+			const detail = outcome.error instanceof Error ? outcome.error.message : String(outcome.error);
+			if (/agent_prompt_stalled|timed?\s*out|timeout/i.test(detail)) await persistRuntime("delivery_unknown", detail);
+			else if (/agent_blocked/i.test(detail)) await persistRuntime("waiting_interaction", "Herdr is waiting for an approval or interaction; no business input request has been reported.");
+		} else if (outcome.result.status === "working" || outcome.result.status === "blocked" || outcome.result.status === "idle" || outcome.result.status === "done") promptStatus = outcome.result.status;
+	});
+	const stalledTimer = options.stalledWarningMs ? setTimeout(() => options.onStalled?.(), options.stalledWarningMs) : undefined;
+	let terminalObservedAt: number | undefined;
+	let turnObserved = false;
+	try {
+		await persistRuntime("working");
+		while (!existsSync(attemptReportFile)) {
+			await Promise.resolve();
+			let agentState = promptStatus;
+			let observationDiagnostic: string | undefined;
+			try { agentState = await options.herdr.getAgentState(agentName, options.signal); }
+			catch (error) { observationDiagnostic = `Could not observe Herdr agent state: ${error instanceof Error ? error.message : String(error)}`; }
+			const attemptState = await readAttemptState();
+			if (agentState === "working" || agentState === "blocked" || attemptState === "working") turnObserved = true;
+			const promptDetail = promptError instanceof Error ? promptError.message : promptError === undefined ? "" : String(promptError);
+			if (agentState === "blocked" || /agent_blocked/i.test(promptDetail)) {
+				await persistRuntime("waiting_interaction", observationDiagnostic ?? "Herdr is waiting for an approval or interaction; no business input request has been reported.");
+				terminalObservedAt = undefined;
+			} else if (promptError && /agent_prompt_stalled|timed?\s*out|timeout/i.test(promptDetail)) {
+				await persistRuntime("delivery_unknown", observationDiagnostic ?? promptDetail);
+				let live = false;
+				try { live = await options.herdr.isTaskRunning(options.paneId, options.signal); } catch { live = true; }
+				if (attemptState !== "working" || !live) {
+					terminalObservedAt ??= Date.now();
+					if (Date.now() - terminalObservedAt >= 50) throw promptError;
+				}
+			} else if (promptError && promptSettled) {
+				terminalObservedAt ??= Date.now();
+				if (Date.now() - terminalObservedAt >= 50) throw promptError;
+			} else if ((promptSettled || turnObserved || attemptState === "settled") && (agentState === "idle" || agentState === "done" || attemptState === "settled")) {
+				if (attemptState === "working") {
+					let live = false;
+					try { live = await options.herdr.isTaskRunning(options.paneId, options.signal); } catch { live = true; }
+					if (!live) throw new Error("Child Pi stopped while its authoritative attempt state was still working and did not submit a subagent_report.");
+				}
+				terminalObservedAt ??= Date.now();
+				if (Date.now() - terminalObservedAt >= 50) throw new Error("Child Pi did not submit a subagent_report before settling.");
+			} else {
+				await persistRuntime("working", observationDiagnostic);
+				terminalObservedAt = undefined;
+				if (!observationDiagnostic && agentState === "unknown") {
+					let live = false;
+					try { live = await options.herdr.isTaskRunning(options.paneId, options.signal); } catch { live = true; }
+					if (!live) throw new Error("Child Pi stopped without submitting a subagent_report.");
 				}
-			} catch (error) {
-				if (error === promptError || (error instanceof Error && error.message.startsWith("Child Pi stopped while"))) throw error;
-				// A transient liveness query is not evidence that the child stopped.
 			}
-			await new Promise<void>((resolve, reject) => {
-				const onAbort = () => { clearTimeout(timer); reject(options.signal?.reason ?? new Error("Subagent attempt aborted.")); };
-				const timer = setTimeout(() => { options.signal?.removeEventListener("abort", onAbort); resolve(); }, 100);
-				if (options.signal?.aborted) onAbort();
-				else options.signal?.addEventListener("abort", onAbort, { once: true });
-			});
-			continue;
+			await wait();
 		}
-		if (promptError) throw promptError;
-		throw new Error(state === "settled" ? "Child Pi settled but did not submit a subagent_report." : "Child Pi stopped without an authoritative lifecycle state and did not submit a subagent_report.");
+	} finally {
+		if (stalledTimer) clearTimeout(stalledTimer);
+		promptController.abort(new Error("Authoritative subagent_report observed; stop waiting for prompt acknowledgement."));
+		await promptSettlementWork;
+		options.signal?.removeEventListener("abort", abortPrompt);
 	}
 	let value: unknown;
 	try { value = JSON.parse(await readFile(attemptReportFile, "utf8")); }
@@ -127,7 +191,7 @@ export async function promptLiveAgent(options: {
 		throw new Error("Child Pi submitted an invalid subagent_report.");
 	}
 	try {
-		const report = parseReport(value, "child subagent_report") as HerdrSubagentsReport;
+		const report = parseReport(value, "child subagent_report");
 		if (report.attemptId !== attemptId) throw new Error(`Report belongs to attempt '${report.attemptId ?? "unknown"}', expected '${attemptId}'.`);
 		await writeJsonAtomic(reportFile, report);
 		return { report, agentName, attemptId };

package/packages/herdr-subagents/src/parameters.ts

@@ -18,7 +18,7 @@ export const HerdrSubagentsParams = Type.Object({
 export const HerdrSubagentsControlParams = Type.Object({
 	action: StringEnum(["list", "status", "respond", "history", "resume", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
 	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by status, respond, resume, cancel, or cleanup." })),
-	answer: Type.Optional(Type.String({ minLength: 1, description: "Answer sent to a blocked task when action is respond." })),
-	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number selected for respond or resume." })),
+	answer: Type.Optional(Type.String({ minLength: 1, description: "Message sent to the selected blocked or failed task when action is respond." })),
+	task: Type.Optional(Type.Integer({ minimum: 1, description: "One-based task number. Always required for respond, and selects the task for resume." })),
 	prompt: Type.Optional(Type.String({ minLength: 1, description: "Follow-up prompt used by resume." })),
 }, { additionalProperties: false });

package/packages/herdr-subagents/src/protocol.ts

@@ -13,7 +13,9 @@ export function reportProtocolPrompt(systemPrompt: string, kind: ReportPromptKin
 		"",
 		"When this turn is finished, call subagent_report exactly once for this turn.",
 		"Put the complete final answer in result, a concise parent-facing paragraph in summary, and list any useful document paths.",
-		"Use status=needs-input with question when missing information prevents progress, or status=failed with an error when the task cannot be completed.",
+		"Use status=completed when the task is finished.",
+		"Use status=blocked with question when you have a specific question or decision the parent agent must answer before you can continue; the run stays open waiting for it.",
+		"Use status=failed with error when this task cannot be completed, so the run does not wait for an answer.",
 	].filter((line, index) => line || index > 1).join("\n").trim();
 }