pi-extensions-tool-display 1.0.0 → 1.1.0

package/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: configure-pi-extensions-tool-display
+description: "配置与排查 Pi 工具展示宿主、内建/自定义工具 override、输出模式和 diff 视图。Use when changing pi-extensions-tool-display rendering."
+---
+
+# 配置 pi-extensions-tool-display
+
+## 诊断
+
+读取实际 Pi agent 目录下的 `extensions/pi-tool-display/config.json`。注意目录名是 `pi-tool-display`，不是 npm 包名。以包内 `config.example.json` 和当前源码支持的字段为准。
+
+确认没有同时加载另一份工具展示宿主；`pi-distill` 与 `pi-tool-supervisor` 已会加载这个共享宿主，通常无需重复安装。
+
+## 修改
+
+优先运行 `/config:tool-display`；`/tool-display`、`/pi-tool-display` 是兼容别名。按目标最小修改：
+
+- `registerToolOverrides` 控制 `read/grep/find/ls/bash/edit/write` 的展示所有权；
+- `customToolOverrides.<tool>` 使用 `enabled`、`kind`、`outputMode`；
+- `readOutputMode`、`searchOutputMode`、`mcpOutputMode`、`bashOutputMode` 控制输出展示；
+- `diffViewMode`、`diffIndicatorMode`、折叠行数和换行字段只影响 diff UI；
+- `enabled: false` 关闭宿主展示。
+
+不要把展示开关解释为禁用工具，也不要让多个宿主同时注册同一内建 override。
+
+## 验证
+
+分别调用一个受影响的内建或自定义工具，观察折叠、预览、diff 或输出模式。若消费者审计卡片未出现，先确认宿主只加载一次，再确认消费者 middleware 已注册；不能用配置文件可解析代替真实 UI 证据。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-extensions-tool-display",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Pi tool display host and shared result-rendering protocol for extensions",
   "type": "module",
   "main": "./index.ts",
@@ -15,6 +15,7 @@
     "config.example.json",
     "README.md",
     "README.zh-CN.md",
