@maxiaochao/pi-toolkit 0.11.22 → 0.12.1

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-19 - v0.12.1
+
+- herdr-subagents v0.7.0: add global and project default extension sources with Persona overrides
+- Add Herdr Subagents `defaultExtensions` in global/project settings as a fallback below Persona-specific extension lists, with replacement semantics, explicit `[]` clearing, source diagnostics, and real child-loading coverage.
+
+## 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/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 maxiaochao
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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`. Set top-level `defaultExtensions` in `~/.pi/agent/herdr-subagents.json` (or project `.pi/herdr-subagents.json`) to share a fallback list; Persona-specific lists take precedence, and `[]` clears inherited sources. 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.1",
   "description": "Personal pi coding agent toolkit: scheduler, /btw, /cache_export, apply_patch, browser automation, and bundled theme/skills.",
   "type": "module",
   "workspaces": [
@@ -69,5 +69,6 @@
   },
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "license": "MIT"
 }

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-19 - v0.7.0
+
+- add global and project default extension sources with Persona overrides
+- Add Herdr Subagents `defaultExtensions` in global/project settings as a fallback below Persona-specific extension lists, with replacement semantics, explicit `[]` clearing, source diagnostics, and real child-loading coverage.
+
+## 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.
@@ -170,6 +170,7 @@ These are all supported top-level fields in `herdr-subagents.json`:
 | `stalledWarningSeconds` | Positive integer | `300` | Emit a warning after a child runs this long. This is not a timeout and does not stop it. |
 | `defaultModel` | Non-empty Pi model ID, normally `provider/model` | Unset | Fallback child model. If unset, the parent model is inherited. |
 | `defaultThinking` | Non-empty Pi thinking value | Unset | Fallback thinking level below Persona-specific settings. Typical Pi values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`; model support varies. |
+| `defaultExtensions` | Array of non-empty Pi source strings | Unset (no optional extensions) | Fallback extension sources for Personas without an explicit `extensions` list. Project replaces global; `[]` clears inherited defaults. |
 | `personas` | Object keyed by an existing Persona name | `{}` | Per-Persona overrides. It cannot create a Persona without a matching Markdown definition. |
 
 Each `personas.<name>` object supports:
@@ -213,12 +214,12 @@ Save this as `~/.pi/agent/herdr-subagents.json`. Model IDs, skills, and extensio
   "stalledWarningSeconds": 300,
   "defaultModel": "anthropic/claude-sonnet-4-5",
   "defaultThinking": "medium",
