@maxiaochao/pi-toolkit 0.13.4 → 0.13.6

package/packages/background-tasks/tests/notifications.mjs

@@ -0,0 +1,80 @@
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { test } from "node:test";
+import { piBinary } from "./runtime.mjs";
+
+test("native Codemode receives start guidance and exposes it to the model", () => {
+	const directory = mkdtempSync(join(tmpdir(), "pi-bg-guidance-"));
+	try {
+		const events = join(directory, "events.jsonl");
+		const output = execFileSync(piBinary, [
+			"--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "--no-session", "--offline",
+			"-e", "builtin:codemode", "-e", fileURLToPath(new URL("../extensions/background-tasks.ts", import.meta.url)),
+			"-e", fileURLToPath(new URL("fixtures/provider.ts", import.meta.url)),
+			"--tools", "codemode,background_task", "--model", "bg-fixture/deterministic", "-p", "SMOKE_GUIDANCE",
+		], { cwd: directory, encoding: "utf8", timeout: 30000,
+			env: { ...process.env, PI_CODING_AGENT_DIR: directory, PI_OFFLINE: "1", BG_SMOKE_EVENTS: events }, stdio: ["ignore", "pipe", "pipe"] });
+		assert.match(output, /Main agent is ready/);
+		const records = readFileSync(events, "utf8").trim().split("\n").map((line) => JSON.parse(line));
+		const started = records.find((entry) => entry.event === "tool_end" && entry.name === "background_task");
+		assert.equal(started.isError, false);
+		const guidance = started.result.structuredContent.guidance;
+		assert.equal(guidance, "完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。");
+		const codemode = records.find((entry) => entry.event === "tool_end" && entry.name === "codemode");
+		assert.equal(codemode.isError, false);
+		assert.ok(codemode.result.content.some((block) => block.type === "text" && block.text.includes(guidance)));
+		const requests = records.filter((entry) => entry.event === "request");
+		assert.ok(requests[0].backgroundDescription.includes(guidance));
+		assert.ok(requests[1].text.includes(guidance), "the next model request sees guidance printed from the programmatic result");
+	} finally { rmSync(directory, { recursive: true, force: true }); }
+});
+
+for (const mode of ["codemode", "direct"]) {
+	for (const reads of [0, 1, 4]) {
+		test(`real Pi ${mode} merges four completions before the next model call, excluding ${reads} consumed results`, () => {
+			const directory = mkdtempSync(join(tmpdir(), "pi-bg-notifications-"));
+			try {
+				const events = join(directory, "events.jsonl");
+				writeFileSync(join(directory, "settings.json"), JSON.stringify({ quietStartup: true, followUpMode: "one-at-a-time", steeringMode: "one-at-a-time" }));
+				const output = execFileSync(piBinary, [
+					"--no-extensions", "--no-skills", "--no-prompt-templates", "--no-themes", "--no-context-files", "--no-session", "--offline",
+					"-e", "builtin:codemode", "-e", process.env.BG_TEST_EXTENSION ?? fileURLToPath(new URL("../extensions/background-tasks.ts", import.meta.url)),
+					"-e", fileURLToPath(new URL("fixtures/notifications.ts", import.meta.url)),
+					"--tools", "codemode,background_task,synchronous_subagent_fixture", "--model", "bg-notifications/deterministic", "--mode", "json", "-p", "Run the synchronous subagent scenario",
+				], { cwd: directory, encoding: "utf8", timeout: 30000, env: { ...process.env, PI_CODING_AGENT_DIR: directory, PI_OFFLINE: "1", BG_NOTIFICATION_EVENTS: events, BG_NOTIFICATION_READS: String(reads), BG_NOTIFICATION_MODE: mode }, stdio: ["ignore", "pipe", "pipe"] });
+				assert.doesNotMatch(output, /Failed to load|Error loading|Fixture shell jobs did not finish/);
+				const records = readFileSync(events, "utf8").trim().split("\n").map((line) => JSON.parse(line));
+				const returned = records.find((entry) => entry.event === "returned");
+				assert.ok(returned, `the blocking tool finished all real shell jobs\n${output}`);
+				assert.equal(returned.tasks.length, 4);
+				assert.ok(returned.tasks.every((task) => task.status === "failed" && task.exit_code === 7));
+				const transcript = output.trim().split("\n").map((line) => JSON.parse(line));
+				const notifications = transcript.filter((entry) =>
+					(entry.type === "entry_appended" && entry.entry.customType === "background-task-finished") ||
+					(entry.type === "message_start" && entry.message.customType === "background-task-finished")
+				);
+				assert.equal(notifications.length, reads === 4 ? 0 : 1);
+				if (reads !== 4) {
+					const message = notifications[0].entry ?? notifications[0].message;
+					const tasks = message.details.tasks;
+					assert.equal(tasks.length, 4 - reads);
+					assert.ok(tasks.every((task) => !returned.consumed.includes(task.id)));
+					const toolEnd = transcript.findIndex((entry) => entry.type === "tool_execution_end" && entry.toolName === "synchronous_subagent_fixture");
+					assert.ok(toolEnd >= 0 && transcript.indexOf(notifications[0]) > toolEnd, "the notification cannot interrupt the synchronous tool");
+					assert.match(message.content, /Ended at: \d{4}-/);
+				}
+				const requests = records.filter((entry) => entry.event === "request");
+				assert.equal(requests.length, mode === "direct" ? 3 : 2, "no extra model turns after the final report");
+				const nextContext = JSON.stringify(requests.at(-1).messages);
+				assert.equal((nextContext.match(/\[Background task finished\]/g) ?? []).length, reads === 4 ? 0 : 1);
+				assert.doesNotMatch(nextContext, /FINAL_REPORT/, "completion is delivered before, not after, the final report");
+				const contextText = requests.at(-1).messages.flatMap((message) => typeof message.content === "string" ? [message.content] : (message.content ?? []).filter((block) => block.type === "text").map((block) => block.text)).join("\n");
+				for (const task of returned.tasks.filter((task) => !returned.consumed.includes(task.id))) assert.ok(contextText.includes(task.id));
+			} finally { rmSync(directory, { recursive: true, force: true }); }
+		});
+	}
+}

