@maxiaochao/pi-toolkit 0.10.4 → 0.10.5

package/CHANGELOG.md

@@ -1,3 +1,6 @@
+## 2026-10-08 - v0.10.5
+
+- bundle herdr-subagents v0.4.2: add Alt+P and /parent controls to return from child Agents
 ## 2026-10-08 - v0.10.4
 
 - bundle herdr-subagents v0.4.1: targeted cancellation, live token polling, and idempotent tab cleanup

package/package.json

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

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,8 @@
+## 2026-10-08 - v0.4.2
+
+- add Alt+P and /parent controls to return from child Agents
+- Add `/parent` and `Alt+P` inside child Agents to return focus to the exact parent Agent pane, with a visible child footer hint.
+
 ## 2026-10-08 - v0.4.1
 
 - targeted cancellation, live token polling, and idempotent tab cleanup

package/packages/herdr-subagents/README.md

@@ -76,7 +76,7 @@ Cancel one active or queued run with `herdr_subagents_control({ action: "cancel"
 
 While a batch is active, a compact Fleet monitor stays below the editor. Its divider/title row summarizes the run, and each task row shows a hollow or filled status circle, the real persona and task name, status, live active duration, and cumulative child Pi token usage in one compact shared metrics column after the longest row rather than at the terminal edge. Running work uses Pi's warning/yellow semantic color and completed work uses success/green. Token totals use the child session's persisted assistant, tool-result, standalone usage, compaction, and branch-summary usage; they are never estimated. Queued tasks show neither fabricated time nor tokens. The monitor follows Pi theme semantics, truncates by visible terminal columns, and refreshes session usage from both file events and the running one-second timer.
 
-With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback.
+With an empty editor, press `↓` to enter the list, `↑`/`↓` to choose a task, `Enter` to focus its exact pane, and `Esc` to return. `/herdr-subagents focus <task-number>` remains available as a fallback. Inside every child Agent, press `Alt+P` or run `/parent` to return to the exact parent Agent pane; the shortcut is also shown in the child footer.
 
 ## History
 

package/packages/herdr-subagents/TESTING.md

@@ -16,7 +16,7 @@
 - Force write-capable batches to serial execution while allowing bounded read-only parallelism.
 - Preserve compact reports, full results, Pi sessions, blocked questions, and historical follow-ups.
 - Recover queued/running work after interruption without retrying post-prompt side effects, including truncated reports and recovery errors.
-- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, and stable display while another background run queues.
+- Verify the split public contracts (`herdr_subagents` with required `tasks`, plus `herdr_subagents_control` with required `action`) and injectable extension wiring, including conditional registration only inside Herdr, Fleet rendering, editor focus ownership, terminal-input passthrough, exact-pane navigation, child `/parent` and `Alt+P` return controls, and stable display while another background run queues.
 - Verify Fleet divider/row formatting, warning/yellow running indicators, success/green completed indicators, persona and task projections, cumulative active duration across blocking/resume, exact Pi usage aggregation from assistant messages, tool results, standalone usage, compaction, and branch summaries, malformed/truncated JSONL tolerance, queued metric omission, and visible-column bounds at narrow widths.
 - Verify live token updates are file-event driven and polled on each running one-second tick, elapsed repainting exists only while work runs, and widget disposal closes watchers and timers.
 - Verify selected active/queued run cancellation, blocked-response live Fleet updates, authoritative stale-field replacement, parent-shutdown cancellation, idempotent missing-tab cleanup, cleanup notifications, atomic state replacement, non-retried uncertain startup operations, and stalled warnings.
@@ -24,4 +24,4 @@
 
 ## Latest baseline
 
-All 168 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.
+All 169 deterministic scheduler, recovery, process-boundary, schema-validation, navigation, metrics, responsive-formatting, and persona cases must pass. Release validation also requires extension loading and a real Herdr read-only batch smoke with distinct task panes and final tab cleanup. The latest smoke completed two concurrent tasks, retained its focused run tab through settlement, and closed it automatically after focus moved away.

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

@@ -4,6 +4,21 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { resultPathForAttempt } from "../src/result-path.ts";
+import { PARENT_PANE_ENV } from "../src/live-agent.ts";
+
+const RETURN_SHORTCUT = "alt+p";
+
+async function returnToParent(pi: ExtensionAPI, ctx: { ui: { notify(message: string, type?: "info" | "warning" | "error"): void } }): Promise<void> {
+	const parentPaneId = process.env[PARENT_PANE_ENV]?.trim();
+	if (!parentPaneId) {
+		ctx.ui.notify("Parent Agent pane is unavailable for this Subagent session.", "error");
+		return;
+	}
+	const result = await pi.exec("herdr", ["agent", "focus", parentPaneId]);
+	if (result.code !== 0) {
+		ctx.ui.notify(`Could not return to the parent Agent: ${result.stderr.trim() || result.stdout.trim() || `Herdr exited ${result.code}`}`, "error");
+	}
+}
 
 const ReportParams = Type.Object({
 	status: StringEnum(["completed", "needs-input", "failed"] as const, { description: "Current outcome for this task." }),
@@ -24,6 +39,17 @@ function writeAtomic(path: string, content: string): void {
 }
 
 export default function (pi: ExtensionAPI) {
+	pi.registerCommand("parent", {
+		description: "Return focus to the parent Agent pane",
+		async handler(_args, ctx) { await returnToParent(pi, ctx); },
+	});
+	pi.registerShortcut(RETURN_SHORTCUT, {
+		description: "Return to parent Agent",
+		async handler(ctx) { await returnToParent(pi, ctx); },
+	});
+	pi.on("session_start", async (_event, ctx) => {
+		if (process.env[PARENT_PANE_ENV]?.trim()) ctx.ui.setStatus("herdr-subagents-parent", `${RETURN_SHORTCUT} parent`);
+	});
 	pi.registerTool({
 		name: "subagent_report",
 		label: "Subagent Report",

package/packages/herdr-subagents/package.json

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

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

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { appendFile, mkdir, readFile, rm, rmdir } from "node:fs/promises";
 import { isAbsolute, join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
-import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
 import { writeJsonAtomic, writeTextAtomic } from "./state.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
@@ -144,7 +144,7 @@ async function resumeHistoricalTaskLocked(cwd: string, runId: string, taskNumber
 		let report: PersistedReport;
 		let status: "blocked" | "completed" | "failed";
 		try {
-			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: historical.recordDirectory };
+			const env = childEnvironment(historical.recordDirectory);
 			tab = await herdr.createTab({ workspaceId: process.env.HERDR_WORKSPACE_ID ?? "", cwd, label: `SA · ${run.label}`, env, focus: false, signal: options.signal });
 			const paneLabel = `${String(historical.order).padStart(2, "0")} · ${historical.name}`;
 			await herdr.renamePane(tab.paneId, paneLabel, options.signal);

package/packages/herdr-subagents/src/live-agent.ts

@@ -17,6 +17,17 @@ export interface LiveTaskRecord {
 	skills?: string[];
 }
 
+export const PARENT_PANE_ENV = "PI_HERDR_SUBAGENTS_PARENT_PANE_ID";
+
+export function childEnvironment(taskDirectory: string, environment: NodeJS.ProcessEnv = process.env): Record<string, string> {
+	const parentPaneId = environment.HERDR_PANE_ID?.trim();
+	return {
+		PI_HERDR_SUBAGENTS_CHILD: "1",
+		PI_HERDR_SUBAGENTS_TASK_DIR: taskDirectory,
+		...(parentPaneId ? { [PARENT_PANE_ENV]: parentPaneId } : {}),
+	};
+}
+
 export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): string[] {
 	const args = [
 		"--approve",

package/packages/herdr-subagents/src/run-pane-allocator.ts

@@ -3,6 +3,7 @@ import { writeJsonAtomic } from "./state.ts";
 import type { RunRecord } from "./records.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
+import { childEnvironment } from "./live-agent.ts";
 
 interface RunPaneAllocatorOptions {
 	herdr: HerdrAutomation;
@@ -31,7 +32,7 @@ export class RunPaneAllocator {
 		let paneId = "";
 		this.allocation = this.allocation.then(async () => {
 			const { herdr, run, runFile, signal } = this.options;
-			const env = { PI_HERDR_SUBAGENTS_CHILD: "1", PI_HERDR_SUBAGENTS_TASK_DIR: taskDirectory };
+			const env = childEnvironment(taskDirectory);
 			let anchorExists = Boolean(run.tabId && this.lastPaneId);
 			if (anchorExists && this.options.validateExistingPane) {
 				const survivingPaneIds: string[] = [];

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

@@ -3,7 +3,7 @@ import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CliHerdrAutomation, type HerdrAutomation } from "./herdr.ts";
 import { ensureRuntimeIgnored } from "./history.ts";
-import { liveAgentName, promptLiveAgent } from "./live-agent.ts";
+import { childEnvironment, liveAgentName, promptLiveAgent } from "./live-agent.ts";
 import { writeJsonAtomic } from "./state.ts";
 import { cleanupRunTab } from "./tab-cleanup.ts";
 import type { OwnerIdentity } from "./ownership.ts";
@@ -13,9 +13,6 @@ import { reportProtocolPrompt } from "./protocol.ts";
 import { applyRunStatus } from "./run-status.ts";
 import { isAbortError } from "./errors.ts";
 
-const CHILD_ENV = "PI_HERDR_SUBAGENTS_CHILD";
-const TASK_DIRECTORY_ENV = "PI_HERDR_SUBAGENTS_TASK_DIR";
-
 export type HerdrSubagentsDocument = PersistedDocument;
 export type HerdrSubagentsReport = PersistedReport;
 
@@ -168,10 +165,7 @@ export async function runHerdrSubagents(prompt: string, options: HerdrSubagentsO
 			workspaceId: process.env.HERDR_WORKSPACE_ID,
 			cwd,
 			label: `SA · ${label}`,
-			env: {
-				[CHILD_ENV]: "1",
-				[TASK_DIRECTORY_ENV]: taskDirectory,
-			},
+			env: childEnvironment(taskDirectory),
 			focus: false,
 			signal: options.signal,
 		});

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

@@ -23,6 +23,7 @@ import { applyTaskStatus, isSettledRunStatus, projectTaskActivity, readTaskRecor
 import { RunPaneAllocator } from "../src/run-pane-allocator.ts";
 import { aggregateTaskStatus } from "../src/run-status.ts";
 import { isAbortError } from "../src/errors.ts";
+import registerSubagentReport from "../extensions/subagent-report.ts";
 
 let passed = 0;
 let failed = 0;
@@ -313,7 +314,25 @@ try {
 	const outside = await runHerdrSubagents("hello", { cwd: root, herdr: unavailableHerdr });
 	check("Herdr is required", !outside.ok && outside.errorMessage?.includes("inside Herdr") && unavailableHerdr.calls.length === 0);
 
-	setEnv({ HERDR_ENV: "1", HERDR_WORKSPACE_ID: "w1", PI_HERDR_SUBAGENTS_PI_BINARY: "/definitely/missing/pi" });
+	setEnv({ HERDR_ENV: "1", HERDR_WORKSPACE_ID: "w1", HERDR_PANE_ID: "w1:p-parent", PI_HERDR_SUBAGENTS_PI_BINARY: "/definitely/missing/pi" });
+	const childCommands = new Map();
+	const childShortcuts = new Map();
+	const childEvents = new Map();
+	const childExecCalls = [];
+	const childStatuses = [];
+	registerSubagentReport({
+		registerTool() {},
+		registerCommand(name, options) { childCommands.set(name, options); },
+		registerShortcut(key, options) { childShortcuts.set(key, options); },
+		on(name, handler) { childEvents.set(name, handler); },
+		async exec(command, args) { childExecCalls.push([command, args]); return { stdout: "", stderr: "", code: 0, killed: false }; },
+	});
+	process.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID = "w1:p-parent";
+	const childContext = { ui: { notify() {}, setStatus(key, value) { childStatuses.push([key, value]); } } };
+	await childEvents.get("session_start")?.({}, childContext);
+	await childCommands.get("parent")?.handler("", childContext);
+	await childShortcuts.get("alt+p")?.handler(childContext);
+	check("child command and shortcut return to the exact parent Agent pane", childExecCalls.length === 2 && childExecCalls.every(([command, args]) => command === "herdr" && args.join(",") === "agent,focus,w1:p-parent") && childStatuses.some(([, value]) => value.includes("alt+p")));
 	const herdr = fakeHerdr();
 	const success = await runHerdrSubagents("Review authentication", {
 		cwd: root,
@@ -330,7 +349,7 @@ try {
 	const startRequest = herdr.calls.find(([name]) => name === "startAgent")[1];
 	check("named unfocused tab in parent workspace", createRequest.workspaceId === "w1" && createRequest.cwd === root && createRequest.label === "SA · auth-review" && createRequest.focus === false);
 	check("ordinary execution never steals pane focus", !herdr.calls.some(([name]) => name === "focusPane"));
-	check("child environment points at durable task", createRequest.env.PI_HERDR_SUBAGENTS_CHILD === "1" && createRequest.env.PI_HERDR_SUBAGENTS_TASK_DIR.includes(join(".pi", "herdr-subagents", "runs")));
+	check("child environment points at durable task and parent pane", createRequest.env.PI_HERDR_SUBAGENTS_CHILD === "1" && createRequest.env.PI_HERDR_SUBAGENTS_TASK_DIR.includes(join(".pi", "herdr-subagents", "runs")) && createRequest.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID === "w1:p-parent");
 	check("persistent isolated child Pi", startRequest.kind === "pi" && startRequest.paneId === "w1:p2" && startRequest.args.includes("--session") && startRequest.args.includes("--no-extensions") && startRequest.args.includes("--extension") && startRequest.args.includes("--no-skills") && startRequest.args.includes("--model") && startRequest.args.includes("fake/model") && startRequest.args.includes("--tools") && startRequest.args.includes("read,grep,subagent_report"));
 	const promptRequest = herdr.calls.find(([name]) => name === "promptAgent")[1];
 	check("prompt submitted through Herdr", promptRequest.prompt === "Review authentication" && promptRequest.target === startRequest.name);