+  "defaultExtensions": ["~/.pi/agent/extensions/provider-routing.ts"],
   "personas": {
     "explorer": {
       "model": "anthropic/claude-haiku-4-5",
       "thinking": "low",
-      "skills": ["code-search"],
-      "extensions": ["~/.pi/agent/extensions/provider-routing.ts"]
+      "skills": ["code-search"]
     },
     "reviewer": {
       "thinking": "high",
@@ -247,7 +248,7 @@ A project can override only what differs in `.pi/herdr-subagents.json`:
 }
 ```
 
-Here the project keeps global `maxConcurrency`, `defaultModel`, and `defaultThinking`; replaces the explorer model and skill list; and replaces the reviewer extension list. It does not append arrays.
+Here the project keeps global `maxConcurrency`, `defaultModel`, `defaultThinking`, and `defaultExtensions`; replaces the explorer model and skill list; and replaces the reviewer extension list. It does not append arrays.
 
 ### Built-in Personas
 
@@ -294,7 +295,11 @@ The Markdown body is the child system prompt. Frontmatter is intentionally a sma
 | `skills` | Comma-separated list, optionally `[bracketed]` | None | Explicit child skills; normal automatic skill discovery is disabled. |
 | `extensions` | One source or a comma-separated list; `[]` clears | None | Additional Pi extension/package sources loaded into the child. |
 
-Relative extension paths resolve from the project root. `~` resolves to the home directory. Pi-native local, `npm:`, `git:`, and `builtin:` sources are accepted. Children always load the required report extension and Codemode; configured sources are additional. Pi packages may provide resources beyond extensions, so load only trusted code and pin versions/refs when reproducibility matters.
+### Explicit extension sources and Pi packages
+
+Use top-level `defaultExtensions` in `~/.pi/agent/herdr-subagents.json` to share trusted extension sources across Personas. Set the same field in `<project>/.pi/herdr-subagents.json` to replace the global default list for that project. Defaults are a fallback, not an appended list: any Persona-specific `extensions`, including Markdown frontmatter and explicit `[]`, takes precedence. An empty default list clears inherited defaults but does not remove Persona-specific sources or the mandatory child extensions.
+
+Relative extension paths resolve from the project root, including paths in global `defaultExtensions`. `~` resolves to the home directory. Pi-native local, `npm:`, `git:`, and `builtin:` sources are accepted. Children always load the required report extension and Codemode; configured sources are additional. Pi packages may provide resources beyond extensions, so load only trusted code and pin versions/refs when reproducibility matters.
 
 ### Effective option precedence
 
@@ -315,7 +320,18 @@ Thinking is selected in this order:
 4. effective `defaultThinking` (project, then global)
 5. parent thinking when the child also inherits the parent model
 
-There is no task-level thinking override. `skills` and `extensions` use project Persona JSON, then global Persona JSON, then effective Persona Markdown. Each winning list replaces the whole lower-precedence list.
+There is no task-level thinking override. `skills` uses project Persona JSON, then global Persona JSON, then effective Persona Markdown.
+
+Extension sources are selected in this order:
+
+1. project `personas.<name>.extensions`
+2. global `personas.<name>.extensions`
+3. effective Persona Markdown `extensions`
+4. project `defaultExtensions`
+5. global `defaultExtensions`
+6. no optional extensions
+
+Each winning list replaces the whole lower-precedence list, including when it is `[]`. The required report extension and Codemode always remain loaded. `/herdr-subagents settings` shows the effective defaults and their source; the agents listing shows each resolved extension list and its source.
 
 Use `/herdr-subagents agents`, `/herdr-subagents models`, and `/herdr-subagents settings` to inspect the result before starting work.
 

package/packages/herdr-subagents/TESTING.md

@@ -8,11 +8,15 @@ npm test --workspace @maxiaochao/pi-herdr-subagents
 
 It verifies:
 
+- global/project `defaultExtensions` replacement, trimming, source attribution, Persona JSON/Markdown precedence, explicit empty-list clearing, invalid-value diagnostics, and per-call reloads;
+- resolved defaults in control listings, settings output, and child CLI arguments while preserving mandatory extensions;
 - strict serial start order at concurrency one;
 - 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;
@@ -26,7 +30,7 @@ It verifies:
 
 The previous broad lifecycle suite remains available temporarily as `npm run test:legacy --workspace @maxiaochao/pi-herdr-subagents` for migration auditing. Scenarios for background queues, blocked/respond, and historical resume intentionally no longer describe the public contract.
 
-Run extension source loading. The direct-Pi fixture validates explicit file/package sources; Herdr's `builtin:codemode` alias is validated by the real-Herdr smoke because the alias is translated by `herdr agent start`:
+Run extension source loading. The direct-Pi fixture resolves global `defaultExtensions` and validates real file/package loading; Herdr's `builtin:codemode` alias is validated by the real-Herdr smoke because the alias is translated by `herdr agent start`:
 
 ```sh
 npm run load-test --workspace @maxiaochao/pi-herdr-subagents
@@ -38,7 +42,7 @@ Run the real Herdr smoke test from a Herdr session:
 npm run test:real-herdr --workspace @maxiaochao/pi-herdr-subagents
 ```
 
-The smoke reads the effective `analyst` model, thinking level, and explicit `extensions` from the invoking project's normal Herdr configuration (npm's `INIT_CWD`, or the current directory when run directly). It copies only those fields into its temporary configuration. It keeps the bundled read-only Persona, tool allowlist, and test concurrency; user skills, prompts, and unrelated settings are not copied. Local extension paths remain relative to the invoking project. The concurrent package-loading probe appends its test package rather than replacing the configured extensions.
+The smoke reads the effective `analyst` model, thinking level, and explicit `extensions` from the invoking project's normal Herdr configuration (npm's `INIT_CWD`, or the current directory when run directly). It copies only those fields into its temporary configuration. It keeps the bundled read-only Persona, tool allowlist, and test concurrency; user skills, prompts, and unrelated settings are not copied. Local extension paths remain relative to the invoking project. The concurrent package-loading probe appends its test package rather than replacing the configured extensions. The isolated smoke supplies these sources through global `defaultExtensions`, so both single and concurrent runs exercise default resolution, actual child loading, durable task records, and tab cleanup.
 
 This preserves authentication extensions such as `npm:@maxiaochao/pi-openai-account-pool` in both the single and concurrent cases. Children still use `--no-extensions`: only the mandatory child extensions, configured explicit sources, and test probe load. The smoke does not copy or edit credentials. If no Herdr model is configured, Pi's normal startup model selection still applies.
 

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 } : {}),
@@ -89,7 +89,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, defaultThinking: settings.defaultThinking };
+		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, defaultModel: settings.defaultModel, defaultThinking: settings.defaultThinking, defaultExtensions: JSON.stringify(settings.defaultExtensions ?? []) };
 		const lines = [`exposure=${registeredExposure.value ?? "Pi default"} (${registeredExposure.source}; loaded at extension registration)`, ...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");
@@ -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.7.0",
   "description": "Run inspectable interactive Pi subagent batches through Herdr.",
   "type": "module",
   "keywords": [
@@ -37,7 +37,7 @@
     "typebox": "*"
   },
   "scripts": {
-    "test": "node --experimental-strip-types tests/core-state-machine.mjs && node --experimental-strip-types tests/real-herdr-config.test.mjs",
+    "test": "node --experimental-strip-types tests/config.mjs && node --experimental-strip-types tests/core-state-machine.mjs && node --experimental-strip-types tests/real-herdr-config.test.mjs",
     "test:real-herdr": "node --experimental-strip-types tests/real-herdr-smoke.mjs",
     "load-test": "env -u PI_HERDR_SUBAGENTS_CHILD \"${PI_TEST_BINARY:-pi}\" -ne -ns --no-session -e ./tests/extension-contract.ts && env -u PI_HERDR_SUBAGENTS_CHILD \"${PI_TEST_BINARY:-pi}\" -ne -ns --no-session -e ./extensions/herdr-subagents.ts && node --experimental-strip-types tests/extension-sources-load.mjs",
     "test:legacy": "node --experimental-strip-types tests/run-tests.mjs && node --experimental-strip-types tests/cleanup-timing.mjs"

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/config.ts

@@ -13,6 +13,7 @@ export interface SubagentConfig {
 	stalledWarningSeconds: number;
 	defaultModel?: string;
 	defaultThinking?: string;
+	defaultExtensions?: string[];
 	personas: Record<string, PersonaConfig>;
 }
 export interface EffectivePersona extends AgentDefinition {
@@ -40,6 +41,7 @@ interface ConfigFile {
 	stalledWarningSeconds?: number;
 	defaultModel?: string;
 	defaultThinking?: string;
+	defaultExtensions?: string[];
 	personas?: Record<string, PersonaConfig>;
 }
 export interface ConfigurationPaths {
@@ -81,6 +83,13 @@ function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, so
 		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.defaultExtensions !== undefined) {
+		const value = input.defaultExtensions;
+		if (Array.isArray(value) && value.every((item) => typeof item === "string" && item.trim())) {
+			result.defaultExtensions = value.map((item) => item.trim());
+			sources.defaultExtensions = source;
+		} else diagnostics.push(`${source} defaultExtensions must be an array of non-empty strings`);
+	}
 	if (input.personas !== undefined) {
 		if (!input.personas || typeof input.personas !== "object" || Array.isArray(input.personas)) diagnostics.push(`${source} personas must be an object`);
 		else for (const [name, raw] of Object.entries(input.personas)) {
@@ -134,8 +143,8 @@ export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: s
 		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";
-		const extensions = projectPersona.extensions ?? globalPersona.extensions ?? definition.extensions ?? [];
-		const extensionsSource = projectPersona.extensions ? "project persona" : globalPersona.extensions ? "global persona" : definition.extensions ? `${source} persona` : "none";
+		const extensions = projectPersona.extensions ?? globalPersona.extensions ?? definition.extensions ?? settings.defaultExtensions ?? [];
+		const extensionsSource = projectPersona.extensions ? "project persona" : globalPersona.extensions ? "global persona" : definition.extensions ? `${source} persona` : settings.defaultExtensions ? settingSources.defaultExtensions : "none";
 		return { ...definition, source, access: definition.access ?? "write", model, modelSource, thinking, thinkingSource, skills, skillsSource, extensions, extensionsSource };
 	}).sort((left, right) => left.name.localeCompare(right.name));
 	return { settings, settingSources, personas, diagnostics };

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/config.mjs

@@ -0,0 +1,103 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { childPiArgs } from "../src/live-agent.ts";
+import { executeHerdrSubagentsControl } from "../src/tool.ts";
+
+const root = mkdtempSync(join(tmpdir(), "herdr-default-extensions-"));
+const agents = join(root, "agents");
+const paths = {
+	globalConfig: join(root, "global.json"),
+	projectConfig: join(root, "project.json"),
+	globalAgents: join(root, "global-agents"),
+	projectAgents: join(root, "project-agents"),
+};
+const write = (path, value) => writeFileSync(path, JSON.stringify(value));
+const load = () => loadSubagentConfiguration(root, agents, undefined, paths);
+const persona = (configuration, name = "plain") => configuration.personas.find((entry) => entry.name === name);
+try {
+	mkdirSync(agents);
+	for (const [name, frontmatter] of [["plain", ""], ["pinned", "extensions: ./markdown.ts\n"], ["cleared", "extensions: []\n"]]) {
+		writeFileSync(join(agents, `${name}.md`), `---\nname: ${name}\ndescription: Configuration fixture\naccess: read\n${frontmatter}---\nRead only.\n`);
+	}
+	assert.deepEqual(persona(load()).extensions, []);
+	assert.equal(persona(load()).extensionsSource, "none");
+	write(paths.globalConfig, { defaultExtensions: [" ./global.ts ", "npm:provider@1.0.0"] });
+	let configuration = load();
+	assert.deepEqual(configuration.settings.defaultExtensions, ["./global.ts", "npm:provider@1.0.0"]);
+	assert.equal(configuration.settingSources.defaultExtensions, "global");
+	assert.deepEqual(persona(configuration).extensions, configuration.settings.defaultExtensions);
+	assert.equal(persona(configuration).extensionsSource, "global");
+	assert.deepEqual(persona(configuration, "pinned").extensions, ["./markdown.ts"]);
+	assert.deepEqual(persona(configuration, "cleared").extensions, []);
+
+	write(paths.projectConfig, { defaultExtensions: ["./project.ts"] });
+	configuration = load();
+	assert.deepEqual(persona(configuration).extensions, ["./project.ts"]);
+	assert.equal(persona(configuration).extensionsSource, "project");
+	assert.equal(configuration.settingSources.defaultExtensions, "project");
+	assert.deepEqual(persona(configuration, "pinned").extensions, ["./markdown.ts"]);
+	assert.deepEqual(persona(configuration, "cleared").extensions, []);
+	console.log("PASS project defaults replace global defaults; Markdown lists and [] override defaults");
+
+	write(paths.globalConfig, { defaultExtensions: ["./global.ts"], personas: { plain: { extensions: ["./global-persona.ts"] }, pinned: { extensions: [] } } });
+	assert.deepEqual(persona(load(), "pinned").extensions, []);
+	assert.equal(persona(load(), "pinned").extensionsSource, "global persona");
+	assert.deepEqual(persona(load()).extensions, ["./global-persona.ts"]);
+	assert.equal(persona(load()).extensionsSource, "global persona");
+	write(paths.projectConfig, { defaultExtensions: ["./project.ts"], personas: { plain: { extensions: ["./project-persona.ts"] }, pinned: { extensions: ["./project-persona.ts"] } } });
+	assert.deepEqual(persona(load(), "pinned").extensions, ["./project-persona.ts"]);
+	assert.deepEqual(persona(load()).extensions, ["./project-persona.ts"]);
+	assert.equal(persona(load()).extensionsSource, "project persona");
+	write(paths.projectConfig, { defaultExtensions: ["./project.ts"], personas: { plain: { extensions: [] } } });
+	assert.deepEqual(persona(load()).extensions, []);
+	assert.equal(persona(load()).extensionsSource, "project persona");
+	console.log("PASS Persona JSON lists win over defaults and [] clears rather than inherits");
+
+	write(paths.globalConfig, { defaultExtensions: ["./global.ts"] });
+	write(paths.projectConfig, { defaultExtensions: [] });
+	assert.deepEqual(load().settings.defaultExtensions, []);
+	assert.deepEqual(persona(load()).extensions, []);
+	assert.equal(persona(load()).extensionsSource, "project");
+	assert.deepEqual(persona(load(), "pinned").extensions, ["./markdown.ts"]);
+	for (const value of [null, "./invalid.ts", {}, [1], [""], [" \t "], ["./valid.ts", false]]) {
+		write(paths.projectConfig, { defaultExtensions: value });
+		configuration = load();
+		assert.deepEqual(persona(configuration).extensions, ["./global.ts"]);
+		assert.equal(configuration.settingSources.defaultExtensions, "global");
+		assert.ok(configuration.diagnostics.includes("project defaultExtensions must be an array of non-empty strings"));
+		write(paths.globalConfig, { defaultExtensions: value });
+		write(paths.projectConfig, {});
+		configuration = load();
+		assert.deepEqual(persona(configuration).extensions, []);
+		assert.ok(configuration.diagnostics.includes("global defaultExtensions must be an array of non-empty strings"));
+		write(paths.globalConfig, { defaultExtensions: ["./global.ts"] });
+	}
+	console.log("PASS empty defaults clear inherited defaults; invalid lists are diagnosed without partial loading");
+
+	write(paths.projectConfig, { defaultExtensions: ["./updated.ts"] });
+	configuration = load();
+	const selected = persona(configuration);
+	const args = childPiArgs({ ...selected, sessionFile: join(root, "session.jsonl") }, join(root, "system.md"));
+	assert.ok(args.includes("--no-extensions"));
+	assert.ok(args.includes("builtin:codemode"));
+	assert.ok(args.some((arg) => arg.endsWith("/extensions/subagent-report.ts")));
+	assert.equal(args[args.indexOf("./updated.ts") - 1], "--extension");
+	const response = await executeHerdrSubagentsControl({ action: "list" }, undefined, undefined, { cwd: root }, { agentsDirectory: agents, configurationPaths: paths });
+	assert.deepEqual(response.details.agents.find(({ name }) => name === "plain").extensions, ["./updated.ts"]);
+	assert.deepEqual(response.details.settings.defaultExtensions, ["./updated.ts"]);
+	assert.match(response.content[0].text, /extensions: \.\/updated\.ts \[project\]/);
+	write(paths.projectConfig, { defaultExtensions: [] });
+	const cleared = persona(load());
+	assert.deepEqual(cleared.extensions, []);
+	const clearedArgs = childPiArgs({ ...cleared, sessionFile: join(root, "session.jsonl") }, join(root, "system.md"));
+	assert.ok(clearedArgs.includes("builtin:codemode"));
+	assert.ok(clearedArgs.some((arg) => arg.endsWith("/extensions/subagent-report.ts")));
+	assert.ok(!clearedArgs.includes("./updated.ts"));
+	assert.deepEqual(selected.extensions, ["./updated.ts"]);
+	console.log("PASS defaults reach child arguments and control listings, reload per call, and preserve mandatory extensions");
+} finally {
+	rmSync(root, { recursive: true, force: true });
+}

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,18 +230,25 @@ 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 });
-	writeFileSync(join(lifecycleRoot, ".pi", "herdr-subagents.json"), JSON.stringify({ exposure: "model-only" }));
+	writeFileSync(join(lifecycleRoot, ".pi", "herdr-subagents.json"), JSON.stringify({ exposure: "model-only", defaultExtensions: [] }));
 	const configuredTools = new Map();
+	const configuredCommands = new Map();
 	registerHerdrSubagents({
 		on() {},
 		registerTool(tool) { configuredTools.set(tool.name, tool); },
-		registerCommand() {},
+		registerCommand(name, command) { configuredCommands.set(name, command); },
 	}, { herdr: {}, isEditor: () => false, configurationCwd: lifecycleRoot, configurationPaths });
 	assert.equal(configuredTools.get("herdr_subagents")?.exposure, "model-only", "Project configuration can exclude Subagent execution from Codemode");
 	assert.equal(configuredTools.get("herdr_subagents_control")?.exposure, "model-only", "Project configuration applies consistently to both Subagent tools");
+	const notifications = [];
+	await configuredCommands.get("herdr-subagents").handler("settings", { cwd: lifecycleRoot, ui: { notify(message) { notifications.push(message); } } });
+	assert.match(notifications[0], /defaultExtensions=\[\] \(project\)/, "Settings must show empty defaults and their source");
 }
 
 {

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

@@ -4,6 +4,8 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "nod
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { childPiArgs } from "../src/live-agent.ts";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { fileURLToPath } from "node:url";
 
 // Exercise native Pi package semantics without provider calls or network installs.
 const root = mkdtempSync(join(tmpdir(), "pi-herdr-extension-sources-"));
@@ -36,7 +38,12 @@ try {
 				ctx.shutdown();
 			});
 		}`);
