@zhushanwen/pi-unified-hooks 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-unified-hooks",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Unified hooks extension - collect scattered hooks in one place for easy maintenance",
   "main": "index.ts",
   "type": "module",
@@ -15,9 +15,13 @@
     "hooks"
   ],
   "license": "MIT",
+  "dependencies": {
+    "@zhushanwen/pi-extension-logger": "0.2.1"
+  },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*"
   },
+  "peerDependenciesMeta": {},
   "devDependencies": {
     "vitest": "^4.1.8"
   },

package/src/__tests__/session-start-handler.test.ts

@@ -18,15 +18,10 @@ vi.mock("../hooks/test-timeout-guard.ts", () => ({
 	setupTestTimeoutGuard: vi.fn(),
 }));
 
-vi.mock("../hooks/subagent-list-injector.ts", () => ({
-	setupSubagentListInjector: vi.fn(),
-}));
-
 // Re-import after mocking so the mocked versions are used
 import { setupToolErrorHandler } from "../hooks/tool-error-handler.ts";
 import { setupNetworkTimeoutGuard } from "../hooks/network-timeout-guard.ts";
 import { setupTestTimeoutGuard } from "../hooks/test-timeout-guard.ts";
-import { setupSubagentListInjector } from "../hooks/subagent-list-injector.ts";
 
 import unifiedHooksExtension from "../index.ts";
 
