@maxiaochao/pi-toolkit 0.11.6 → 0.11.7

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

@@ -2,9 +2,9 @@ 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 { 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 type { HerdrAutomation } from "./herdr.ts";
+import { parseReport, type PersistedReport, type TaskRecord } from "./records.ts";
+import { attemptReportPath, attemptStatePath, createAttemptId } from "./attempts.ts";
 import { writeJsonAtomic } from "./state.ts";
 
 export interface LiveTaskRecord {
@@ -33,14 +33,11 @@ export function childEnvironment(taskDirectory: string, environment: NodeJS.Proc
 
 export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): string[] {
 	const args = [
-		"--approve",
-		"--session", task.sessionFile,
+		"--approve", "--session", task.sessionFile,
 		"--name", `Subagent: ${task.name ?? task.agent ?? "worker"}`,
-		"--no-extensions",
-		"--extension", "builtin:codemode",
+		"--no-extensions", "--extension", "builtin:codemode",
 		"--extension", fileURLToPath(new URL("../extensions/subagent-report.ts", import.meta.url)),
-		"--no-skills",
-		"--append-system-prompt", systemPromptFile,
+		"--no-skills", "--append-system-prompt", systemPromptFile,
 	];
 	for (const extension of task.extensions ?? []) args.push("--extension", extension);
 	if (task.model) args.push("--model", task.model);
@@ -51,8 +48,17 @@ export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): str
 	return args;
 }
 
-export function liveAgentName(taskId: string, attempt = 1): string {
-	return `herdr-subagent-${taskId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 12)}-${attempt}`;
+export function liveAgentName(taskId: string, _attempt = 1): string {
+	return `herdr-subagent-${taskId.replace(/[^a-zA-Z0-9]/g, "").slice(0, 12)}`;
+}
+
+async function pause(signal?: AbortSignal): Promise<void> {
+	await new Promise<void>((resolve, reject) => {
+		const onAbort = () => { clearTimeout(timer); reject(signal?.reason ?? new Error("Subagent wait aborted.")); };
+		const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, 250);
+		if (signal?.aborted) onAbort();
+		else signal?.addEventListener("abort", onAbort, { once: true });
+	});
 }
 
 export async function promptLiveAgent(options: {
@@ -75,121 +81,52 @@ export async function promptLiveAgent(options: {
 	const taskFile = join(taskDirectory, "task.json");
 	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 })]);
+	await Promise.all([
+		mkdir(dirname(attemptReportFile), { recursive: true, mode: 0o700 }),
+		mkdir(dirname(attemptStatePath(taskDirectory, attemptId)), { recursive: true, mode: 0o700 }),
+	]);
 	const durableTask = JSON.parse(await readFile(taskFile, "utf8")) as Record<string, unknown>;
 	durableTask.currentAttemptId = attemptId;
 	await writeJsonAtomic(taskFile, durableTask);
-	const agentName = options.agentName ?? liveAgentName(options.task.id, options.attempt);
-	if (options.start !== false) {
-		await options.herdr.startAgent({
-			name: agentName,
-			kind: "pi",
-			paneId: options.paneId,
-			args: childPiArgs(options.task, options.systemPromptFile),
-			signal: options.signal,
-		});
-	}
-	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 agentName = options.agentName ?? liveAgentName(options.task.id);
+	if (options.start !== false) await options.herdr.startAgent({
+		name: agentName, kind: "pi", paneId: options.paneId,
+		args: childPiArgs(options.task, options.systemPromptFile), signal: options.signal,
 	});
+	// Delivery is attempted exactly once. Its acknowledgement is not a lifecycle
+	// signal: Pi can recover from a transport/provider error in the same process.
 	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;
-	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 promptSignal = options.signal ? AbortSignal.any([options.signal, promptController.signal]) : promptController.signal;
+	const prompt = options.herdr.promptAgent({ target: agentName, prompt: options.prompt, signal: promptSignal }).catch(() => undefined);
 	const stalledTimer = options.stalledWarningMs ? setTimeout(() => options.onStalled?.(), options.stalledWarningMs) : undefined;
-	let terminalObservedAt: number | undefined;
 	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();
-			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 || 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.");
-				}
+		while (true) {
+			if (existsSync(attemptReportFile)) break;
+			if (options.signal?.aborted) {
+				if (existsSync(attemptReportFile)) break;
+				throw options.signal.reason ?? new Error("Subagent attempt aborted.");
 			}
-			await wait();
+			let alive = true;
+			try { alive = await options.herdr.isTaskRunning(options.paneId, options.signal); }
+			catch { /* an observation failure is not a child failure */ }
+			if (!alive) {
+				// The child publishes by atomic rename before it exits. Reconcile disk once;
+				// there is no timing-based drain and no semantic use of idle/done.
+				if (existsSync(attemptReportFile)) break;
+				throw new Error("Child Pi exited without submitting a subagent_report.");
+			}
+			if (options.herdr.waitForAgentChange) await options.herdr.waitForAgentChange(agentName, options.signal).catch(() => undefined);
+			else await pause(options.signal);
 		}
 	} 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);