-	const args = childPiArgs({ id: "probe", sessionFile: join(root, "session.jsonl"), tools: ["read"], extensions: [fileExtension, "./local package", probe] }, join(root, "system.md"));
+	const globalConfig = join(root, "global.json");
+	writeFileSync(globalConfig, JSON.stringify({ defaultExtensions: [fileExtension, "./local package", probe] }));
+	const configuration = loadSubagentConfiguration(root, fileURLToPath(new URL("../agents", import.meta.url)), undefined, { globalConfig, globalAgents: join(root, "global-agents") });
+	const analyst = configuration.personas.find(({ name }) => name === "analyst");
+	assert.equal(analyst.extensionsSource, "global");
+	const args = childPiArgs({ id: "probe", sessionFile: join(root, "session.jsonl"), tools: ["read"], extensions: analyst.extensions }, join(root, "system.md"));
 	// `builtin:codemode` is translated by `herdr agent start` and is covered by
 	// the real-Herdr smoke test. Direct Pi has no portable form of that alias.
 	const codemode = args.indexOf("builtin:codemode");
@@ -50,7 +57,7 @@ try {
 	const loaded = JSON.parse(readFileSync(resultPath, "utf8"));
 	for (const command of ["file-extension", "package-extension", "skill:package-skill", "package-prompt", "parent"]) assert.ok(loaded.commands.includes(command), `Missing ${command}: ${JSON.stringify(loaded)}`);
 	assert.deepEqual([...loaded.tools].sort(), ["read", "subagent_report"]);
-	console.log("PASS real Pi loads explicit file and package sources, including package skills/prompts despite discovery flags, without broadening the direct-Pi tool allowlist");
+	console.log("PASS real Pi loads defaultExtensions file and package sources, including package skills/prompts despite discovery flags, without broadening the direct-Pi tool allowlist");
 } finally {
 	rmSync(root, { recursive: true, force: true });
 }

