@maxiaochao/pi-toolkit 0.11.19 → 0.11.20

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-14 - v0.11.20
+
+- herdr-subagents v0.5.3: allow optional Pi-native tool exposure while inheriting Pi defaults when unset
+
 ## 2026-10-14 - v0.11.19
 
 - herdr-subagents v0.5.2: stop Pi startup from scanning historical runs or closing recorded Herdr tabs

package/package.json

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

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -110,3 +110,7 @@ Writing the same report again is idempotent. A conflicting replacement is reject
 ## Cancellation and shutdown
 
 Caller or parent-session cancellation aborts active waits, marks nonterminal tasks cancelled, and closes the Herdr tab owned by that session. A new Pi session never scans, mutates, resumes, or closes historical runs during startup. If Pi is terminated before its shutdown handlers run, its visible Subagent tabs remain for explicit user inspection or cleanup.
+
+## Tool exposure
+
+The extension reads optional `exposure` once before registering its two tools. When omitted, the extension also omits the registration field and delegates to Pi's default. Global or project configuration can select Pi's `model-only` or `direct` exposure explicitly. Changing this registration-time setting requires `/reload` or a Pi restart; the extension does not re-register tools during a session.

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-14 - v0.5.3
+
+- allow optional Pi-native tool exposure while inheriting Pi defaults when unset
+
 ## 2026-10-14 - v0.5.2
 
 - stop Pi startup from scanning historical runs or closing recorded Herdr tabs

package/packages/herdr-subagents/README.md

