@maxiaochao/pi-toolkit 0.13.12 → 0.13.14

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 2026-10-26 - v0.13.14
+
+- herdr-subagents v0.7.6: Esc in a child waits abortGraceSeconds (default 30) for a correction before publishing child_aborted
+
+## 2026-10-26 - v0.13.13
+
+- background-tasks v0.1.2: restrict background tasks to model-only and use concise automatic-notification guidance
+
 ## 2026-10-23 - v0.13.12
 
 - worktree v0.4.1: return the worktree root from already-active nested directories
@@ -54,6 +62,8 @@
 
 ## Unreleased
 
+- Background Tasks: fix tool exposure to `model-only` and shorten startup guidance to English, emphasizing automatic notification without sleep or polling.
+
 - OpenAI Account Pool: clear stranded `openai-codex` references after deleting the last real account and on startup, including stale membership left by external credential deletion.
 - OpenAI Account Pool: recover email labels from both profile and root-level token claims; cover removal persistence and last-account cleanup through the production extension and Pi credential cache.
 - Background Tasks: expose the approved non-polling startup guidance to direct and Codemode callers. Retain results after a user interrupt without restarting the agent, then hand them to the next user-message run; verify native tool batches, interrupts and compaction cancellation without changing Pi itself.

package/README.md

@@ -40,7 +40,7 @@ Restart Pi after updating. `pi update --extensions` has the same effect when upd
 
 Each child README owns its feature description, motivation or upstream alignment, examples, screenshots/demos, configuration, and test documentation.
 
-Background Tasks combines unread completions after any current tool batch, before the next model request, including when the main agent waits for a synchronous subagent. Idle completions wake the main agent automatically, except after a user interrupt: results remain available until the next user-message run. Reading a finished task's `output` through the tool consumes its pending reminder. Startup guidance tells direct and Codemode callers to continue independent work or end the turn, not query to wait. See [completion delivery](packages/background-tasks/README.md#user-controls-and-status).
+Background Tasks combines unread completions after any current tool batch, before the next model request, including when the main agent waits for a synchronous subagent. Idle completions wake the main agent automatically, except after a user interrupt: results remain available until the next user-message run. Reading a finished task's `output` through the tool consumes its pending reminder. The tool is fixed to `model-only`, not callable through Codemode. Startup guidance emphasizes automatic notification without sleep or polling. See [completion delivery](packages/background-tasks/README.md#user-controls-and-status).
 
 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).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-toolkit",
-  "version": "0.13.12",
+  "version": "0.13.14",
   "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/background-tasks/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026-10-26 - v0.1.2
+
+- restrict background tasks to model-only and use concise automatic-notification guidance
+- Fix `background_task` exposure to `model-only`; reject Codemode and other nested callers without adding a configuration file.
+- Use concise English startup guidance emphasizing automatic notification without sleep or polling.
+
 ## 2026-10-22 - v0.1.1
 
 - batch unread completions at tool boundaries, preserve interrupted runs, and provide non-polling startup guidance

package/packages/background-tasks/README.md