@@ -55,7 +50,7 @@ function getSessionStartHandler(pi: ReturnType<typeof createMockPi>): (event: un
 
 // --- tests ---
 describe("session_start handler", () => {
-	it("notifies 'info' when all hooks are enabled", () => {
+	it("does not notify when all hooks are enabled (only appendEntry)", () => {
 		const pi = createMockPi();
 		const { ctx, notify } = createMockCtx();
 
@@ -63,22 +58,21 @@ describe("session_start handler", () => {
 		(setupToolErrorHandler as ReturnType<typeof vi.fn>).mockImplementation(() => {});
 		(setupNetworkTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {});
 		(setupTestTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {});
-		(setupSubagentListInjector as ReturnType<typeof vi.fn>).mockImplementation(() => {});
 
 		unifiedHooksExtension(pi as unknown as ExtensionAPI);
 
 		const handler = getSessionStartHandler(pi);
 		handler({}, ctx);
 
-		expect(notify).toHaveBeenCalledTimes(1);
-		expect(notify.mock.calls[0]![1]).toBe("info");
+		// 全成功时不 notify（避免刷屏），只 appendEntry
+		expect(notify).not.toHaveBeenCalled();
 		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", {
-			enabled: ["tool-error-handler", "network-timeout-guard", "test-timeout-guard", "subagent-list-injector"],
+			enabled: ["tool-error-handler", "network-timeout-guard", "test-timeout-guard"],
 			disabled: [],
 		});
 	});
 
-	it("notifies 'warning' and lists disabled hooks when some hooks fail", () => {
+	it("notifies 'warning' listing only disabled hooks when some hooks fail", () => {
 		const pi = createMockPi();
 		const { ctx, notify } = createMockCtx();
 
@@ -90,7 +84,6 @@ describe("session_start handler", () => {
 		(setupTestTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {
 			throw new Error("timeout");
 		});
-		(setupSubagentListInjector as ReturnType<typeof vi.fn>).mockImplementation(() => {});
 
 		unifiedHooksExtension(pi as unknown as ExtensionAPI);
 
@@ -101,14 +94,13 @@ describe("session_start handler", () => {
 		const [msg, level] = notify.mock.calls[0]!;
 		expect(level).toBe("warning");
 		expect(msg).toContain("Failed: network-timeout-guard, test-timeout-guard");
-		expect(msg).toContain("Loaded: tool-error-handler, subagent-list-injector");
 		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", {
-			enabled: ["tool-error-handler", "subagent-list-injector"],
+			enabled: ["tool-error-handler"],
 			disabled: ["network-timeout-guard", "test-timeout-guard"],
 		});
 	});
 
-	it("notifies 'warning' when all hooks are disabled", () => {
+	it("notifies 'warning' listing all hooks when all are disabled", () => {
 		const pi = createMockPi();
 		const { ctx, notify } = createMockCtx();
 
@@ -122,9 +114,6 @@ describe("session_start handler", () => {
 		(setupTestTimeoutGuard as ReturnType<typeof vi.fn>).mockImplementation(() => {
 			throw new Error("c");
 		});
-		(setupSubagentListInjector as ReturnType<typeof vi.fn>).mockImplementation(() => {
-			throw new Error("d");
-		});
 
 		unifiedHooksExtension(pi as unknown as ExtensionAPI);
 
@@ -133,10 +122,10 @@ describe("session_start handler", () => {
 
 		expect(notify.mock.calls[0]![1]).toBe("warning");
 		const msg = notify.mock.calls[0]![0] as string;
-		expect(msg).toContain("(none)");
+		expect(msg).toContain("Failed: tool-error-handler, network-timeout-guard, test-timeout-guard");
 		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:loaded", {
 			enabled: [],
-			disabled: ["tool-error-handler", "network-timeout-guard", "test-timeout-guard", "subagent-list-injector"],
+			disabled: ["tool-error-handler", "network-timeout-guard", "test-timeout-guard"],
 		});
 	});
 

package/src/__tests__/tool-error-handler.test.ts

@@ -3,7 +3,19 @@ import { describe, expect, it, vi } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { setupToolErrorHandler, type HookContext } from "../hooks/tool-error-handler.ts";
+// Mock 共享 logger，让 logger.warn 可被 spy
+const { loggerMock } = vi.hoisted(() => ({
+	loggerMock: {
+		debug: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+	},
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+	getLogger: () => loggerMock,
+}));
+
+import { setupToolErrorHandler } from "../hooks/tool-error-handler.ts";
 
 // --- helper types ---
 interface MockPi {
@@ -19,12 +31,6 @@ function createMockPi(overrides?: Partial<MockPi>): MockPi {
 	};
 }
 
-function createMockCtx(): { ctx: HookContext; notify: ReturnType<typeof vi.fn> } {
-	const notify = vi.fn();
-	const ctx = { ui: { notify } };
-	return { ctx, notify };
-}
-
 describe("setupToolErrorHandler", () => {
 	it("registers a handler on the tool_execution_end event", () => {
 		const pi = createMockPi();
@@ -34,211 +40,129 @@ describe("setupToolErrorHandler", () => {
 		expect(pi.on).toHaveBeenCalledWith("tool_execution_end", expect.any(Function));
 	});
 
-	it("notifies via ctx.ui.notify and persists via appendEntry on isError:true", async () => {
+	it("logs via logger.warn and appendEntry with dedicated customType on isError:true", async () => {
 		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
+		loggerMock.warn.mockClear();
+		pi.appendEntry.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
 
-		await handler(
-			{ isError: true, toolName: "read", toolCallId: "call-42" },
-			ctx,
-		);
+		await handler({ isError: true, toolName: "read", toolCallId: "call-42" });
 
-		expect(notify).toHaveBeenCalledTimes(1);
-		expect(notify).toHaveBeenCalledWith(
+		// logger.warn 被调一次（内部走泛化 appendEntry customType）
+		expect(loggerMock.warn).toHaveBeenCalledTimes(1);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
 			"[unified-hooks] read error (callId=call-42)",
-			"warning",
+			expect.objectContaining({
+				toolName: "read",
+				toolCallId: "call-42",
+				errorText: null,
+			}),
 		);
+		// 额外 appendEntry 用专属 customType "unified-hooks:tool-error"，
+		// 保留按 entry type 过滤 tool 错误的埋点契约
 		expect(pi.appendEntry).toHaveBeenCalledTimes(1);
-		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
-			toolName: "read",
-			toolCallId: "call-42",
-			errorText: null,
-		});
-	});
-
-	it("does nothing on isError:false (no notify, no appendEntry)", async () => {
-		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
-
-		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
-
-		await handler(
-			{ isError: false, toolName: "bash", toolCallId: "call-99" },
-			ctx,
+		expect(pi.appendEntry).toHaveBeenCalledWith(
+			"unified-hooks:tool-error",
+			expect.objectContaining({
+				toolName: "read",
+				toolCallId: "call-42",
+				errorText: null,
+			}),
 		);
-
-		expect(notify).not.toHaveBeenCalled();
-		expect(pi.appendEntry).not.toHaveBeenCalled();
 	});
 
-	it("uses the warn notification type for errors", async () => {
+	it("does nothing on isError:false (no logger.warn)", async () => {
 		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
+		loggerMock.warn.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
 
-		await handler(
-			{ isError: true, toolName: "edit", toolCallId: "c1" },
-			ctx,
-		);
+		await handler({ isError: false, toolName: "bash", toolCallId: "call-99" });
 
-		// Second arg of notify is the type — must be "warning" (matches SDK literal union, not info/error).
-		expect(notify.mock.calls[0]![1]).toBe("warning");
+		expect(loggerMock.warn).not.toHaveBeenCalled();
 	});
 
 	// --- edge cases ---
 
 	it("propagates if pi.on throws during registration", () => {
 		const pi = createMockPi({
-		on: vi.fn(() => { throw new Error("registration failed"); }),
+			on: vi.fn(() => { throw new Error("registration failed"); }),
 		});
 
 		expect(() => setupToolErrorHandler(pi as unknown as ExtensionAPI)).toThrow("registration failed");
 	});
 
-	it("does not crash if handler callback throws (notify throws)", async () => {
-		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
-		notify.mockImplementation(() => { throw new Error("notify broke"); });
-
-		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
-
-		await expect(
-			handler({ isError: true, toolName: "bash", toolCallId: "c2" }, ctx),
-		).rejects.toThrow("notify broke");
-
-		// appendEntry should NOT have been called since notify threw first
-		expect(pi.appendEntry).not.toHaveBeenCalled();
-	});
-
-	it("does not crash if handler callback throws (appendEntry throws)", async () => {
-		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
-		pi.appendEntry.mockImplementation(() => { throw new Error("append broke"); });
-
-		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
-
-		await expect(
-			handler({ isError: true, toolName: "grep", toolCallId: "c3" }, ctx),
-		).rejects.toThrow("append broke");
-
-		// notify was called before appendEntry threw
-		expect(notify).toHaveBeenCalledTimes(1);
-	});
-
 	it("handles concurrent error events independently", async () => {
 		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
+		loggerMock.warn.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
 
 		await Promise.all([
-			handler({ isError: true, toolName: "read", toolCallId: "e1" }, ctx),
-			handler({ isError: true, toolName: "bash", toolCallId: "e2" }, ctx),
-			handler({ isError: false, toolName: "edit", toolCallId: "e3" }, ctx),
+			handler({ isError: true, toolName: "read", toolCallId: "e1" }),
+			handler({ isError: true, toolName: "bash", toolCallId: "e2" }),
+			handler({ isError: false, toolName: "edit", toolCallId: "e3" }),
 		]);
 
-		expect(notify).toHaveBeenCalledTimes(2);
-		expect(pi.appendEntry).toHaveBeenCalledTimes(2);
-
-		// verify both calls persisted independently
-		const calls = pi.appendEntry.mock.calls.map((c) => c[1]);
-		expect(calls).toEqual(
-			expect.arrayContaining([
-				{ toolName: "read", toolCallId: "e1", errorText: null },
-				{ toolName: "bash", toolCallId: "e2", errorText: null },
-			]),
+		expect(loggerMock.warn).toHaveBeenCalledTimes(2);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			"[unified-hooks] read error (callId=e1)",
+			expect.objectContaining({ toolName: "read", toolCallId: "e1" }),
+		);
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			"[unified-hooks] bash error (callId=e2)",
+			expect.objectContaining({ toolName: "bash", toolCallId: "e2" }),
 		);
 	});
 
-	it("falls back to console.warn when ctx.ui is undefined (headless session)", async () => {
-		// [HISTORICAL] headless / RPC 会话 ctx.ui 为 undefined，旧实现直接 ctx.ui.notify 会 NPE。
+	// --- errorText 提取（核心能力）---
+
+	it("从 result.content[0].text 提取错误文本（如 'hub disposed'）", async () => {
 		const pi = createMockPi();
-		const ctx = { ui: undefined } as unknown as HookContext;
-		const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+		loggerMock.warn.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
 
-		await handler({ isError: true, toolName: "bash", toolCallId: "h1" }, ctx);
-
-		expect(warnSpy).toHaveBeenCalledTimes(1);
-		expect(warnSpy.mock.calls[0]![0]).toContain("bash error");
-		// appendEntry 仍持久化
-		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
-			toolName: "bash",
-			toolCallId: "h1",
-			errorText: null,
+		await handler({
+			isError: true,
+			toolName: "subagent",
+			toolCallId: "call-disposed",
+			result: { content: [{ type: "text", text: "hub disposed" }] },
 		});
-		warnSpy.mockRestore();
-	});
-
-	// --- errorText 提取（核心新增能力）---
 
-	it("从 result.content[0].text 提取错误文本并拼到 warning（如 'hub disposed'）", async () => {
-		// [HISTORICAL] subagent execute throw 时 Pi 把 error.message 塞进 result.content[0].text。
-		// 旧实现只打 "(callId=xxx)" 无详情，AI 看不到真实原因（如 hub disposed）只能盲猜。
-		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
-
-		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
-
-		await handler(
-			{
-				isError: true,
+		expect(loggerMock.warn).toHaveBeenCalledWith(
+			"[unified-hooks] subagent error (callId=call-disposed)",
+			expect.objectContaining({
 				toolName: "subagent",
 				toolCallId: "call-disposed",
-				result: { content: [{ type: "text", text: "hub disposed" }] },
-			},
-			ctx,
+				errorText: "hub disposed",
+			}),
 		);
-
-		expect(notify).toHaveBeenCalledWith(
-			"[unified-hooks] subagent error (callId=call-disposed): hub disposed",
-			"warning",
-		);
-		expect(pi.appendEntry).toHaveBeenCalledWith("unified-hooks:tool-error", {
-			toolName: "subagent",
-			toolCallId: "call-disposed",
-			errorText: "hub disposed",
-		});
 	});
 
 	it("result 缺失或无 content 时降级到无详情（不崩）", async () => {
 		const pi = createMockPi();
-		const { ctx, notify } = createMockCtx();
+		loggerMock.warn.mockClear();
 
 		setupToolErrorHandler(pi as unknown as ExtensionAPI);
-		const handler = pi.on.mock.calls[0]![1] as (event: unknown, ctx: HookContext) => Promise<void>;
+		const handler = pi.on.mock.calls[0]![1] as (event: unknown) => Promise<void>;
 
 		// result 为 undefined（某些 headless 路径）
-		await handler({ isError: true, toolName: "bash", toolCallId: "x1" }, ctx);
+		await handler({ isError: true, toolName: "bash", toolCallId: "x1" });
 		// result.content 为空数组
-		await handler(
-			{ isError: true, toolName: "bash", toolCallId: "x2", result: { content: [] } },
-			ctx,
-		);
+		await handler({ isError: true, toolName: "bash", toolCallId: "x2", result: { content: [] } });
 		// result 不是对象
-		await handler(
-			{ isError: true, toolName: "bash", toolCallId: "x3", result: "oops" },
-			ctx,
-		);
+		await handler({ isError: true, toolName: "bash", toolCallId: "x3", result: "oops" });
 
-		// 三次都降级为无详情后缀
-		expect(notify.mock.calls[0]![0]).toBe("[unified-hooks] bash error (callId=x1)");
-		expect(notify.mock.calls[1]![0]).toBe("[unified-hooks] bash error (callId=x2)");
-		expect(notify.mock.calls[2]![0]).toBe("[unified-hooks] bash error (callId=x3)");
-		pi.appendEntry.mock.calls.forEach((c) => {
-			expect(c[1]).toHaveProperty("errorText", null);
-		});
+		// 三次都降级为无详情
+		expect(loggerMock.warn.mock.calls[0]![0]).toBe("[unified-hooks] bash error (callId=x1)");
+		expect(loggerMock.warn.mock.calls[0]![1]).toHaveProperty("errorText", null);
+		expect(loggerMock.warn.mock.calls[1]![1]).toHaveProperty("errorText", null);
+		expect(loggerMock.warn.mock.calls[2]![1]).toHaveProperty("errorText", null);
 	});
 });

package/src/hooks/tool-error-handler.ts

@@ -1,11 +1,19 @@
 /**
  * Tool Error Handler Hook
  *
- * Logs tool execution errors for debugging. Can be extended to handle
- * specific error patterns with contextual recovery.
+ * Records tool execution errors for post-hoc debugging via appendEntry.
+ *
+ * Design: tool errors already surface in the conversation flow via pi's native
+ * tool result (isError → error content fed back to LLM). This hook does NOT
+ * call ctx.ui.notify — that would duplicate the error in the TUI notification
+ * area, and the "bash error" wording misleads (the error may be a hook's
+ * block reason, not a real crash). We only appendEntry for audit trail.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("unified-hooks");
 
 /**
  * Subset of `ToolExecutionEndEvent` fields used by this hook.
@@ -68,30 +76,31 @@ function getStringProperty(obj: unknown, key: string): string | undefined {
 }
 
 export function setupToolErrorHandler(pi: ExtensionAPI): void {
-  pi.on("tool_execution_end", async (event: unknown, ctx: HookContext) => {
+  pi.on("tool_execution_end", async (event: unknown) => {
     const e = event as ToolExecutionEndLikeEvent;
     if (!e.isError) return;
 
     // 提取错误文本：tool execute throw 时 Pi 把 error.message 塞进 result.content。
     // SDK 事件无 errorMessage 字段，只能从这里捞；拿不到也不阻断（降级到无详情）。
     const errorText = extractErrorText(e.result);
-    const detail = errorText ? `: ${errorText}` : "";
-    const msg = `[unified-hooks] ${e.toolName} error (callId=${e.toolCallId})${detail}`;
 
-    // ctx.ui.notify 走 TUI 通知区，不越过 alternate screen 污染 input。
-    // console.warn 会写 raw stderr，在 TUI 下泄漏到 input 区。
-    // headless / RPC 会话 ctx.ui 可能为 undefined——降级到 console.warn 保证不 NPE。
-    if (ctx.ui?.notify) {
-      ctx.ui.notify(msg, "warning");
-    } else {
-      console.warn(msg);
-    }
     // appendEntry 持久化到 session entries，供事后排查（无 UI、不泄漏）。
     // errorText 一起存上——事后排查能看到真实原因（如 "hub disposed"）。
-    pi.appendEntry("unified-hooks:tool-error", {
+    // 不调 ctx.ui.notify——tool error 已在对话流里（pi 原生 tool result），
+    // notify 会重复显示且措辞（"bash error"）误导。
+    //
+    // 注意：除了 logger.warn（内部走泛化 `unified-hooks:log` customType），
+    // 这里额外调一次 `pi.appendEntry("unified-hooks:tool-error", ...)`。
+    // 原因：logger 内部的 appendEntry 用的是泛化 customType，无法区分 entry
+    // 是否为 tool 错误；保留专属 entry type 让事后按 customType 过滤 tool
+    // 错误的脚本/dashboard 仍可工作（埋点契约）。
+    const entry = {
+      timestamp: Date.now(),
       toolName: e.toolName,
       toolCallId: e.toolCallId,
       errorText: errorText ?? null,
-    });
+    };
+    pi.appendEntry("unified-hooks:tool-error", entry);
+    logger.warn(`[unified-hooks] ${e.toolName} error (callId=${e.toolCallId})`, entry);
   });
 }

package/src/index.ts

@@ -6,18 +6,24 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 // Re-export hook modules for easy access
 
 import { setupNetworkTimeoutGuard } from "./hooks/network-timeout-guard";
-import { setupSubagentListInjector } from "./hooks/subagent-list-injector";
 import { setupTestTimeoutGuard } from "./hooks/test-timeout-guard";
 import { type HookContext, setupToolErrorHandler } from "./hooks/tool-error-handler";
 
+// 模块级 logger（setPiHandle 注入后自动走 appendEntry）
+const logger = getLogger("unified-hooks");
+
 /**
  * Extension factory - registers all unified hooks
  */
 export default function unifiedHooksExtension(pi: ExtensionAPI): void {
+  // 注入 pi handle 给全局 extension-logger
+  setPiHandle(pi);
+
   // Initialize hook registry
   const hooks: Array<{ name: string; enabled: boolean }> = [];
 
@@ -27,7 +33,6 @@ export default function unifiedHooksExtension(pi: ExtensionAPI): void {
     { name: "tool-error-handler", setup: setupToolErrorHandler },
     { name: "network-timeout-guard", setup: setupNetworkTimeoutGuard },
     { name: "test-timeout-guard", setup: setupTestTimeoutGuard },
-    { name: "subagent-list-injector", setup: setupSubagentListInjector },
   ];
 
   for (const hook of hookModules) {
@@ -35,21 +40,30 @@ export default function unifiedHooksExtension(pi: ExtensionAPI): void {
       hook.setup(pi);
       hooks.push({ name: hook.name, enabled: true });
     } catch (err) {
-      console.error(`[unified-hooks] Failed to setup ${hook.name}:`, err);
+      logger.error(`[unified-hooks] Failed to setup ${hook.name}`, {
+        reason: err instanceof Error ? err.message : String(err),
+      });
       hooks.push({ name: hook.name, enabled: false });
     }
   }
 
-  // Hook status surfaced via TUI notify (走通知区，不泄漏到 input area）
-  // + appendEntry 持久化供事后排查。禁止用 console.warn（raw stderr 在 TUI
-  // alternate screen 下会越过渲染层污染 input 区）。
+  // Hook 状态：appendEntry 持久化（事后排查）。
+  // notify 仅在有 disabled hook（setup 失败）时提醒用户——全成功时不刷屏。
+  // 禁止用 console.warn（raw stderr 在 TUI alternate screen 下会越过渲染层污染 input 区）。
+  //
+  // 行为收敛（非向后兼容）：旧实现每次 session_start 无条件 notify，现在改为
+  // 「全成功仅 appendEntry，有失败才 notify disabled 列表」。`unified-hooks:loaded`
+  // customEntry 仍每次写入（持久化面不变）。消费方若依赖「每 session 必发 notify」
+  // 需改读 session.jsonl 中的 `unified-hooks:loaded` entry。
   pi.on("session_start", (_event: unknown, ctx: HookContext) => {
     const enabled = hooks.filter((h) => h.enabled).map((h) => h.name);
     const disabled = hooks.filter((h) => !h.enabled).map((h) => h.name);
-    const msg = `[unified-hooks] Loaded: ${enabled.join(", ") || "(none)"}${
-      disabled.length ? ` | Failed: ${disabled.join(", ")}` : ""
-    }`;
-    ctx.ui?.notify(msg, disabled.length ? "warning" : "info");
     pi.appendEntry("unified-hooks:loaded", { enabled, disabled });
+    if (disabled.length > 0) {
+      ctx.ui?.notify(
+        `[unified-hooks] Failed: ${disabled.join(", ")}`,
+        "warning",
+      );
+    }
   });
 }

package/src/hooks/subagent-list-injector.ts

@@ -1,173 +0,0 @@
-/**
- * Subagent List Injector Hook
- *
- * Discovers all available subagents (builtin + user + project scope) and
- * injects their names and descriptions into the system prompt on every turn,
- * so the AI model can pick the correct agent name instead of fabricating one.
- *
- * Injection format mirrors Pi's built-in skill injection (XML tags).
- */
-
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-
-/** Minimal agent info extracted from .md frontmatter */
-interface AgentEntry {
-	name: string;
-	description: string;
-}
-
-/**
- * Parse YAML frontmatter from a markdown file.
- * Returns null if the file has no valid frontmatter or missing name/description.
- */
-function parseAgentFrontmatter(content: string): AgentEntry | null {
-	if (!content.startsWith("---")) return null;
-
-	const FRONTMATTER_OPEN_LEN = 3;
-	const endIndex = content.indexOf("\n---", FRONTMATTER_OPEN_LEN);
-	if (endIndex === -1) return null;
-
-	const block = content.slice(FRONTMATTER_OPEN_LEN, endIndex);
-	let name = "";
-	let description = "";
-
-	for (const line of block.split("\n")) {
-		const match = line.match(/^([\w-]+):\s*(.*)$/);
-		if (!match) continue;
-
-		const key = match[1]!;
-		let value = match[2]!.trim();
-		// Strip surrounding quotes
-		if (
-			(value.startsWith('"') && value.endsWith('"')) ||
-			(value.startsWith("'") && value.endsWith("'"))
-		) {
-			value = value.slice(1, -1);
-		}
-
-		if (key === "name") name = value;
-		if (key === "description") description = value;
-	}
-
-	if (!name || !description) return null;
-	return { name, description };
-}
-
-/** Read agent .md files from a directory, return parsed entries */
-function loadAgentsFromDir(dir: string): AgentEntry[] {
-	if (!fs.existsSync(dir)) return [];
-
-	const entries: AgentEntry[] = [];
-	let dirents: fs.Dirent[];
-	try {
-		dirents = fs.readdirSync(dir, { withFileTypes: true });
-	} catch {
-		return [];
-	}
-
-	for (const entry of dirents) {
-		if (!entry.name.endsWith(".md")) continue;
-		if (entry.name.endsWith(".chain.md")) continue;
-		if (!entry.isFile() && !entry.isSymbolicLink()) continue;
-
-		const filePath = path.join(dir, entry.name);
-		try {
-			const content = fs.readFileSync(filePath, "utf8");
-			const agent = parseAgentFrontmatter(content);
-			if (agent) {
-				entries.push(agent);
-			}
-		} catch (err) {
-			// Individual file read failure should not block the entire agent list injection
-			console.error(`[subagent-list-injector] skip unreadable file ${filePath}:`, err);
-		}
-	}
-
-	return entries;
-}
-
-/** Escape special XML characters */
-function escapeXml(str: string): string {
-	return str
-		.replace(/&/g, "&")
-		.replace(/</g, "&lt;")
-		.replace(/>/g, "&gt;")
-		.replace(/"/g, "&quot;")
-		.replace(/'/g, "&apos;");
-}
-
-/**
- * Discover all available agents across scopes.
- * Deduplicates by name: project > user > builtin.
- */
-function discoverAllAgents(cwd: string): AgentEntry[] {
-	// Builtin agents from pi-subagents package
-	const builtinDir = path.join(
-		os.homedir(),
-		".pi/agent/npm/node_modules/pi-subagents/agents",
-	);
-
-	// User scope (both legacy and new paths)
-	const userDirLegacy = path.join(os.homedir(), ".pi/agent/agents");
-	const userDirNew = path.join(os.homedir(), ".agents");
-
-	// Project scope (both legacy and new paths)
-	const projectDirNew = path.join(cwd, ".pi/agents");
-	const projectDirLegacy = path.join(cwd, ".agents");
-
-	const agentMap = new Map<string, AgentEntry>();
-
-	// Load in priority order: builtin first, then user overrides, then project overrides
-	for (const agent of loadAgentsFromDir(builtinDir)) {
-		agentMap.set(agent.name, agent);
-	}
-	for (const dir of [userDirLegacy, userDirNew]) {
-		for (const agent of loadAgentsFromDir(dir)) {
-			agentMap.set(agent.name, agent);
-		}
-	}
-	for (const dir of [projectDirLegacy, projectDirNew]) {
-		for (const agent of loadAgentsFromDir(dir)) {
-			agentMap.set(agent.name, agent);
-		}
-	}
-
-	return [...agentMap.values()];
-}
-
-/** Format agent list as XML injection block */
-function formatAgentList(agents: AgentEntry[]): string {
-	if (agents.length === 0) return "";
-
-	const lines = [
-		"\n\n<available_subagents>",
-		"The following agents are available for the subagent tool. When using the subagent tool, ONLY use agent names from this list. If no agent matches your task, pass systemPrompt alongside the agent name to create a dynamic agent.",
-	];
-	for (const agent of agents) {
-		lines.push(
-			`  <agent><name>${escapeXml(agent.name)}</name><description>${escapeXml(agent.description)}</description></agent>`,
-		);
-	}
-	lines.push("</available_subagents>");
-	return lines.join("\n");
-}
-
-export function setupSubagentListInjector(pi: ExtensionAPI): void {
-	pi.on(
-		"before_agent_start",
-		(event: unknown, _ctx: unknown) => {
-			const e = event as { systemPrompt?: string };
-			const cwd = process.cwd();
-			const agents = discoverAllAgents(cwd);
-			const injection = formatAgentList(agents);
-
-			if (!injection) return;
-
-			return { systemPrompt: (e.systemPrompt ?? "") + injection };
-		},
-	);
-}