@maxiaochao/pi-toolkit 0.11.18 → 0.11.20

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 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
+
 ## 2026-10-14 - v0.11.18
 
 - simplify global worktree isolation guidance

package/package.json

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

@@ -107,6 +107,10 @@ There is no fixed drain delay and no transcript parsing. Pi retries are internal
 
 Writing the same report again is idempotent. A conflicting replacement is rejected.
 
-## Cancellation and recovery
+## Cancellation and shutdown
 
-Caller or parent-session cancellation aborts active waits, marks nonterminal tasks cancelled, and closes the owned Herdr tab. Startup recovery is scoped by recorded parent ownership and retains readers for prior record formats. Recovery never resumes or mutates an already terminal task.
+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,11 @@
+## 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
+
 ## 2026-10-14 - v0.5.1
 
 - fix focus-safe run cleanup and compact report output

package/packages/herdr-subagents/README.md

@@ -36,6 +36,8 @@ The reproducible source recording is retained as [`docs/demo.webm`](docs/demo.we
 
 Each task starts a single-task interactive Pi process in its own Herdr pane. Herdr first confirms the interactive Pi is ready, then the prompt is delivered exactly once. Prompt acknowledgement never decides task completion. Panes remain ordinary Herdr panes: they can be focused and inspected while work is running or after it settles. An early-finishing child stays at the Pi UI while sibling tasks continue. After the whole run settles, cleanup closes an unfocused run tab immediately or waits for the user to leave a focused run tab.
 
+Cleanup belongs to the Pi session that created the run. Starting a new Pi session never scans historical runs or closes their recorded Herdr tabs. If Pi terminates before shutdown cleanup runs, any surviving Subagent tab remains visible for explicit inspection or cleanup.
+
 ## Result protocol
 
 The child must call `subagent_report` once with a terminal status:
@@ -87,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

@@ -16,6 +16,8 @@ It verifies:
 - waiting through a delayed authoritative report after a prompt transport error while the Pi process is alive;
 - explicit failure when the process exits without a report;
 - parent cancellation of running and queued tasks;
+- 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,12 +2,11 @@ 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";
-import { cancelQueuedRuns, loadQueuedRuns } from "../src/queued-runs.ts";
-import { cancelActiveSubagentRuns, reconcileSubagentRuns } from "../src/reconcile.ts";
+import { cancelActiveSubagentRuns } from "../src/reconcile.ts";
 import { executeHerdrSubagents, executeHerdrSubagentsControl, type HerdrSubagentsBatchDetails, type HerdrSubagentsControlToolParams, type HerdrSubagentsRunParams } from "../src/tool.ts";
 import { HerdrSubagentsControlParams, HerdrSubagentsParams } from "../src/parameters.ts";
 import { HERDR_ACTIONS } from "../src/validation.ts";
@@ -63,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");
@@ -91,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;
@@ -101,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;
@@ -108,19 +109,6 @@ export interface HerdrSubagentsExtensionDependencies {
 	fleetWidgetRuntime?: FleetWidgetRuntime;
 }
 
-async function recoverParentSession(cwd: string, herdr: HerdrAutomation, owner: { sessionId?: string; processId: number }, notify: (message: string) => void): Promise<void> {
-	try {
-		const queued = await loadQueuedRuns(cwd, notify);
-		await cancelQueuedRuns(cwd, queued.map((run) => run.runId), { reason: "Owning parent Pi session is no longer active.", owner, onlyOrphaned: true, onError: notify });
-	}
-	catch (error) { notify(`Subagent queue recovery failed: ${error instanceof Error ? error.message : String(error)}`); }
-	try {
-		const reconciliation = await reconcileSubagentRuns(cwd, herdr, owner);
-		for (const message of reconciliation.cleanupErrors) notify(message);
-	}
-	catch (error) { notify(`Subagent recovery could not inspect active runs: ${error instanceof Error ? error.message : String(error)}`); }
-}
-
 async function shutdownParentSession(options: { cwd: string; herdr: HerdrAutomation; owner: { sessionId?: string; processId: number }; fleet: FleetController; sessionController: AbortController; runControllers: Map<string, AbortController>; inFlight: Set<Promise<unknown>>; notify: (message: string) => void }): Promise<void> {
 	options.sessionController.abort(new Error("Parent Pi session closed."));
 	for (const controller of options.runControllers.values()) controller.abort(new Error("Parent Pi session closed."));
@@ -135,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>();
@@ -146,16 +137,16 @@ export function registerHerdrSubagents(pi: ExtensionAPI, dependencies: HerdrSuba
 	pi.on("session_shutdown", async (_event, ctx) => {
 		await shutdownParentSession({ cwd: ctx.cwd, herdr, owner: { sessionId: ownerSessionId, processId: process.pid }, fleet, sessionController, runControllers, inFlight, notify: (message) => ctx.ui.notify(message, "error") });
 	});
-	pi.on("session_start", async (_event, ctx) => {
+	pi.on("session_start", (_event, ctx) => {
 		sessionController.abort(new Error("Parent Pi session changed."));
 		sessionController = new AbortController();
 		ownerSessionId = `${ctx.sessionManager.getSessionId()}:${randomUUID()}`;
 		fleet.bind(ctx.ui, ctx.mode === "tui");
-		await recoverParentSession(ctx.cwd, herdr, { sessionId: ownerSessionId, processId: process.pid }, (message) => ctx.ui.notify(message, "error"));
 	});
 
 	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",
@@ -196,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,
@@ -246,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.1",
+  "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

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { runHerdrSubagentsBatch } from "../src/batch-runner.ts";
 import registerSubagentReport from "../extensions/subagent-report.ts";
+import { registerHerdrSubagents } from "../extensions/herdr-subagents.ts";
 import { applyTaskStatus } from "../src/records.ts";
 
 process.env.HERDR_ENV = "1";
@@ -150,6 +151,50 @@ await assert.rejects(() => run([task("writer", "edit", "write"), task("reader",
 const terminal = { id: "task", runId: "run", order: 1, status: "completed" };
 assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are immutable/);
 
+{
+	const lifecycleRoot = join(root, "startup-history-isolation");
+	const runDirectory = join(lifecycleRoot, ".pi", "herdr-subagents", "runs", "historical-run");
+	const taskDirectory = join(runDirectory, "tasks", "01-task");
+	mkdirSync(taskDirectory, { recursive: true });
+	const historicalRun = { id: "historical-run", label: "historical", status: "completed", ownerSessionId: "old-session", ownerProcessId: 99999999, tabId: "w1:t-reused", taskIds: ["historical-task"], completedAt: "2026-10-01T00:00:00.000Z" };
+	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(tool) { registeredTools.set(tool.name, tool); },
+		registerCommand() {},
+	}, {
+		herdr: {
+			async isTabFocused(tabId) { herdrCalls.push(["isTabFocused", tabId]); return false; },
+			async closeTab(tabId) { herdrCalls.push(["closeTab", tabId]); },
+		},
+		isEditor: () => false,
+	});
+	await events.get("session_start")?.({}, {
+		cwd: lifecycleRoot,
+		mode: "rpc",
+		sessionManager: { getSessionId: () => "new-session" },
+		ui: { notify() {} },
+	});
+	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");
+}
+
 {
 	const directory = join(root, "report-idempotency");
 	mkdirSync(directory, { recursive: true });