+		promptController.abort(new Error("Task lifecycle settled; stop waiting for prompt acknowledgement."));
 	}
+	await prompt;
 	let value: unknown;
 	try { value = JSON.parse(await readFile(attemptReportFile, "utf8")); }
 	catch {
 		await rename(attemptReportFile, `${reportFile}.invalid-${Date.now()}`).catch(() => undefined);
-		if (promptError) throw new Error(`${promptError instanceof Error ? promptError.message : String(promptError)}; Child Pi also submitted an invalid subagent_report.`);
 		throw new Error("Child Pi submitted an invalid subagent_report.");
 	}
 	try {
@@ -197,10 +134,8 @@ export async function promptLiveAgent(options: {
 		if (report.attemptId !== attemptId) throw new Error(`Report belongs to attempt '${report.attemptId ?? "unknown"}', expected '${attemptId}'.`);
 		await writeJsonAtomic(reportFile, report);
 		return { report, agentName, attemptId };
-	}
-	catch (error) {
+	} catch (error) {
 		await rename(attemptReportFile, `${reportFile}.invalid-${Date.now()}`).catch(() => undefined);
-		const detail = `Child Pi submitted an invalid subagent_report: ${error instanceof Error ? error.message : String(error)}`;
-		throw new Error(promptError ? `${promptError instanceof Error ? promptError.message : String(promptError)}; ${detail}` : detail);
+		throw new Error(`Child Pi submitted an invalid subagent_report: ${error instanceof Error ? error.message : String(error)}`);
 	}
 }

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

@@ -12,13 +12,9 @@ export const HerdrSubagentsParams = Type.Object({
 	tasks: Type.Array(HerdrSubagentsTaskParams, { minItems: 1, description: "Ordered tasks to execute. Use one item for a single task; independent read-only tasks may run concurrently." }),
 	label: Type.Optional(Type.String({ minLength: 1, maxLength: 48, description: "Short Herdr run-tab label." })),
 	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneously active Agents. Write-capable tasks force concurrency one." })),
-	background: Type.Optional(Type.Boolean({ description: "Return a run ID immediately while the run continues in this parent session." })),
 }, { additionalProperties: false });
 
 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: "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." })),
+	action: StringEnum(["list", "status", "history", "cancel", "cleanup"] as const, { description: "Control operation to perform." }),
+	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by status, cancel, or cleanup." })),
 }, { additionalProperties: false });

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

@@ -1,4 +1,4 @@
-export type ReportPromptKind = "initial" | "resumed" | "followup";
+export type ReportPromptKind = "initial" | "resumed" | "followup"; // legacy kinds remain readable
 
 const TURN_INTRO: Record<ReportPromptKind, string> = {
 	initial: "",
@@ -11,11 +11,10 @@ export function reportProtocolPrompt(systemPrompt: string, kind: ReportPromptKin
 		TURN_INTRO[kind],
 		systemPrompt.trim(),
 		"",
-		"When this turn is finished, call subagent_report exactly once for this turn.",
+		"Before this process exits, call subagent_report exactly once with a terminal result.",
 		"Put the complete final answer in result, a concise parent-facing paragraph in summary, and list any useful document paths.",
-		"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.",
+		"Use status=completed when the task is finished, or status=failed with error when it cannot be completed.",
+		"Do not pause for parent input; make a reasonable assumption or report failed with the missing requirement.",
 	].filter((line, index) => line || index > 1).join("\n").trim();
 }
 

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