package/packages/background-tasks/tests/tui-smoke.py

@@ -138,12 +138,15 @@ try:
     shot('running')
     send('/bg output ' + first['id'])
     send('SMOKE_CANCEL')
-    wait(lambda: bool(finished('cancelled')), 'cancel follow-up')
-    wait(lambda: bool(finished('succeeded')), 'successful background follow-up')
+    wait(lambda: bool(finished('cancelled')), 'cancel notification')
+    wait(lambda: bool(finished('succeeded')), 'successful background notification')
     shot('completed')
     send('SMOKE_OUTPUT')
     wait(lambda: any(e.get('result', {}).get('structuredContent', {}).get('output') == 'BUILD SUCCESSFUL\n' for e in tools()), 'explicit output query')
-    wait(lambda: 'BACKGROUND_FOLLOWUP_RECEIVED' in raw, 'main agent automatic response')
+    wait(lambda: 'BACKGROUND_NOTIFICATION_RECEIVED' in raw, 'main agent automatic response')
+    pump(0.5)
+    notifications = [e for e in events() if e.get('event') == 'custom' and e.get('type') == 'background-task-finished']
+    assert len(notifications) == 2, 'Duplicate persisted busy/idle notifications'
     pump(5.3)
     shot('history')
 
@@ -174,7 +177,8 @@ try:
     (OUT / 'events.jsonl').write_text('\n'.join(json.dumps(e) for e in records) + '\n')
     (OUT / 'result.json').write_text(json.dumps({'passed': True, 'screenshots': screens,
         'checks': ['two jobs', 'third rejected', 'Codemode returns while jobs live', 'Scheduler coexistence', '/bg output',
-                   'cancel notification', 'success notification', 'main agent follow-up', '5-second terminal row', 'reload cleanup', 'new-session cleanup', 'quit cleanup']}, indent=2))
+                   'cancel notification', 'success notification', 'main agent notification', 'no duplicate persisted notifications',
+                   '5-second terminal row', 'reload cleanup', 'new-session cleanup', 'quit cleanup']}, indent=2))
 except Exception:
     (OUT / 'error.txt').write_text(traceback.format_exc())
     raise

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2026-10-22 - v0.7.4
+
+- preserve Codex patch editing in child allowlists and hide the parent shortcut footer hint
+- Hide the child parent-navigation footer hint and clear its legacy status on reload, while retaining `Alt+P`, `/parent`, and editor/plugin status.
+- Permit `apply_patch` in the persistent CLI allowlist only for Personas that allow `edit`; test actual Pi startup selection, read-only limits and native fallback instead of relying on mocked tool lists or status labels.
+
 ## 2026-10-22 - v0.7.3
 
 - keep Persona selection lists concise

package/packages/herdr-subagents/README.md

@@ -48,6 +48,10 @@ The tools and command are registered only when Pi is running inside Herdr with a
 
 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.
 
