@maxiaochao/pi-toolkit 0.10.0 → 0.10.2

package/packages/herdr-subagents/extensions/herdr-subagents.ts

@@ -9,8 +9,8 @@ import { RunDispatcher } from "../src/dispatcher.ts";
 import { historyText, listSubagentHistory } from "../src/history.ts";
 import { cancelQueuedRuns, loadQueuedRuns, persistQueuedRun, removeQueuedRun } from "../src/queued-runs.ts";
 import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcile.ts";
-import { executeHerdrSubagents, type HerdrSubagentsBatchDetails, type HerdrSubagentsDetails, type HerdrSubagentsToolParams } from "../src/tool.ts";
-import { HerdrSubagentsParams } from "../src/parameters.ts";
+import { executeHerdrSubagents, executeHerdrSubagentsControl, type HerdrSubagentsBatchDetails, type HerdrSubagentsControlToolParams, type HerdrSubagentsDetails, type HerdrSubagentsRunParams } from "../src/tool.ts";
+import { HerdrSubagentsControlParams, HerdrSubagentsParams } from "../src/parameters.ts";
 import { HERDR_ACTIONS } from "../src/validation.ts";
 import { FleetController } from "../src/fleet-controller.ts";
 import { isSettledRunStatus } from "../src/records.ts";
@@ -25,18 +25,32 @@ function statusVisual(status: string): { color: "success" | "warning" | "error"
 	return { color: "error", glyph: "✗" };
 }
 
-function renderToolCall(args: HerdrSubagentsToolParams, theme: Theme): Text {
-	if (args.action) {
-		const action = HERDR_ACTIONS[args.action];
-		const runId = action.includeRunId ? ` ${theme.fg("muted", String(args.runId ?? ""))}` : "";
-		return new Text(`${theme.fg("toolTitle", theme.bold(`herdr_subagents ${args.action}`))}${runId}`, 0, 0);
-	}
-	if (args.tasks) return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", `${args.tasks.length} tasks`)}${theme.fg("muted", ` · concurrency ${args.concurrency ?? "default"}`)}`, 0, 0);
-	const agent = args.agent || "worker";
-	const label = args.label ? ` · ${String(args.label)}` : "";
-	const prompt = args.prompt ? String(args.prompt).replace(/\s+/g, " ") : "...";
-	const preview = prompt.length > 80 ? `${prompt.slice(0, 80)}...` : prompt;
-	return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", agent)}${theme.fg("muted", label)}\n  ${theme.fg("dim", preview)}`, 0, 0);
+function renderToolCall(args: HerdrSubagentsRunParams, theme: Theme): Text {
+	return new Text(`${theme.fg("toolTitle", theme.bold("herdr_subagents"))} ${theme.fg("accent", `${args.tasks.length} task${args.tasks.length === 1 ? "" : "s"}`)}${theme.fg("muted", ` · concurrency ${args.concurrency ?? "default"}`)}`, 0, 0);
+}
+
+function renderControlToolCall(args: HerdrSubagentsControlToolParams, theme: Theme): Text {
+	const action = HERDR_ACTIONS[args.action];
+	const runId = action.includeRunId ? ` ${theme.fg("muted", String(args.runId ?? ""))}` : "";
+	return new Text(`${theme.fg("toolTitle", theme.bold(`herdr_subagents_control ${args.action}`))}${runId}`, 0, 0);
+}
+
+export function normalizeHerdrSubagentsArguments(args: unknown): HerdrSubagentsRunParams {
+	if (!args || typeof args !== "object") return args as HerdrSubagentsRunParams;
+	const legacy = args as Record<string, unknown>;
+	if (Array.isArray(legacy.tasks) || typeof legacy.prompt !== "string" || legacy.action !== undefined) return args as HerdrSubagentsRunParams;
+	if (Object.keys(legacy).some((key) => !["prompt", "agent", "label", "model", "background"].includes(key))) return args as HerdrSubagentsRunParams;
+	const label = typeof legacy.label === "string" ? legacy.label : undefined;
+	return {
+		tasks: [{
+			name: label || "task",
+			prompt: legacy.prompt,
+			...(typeof legacy.agent === "string" ? { agent: legacy.agent } : {}),
+			...(typeof legacy.model === "string" ? { model: legacy.model } : {}),
+		}],
+		...(label ? { label } : {}),
+		...(typeof legacy.background === "boolean" ? { background: legacy.background } : {}),
+	};
 }
 
 function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRenderResultOptions, theme: Theme): Container | Text {
@@ -49,20 +63,20 @@ function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRender
 		return container;
 	}
 	const details = result.details as HerdrSubagentsDetails | undefined;