@@ -89,10 +89,12 @@ The orchestrator is the only writer of `run.json`, `task.json`, and promoted `re
 
 `herdr_subagents_control` supports `list`, `status`, `history`, `cancel`, and `cleanup`. Follow-up work is a new task or run; settled tasks are never revived.
 
+When `exposure` is absent, both tools omit the registration field and inherit Pi's default exposure. Set `"exposure": "model-only"` to keep explicit top-level model calls while excluding Codemode scripts and other nested tools, or `"exposure": "direct"` to request Pi's direct-and-nested behavior explicitly. Exposure is read when the extension loads, so use `/reload` or restart Pi after changing it.
+
 Use `/herdr-subagents focus <task-number>` to focus a running pane. `/herdr-subagents active`, `history`, `agents`, `models`, and `settings` provide compact inspection.
 
 ## Personas and settings
 
 Bundled personas are `worker`, `explorer`, `analyst`, and `reviewer`. Project personas can be added under `.pi/agents/` using the same frontmatter format as the bundled files. Access is declared as `read` or `write` and drives concurrency safety.
 
-Settings are read from the existing package configuration. `defaultConcurrency`, `maxConcurrency`, and `stalledWarningSeconds` remain supported.
+Settings are read from `~/.pi/agent/herdr-subagents.json` and the project-level `.pi/herdr-subagents.json`, with the project value taking precedence. Optional `exposure` accepts Pi's `model-only` or `direct`; omitting it delegates to Pi. `defaultConcurrency`, `maxConcurrency`, and `stalledWarningSeconds` remain supported.

package/packages/herdr-subagents/TESTING.md

@@ -17,6 +17,7 @@ It verifies:
 - explicit failure when the process exits without a report;
 - parent cancellation of running and queued tasks;
 - startup isolation: a new Pi session neither mutates historical records nor closes their recorded Herdr tabs;
+- omitted exposure delegates both tools to Pi's default, while project configuration can consistently select model-only exposure;
 - immutable terminal task records;
 - idempotent duplicate reports and rejection of conflicting replacements;
 - keeping a settled child alive for focus-aware cleanup instead of force-exiting its TUI.

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

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { fileURLToPath } from "node:url";
 import type { AgentToolResult, ExtensionAPI, ExtensionCommandContext, Theme, ToolRenderResultOptions } from "@earendil-works/pi-coding-agent";
 import { Container, Editor, Text } from "@earendil-works/pi-tui";
-import { loadSubagentConfiguration } from "../src/config.ts";
+import { loadSubagentConfiguration, type ConfigurationPaths } from "../src/config.ts";
 import { CliHerdrAutomation, type HerdrAutomation } from "../src/herdr.ts";
 import { activeRunText } from "../src/monitor.ts";
 import { historyText, listSubagentHistory } from "../src/history.ts";
@@ -62,7 +62,7 @@ function renderToolResult(result: AgentToolResult<unknown>, _options: ToolRender
 	return new Text(content?.type === "text" ? content.text : "(no output)", 0, 0);
 }
 
-async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fleet: FleetController): Promise<void> {
+async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fleet: FleetController, registeredExposure: { value?: "direct" | "model-only"; source: string }): Promise<void> {
 	const section = args.trim() || "active";
 	if (section === "active") {
 		ctx.ui.notify(fleet.active ? activeRunText(fleet.active) : "No active Subagent run.", "info");
@@ -90,7 +90,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 lines = Object.entries(values).map(([key, value]) => `${key}=${String(value ?? "unset")} (${configuration.settingSources[key] ?? "built-in"})`);
+		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");
 		return;
@@ -100,6 +100,8 @@ async function handleHerdrCommand(args: string, ctx: ExtensionCommandContext, fl
 
 export interface HerdrSubagentsExtensionDependencies {
 	herdr?: HerdrAutomation;
+	configurationCwd?: string;
+	configurationPaths?: ConfigurationPaths;
 	execute?: typeof executeHerdrSubagents;
 	executeControl?: typeof executeHerdrSubagentsControl;
 	isEditor?: (value: unknown) => boolean;
@@ -121,6 +123,9 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	const herdr = dependencies.herdr ?? new CliHerdrAutomation();
 	const execute = dependencies.execute ?? executeHerdrSubagents;
 	const executeControl = dependencies.executeControl ?? executeHerdrSubagentsControl;
+	const registrationConfiguration = loadSubagentConfiguration(dependencies.configurationCwd ?? process.cwd(), packageAgentsDir, undefined, dependencies.configurationPaths);
+	const exposure = registrationConfiguration.settings.exposure;
+	const registeredExposure = { value: exposure, source: registrationConfiguration.settingSources.exposure ?? "Pi" };
 	const isEditorComponent = dependencies.isEditor ?? ((value: unknown) => value instanceof Editor);
 	const fleet = new FleetController(herdr, isEditorComponent, dependencies.createFleetWidget, dependencies.fleetWidgetRuntime);
 	const runControllers = new Map<string, AbortController>();
@@ -141,6 +146,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 
 	pi.registerTool({
 		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.",
 		promptSnippet: "Run focused work in visible Herdr subagents",
@@ -181,6 +187,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 
 	pi.registerTool({
 		name: "herdr_subagents_control",
+		...(exposure ? { exposure } : {}),
 		label: "Herdr Subagents Control",
 		description: "Inspect Herdr personas, query one run by ID, list run history, cancel active work, or remove an archived run. Use herdr_subagents to start new work.",
 		parameters: HerdrSubagentsControlParams,
@@ -231,7 +238,7 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.registerCommand("herdr-subagents", {
 		description: "Inspect effective subagent agents, models, and settings",
 		getArgumentCompletions: (prefix) => ["active", "history", "agents", "models", "settings", "focus "].filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value })),
-		handler: (args, ctx) => handleHerdrCommand(args, ctx, fleet),
+		handler: (args, ctx) => handleHerdrCommand(args, ctx, fleet, registeredExposure),
 	});
 }
 

package/packages/herdr-subagents/package.json

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

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

@@ -4,8 +4,10 @@ import { dirname, join } from "node:path";
 import { discoverPackageAgents, type AgentDefinition } from "./personas.ts";
 
 export type PersonaAccess = "read" | "write";
+export type SubagentToolExposure = "direct" | "model-only";
 export interface PersonaConfig { model?: string; thinking?: string; skills?: string[]; extensions?: string[]; }
 export interface SubagentConfig {
+	exposure?: SubagentToolExposure;
 	defaultConcurrency: number;
 	maxConcurrency: number;
 	stalledWarningSeconds: number;
@@ -32,6 +34,7 @@ export interface SubagentConfiguration {
 	diagnostics: string[];
 }
 interface ConfigFile {
+	exposure?: string;
 	defaultConcurrency?: number;
 	maxConcurrency?: number;
 	stalledWarningSeconds?: number;
@@ -61,6 +64,10 @@ function readConfig(path: string, source: string, diagnostics: string[]): Config
 
 function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, sources: Record<string, string>, diagnostics: string[]): SubagentConfig {
 	const result: SubagentConfig = { ...base, personas: { ...base.personas } };
+	if (input.exposure !== undefined) {
+		if (input.exposure === "direct" || input.exposure === "model-only") { result.exposure = input.exposure; sources.exposure = source; }
+		else diagnostics.push(`${source} exposure must be 'direct' or 'model-only'`);
+	}
 	for (const key of ["defaultConcurrency", "maxConcurrency", "stalledWarningSeconds"] as const) {
 		const value = input[key];
 		if (value === undefined) continue;

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

@@ -160,10 +160,11 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	writeFileSync(join(runDirectory, "run.json"), JSON.stringify(historicalRun));
 	writeFileSync(join(taskDirectory, "task.json"), JSON.stringify({ id: "historical-task", runId: "historical-run", order: 1, status: "completed", completedAt: historicalRun.completedAt }));
 	const events = new Map();
+	const registeredTools = new Map();
 	const herdrCalls = [];
 	registerHerdrSubagents({
 		on(name, handler) { events.set(name, handler); },
-		registerTool() {},
+		registerTool(tool) { registeredTools.set(tool.name, tool); },
 		registerCommand() {},
 	}, {
 		herdr: {
@@ -180,6 +181,18 @@ 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");
+	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" }));
+	const configuredTools = new Map();
+	registerHerdrSubagents({
+		on() {},
+		registerTool(tool) { configuredTools.set(tool.name, tool); },
+		registerCommand() {},
+	}, { herdr: {}, isEditor: () => false, configurationCwd: lifecycleRoot });
+	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");
 }
 
 {