@fyeeme/pi-hooks 1.0.2 → 1.0.3

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.3] - 2026-09-09
+
+### Fixed
+
+- PreToolUse hook processes are killed through the existing SIGTERM→SIGKILL escalation when the turn is aborted (`ctx.signal`); an already-aborted turn skips spawning entirely.
+- Hook `additionalContext` injected into the prompt is capped at 50KB/2000 lines with a truncation notice.
+
+### Changed
+
+- Config resolution now prioritizes `~/.pi/agent/hooks.json` (user-global, resolved via `getAgentDir()` so `PI_CODING_AGENT_DIR` is honored) above the project `.pi/hooks.json`; the legacy `~/.pi/hooks.json` location remains the last fallback. A candidate that parses but defines no hooks (e.g. `{}`, or a leftover file in an older schema) no longer shadows lower-priority files — the chain falls through to the next candidate (`PI_HOOKS_CONFIG` remains an exclusive single source when set). Configs are still winner-take-all, never merged.
+
 ## [1.0.2] - 2026-08-08
 
 ### Breaking Changes

package/README.md

@@ -1,6 +1,15 @@
 # pi-hooks
 
-A Claude Code-compatible hooks runner for [pi](https://pi.dev). Reads `.pi/hooks.json` from your project and maps `SessionStart`, `PreToolUse`, and `Stop` events to pi lifecycle events — matching Claude Code's hooks protocol including stdin JSON and stdout `additionalContext` capture.
+A Claude Code-compatible hooks runner for [pi](https://pi.dev). Reads your hooks configuration and maps `SessionStart`, `PreToolUse`, and `Stop` events to pi lifecycle events — matching Claude Code's hooks protocol including stdin JSON and stdout `additionalContext` capture.
+
+**Config resolution order** (first file that defines at least one hook wins):
+
+1. `PI_HOOKS_CONFIG` env var (exclusive single source when set)
+2. `~/.pi/agent/hooks.json` — user-global, **top priority**
+3. `<project>/.pi/hooks.json` — project-local fallback
+4. `~/.pi/hooks.json` — legacy home location fallback
+
+A file that parses but defines no hooks (e.g. `{}`, or a leftover file in an older schema) does not shadow lower-priority files — the chain falls through. Note the chain is winner-take-all: configs are never merged.
 
 ## Install
 
@@ -39,7 +48,7 @@ See the Pi Packages guide on [pi.dev](https://pi.dev) for the full list of sourc
 
 ## Configuration
 
-Create `.pi/hooks.json` in your project root:
+Create `~/.pi/agent/hooks.json` (user-global, highest file priority — runs in every project) or `.pi/hooks.json` in a project root (used only when no global config defines hooks):
 
 ```json
 {
@@ -139,6 +148,54 @@ The `additionalContext` is injected into the pi conversation (appended to the la
 
 Pi names MCP tools as `<serverName>_<toolName>` (not `mcp__server__tool` like Claude Code), so target them with regex like `plugin_serena_serena_.*`. Check your actual tool names with `/mcp` in pi to set the correct `matcher`.
 
+## Using pi-hooks with Serena
+
+[Serena](https://github.com/oraios/serena) ships a `serena-hooks` CLI (Claude Code compatible) whose four subcommands map cleanly onto pi-hooks events. With Serena's MCP server running in pi (confirm with `/mcp` — you should see a `serena` server), drop this into `~/.pi/agent/hooks.json` (global) or the project's `.pi/hooks.json`:
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "serena-hooks activate --client=claude-code" }]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "serena-hooks remind --client=claude-code" }]
+      },
+      {
+        "matcher": "serena_.*",
+        "hooks": [{ "type": "command", "command": "serena-hooks auto-approve --client=claude-code" }]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [{ "type": "command", "command": "serena-hooks cleanup --client=claude-code" }]
+      }
+    ]
+  }
+}
+```
+
+What each hook does:
+
+| Event | Command | Role |
+|---|---|---|
+| `SessionStart` | `activate` | Prompts the agent to activate the project and read Serena's instructions at session start. |
+| `PreToolUse` (`""`) | `remind` | Nudges the agent to prefer Serena's symbolic tools over raw `read`/`grep`. Runs before every tool call. |
+| `PreToolUse` (`serena_.*`) | `auto-approve` | Auto-approves Serena tool calls while the client is in a permissive permission mode. |
+| `Stop` | `cleanup` | Clears per-session hook state on exit. |
+
+**Get the matcher prefix right.** pi exposes an MCP server's tools as `<server>_<tool>`. With Serena registered as the `serena` MCP server (the default), tools are named `serena_find_symbol`, `serena_read_file`, … → use `serena_.*`. If you installed Serena as a pi **plugin** instead, the names are `plugin_serena_serena_*` → use `plugin_serena_serena_.*`. Run `/mcp` in pi to confirm your exact prefix.
+
+> ⚠️ **`auto-approve` is currently inert under pi-hooks.** `serena-hooks auto-approve` only emits its approval when stdin reports a permissive `permission_mode` (`acceptEdits` or `auto`), but pi-hooks always sends `permission_mode: "default"` today. The hook still runs but stays silent, so pi's own permission flow applies. `activate`, `remind`, and `cleanup` are unaffected. This will resolve once pi-hooks forwards the real permission mode.
+
+`--client=claude-code` is correct for pi: pi-hooks speaks the Claude Code hooks protocol, so Serena treats pi as a Claude Code client.
+
 ## Config Override
 
-Set `PI_HOOKS_CONFIG` env var to point to a custom config path.
+Set `PI_HOOKS_CONFIG` env var to point to a custom config path (exclusive single source; when set, no other location is consulted).

package/index.ts

@@ -3,7 +3,15 @@
  *
  * Claude Code-compatible hooks runner for pi.
  *
- * Reads `.pi/hooks.json` (or `PI_HOOKS_CONFIG` env) and maps:
+ * Reads hooks config with the following priority (first file that defines at
+ * least one hook wins; a valid-but-hookless file falls through to the next
+ * candidate instead of silently disabling everything below it):
+ *   1. PI_HOOKS_CONFIG env (exclusive single source when set)
+ *   2. ~/.pi/agent/hooks.json   (user-global, via getAgentDir())
+ *   3. <cwd>/.pi/hooks.json     (project-local)
+ *   4. ~/.pi/hooks.json         (legacy home location)
+ *
+ * and maps:
  *   SessionStart  → session_start        (source = mapped reason)
  *   PreToolUse    → tool_call            (can block via {block:true})
  *   Stop          → session_shutdown     (cleanup only; cannot block exit)
@@ -31,7 +39,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { CONFIG_DIR_NAME, formatSize } from "@earendil-works/pi-coding-agent";
+import { CONFIG_DIR_NAME, formatSize, getAgentDir, truncateHead, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 // ============================================================================
@@ -137,13 +145,30 @@ export function matchTool(pattern: string, value: string): boolean {
 // Config loader (failure is cached, not re-read every event)
 // ============================================================================
 
+/** True when the normalized config defines at least one runnable hook. */
+function hasAnyHook(cfg: HooksConfig): boolean {
+	return (Object.values(cfg.hooks) as HookGroup[][]).some((groups) => groups.length > 0);
+}
+
 export function loadConfig(cwd: string): HooksConfig | null {
 	const envPath = process.env.PI_HOOKS_CONFIG;
 	// os.homedir() is cross-platform (HOME on POSIX, USERPROFILE on Windows).
+	// getAgentDir() additionally honors PI_CODING_AGENT_DIR.
 	const candidates = envPath
 		? [envPath]
-		: [join(cwd, CONFIG_DIR_NAME, "hooks.json"), join(homedir(), CONFIG_DIR_NAME, "hooks.json")];
-
+		: [
+				join(getAgentDir(), "hooks.json"), // ~/.pi/agent/hooks.json — user-global, top priority
+			join(cwd, CONFIG_DIR_NAME, "hooks.json"), // project-local
+			join(homedir(), CONFIG_DIR_NAME, "hooks.json"), // legacy home
+			];
+
+	// First valid config that defines hooks wins. A candidate that parses but
+	// normalizes to zero hooks (e.g. `{}`, or a file in an older/unrelated
+	// schema) is remembered as a fallback and the chain continues — otherwise a
+	// stale higher-priority file would silently disable a usable config below
+	// it. PI_HOOKS_CONFIG is an explicit pointer: whatever it yields (even
+	// empty) is the answer; no fall-through applies.
+	let hookless: HooksConfig | null = null;
 	for (const p of candidates) {
 		if (!existsSync(p)) continue;
 		let parsed: unknown;
@@ -154,13 +179,17 @@ export function loadConfig(cwd: string): HooksConfig | null {
 			continue;
 		}
 		const cfg = normalizeConfig(parsed);
-		if (cfg) return cfg;
-		// Valid JSON but wrong shape (e.g. copied from CC with events as objects):
-		// warn and fall through to the next candidate instead of silently
-		// returning null while a usable home config exists.
-		console.error(`[hooks] invalid hooks shape in ${p} (expected { "hooks": { ... } })`);
+		if (!cfg) {
+			// Valid JSON but wrong shape (e.g. copied from CC with events as
+			// objects): warn and fall through to the next candidate instead of
+			// silently returning null while a usable config exists.
+			console.error(`[hooks] invalid hooks shape in ${p} (expected { "hooks": { ... } })`);
+			continue;
+		}
+		if (envPath || hasAnyHook(cfg)) return cfg;
+		hookless ??= cfg;
 	}
-	return null;
+	return hookless;
 }
 
 // ============================================================================
@@ -253,8 +282,15 @@ async function runCommand(
 	cwd: string,
 	stdinText: string,
 	timeoutMs: number,
+	signal?: AbortSignal,
 ): Promise<HookResult> {
 	return new Promise((resolve) => {
+		// Already-aborted caller signal (Esc before the hook started): skip the
+		// spawn entirely — a dead turn must not launch new work.
+		if (signal?.aborted) {
+			resolve(emptyResult());
+			return;
+		}
 		const isWin = process.platform === "win32";
 		const proc = spawn(command, [], {
 			shell: true,
@@ -275,6 +311,7 @@ async function runCommand(
 			settled = true;
 			clearTimeout(sigtermTimer);
 			clearTimeout(sigkillTimer);
+			signal?.removeEventListener("abort", onAbort);
 			resolve(result);
 		};
 
@@ -311,6 +348,11 @@ async function runCommand(
 			}, KILL_GRACE_MS);
 		};
 
+		// Esc during the turn aborts ctx.signal: kill the hook tree through the
+		// same SIGTERM→SIGKILL escalation as the timeout path.
+		const onAbort = () => killAndFinish();
+		signal?.addEventListener("abort", onAbort, { once: true });
+
 		// Accumulate raw buffers; decode once at the end to avoid splitting
 		// multi-byte UTF-8 characters across chunks (silent mojibake).
 		proc.stdout?.on("data", (chunk: Buffer) => {
@@ -361,6 +403,7 @@ async function runGroups(
 	toolName: string,
 	cwd: string,
 	stdinText: string,
+	signal?: AbortSignal,
 ): Promise<{ contexts: string[]; block: string | null }> {
 	if (!groups) return { contexts: [], block: null };
 
@@ -382,7 +425,7 @@ async function runGroups(
 	const results: HookResult[] = [];
 	for (let i = 0; i < commands.length; i += MAX_CONCURRENT) {
 		const batch = commands.slice(i, i + MAX_CONCURRENT);
-		results.push(...(await Promise.all(batch.map((c) => runCommand(c.command, cwd, stdinText, c.timeoutMs)))));
+		results.push(...(await Promise.all(batch.map((c) => runCommand(c.command, cwd, stdinText, c.timeoutMs, signal)))));
 	}
 
 	const contexts: string[] = [];
@@ -478,7 +521,14 @@ export default function (pi: ExtensionAPI): void {
 
 		if (toInject.length === 0) return;
 
-		const text = toInject.join("\n\n");
+		// Cap injected context (doc output-truncation rationale: unbounded text
+		// overflows the model context and breaks compaction). The hook's stdout
+		// kill switch is 10MB; the model only ever sees the first 50KB/2000 lines.
+		const joined = toInject.join("\n\n");
+		const capped = truncateHead(joined, { maxLines: DEFAULT_MAX_LINES, maxBytes: DEFAULT_MAX_BYTES });
+		const text = capped.truncated
+			? `${capped.content}\n\n[hooks: additionalContext truncated to ${capped.outputLines}/${capped.totalLines} lines]`
+			: capped.content;
 		const messages = [...event.messages];
 		const lastUserIdx = messages.findLastIndex((m) => (m as { role: string }).role === "user");
 
@@ -522,7 +572,9 @@ export default function (pi: ExtensionAPI): void {
 			tool_input: event.input ?? {},
 		});
 
-		const { contexts, block } = await runGroups(cfg.hooks.PreToolUse, event.toolName, ctx.cwd, JSON.stringify(stdin));
+		// ctx.signal: Esc mid-turn kills running hook processes (same escalation
+		// as the timeout path); undefined outside an active turn is harmless.
+		const { contexts, block } = await runGroups(cfg.hooks.PreToolUse, event.toolName, ctx.cwd, JSON.stringify(stdin), ctx.signal);
 		// A block + terminate skips this round's follow-up LLM call, so queued
 		// context would leak into the next user prompt — drop it on block.
 		if (block) return { block: true, reason: block, terminate: true };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fyeeme/pi-hooks",
-  "version": "1.0.2",
-  "description": "Claude Code-compatible hooks runner for pi. Reads .pi/hooks.json and maps SessionStart, PreToolUse, and Stop events to pi lifecycle events.",
+  "version": "1.0.3",
+  "description": "Claude Code-compatible hooks runner for pi. Reads hooks config (priority: ~/.pi/agent/hooks.json, then project .pi/hooks.json) and maps SessionStart, PreToolUse, and Stop events to pi lifecycle events.",
   "type": "module",
   "license": "MIT",
   "author": "fyeeme",