@zhushanwen/pi-base-tool-enhance 0.5.4 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-base-tool-enhance",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "description": "Base tool enhancement - override builtin bash tool: foreground delegates to pi official factory, incremental background mode (design decisions documented in source comments)",
   "type": "module",
   "main": "src/index.ts",
@@ -28,11 +28,11 @@
     "skills/"
   ],
   "dependencies": {
-    "@taiji/extension-protocol": "0.11.0",
-    "@zhushanwen/pi-ext-guards": "0.4.0",
-    "@zhushanwen/pi-extension-logger": "0.6.0",
-    "@zhushanwen/pi-file-lock": "0.4.0",
-    "@zhushanwen/pi-llm-shared": "0.8.0"
+    "@zhushanwen/extension-protocol": "0.12.0",
+    "@zhushanwen/pi-ext-guards": "0.4.1",
+    "@zhushanwen/pi-extension-logger": "0.6.1",
+    "@zhushanwen/pi-file-lock": "0.4.1",
+    "@zhushanwen/pi-llm-shared": "0.8.1"
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.9",
@@ -41,7 +41,7 @@
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.7.3"
+    "@zhushanwen/pi-pending-notifications": "0.7.5"
   },
   "peerDependenciesMeta": {
     "@zhushanwen/pi-pending-notifications": {

package/src/__tests__/background-lifecycle.test.ts

@@ -20,9 +20,9 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 // 进程原语（ext-simplify-13 后单点在 protocol 子出口）转发真实杀 + 记录调用
 //（timeout 分支断言 killProcessTree 被调）
 const { killTreeCalls } = vi.hoisted(() => ({ killTreeCalls: [] as number[] }));
-vi.mock("@taiji/extension-protocol/background-task", async (importOriginal) => {
+vi.mock("@zhushanwen/extension-protocol/background-task", async (importOriginal) => {
 	const orig = await importOriginal<
-		typeof import("@taiji/extension-protocol/background-task")
+		typeof import("@zhushanwen/extension-protocol/background-task")
 	>();
 	return {
 		...orig,
@@ -33,7 +33,7 @@ vi.mock("@taiji/extension-protocol/background-task", async (importOriginal) => {
 	};
 });
 
-import { isPidAlive } from "@taiji/extension-protocol/background-task";
+import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 
 import { createBashKillToolDefinition } from "../bash-kill-tool.ts";
 import { createBashOutputToolDefinition } from "../bash-output-tool.ts";
@@ -237,6 +237,12 @@ describe("real spawn lifecycle (poll edge finalization)", () => {
 });
 
 describe("bash_output tool", () => {
+	it("description pins the auto-notify contract (on-demand checks only, DO NOT bash sleep)", () => {
+		// 与 bash description / 启动回执同一契约话术（统一 "DO NOT bash sleep"）——删改必须红灯
+		expect(bashOutput.description).toContain("completion is auto-notified");
+		expect(bashOutput.description).toContain("DO NOT bash sleep");
+	});
+
 	it("list merges store + registry terminal entries, store wins on same id", async () => {
 		// 单例表：一个 running 真任务
 		const spawned = spawnBg("sleep 5");

package/src/__tests__/bash-tool.test.ts

@@ -139,6 +139,10 @@ describe("createBashOverrideToolDefinition", () => {
 		// 白名单自动转后台 + timeout 显式值被尊重（除白名单强转后台例外）
 		expect(tool.description).toContain("whitelist");
 		expect(tool.description).toContain("timeout in seconds");
+		// 自动通知契约（"DO NOT bash sleep" 统一话术是 background-bash-notify 主线主张——
+		// 实测大量 agent bash sleep 空等后加的硬契约，删改必须红灯）
+		expect(tool.description).toContain("Completion is auto-notified");
+		expect(tool.description).toContain("DO NOT bash sleep");
 	});
 
 	it("passes through official promptSnippet/promptGuidelines (system-prompt parity)", () => {
@@ -281,6 +285,9 @@ describe("background branch routing (M2)", () => {
 		expect(text).toContain("pid: 12345");
 		expect(text).toContain("Output file:");
 		expect(text).toContain('bash_output {task_id:"bt-1724589012-a3f7"}');
+		// 启动回执同钉自动通知契约（与 description 同一话术，startBackgroundAndReply 单点拼装）
+		expect(text).toContain("Completion is auto-notified");
+		expect(text).toContain("DO NOT bash sleep");
 	});
 
 	it("background spawn failure surfaces the error", async () => {

package/src/__tests__/maintenance-once.test.ts

@@ -1,7 +1,6 @@
 // src/__tests__/maintenance-once.test.ts —— 收殓下沉后的 session_start 维护链
-// 语义（实施单元 u-bte-remove，设计 docs/architecture/file-lock-unification-and-
-// reaper-sink.md §3.2 D2「extension 删 session_start reaper」/ §3.3 D3 粒度段 / §4 S6
-// 「批 2 后 reap 类操作不再执行」）：
+// 语义（实施单元 u-bte-remove：extension 删 session_start reaper，批 2 后
+// reap 类操作不再执行）：
 //  - reconcilePendingEntries 是 session 级豁免类，每 session_start 派发都执行
 //    （startup/resume/new 多派发 ×N——含 factory 二调 handler 累积的真实形态）
 //  - 触发面消失：reaper.ts 模块文件已删除（文件级断言，见首条用例）+ 维护链不再触发

package/src/__tests__/notify.test.ts

@@ -8,10 +8,11 @@ import { join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
-import { killProcessTree } from "@taiji/extension-protocol/background-task";
+import { killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import {
 	BACKGROUND_BASH_CUSTOM_TYPE,
 	buildNotificationContent,
+	buildNotifyDetails,
 	emitPendingRegister,
 	handleTaskExit,
 	refreshPiReference,
@@ -46,6 +47,12 @@ function attach(pi: MockPi): void {
 	refreshPiReference(pi as unknown as ExtensionAPI);
 }
 
+/** 取第一条 sendMessage 的首参数对象（D1 details 断言入口）。 */
+function sentMessage(pi: MockPi): { content: string; details: unknown } {
+	const [message] = pi.sendMessage.mock.calls[0] as [{ content: string; details: unknown }, unknown];
+	return message;
+}
+
 function sleep(ms: number): Promise<void> {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -187,7 +194,7 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		});
 		expect(pi.sendMessage).toHaveBeenCalledTimes(1);
 		const [message, options] = pi.sendMessage.mock.calls[0] as [
-			{ customType: string; content: string; display: boolean },
+			{ customType: string; content: string; display: boolean; details: Record<string, unknown> },
 			{ deliverAs: string; triggerTurn: boolean },
 		];
 		expect(message.customType).toBe(BACKGROUND_BASH_CUSTOM_TYPE);
@@ -196,6 +203,15 @@ describe("exit-edge notification (⑧⑨, poll edge wiring)", () => {
 		expect(message.content).toContain("exit 0");
 		expect(message.content).toContain("done"); // tail 摘要
 		expect(options).toEqual({ deliverAs: "steer", triggerTurn: true });
+		// U1（D1）：真实轮询边沿投递的 details 与终态条目逐字段一致（非 fixture 常量）
+		const finalizedEntry = getTask(task.taskId);
+		expect(message.details).toMatchObject({
+			taskId: task.taskId,
+			command: "sleep 0.3 && echo done",
+			endReason: "natural",
+			exitCode: 0,
+		});
+		expect((message.details as { durationMs: number }).durationMs).toBe(finalizedEntry?.durationMs);
 	});
 
 	it("killed: emits unregister reason 'cancelled' but does NOT sendMessage (single-point rule)", async () => {
@@ -285,6 +301,70 @@ describe("notification content (§3.1 sample)", () => {
 	});
 });
 
+describe("notification details (D1 schema: taskId/command/durationMs/endReason/exitCode)", () => {
+	it("natural: details mirror the terminal task fields; content stays byte-identical (LLM payload)", () => {
+		const pi = createMockPi();
+		attach(pi);
+		const task = finalizedTask();
+		handleTaskExit(task);
+
+		const message = sentMessage(pi);
+		expect(message.details).toEqual({
+			taskId: task.taskId,
+			command: task.command,
+			durationMs: task.durationMs,
+			endReason: "natural",
+			exitCode: task.exitCode,
+		});
+		// 键级断言：D1 恰五字段，防字段悄悄混入（register emit 同款范式）
+		expect(Object.keys(message.details as Record<string, unknown>).sort()).toEqual([
+			"command",
+			"durationMs",
+			"endReason",
+			"exitCode",
+			"taskId",
+		]);
+		// content 是 triggerTurn:true 给 LLM 接力的载荷：挂 details 不得改动一个字节
+		expect(message.content).toBe(
+			"[background-bash] bt-1700000000-test01 finished (exit 0, 3m12s): pnpm test\n" +
+				"Last lines: Tests: 42 passed\n" +
+				'Full output: /tmp/out/bt-1700000000-test01.log; use bash_output {task_id:"bt-1700000000-test01"} for details.',
+		);
+	});
+
+	it("natural nonzero exit: exitCode passes through unchanged, endReason stays 'natural'", () => {
+		const pi = createMockPi();
+		attach(pi);
+		handleTaskExit(finalizedTask({ exitCode: 3, durationMs: 5000 }));
+
+		expect(sentMessage(pi).details).toEqual({
+			taskId: "bt-1700000000-test01",
+			command: "pnpm test",
+			durationMs: 5000,
+			endReason: "natural",
+			exitCode: 3,
+		});
+	});
+
+	it("timeout: endReason 'timeout' + exitCode null (D1 可空字段的 timeout 形态)", () => {
+		const pi = createMockPi();
+		attach(pi);
+		handleTaskExit(finalizedTask({ reason: "timeout", exitCode: null, durationMs: 15_000 }));
+
+		expect(sentMessage(pi).details).toEqual({
+			taskId: "bt-1700000000-test01",
+			command: "pnpm test",
+			durationMs: 15_000,
+			endReason: "timeout",
+			exitCode: null,
+		});
+	});
+
+	it("durationMs 缺省归 0：必需字段恒为 number（消费侧解析器才不判 null）", () => {
+		expect(buildNotifyDetails(finalizedTask({ durationMs: undefined })).durationMs).toBe(0);
+	});
+});
+
 describe("D17: pi reference refresh (session replacement takeover)", () => {
 	it("second load wins: notification goes through the NEW reference, old one untouched", () => {
 		const piA = createMockPi();

package/src/__tests__/pending-reconcile.test.ts

@@ -10,7 +10,7 @@ import {
 	BACKGROUND_TASK_ID_PREFIX,
 	collectActivePendingIds,
 	mapReasonToStatus,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 import {

package/src/__tests__/registry.test.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 
 import { afterEach, describe, expect, it } from "vitest";
 
-import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@taiji/extension-protocol";
+import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@zhushanwen/extension-protocol";
 
 import {
 	getRegistryPath,

package/src/background/notify.ts

@@ -48,6 +48,16 @@ export const BACKGROUND_BASH_CUSTOM_TYPE = "background-bash";
  */
 const PENDING_NAME_LIMIT = 80;
 
+/**
+ * 命令文案截断（pending register 的 name 与完成通知 head 行共用同一口径）：
+ * 超 PENDING_NAME_LIMIT 取前 80 字符 + 省略号。
+ */
+function truncateCommand(command: string): string {
+	return command.length > PENDING_NAME_LIMIT
+		? `${command.slice(0, PENDING_NAME_LIMIT)}…`
+		: command;
+}
+
 /** 模块级「当前 pi 引用」（D17 核心可变状态，见文件头）。 */
 let currentPi: ExtensionAPI | undefined;
 
@@ -100,10 +110,7 @@ export function toPendingReason(
 export function emitPendingRegister(task: BackgroundTask): void {
 	const pi = currentPi;
 	if (pi === undefined) return;
-	const name =
-		task.command.length > PENDING_NAME_LIMIT
-			? `${task.command.slice(0, PENDING_NAME_LIMIT)}…`
-			: task.command;
+	const name = truncateCommand(task.command);
 	try {
 		pi.events.emit("pending:register", { id: task.taskId, type: "bash", name });
 	} catch (err) {
@@ -153,7 +160,12 @@ function sendTaskFinishedMessage(task: BackgroundTask): void {
 	if (pi === undefined) return;
 	try {
 		pi.sendMessage(
-			{ customType: BACKGROUND_BASH_CUSTOM_TYPE, content: buildNotificationContent(task), display: true },
+			{
+				customType: BACKGROUND_BASH_CUSTOM_TYPE,
+				content: buildNotificationContent(task),
+				display: true,
+				details: buildNotifyDetails(task),
+			},
 			{ deliverAs: "steer", triggerTurn: true },
 		);
 	} catch (err) {
@@ -179,10 +191,7 @@ function sendTaskFinishedMessage(task: BackgroundTask): void {
  */
 export function buildNotificationContent(task: BackgroundTask): string {
 	const duration = formatDurationMs(task.durationMs ?? 0);
-	const command =
-		task.command.length > PENDING_NAME_LIMIT
-			? `${task.command.slice(0, PENDING_NAME_LIMIT)}…`
-			: task.command;
+	const command = truncateCommand(task.command);
 	let head: string;
 	if (task.reason === "timeout") {
 		head = `[background-bash] ${task.taskId} timed out (${duration}): ${command}`;
@@ -199,6 +208,49 @@ export function buildNotificationContent(task: BackgroundTask): string {
 	return lines.join("\n");
 }
 
+/**
+ * sendMessage details 载荷（设计 §3.3 D1 schema）。
+ *
+ * 为什么另立 details 而非让上层解析 content：content 是本模块内部模板字符串、写给
+ * LLM 接力的日志行，格式漂移即静默打破解析；details 经既有透传管道（event-adapter
+ * → registry → reducer → Message.details）结构化到达渲染层，content 原文对 LLM 逐
+ * 字节不变。
+ *
+ * 字面量镜像：消费侧解析器 `packages/shared/src/message.ts` 的
+ * `parseBackgroundBashDetails`（本包是独立 npm 包，不 import taiji 内部 shared）——
+ * 字段名、可空性、枚举值三处必须逐字对齐，改动须同步另一侧。
+ *
+ * 枚举收敛：`endReason` 只落 natural | timeout——killed 在 handleTaskExit 提前返回、
+ * process-exit 走收殓路径（只 emit 不发消息、根本不进本函数），两者均不可达（D1
+ * 源码核实），不为不可达形态造死值。
+ */
+export interface BackgroundBashDetails {
+	taskId: string;
+	command: string;
+	/** 存活时长（毫秒），与 content 中的耗时同源同口径。 */
+	durationMs: number;
+	endReason: "natural" | "timeout";
+	/** 无退出码时为 null（timeout / 被信号终止语义，D1 可空字段）。 */
+	exitCode: number | null;
+}
+
+/**
+ * 完成通知 details（D1）：终态字段与 buildNotificationContent 同源——durationMs
+ * 同用 `?? 0` 归一（终态条目必已物化，缺省仅防御）。
+ *
+ * command 取原始终态值不截断：截断（PENDING_NAME_LIMIT）是 content 行宽约束，结构化
+ * 消费方的行宽由渲染层自己决定（旧数据无 details 时仍走 content 原文兜底）。
+ */
+export function buildNotifyDetails(task: BackgroundTask): BackgroundBashDetails {
+	return {
+		taskId: task.taskId,
+		command: task.command,
+		durationMs: task.durationMs ?? 0,
+		endReason: task.reason === "timeout" ? "timeout" : "natural",
+		exitCode: task.exitCode ?? null,
+	};
+}
+
 /** 耗时换算常量（毫秒/秒/分/时 + 时分两位补零宽度）。 */
 const MS_PER_SECOND = 1000;
 const SECONDS_PER_MINUTE = 60;

package/src/background/output-tail.ts

@@ -8,7 +8,7 @@
  *  - readTailSummary：exit 边沿的 tail 摘要（存条目 / M3 通知用）
  */
 
-import { readOutputTail as readOutputTailPrimitive } from "@taiji/extension-protocol/background-task";
+import { readOutputTail as readOutputTailPrimitive } from "@zhushanwen/extension-protocol/background-task";
 
 /** pi 内置 bash 同款截断上限（last 2000 lines / 50KB = 51200 bytes，先到为准）。 */
 export const TAIL_MAX_LINES = 2000;

package/src/background/pending-reconcile.ts

@@ -35,8 +35,8 @@ import {
 	BACKGROUND_TASK_ID_PREFIX,
 	collectActivePendingIds,
 	mapReasonToStatus,
-} from "@taiji/extension-protocol";
-import { isPidAlive } from "@taiji/extension-protocol/background-task";
+} from "@zhushanwen/extension-protocol";
+import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 

package/src/background/poller.ts

@@ -13,7 +13,7 @@
  * 可查、对账可补），不加同步握手。
  */
 
-import { isPidAlive } from "@taiji/extension-protocol/background-task";
+import { isPidAlive } from "@zhushanwen/extension-protocol/background-task";
 
 import { readTailSummary } from "./output-tail.ts";
 import { readRegistry, taskToRegistryEntry, writeRegistryEntry } from "./registry.ts";

package/src/background/process-exit-guard.ts

@@ -27,7 +27,7 @@
  * 本单元不管。
  */
 
-import { killProcessTree } from "@taiji/extension-protocol/background-task";
+import { killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 

package/src/background/registry.ts

@@ -7,7 +7,7 @@
  * 写入。
  *
  * 行为原语单点（ext-simplify-13）：解析防御 / corrupt 隔离 / 原子写 / 序列化 /
- * 终态 LRU 裁剪自 @taiji/extension-protocol background-task 子出口引入——此前
+ * 终态 LRU 裁剪自 @zhushanwen/extension-protocol background-task 子出口引入——此前
  * 本地实现与 runtime 侧逐字同构、靠注释对齐；本模块只保留 bte 形态薄壳：Map 投影
  * readRegistry 与锁内 RMW 写壳。
  *
@@ -26,14 +26,14 @@ import { join } from "node:path";
 
 // 契约常量（LRU 上限）走 index 出口（background-task.ts 契约面）；行为原语走
 // background-task 子出口（含 node 内建依赖，不进 index——renderer/core 零触达）
-import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@taiji/extension-protocol";
+import { MAX_TERMINAL_REGISTRY_ENTRIES } from "@zhushanwen/extension-protocol";
 import {
 	atomicWriteRegistry,
 	readRegistry as readRegistryEntries,
 	serializeRegistryFile,
 	trimTerminalEntries,
 	type RegistryFileLogFn,
-} from "@taiji/extension-protocol/background-task";
+} from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { withFileLockSync } from "@zhushanwen/pi-file-lock";

package/src/background/spawn-background.ts

@@ -17,7 +17,7 @@ import { mkdirSync, openSync, closeSync, accessSync, constants } from "node:fs";
 import { dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 
-import { getProcessStartTimeSec, killProcessTree, pidStartMatchesRegistered } from "@taiji/extension-protocol/background-task";
+import { getProcessStartTimeSec, killProcessTree, pidStartMatchesRegistered } from "@zhushanwen/extension-protocol/background-task";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 

package/src/background/task-store.ts

@@ -28,7 +28,7 @@
  * 未来新增写路径（如 maintenance 类）必须保持该顺序，违反即 intent 可丢失。
  */
 
-import { trimTerminalEntries } from "@taiji/extension-protocol/background-task";
+import { trimTerminalEntries } from "@zhushanwen/extension-protocol/background-task";
 
 import {
 	isActiveState,

package/src/background/types.ts

@@ -1,5 +1,5 @@
 /**
- * background 任务核心数据模型（设计文档 docs/design/base-tool-enhance.md §3.5）。
+ * background 任务核心数据模型。
  *
  * 两层存储分工：
  *  - 单例任务表（task-store.ts，模块级 Map）= 运行时权威；条目唯一来源 = 本进程
@@ -8,7 +8,7 @@
  *    条目记 ownerPiPid（M2 只负责写入）
  *
  * 契约改引（u-bte-remove）：registry 持久化形状（RegistryEntry / 状态机 / reason
- * 枚举 / active·terminal 判定）与 @taiji/extension-protocol background-task.ts
+ * 枚举 / active·terminal 判定）与 @zhushanwen/extension-protocol background-task.ts
  * 契约逐字段一致（契约文档头声明基线即本文件 + registry.ts），本地副本已删除、
  * 此处 re-export 并保留包内短名——消费方 import 路径与字段语义零变化。运行时
  * 对象类型（BackgroundTask / KillingIntent）不在契约内（剥离非持久字段前的形状），
@@ -19,18 +19,18 @@ import type { ChildProcess } from "node:child_process";
 import type {
 	BackgroundTaskEndReason as ContractEndReason,
 	BackgroundTaskState as ContractState,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 /** 状态机与 reason 枚举 / 持久化条目 / active·terminal 判定：契约 SSOT re-export。 */
 export type {
 	BackgroundTaskRegistryEntry as RegistryEntry,
 	BackgroundTaskState,
 	BackgroundTaskEndReason,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 export {
 	isActiveBackgroundTaskState as isActiveState,
 	isTerminalBackgroundTaskState as isTerminalState,
-} from "@taiji/extension-protocol";
+} from "@zhushanwen/extension-protocol";
 
 /**
  * killing intent：bash_kill / 后台 timeout 已发令、轮询器 exit 边沿未确认的瞬态标记。

package/src/bash-kill-tool.ts

@@ -18,7 +18,7 @@
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "@taiji/extension-protocol/background-task";
+import { getProcessStartTimeSec, isPidAlive, killProcessTree } from "@zhushanwen/extension-protocol/background-task";
 import { Type } from "typebox";
 
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";

package/src/bash-output-tool.ts

@@ -14,7 +14,7 @@
 
 import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
-import { readOutputTail } from "@taiji/extension-protocol/background-task";
+import { readOutputTail } from "@zhushanwen/extension-protocol/background-task";
 import { Type } from "typebox";
 
 import { TAIL_MAX_BYTES, TAIL_MAX_LINES } from "./background/output-tail.ts";
@@ -32,6 +32,7 @@ const JSON_INDENT = 2;
 
 const BASH_OUTPUT_DESCRIPTION = [
 	"Fetch output and status of a background bash task started with bash {background:true}.",
+	"On-demand checks only: completion is auto-notified (steer wakes your next turn), so DO NOT bash sleep or call this tool in a wait loop.",
 	"Provide task_id to get task detail: state (running|killing|exited|orphaned), exitCode, reason, duration and tail output (last 2000 lines / 50KB).",
 	'reason "killed" means the task was terminated by the user from the UI — do not restart the command unless explicitly asked.',
 	'reason "orphaned" means the owner process died before the task finished — the task is no longer supervised.',

package/src/bash-tool.ts

@@ -1,5 +1,5 @@
 /**
- * bash 工具同名 override 定义（设计文档 docs/design/base-tool-enhance.md §3.2 方案 B / §3.5）。
+ * bash 工具同名 override 定义。
  *
  * 前台行为 100% 委托 pi 官方工厂 createBashToolDefinition——override 后工具的全部
  * 行为归本包负责，前台语义必须跟随 pi 版本升级而不是自研复刻（自研 spawn 会与
@@ -54,6 +54,9 @@ const enhancedBashSchema = Type.Object({
  *  1. background:true 语义（立即返回 task_id，bash_output 查询 / bash_kill 终止）
  *  2. 白名单命中命令自动转后台（即使未要求 background）
  *  3. timeout 单位秒、显式填写会被尊重（唯一例外：白名单强转后台时忽略，D13）
+ *  4. 自动通知契约（统一话术 "DO NOT bash sleep"）：任务完成 steer 自动唤醒新
+ *     turn（notify.ts），LLM 文案必须传达「不要 sleep 空等」——实测大量 agent
+ *     启动后台任务后跑 bash sleep 轮询空等，机制在而契约不在所致
  *
  * bash_output / bash_kill 工具由 M2 单元注册，description 先行提及（D2/§3.5 要求）。
  */
@@ -62,10 +65,11 @@ const ENHANCED_BASH_DESCRIPTION = [
 	"Output is truncated to last 2000 lines or 50KB (whichever is hit first). If truncated, full output is saved to a temp file.",
 	"Optionally provide a timeout in seconds; an explicit timeout is respected, except when a whitelisted long-running command is force-routed to background. If no timeout is given, a configured default timeout applies when set.",
 	"",
-	"Background mode: set background: true to start the command without waiting for it. The tool returns immediately with a task_id, the pid, and an output file path, and you can continue other work while it runs.",
-	"Poll progress and fetch output with bash_output {task_id} (omit task_id to list known background tasks); terminate a task with bash_kill {task_id}.",
+	"Background mode: set background: true to start the command without waiting for it. The tool returns immediately with a task_id, the pid, and an output file path.",
+	"Completion is auto-notified: when the task finishes, a steer message with its output tail wakes your next turn — DO NOT bash sleep (e.g. run `sleep 30` in another bash call) or busy-wait while it runs. Do useful non-overlapping work, otherwise just stop and let the notification arrive.",
+	"bash_output {task_id} is for on-demand progress checks only (omit task_id to list known background tasks); never use it as a wait loop. Terminate a task with bash_kill {task_id}.",
 	"",
-	"Commands matching the force-background whitelist (test suites, dev servers, watch jobs and similar long-running commands) are automatically routed to background even when background was not requested; in that case the result carries a task_id to poll.",
+	"Commands matching the force-background whitelist (test suites, dev servers, watch jobs and similar long-running commands) are automatically routed to background even when background was not requested; the result carries a task_id and completion auto-notifies — the same DO NOT bash sleep rule applies.",
 ].join("\n");
 
 /**
@@ -101,7 +105,7 @@ function startBackgroundAndReply(
 					`task_id: ${task.taskId}  pid: ${task.pid}`,
 					`Output file: ${task.outputFile}`,
 					...extraNotes,
-					`Poll with bash_output {task_id:"${task.taskId}"} or omit task_id to list all tasks; terminate with bash_kill {task_id:"${task.taskId}"}.`,
+					`Completion is auto-notified — DO NOT bash sleep while waiting. On-demand check: bash_output {task_id:"${task.taskId}"} (or omit task_id to list all tasks); terminate with bash_kill {task_id:"${task.taskId}"}.`,
 				].join("\n"),
 			},
 		],