@maxiaochao/pi-toolkit 0.12.0 → 0.12.2

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 2026-10-20 - v0.12.2
+
+- herdr-subagents v0.7.1: clarify Persona responsibilities and dispatch guidance
+- Clarify Herdr Persona selection and instructions: broad independent reviewer, codebase explorer, file-changing worker, and neutral charter-driven agent-team analyst. Make the Agent Team skill explicitly select analyst when dispatching through Personas.
+
+## 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

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 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.
+Herdr Subagents tasks require an explicit `agent` Persona; no default `worker` is selected. Choose `reviewer` for independent reviews of proposals, designs, documents, implementations, or analysis; `explorer` for codebase investigation; `worker` for file-changing work; and `analyst` for charter-defined agent-team roles. See [built-in Personas](packages/herdr-subagents/README.md#built-in-personas) for selection guidance and the distinction between parent-facing descriptions and child instructions. 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.12.0",
+  "version": "0.12.2",
   "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-20 - v0.7.1
+
+- clarify Persona responsibilities and dispatch guidance
+- Clarify parent-facing Persona selection and child instructions: reviewer independently reviews proposals, designs, documents, implementations, and analysis; analyst is the neutral agent-team execution persona with task-defined roles; explorer investigates codebase structure, behavior, and dependencies. Preserve worker instructions and all tool/access boundaries.
+
+## 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

package/packages/herdr-subagents/README.md

@@ -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
 
@@ -256,9 +257,13 @@ None of the bundled Personas pins a model, thinking level, skill, or optional ex
 | Persona | Access | Built-in tools | Intended use |
 | --- | --- | --- | --- |
 | `worker` | `write` | `read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`, `codemode` | One focused implementation or other file-changing task. |
-| `explorer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Fast codebase investigation without file changes. |
-| `analyst` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Neutral analysis where the task prompt supplies the role and evaluation method. |
-| `reviewer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Correctness and maintainability review with actionable evidence. |
+| `explorer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Codebase structure, behavior, and dependency investigation without file changes. |
+| `analyst` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Neutral agent-team execution where each task supplies the role charter and evaluation method. |
+| `reviewer` | `read` | `read`, `bash`, `grep`, `find`, `ls`, `codemode` | Independent review of proposals, designs, documents, implementations, and analysis against goals and constraints. |
+
+Choose `reviewer` for an independent assessment of existing work, `explorer` to investigate how the codebase works, `worker` for file-changing work, and `analyst` for agent-team members whose role is supplied by the task charter. An analyst may perform a review when its charter calls for one; its neutral execution role does not replace the reviewer selection for ordinary review requests.
+
+The control tool's `list` action exposes each effective `description` to help the parent choose a Persona. The Markdown body instead becomes the selected child's appended system prompt. Put selection guidance in `description` and execution instructions in the body; bundled definitions keep both in English.
 
 `access` is a scheduling declaration: any `write` Persona requires serial execution. It is not by itself a sandbox. For a custom read-only Persona, also omit write-capable tools and load only trusted extensions.
 
@@ -294,7 +299,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 +324,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;
 - required explicit Personas in the tool schema and execution, including legacy single-task argument normalization;
+- model-facing role selection guidance for broad independent review, codebase investigation, file-changing work, and charter-driven agent-team execution;
+- effective Persona descriptions in parent listings, corresponding bodies in child system prompts, and unchanged read/write tool boundaries;
 - 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;
@@ -28,7 +32,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
@@ -40,7 +44,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/agents/analyst.md

@@ -1,8 +1,8 @@
 ---
 name: analyst
-description: Neutral read-only analyst for dynamically assigned roles
+description: Neutral read-only execution persona for agent-team, with roles defined by each task
 access: read
 tools: read, bash, grep, find, ls, codemode
 ---
 
-Act as an independent analyst and follow the role and evaluation method in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful paths.
+Serve as a neutral execution persona for agent-team. Follow the role charter and evaluation method supplied in the task prompt. Do not modify project files. Separate direct evidence, inference, and unknowns, and report concrete evidence with useful source references.

package/packages/herdr-subagents/agents/explorer.md

@@ -1,8 +1,8 @@
 ---
 name: explorer
-description: Read-only explorer for fast codebase investigation
+description: Read-only explorer for codebase structure, behavior, and dependencies
 access: read
 tools: read, bash, grep, find, ls, codemode
 ---
 
-Investigate the assigned question without modifying files. Report concrete evidence and useful paths.
+Investigate the assigned question without modifying files. Locate relevant files, trace behavior and dependencies, and report concrete evidence with useful paths. Distinguish confirmed behavior from unresolved questions.

package/packages/herdr-subagents/agents/reviewer.md

@@ -1,8 +1,8 @@
 ---
 name: reviewer
-description: Read-only reviewer for correctness and maintainability risks
+description: Independent read-only reviewer for proposals, designs, documents, implementations, and analysis
 access: read
 tools: read, bash, grep, find, ls, codemode
 ---
 
-Review the assigned work without modifying files. Report actionable findings with concrete evidence.
+Independently review the assigned work against its goals and constraints. Examine assumptions, logic, evidence, trade-offs, and risks. Identify gaps and provide actionable recommendations with concrete evidence. Do not modify project files.

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

@@ -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 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.",
+		description: "Run ordered tasks in visible Herdr Pi panes, with an explicit agent for each task. Choose reviewer for independent reviews, explorer for codebase investigation, worker for file changes, or analyst for agent-team tasks with a supplied role charter; use control list to inspect effective and custom Personas. 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.6.0",
+  "version": "0.7.1",
   "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/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/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

@@ -7,7 +7,7 @@ import { runHerdrSubagentsBatch } from "../src/batch-runner.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
 import { normalizeHerdrSubagentsArguments, registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
 import { applyTaskStatus } from "../src/records.ts";
-import { executeHerdrSubagents } from "../src/tool.ts";
+import { executeHerdrSubagents, executeHerdrSubagentsControl } from "../src/tool.ts";
 
 process.env.HERDR_ENV = "1";
 process.env.HERDR_WORKSPACE_ID = "test-workspace";
@@ -101,6 +101,32 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 		configurationPaths: { globalConfig: join(root, "global-config.json") },
 		herdr,
 	});
+	const listed = await executeHerdrSubagentsControl({ action: "list" }, undefined, undefined, { cwd: root }, {
+		agentsDirectory: fileURLToPath(new URL("../agents/", import.meta.url)),
+		configurationPaths: { globalConfig: join(root, "global-config.json") },
+	});
+	const personas = new Map(listed.details.agents.map((persona) => [persona.name, persona]));
+	const analyst = personas.get("analyst");
+	assert.match(analyst.description, /agent-team.*roles defined by each task/);
+	assert.match(analyst.systemPrompt, /role charter and evaluation method/);
+	const reviewer = personas.get("reviewer");
+	assert.match(reviewer.description, /proposals, designs, documents, implementations, and analysis/);
+	assert.match(reviewer.systemPrompt, /goals and constraints/);
+	assert.match(reviewer.systemPrompt, /assumptions, logic, evidence, trade-offs, and risks/);
+	const explorer = personas.get("explorer");
+	assert.match(explorer.description, /codebase structure, behavior, and dependencies/);
+	assert.match(explorer.systemPrompt, /Locate relevant files, trace behavior and dependencies/);
+	const readTools = ["read", "bash", "grep", "find", "ls", "codemode"];
+	for (const name of ["analyst", "reviewer", "explorer"]) {
+		const persona = personas.get(name);
+		assert.equal(persona.access, "read");
+		assert.deepEqual(persona.tools, readTools);
+		assert.ok(listed.content[0].text.includes(`${name}: ${persona.description}`), "The parent must see role selection guidance in Persona listings");
+		assert.ok(!listed.content[0].text.includes(persona.systemPrompt), "Persona listings must not embed the child instructions");
+	}
+	assert.equal(personas.get("worker").access, "write");
+	assert.equal(personas.get("worker").description, "General-purpose worker for one focused task");
+	assert.match(personas.get("worker").systemPrompt, /Do not delegate to another agent/);
 	const missing = { name: "review", prompt: "Read-only review" };
 	for (const params of [
 		{ tasks: [missing] },
@@ -125,6 +151,12 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	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);
+	for (const [index, name] of ["analyst", "reviewer", "explorer"].entries()) {
+		const directory = parallel.details.tasks[index].recordDirectory;
+		const instructions = readFileSync(join(directory, "system-prompt.md"), "utf8");
+		assert.ok(instructions.startsWith(personas.get(name).systemPrompt), "Each child must receive its selected Persona body");
+		assert.match(instructions, /call subagent_report exactly once/);
+	}
 
 	const projectAgents = join(root, ".pi", "herdr-subagents", "agents");
 	mkdirSync(projectAgents, { recursive: true });
@@ -231,20 +263,29 @@ 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;
+	const description = registeredTools.get("herdr_subagents").description;
+	assert.match(description, /reviewer for independent reviews/);
+	assert.match(description, /explorer for codebase investigation/);
+	assert.match(description, /worker for file changes/);
+	assert.match(description, /analyst for agent-team/);
 	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);

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

@@ -598,7 +598,7 @@ try {
 	check("persona discovery and diagnostics", discovery.agents.length === 1 && discovery.agents[0].name === "worker" && discovery.diagnostics.length === 1);
 	const packageDiscovery = discoverPackageAgents(join(process.cwd(), "agents"));
 	const analystPersona = packageDiscovery.agents.find((persona) => persona.name === "analyst");
-	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls,codemode" && /independent analyst/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
+	check("built-in analyst is neutral and read-only", packageDiscovery.diagnostics.length === 0 && analystPersona?.access === "read" && analystPersona.model === undefined && analystPersona.tools?.join(",") === "read,bash,grep,find,ls,codemode" && /neutral execution persona for agent-team/.test(analystPersona.systemPrompt) && /role charter and evaluation method/.test(analystPersona.systemPrompt) && /direct evidence, inference, and unknowns/.test(analystPersona.systemPrompt) && !/auditor|replicator|adversary/.test(analystPersona.systemPrompt));
 
 	const configRoot = join(root, "configuration");
 	const packageAgents = join(configRoot, "package-agents");

package/skills/agent-team/SKILL.md

@@ -28,7 +28,7 @@ description: 多模型协作分析：主 Agent 按配置的模型和角色调度
 
 读取本 skill 同目录的 [models.json](models.json)：`members` 是成员与模型的唯一配置来源，`roles` 是角色职责的唯一配置来源。默认将两个数组按顺序一一对应；配置为空或数量不匹配时，报告配置问题后再启动。
 
-按配置成员数并发启动子代理，显式传入各自的 `model`，并将对应角色的 `charter` 放入任务。成员使用相同的中性只读执行约束。启动后核对并在本轮记录中写下每个任务实际生效的模型；无法确认或与配置不符时，该成员结果无效并报告原因。
+按配置成员数并发启动子代理，显式传入各自的 `model`，并将对应角色的 `charter` 放入任务。使用 Persona 派发时，成员统一选择 `agent: "analyst"`，作为中立执行载体；具体职责由本轮 `charter` 注入。成员使用相同的中性只读执行约束。启动后核对并在本轮记录中写下每个任务实际生效的模型；无法确认或与配置不符时，该成员结果无效并报告原因。
 
 每轮在 `rounds/N.md` 写明成员、模型、角色、输入文件和分派问题。默认沿用角色映射；需要交叉复核时可轮换，并记录新的映射。