+Use `Alt+P` or `/parent` in a child to focus its parent Agent pane. The shortcut has no persistent footer hint. Other extensions' status text, such as Codex Edit's `editor: apply_patch`, remains visible when those extensions are loaded and their editing tools are active. Changing Persona extensions does not change an already running child.
+
+For a Persona whose `tools` includes `edit`, the child CLI also permits `apply_patch` so a trusted editing extension can switch protocols. This does not load an extension or enable both editors by itself. Personas without `edit` do not receive this permission, and a child without a patch extension keeps native `edit`.
+
 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

package/packages/herdr-subagents/TESTING.md

@@ -29,6 +29,8 @@ It verifies:
 - 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;
+- clearing the legacy parent shortcut footer hint while preserving other extension status, with `Alt+P` and `/parent` still focusing the exact parent pane;
+- adding `apply_patch` to the child CLI allowlist only when the Persona permits `edit`;
 - preserving the configured smoke model, thinking level, and authentication extensions while isolating unrelated settings;
 - project-over-global smoke configuration, explicit extension clearing, model overrides, and local-source paths after moving to a temporary directory.
 
@@ -40,6 +42,8 @@ Run extension source loading. The direct-Pi fixture resolves global `defaultExte
 npm run load-test --workspace @maxiaochao/pi-herdr-subagents
 ```
 
+The native CLI fixture also exercises an extension that switches `edit` to `apply_patch`. It checks the final active tools, not just status text: writable children retain the selected patch tool, read-only/no-editor children do not gain it, and children without the patch extension retain native `edit`. This deterministic probe does not call a model or test Codex Edit's parser.
+
 Run the real Herdr smoke test from a Herdr session:
 
 ```sh

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

@@ -96,7 +96,8 @@ export default function (pi: ExtensionAPI) {
 		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`);
+		// Remove the legacy hint on reload without touching editor/plugin status.
+		ctx.ui.setStatus("herdr-subagents-parent", undefined);
 	});
 	pi.registerTool({
 		name: "subagent_report",

package/packages/herdr-subagents/package.json

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

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

@@ -42,8 +42,11 @@ export function childPiArgs(task: LiveTaskRecord, systemPromptFile: string): str
 	for (const extension of task.extensions ?? []) args.push("--extension", extension);
 	if (task.model) args.push("--model", task.model);
 	if (task.thinking) args.push("--thinking", task.thinking);
-	if (task.tools?.length) args.push("--tools", [...new Set([...task.tools, "codemode", "subagent_report"])].join(","));
-	else args.push("--tools", "+codemode");
+	if (task.tools?.length) {
+		// Pi keeps this allowlist after startup, including editor protocol switches.
+		const editorTools = task.tools.includes("edit") ? ["apply_patch"] : [];
+		args.push("--tools", [...new Set([...task.tools, ...editorTools, "codemode", "subagent_report"])].join(","));
+	} else args.push("--tools", "+codemode");
 	for (const skill of task.skills ?? []) args.push("--skill", skill);
 	return args;
 }

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

@@ -108,6 +108,14 @@ 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");
+
+	const editorArgs = childPiArgs({ id: "editor", sessionFile: join(root, "editor.jsonl"), tools: ["read", "edit", "write"] }, join(root, "system.md"));
+	assert.deepEqual(editorArgs[editorArgs.indexOf("--tools") + 1].split(","), ["read", "edit", "write", "apply_patch", "codemode", "subagent_report"]);
+	const readonlyArgs = childPiArgs({ id: "readonly", sessionFile: join(root, "readonly.jsonl"), tools: ["read", "bash"] }, join(root, "system.md"));
+	assert.ok(!readonlyArgs[readonlyArgs.indexOf("--tools") + 1].split(",").includes("apply_patch"));
+	console.log("PASS edit-capable children allow the patch editor without adding it to read-only tool lists");
+
 	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

@@ -291,6 +291,42 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 	assert.match(notifications[1], /: (?:package|global|project), (?:read|write), model=.*thinking=.*tools=.*skills=.*extensions=/, "User-facing inspection must retain detailed configuration fields");
 }
 
