@maxiaochao/pi-toolkit 0.11.22 → 0.12.0

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-15 - v0.12.0
+
+- herdr-subagents v0.6.0: require explicit task Personas and clarify concise tool descriptions
+- Require an explicit Herdr Subagents Persona for every new task, clarify concise tool descriptions, and identify tasks with conflicting write access in parallel requests.
+
 ## 2026-10-15 - v0.11.22
 
 - herdr-subagents v0.5.4: preserve configured model and authentication extensions in isolated real-Herdr smoke tests

package/README.md

@@ -39,7 +39,7 @@ Restart Pi after updating. `pi update --extensions` has the same effect when upd
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
-Herdr Subagents personas can opt into local extension files or npm/git Pi packages through `extensions`. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
+Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. Personas can opt into local extension files or npm/git Pi packages through `extensions`. This uses native Pi package semantics: package-provided skills, prompt templates, and themes may also load, and `--no-skills` does not exclude explicitly selected package skills. See the [extension-source contract](packages/herdr-subagents/README.md#explicit-extension-sources-and-pi-packages) for precedence, isolation, and examples. The [real Herdr smoke test](packages/herdr-subagents/TESTING.md) preserves the configured analyst model and explicit authentication extensions while isolating unrelated settings.
 
 Multiple standalone children may be installed together. `pi-openai-account-pool` may also be installed alongside the complete toolkit because the toolkit does not embed it. Every other child in the table above is embedded, so a second install exposes the same resource twice.
 

package/package.json

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

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-15 - v0.6.0
+
+- require explicit task Personas and clarify concise tool descriptions
+- Require an explicit Herdr Subagents Persona for every new task, clarify concise tool descriptions, and identify tasks with conflicting write access in parallel requests.
+
 ## 2026-10-15 - v0.5.4
 
 - preserve configured model and authentication extensions in isolated real-Herdr smoke tests

package/packages/herdr-subagents/README.md

@@ -26,7 +26,7 @@ The tools and command are registered only when Pi is running inside Herdr with a
 
 ## Execution contract
 
-`herdr_subagents` accepts an ordered, non-empty `tasks` array.
+`herdr_subagents` accepts an ordered, non-empty `tasks` array. Every task must explicitly set `agent`; there is no default Persona.
 
 - `concurrency: 1` runs tasks strictly in input order.
 - `concurrency: N` runs at most N read-only tasks at once.
@@ -110,7 +110,7 @@ Starts one ordered batch and waits until every task reaches a terminal state. It
 | `concurrency` | No | `defaultConcurrency` | Maximum number of simultaneously active read-only tasks. It is capped by `maxConcurrency`. |
 | `tasks[].name` | Yes | — | Short pane/task name, at most 48 characters. |
 | `tasks[].prompt` | Yes | — | Self-contained task instructions. |
-| `tasks[].agent` | No | `"worker"` | Effective Persona name. |
+| `tasks[].agent` | Yes | — | Effective Persona name; use control `list` to inspect available Personas. |
 | `tasks[].model` | No | Persona/default model | Model override for this task. |
 
 A batch containing a write-capable Persona must explicitly or effectively use `concurrency: 1`; an unsafe parallel request is rejected.

package/packages/herdr-subagents/TESTING.md

@@ -12,7 +12,9 @@ It verifies:
 - bounded read-only parallelism;
 - ordered results despite concurrent completion;
 - sibling continuation after failure and all-failed aggregation;
-- explicit rejection of parallel write-capable tasks;
+- required explicit Personas in the tool schema and execution, including legacy single-task argument normalization;
+- rejection of missing, blank, invalid, and unknown Personas before creating runs, while custom Personas remain supported;
+- explicit rejection of parallel write-capable tasks with the conflicting task, Persona, and corrective action;
 - waiting through a delayed authoritative report after a prompt transport error while the Pi process is alive;
 - explicit failure when the process exits without a report;
 - parent cancellation of running and queued tasks;

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

@@ -42,7 +42,7 @@ export function normalizeHerdrSubagentsArguments(args: unknown): HerdrSubagentsR
 		tasks: [{
 			name: label || "task",
 			prompt: legacy.prompt,
-			...(typeof legacy.agent === "string" ? { agent: legacy.agent } : {}),
+			agent: legacy.agent as string,
 			...(typeof legacy.model === "string" ? { model: legacy.model } : {}),
 		}],
 		...(label ? { label } : {}),
@@ -148,7 +148,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 		name: "herdr_subagents",
 		...(exposure ? { exposure } : {}),
 		label: "Herdr Subagents",
-		description: "Run one or more ordered tasks in visible, focusable Herdr Pi panes. concurrency 1 is strict serial execution; higher values form a bounded pool for read-only tasks. Write-capable tasks require concurrency 1. The call returns only after every task has one terminal completed, failed, or cancelled result. Complete results and Pi sessions stay in project-local records.",
+		description: "Run ordered tasks in visible Herdr Pi panes, with an explicit agent for each task. concurrency 1 is serial; higher values require read-only Personas. Returns after all tasks complete, fail, or cancel; full results and sessions remain in project-local records.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
 		parameters: HerdrSubagentsParams,
 		prepareArguments: normalizeHerdrSubagentsArguments,

package/packages/herdr-subagents/package.json

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

package/packages/herdr-subagents/src/batch-runner.ts

@@ -92,7 +92,8 @@ export async function runHerdrSubagentsBatch(tasks: BatchTask[], options: BatchO
 	const runId = options.runId ?? randomUUID();
 	const requestedConcurrency = Math.max(1, Math.floor(options.concurrency));
 	if (requestedConcurrency > 1 && tasks.some((task) => task.access === "write")) {
-		throw new Error("Write-capable tasks require concurrency 1; parallel writes are not safe.");
+		const writers = tasks.filter((task) => task.access === "write").map((task) => `${JSON.stringify(task.name)} (agent=${task.agent})`).join(", ");
+		throw new Error(`Write-capable tasks require concurrency 1: ${writers}. Use concurrency: 1, or select a read-only Persona for read-only work.`);
 	}
 	const effectiveConcurrency = Math.min(requestedConcurrency, options.maxConcurrency, tasks.length);
 	const runDirectory = join(options.cwd, ".pi", "herdr-subagents", "runs", `${timestamp().replace(/[-:.]/g, "").replace("Z", "Z-")}${runId.slice(0, 8)}`);

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

@@ -4,14 +4,14 @@ 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." })),
+	agent: Type.String({ minLength: 1, description: "Persona name, use control list for available Personas." }),
 	model: Type.Optional(Type.String({ minLength: 1, description: "Optional model override for this task." })),
 }, { additionalProperties: false });
 
 export const HerdrSubagentsParams = Type.Object({
 	tasks: Type.Array(HerdrSubagentsTaskParams, { minItems: 1, description: "Ordered tasks to execute. Use one item for a single task; independent read-only tasks may run concurrently." }),
 	label: Type.Optional(Type.String({ minLength: 1, maxLength: 48, description: "Short Herdr run-tab label." })),
-	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum simultaneously active Agents. Write-capable tasks force concurrency one." })),
+	concurrency: Type.Optional(Type.Integer({ minimum: 1, description: "Maximum active Agents. Values above 1 require read-only Personas; write-capable Personas require 1 or the batch is rejected." })),
 }, { additionalProperties: false });
 
 export const HerdrSubagentsControlParams = Type.Object({

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

@@ -7,7 +7,7 @@ import type { OwnerIdentity } from "./ownership.ts";
 import { cancelActiveSubagentRuns } from "./reconcile.ts";
 import { getSubagentRunStatus, runStatusText } from "./status.ts";
 
-export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent?: string; model?: string; }
+export interface HerdrSubagentsTaskParams { name: string; prompt: string; agent: string; model?: string; }
 
 export interface HerdrSubagentsRunParams {
 	tasks: HerdrSubagentsTaskParams[];
@@ -140,7 +140,7 @@ async function executeBatch({ params, signal, onUpdate, ctx, dependencies, disco
 	const tasks = params.tasks as HerdrSubagentsTaskParams[];
 	const resolved: BatchTask[] = [];
 	for (const task of tasks) {
-		const personaName = task.agent?.trim() || "worker";
+		const personaName = task.agent.trim();
 		const persona = discovery.personas.find((candidate) => candidate.name === personaName);
 		if (!persona) return errorResponse(`Unknown persona '${personaName}'.\n\n${listText(discovery)}`);
 		resolved.push({ name: task.name, prompt: task.prompt, agent: persona.name, access: persona.access, model: task.model?.trim() || persona.model, thinking: persona.thinking ?? (persona.modelSource === "parent session" && !task.model ? ctx.thinkingLevel : undefined), tools: persona.tools, skills: persona.skills, extensions: persona.extensions, systemPrompt: persona.systemPrompt });

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

@@ -10,6 +10,9 @@ export const HERDR_ACTIONS = {
 
 export function validateRunParams(params: HerdrSubagentsRunParams): string | undefined {
 	if (!params.tasks?.length) return "Provide a non-empty tasks list.";
+	for (const [index, task] of params.tasks.entries()) {
+		if (typeof task.agent !== "string" || !task.agent.trim()) return `tasks[${index}].agent is required; select a Persona explicitly (use herdr_subagents_control action=list).`;
+	}
 	return undefined;
 }
 

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

@@ -1,11 +1,13 @@
 import assert from "node:assert/strict";
-import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { runHerdrSubagentsBatch } from "../src/batch-runner.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
-import { registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
+import { normalizeHerdrSubagentsArguments, registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
 import { applyTaskStatus } from "../src/records.ts";
+import { executeHerdrSubagents } from "../src/tool.ts";
 
 process.env.HERDR_ENV = "1";
 process.env.HERDR_WORKSPACE_ID = "test-workspace";
@@ -92,6 +94,45 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	return { result, herdr };
 }
 
+{
+	const herdr = fakeHerdr();
+	const execute = (params) => executeHerdrSubagents(params, undefined, undefined, { cwd: root }, {
+		agentsDirectory: fileURLToPath(new URL("../agents/", import.meta.url)),
+		configurationPaths: { globalConfig: join(root, "global-config.json") },
+		herdr,
+	});
+	const missing = { name: "review", prompt: "Read-only review" };
+	for (const params of [
+		{ tasks: [missing] },
+		...["", " \t", null, 42].map((agent) => ({ tasks: [{ ...missing, agent }] })),
+		normalizeHerdrSubagentsArguments({ prompt: "Read-only review" }),
+		normalizeHerdrSubagentsArguments({ prompt: "Read-only review", agent: 42 }),
+	]) {
+		const response = await execute(params);
+		assert.equal(response.isError, true, "Missing or invalid agent must not silently select worker");
+		assert.match(response.content[0].text, /tasks\[0\]\.agent.*required/);
+	}
+	const laterMissing = await execute({ tasks: [{ ...missing, agent: "analyst" }, missing], concurrency: 2 });
+	assert.match(laterMissing.content[0].text, /tasks\[1\]\.agent.*required/);
+	const unknown = await execute({ tasks: [{ ...missing, agent: "unknown-persona" }] });
+	assert.equal(unknown.isError, true);
+	assert.match(unknown.content[0].text, /Unknown persona 'unknown-persona'/);
+	assert.deepEqual(herdr.starts, [], "Invalid requests must not start an Agent");
+	assert.equal(existsSync(join(root, ".pi", "herdr-subagents", "runs")), false, "Invalid requests must not create run records");
+
+	const serial = await execute(normalizeHerdrSubagentsArguments({ prompt: "make change", agent: "worker" }));
+	assert.equal(serial.details.status, "completed", "Explicit worker must still run serially through legacy argument normalization");
+	const parallel = await execute({ tasks: ["analyst", "reviewer", "explorer"].map((agent) => ({ ...missing, agent })), concurrency: 2 });
+	assert.equal(parallel.details.status, "completed");
+	assert.equal(parallel.details.effectiveConcurrency, 2);
+
+	const projectAgents = join(root, ".pi", "herdr-subagents", "agents");
+	mkdirSync(projectAgents, { recursive: true });
+	writeFileSync(join(projectAgents, "auditor.md"), "---\nname: auditor\ndescription: Custom read-only reviewer\naccess: read\n---\nReview the task.\n");
+	const custom = await execute({ tasks: [{ ...missing, agent: " auditor " }], concurrency: 2 });
+	assert.equal(custom.details.status, "completed", "Custom Persona names must remain valid and trim whitespace");
+}
+
 {
 	const { result, herdr } = await run([task("one", "first slow"), task("two", "second")], 1);
 	assert.equal(result.status, "completed");
@@ -146,7 +187,12 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	assert.deepEqual(result.activity.map((entry) => entry.status), ["cancelled", "cancelled"]);
 }
 
-await assert.rejects(() => run([task("writer", "edit", "write"), task("reader", "read")], 2), /require concurrency 1/);
+await assert.rejects(() => run([task("writer", "edit", "write"), task("reader", "read")], 2), (error) => {
+	assert.match(error.message, /writer.*worker/);
+	assert.match(error.message, /concurrency: 1/);
+	assert.match(error.message, /read-only Persona/);
+	return true;
+});
 
 const terminal = { id: "task", runId: "run", order: 1, status: "completed" };
 assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are immutable/);
@@ -184,6 +230,9 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	});
 	assert.deepEqual(herdrCalls, [], "Pi startup must not inspect or close historical Subagent tabs");
 	assert.deepEqual(JSON.parse(readFileSync(join(runDirectory, "run.json"), "utf8")), historicalRun, "Pi startup must not mutate historical Subagent records");
+	const taskSchema = registeredTools.get("herdr_subagents").parameters.properties.tasks.items;
+	assert.ok(taskSchema.required.includes("agent"), "The model-facing schema must require agent");
+	assert.equal(taskSchema.properties.agent.enum, undefined, "Custom Persona names must remain valid");
 	assert.equal(registeredTools.get("herdr_subagents")?.exposure, undefined, "Unconfigured Subagent execution must inherit Pi's exposure default");
 	assert.equal(registeredTools.get("herdr_subagents_control")?.exposure, undefined, "Unconfigured Subagent control must inherit Pi's exposure default");
 	mkdirSync(join(lifecycleRoot, ".pi"), { recursive: true });