@@ -252,6 +252,8 @@ export function applyLifecycleStatus<T extends { status: string; question?: stri
 }
 
 export function applyTaskStatus<T extends TaskRecord | TurnRecord>(record: T, status: TaskStatus, options: { question?: string; error?: string; at?: string } = {}): T {
+	const terminal = record.status === "completed" || record.status === "failed" || record.status === "cancelled";
+	if (terminal && record.status !== status) throw new Error(`Task is already terminal (${record.status}); terminal tasks are immutable.`);
 	const at = options.at ?? new Date().toISOString();
 	if ("order" in record) {
 		if (record.status === "running" && status !== "running") {

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

@@ -1,12 +1,10 @@
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
 import { loadSubagentConfiguration, type ConfigurationPaths, type SubagentConfiguration } from "./config.ts";
 import { runHerdrSubagentsBatch, type BatchResult, type BatchTask } from "./batch-runner.ts";
-import { respondToBlockedTask } from "./blocking.ts";
-import { cleanSubagentRun, historyText, listSubagentHistory, resumeHistoricalTask } from "./history.ts";
+import { cleanSubagentRun, historyText, listSubagentHistory } from "./history.ts";
 import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./validation.ts";
 import type { OwnerIdentity } from "./ownership.ts";
 import { cancelActiveSubagentRuns } from "./reconcile.ts";
-import { cancelQueuedRuns, loadQueuedRuns } from "./queued-runs.ts";
 import { getSubagentRunStatus, runStatusText } from "./status.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
@@ -15,28 +13,20 @@ export interface HerdrSubagentsRunParams {
 	tasks: HerdrSubagentsTaskParams[];
 	label?: string;
 	concurrency?: number;
-	background?: boolean;
 }
 
 export interface HerdrSubagentsControlToolParams {
-	action: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
+	action: "list" | "status" | "history" | "cancel" | "cleanup";
 	runId?: string;
-	answer?: string;
-	task?: number;
-	prompt?: string;
 }
 
 /** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
-	action?: "list" | "status" | "respond" | "history" | "resume" | "cancel" | "cleanup";
-	prompt?: string;
+	action?: "list" | "status" | "history" | "cancel" | "cleanup";
 	label?: string;
 	tasks?: HerdrSubagentsTaskParams[];
 	concurrency?: number;
-	background?: boolean;
 	runId?: string;
-	answer?: string;
-	task?: number;
 }
 
 export interface HerdrSubagentsToolContext {
@@ -51,7 +41,7 @@ export interface HerdrSubagentsToolDependencies {
 	configurationPaths?: ConfigurationPaths;
 	owner?: OwnerIdentity;
 	runId?: string;
-	cancelRun?: (runId: string) => Promise<{ cancelled: boolean; queued?: boolean; cleanupErrors?: string[] }>;
+	cancelRun?: (runId: string) => Promise<{ cancelled: boolean; cleanupErrors?: string[] }>;
 }
 
 export type HerdrSubagentsBatchDetails = BatchResult & { prompts: string[] };
@@ -127,51 +117,20 @@ const actionHandlers = {
 		const requestedRunId = (params.runId as string).trim();
 		try {
 			const runId = (await getSubagentRunStatus(ctx.cwd, requestedRunId))?.runId ?? requestedRunId;
-			let result: { cancelled: boolean; queued?: boolean; cleanupErrors?: string[] };
+			let result: { cancelled: boolean; cleanupErrors?: string[] };
 			if (dependencies.cancelRun) result = await dependencies.cancelRun(runId);
 			else {
 				const reason = "Subagent run cancelled by user.";
-				const queued = (await loadQueuedRuns(ctx.cwd)).some((run) => run.runId === runId);
-				if (queued) {
-					await cancelQueuedRuns(ctx.cwd, [runId], { reason, owner: dependencies.owner });
-					result = { cancelled: true, queued: true };
-				} else {
-					const cancellation = await cancelActiveSubagentRuns(ctx.cwd, dependencies.herdr ?? new CliHerdrAutomation(), { reason, owner: dependencies.owner, runId });
-					result = { cancelled: cancellation.cancelledRuns > 0, cleanupErrors: cancellation.cleanupErrors };
-				}
+				const cancellation = await cancelActiveSubagentRuns(ctx.cwd, dependencies.herdr ?? new CliHerdrAutomation(), { reason, owner: dependencies.owner, runId });
+				result = { cancelled: cancellation.cancelledRuns > 0, cleanupErrors: cancellation.cleanupErrors };
 			}
 			const suffix = result.cleanupErrors?.length ? ` Cleanup warnings: ${result.cleanupErrors.join("; ")}` : "";
-			const text = result.cancelled ? `Cancelled Subagent run ${runId}.${suffix}` : `Subagent run '${runId}' is not active or queued.`;
+			const text = result.cancelled ? `Cancelled Subagent run ${runId}.${suffix}` : `Subagent run '${runId}' is not active.`;
 			return { content: [{ type: "text", text }], details: { action: "cancel", runId, ...result }, ...(result.cancelled ? {} : { isError: true }) };
 		} catch (error) {
 			return errorResponse(error instanceof Error ? error.message : String(error), { action: "cancel", runId: requestedRunId, cancelled: false });
 		}
 	},
-	async resume({ params, signal, onUpdate, ctx, dependencies, discovery }: ToolExecutionContext) {
-		try {
-			const result = await resumeHistoricalTask(ctx.cwd, params.runId as string, params.task as number, (params.prompt as string).trim(), {
-				herdr: dependencies.herdr, signal, owner: dependencies.owner, stalledWarningSeconds: discovery.settings.stalledWarningSeconds,
-				onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: partial }),
-				onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "resume", runId: params.runId, stalled: true } }),
-				onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "resume", runId: params.runId, cleanupError: text } }),
-			});
-			return { content: [{ type: "text", text: result.summary }], details: result, ...(result.status === "failed" || result.status === "cancelled" ? { isError: true } : {}) };
-		} catch (error) { return errorResponse(error instanceof Error ? error.message : String(error)); }
-	},
-	async respond({ params, signal, onUpdate, ctx, dependencies }: ToolExecutionContext) {
-		try {
-			const result = await respondToBlockedTask(ctx.cwd, (params.runId as string).trim(), (params.answer as string).trim(), {
-				herdr: dependencies.herdr, taskNumber: params.task as number, signal, owner: dependencies.owner,
-				onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: partial }),
-				onStalled: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, stalled: true } }),
-				onWarning: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, warning: text } }),
-				onCleanupError: (text) => onUpdate?.({ content: [{ type: "text", text }], details: { action: "respond", runId: params.runId, cleanupError: text } }),
-			});
-			const blockedControl = result.status === "blocked" ? { allowedActions: ["respond", "cancel"] as const } : {};
-			const text = [result.summary, ...(result.question ? [`Question: ${result.question}`] : []), ...(result.status === "blocked" ? [`Run ID: ${result.runId}`, `Answer with herdr_subagents_control({ action: "respond", runId: "${result.runId}", answer: "..." }) or cancel this run.`] : []), ...result.documents.map((document) => `${document.description}: ${document.path}`)].join("\n");
-			return { content: [{ type: "text", text }], details: { ...result, ...blockedControl }, ...(result.status === "failed" || result.status === "partial" || result.status === "cancelled" ? { isError: true } : {}) };
-		} catch (error) { return errorResponse(error instanceof Error ? error.message : String(error)); }
-	},
 	async list({ discovery }: ToolExecutionContext) {
 		return { content: [{ type: "text", text: listText(discovery) }], details: { action: "list", agents: discovery.personas, diagnostics: discovery.diagnostics, settings: discovery.settings } };
 	},
@@ -201,10 +160,9 @@ async function executeBatch({ params, signal, onUpdate, ctx, dependencies, disco
 			onUpdate: (partial) => onUpdate?.({ content: [{ type: "text", text: partial.summary }], details: { ...partial, prompts: tasks.map((task) => task.prompt) } }),
 		});
 		const lines = [result.summary, ...result.tasks.map((task) => `- ${task.name}: ${task.status} — ${task.summary}`)];
-		if (result.status === "blocked") lines.push("", `Run ID: ${result.runId}`, `Answer with herdr_subagents_control({ action: "respond", runId: "${result.runId}", answer: "..." }) or cancel this run before starting another foreground run.`);
 		if (result.documents.length) lines.push("", "Documents:", ...result.documents.map((document) => `- ${document.description}: ${document.path}`));
 		const isError = result.status === "failed" || result.status === "partial" || result.status === "cancelled";
-		return { content: [{ type: "text", text: lines.join("\n") }], details: { ...result, prompts: tasks.map((task) => task.prompt), ...(result.status === "blocked" ? { allowedActions: ["respond", "cancel"] } : {}) }, ...(isError ? { isError: true } : {}) };
+		return { content: [{ type: "text", text: lines.join("\n") }], details: { ...result, prompts: tasks.map((task) => task.prompt) }, ...(isError ? { isError: true } : {}) };
 	} catch (error) {
 		const text = error instanceof Error ? error.message : String(error);
 		const diagnostic = error as { recordDirectory?: string; runId?: string };

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

@@ -6,8 +6,6 @@ export const HERDR_ACTIONS = {
 	status: { allowed: ["action", "runId"], includeRunId: true },
 	cancel: { allowed: ["action", "runId"], includeRunId: true },
 	cleanup: { allowed: ["action", "runId"], includeRunId: true },
-	respond: { allowed: ["action", "runId", "answer", "task"], includeRunId: true },
-	resume: { allowed: ["action", "runId", "task", "prompt"], includeRunId: true },
 } as const satisfies Record<string, { allowed: readonly (keyof HerdrSubagentsControlToolParams)[]; includeRunId: boolean }>;
 
 export function validateRunParams(params: HerdrSubagentsRunParams): string | undefined {
@@ -21,7 +19,5 @@ export function validateControlParams(params: HerdrSubagentsControlToolParams):
 	const extra = Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsControlToolParams));
 	if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
 	if ((params.action === "status" || params.action === "cancel" || params.action === "cleanup") && !params.runId?.trim()) return `runId is required for action '${params.action}'.`;
-	if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim() || !params.task)) return "runId, answer, and task are required for action 'respond'.";
-	if (params.action === "resume" && (!params.runId?.trim() || !params.task || !params.prompt?.trim())) return "runId, task, and prompt are required for action 'resume'.";
 	return undefined;
 }

package/packages/herdr-subagents/tests/core-state-machine.mjs

@@ -0,0 +1,178 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { runHerdrSubagentsBatch } from "../src/batch-runner.ts";
+import registerSubagentReport from "../extensions/subagent-report.ts";
+import { applyTaskStatus } from "../src/records.ts";
+
+process.env.HERDR_ENV = "1";
+process.env.HERDR_WORKSPACE_ID = "test-workspace";
+
+const root = mkdtempSync(join(tmpdir(), "herdr-state-machine-"));
+
+function task(name, prompt, access = "read") {
+	return { name, prompt, agent: "worker", access, skills: [], systemPrompt: "Finish the delegated task." };
+}
+
+function fakeHerdr() {
+	let pane = 0;
+	let active = 0;
+	let maxActive = 0;
+	const alive = new Map();
+	const starts = [];
+	const paneDirectories = new Map();
+	const agents = new Map();
+	const publish = (directory, report) => {
+		const record = JSON.parse(readFileSync(join(directory, "task.json"), "utf8"));
+		const path = join(directory, "reports", `${record.currentAttemptId}.json`);
+		mkdirSync(dirname(path), { recursive: true });
+		writeFileSync(path, JSON.stringify({ attemptId: record.currentAttemptId, documents: [], reportedAt: new Date().toISOString(), ...report }));
+	};
+	return {
+		get maxActive() { return maxActive; },
+		starts,
+		async createTab(request) {
+			pane += 1;
+			const paneId = `pane-${pane}`;
+			paneDirectories.set(paneId, request.env.PI_HERDR_SUBAGENTS_TASK_DIR);
+			return { tabId: "tab-1", paneId };
+		},
+		async splitPane(request) {
+			pane += 1;
+			const paneId = `pane-${pane}`;
+			paneDirectories.set(paneId, request.env.PI_HERDR_SUBAGENTS_TASK_DIR);
+			return { paneId };
+		},
+		async startAgent(request) {
+			const session = request.args[request.args.indexOf("--session") + 1];
+			const directory = dirname(session);
+			assert.equal(paneDirectories.get(request.paneId), directory);
+			assert.equal(request.args.includes("--print"), false);
+			alive.set(request.paneId, true);
+			agents.set(request.name, { paneId: request.paneId, directory });
+		},
+		async promptAgent(request) {
+			const { paneId, directory } = agents.get(request.target);
+			starts.push(request.prompt);
+			active += 1;
+			maxActive = Math.max(maxActive, active);
+			if (request.prompt.includes("transport retry")) {
+				setTimeout(() => {
+					publish(directory, { status: "completed", summary: `${request.prompt} result` });
+					alive.set(paneId, false);
+					active -= 1;
+				}, 35);
+				throw new Error("WebSocket closed 1000");
+			}
+			await new Promise((resolve) => setTimeout(resolve, request.prompt.includes("slow") ? 35 : 10));
+			if (!request.prompt.includes("omit report")) publish(directory, {
+				status: request.prompt.includes("fail") ? "failed" : "completed",
+				summary: `${request.prompt} result`,
+				...(request.prompt.includes("fail") ? { error: "expected failure" } : {}),
+			});
+			alive.set(paneId, false);
+			active -= 1;
+			return { status: "done" };
+		},
+		async getAgentState() { return "unknown"; },
+		async waitForAgentChange() { await new Promise((resolve) => setTimeout(resolve, 5)); },
+		async isTaskRunning(paneId) { return alive.get(paneId) === true; },
+		async renamePane() {}, async renameTab() {}, async focusPane() {},
+		async isTabFocused() { return false; }, async waitForTabUnfocused() {},
+		async paneExists() { return true; }, async closeTab() {},
+	};
+}
+
+async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
+	const result = await runHerdrSubagentsBatch(tasks, {
+		label: "state-machine-test", concurrency, maxConcurrency: 4, cwd: root, herdr, signal,
+	});
+	return { result, herdr };
+}
+
+{
+	const { result, herdr } = await run([task("one", "first slow"), task("two", "second")], 1);
+	assert.equal(result.status, "completed");
+	assert.equal(herdr.maxActive, 1);
+	assert.deepEqual(herdr.starts, ["first slow", "second"]);
+	assert.deepEqual(result.tasks.map((entry) => entry.status), ["completed", "completed"]);
+}
+
+{
+	const { result, herdr } = await run([task("one", "one slow"), task("two", "two slow"), task("three", "three")], 2);
+	assert.equal(result.status, "completed");
+	assert.equal(herdr.maxActive, 2);
+	assert.deepEqual(result.tasks.map((entry) => entry.index), [0, 1, 2]);
+}
+
+{
+	const { result } = await run([task("retry", "retry slow")], 1);
+	assert.equal(result.status, "completed");
+	assert.equal(result.tasks[0].summary, "retry slow result");
+}
+
+
+{
+	const { result } = await run([task("retry", "transport retry")], 1);
+	assert.equal(result.status, "completed");
+	assert.equal(result.tasks[0].summary, "transport retry result");
+}
+
+{
+	const { result } = await run([task("missing", "omit report")], 1);
+	assert.equal(result.status, "failed");
+	assert.match(result.tasks[0].error, /exited without submitting/);
+}
+
+{
+	const { result } = await run([task("bad", "fail"), task("good", "still run")], 2);
+	assert.equal(result.status, "partial");
+	assert.deepEqual(result.tasks.map((entry) => entry.status), ["failed", "completed"]);
+}
+
+{
+	const { result } = await run([task("bad-one", "fail one"), task("bad-two", "fail two")], 2);
+	assert.equal(result.status, "failed");
+	assert.deepEqual(result.tasks.map((entry) => entry.status), ["failed", "failed"]);
+}
+
+{
+	const controller = new AbortController();
+	setTimeout(() => controller.abort(new Error("test cancellation")), 8);
+	const { result } = await run([task("active", "slow active"), task("queued", "queued")], 1, fakeHerdr(), controller.signal);
+	assert.equal(result.status, "cancelled");
+	assert.deepEqual(result.activity.map((entry) => entry.status), ["cancelled", "cancelled"]);
+}
+
+await assert.rejects(() => run([task("writer", "edit", "write"), task("reader", "read")], 2), /require concurrency 1/);
+
+const terminal = { id: "task", runId: "run", order: 1, status: "completed" };
+assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are immutable/);
+
+{
+	const directory = join(root, "report-idempotency");
+	mkdirSync(directory, { recursive: true });
+	const attemptId = "11111111-1111-4111-8111-111111111111";
+	writeFileSync(join(directory, "task.json"), JSON.stringify({ id: "task", runId: "run", order: 1, status: "running", currentAttemptId: attemptId }));
+	const handlers = new Map();
+	let reportTool;
+	registerSubagentReport({
+		registerTool(tool) { reportTool = tool; },
+		registerCommand() {}, registerShortcut() {},
+		on(name, handler) { handlers.set(name, handler); },
+		events: { on() {} },
+		async exec() { return { code: 0, stdout: "", stderr: "", killed: false }; },
+	});
+	process.env.PI_HERDR_SUBAGENTS_TASK_DIR = directory;
+	await handlers.get("before_agent_start")?.();
+	const report = { status: "completed", summary: "done", result: "full result", documents: [] };
+	await reportTool.execute("first", report);
+	await reportTool.execute("duplicate", report);
+	await assert.rejects(() => reportTool.execute("conflict", { ...report, summary: "different" }), /Conflicting subagent_report/);
+	const persisted = JSON.parse(readFileSync(join(directory, "reports", `${attemptId}.json`), "utf8"));
+	assert.equal(persisted.summary, "done");
+	delete process.env.PI_HERDR_SUBAGENTS_TASK_DIR;
+}
+
+console.log("PASS core Herdr state machine");

package/packages/herdr-subagents/tests/extension-sources-load.mjs

@@ -37,16 +37,20 @@ try {
 			});
 		}`);
 	const args = childPiArgs({ id: "probe", sessionFile: join(root, "session.jsonl"), tools: ["read"], extensions: [fileExtension, "./local package", probe] }, join(root, "system.md"));
+	// `builtin:codemode` is translated by `herdr agent start` and is covered by
+	// the real-Herdr smoke test. Direct Pi has no portable form of that alias.
+	const codemode = args.indexOf("builtin:codemode");
+	args.splice(codemode - 1, 2);
 	writeFileSync(join(root, "system.md"), "Extension source loading probe.");
 	const env = { ...process.env, PI_CODING_AGENT_DIR: join(root, "agent"), PI_HERDR_SUBAGENTS_CHILD: "1" };
 	for (const key of Object.keys(env)) if (key.startsWith("HERDR_") || key === "PI_HERDR_SUBAGENTS_TASK_DIR" || key === "PI_HERDR_SUBAGENTS_PARENT_PANE_ID") delete env[key];
-	const result = spawnSync(process.env.PI_TEST_BINARY?.trim() || "pi", [...args, "--offline", "--no-mcp"], { cwd: root, env, encoding: "utf8", timeout: 30_000 });
+	const result = spawnSync(process.env.PI_TEST_BINARY?.trim() || "pi", [...args, "--offline"], { cwd: root, env, encoding: "utf8", timeout: 30_000 });
 	assert.equal(result.error, undefined, String(result.error));
 	assert.equal(result.status, 0, result.stderr || result.stdout);
 	const loaded = JSON.parse(readFileSync(resultPath, "utf8"));
 	for (const command of ["file-extension", "package-extension", "skill:package-skill", "package-prompt", "parent"]) assert.ok(loaded.commands.includes(command), `Missing ${command}: ${JSON.stringify(loaded)}`);
-	assert.deepEqual([...loaded.tools].sort(), ["codemode", "read", "subagent_report"]);
-	console.log("PASS real Pi loads explicit file and package sources, including package skills/prompts despite discovery flags, without broadening the tool allowlist");
+	assert.deepEqual([...loaded.tools].sort(), ["read", "subagent_report"]);
+	console.log("PASS real Pi loads explicit file and package sources, including package skills/prompts despite discovery flags, without broadening the direct-Pi tool allowlist");
 } finally {
 	rmSync(root, { recursive: true, force: true });
 }