+{
+	const previousParent = process.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID;
+	process.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID = "test-workspace:parent";
+	const handlers = new Map();
+	const commands = new Map();
+	const shortcuts = new Map();
+	const calls = [];
+	const statuses = new Map([
+		["herdr-subagents-parent", "alt+p parent"],
+		["codex-edit", "editor: apply_patch"],
+	]);
+	const ctx = { ui: { notify() {}, setStatus(key, value) { statuses.set(key, value); } } };
+	try {
+		registerSubagentReport({
+			registerTool() {},
+			registerCommand(name, command) { commands.set(name, command); },
+			registerShortcut(key, shortcut) { shortcuts.set(key, shortcut); },
+			on(name, handler) { handlers.set(name, handler); },
+			events: { on() {} },
+			async exec(command, args) { calls.push([command, args]); return { code: 0, stdout: "", stderr: "" }; },
+		});
+		await handlers.get("session_start")({}, ctx);
+		assert.equal(statuses.get("herdr-subagents-parent"), undefined, "child startup clears the old parent shortcut hint");
+		assert.equal(statuses.get("codex-edit"), "editor: apply_patch", "child navigation must not overwrite editor status");
+		await commands.get("parent").handler("", ctx);
+		await shortcuts.get("alt+p").handler(ctx);
+		assert.deepEqual(calls, [
+			["herdr", ["agent", "focus", "test-workspace:parent"]],
+			["herdr", ["agent", "focus", "test-workspace:parent"]],
+		], "the parent command and shortcut must remain functional without a footer hint");
+	} finally {
+		if (previousParent === undefined) delete process.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID;
+		else process.env.PI_HERDR_SUBAGENTS_PARENT_PANE_ID = previousParent;
+	}
+}
+
 {
 	const directory = join(root, "report-idempotency");
 	mkdirSync(directory, { recursive: true });

package/packages/herdr-subagents/tests/extension-sources-load.mjs

@@ -19,6 +19,15 @@ try {
 	}));
 	writeFileSync(join(packageDirectory, "extension.ts"), `export default function (pi) {
 		pi.registerCommand("package-extension", { description: "Package extension loaded", handler() {} });
+		pi.registerTool({
+			name: "apply_patch", label: "Patch editor probe", description: "Editing protocol selection probe",
+			parameters: { type: "object", properties: {}, additionalProperties: false },
+			async execute() { return { content: [], details: {} }; },
+		});
+		pi.on("session_start", () => {
+			const active = pi.getActiveTools();
+			if (active.includes("edit")) pi.setActiveTools([...active.filter((name) => name !== "edit"), "apply_patch"]);
+		});
 	}`);
 	writeFileSync(join(packageDirectory, "skills", "package-skill", "SKILL.md"), "---\nname: package-skill\ndescription: Package skill loading probe\n---\n# Probe\n");
 	writeFileSync(join(packageDirectory, "prompts", "package-prompt.md"), "Package prompt loading probe.");
@@ -58,6 +67,22 @@ try {
 	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 defaultExtensions file and package sources, including package skills/prompts despite discovery flags, without broadening the direct-Pi tool allowlist");
+
+	for (const [id, tools, extensions, expected] of [
+		["patch-editor", ["read", "edit", "write"], analyst.extensions, ["read", "write", "apply_patch", "subagent_report"]],
+		["no-editor", ["read", "write"], analyst.extensions, ["read", "write", "subagent_report"]],
+		["native-editor", ["read", "edit", "write"], [fileExtension, probe], ["read", "edit", "write", "subagent_report"]],
+	]) {
+		const childArgs = childPiArgs({ id, sessionFile: join(root, `${id}.jsonl`), tools, extensions }, join(root, "system.md"));
+		const builtin = childArgs.indexOf("builtin:codemode");
+		childArgs.splice(builtin - 1, 2);
+		const child = spawnSync(process.env.PI_TEST_BINARY?.trim() || "pi", [...childArgs, "--offline"], { cwd: root, env, encoding: "utf8", timeout: 30_000 });
+		assert.equal(child.error, undefined, String(child.error));
+		assert.equal(child.status, 0, child.stderr || child.stdout);
+		const actual = JSON.parse(readFileSync(resultPath, "utf8"));
+		assert.deepEqual([...actual.tools].sort(), [...expected].sort(), `${id}: the real CLI must preserve the selected editing protocol`);
+	}
+	console.log("PASS real Pi CLI permits apply_patch for edit-capable children, preserves native fallback, and denies it to read-only/no-editor children");
 } finally {
 	rmSync(root, { recursive: true, force: true });
 }

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

@@ -430,7 +430,7 @@ try {
 	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")));
+	check("child command and shortcut return to the exact parent Agent pane without a footer hint", childExecCalls.length === 2 && childExecCalls.every(([command, args]) => command === "herdr" && args.join(",") === "agent,focus,w1:p-parent") && childStatuses.every(([, value]) => value === undefined));
 	const reportToolDirectory = join(root, "child-report-tool");
 	const reportAttemptId = "11111111-1111-4111-8111-111111111111";
 	mkdirSync(reportToolDirectory, { recursive: true });