package/packages/herdr-subagents/tests/real-herdr-config.test.mjs

@@ -21,8 +21,8 @@ try {
 		maxConcurrency: 1,
 		defaultModel: "openai-codex/test-model",
 		defaultThinking: "high",
+		defaultExtensions: ["npm:@maxiaochao/pi-openai-account-pool"],
 		personas: { analyst: {
-			extensions: ["npm:@maxiaochao/pi-openai-account-pool"],
 			skills: ["unrelated-skill"],
 		} },
 	});

package/packages/herdr-subagents/tests/real-herdr-smoke.mjs

@@ -97,7 +97,7 @@ async function waitForCleanup(result) {
 
 async function runCase(label, names, concurrency, extraExtensions = []) {
 	const extensions = [...runtimePersona.extensions, ...extraExtensions];
-	writeFileSync(configurationPaths.globalConfig, JSON.stringify({ personas: { analyst: { ...runtimePersona, extensions } } }));
+	writeFileSync(configurationPaths.globalConfig, JSON.stringify({ defaultExtensions: extensions, personas: { analyst: { model: runtimePersona.model, thinking: runtimePersona.thinking } } }));
 	if (concurrency > 1 && process.env.HERDR_SUBAGENTS_E2E_FOCUS_CLEANUP === "1") {
 		const workspaces = spawnSync(process.env.PI_HERDR_SUBAGENTS_HERDR_BINARY?.trim() || "herdr", ["workspace", "list"], { encoding: "utf8", timeout: 10_000 });
 		assert.equal(workspaces.status, 0, workspaces.stderr);