@fyeeme/pi-hooks 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -5,7 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.0.4] - 2026-09-12
+
+### Added
+
+- `denyAsContext` per-hook flag: a deny (`permissionDecision: "deny"` or exit code 2) is demoted to `additionalContext` — the tool call proceeds and the nudge text is injected before the next LLM call instead of blocking the agent (e.g. `serena-hooks remind` stops killing read bursts).
+
+## [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
 

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";
 
 // ============================================================================
@@ -43,6 +51,11 @@ interface HookEntry {
 	command: string;
 	/** Per-hook timeout in seconds (Claude Code compatible). Default 60. */
 	timeout?: number;
+	/** Demote deny (`permissionDecision: "deny"` or exit code 2) to
+	 *  `additionalContext`: the tool call proceeds and the nudge text is
+	 *  injected before the next LLM call instead of blocking the agent
+	 *  (e.g. `serena-hooks remind`). */
+	denyAsContext?: boolean;
 }
 
 interface HookGroup {
@@ -97,7 +110,12 @@ export function normalizeConfig(raw: unknown): HooksConfig | null {
 				if (he.type !== "command" || typeof he.command !== "string") continue;
 				const timeout =
 					typeof he.timeout === "number" && he.timeout > 0 ? he.timeout : undefined;
-				entries.push({ type: "command", command: he.command, ...(timeout === undefined ? {} : { timeout }) });
+				entries.push({
+					type: "command",
+					command: he.command,
+					...(timeout === undefined ? {} : { timeout }),
+					...(he.denyAsContext === true ? { denyAsContext: true } : {}),
+				});
 			}
 			if (entries.length > 0) groups.push({ matcher: gr.matcher, hooks: entries });
 		}
@@ -137,13 +155,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 +189,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;
 }
 
 // ============================================================================
@@ -213,6 +252,18 @@ export interface HookResult {
 	block: string | null;
 }
 
+/**
+ * Demote a deny to a pure context hint (`denyAsContext` per-hook flag): the
+ * tool call proceeds and the nudge text rides along before the next LLM call
+ * instead of blocking the agent. Prefers the hook's own `additionalContext`
+ * (e.g. serena-hooks remind's "Consider using Serena's symbolic tools...")
+ * and falls back to the block reason.
+ */
+export function applyDenyAsContext(result: HookResult): HookResult {
+	if (!result.block) return result;
+	return { context: result.context ?? result.block, block: null };
+}
+
 function emptyResult(): HookResult {
 	return { context: null, block: null };
 }
@@ -253,8 +304,16 @@ async function runCommand(
 	cwd: string,
 	stdinText: string,
 	timeoutMs: number,
+	denyAsContext: boolean,
+	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 +334,7 @@ async function runCommand(
 			settled = true;
 			clearTimeout(sigtermTimer);
 			clearTimeout(sigkillTimer);
+			signal?.removeEventListener("abort", onAbort);
 			resolve(result);
 		};
 
@@ -311,6 +371,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) => {
@@ -335,7 +400,8 @@ async function runCommand(
 			// parseHookOutput honors it as a block, so don't log it as a failure.
 			if (code !== 0 && code !== 2 && code !== null) console.error(`[hooks] exited ${code}: ${command}`);
 			const stdout = Buffer.concat(chunks).toString("utf8").trim();
-			finish(parseHookOutput(command, stdout, code));
+			const result = parseHookOutput(command, stdout, code);
+			finish(denyAsContext ? applyDenyAsContext(result) : result);
 		});
 
 		proc.on("error", (err) => {
@@ -361,16 +427,18 @@ async function runGroups(
 	toolName: string,
 	cwd: string,
 	stdinText: string,
+	signal?: AbortSignal,
 ): Promise<{ contexts: string[]; block: string | null }> {
 	if (!groups) return { contexts: [], block: null };
 
-	const commands: Array<{ command: string; timeoutMs: number }> = [];
+	const commands: Array<{ command: string; timeoutMs: number; denyAsContext: boolean }> = [];
 	for (const group of groups) {
 		if (!matchTool(group.matcher, toolName)) continue;
 		for (const hook of group.hooks) {
 			commands.push({
 				command: hook.command,
 				timeoutMs: (hook.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+				denyAsContext: hook.denyAsContext === true,
 			});
 		}
 	}
@@ -382,7 +450,9 @@ 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, c.denyAsContext, signal)))),
+		);
 	}
 
 	const contexts: string[] = [];
@@ -478,7 +548,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 +599,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.4",
+  "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",