@maxiaochao/pi-toolkit 0.10.1 → 0.10.2

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-08 - v0.10.2
+
+- bundle herdr-subagents v0.3.0: split execution and control tools and unify task runs
+- Bundle the Herdr Subagents execution/control tool split and unified non-empty `tasks` input for single and multi-task runs.
+
 ## 2026-10-08 - v0.10.1
 
 - bundle herdr-subagents v0.2.1: add default thinking configuration and inline Herdr workflow video

package/global/AGENTS.md

@@ -4,71 +4,54 @@ Behavioral guidelines to reduce common LLM coding mistakes. Project-specific ins
 
 ## 1. Think Before Coding
 
-**Surface tradeoffs. Name confusion instead of resolving it silently.**
+- Surface material assumptions, interpretations, and tradeoffs.
+- If unresolved ambiguity would materially change the result, ask. When no human is reachable, choose a defensible interpretation, state it, and proceed with verifiable criteria.
+- Prefer the simpler approach. Name conflicting requirements rather than silently compromising between them.
 
-- State your material assumptions explicitly.
-- If multiple interpretations exist, present them rather than picking one silently.
-- If a simpler approach exists, say so. Push back when warranted.
-- If requirements conflict (durability vs latency, correctness vs speed), name the conflict explicitly. Never average conflicting requirements into something that satisfies neither.
-- When unresolved ambiguity would materially change the result, ask. When no human is reachable (headless, async, subagent), choose the interpretation you can defend, state it as an assumption, and proceed under Rule 4.
+## 2. Minimal Solution
 
-## 2. Simplicity First
+Understand the problem and relevant code flow before choosing the first rung that works:
 
-**YAGNI cuts what you don't need; KISS keeps what remains simple.**
+1. Skip functionality that is speculative or was not requested.
+2. Reuse an existing project abstraction when it encodes the required semantics.
+3. Otherwise use the standard library or a native platform feature.
+4. Otherwise use a direct dependency already declared by the project.
+5. Only then write the minimum custom code that works.
 
-- Build what was asked, for the callers that exist today.
-- Introduce an abstraction after repeated use reveals a stable concept.
+- Introduce abstractions only after repeated use reveals a stable concept.
+- Prefer boring, focused code; review long or deeply nested functions for splitting.
+- Never simplify away explicit requirements, trust-boundary validation, data-loss protection, security, or accessibility.
 - For states excluded by enforced invariants, fail visibly instead of inventing fallback behavior.
-- Each function you write does one thing. If it runs past a couple of screens or nests past three levels, review whether splitting it improves clarity.
+- State the ceiling and upgrade trigger of any deliberate simplification that cuts a real corner.
 
-## 3. Surgical Changes
+## 3. Skill Boundaries
 
-**Touch only what you must. Clean up only your own mess.**
+After loading a skill, treat its documented interface as sufficient for normal use. Do not inspect the skill's implementation, installed executable, or package source unless the user asks to review, debug, or modify it; its documented behavior conflicts with observed behavior; or required usage details are missing from the skill.
 
-The test: every changed line traces to the user's request, or to a defect that request reveals.
+## 4. Read, Then Change Surgically
 
-- Match existing style, even if you'd do it differently.
-- Remove imports, variables, and functions that YOUR changes made unused. Leave pre-existing dead code in place and mention it.
+Before editing, read the affected public API and its immediate callers. For a bug, find every statically discoverable caller and relevant implementation.
 
-When fixing a bug, fix the root cause, not the symptom. Find where the defect actually lives:
-- Find every statically discoverable caller and relevant implementation; a report names a symptom, and patching only the path the ticket mentions leaves sibling callers still broken.
-- If the shared function is wrong, fix it once - do not scatter per-caller guards. Name the sibling callers the fix now affects.
-- If one caller is wrong, fix that caller - do not add defensive handling to a correct shared function.
+Every changed line traces to the user's request or to a defect that request reveals.
 
-## 4. Goal-Driven Execution
+- Match existing style.
+- Remove imports, variables, and functions that your changes make unused. Leave pre-existing dead code in place and mention it.
+- Fix a faulty shared function once and name affected sibling callers; if only one caller is wrong, fix that caller instead of guarding a correct shared function.
 