-	if (!details?.agent) {
-		const content = result.content[0];
-		return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
-	}
-	const container = new Container();
-	container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(statusVisual(details.status).color, details.status)}`, 0, 0));
-	container.addChild(new Text(details.summary, 0, 0));
-	if (details.documents.length > 0) {
-		container.addChild(new Spacer(1));
-		for (const document of details.documents) container.addChild(new Text(theme.fg("muted", `${document.description}: ${document.path}`), 0, 0));
+	if (details?.agent) {
+		const container = new Container();
+		container.addChild(new Text(`${theme.fg("toolTitle", theme.bold(details.agent))} ${theme.fg(statusVisual(details.status).color, details.status)}`, 0, 0));
+		container.addChild(new Text(details.summary, 0, 0));
+		if (details.documents.length > 0) {
+			container.addChild(new Spacer(1));
+			for (const document of details.documents) container.addChild(new Text(theme.fg("muted", `${document.description}: ${document.path}`), 0, 0));
+		}
+		if (details.recordDirectory) container.addChild(new Text(theme.fg("dim", `Record: ${details.recordDirectory}`), 0, 0));
+		if (details.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
+		return container;
 	}
-	if (details.recordDirectory) container.addChild(new Text(theme.fg("dim", `Record: ${details.recordDirectory}`), 0, 0));
-	if (details.errorMessage) container.addChild(new Text(theme.fg("error", `Error: ${details.errorMessage}`), 0, 0));
-	return container;
+	const content = result.content[0];
+	return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
 }
 
 async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fleet: FleetController): Promise<void> {
@@ -92,7 +106,7 @@ async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fl
 	}
 	if (section === "settings") {
 		const settings = configuration.settings;
-		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, defaultModel: settings.defaultModel };
+		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, defaultModel: settings.defaultModel, defaultThinking: settings.defaultThinking };
 		const lines = Object.entries(values).map(([key, value]) => `${key}=${String(value ?? "unset")} (${configuration.settingSources[key] ?? "built-in"})`);
 		if (configuration.diagnostics.length) lines.push("Diagnostics:", ...configuration.diagnostics);
 		ctx.ui.notify(lines.join("\n"), "info");
@@ -104,6 +118,7 @@ async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fl
 export interface HerdrSubagentsExtensionDependencies {
 	herdr?: HerdrAutomation;
 	execute?: typeof executeHerdrSubagents;
+	executeControl?: typeof executeHerdrSubagentsControl;
 	isEditor?: (value: unknown) => boolean;
 	createFleetWidget?: (lines: string[]) => Container;
 }
@@ -139,6 +154,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	if (process.env.PI_HERDR_SUBAGENTS_CHILD === "1" || process.env.HERDR_ENV !== "1" || !process.env.HERDR_WORKSPACE_ID) return;
 	const herdr = dependencies.herdr ?? new CliHerdrAutomation();
 	const execute = dependencies.execute ?? executeHerdrSubagents;
+	const executeControl = dependencies.executeControl ?? executeHerdrSubagentsControl;
 	const isEditorComponent = dependencies.isEditor ?? ((value: unknown) => value instanceof Editor);
 	const dispatcher = new RunDispatcher();
 	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget);
@@ -177,17 +193,17 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerTool({
 		name: "herdr_subagents",
 		label: "Herdr Subagents",
-		description: "Run one focused task or an ordered bounded-concurrency batch in visible interactive Herdr Pi Agents. Foreground calls block while workers run concurrently; background batches return a run ID immediately and publish completion later. Complete results and Pi sessions stay in project-local records.",
+		description: "Run one or more ordered tasks in visible interactive Herdr Pi Agents. Use one tasks item for a single task. Independent read-only tasks may run concurrently; write-capable runs are serialized. Foreground calls block, while background calls return a run ID immediately. Complete results and Pi sessions stay in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
-		promptGuidelines: ["Call action=list once before the first execution. Submit one prompt or an ordered tasks list; use concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
+		promptGuidelines: ["Call herdr_subagents_control with action=list once before the first execution. Submit an ordered tasks list; use one item for a single task and concurrency only for independent read-only tasks. Foreground calls block until the run settles; background calls return a run ID immediately."],
 		parameters: HerdrSubagentsParams,
+		prepareArguments: normalizeHerdrSubagentsArguments,
 
-		async execute(_toolCallId, params: HerdrSubagentsToolParams, signal, onUpdate, ctx) {
+		async execute(_toolCallId, params: HerdrSubagentsRunParams, signal, onUpdate, ctx) {
 			const generation = sessionGeneration;
-			const runId = params.tasks ? randomUUID() : undefined;
-			const executionId = runId ?? params.runId ?? randomUUID();
+			const runId = randomUUID();
 			const controller = new AbortController();
-			runControllers.set(executionId, controller);
+			runControllers.set(runId, controller);
 			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(!params.background && signal ? [signal] : [])]);
 			const executeRun = async () => {
 				const result = await execute(params, runSignal, (update) => {
@@ -201,21 +217,6 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 				fleet.sync(result.details);
 				return result;
 			};
-			if (!params.tasks) {
-				const promise = executeRun();
-				inFlight.add(promise);
-				const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
-				if (params.action === "respond") {
-					const details = result.details as { runId?: string; status?: string };
-					if (details.status === "blocked") fleet.sync(result.details);
-					else if (isSettledRunStatus(details.status)) {
-						fleet.clearRun(params.runId);
-						if (params.runId) dispatcher.release(params.runId);
-					}
-				}
-				return result;
-			}
-			if (!runId) throw new Error("Batch run ID was not allocated.");
 			if (params.background) await persistQueuedRun(ctx.cwd, runId, params, { sessionId: ownerSessionId, processId: process.pid });
 			const promise = dispatcher.submit(runId, async () => {
 				const result = await executeRun().finally(async () => { if (params.background) await removeQueuedRun(ctx.cwd, runId); });
@@ -227,7 +228,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 				return result;
 			});
 			inFlight.add(promise);
-			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); }).catch(() => undefined);
+			void promise.finally(() => { inFlight.delete(promise); runControllers.delete(runId); }).catch(() => undefined);
 			if (params.background) {
 				void promise.then((result) => {
 					if (generation !== sessionGeneration) return;
@@ -248,6 +249,44 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 		renderResult: renderToolResult,
 	});
 
+	pi.registerTool({
+		name: "herdr_subagents_control",
+		label: "Herdr Subagents Control",
+		description: "Inspect Herdr personas and run history, answer a blocked task, resume a saved task, or remove a selected archived run. Use herdr_subagents to start new work.",
+		promptSnippet: "Inspect and control Herdr subagent runs",
+		parameters: HerdrSubagentsControlParams,
+
+		async execute(_toolCallId, params: HerdrSubagentsControlToolParams, signal, onUpdate, ctx) {
+			const executionId = params.runId ?? randomUUID();
+			const controller = new AbortController();
+			runControllers.set(executionId, controller);
+			const runSignal = AbortSignal.any([controller.signal, sessionController.signal, ...(signal ? [signal] : [])]);
+			const promise = executeControl(params, runSignal, (update) => {
+				const details = update.details as HerdrSubagentsBatchDetails | undefined;
+				if (details?.activity) fleet.sync(details);
+				const updateText = update.content.find((item) => item.type === "text")?.text;
+				const updateDetails = update.details as { warning?: string };
+				if (updateDetails.warning || updateText?.includes("cleanup failed")) ctx.ui.notify(updateDetails.warning ?? updateText ?? "Subagent warning", "warning");
+				onUpdate?.(update);
+			}, ctx, { agentsDirectory: packageAgentsDir, owner: { sessionId: ownerSessionId, processId: process.pid } });
+			inFlight.add(promise);
+			const result = await promise.finally(() => { inFlight.delete(promise); runControllers.delete(executionId); });
+			fleet.sync(result.details);
+			if (params.action === "respond") {
+				const details = result.details as { status?: string };
+				if (details.status === "blocked") fleet.sync(result.details);
+				else if (isSettledRunStatus(details.status)) {
+					fleet.clearRun(params.runId);
+					if (params.runId) dispatcher.release(params.runId);
+				}
+			}
+			return result;
+		},
+
+		renderCall: renderControlToolCall,
+		renderResult: renderToolResult,
+	});
+
 	pi.registerCommand("herdr-subagents", {
 		description: "Inspect effective subagent agents, models, and settings",
 		getArgumentCompletions: (prefix) => ["active", "history", "agents", "models", "settings", "focus "].filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

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

@@ -10,6 +10,7 @@ export interface SubagentConfig {
 	maxConcurrency: number;
 	stalledWarningSeconds: number;
 	defaultModel?: string;
+	defaultThinking?: string;
 	personas: Record<string, PersonaConfig>;
 }
 export interface EffectivePersona extends AgentDefinition {
@@ -33,6 +34,7 @@ interface ConfigFile {
 	maxConcurrency?: number;
 	stalledWarningSeconds?: number;
 	defaultModel?: string;
+	defaultThinking?: string;
 	personas?: Record<string, PersonaConfig>;
 }
 export interface ConfigurationPaths {
@@ -64,9 +66,11 @@ function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, so
 		result[key] = value as number;
 		sources[key] = source;
 	}
-	if (input.defaultModel !== undefined) {
-		if (typeof input.defaultModel === "string" && input.defaultModel.trim()) { result.defaultModel = input.defaultModel.trim(); sources.defaultModel = source; }
-		else diagnostics.push(`${source} defaultModel must be a non-empty string`);
+	for (const key of ["defaultModel", "defaultThinking"] as const) {
+		const value = input[key];
+		if (value === undefined) continue;
+		if (typeof value === "string" && value.trim()) { result[key] = value.trim(); sources[key] = source; }
+		else diagnostics.push(`${source} ${key} must be a non-empty string`);
 	}
 	if (input.personas !== undefined) {
 		if (!input.personas || typeof input.personas !== "object" || Array.isArray(input.personas)) diagnostics.push(`${source} personas must be an object`);
@@ -115,8 +119,8 @@ export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: s
 		const projectPersona = projectInput.personas?.[definition.name] ?? {};
 		const model = projectPersona.model ?? globalPersona.model ?? definition.model ?? settings.defaultModel ?? parentModel;
 		const modelSource = projectPersona.model ? "project persona" : globalPersona.model ? "global persona" : definition.model ? `${source} persona` : settings.defaultModel ? settingSources.defaultModel : parentModel ? "parent session" : "unresolved";
-		const thinking = projectPersona.thinking ?? globalPersona.thinking ?? definition.thinking;
-		const thinkingSource = projectPersona.thinking ? "project persona" : globalPersona.thinking ? "global persona" : definition.thinking ? `${source} persona` : "default";
+		const thinking = projectPersona.thinking ?? globalPersona.thinking ?? definition.thinking ?? settings.defaultThinking;
+		const thinkingSource = projectPersona.thinking ? "project persona" : globalPersona.thinking ? "global persona" : definition.thinking ? `${source} persona` : settings.defaultThinking ? settingSources.defaultThinking : "default";
 		const skills = projectPersona.skills ?? globalPersona.skills ?? definition.skills ?? [];
 		const skillsSource = projectPersona.skills ? "project persona" : globalPersona.skills ? "global persona" : definition.skills ? `${source} persona` : "none";
 		return { ...definition, source, access: definition.access ?? "write", model, modelSource, thinking, thinkingSource, skills, skillsSource };

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

@@ -1,21 +1,24 @@
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 
+const HerdrSubagentsTaskParams = Type.Object({
+	name: Type.String({ minLength: 1, maxLength: 48, description: "Short task name shown in the pane and task list." }),
+	prompt: Type.String({ minLength: 1, description: "Self-contained prompt for this task." }),
+	agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for this task. Defaults to worker." })),
+	model: Type.Optional(Type.String({ minLength: 1, description: "Optional model override for this task." })),
+}, { additionalProperties: false });
+
 export const HerdrSubagentsParams = Type.Object({
-	action: Type.Optional(StringEnum(["list", "respond", "history", "resume", "cleanup"] as const, { description: "Operation mode. Omit it to execute one task or a batch." })),
+	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", "respond", "history", "resume", "cleanup"] as const, { description: "Control operation to perform." }),
 	runId: Type.Optional(Type.String({ minLength: 1, description: "Durable run ID used by respond, resume, 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." })),
-	prompt: Type.Optional(Type.String({ minLength: 1, description: "Task prompt for single execution, or follow-up prompt for resume." })),
-	agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for single execution. Defaults to worker." })),
-	label: Type.Optional(Type.String({ minLength: 1, maxLength: 48, description: "Short Herdr run-tab label." })),
-	model: Type.Optional(Type.String({ minLength: 1, description: "Optional Pi model override, for example provider/model:high." })),
-	tasks: Type.Optional(Type.Array(Type.Object({
-		name: Type.String({ minLength: 1, maxLength: 48, description: "Short task name shown in the pane and task list." }),
-		prompt: Type.String({ minLength: 1, description: "Self-contained prompt for this task." }),
-		agent: Type.Optional(Type.String({ minLength: 1, description: "Persona for this task. Defaults to worker." })),
-		model: Type.Optional(Type.String({ minLength: 1, description: "Optional model override for this task." })),
-	}), { minItems: 1, description: "Ordered tasks for bounded-concurrency batch execution." })),
-	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneously active Agents in a batch." })),
-	background: Type.Optional(Type.Boolean({ description: "Return a run ID immediately while the batch continues in this parent session." })),
+	prompt: Type.Optional(Type.String({ minLength: 1, description: "Follow-up prompt used by resume." })),
 }, { additionalProperties: false });

package/packages/herdr-subagents/src/queued-runs.ts

@@ -1,15 +1,15 @@
 import { existsSync, readdirSync } from "node:fs";
 import { mkdir, readFile, rm } from "node:fs/promises";
 import { join } from "node:path";
-import type { HerdrSubagentsToolParams } from "./tool.ts";
+import type { HerdrSubagentsRunParams } from "./tool.ts";
 import { isProcessAlive, ownerRecord, type OwnerIdentity } from "./ownership.ts";
 import { writeJsonAtomic } from "./state.ts";
 import { findRunDirectory } from "./run-locator.ts";
 
-export interface QueuedRunRecord { runId: string; cwd: string; ownerSessionId?: string; ownerProcessId?: number; params: HerdrSubagentsToolParams; queuedAt: string; }
+export interface QueuedRunRecord { runId: string; cwd: string; ownerSessionId?: string; ownerProcessId?: number; params: HerdrSubagentsRunParams; queuedAt: string; }
 function queueDirectory(cwd: string): string { return join(cwd, ".pi", "herdr-subagents", "queue"); }
 
-export async function persistQueuedRun(cwd: string, runId: string, params: HerdrSubagentsToolParams, owner?: OwnerIdentity): Promise<void> {
+export async function persistQueuedRun(cwd: string, runId: string, params: HerdrSubagentsRunParams, owner?: OwnerIdentity): Promise<void> {
 	const directory = queueDirectory(cwd);
 	await mkdir(directory, { recursive: true, mode: 0o700 });
 	await writeJsonAtomic(join(directory, `${runId}.json`), { runId, cwd, ...ownerRecord(owner), params: { ...params, background: true }, queuedAt: new Date().toISOString() });

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

@@ -4,11 +4,27 @@ import { runHerdrSubagents, type HerdrSubagentsResult } from "./runner.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 { HERDR_ACTIONS, validateToolParams } from "./validation.ts";
+import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "./validation.ts";
 import type { OwnerIdentity } from "./ownership.ts";
 
 export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
 
+export interface HerdrSubagentsRunParams {
+	tasks: HerdrSubagentsTaskParams[];
+	label?: string;
+	concurrency?: number;
+	background?: boolean;
+}
+
+export interface HerdrSubagentsControlToolParams {
+	action: "list" | "respond" | "history" | "resume" | "cleanup";
+	runId?: string;
+	answer?: string;
+	task?: number;
+	prompt?: string;
+}
+
+/** Internal superset used by shared execution helpers. */
 export interface HerdrSubagentsToolParams {
 	action?: "list" | "respond" | "history" | "resume" | "cleanup";
 	prompt?: string;
@@ -201,17 +217,34 @@ async function executeSingle({ params, signal, onUpdate, ctx, dependencies, disc
 }
 
 export async function executeHerdrSubagents(
-	params: HerdrSubagentsToolParams,
+	params: HerdrSubagentsRunParams | HerdrSubagentsToolParams,
 	signal: AbortSignal | undefined,
 	onUpdate: ((response: ToolResponse) => void) | undefined,
 	ctx: HerdrSubagentsToolContext,
 	dependencies: HerdrSubagentsToolDependencies,
 ): Promise<ToolResponse> {
-	const validationError = validateToolParams(params);
+	if (params.action) return executeHerdrSubagentsControl(params as HerdrSubagentsControlToolParams, signal, onUpdate, ctx, dependencies);
+	if (params.prompt && !params.tasks) {
+		const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
+		return executeSingle({ params, signal, onUpdate, ctx, dependencies, discovery });
+	}
+	const runParams = params as HerdrSubagentsRunParams;
+	const validationError = validateRunParams(runParams);
 	if (validationError) return { content: [{ type: "text", text: validationError }], details: { errorMessage: validationError }, isError: true };
 	const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
-	const execution = { params, signal, onUpdate, ctx, dependencies, discovery };
-	if (params.action) return actionHandlers[params.action](execution);
+	const execution = { params: runParams, signal, onUpdate, ctx, dependencies, discovery };
+	return executeBatch(execution);
+}
 
-	return params.tasks ? executeBatch(execution) : executeSingle(execution);
+export async function executeHerdrSubagentsControl(
+	params: HerdrSubagentsControlToolParams,
+	signal: AbortSignal | undefined,
+	onUpdate: ((response: ToolResponse) => void) | undefined,
+	ctx: HerdrSubagentsToolContext,
+	dependencies: HerdrSubagentsToolDependencies,
+): Promise<ToolResponse> {
+	const validationError = validateControlParams(params);
+	if (validationError) return { content: [{ type: "text", text: validationError }], details: { errorMessage: validationError }, isError: true };
+	const discovery = loadSubagentConfiguration(ctx.cwd, dependencies.agentsDirectory, modelId(ctx), dependencies.configurationPaths);
+	return actionHandlers[params.action]({ params, signal, onUpdate, ctx, dependencies, discovery });
 }

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

@@ -1,6 +1,4 @@
-import type { HerdrSubagentsToolParams } from "./tool.ts";
-
-const executionFields = ["prompt", "agent", "label", "model", "tasks", "concurrency", "background"] as const;
+import type { HerdrSubagentsControlToolParams, HerdrSubagentsRunParams } from "./tool.ts";
 
 export const HERDR_ACTIONS = {
 	list: { allowed: ["action"], includeRunId: false },
@@ -8,31 +6,20 @@ export const HERDR_ACTIONS = {
 	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 HerdrSubagentsToolParams)[]; includeRunId: boolean }>;
+} as const satisfies Record<string, { allowed: readonly (keyof HerdrSubagentsControlToolParams)[]; includeRunId: boolean }>;
+
+export function validateRunParams(params: HerdrSubagentsRunParams): string | undefined {
+	if (!params.tasks?.length) return "Provide a non-empty tasks list.";
+	return undefined;
+}
 
-export function validateToolParams(params: HerdrSubagentsToolParams): string | undefined {
-	const present = (key: keyof HerdrSubagentsToolParams) => params[key] !== undefined;
-	const extraField = (allowed: readonly (keyof HerdrSubagentsToolParams)[]) => Object.keys(params).find((key) => !allowed.includes(key as keyof HerdrSubagentsToolParams));
-	if (params.action) {
-		const extra = extraField(HERDR_ACTIONS[params.action].allowed);
-		if (extra) return `Field '${extra}' is not valid with action '${params.action}'.`;
-		if (params.action === "cleanup" && !params.runId?.trim()) return "runId is required for action 'cleanup'.";
-		if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer 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;
-	}
-	if (params.prompt && params.tasks) return "Provide either prompt or tasks, not both.";
-	if (params.prompt) {
-		const extra = extraField(["prompt", "agent", "label", "model"]);
-		if (extra) return `Field '${extra}' is not valid for single-task execution.`;
-		return undefined;
-	}
-	if (params.tasks) {
-		if (!params.tasks.length) return "tasks must contain at least one task.";
-		const extra = extraField(["tasks", "label", "concurrency", "background"]);
-		if (extra) return `Field '${extra}' is not valid for batch execution.`;
-		return undefined;
-	}
-	const supplied = executionFields.find((key) => present(key));
-	return supplied ? `Field '${supplied}' requires prompt or tasks.` : "Provide an action, prompt, or non-empty tasks list.";
+export function validateControlParams(params: HerdrSubagentsControlToolParams): string | undefined {
+	const allowed = HERDR_ACTIONS[params.action]?.allowed;
+	if (!allowed) return "Provide a valid control action.";
+	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 === "cleanup" && !params.runId?.trim()) return "runId is required for action 'cleanup'.";
+	if (params.action === "respond" && (!params.runId?.trim() || !params.answer?.trim())) return "runId and answer 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/extension-contract.ts

@@ -9,6 +9,7 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 	const handlers = new Map<string, (...args: any[]) => any>();
 	const commands: string[] = [];
 	let tool: Record<string, any> | undefined;
+	let controlTool: Record<string, any> | undefined;
 	let terminalInput: ((data: string) => { consume?: boolean } | undefined) | undefined;
 	let widgetCalls = 0;
 	let renderedLines: string[] = [];
@@ -26,13 +27,17 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 	};
 	const pi = {
 		on(name: string, handler: (...args: any[]) => any) { handlers.set(name, handler); },
-		registerTool(definition: Record<string, any>) { tool = definition; },
+		registerTool(definition: Record<string, any>) {
+			if (definition.name === "herdr_subagents") tool = definition;
+			if (definition.name === "herdr_subagents_control") controlTool = definition;
+		},
 		registerCommand(name: string) { commands.push(name); },
 		sendMessage() {},
 	};
 	registerHerdrSubagents(pi as never, {
 		herdr: { async focusPane(paneId: string) { focusedPanes.push(paneId); } } as never,
 		execute: execute as never,
+		executeControl: execute as never,
 		isEditor: (value) => value === editor,
 		createFleetWidget(lines) { renderedLines = lines; return new Container(); },
 	});
@@ -40,6 +45,7 @@ function harness(execute: (...args: any[]) => Promise<any>) {
 		handlers,
 		commands,
 		get tool() { return tool; },
+		get controlTool() { return controlTool; },
 		get terminalInput() { return terminalInput; },
 		get widgetCalls() { return widgetCalls; },
 		get renderedLines() { return renderedLines; },
@@ -73,7 +79,8 @@ async function verifyPublicUiWiring() {
 		if (!responding.tool) throw new Error("herdr_subagents was not registered for UI wiring test");
 		const renderedBlocked = responding.tool.renderResult({ content: [{ type: "text", text: "needs input" }], details: { agent: "explorer", status: "blocked", ok: false, summary: "Need input.", documents: [] } }, { isPartial: false }, { fg: (_color: string, text: string) => text, bold: (text: string) => text }).render(100).join("\n");
 		if (!renderedBlocked.includes("blocked") || renderedBlocked.includes("failed")) throw new Error("single-task blocked result did not render its authoritative status");
-		await responding.tool.execute("call", { action: "respond", runId: "blocked-run", answer: "main" }, undefined, undefined, { cwd, ui: responding.ui });
+		if (!responding.controlTool) throw new Error("herdr_subagents_control was not registered for UI wiring test");
+		await responding.controlTool.execute("call", { action: "respond", runId: "blocked-run", answer: "main" }, undefined, undefined, { cwd, ui: responding.ui });
 		if (!responding.renderedLines.some((line) => line.includes("second") && line.includes("blocked"))) throw new Error("blocked response did not refresh Fleet rows");
 		if (!responding.terminalInput?.("\u001b[B")?.consume || !responding.terminalInput?.("\u001b[B")?.consume || !responding.terminalInput?.("\r")?.consume) throw new Error("Fleet terminal input was not consumed while selecting");
 		await new Promise((resolve) => setTimeout(resolve, 0));
@@ -167,7 +174,7 @@ try {
 	if (inactiveHerdr.tool || inactiveHerdr.commands.length || inactiveHerdr.handlers.size) throw new Error("Subagents registered with HERDR_ENV=0");
 	process.env.HERDR_ENV = "1";
 	const inside = harness(async () => { throw new Error("unreachable"); });
-	if (!inside.tool || !inside.commands.includes("herdr-subagents") || !inside.handlers.has("session_start")) throw new Error("Subagents did not register inside Herdr");
+	if (!inside.tool || !inside.controlTool || !inside.commands.includes("herdr-subagents") || !inside.handlers.has("session_start")) throw new Error("Subagents did not register both tools inside Herdr");
 	process.env.PI_HERDR_SUBAGENTS_CHILD = "1";
 	const child = harness(async () => { throw new Error("unreachable"); });
 	if (child.tool || child.commands.length || child.handlers.size) throw new Error("Subagents registered inside a child Agent");
@@ -183,10 +190,10 @@ try {
 }
 
 export default function (_pi: ExtensionAPI) {
-	let tool: Record<string, any> | undefined;
+	const tools = new Map<string, Record<string, any>>();
 	const pi = {
 		on() {},
-		registerTool(definition: Record<string, any>) { tool = definition; },
+		registerTool(definition: Record<string, any>) { tools.set(definition.name, definition); },
 		registerCommand() {},
 		sendMessage() {},
 	};
@@ -207,19 +214,30 @@ export default function (_pi: ExtensionAPI) {
 		if (previousChild === undefined) delete process.env.PI_HERDR_SUBAGENTS_CHILD;
 		else process.env.PI_HERDR_SUBAGENTS_CHILD = previousChild;
 	}
-	if (!tool) throw new Error("herdr_subagents was not registered");
+	const tool = tools.get("herdr_subagents");
+	const controlTool = tools.get("herdr_subagents_control");
+	if (!tool || !controlTool) throw new Error("Herdr execution and control tools were not both registered");
 	const schema = tool.parameters as Record<string, any>;
 	if (schema.type !== "object" || schema.anyOf || schema.oneOf) throw new Error("herdr_subagents parameters must be one flat object schema");
-	const required = ["action", "runId", "answer", "task", "prompt", "agent", "label", "model", "tasks", "concurrency", "background"];
-	for (const name of required) {
+	for (const name of ["tasks", "label", "concurrency", "background"]) {
 		if (!schema.properties?.[name]) throw new Error(`schema is missing property '${name}'`);
 		if (!schema.properties[name].description) throw new Error(`schema property '${name}' has no description`);
 	}
+	if (!schema.required?.includes("tasks")) throw new Error("herdr_subagents tasks must be required");
+	const normalized = tool.prepareArguments?.({ prompt: "inspect", agent: "explorer", label: "probe", background: true });
+	if (normalized?.tasks?.length !== 1 || normalized.tasks[0].name !== "probe" || normalized.tasks[0].prompt !== "inspect" || normalized.tasks[0].agent !== "explorer" || normalized.background !== true) {
+		throw new Error("legacy single-task arguments were not normalized into a one-item background run");
+	}
 	for (const name of ["name", "prompt", "agent", "model"]) {
 		const property = schema.properties.tasks.items.properties[name];
 		if (!property?.description) throw new Error(`nested task property '${name}' has no description`);
 	}
-	if (!/Foreground calls block/.test(tool.description) || !/background batches return a run ID immediately/.test(tool.description)) {
+	const controlSchema = controlTool.parameters as Record<string, any>;
+	for (const name of ["action", "runId", "answer", "task", "prompt"]) {
+		if (!controlSchema.properties?.[name]?.description) throw new Error(`control schema property '${name}' is missing or undocumented`);
+	}
+	if (!controlSchema.required?.includes("action")) throw new Error("herdr_subagents_control action must be required");
+	if (!/Foreground calls block/.test(tool.description) || !/background calls return a run ID immediately/.test(tool.description)) {
 		throw new Error("tool description does not distinguish foreground and background execution");
 	}
 }