@maxiaochao/pi-toolkit 0.13.3 → 0.13.4

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-22 - v0.13.4
+
+- herdr-subagents v0.7.3: keep Persona selection lists concise
+
 ## 2026-10-21 - v0.13.3
 
 - codex-edit v0.2.0: persist personal routing rules in the Pi agent directory across package updates
@@ -9,6 +13,7 @@
 
 ## Unreleased
 
+- Herdr Subagents: show only Persona names and descriptions in model-facing selection lists, preserving diagnostics and detailed user-facing inspection.
 - Make Agent Team user-invoked only through `/skill:agent-team`, hidden from automatic model selection.
 - Add `npm run release:check -- vX.Y.Z` to wait for GitHub publication and verify exact npm versions, remote tags, integrity, and all tarball contents against the release commit, including coordinated child releases.
 

package/README.md

@@ -42,7 +42,7 @@ Each child README owns its feature description, motivation or upstream alignment
 
 Codex Edit personal routing rules belong in `~/.pi/agent/codex-edit.json`, not inside `node_modules`. User fields override bundled defaults; `models` replaces the complete default list. The file survives package updates and is shared by parent sessions and explicitly configured subagents using the same agent directory. Use `/reload` after editing it, and start new subagents. See [Codex Edit configuration](packages/codex-edit/README.md#configuration).
 
-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.
+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. Control `list` returns names and descriptions for selection, plus configuration diagnostics when present; use `/herdr-subagents agents` and `settings` for detailed configuration. 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, including `pi-background-tasks`, is embedded, so a second install exposes the same resource twice.
 

package/package.json

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

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-22 - v0.7.3
+
+- keep Persona selection lists concise
+- Limit model-facing Persona listings and unknown-Persona suggestions to names and descriptions. Preserve configuration diagnostics, detailed result metadata, and the `/herdr-subagents agents` and `settings` inspection commands.
+
 ## 2026-10-21 - v0.7.2
 
 - clarify final answer submission through subagent_report

package/packages/herdr-subagents/README.md

@@ -119,7 +119,7 @@ A batch containing a write-capable Persona must explicitly or effectively use `c
 
 | Action | `runId` | Purpose |
 | --- | --- | --- |
-| `list` | Not accepted | List effective Personas, resolved options, and diagnostics. |
+| `list` | Not accepted | List Persona names and descriptions for task selection, plus configuration diagnostics when present. |
 | `status` | Required | Show one run and its task states. |
 | `history` | Not accepted | List durable project-local run history. |
 | `cancel` | Required | Cancel an active run. |
@@ -127,6 +127,8 @@ A batch containing a write-capable Persona must explicitly or effectively use `c
 
 Settled tasks are immutable. Follow-up work starts a new task or run; there is no resume/respond lifecycle.
 
+The model-facing `list` text does not expand tools, skills, extensions, models, thinking levels, or configuration sources. Describe routing-relevant capabilities and constraints in each Persona's description. Use `/herdr-subagents agents` and `/herdr-subagents settings` for detailed configuration; full resolved data remains in the tool result's `details` metadata.
+
 ### Slash command
 
 `/herdr-subagents` supports:

package/packages/herdr-subagents/TESTING.md

@@ -9,7 +9,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;
+- concise Persona names/descriptions in model-facing listings and unknown-Persona errors, including empty lists and visible configuration diagnostics;
+- resolved defaults in control result metadata, 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;

package/packages/herdr-subagents/package.json

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

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

@@ -60,10 +60,7 @@ export function listText(discovery: SubagentConfiguration): string {
 	const lines = ["Available Herdr Subagents personas:"];
 	if (discovery.personas.length === 0) lines.push("- (none)");
 	for (const agent of discovery.personas) {
-		const model = agent.model ?? "unresolved";
-		const tools = agent.tools?.join(", ") ?? "Pi default built-in tools";
-		const skills = agent.skills.join(", ") || "none";
-		lines.push(`- ${agent.name}: ${agent.description} (source: ${agent.source}; access: ${agent.access}; model: ${model} [${agent.modelSource}]; thinking: ${agent.thinking ?? "default"}; tools: ${tools}; skills: ${skills}; extensions: ${agent.extensions.join(", ") || "none"} [${agent.extensionsSource}])`);
+		lines.push(`- ${agent.name}: ${agent.description}`);
 	}
 	if (discovery.diagnostics.length > 0) {
 		lines.push("", "Persona diagnostics:", ...discovery.diagnostics.map((diagnostic) => `- ${diagnostic}`));

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

@@ -4,7 +4,7 @@ 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";
+import { executeHerdrSubagentsControl, listText } from "../src/tool.ts";
 
 const root = mkdtempSync(join(tmpdir(), "herdr-default-extensions-"));
 const agents = join(root, "agents");
@@ -88,7 +88,18 @@ try {
 	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\]/);
+	const expectedListing = [
+		"Available Herdr Subagents personas:",
+		"- cleared: Configuration fixture",
+		"- pinned: Configuration fixture",
+		"- plain: Configuration fixture",
+	].join("\n");
+	assert.equal(response.content[0].text, expectedListing, "Model-facing listings must contain only Persona names and descriptions");
+	assert.equal(listText({ ...configuration, personas: [] }), "Available Herdr Subagents personas:\n- (none)");
+	write(paths.projectConfig, { defaultExtensions: "./invalid.ts" });
+	const diagnosed = await executeHerdrSubagentsControl({ action: "list" }, undefined, undefined, { cwd: root }, { agentsDirectory: agents, configurationPaths: paths });
+	assert.equal(diagnosed.content[0].text, `${expectedListing}\n\nPersona diagnostics:\n- project defaultExtensions must be an array of non-empty strings`, "Concise listings must still surface invalid configuration");
+	assert.deepEqual(diagnosed.details.diagnostics, ["project defaultExtensions must be an array of non-empty strings"]);
 	write(paths.projectConfig, { defaultExtensions: [] });
 	const cleared = persona(load());
 	assert.deepEqual(cleared.extensions, []);
@@ -97,7 +108,7 @@ try {
 	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");
+	console.log("PASS concise Persona listings preserve diagnostics and detailed metadata; defaults reach child arguments and reload per call");
 } finally {
 	rmSync(root, { recursive: true, force: true });
 }

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

@@ -142,7 +142,7 @@ async function run(tasks, concurrency, herdr = fakeHerdr(), signal) {
 	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.equal(unknown.content[0].text, `Unknown persona 'unknown-persona'.\n\n${listed.content[0].text}`, "Unknown-Persona errors must reuse the concise selection list");
 	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");
 
@@ -287,6 +287,8 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	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");
+	await configuredCommands.get("herdr-subagents").handler("agents", { cwd: lifecycleRoot, ui: { notify(message) { notifications.push(message); } } });
+	assert.match(notifications[1], /: (?:package|global|project), (?:read|write), model=.*thinking=.*tools=.*skills=.*extensions=/, "User-facing inspection must retain detailed configuration fields");
 }
 
 {

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

@@ -661,7 +661,7 @@ try {
 	const extensionHistory = await listSubagentHistory(extensionRoot);
 	check("history exposes saved extension sources", JSON.stringify(extensionHistory[0]?.tasks[0]?.extensions) === JSON.stringify(extensionSources));
 	const extensionList = await executeHerdrSubagents({ action: "list" }, undefined, undefined, { cwd: extensionRoot }, extensionDependencies);
-	check("persona listing shows extension sources and their precedence", extensionList.content[0].text.includes("npm:@example/pi-tools@1.0.0") && extensionList.content[0].text.includes("project persona"));
+	check("persona listing keeps extension configuration in metadata only", !extensionList.content[0].text.includes("npm:@example/pi-tools@1.0.0") && extensionList.details.agents[0].extensionsSource === "project persona" && JSON.stringify(extensionList.details.agents[0].extensions) === JSON.stringify(extensionSources));
 	writeFileSync(extensionPaths.projectConfig, JSON.stringify({ personas: { routed: { extensions: [] } } }));
 	check("empty project extension list clears lower-precedence sources", extensionPersona()?.extensions?.length === 0 && extensionPersona()?.extensionsSource === "project persona");
 	const extensionResumeHerdr = fakeHerdr();