-**Define success criteria. Loop until verified.**
+## 5. Goal-Driven Execution
 
-Transform tasks into verifiable goals:
-- "Add validation" -> "Write tests for invalid inputs, then make them pass"
-- "Fix the bug" -> "Write a test that reproduces it, then make it pass"
-- "Refactor X" -> "Ensure tests pass before and after"
-- "Make X fast" -> "Write and test a simple reference implementation, then optimize against its results"
+- Turn work into checkable outcomes: reproduce bugs before fixing them, preserve behavior during refactors, and optimize against a tested reference implementation.
+- For multi-step or materially ambiguous work, state a brief plan and give every step its own verification.
+- Leave the smallest relevant runnable check for new or changed non-trivial logic. Do not introduce a test framework solely for that check.
 
-For multi-step or materially ambiguous tasks, state a brief plan where every step carries its own check:
-1. [Step] -> verify: [check]
+## 6. Fail Visibly
 
-Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
-
-## 5. Read Before You Write
-
-**Understand adjacent code before changing it. "Looks orthogonal" is a dangerous assumption.**
-
-Before changing a file:
-- Read the file's exports and public API.
-- Read the immediate callers of the function you're modifying.
-
-## 6. Fail Visibly, Not Silently
-
-**Silent skips are failures.**
-
-- "Completed" is wrong if anything was silently skipped.
+- "Completed" is wrong if anything required was silently skipped.
 - "Tests pass" is wrong if any required test was skipped or not run.
-- If a required input, file, or tool is missing (or a step is impossible under the stated constraints), do NOT fabricate it to make a check pass. Report what is missing and what you need.
+- If a required input, file, or tool is missing, or a step is impossible under the stated constraints, report what is missing and what you need. Never fabricate it to make a check pass.
+
+## 7. Worktree Isolation
 
-## 7. Reuse Before Writing
+For a Git-repository task that coordinates substantial changes across multiple files or modules, or implements a feature intended for release, ask before editing whether to isolate it in a worktree. Skip the question when already in a linked worktree.
 
-**Before writing new code, check in order:**
-1. Reuse an existing project abstraction when it encodes project semantics. (If it is itself the bug, fix it once - see Rule 3.)
-2. Otherwise use the standard library or a direct dependency already declared by the project.
-3. Only then write it yourself.
+If the user agrees, read the `pi-worktree` skill and establish the worktree before changing code. When no human is reachable, create a worktree only when the task explicitly requests one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "description": "Personal pi coding agent toolkit: /todos, /btw, /cache_export and apply_patch extensions, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2026-10-08 - v0.3.0
+
+- split execution and control tools and unify task runs
+- Split execution and control into `herdr_subagents` and `herdr_subagents_control`; require a non-empty `tasks` array for new runs so one-item runs and batches share background and concurrency semantics.
+- Normalize legacy top-level single-task prompts into one-item task arrays before schema validation.
+
 ## 2026-10-08 - v0.2.1
 
 - add default thinking configuration and inline Herdr workflow video

package/packages/herdr-subagents/README.md

@@ -29,7 +29,7 @@ pi update npm:@maxiaochao/pi-herdr-subagents
 
 The full `@maxiaochao/pi-toolkit` package also bundles this extension. Install the full toolkit or this standalone child package, not both.
 
-Inside a Herdr workspace, the package registers `herdr_subagents` and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers neither, so the tool is absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
+Inside a Herdr workspace, the package registers `herdr_subagents`, `herdr_subagents_control`, and `/herdr-subagents`. Outside Herdr (or without a workspace ID), the extension registers none of them, so these capabilities are absent from the model context. Start Pi inside Herdr or reload the extension there to enable them.
 
 The design replaces hidden print-mode subprocesses with ordinary interactive Pi Agents managed through Herdr, so delegated work stays visible, inspectable, resumable, and durably recorded.
 
@@ -38,16 +38,17 @@ The design replaces hidden print-mode subprocesses with ordinary interactive Pi
 Discover the effective personas first:
 
 ```text
-herdr_subagents({ action: "list" })
+herdr_subagents_control({ action: "list" })
 ```
 
 Then run one self-contained task:
 
 ```text
 herdr_subagents({
-  agent: "worker",
   label: "auth-review",
-  prompt: "Inspect the authentication flow and summarize the risks"
+  tasks: [
+    { name: "auth", agent: "worker", prompt: "Inspect the authentication flow and summarize the risks" }
+  ]
 })
 ```
 