@@ -31,9 +31,11 @@ The complete `@maxiaochao/pi-toolkit` package **bundles and enables Background T
 background_task({ action: "start", command: "sleep 10; printf 'checks complete\\n'", description: "Delayed check", timeout: 120 })
 ```
 
-Each accepted start includes this exact guidance in the tool's text and `structuredContent.guidance`. The tool description carries it too, including for Codemode discovery:
+The tool is fixed to `exposure: "model-only"`: the model calls it directly; Codemode and other tools cannot call it. There is no exposure setting.
 
-> 完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。
+Each accepted start includes this guidance in the tool description, result text and `structuredContent.guidance`:
+
+> Notifies automatically on completion. Do not sleep or poll; continue other work or end the turn.
 
 After the completion notification, read the result:
 
@@ -79,7 +81,7 @@ Completion, failure, cancellation, timeout and output-limit termination update t
 - While idle, pending completions are combined on the next event-loop tick and wake the main agent once. Jobs that finish after that batch can produce another notification. Pi's global steering/follow-up queue settings are unchanged.
 - If another operation such as manual compaction keeps the session busy without an agent boundary, one local timer retries after 1, 2, 4, 8, 16, then 30 seconds, staying at 30 seconds thereafter. There is no retry-count limit or expiry that discards unread results. This does not call a model or poll shell output.
 - Normal tool/settlement boundaries still deliver immediately, without waiting for the retry timer. Without a boundary, an idle session can wait up to the current retry interval (at most 30 seconds, subject to native timer delays). Once a batch is delivered or fully consumed, the next batch starts with an immediate check and fresh backoff.
-- A successful tool `output` read of a finished task consumes its pending reminder, including failed tasks. This applies to direct and Codemode callers; a script that reads and filters a result has consumed it even if it does not print it. A running snapshot, `list`, a failed log read, or a user `/bg output` inspection does not consume the main agent's reminder. Consumption does not mean the task passed validation.
+- A successful tool `output` read of a finished task consumes its pending reminder, including failed tasks. A running snapshot, `list`, a failed log read, or a user `/bg output` inspection does not consume the main agent's reminder. Consumption does not mean the task passed validation.
 - Aborted/error boundaries do not request continuation or replay a previously scheduled wake. An error does not suppress later completions.
 - A user interrupt keeps the agent stopped: accepted jobs still run, but even later completions cannot restart it. Unread results remain queryable and are handed to the next user-message run before its first model request. Another extension's custom wake does not release this interrupt state; a new user-message run or session replacement does. This adds no notification pause switch.
 - Cancelling manual compaction is separate from interrupting the agent. Pending completions still wake an otherwise-idle session after compaction succeeds, fails or is cancelled.
@@ -95,7 +97,7 @@ Pi reports asynchronous message/run-start failures through its extension error c
 | View | Limit |
 | --- | --- |
 | Model-visible output | Last 2000 lines or 50 KiB, whichever is reached first, like Bash |
-| Codemode's `structuredContent.output` | Up to 1 MiB of raw log bytes; larger logs keep their first and last 512 KiB with an omission marker |
+| Internal `structuredContent.output` | Up to 1 MiB of raw log bytes; larger logs keep their first and last 512 KiB with an omission marker |
 | Disk capture | 32 MiB per task, 256 MiB total per session |
 
 Display/program-view truncation does **not** stop the command. Disk limits **do** stop the overflowing task with `output_limit`; a full session budget rejects new starts. Nothing silently evicts old logs.
@@ -104,22 +106,11 @@ Output includes a log path for further reads. `truncated` describes the program
 
 Output streams to private temporary logs (directory 0700, files 0600 on Unix), with bounded memory and range-limited reads. Log errors stop the task and are reported. Stdout and stderr are merged; strict ordering across the two streams is not promised. Logs and command arguments can contain secrets: choose commands accordingly.
 
-## Codemode and Bash
-
-Use Bash when you need a command's result before proceeding. Codemode composes tool calls and filters their results; it does not itself own background jobs.
+## Bash and background execution
 
-Codemode can start a managed job and finish immediately:
-
-```javascript
-const started = await tools.background_task({
-  action: "start",
-  command: "sleep 10; printf 'done\\n'",
-  timeout: 120,
-});
-text(started);
-```
+Use Bash when you need a command's result before proceeding. Use `background_task` directly when the command should keep running after the model's turn ends. Completion notifies the model automatically; do not add sleep or polling calls to wait for it.
 
-This prints the startup guidance as well as the task. Continue independent work or end the turn; do not keep a Codemode worker open to sleep or poll for completion. After notification, another script can read the result. Merely starting an unawaited Bash call is different: Codemode cancels unfinished nested calls when its script ends.
+Codemode cannot call this model-only tool. Starting an unawaited Bash call in Codemode is not a substitute: Codemode cancels unfinished nested calls when its script ends.
 
 The tool description is compact. This package adds no `promptGuidelines` or extra global system-prompt rules.
 

package/packages/background-tasks/TESTING.md

@@ -13,8 +13,8 @@ Tests use Node's built-in test runner. They resolve host peers from the installe
 - `tasks.mjs`: fake execution and clock at the task-manager interface; immediate return, two slots, validation, timeout/cancel races, final failure, disk budgets, write errors, bounded history and shutdown.
 - `output.mjs`: compares both output views with the real host Bash tool. Covers line/byte limits, long lines, empty output, missing final newline, UTF-8 split across chunks, invalid UTF-8 and logs larger than 1 MiB.
 - `processes.mjs`: the native backend, a multi-line Python log check, non-blocking concurrency, PID-observed process-tree cleanup, silent busy-loop timeout and the default 32 MiB disk limit.
-- `extension.mjs`: real extension registration with fake execution/clock; schema errors, command parity, parent-signal independence, merged busy/idle notifications, terminal-output consumption and failed-read retention, abort/error boundaries, manual-compaction-style busy intervals without agent boundaries, other extensions' draft preservation, no output in notifications, above-editor placement, five-second retention, narrow/CJK rendering, coexistence and non-TUI modes. Checks the exact approved startup guidance in both return paths and the tool description; verifies 24-hour retention after an interrupt, output consumption while stopped, custom-wake isolation and restoration of automatic delivery by a new user-message run.
-- `notifications.mjs`: isolated real Pi with direct tool batches or its native Codemode tool, default one-at-a-time queues and an offline provider. Four actual failing shell jobs finish while a synchronous tool stands in for a subagent. The next model request gets one merged notification, excluding zero, one or four consumed terminal outputs; no extra requests follow the final report. Also verifies that native Codemode and the next model request receive the exact startup guidance. The blocking tool is a fixture, not a real Herdr child. `BG_TEST_EXTENSION=/absolute/path/to/background-tasks.ts` can run the queue regressions against an older implementation.
+- `extension.mjs`: real extension registration with fake execution/clock; schema errors, command parity, parent-signal independence, merged busy/idle notifications, terminal-output consumption and failed-read retention, abort/error boundaries, manual-compaction-style busy intervals without agent boundaries, other extensions' draft preservation, no output in notifications, above-editor placement, five-second retention, narrow/CJK rendering, coexistence and non-TUI modes. Checks fixed `model-only` exposure and the concise English startup guidance in both return paths and the tool description; verifies 24-hour retention after an interrupt, output consumption while stopped, custom-wake isolation and restoration of automatic delivery by a new user-message run.
+- `notifications.mjs`: isolated real Pi with model-issued background calls, default one-at-a-time queues and an offline provider. Sequential blocking fixtures hold one native tool batch open across two waves of actual failing shell jobs. The blocking fixture runs directly or through native Codemode, but background calls always come from the model. The next model request gets one merged notification for four completions, excluding zero, one or two first-wave terminal outputs read directly by the model before the boundary; no extra requests follow the final report. Complete pending-batch consumption remains covered by the deterministic extension tests. Also verifies that the model receives the English guidance without a Codemode suffix, and that native Codemode cannot discover or call `background_task`. The blocking tool is a fixture, not a real Herdr child. `BG_TEST_EXTENSION=/absolute/path/to/background-tasks.ts` can run the queue regressions against an older implementation.
 - `compaction.mjs`: isolated native Pi SDK sessions call `session.compact()`, the same manual-compaction entry point used by `/compact` and RPC. Real shell jobs exit during a held offline summary request. Covers successful native compaction, a provider summary error and `abortCompaction()` cancellation; each must retain the pending completion while busy and automatically deliver it once afterward, without another user prompt. Checks actual compaction lifecycle/events, saved compaction entries, completion timestamps/logs and exactly one automatic conversation request. Uses real timers and native `isIdle`/`isCompacting`, not injected busy state or replacement compaction results; no paid model call or TUI keyboard invocation of `/compact`. `BG_TEST_EXTENSION` also supports a negative-control extension.
 - `interruptions.mjs`: isolated native Pi SDK sessions call the real `session.abort()` while a foreground tool is held. A real shell finishes before or after the interrupt; terminal timestamps verify the ordering. Native `agent_settled.aborted` must confirm the stop; no completion may start another model request. A new user prompt sees the retained completion in its first request, reads the real failed task's output, and finishes without duplicate delivery or extension errors. A third case starts actual manual compaction while the foreground tool is held: Pi itself interrupts the active agent, which must stay stopped even after compaction and background completion. The public abort event has no reason field, so the extension preserves this native interruption rather than guessing its source. `BG_TEST_EXTENSION` supports a negative control without interrupt suppression.
 
@@ -32,7 +32,7 @@ Requires Python 3 with the existing `pexpect` module; process fixtures use Bash,
 python3 packages/background-tasks/tests/tui-smoke.py .cache/verification/background-tui
 ```
 
-This starts a real Pi in a PTY with the production extension, Scheduler, the built-in Codemode tool and a deterministic fixture provider. It checks two jobs, rejection of a third, Codemode completion while jobs remain alive, explicit output, cancellation, automatic main-agent notification, reload/new/quit cleanup and log removal. It observes both persisted boundary entries and idle custom messages by unique session-entry ID, and rejects duplicate notifications. No network model calls occur. Mocked UI tests separately verify the exact five-second boundary.
+This starts a real Pi in a PTY with the production extension, Scheduler, the built-in Codemode tool and a deterministic fixture provider. It checks two jobs, rejection of a third, model turn completion while jobs remain alive and rejection of Codemode background calls, explicit output, cancellation, automatic main-agent notification, reload/new/quit cleanup and log removal. It observes both persisted boundary entries and idle custom messages by unique session-entry ID, and rejects duplicate notifications. No network model calls occur. Mocked UI tests separately verify the exact five-second boundary.
 
 Results and the actual ANSI stream are stored under the chosen evidence directory. Real screenshots require an isolated X11 terminal window, `gnome-terminal.real`, `xwininfo` and ImageMagick `import`:
 

package/packages/background-tasks/extensions/background-tasks.ts