+    "SKILL.md",
     "tsconfig.json"
   ],
   "scripts": {
@@ -53,6 +54,9 @@
   "pi": {
     "extensions": [
       "./index.ts"
+    ],
+    "skills": [
+      "./SKILL.md"
     ]
   },
   "devDependencies": {

package/src/config-modal.ts

@@ -104,7 +104,7 @@ export function buildInspectorSettings(
 			inspectorTitle: "Global Tool Display Switch",
 			inspectorSummary: [
 				"Enables or disables all pi-tool-display rendering and tool ownership behavior.",
-				"The /tool-display command remains available while disabled so the extension can be enabled again without editing Pi package settings.",
+				"The /config:tool-display command remains available while disabled so the extension can be enabled again without editing Pi package settings.",
 			],
 			inspectorOptions: [
 				"on — enable tool overrides and enhanced rendering",
@@ -500,7 +500,7 @@ export function handleToolDisplayArgs(args: string, ctx: ExtensionCommandContext
 		const candidate = normalized.slice("preset ".length).trim();
 		const preset = parseToolDisplayPreset(candidate);
 		if (!preset) {
-			ctx.ui.notify(`Unknown preset. Use: /tool-display preset ${PRESET_COMMAND_HINT}`, "warning");
+			ctx.ui.notify(`Unknown preset. Use: /config:tool-display preset ${PRESET_COMMAND_HINT}`, "warning");
 			return true;
 		}
 
@@ -509,7 +509,7 @@ export function handleToolDisplayArgs(args: string, ctx: ExtensionCommandContext
 		return true;
 	}
 
-	ctx.ui.notify(`Usage: /tool-display [show|reset|preset ${PRESET_COMMAND_HINT}]`, "warning");
+	ctx.ui.notify(`Usage: /config:tool-display [show|reset|preset ${PRESET_COMMAND_HINT}]`, "warning");
 	return true;
 }
 
@@ -523,7 +523,7 @@ export async function runToolDisplayCommandHandler(
 	}
 
 	if (!ctx.hasUI) {
-		ctx.ui.notify("/tool-display requires interactive TUI mode.", "warning");
+		ctx.ui.notify("/config:tool-display requires interactive TUI mode.", "warning");
 		return;
 	}
 
@@ -531,10 +531,13 @@ export async function runToolDisplayCommandHandler(
 }
 
 export function registerToolDisplayCommand(pi: ExtensionAPI, controller: ToolDisplayConfigController): void {
-	pi.registerCommand("tool-display", {
+	const command = {
 		description: "Configure tool output rendering (OpenCode-style)",
 		handler: async (args, ctx) => {
 			await runToolDisplayCommandHandler(args, ctx, controller);
 		},
-	});
+	};
+	for (const name of ["config:tool-display", "tool-display", "pi-tool-display"] as const) {
+		pi.registerCommand(name, command);
+	}
 }

package/src/index.ts

@@ -44,9 +44,9 @@ export function toolDisplayReloadRequired(
 
 const initializedHosts = new WeakSet<ExtensionAPI>();
 
-function hasRegisteredToolDisplayCommand(pi: ExtensionAPI): boolean {
+function hasRegisteredToolDisplayCommand(pi: ExtensionAPI, name: string): boolean {
   try {
-    return pi.getCommands().some((command) => command.name === "tool-display");
+    return pi.getCommands().some((command) => command.name === name);
   } catch {
     return false;
   }
@@ -119,15 +119,16 @@ export function ensureToolDisplayHost(
 
   // Each Pi extension has its own registration map, while getCommands() sees
   // the shared runtime. Check the latter so feature extensions do not expose
-  // duplicate /tool-display entries when they initialize this host separately.
-  if (!hasRegisteredToolDisplayCommand(pi)) {
-    pi.registerCommand("tool-display", {
-      description: "Configure tool output rendering (OpenCode-style)",
-      handler: async (args, ctx) => {
-        const { runToolDisplayCommandHandler } = await import("./config-modal.js");
-        await runToolDisplayCommandHandler(args, ctx, { getConfig, setConfig, getCapabilities });
-      },
-    });
+  // duplicate management commands when they initialize this host separately.
+  const command = {
+    description: "Configure tool output rendering (OpenCode-style)",
+    handler: async (args: string, ctx: ExtensionCommandContext) => {
+      const { runToolDisplayCommandHandler } = await import("./config-modal.js");
+      await runToolDisplayCommandHandler(args, ctx, { getConfig, setConfig, getCapabilities });
+    },
+  };
+  for (const name of ["config:tool-display", "tool-display", "pi-tool-display"] as const) {
+    if (!hasRegisteredToolDisplayCommand(pi, name)) pi.registerCommand(name, command);
   }
 
   pi.on("session_start", async (_event, ctx) => {

package/src/result-render-middleware.ts

@@ -66,10 +66,14 @@ export function registerResultRenderMiddleware(
   const api = getApi();
   if (typeof api?.registerResultRenderMiddleware === "function") {
     api.registerResultRenderMiddleware(registration);
-  } else {
-    queueRegistration(registration);
   }
 
+  // Keep the registration in the shared protocol queue even when a host is
+  // already available. The host can be replaced during /reload or when a new
+  // session creates a new ExtensionAPI instance; the new host must be able to
+  // rehydrate registrations that were attached to the previous API object.
+  queueRegistration(registration);
+
   return () => {
     getApi()?.unregisterResultRenderMiddleware?.(registration.id);
     removeQueuedRegistration(registration.id);

package/src/tool-overrides.ts

@@ -1525,8 +1525,11 @@ function drainPendingResultRenderMiddlewares(api: ToolDisplayApi): void {
   const pending = globalWithApi[TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY];
   if (!Array.isArray(pending) || pending.length === 0) return;
 
-  const entries = pending.splice(0);
-  for (const entry of entries) {
+  // This queue is the cross-host registry for external middleware, not a
+  // one-shot bootstrap queue. Keep it populated so a replacement host during
+  // /reload or a new session can rehydrate middleware registered on the old
+  // API instance.
+  for (const entry of pending) {
     if (!entry?.id || !entry.toolName || typeof entry.middleware !== "function") continue;
     api.registerResultRenderMiddleware(entry);
   }

package/tool-display-api-consumer.js

@@ -53,19 +53,25 @@ export function registerToolResultRenderMiddleware(toolName, middleware, options
   }
 
   const id = options.id || `external-result-middleware-${++nextResultMiddlewareId}`;
+  const registration = { id, toolName, middleware };
   const api = getToolDisplayApi();
   if (typeof api?.registerResultRenderMiddleware === "function") {
-    return api.registerResultRenderMiddleware({ id, toolName, middleware });
+    const registeredId = api.registerResultRenderMiddleware(registration);
+    queueResultRenderMiddleware(registration);
+    return registeredId;
   }
 
+  queueResultRenderMiddleware(registration);
+  return id;
+}
+
+function queueResultRenderMiddleware(registration) {
   const existing = globalThis[TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY];
   const queue = Array.isArray(existing) ? existing : [];
-  const registration = { id, toolName, middleware };
-  const index = queue.findIndex((entry) => entry?.id === id);
+  const index = queue.findIndex((entry) => entry?.id === registration.id);
   if (index >= 0) queue[index] = registration;
   else queue.push(registration);
   globalThis[TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY] = queue;
-  return id;
 }
 
 export function unregisterToolResultRenderMiddleware(id) {