@zhushanwen/pi-unified-hooks 0.0.1

package/README.md

@@ -0,0 +1,55 @@
+# unified-hooks — Unified Hooks Extension
+
+Collect scattered hooks in one place for easy maintenance. Each hook is a self-contained module that can be enabled/disabled independently.
+
+## Installation
+
+```bash
+ln -s /path/to/xyz-pi-extensions/unified-hooks ~/.pi/agent/extensions/unified-hooks
+```
+
+## Available Hooks
+
+### edit-whitespace-autofix
+
+When edit tool fails due to whitespace mismatch, injects a steering message that tells the AI to fix whitespace and retry.
+
+**Trigger patterns:**
+- `Could not find the exact text`
+- `oldText must match exactly`
+- `Could not find edits[`
+
+**Behavior:**
+1. Detect whitespace mismatch error from edit tool
+2. Extract the file path from tool args
+3. Inject steer message with `fix_whitespace.py --fix <file>` command
+4. AI automatically fixes whitespace and retries the edit
+
+### tool-error-handler
+
+Logs all tool execution errors to console for debugging.
+
+## Adding New Hooks
+
+1. Create `src/hooks/my-hook.ts`:
+   ```typescript
+   import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+   export function setupMyHook(pi: ExtensionAPI): void {
+     pi.on("tool_execution_end", async (event) => {
+       if (event.toolName === "edit" && event.isError) {
+         // Your logic
+       }
+     });
+   }
+   ```
+
+2. Register in `src/index.ts` hookModules array
+
+3. Type check: `npx tsc --noEmit`
+
+## Important API Notes
+
+- Use `pi.sendUserMessage()` in event handlers, **not** `ctx.sendUserMessage()` (only available in command context)
+- `tool_execution_end` event has `{ toolCallId, toolName, args, result, isError }`
+- Inject direct instructions in steer messages, don't try to invoke `/skill-name` via text

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@zhushanwen/pi-unified-hooks",
+  "version": "0.0.1",
+  "description": "Unified hooks extension - collect scattered hooks in one place for easy maintenance",
+  "main": "index.js",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "extension",
+    "hooks"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "typebox": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "files": [
+    "src/",
+    "index.ts"
+  ],
+  "scripts": {
+    "typecheck": "npx tsc --noEmit"
+  }
+}

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

@@ -0,0 +1,15 @@
+/**
+ * Tool Error Handler Hook
+ *
+ * Logs tool execution errors for debugging. Can be extended to handle
+ * specific error patterns with contextual recovery.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+export function setupToolErrorHandler(pi: ExtensionAPI): void {
+  pi.on("tool_execution_end", async (event) => {
+    if (!event.isError) return;
+    console.log(`[unified-hooks] ${event.toolName} error (callId=${event.toolCallId})`);
+  });
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Unified Hooks Extension
+ *
+ * Collects scattered hooks in one place for easy maintenance.
+ * Each hook is a self-contained module that can be enabled/disabled independently.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+// Re-export hook modules for easy access
+export { setupToolErrorHandler } from "./hooks/tool-error-handler";
+
+import { setupToolErrorHandler } from "./hooks/tool-error-handler";
+
+/**
+ * Extension factory - registers all unified hooks
+ */
+export default function unifiedHooksExtension(pi: ExtensionAPI): void {
+  // Initialize hook registry
+  const hooks: Array<{ name: string; enabled: boolean }> = [];
+
+  // edit-stale-content-guard removed: pi-hashline-edit replaces built-in edit
+  // with hash-anchor mode, making oldText-based guard unreachable
+  const hookModules = [
+    { name: "tool-error-handler", setup: setupToolErrorHandler },
+  ];
+
+  for (const hook of hookModules) {
+    try {
+      hook.setup(pi);
+      hooks.push({ name: hook.name, enabled: true });
+    } catch (err) {
+      console.error(`[unified-hooks] Failed to setup ${hook.name}:`, err);
+      hooks.push({ name: hook.name, enabled: false });
+    }
+  }
+
+  // Log hook status on session start for debugging
+  pi.on("session_start", () => {
+    const enabled = hooks.filter((h) => h.enabled).map((h) => h.name);
+    const disabled = hooks.filter((h) => !h.enabled).map((h) => h.name);
+    console.log(
+      `[unified-hooks] Loaded: ${enabled.join(", ") || "(none)"}${
+        disabled.length ? ` | Failed: ${disabled.join(", ")}` : ""
+      }`
+    );
+  });
+}