@@ -7,7 +7,7 @@ import { BackgroundTasks, errorText, summary, systemClock, type Clock, type Task
 import { BackgroundWidget, FINISHED_VISIBLE_MS, WIDGET_KEY, duration, visibleTasks } from "../src/widget.ts";
 
 const actions = ["start", "list", "output", "cancel"] as const;
-const startGuidance = "完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。";
+const startGuidance = "Notifies automatically on completion. Do not sleep or poll; continue other work or end the turn.";
 type Action = typeof actions[number];
 interface Params {
 	action: Action;
@@ -23,7 +23,7 @@ const Parameters = Type.Object({
 	description: Type.Optional(Type.String({ description: "Short display label for start" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for start; defaults to the session directory. Relative paths resolve from it." })),
 	timeout: Type.Optional(Type.Integer({ minimum: 1, maximum: 7200, description: "Runtime limit for start, in seconds: default 1800 (30 minutes), maximum 7200 (2 hours); no unlimited mode" })),
-	id: Type.Optional(Type.String({ description: "Task ID for output or cancel; output shows the last 2000 lines or 50 KiB. Codemode receives up to 1 MiB, keeping head/tail if larger, plus a log path." })),
+	id: Type.Optional(Type.String({ description: "Task ID for output or cancel; output shows the last 2000 lines or 50 KiB, plus a log path." })),
 }, { additionalProperties: false });
 const TaskSchema = Type.Object({
 	id: Type.String(), status: StringEnum(["running", "succeeded", "failed", "cancelled", "timed_out", "output_limit"] as const),
@@ -240,6 +240,7 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 
 	pi.registerTool({
 		name: "background_task", label: "Background task",
+		exposure: "model-only",
 		description: `Start shell commands as background tasks and return task IDs immediately. Supports status, output, and cancellation. After start: ${startGuidance}`,
 		parameters: Parameters, outputSchema: OutputSchema,
 		annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
@@ -247,7 +248,7 @@ export default function (pi: ExtensionAPI, dependencies: { operations?: BashOper
 			try {
 				if (signal?.aborted) throw new Error("Tool call aborted before task acceptance");
 				const result = await perform(params, ctx?.cwd ?? context?.cwd ?? process.cwd());
-				// A terminal result was consumed by this tool's caller (including Codemode).
+				// A terminal result was consumed by the model.
 				// User /bg inspections and running snapshots do not acknowledge completion.
 				if (params.action === "output" && "task" in result.data && result.data.task.status !== "running") {
 					pending.delete(result.data.task.id);

package/packages/background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maxiaochao/pi-background-tasks",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Session-scoped background shell tasks with completion notifications for Pi.",
   "type": "module",
   "keywords": [

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

@@ -325,6 +325,7 @@ test("registration is compact, does not inject prompt rules or start session res
 	const h = harness();
 	try {
 		assert.equal(h.tool.name, "background_task");
+		assert.equal(h.tool.exposure, "model-only");
 		assert.match(h.tool.description, /return task IDs immediately/);
 		assert.ok(h.tool.description.length < 500);
 		assert.equal(h.tool.promptGuidelines, undefined);
@@ -344,9 +345,9 @@ test("start provides non-blocking next steps in both model text and structured r
 		const started = await h.tool.execute("start", { action: "start", command: "sleep 60" });
 		const { task, guidance } = started.structuredContent;
 		assert.equal(task.status, "running");
-		assert.equal(guidance, "完成会自动通知。现在不要查询等待；继续其他独立工作，没有其他工作就结束当前轮，收到通知后再取结果。");
-		assert.ok(started.content[0].text.includes(guidance), "ordinary tool callers must see the same guidance as Codemode");
-		assert.ok(h.tool.description.includes(guidance), "scripts that filter out guidance still discover the lifecycle in the tool description");
+		assert.equal(guidance, "Notifies automatically on completion. Do not sleep or poll; continue other work or end the turn.");
+		assert.ok(started.content[0].text.includes(guidance), "the start result must include the guidance");
+		assert.ok(h.tool.description.includes(guidance), "the tool description must include the same guidance");
 		assert.equal(h.tool.outputSchema.properties.guidance.type, "string");
 		assert.equal(h.tool.outputSchema.required?.includes("guidance") ?? false, false);
 		const list = await h.tool.execute("list", { action: "list" });

package/packages/background-tasks/tests/fixtures/notifications.ts

@@ -1,5 +1,5 @@
-// A blocking tool stands in for a synchronous subagent. Pi queues and shell jobs are real.
-import { appendFileSync, writeFileSync } from "node:fs";
+// Sequential fixture tools hold one native batch open; background calls remain model-issued.
+import { appendFileSync, existsSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 import { createAssistantMessageEventStream } from "@earendil-works/pi-ai";
@@ -8,32 +8,40 @@ import { Type } from "typebox";
 
 export default function (pi: ExtensionAPI) {
 	const record = (entry: unknown) => appendFileSync(process.env.BG_NOTIFICATION_EVENTS!, JSON.stringify(entry) + "\n");
+	const tasks = new Map<string, any>();
+	const consumed: string[] = [];
+	let finished = false;
 	pi.registerTool({
 		name: "synchronous_subagent_fixture", label: "Synchronous subagent fixture",
-		description: "Wait for four real shell jobs while holding one synchronous tool call open.",
-		parameters: Type.Object({ reads: Type.Number() }),
-		async execute(_id, { reads }, _signal, _update, ctx) {
-			record({ event: "waiting" });
-			writeFileSync(join(ctx.cwd, "release"), "ready");
-			const list = async () => (await ctx.executeTool("background_task", { action: "list" })).result.structuredContent as any;
-			const wait = async () => {
-				for (let i = 0; i < 1000; i++) {
-					const tasks = await list();
-					if (tasks.running === 0) return tasks.tasks;
-					await delay(5);
+		description: "Wait for two real shell jobs while holding one synchronous tool call open.",
+		parameters: Type.Object({ wave: Type.Number() }), executionMode: "sequential",
+		async execute(_id, { wave }, _signal, _update, ctx) {
+			record({ event: "waiting", wave });
+			writeFileSync(join(ctx.cwd, `release-${wave}`), "ready");
+			for (let i = 0; i < 1000; i++) {
+				if ([0, 1].every((job) => existsSync(join(ctx.cwd, `exited-${wave}-${job}`)))) {
+					// Exit markers precede process exit. Let the native shell backend settle.
+					await delay(100);
+					if (wave === 1) finished = true;
+					return { content: [{ type: "text", text: "Synchronous subagent returned; shell wave finished." }], details: undefined };
 				}
-				throw new Error("Fixture shell jobs did not finish");
-			};
-			await wait();
-			for (let i = 0; i < 2; i++) await ctx.executeTool("background_task", {
-				action: "start", command: "printf 'second wave\\n'; exit 7", description: `second wave ${i}`, timeout: 10,
-			});
-			const tasks = await wait();
-			for (const task of tasks.slice(0, reads)) await ctx.executeTool("background_task", { action: "output", id: task.id });
-			record({ event: "returned", tasks, consumed: tasks.slice(0, reads).map((task: any) => task.id) });
-			return { content: [{ type: "text", text: "Synchronous subagent returned; final build report is ready." }], details: undefined };
+				await delay(5);
+			}
+			throw new Error("Fixture shell jobs did not finish");
 		},
 	});
+	pi.on("tool_execution_end", (event) => {
+		if (event.toolName !== "background_task") return;
+		const data = event.result.structuredContent as any;
+		if (data?.task) tasks.set(data.task.id, data.task);
+		if (data?.action === "output" && data.task.status !== "running") consumed.push(data.task.id);
+	});
+	pi.on("context", () => {
+		if (finished) {
+			record({ event: "returned", tasks: [...tasks.values()], consumed });
+			finished = false;
+		}
+	});
 	let requests = 0;
 	pi.registerProvider("bg-notifications", {
 		name: "Offline notification fixture", baseUrl: "http://127.0.0.1:1", api: "bg-notifications", apiKey: "fixture-not-a-secret",
@@ -43,21 +51,23 @@ export default function (pi: ExtensionAPI) {
 			queueMicrotask(() => {
 				requests++;
 				record({ event: "request", number: requests, messages: context.messages });
-				const direct = process.env.BG_NOTIFICATION_MODE === "direct";
-				const toolTurn = requests === 1 || (direct && requests === 2);
-				const message: any = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: toolTurn ? "toolUse" : "stop",
+				const message: any = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: requests <= 2 ? "toolUse" : "stop",
 					usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
 				stream.push({ type: "start", partial: message });
-				if (toolTurn) {
-					const reads = Number(process.env.BG_NOTIFICATION_READS);
-					if (direct && requests === 1) {
-						for (let i = 0; i < 2; i++) message.content.push({ type: "toolCall", id: `direct-start-${i}`, name: "background_task", arguments: {
-							action: "start", command: "while [ ! -f release ]; do sleep 0.01; done; printf 'first wave\\n'; exit 7", description: `first wave ${i}`, timeout: 10,
-						} });
-					} else if (direct) message.content.push({ type: "toolCall", id: "direct-blocking-tool", name: "synchronous_subagent_fixture", arguments: { reads } });
-					else {
-						const code = `for (let i = 0; i < 2; i++) text(await tools.background_task({ action: "start", command: "while [ ! -f release ]; do sleep 0.01; done; printf 'first wave\\\\n'; exit 7", description: "first wave " + i, timeout: 10 }));\ntext(await tools.synchronous_subagent_fixture({ reads: ${reads} }));`;
-						message.content.push({ type: "toolCall", id: "notification-fixture", name: "codemode", arguments: { code } });
+				if (requests <= 2) {
+					// First start a pair to obtain IDs. The second native batch waits, starts
+					// another pair, waits again, and reads selected outputs before its boundary.
+					const wave = requests - 1;
+					if (requests === 2) message.content.push({ type: "toolCall", id: "wait-first-wave", name: "synchronous_subagent_fixture", arguments: { wave: 0 } });
+					for (let i = 0; i < 2; i++) message.content.push({ type: "toolCall", id: `start-${wave}-${i}`, name: "background_task", arguments: {
+						action: "start", command: `while [ ! -f release-${wave} ]; do sleep 0.01; done; printf 'wave ${wave}\\n'; touch exited-${wave}-${i}; exit 7`, description: `wave ${wave} job ${i}`, timeout: 10,
+					} });
+					if (requests === 2) {
+						if (process.env.BG_NOTIFICATION_MODE === "codemode") message.content.push({ type: "toolCall", id: "wait-second-wave", name: "codemode", arguments: { code: "text(await tools.synchronous_subagent_fixture({ wave: 1 }));" } });
+						else message.content.push({ type: "toolCall", id: "wait-second-wave", name: "synchronous_subagent_fixture", arguments: { wave: 1 } });
+						// Only first-wave IDs are known to the model before this batch returns.
+						const reads = Number(process.env.BG_NOTIFICATION_READS);
+						for (const task of [...tasks.values()].slice(0, reads)) message.content.push({ type: "toolCall", id: `read-${task.id}`, name: "background_task", arguments: { action: "output", id: task.id } });
 					}
 					for (let i = 0; i < message.content.length; i++) {
 						stream.push({ type: "toolcall_start", contentIndex: i, partial: message });

package/packages/background-tasks/tests/fixtures/provider.ts

@@ -8,6 +8,7 @@ export default function (pi: ExtensionAPI) {
 		if (process.env.BG_SMOKE_EVENTS) appendFileSync(process.env.BG_SMOKE_EVENTS, JSON.stringify(entry) + "\n");
 	};
 	let sequence = 0;
+	const tasks = new Map<string, any>();
 	const observedNotifications = new Set<string>();
 	pi.registerProvider("bg-fixture", {
 		name: "Offline background-task fixture", baseUrl: "http://127.0.0.1:1", api: "bg-fixture",
@@ -21,29 +22,38 @@ export default function (pi: ExtensionAPI) {
 				const tools = getCurrentTools(context.messages);
 				record({ event: "request", lastRole: last?.role, text: text.slice(0, 2000), tools: tools.map((tool) => tool.name),
 					backgroundDescription: tools.find((tool) => tool.name === "background_task")?.description });
-				let code: string | undefined;
+				const calls: { name: string; arguments: any }[] = [];
+				const call = (args: any) => calls.push({ name: "background_task", arguments: args });
 				if (last?.role !== "toolResult") {
-					if (text.includes("SMOKE_START")) code = `const a = await tools.background_task({ action: "start", command: "sleep 9; printf 'BUILD SUCCESSFUL\\\\n'", description: "Release build", timeout: 30 });
-const b = await tools.background_task({ action: "start", command: "sleep 300", description: "Cancel this task", timeout: 300 });
-const c = await tools.background_task({ action: "start", command: "printf third" });
-text({ first: a.task.id, second: b.task.id, third: c });`;
-					else if (text.includes("SMOKE_CANCEL")) code = `const list = await tools.background_task({ action: "list" });
-const task = list.tasks.find(t => t.description === "Cancel this task");
-text(await tools.background_task({ action: "cancel", id: task.id }));`;
-					else if (text.includes("SMOKE_OUTPUT")) code = `const list = await tools.background_task({ action: "list" });
-const task = list.tasks.find(t => t.description === "Release build");
-const result = await tools.background_task({ action: "output", id: task.id });
-text({ status: result.task.status, output: result.output });`;
-					else if (text.includes("SMOKE_LONG")) code = `text(await tools.background_task({ action: "start", command: "echo $$ > shell.pid; sleep 300 & echo $! > child.pid; wait", description: "Lifecycle cleanup check", timeout: 300 }));`;
-					else if (text.includes("SMOKE_GUIDANCE")) code = `text(await tools.background_task({ action: "start", command: "sleep 300", description: "Guidance check", timeout: 300 }));`;
+					if (text.includes("SMOKE_START")) {
+						call({ action: "start", command: "sleep 9; printf 'BUILD SUCCESSFUL\\n'", description: "Release build", timeout: 30 });
+						call({ action: "start", command: "sleep 300", description: "Cancel this task", timeout: 300 });
+						call({ action: "start", command: "printf third" });
+					} else if (text.includes("SMOKE_CANCEL")) {
+						call({ action: "cancel", id: tasks.get("Cancel this task").id });
+					} else if (text.includes("SMOKE_OUTPUT")) {
+						call({ action: "output", id: tasks.get("Release build").id });
+					} else if (text.includes("SMOKE_LONG")) {
+						call({ action: "start", command: "echo $$ > shell.pid; sleep 300 & echo $! > child.pid; wait", description: "Lifecycle cleanup check", timeout: 300 });
+					} else if (text.includes("SMOKE_GUIDANCE")) {
+						call({ action: "start", command: "sleep 300", description: "Guidance check", timeout: 300 });
+					} else if (text.includes("SMOKE_EXPOSURE")) {
+						calls.push({ name: "codemode", arguments: { code: `
+text({ discovered: ALL_TOOLS.some(t => t.name === "background_task"), available: "background_task" in tools });
+try { await tools.background_task({ action: "start", command: "touch should-not-exist" }); text("UNEXPECTED_SUCCESS"); }
+catch { text("BACKGROUND_CALL_BLOCKED"); }` } });
+					}
 				}
-				const message: any = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: code ? "toolUse" : "stop",
+				const message: any = { role: "assistant", api: model.api, provider: model.provider, model: model.id, timestamp: Date.now(), content: [], stopReason: calls.length ? "toolUse" : "stop",
 					usage: { input: 1, output: 1, cacheRead: 0, cacheWrite: 0, totalTokens: 2, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } } };
 				stream.push({ type: "start", partial: message });
-				if (code) {
-					message.content.push({ type: "toolCall", id: `fixture-${++sequence}`, name: "codemode", arguments: { code } });
-					stream.push({ type: "toolcall_start", contentIndex: 0, partial: message });
-					stream.push({ type: "toolcall_end", contentIndex: 0, toolCall: message.content[0], partial: message });
+				if (calls.length) {
+					for (const call of calls) {
+						const index = message.content.length;
+						message.content.push({ type: "toolCall", id: `fixture-${++sequence}`, ...call });
+						stream.push({ type: "toolcall_start", contentIndex: index, partial: message });
+						stream.push({ type: "toolcall_end", contentIndex: index, toolCall: message.content[index], partial: message });
+					}
 				} else {
 					const reply = text.includes("[Background task finished]") ? "BACKGROUND_NOTIFICATION_RECEIVED" : "Main agent is ready; accepted background tasks keep running.";
 					message.content.push({ type: "text", text: reply });
@@ -60,7 +70,12 @@ text({ status: result.task.status, output: result.output });`;
 		record({ event: "loaded", tools: pi.getAllTools().map((tool) => tool.name) });
 		if (ctx.hasUI) ctx.ui.setTitle("Pi Background Tasks Smoke");
 	});
-	pi.on("tool_execution_end", (event) => record({ event: "tool_end", name: event.toolName, isError: event.isError, result: event.result }));
+	pi.on("agent_settled", () => record({ event: "settled" }));
+	pi.on("tool_execution_end", (event) => {
+		const data = event.result.structuredContent as any;
+		if (event.toolName === "background_task" && data?.action === "start" && data.task) tasks.set(data.task.description, data.task);
+		record({ event: "tool_end", name: event.toolName, isError: event.isError, result: event.result });
+	});
 	pi.on("context", (_event, ctx) => {
 		// Both boundary entries and idle messages are persisted before the provider request.
 		// Key by entry ID so two actual notifications for the same tasks remain observable.

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

@@ -1,13 +1,13 @@
 import assert from "node:assert/strict";
 import { execFileSync } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, 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", () => {
+test("native model receives concise start guidance without Codemode instructions", () => {
 	const directory = mkdtempSync(join(tmpdir(), "pi-bg-guidance-"));
 	try {
 		const events = join(directory, "events.jsonl");
@@ -23,19 +23,44 @@ test("native Codemode receives start guidance and exposes it to the model", () =
 		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)));
+		assert.equal(guidance, "Notifies automatically on completion. Do not sleep or poll; continue other work or end the turn.");
+		assert.equal(records.some((entry) => entry.event === "tool_end" && entry.name === "codemode"), false);
 		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");
+		assert.ok(!requests[0].backgroundDescription.includes("Codemode:"));
+		assert.ok(requests[1].text.includes(guidance), "the next model request sees the startup guidance");
+	} finally { rmSync(directory, { recursive: true, force: true }); }
+});
+
+test("native Codemode cannot discover or call the model-only background tool", () => {
+	const directory = mkdtempSync(join(tmpdir(), "pi-bg-exposure-"));
+	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_EXPOSURE",
+		], { 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 codemode = records.find((entry) => entry.event === "tool_end" && entry.name === "codemode");
+		assert.equal(codemode.isError, false);
+		const text = codemode.result.content.filter((block) => block.type === "text").map((block) => block.text).join("\n");
+		assert.match(text, /"discovered":false/);
+		assert.match(text, /"available":false/);
+		assert.match(text, /BACKGROUND_CALL_BLOCKED/);
+		assert.doesNotMatch(text, /UNEXPECTED_SUCCESS/);
+		assert.equal(records.some((entry) => entry.event === "tool_end" && entry.name === "background_task"), false);
+		assert.equal(existsSync(join(directory, "should-not-exist")), false);
+		assert.ok(records.find((entry) => entry.event === "request").tools.includes("background_task"));
 	} 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`, () => {
+	for (const reads of [0, 1, 2]) {
+		test(`real Pi ${mode} blocker merges four completions, excluding ${reads} model-read results`, () => {
 			const directory = mkdtempSync(join(tmpdir(), "pi-bg-notifications-"));
 			try {
 				const events = join(directory, "events.jsonl");
@@ -51,26 +76,27 @@ for (const mode of ["codemode", "direct"]) {
 				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));
+				assert.equal(returned.consumed.length, reads);
+				assert.ok(returned.tasks.filter((task) => returned.consumed.includes(task.id)).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}-/);
-				}
+				assert.equal(notifications.length, 1);
+				const message = notifications[0].entry ?? notifications[0].message;
+				const tasks = message.details.tasks;
+				assert.equal(tasks.length, 4 - reads);
+				assert.ok(tasks.every((task) => task.status === "failed" && task.exit_code === 7));
+				assert.ok(tasks.every((task) => !returned.consumed.includes(task.id)));
+				assert.deepEqual([...returned.consumed, ...tasks.map((task) => task.id)].sort(), returned.tasks.map((task) => task.id).sort());
+				const toolEnd = transcript.findLastIndex((entry) => entry.type === "tool_execution_end" && ["synchronous_subagent_fixture", "codemode"].includes(entry.toolName));
+				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");
+				assert.equal(requests.length, 3, "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.equal((nextContext.match(/\[Background task finished\]/g) ?? []).length, 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));

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

@@ -126,15 +126,21 @@ try:
     assert loaded['tools'].count('background_task') == 1
     send('/schedule add 1h Check release status')
     wait(lambda: 'active schedule' in raw, 'Scheduler widget')
+    send('SMOKE_EXPOSURE')
+    wait(lambda: bool(tools('codemode')), 'Codemode exposure check')
+    assert 'BACKGROUND_CALL_BLOCKED' in str(tools('codemode')[-1]['result'])
+    assert not (work / 'should-not-exist').exists()
+    wait(lambda: any(e.get('event') == 'settled' for e in events()), 'exposure turn completion')
+    settled_count = len([e for e in events() if e.get('event') == 'settled'])
     send('SMOKE_START')
-    wait(lambda: len(tools()) >= 3 and any(e.get('name') == 'codemode' for e in tools('codemode')), 'Codemode startup batch')
+    wait(lambda: len(tools()) >= 3, 'model startup batch')
     starts = tools()[:3]
     assert not starts[0]['isError'] and not starts[1]['isError'] and starts[2]['isError'], starts
     first = starts[0]['result']['structuredContent']['task']
     second = starts[1]['result']['structuredContent']['task']
     assert first['status'] == second['status'] == 'running'
-    assert any('Script completed' in str(e.get('result')) for e in tools('codemode')), tools('codemode')
-    assert not finished('succeeded'), 'Sleeping job must survive Codemode completion'
+    wait(lambda: len([e for e in events() if e.get('event') == 'settled']) > settled_count, 'foreground turn completion')
+    assert not finished('succeeded'), 'Sleeping job must survive foreground turn completion'
     shot('running')
     send('/bg output ' + first['id'])
     send('SMOKE_CANCEL')
@@ -176,7 +182,7 @@ try:
     assert all(not Path(path).exists() for path in logs), 'Session logs were not removed'
     (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',
+        'checks': ['two jobs', 'third rejected', 'Codemode background calls blocked', 'model returns while jobs live', 'Scheduler coexistence', '/bg output',
                    '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:

package/packages/herdr-subagents/ARCHITECTURE.md

@@ -82,7 +82,7 @@ There is no global dispatcher, persisted background queue, blocked response lane
 
 Each task owns one Herdr pane and one single-task Pi process. Herdr first starts and detects the interactive Pi, then submits the prompt exactly once. At Pi’s final `agent_settled` boundary, the child extension records settled state but leaves the interactive process alive. The atomic report remains the authoritative task result. Early-finishing children remain visible while sibling tasks continue. Once the whole run settles, the orchestrator closes an unfocused owned tab immediately and defers a focused tab until the user leaves it, so Pi can restore the terminal normally.
 
-A completed round without a terminal report gets one child-side reminder at `agent_before_settle`. The marker is written before continuation. Another omission publishes an unconfirmed `missing_report` diagnostic; final errors use `child_error`. Native cancellation skips that boundary, so `agent_settled` publishes only `child_aborted`, never a model wake-up. Existing terminal reports are not replaced. None of this adds a parent monitoring loop.
+A completed round without a terminal report gets one child-side reminder at `agent_before_settle`. The marker is written before continuation. Another omission publishes an unconfirmed `missing_report` diagnostic; final errors use `child_error`. A user abort (Esc) skips that boundary. `agent_settled(aborted)` starts a grace timer (`abortGraceSeconds`, default 30); a new round (`before_agent_start`) or session shutdown clears it, otherwise it publishes `child_aborted`. Existing terminal reports are not replaced. None of this adds a parent monitoring loop.
 
 The child writes:
 

package/packages/herdr-subagents/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 2026-10-26 - v0.7.6
+
+- Esc in a child waits abortGraceSeconds (default 30) for a correction before publishing child_aborted
+
 ## 2026-10-23 - v0.7.5
 
 - bound missing-report recovery and close unconfirmed child outcomes

package/packages/herdr-subagents/README.md

@@ -175,6 +175,7 @@ These are all supported top-level fields in `herdr-subagents.json`:
 | `defaultConcurrency` | Positive integer | `1` | Concurrency used when a call omits `concurrency`; capped to `maxConcurrency`. |
 | `maxConcurrency` | Positive integer | `4` | Hard ceiling for requested/default read-only concurrency. It does not make write-capable batches safe. |
 | `stalledWarningSeconds` | Positive integer | `300` | Emit a warning after a child runs this long. This is not a timeout and does not stop it. |
+| `abortGraceSeconds` | Positive integer | `30` | After the user aborts a child with Esc, wait this long for a correction. If no new round starts, publish an unconfirmed `child_aborted` failure. |
 | `defaultModel` | Non-empty Pi model ID, normally `provider/model` | Unset | Fallback child model. If unset, the parent model is inherited. |
 | `defaultThinking` | Non-empty Pi thinking value | Unset | Fallback thinking level below Persona-specific settings. Typical Pi values are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`; model support varies. |
 | `defaultExtensions` | Array of non-empty Pi source strings | Unset (no optional extensions) | Fallback extension sources for Personas without an explicit `extensions` list. Project replaces global; `[]` clears inherited defaults. |
@@ -219,6 +220,7 @@ Save this as `~/.pi/agent/herdr-subagents.json`. Model IDs, skills, and extensio
   "defaultConcurrency": 2,
   "maxConcurrency": 4,
   "stalledWarningSeconds": 300,
+  "abortGraceSeconds": 30,
   "defaultModel": "anthropic/claude-sonnet-4-5",
   "defaultThinking": "medium",
   "defaultExtensions": ["~/.pi/agent/extensions/provider-routing.ts"],
@@ -354,6 +356,6 @@ See [TESTING.md](TESTING.md) for deterministic tests, extension loading, packagi
 
 The child checks `reports/<attempt-id>.json` at `agent_before_settle`. A valid completed or failed report adds zero requests. A normally completed round without a report receives one reminder to submit existing results, not redo the task. `attempts/<attempt-id>.reminded` is persisted before continuing; rounds and reloads cannot reset it.
 
-A second omission produces a `failed` protocol report with `error: missing_report`, an explicitly **unconfirmed** result, and the child session path. This does not assert the delegated work itself failed. Final provider errors produce `child_error` without a reminder. Pi skips before-settle on cancellation; the child writes `child_aborted` at `agent_settled`, without waking the model or replacing an existing report. Parent-requested cancellation retains its existing cancelled lifecycle.
+A second omission produces a `failed` protocol report with `error: missing_report`, an explicitly **unconfirmed** result, and the child session path. This does not assert the delegated work itself failed. Final provider errors produce `child_error` without a reminder. A user abort (Esc) skips before-settle. The child waits `abortGraceSeconds` (default 30) for a correction; a new round cancels the timer and the child continues. If nothing starts in time, it publishes an unconfirmed `child_aborted` failure. Parent-requested cancellation retains its existing cancelled lifecycle.
 
 The parent still waits for an atomic attempt report or process exit. It does not infer success from idle/settled or run a second reminder monitor. Report idempotency and focus-aware tab cleanup are unchanged.

package/packages/herdr-subagents/TESTING.md

@@ -60,9 +60,9 @@ For real smoke testing, verify that each child appears in a visible pane and can
 
 ## Missing-report regressions
 
-`tests/report-boundary.mjs` checks completed/failed report idempotency, one durable reminder across rounds and extension reload, conflicting report rejection, unconfirmed diagnostics with a session path, and cancellation/error without continuation.
+`tests/report-boundary.mjs` checks completed/failed report idempotency, one durable reminder across rounds and extension reload, conflicting report rejection, unconfirmed diagnostics with a session path, Esc grace period (timer cancelled by steering or shutdown, `child_aborted` after expiry), and error without continuation.
 
-`tests/report-lifecycle.mjs` uses the real installed Pi SDK and a fully offline provider. It covers ten cases: normal report, failed report, successful reminder, repeated omission, transient retry, exhausted retry, queued follow-up, another before-settle continuation, cancellation, and a fresh prompt from a settled listener. A normal report makes one request; a reminder adds at most one. Native cancellation does not emit before-settle and must still get a terminal diagnostic. These are native lifecycle checks, not a claim of real-Herdr pane/concurrency coverage.
+`tests/report-lifecycle.mjs` uses the real installed Pi SDK and a fully offline provider. It covers ten cases: normal report, failed report, successful reminder, repeated omission, transient retry, exhausted retry, queued follow-up, another before-settle continuation, Esc abort, and a fresh prompt from a settled listener. A normal report makes one request; a reminder adds at most one. Native abort does not emit before-settle; its terminal diagnostic appears only after `abortGraceSeconds` (set to 1 in the test). These are native lifecycle checks, not a claim of real-Herdr pane/concurrency coverage.
 
 Use `PI_TEST_BINARY` to select Pi 1.4.0 for these checks rather than an older workspace-local Pi. No paid model or real credential is used by the new regression fixtures.
 

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

@@ -89,7 +89,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, defaultExtensions: JSON.stringify(settings.defaultExtensions ?? []) };
+		const values: Record<string, string | number | undefined> = { defaultConcurrency: settings.defaultConcurrency, maxConcurrency: settings.maxConcurrency, stalledWarningSeconds: settings.stalledWarningSeconds, abortGraceSeconds: settings.abortGraceSeconds, defaultModel: settings.defaultModel, defaultThinking: settings.defaultThinking, defaultExtensions: JSON.stringify(settings.defaultExtensions ?? []) };
 		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");

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

@@ -9,6 +9,10 @@ import { parseReport } from "../src/records.ts";
 import { resultPathForAttemptId } from "../src/result-path.ts";
 import { PARENT_PANE_ENV } from "../src/live-agent.ts";
 import { attemptReportPath, attemptStatePath, requireAttemptId, type AttemptState } from "../src/attempts.ts";
+import { loadSubagentConfiguration } from "../src/config.ts";
+import { fileURLToPath } from "node:url";
+
+const packageAgentsDir = fileURLToPath(new URL("../agents/", import.meta.url));
 
 const RETURN_SHORTCUT = "alt+p";
 
@@ -108,7 +112,10 @@ function reportHerdrState(state: "working" | "blocked" | "idle", message?: strin
 export default function (pi: ExtensionAPI) {
 	let activeAttemptId: string | undefined;
 	let blockedCount = 0;
+	let abortTimer: ReturnType<typeof setTimeout> | undefined;
+	const clearAbortTimer = () => { if (abortTimer) clearTimeout(abortTimer); abortTimer = undefined; };
 	pi.on("before_agent_start", async () => {
+		clearAbortTimer(); // The user steered the child after Esc.
 		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
 		if (!taskDirectory) return;
 		activeAttemptId = currentAttemptId(taskDirectory);
@@ -144,19 +151,25 @@ export default function (pi: ExtensionAPI) {
 				if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
 			}
 		}
-		const reason = event.outcome === "completed" ? "missing_report" : event.outcome === "aborted" ? "child_aborted" : "child_error";
+		// Esc normally skips this boundary; if it lands mid-boundary, still let the user steer.
+		if (event.outcome === "aborted") return;
+		const reason = event.outcome === "completed" ? "missing_report" : "child_error";
 		saveUnconfirmed(taskDirectory, attemptId, reason, ctx.sessionManager.getSessionFile());
-		// Cancellation and final provider errors receive a diagnostic, never a wake-up.
+		// Final provider errors receive a diagnostic, never a wake-up.
 	});
 	pi.on("agent_settled", (event, ctx) => {
 		const taskDirectory = process.env.PI_HERDR_SUBAGENTS_TASK_DIR?.trim();
-		if (taskDirectory && activeAttemptId) {
-			// Pi skips before-settle on cancellation. Close the protocol without
-			// claiming the work failed, replacing a report, or requesting more tokens.
-			if (event.aborted && !existsSync(attemptReportPath(taskDirectory, activeAttemptId))) {
-				saveUnconfirmed(taskDirectory, activeAttemptId, "child_aborted", ctx.sessionManager.getSessionFile());
-			}
-			writeAttemptState(taskDirectory, activeAttemptId, "settled");
+		if (event.aborted && taskDirectory && activeAttemptId) {
+			// Esc skips before-settle. Give the user time to steer; if nothing starts a new
+			// round within the grace period, close the attempt with an unconfirmed diagnostic.
+			const attemptId = activeAttemptId;
+			const sessionFile = ctx.sessionManager.getSessionFile();
+			const graceMs = loadSubagentConfiguration(ctx.cwd, packageAgentsDir).settings.abortGraceSeconds * 1000;
+			clearAbortTimer();
+			abortTimer = setTimeout(() => {
+				abortTimer = undefined;
+				if (!existsSync(attemptReportPath(taskDirectory, attemptId))) saveUnconfirmed(taskDirectory, attemptId, "child_aborted", sessionFile);
+			}, graceMs);
 		}
 		// Keep the interactive child alive at Pi's final automatic-work boundary.
 		// The orchestrator settles each task from its atomic report. Once every task in
@@ -176,6 +189,7 @@ export default function (pi: ExtensionAPI) {
 		description: "Return to parent Agent",
 		async handler(ctx) { await returnToParent(pi, ctx); },
 	});
+	pi.on("session_shutdown", clearAbortTimer);
 	pi.on("session_start", async (_event, ctx) => {
 		// Remove the legacy hint on reload without touching editor/plugin status.
 		ctx.ui.setStatus("herdr-subagents-parent", undefined);

package/packages/herdr-subagents/package.json

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

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

@@ -11,6 +11,7 @@ export interface SubagentConfig {
 	defaultConcurrency: number;
 	maxConcurrency: number;
 	stalledWarningSeconds: number;
+	abortGraceSeconds: number;
 	defaultModel?: string;
 	defaultThinking?: string;
 	defaultExtensions?: string[];
@@ -39,6 +40,7 @@ interface ConfigFile {
 	defaultConcurrency?: number;
 	maxConcurrency?: number;
 	stalledWarningSeconds?: number;
+	abortGraceSeconds?: number;
 	defaultModel?: string;
 	defaultThinking?: string;
 	defaultExtensions?: string[];
@@ -50,7 +52,7 @@ export interface ConfigurationPaths {
 	globalAgents?: string;
 	projectAgents?: string;
 }
-const DEFAULTS: SubagentConfig = { defaultConcurrency: 1, maxConcurrency: 4, stalledWarningSeconds: 300, personas: {} };
+const DEFAULTS: SubagentConfig = { defaultConcurrency: 1, maxConcurrency: 4, stalledWarningSeconds: 300, abortGraceSeconds: 30, personas: {} };
 
 function readConfig(path: string, source: string, diagnostics: string[]): ConfigFile {
 	if (!existsSync(path)) return {};
@@ -70,7 +72,7 @@ function mergeConfig(base: SubagentConfig, input: ConfigFile, source: string, so
 		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) {
+	for (const key of ["defaultConcurrency", "maxConcurrency", "stalledWarningSeconds", "abortGraceSeconds"] as const) {
 		const value = input[key];
 		if (value === undefined) continue;
 		if (!Number.isInteger(value) || Number(value) <= 0) { diagnostics.push(`${source} ${key} must be a positive integer`); continue; }
@@ -121,7 +123,7 @@ export function loadSubagentConfiguration(cwd: string, packageAgentsDirectory: s
 	const projectConfigPath = paths.projectConfig ?? join(cwd, ".pi", "herdr-subagents.json");
 	const globalAgentsDirectory = paths.globalAgents ?? join(dirname(globalConfigPath), "herdr-subagents", "agents");
 	const projectAgentsDirectory = paths.projectAgents ?? join(cwd, ".pi", "herdr-subagents", "agents");
-	const settingSources: Record<string, string> = { defaultConcurrency: "built-in", maxConcurrency: "built-in", stalledWarningSeconds: "built-in" };
+	const settingSources: Record<string, string> = { defaultConcurrency: "built-in", maxConcurrency: "built-in", stalledWarningSeconds: "built-in", abortGraceSeconds: "built-in" };
 	const globalInput = readConfig(globalConfigPath, "global", diagnostics);
 	const projectInput = readConfig(projectConfigPath, "project", diagnostics);
 	const globalSettings = mergeConfig(DEFAULTS, globalInput, "global", settingSources, diagnostics);

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

@@ -357,8 +357,6 @@ assert.throws(() => applyTaskStatus(terminal, "running"), /terminal tasks are im
 		process.exit = originalExit;
 	}
 	assert.equal(exitCode, undefined, "settled child must remain alive for focus-aware tab cleanup");
-	const attempt = JSON.parse(readFileSync(join(directory, "attempts", `${attemptId}.json`), "utf8"));
-	assert.equal(attempt.state, "settled");
 	const theme = { fg: (_color, text) => text, bold: (text) => text };
 	const renderedCall = reportTool.renderCall({ ...report, result: "FULL RESULT MUST NOT RENDER" }, theme).render(120).join("\n");
 	assert.match(renderedCall, /completed.*saved to disk/);

package/packages/herdr-subagents/tests/report-boundary.mjs

@@ -3,6 +3,7 @@ import { randomUUID } from "node:crypto";
 import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { mkdirSync } from "node:fs";
 import registerReport from "../extensions/subagent-report.ts";
 
 const root = mkdtempSync(join(tmpdir(), "herdr-report-boundary-"));
@@ -10,7 +11,9 @@ const previous = process.env.PI_HERDR_SUBAGENTS_TASK_DIR;
 process.env.PI_HERDR_SUBAGENTS_TASK_DIR = root;
 const sessionFile = join(root, "session.jsonl");
 writeFileSync(sessionFile, "");
-const ctx = { sessionManager: { getSessionFile: () => sessionFile }, isIdle: () => true };
+mkdirSync(join(root, ".pi"));
+writeFileSync(join(root, ".pi", "herdr-subagents.json"), JSON.stringify({ abortGraceSeconds: 1 }));
+const ctx = { cwd: root, sessionManager: { getSessionFile: () => sessionFile }, isIdle: () => true };
 function fixture() {
   const handlers = new Map();
   let tool;
@@ -58,14 +61,44 @@ try {
   assert.ok(diagnostic.documents.some(({ path }) => path === sessionFile));
   assert.equal(await reloaded.handlers.get("agent_before_settle")(boundary(), ctx), undefined);
 
-  for (const outcome of ["aborted", "error"]) {
+  {
     const current = attempt();
     const run = fixture();
     await run.handlers.get("before_agent_start")();
-    assert.equal(await run.handlers.get("agent_before_settle")(boundary(outcome), ctx), undefined, `${outcome}: do not wake or retry the child`);
+    assert.equal(await run.handlers.get("agent_before_settle")(boundary("aborted"), ctx), undefined);
+    assert.equal(existsSync(current.report), false, "Esc abort must not publish a terminal report; the user may steer");
+  }
+  {
+    // Esc skips before-settle and only emits agent_settled(aborted). Grace period, configurable.
+    const current = attempt();
+    const run = fixture();
+    await run.handlers.get("before_agent_start")();
+    await run.handlers.get("agent_settled")({ aborted: true }, ctx);
+    assert.equal(existsSync(current.report), false, "no report inside the grace period");
+    await run.handlers.get("before_agent_start")(); // user steers: timer must be cancelled
+    await new Promise((resolve) => setTimeout(resolve, 1300));
+    assert.equal(existsSync(current.report), false, "steering within the grace period cancels the diagnostic");
+    await run.handlers.get("agent_settled")({ aborted: true }, ctx);
+    await new Promise((resolve) => setTimeout(resolve, 1300));
+    const report = JSON.parse(readFileSync(current.report, "utf8"));
+    assert.equal(report.error, "child_aborted");
+    assert.match(report.summary, /unconfirmed/);
+    const shutdown = fixture(); // shutdown must clear a pending timer
+    const other = attempt();
+    await shutdown.handlers.get("before_agent_start")();
+    await shutdown.handlers.get("agent_settled")({ aborted: true }, ctx);
+    shutdown.handlers.get("session_shutdown")();
+    await new Promise((resolve) => setTimeout(resolve, 1300));
+    assert.equal(existsSync(other.report), false, "session shutdown clears the grace timer");
+  }
+  {
+    const current = attempt();
+    const run = fixture();
+    await run.handlers.get("before_agent_start")();
+    assert.equal(await run.handlers.get("agent_before_settle")(boundary("error"), ctx), undefined, "error: do not wake or retry the child");
     const report = JSON.parse(readFileSync(current.report, "utf8"));
     assert.equal(report.status, "failed");
-    assert.equal(report.error, outcome === "aborted" ? "child_aborted" : "child_error");
+    assert.equal(report.error, "child_error");
     assert.match(report.summary, /unconfirmed/);
   }
   const repaired = attempt();

package/packages/herdr-subagents/tests/report-lifecycle.mjs

@@ -18,6 +18,7 @@ try{
   const dir=join(root,scenario);mkdirSync(dir);
   const attemptId=randomUUID();const statePath=join(dir,'attempts',attemptId+'.json');
   process.env.PI_HERDR_SUBAGENTS_TASK_DIR=dir;
+  if(scenario==='abort'){mkdirSync(join(dir,'.pi'));writeFileSync(join(dir,'.pi','herdr-subagents.json'),JSON.stringify({abortGraceSeconds:1}));}
   writeFileSync(join(dir,'task.json'),JSON.stringify({currentAttemptId:attemptId}));
   const trace=[],states=[],errors=[],inputs=[];let requests=0,ended=0,boundaries=0,settled=0;
   const entered=Promise.withResolvers();let session;
@@ -52,6 +53,7 @@ try{
    const running=session.prompt('Run offline lifecycle check');
    if(scenario==='abort'){await entered.promise;await session.abort();}
    await running;
+   if(scenario==='abort'){assert.equal(existsSync(join(dir,'reports',attemptId+'.json')),false,'no report inside the grace period');await new Promise(r=>setTimeout(r,1500));}
    assert.equal(errors.length,0,JSON.stringify(errors));
    const expectedRequests={reported:1,failed_report:1,remind_success:2,normal_no_report:2,transient_retry:3,retry_exhausted:2,queued_followup:3,boundary_continue:2,abort:1,settled_hook_new_prompt:3}[scenario];
    assert.equal(requests,expectedRequests,scenario);