@@ -64,21 +65,21 @@ herdr_subagents({
 })
 ```
 
-Set `background: true` to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
+`tasks` is always a non-empty array: one item is a single task and multiple items form a batch. Set `background: true` for either form to return a stable run ID immediately while the queue continues. One run is dispatched at a time by an extension instance; later runs remain queued and start FIFO. Each background run sends one compact parent notification only when the whole run completes, partially fails, fails, or blocks. Individual successful tasks do not wake the parent model.
 
-A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the same tool to continue the original session:
+A child missing required information reports `needs-input` with an exact question. The run becomes blocked, keeps its Herdr tab, pane, partial report, and Pi session, and returns control to the parent. Answer through the control tool to continue the original session:
 
 ```text
-herdr_subagents({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
+herdr_subagents_control({ action: "respond", runId: "<run-id>", answer: "Use the main branch." })
 ```
 
 While a batch is active, its task rows stay below the editor. With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
 
 ## History
 
-Run `/herdr-subagents history` or `herdr_subagents({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
+Run `/herdr-subagents history` or `herdr_subagents_control({ action: "history" })` to list compact project-local run and task reports after Herdr tabs close. Full results, described documents, artifacts, and persistent Pi sessions remain separate on disk and are not loaded into parent context.
 
-Continue a saved conversation in a new Herdr tab with `herdr_subagents({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
+Continue a saved conversation in a new Herdr tab with `herdr_subagents_control({ action: "resume", runId: "<run-id>", task: 1, prompt: "Follow up..." })`. Remove only a selected archive with `herdr_subagents_control({ action: "cleanup", runId: "<run-id>" })`. History has no automatic count-based eviction. The extension adds the runtime path to local Git excludes when available (and otherwise uses `.pi/.gitignore`) without overwriting unrelated rules.
 
 Read-only tasks start FIFO up to the configured concurrency limit. A pane is created only when its task starts, belongs exclusively to that task, and is never reused. Completed panes remain inspectable while another task in the batch is unsettled. Results remain in input order, and one failed task does not cancel its siblings. Any batch containing a write-capable persona is forced to concurrency one.
 
@@ -250,9 +251,9 @@ Override the model for one task:
 
 ```text
 herdr_subagents({
-  agent: "reviewer",
-  model: "anthropic/claude-opus-4-1:high",
-  prompt: "Review the authorization boundary"
+  tasks: [
+    { name: "authorization", agent: "reviewer", model: "anthropic/claude-opus-4-1:high", prompt: "Review the authorization boundary" }
+  ]
 })
 ```
 

package/packages/herdr-subagents/TESTING.md

@@ -16,10 +16,10 @@
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
-- Verify the flat public contract and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
 - Verify blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
 - Verify resumed batches retain newly allocated pane IDs and historical follow-ups exclude simultaneous session writers.
 
 ## Latest baseline
 
-All 136 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 137 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

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> {
@@ -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.1",
+  "version": "0.3.0",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [

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");
 	}
 }

package/packages/herdr-subagents/tests/run-tests.mjs

@@ -15,7 +15,7 @@ import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcil
 import { continueQueuedRun } from "../src/continue-run.ts";
 import { CliHerdrAutomation } from "../src/herdr.ts";
 import { fleetEditorHasFocus, FleetSelection, fleetLines } from "../src/fleet.ts";
-import { HERDR_ACTIONS, validateToolParams } from "../src/validation.ts";
+import { HERDR_ACTIONS, validateControlParams, validateRunParams } from "../src/validation.ts";
 import { resultPathForAttempt } from "../src/result-path.ts";
 import { isSettledRunStatus, readTaskRecord } from "../src/records.ts";
 import { RunPaneAllocator } from "../src/run-pane-allocator.ts";
@@ -136,22 +136,18 @@ function latestRunDirectory() {
 }
 
 try {
-	check("flat mode validation accepts supported calls", [
+	check("run validation accepts one or more tasks", validateRunParams({ tasks: [{ name: "one", prompt: "do it" }], concurrency: 2, background: true }) === undefined);
+	check("control validation accepts supported calls", [
 		{ action: "list" }, { action: "history" }, { action: "cleanup", runId: "run" },
 		{ action: "respond", runId: "run", answer: "yes", task: 1 },
 		{ action: "resume", runId: "run", task: 1, prompt: "continue" },
-		{ prompt: "one task", agent: "worker", label: "one", model: "fake/model" },
-		{ tasks: [{ name: "one", prompt: "do it" }], concurrency: 2, background: true },
-	].every((params) => validateToolParams(params) === undefined));
+	].every((params) => validateControlParams(params) === undefined));
 	check("all supported actions have shared validation and rendering metadata", ["list", "history", "cleanup", "respond", "resume"].every((action) => action in HERDR_ACTIONS));
-	check("flat mode validation rejects ambiguous and extraneous fields", [
-		validateToolParams({ prompt: "one", tasks: [{ name: "two", prompt: "two" }] }),
-		validateToolParams({ action: "list", prompt: "not allowed" }),
-		validateToolParams({ action: "respond", runId: "run" }),
-		validateToolParams({ tasks: [{ name: "one", prompt: "one" }], agent: "worker" }),
-		validateToolParams({ prompt: "one", runId: "run" }),
-		validateToolParams({ prompt: "one", task: 1 }),
-		validateToolParams({ tasks: [{ name: "one", prompt: "one" }], answer: "extra" }),
+	check("split validation rejects missing tasks and invalid control fields", [
+		validateRunParams({ tasks: [] }),
+		validateControlParams({ action: "list", prompt: "not allowed" }),
+		validateControlParams({ action: "respond", runId: "run" }),
+		validateControlParams({ action: "resume", runId: "run", task: 1 }),
 	].every((message) => typeof message === "string" && message.length > 0));
 	const fleet = new FleetSelection();
 	const fleetBatch = { label: "reviews", activity: [
@@ -554,7 +550,7 @@ try {
 	const historyHerdr = fakeHerdr();
 	const historicalResume = await executeHerdrSubagents({ action: "resume", runId: backgroundId, task: 1, prompt: "follow up" }, undefined, undefined, { cwd: root, model: { provider: "fake", id: "model" } }, { agentsDirectory: join(process.cwd(), "agents"), herdr: historyHerdr });
 	const historyStartRequest = historyHerdr.calls.find(([name]) => name === "startAgent")[1];
-	check("historical resume preserves the saved Pi session and persona prompt", !historicalResume.isError && historyHerdr.calls[0][0] === "createTab" && historyStartRequest.args.includes(stableHistory.tasks[0].sessionFile) && historyStartRequest.args.includes("fake/model") && historyStartRequest.args.some((value) => String(value).includes("subagent_report")) && existsSync(join(stableHistory.tasks[0].recordDirectory, "turns", "02.json")) && readFileSync(join(stableHistory.tasks[0].recordDirectory, "followup-system-prompt.md"), "utf8").includes("Investigate the assigned question without modifying files"));
+	check("historical resume preserves the saved Pi session and persona prompt", !historicalResume.isError && historyHerdr.calls[0][0] === "createTab" && historyStartRequest.args.includes(stableHistory.tasks[0].sessionFile) && historyStartRequest.args.includes(stableHistory.tasks[0].model) && historyStartRequest.args.some((value) => String(value).includes("subagent_report")) && existsSync(join(stableHistory.tasks[0].recordDirectory, "turns", "02.json")) && readFileSync(join(stableHistory.tasks[0].recordDirectory, "followup-system-prompt.md"), "utf8").includes("Investigate the assigned question without modifying files"));
 	const historicalTaskRecord = JSON.parse(readFileSync(join(stableHistory.tasks[0].recordDirectory, "task.json"), "utf8"));
 	const historicalTurnRecord = JSON.parse(readFileSync(join(stableHistory.tasks[0].recordDirectory, "turns", "02.json"), "utf8"));
 	check("historical task and turn retain their tab identity", historicalTaskRecord.tabId === historicalResume.details.tabId && historicalTurnRecord.tabId === historicalResume.details.tabId);