@maxiaochao/pi-toolkit 0.12.0 → 0.12.1

package/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 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. 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.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,8 @@
+## 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
 
@@ -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,6 +8,8 @@ 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;
@@ -28,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
@@ -40,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

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

package/packages/herdr-subagents/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-herdr-subagents",
-  "version": "0.6.0",
+  "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/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

@@ -236,15 +236,19 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	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);