@fyeeme/pi-hooks 1.0.1 → 1.0.3

package/CHANGELOG.md

@@ -7,6 +7,46 @@ 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
+
+- Matchers are now **regex** (Claude Code compatible) instead of globs. Convert patterns like `plugin_serena_serena_*` → `plugin_serena_serena_.*`. `""`/`"*"` still match all; invalid regex falls back to literal.
+- Minimum supported pi is now **0.84.1** (peer dependency `>=0.84.1`). Required because a denied PreToolUse now returns `terminate: true`, which was added to pi's `tool_call` event in 0.84.1 (#7715).
+
+### Added
+
+- PreToolUse blocking: `permissionDecision: "deny"` and exit code 2 now block the tool via pi's `{ block: true, reason, terminate: true }` (requires pi >= 0.84.1). `terminate` skips the follow-up LLM call only in an all-terminating batch; the block always applies.
+- Claude Code-compatible stdin fields on every hook: `hook_event_name`, `cwd`, `permission_mode`, plus a real `session_id` (pi session UUID) and `transcript_path` (conversation JSONL path).
+- SessionStart `matcher` now matches the session source (`startup`/`resume`/`clear`/...), mapped from the pi `session_start` reason.
+- Per-hook `timeout` (seconds, default 60) and parallel execution of matching hooks.
+
+### Changed
+
+- SessionStart hooks now bind to the `session_start` event (was `before_agent_start`) so source matchers work; `additionalContext` is still injected via the `context` event.
+- Config load result (including failure) is now cached per session — a missing/unreadable file no longer triggers a disk read on every event.
+- Hook subprocesses are killed as a process group (grandchildren no longer orphaned); stdout is capped at 10 MB; multi-byte stdout is decoded once via `Buffer.concat` (no mojibake).
+- `session_id` uses the platform `sessionManager.getSessionId()` instead of a `Date.now()` fallback; user-config lookup uses `os.homedir()` (Windows-compatible).
+
+### Fixed
+
+- Crash: writing stdin to a hook that ignores it raised an uncaught `EPIPE` and killed the whole pi process (stdin/stdout now swallow stream errors).
+- Crash: unbounded stdout accumulation hit the V8 string limit (`RangeError`) and killed pi within ~0.3s.
+- Crash: a syntactically valid but misshapen `hooks.json` (e.g. `{}`, `{ "hooks": null }`) threw `TypeError` inside awaited handlers; configs are now validated/normalized.
+- Dropped `additionalContext` from non-empty-matcher PreToolUse groups.
+- Repeated `[hooks] failed to parse` log spam on every event when the config file was unreadable.
+
 ## [1.0.1] - 2025-07-15
 
 ### Fixed

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
 {
@@ -66,7 +75,7 @@ Create `.pi/hooks.json` in your project root:
         ]
       },
       {
-        "matcher": "plugin_serena_serena_*",
+        "matcher": "plugin_serena_serena_.*",
         "hooks": [
           {
             "type": "command",
@@ -94,33 +103,99 @@ Create `.pi/hooks.json` in your project root:
 
 | hooks.json event | pi event | Notes |
 |---|---|---|
-| `SessionStart` | `session_start` | Runs on startup. `additionalContext` sent via `sendUserMessage`. |
-| `PreToolUse` (empty matcher) | `tool_call` | Runs before every tool with real `tool_name`. `additionalContext` injected before next LLM call. |
-| `PreToolUse` (pattern matcher) | `tool_call` | Glob match against pi tool name (e.g. `plugin_serena_serena_*`). |
-| `Stop` | `session_shutdown` | Runs on exit. |
+| `SessionStart` | `session_start` | Runs on session start/reload/switch. `matcher` matches the source (`startup`/`resume`/`clear`/...); empty matcher matches all. `additionalContext` is injected into the first user message via the `context` event. |
+| `PreToolUse` | `tool_call` | Runs before each tool. `matcher` is a **regex** against the pi tool name. `additionalContext` is injected before the next LLM call. `permissionDecision: "deny"` or exit code 2 blocks the tool (`terminate: true`; in a single-tool / all-terminating batch this also skips the follow-up LLM call — requires pi >= 0.84.1). |
+| `Stop` | `session_shutdown` | Runs on exit/reload/session switch. Cleanup only — `decision: "block"` is **not** honored (pi cannot prevent exit). Stop hooks are awaited, so a slow hook delays exit up to its `timeout` (default 60s); keep them fast. |
+
+## Matcher semantics
+
+`matcher` is a **regex** (Claude Code compatible), tested against the full tool name (PreToolUse) or session source (SessionStart):
+
+- `""` or `"*"` — match all
+- `"Edit|Write"` — match either
+- `"Notebook.*"` — prefix match
+- `"plugin_serena_serena_.*"` — all serena tools
+
+> **Breaking change from 1.0.x:** matchers were previously interpreted as **globs** (`*`/`?`). If you upgraded, convert patterns like `plugin_serena_serena_*` → `plugin_serena_serena_.*`. Invalid regex matches nothing and warns once at first use (never throws).
 
 ## Protocol
 
-Commands receive Claude Code-compatible JSON on stdin:
+Commands receive Claude Code-compatible JSON on stdin (`session_id` is the pi session UUID; `transcript_path` is the conversation JSONL path):
 
 ```json
-{ "type": "session_start", "session_id": "...", "transcript_path": "..." }
-{ "type": "pre_tool_use", "session_id": "...", "tool_name": "bash", "tool_input": {} }
-{ "type": "stop", "session_id": "..." }
+{ "hook_event_name": "SessionStart", "session_id": "<uuid>", "transcript_path": "/path/to/session.jsonl", "cwd": "/proj", "permission_mode": "default", "source": "startup" }
+{ "hook_event_name": "PreToolUse", "session_id": "<uuid>", "transcript_path": "...", "cwd": "/proj", "permission_mode": "default", "tool_name": "bash", "tool_input": {} }
+{ "hook_event_name": "Stop", "session_id": "<uuid>", "transcript_path": "...", "cwd": "/proj", "permission_mode": "default" }
 ```
 
-Commands may return JSON on stdout:
+Commands may return JSON on stdout, or control flow via exit codes:
 
 ```json
-{ "hookSpecificOutput": { "additionalContext": "..." } }
+{ "hookSpecificOutput": { "additionalContext": "context injected into the conversation" } }
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny", "permissionDecisionReason": "blocked" } }
 ```
 
-The `additionalContext` is injected into the pi conversation.
+- exit code **0** with `additionalContext` → context injected.
+- exit code **2** (PreToolUse) → tool call blocked (`terminate: true`); reason fed to the model. `terminate` skips the follow-up LLM call only when the denied call is in an all-terminating batch (pi >= 0.84.1, #7715); in a multi-tool batch the block always applies but the agent may continue.
+- exit code **2** (Stop) → ignored (pi cannot block exit).
+- other non-zero → logged, execution continues.
+- non-JSON stdout → logged as a warning, ignored.
+- each hook may set `"timeout"` (seconds, default 60); matching hooks run in **parallel**.
+
+The `additionalContext` is injected into the pi conversation (appended to the last user message, never as a new turn).
 
 ## MCP Tool Names
 
-Pi names MCP tools as `<serverName>_<toolName>` (not `mcp__server__tool` like Claude Code). Check your actual tool names with `/mcp` in pi to set the correct `matcher`.
+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,34 +3,54 @@
  *
  * Claude Code-compatible hooks runner for pi.
  *
- * Reads `.pi/hooks.json` (or `PI_HOOKS_CONFIG` env) and maps:
- *   SessionStart  → before_agent_start (first turn)
- *   PreToolUse    → tool_call
- *   Stop          → session_shutdown
+ * 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)
  *
- * All additionalContext—from both SessionStart and PreToolUse—is injected
- * into the last user message via the context event. This guarantees the LLM
- * sees and acts on the context without extra turns, fake user messages, or
- * system prompt passivity.
+ * and maps:
+ *   SessionStart  → session_start        (source = mapped reason)
+ *   PreToolUse    → tool_call            (can block via {block:true})
+ *   Stop          → session_shutdown     (cleanup only; cannot block exit)
  *
- * Sequence guarantee:
- *   emitBeforeAgentStart() is awaited by agent-session.ts before
- *   _runAgentPrompt() starts, so before_agent_start always completes
- *   before the first context event fires. No race condition.
+ * All additionalContext — from both SessionStart and PreToolUse — is injected
+ * into the last user message via the context event, so the LLM sees and acts on
+ * it without extra turns, fake user messages, or system-prompt passivity.
+ *
+ * Compatibility notes (vs Claude Code hooks protocol):
+ *   - matchers are **regex** (CC semantics): "" / "*" match all; `Edit|Write`
+ *     alternation and `Notebook.*` work. Invalid regex falls back to literal.
+ *   - PreToolUse `permissionDecision: "deny"` and exit code 2 block the tool
+ *     via pi's `{ block: true, reason, terminate: true }`. The tool is always
+ *     blocked; `terminate` additionally tries to skip the automatic follow-up
+ *     model call, but only takes effect when this is the only/last call in an
+ *     all-terminating batch (pi >= 0.84.1, #7715). In a multi-tool batch the
+ *     block still applies but the agent may continue. ("allow"/"ask" are
+ *     no-ops; pi applies its own permission flow.)
+ *   - Stop `decision: "block"` is NOT honored — pi's session_shutdown is
+ *     notification-only and cannot prevent exit.
+ *   - per-hook `timeout` (seconds) is honored; default 60s.
  */
 
 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, getAgentDir, truncateHead, DEFAULT_MAX_LINES, DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 
 // ============================================================================
-// Config schema
+// Config schema + validation
 // ============================================================================
 
 interface HookEntry {
 	type: "command";
 	command: string;
+	/** Per-hook timeout in seconds (Claude Code compatible). Default 60. */
+	timeout?: number;
 }
 
 interface HookGroup {
@@ -46,139 +66,394 @@ interface HooksConfig {
 	};
 }
 
-interface HookOutput {
-	hookSpecificOutput?: {
-		additionalContext?: string;
-	};
+const HOOK_EVENTS = ["SessionStart", "PreToolUse", "Stop"] as const;
+type HookEventName = (typeof HOOK_EVENTS)[number];
+
+/**
+ * Validate and normalize a parsed config. Returns a safe HooksConfig (missing
+ * events treated as empty) or null if the top-level shape is wrong. Never
+ * throws — a malformed file degrades to "no hooks" rather than crashing the
+ * awaited handler that dereferences `config.hooks.*`.
+ */
+export function normalizeConfig(raw: unknown): HooksConfig | null {
+	if (typeof raw !== "object" || raw === null) return null;
+	const root = raw as Record<string, unknown>;
+	const hooksField = root.hooks;
+	// `{}` or `{"hooks": null}` → no hooks configured (not an error).
+	if (hooksField === undefined || hooksField === null) return { hooks: {} };
+	if (typeof hooksField !== "object" || Array.isArray(hooksField)) return null;
+
+	const out: HooksConfig = { hooks: {} };
+	const hooks = hooksField as Record<string, unknown>;
+	for (const evt of HOOK_EVENTS) {
+		const v = hooks[evt];
+		if (!Array.isArray(v)) continue; // missing or non-array event → ignored
+		const groups: HookGroup[] = [];
+		for (const g of v) {
+			if (!g || typeof g !== "object") continue;
+			const gr = g as Record<string, unknown>;
+			// Validate inner shape so a malformed group/entry can't reach matchTool
+			// (e.g. a missing matcher must not silently match the literal
+			// "undefined") or produce a NaN timeout.
+			if (typeof gr.matcher !== "string") continue;
+			const ghooks = gr.hooks;
+			if (!Array.isArray(ghooks)) continue;
+			const entries: HookEntry[] = [];
+			for (const h of ghooks) {
+				if (!h || typeof h !== "object") continue;
+				const he = h as Record<string, unknown>;
+				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 }) });
+			}
+			if (entries.length > 0) groups.push({ matcher: gr.matcher, hooks: entries });
+		}
+		if (groups.length > 0) out.hooks[evt] = groups;
+	}
+	return out;
 }
 
 // ============================================================================
-// Glob matching
+// Matcher (Claude Code regex semantics)
 // ============================================================================
 
-export function globMatch(pattern: string, value: string): boolean {
-	if (pattern === "") return true;
-	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
-	const regexStr = escaped.replace(/\*/g, ".*").replace(/\?/g, ".");
-	return new RegExp(`^${regexStr}$`).test(value);
+/**
+ * Claude Code matcher: "" or "*" match all; otherwise the pattern is a regex
+ * tested against the full value (anchored). Invalid regex falls back to a
+ * literal exact match so a bad pattern never throws inside an event handler.
+ */
+/** Compiled matcher cache (avoid recompiling per event); null = invalid regex. */
+const matcherCache = new Map<string, RegExp | null>();
+
+export function matchTool(pattern: string, value: string): boolean {
+	if (pattern === "" || pattern === "*") return true;
+	let regex = matcherCache.get(pattern);
+	if (regex === undefined) {
+		try {
+			regex = new RegExp(`^(?:${pattern})$`);
+		} catch {
+			regex = null; // invalid regex matches nothing (CC has no literal fallback)
+			console.warn(`[hooks] invalid matcher regex "${pattern}" — will never match`);
+		}
+		matcherCache.set(pattern, regex);
+	}
+	return regex !== null && regex.test(value);
 }
 
 // ============================================================================
-// Config loader - cached per session via ??=
+// 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, ".pi", "hooks.json"), join(process.env.HOME ?? "", ".pi", "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;
 		try {
-			return JSON.parse(readFileSync(p, "utf-8")) as HooksConfig;
+			parsed = JSON.parse(readFileSync(p, "utf-8"));
 		} catch (err) {
 			console.error(`[hooks] failed to parse ${p}: ${err}`);
+			continue;
+		}
+		const cfg = normalizeConfig(parsed);
+		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;
 }
 
 // ============================================================================
-// Session ID
+// Session id / transcript path (CC-compatible field semantics)
 // ============================================================================
 
 function getSessionId(ctx: ExtensionContext): string {
-	try {
-		const sm = ctx.sessionManager as { getSessionFile?: () => string | undefined };
-		const file = sm.getSessionFile?.();
-		if (file) return file;
-	} catch { /* ignore */ }
-	return `${ctx.cwd}:${Date.now()}`;
+	// Platform-stable UUID (session-manager.getSessionId()). Never falls back to
+	// a time-based value, so session_id is stable across events in one session.
+	return ctx.sessionManager.getSessionId();
+}
+
+function getTranscriptPath(ctx: ExtensionContext): string {
+	// The conversation JSONL file path (CC transcript_path semantics).
+	return ctx.sessionManager.getSessionFile() ?? "";
+}
+
+function buildStdin(
+	hookEventName: HookEventName,
+	ctx: ExtensionContext,
+	extra: Record<string, unknown> = {},
+): Record<string, unknown> {
+	return {
+		session_id: getSessionId(ctx),
+		transcript_path: getTranscriptPath(ctx),
+		cwd: ctx.cwd,
+		permission_mode: "default",
+		hook_event_name: hookEventName,
+		...extra,
+	};
+}
+
+// ============================================================================
+// Hook output parsing (control flow + context)
+// ============================================================================
+
+interface HookOutput {
+	hookSpecificOutput?: {
+		additionalContext?: string;
+		permissionDecision?: "allow" | "deny" | "ask";
+		permissionDecisionReason?: string;
+	};
+	reason?: string;
+}
+
+export interface HookResult {
+	/** additionalContext to inject, if any. */
+	context: string | null;
+	/** Block reason (shown to the LLM), or null when not blocking. */
+	block: string | null;
+}
+
+function emptyResult(): HookResult {
+	return { context: null, block: null };
+}
+
+/**
+ * Parse a hook's stdout + exit code into a normalized result. Handles the two
+ * Claude Code blocking signals: exit code 2 and `permissionDecision: "deny"`.
+ */
+export function parseHookOutput(command: string, stdout: string, exitCode: number | null): HookResult {
+	let output: HookOutput | null = null;
+	if (stdout) {
+		try {
+			output = JSON.parse(stdout) as HookOutput;
+		} catch {
+			// Non-JSON stdout (e.g. a stray `echo`/`console.log`) is a common
+			// misconfiguration — surface it instead of failing silently.
+			console.error(`[hooks] non-JSON stdout from ${command}: ${stdout.slice(0, 200)}`);
+		}
+	}
+
+	const context = output?.hookSpecificOutput?.additionalContext ?? null;
+	const deny = exitCode === 2 || output?.hookSpecificOutput?.permissionDecision === "deny";
+	const reason =
+		output?.hookSpecificOutput?.permissionDecisionReason ?? output?.reason ?? "blocked by hook";
+	return { context, block: deny ? reason : null };
 }
 
 // ============================================================================
-// Command runner - pipes JSON to stdin, captures stdout JSON
+// Command runner
 // ============================================================================
 
-async function runCommand(command: string, cwd: string, stdinJson: unknown): Promise<HookOutput | null> {
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const MAX_STDOUT_BYTES = 10 * 1024 * 1024;
+const KILL_GRACE_MS = 5_000;
+
+async function runCommand(
+	command: string,
+	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,
 			cwd,
+			// detached (non-Windows) → own process group so we can kill the tree.
+			detached: !isWin,
 			stdio: ["pipe", "pipe", "inherit"],
 		});
 
-		let stdout = "";
+		const chunks: Buffer[] = [];
+		let bytes = 0;
+		let killed = false;
 		let settled = false;
-		const finish = (result: HookOutput | null) => {
+		let sigkillTimer: NodeJS.Timeout | undefined;
+
+		const finish = (result: HookResult) => {
 			if (settled) return;
 			settled = true;
 			clearTimeout(sigtermTimer);
 			clearTimeout(sigkillTimer);
+			signal?.removeEventListener("abort", onAbort);
 			resolve(result);
 		};
 
+		const killTree = (sig: "SIGTERM" | "SIGKILL") => {
+			try {
+				if (!isWin && proc.pid) process.kill(-proc.pid, sig);
+				else proc.kill(sig);
+			} catch {
+				/* already dead */
+			}
+		};
+
+		// Swallow stream errors (e.g. EPIPE when a hook ignores stdin) so they
+		// never become an uncaughtException that crashes the whole pi process.
+		const swallow = () => {};
+		proc.stdin?.on("error", swallow);
+		proc.stdout?.on("error", swallow);
+
+		// Escalating kill shared by the stdout-over-limit and timeout paths:
+		// SIGTERM, then SIGKILL after a grace window, then force-resolve. The
+		// force-resolve is essential — `close` may never fire if a grandchild
+		// inherited the stdout pipe and outlives the killed shell, which would
+		// otherwise leave this promise (and the awaiting handler) pending
+		// forever. Sets `killed` so any buffered output is discarded rather than
+		// parsed and applied.
+		const killAndFinish = () => {
+			if (settled) return;
+			killed = true;
+			clearTimeout(sigtermTimer);
+			killTree("SIGTERM");
+			sigkillTimer = setTimeout(() => {
+				killTree("SIGKILL");
+				finish(emptyResult());
+			}, 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) => {
-			stdout += chunk.toString();
+			if (killed) return;
+			bytes += chunk.length;
+			if (bytes > MAX_STDOUT_BYTES) {
+				console.error(`[hooks] stdout exceeded ${formatSize(MAX_STDOUT_BYTES)}, killing: ${command}`);
+				killAndFinish();
+				return;
+			}
+			chunks.push(chunk);
 		});
 
-		let sigkillTimer: NodeJS.Timeout | undefined;
-
-		const sigtermTimer = setTimeout(() => {
-			try { proc.kill("SIGTERM"); } catch { /* already dead */ }
-			// escalate to SIGKILL after a 5s grace window
-			sigkillTimer = setTimeout(() => {
-				try { proc.kill("SIGKILL"); } catch { /* already dead */ }
-				// force-resolve: a process that survives SIGKILL is unrecoverable
-				finish(null);
-			}, 5_000);
-		}, 10_000);
+		const sigtermTimer = setTimeout(killAndFinish, timeoutMs);
 
 		proc.on("close", (code) => {
-			if (code !== 0) console.error(`[hooks] exited ${code}: ${command}`);
-			try {
-				const trimmed = stdout.trim();
-				finish(trimmed ? (JSON.parse(trimmed) as HookOutput) : null);
-			} catch {
-				finish(null);
+			if (killed) {
+				finish(emptyResult());
+				return;
 			}
+			// Exit code 2 is the documented PreToolUse "deny" signal, not an error —
+			// 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));
 		});
 
 		proc.on("error", (err) => {
 			console.error(`[hooks] spawn error: ${command}: ${err}`);
-			finish(null);
+			finish(emptyResult());
 		});
 
 		try {
-			proc.stdin?.write(JSON.stringify(stdinJson));
+			proc.stdin?.write(stdinText);
 			proc.stdin?.end();
-		} catch { /* already exited */ }
+		} catch {
+			/* sync throw only; async stream errors handled by 'error' listeners */
+		}
 	});
 }
 
 // ============================================================================
-// Run matching hook groups, return collected additionalContext strings
+// Run matching hook groups (parallel), collecting context + block decision
 // ============================================================================
 
 async function runGroups(
 	groups: HookGroup[] | undefined,
 	toolName: string,
 	cwd: string,
-	stdinJson: unknown,
-): Promise<string[]> {
-	const contexts: string[] = [];
-	if (!groups) return contexts;
+	stdinText: string,
+	signal?: AbortSignal,
+): Promise<{ contexts: string[]; block: string | null }> {
+	if (!groups) return { contexts: [], block: null };
+
+	const commands: Array<{ command: string; timeoutMs: number }> = [];
 	for (const group of groups) {
-		if (!globMatch(group.matcher, toolName)) continue;
+		if (!matchTool(group.matcher, toolName)) continue;
 		for (const hook of group.hooks) {
-			if (hook.type !== "command") continue;
-			const out = await runCommand(hook.command, cwd, stdinJson);
-			const ctx = out?.hookSpecificOutput?.additionalContext;
-			if (ctx) contexts.push(ctx);
+			commands.push({
+				command: hook.command,
+				timeoutMs: (hook.timeout ?? DEFAULT_TIMEOUT_SECONDS) * 1000,
+			});
 		}
 	}
-	return contexts;
+	if (commands.length === 0) return { contexts: [], block: null };
+
+	// Run concurrently (Claude Code runs matching hooks in parallel) but cap
+	// simultaneous subprocesses; preserve submission order of context.
+	const MAX_CONCURRENT = 8;
+	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, signal)))));
+	}
+
+	const contexts: string[] = [];
+	let block: string | null = null;
+	for (const r of results) {
+		if (r.context) contexts.push(r.context);
+		if (r.block && block === null) block = r.block;
+	}
+	return { contexts, block };
+}
+
+// ============================================================================
+// SessionStart reason → Claude Code source mapping
+// ============================================================================
+
+function mapSessionSource(reason: string | undefined): string {
+	switch (reason) {
+		case "new":
+			return "clear"; // CC SessionStart "clear" matcher
+		case "resume":
+			return "resume";
+		case "fork":
+			return "resume"; // fork continues history — closer to CC "resume" than "startup"
+		case "reload":
+		case "startup":
+		default:
+			return "startup";
+	}
 }
 
 // ============================================================================
@@ -186,51 +461,51 @@ async function runGroups(
 // ============================================================================
 
 export default function (pi: ExtensionAPI): void {
+	// undefined = not loaded yet; null = loaded but no config. The single
+	// variable distinguishes both, so a missing/unreadable file is not
+	// re-read on every event.
 	let config: HooksConfig | null | undefined;
+	const getConfig = (cwd: string): HooksConfig | null => {
+		if (config === undefined) {
+			config = loadConfig(cwd);
+		}
+		return config;
+	};
 
-	// SessionStart additionalContext waiting to be injected on the first LLM call.
-	// Set by before_agent_start (which is awaited before the agent loop starts),
-	// consumed once by the context handler.
+	// SessionStart additionalContext waiting to be injected on the first LLM
+	// call. session_start fires before the first context event, so this is set
+	// in time for injection. Consumed once by the context handler.
 	let activateContext: string | null = null;
-	let activated = false;
 
-	// PreToolUse additionalContext queued by tool_call, injected before each LLM call.
+	// PreToolUse additionalContext queued by tool_call, injected before each
+	// LLM call.
 	const pendingContexts: string[] = [];
 
 	// -------------------------------------------------------------------------
-	// before_agent_start: SessionStart hooks (first turn only).
-	//
-	// Runs the hook and stores additionalContext for injection. Does NOT return
-	// a message or modify the system prompt—injection happens in context so all
-	// LLM message modification is in one place and the activate context is
-	// treated identically to remind context by the LLM.
+	// session_start: SessionStart hooks.
 	//
-	// Sequencing: agent-session.ts awaits emitBeforeAgentStart() before calling
-	// _runAgentPrompt(), so this handler always completes before context fires.
+	// Bound to session_start (not before_agent_start) so the matcher can match
+	// the session source (startup/resume/clear/...). session_start fires before
+	// the first context event, so activateContext is ready in time.
 	// -------------------------------------------------------------------------
-	pi.on("before_agent_start", async (_event, ctx) => {
-		config ??= loadConfig(ctx.cwd);
-		if (!config || activated) return;
-		activated = true;
-
-		const stdin = {
-			type: "session_start",
-			session_id: getSessionId(ctx),
-			transcript_path: getSessionId(ctx),
-		};
-		const contexts = await runGroups(config.hooks.SessionStart, "", ctx.cwd, stdin);
-		if (contexts.length > 0) {
-			activateContext = contexts.join("\n\n");
-		}
+	pi.on("session_start", async (event, ctx) => {
+		// "reload" is a runtime rebind, not a session-source event — SessionStart
+		// hooks must not re-run mid-session.
+		if (event.reason === "reload") return;
+		const cfg = getConfig(ctx.cwd);
+		if (!cfg?.hooks.SessionStart) return;
+		const source = mapSessionSource(event.reason);
+		const stdin = buildStdin("SessionStart", ctx, { source });
+		const { contexts } = await runGroups(cfg.hooks.SessionStart, source, ctx.cwd, JSON.stringify(stdin));
+		if (contexts.length > 0) activateContext = contexts.join("\n\n");
 	});
 
 	// -------------------------------------------------------------------------
 	// context: inject all pending contexts before each LLM call.
 	//
-	// Combines activate (SessionStart) and remind (PreToolUse) contexts.
-	// Appends to the last user message's content array—never adds a new message—
-	// so there are no consecutive-user-message issues and no extra turns.
-	// The injected text is invisible to the display layer (UI shows original).
+	// Appends to the last user message's content array — never adds a new
+	// message — so there are no consecutive-user-message issues and no extra
+	// turns. Handles both array and (defensively) string content shapes.
 	// -------------------------------------------------------------------------
 	pi.on("context", (event) => {
 		const toInject: string[] = [];
@@ -246,25 +521,35 @@ 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");
 
 		if (lastUserIdx >= 0) {
-			// Append to the last user message's content array. pi-hooks operates on
-			// messages structurally (any role:"user" message whose content is an
-			// array); it does not depend on a specific message variant type, so we
-			// bridge through `unknown` rather than asserting an incompatible shape.
-			const last = messages[lastUserIdx] as unknown as {
-				role: string;
-				content: unknown[];
-			};
-			if (Array.isArray(last.content)) {
+			const last = messages[lastUserIdx] as unknown as { role: string; content: unknown };
+			const c = last.content;
+			if (typeof c === "string") {
 				messages[lastUserIdx] = {
 					...last,
-					content: [...last.content, { type: "text" as const, text }],
+					content: [
+						{ type: "text" as const, text: c },
+						{ type: "text" as const, text },
+					],
+				} as unknown as (typeof messages)[number];
+			} else if (Array.isArray(c)) {
+				messages[lastUserIdx] = {
+					...last,
+					content: [...c, { type: "text" as const, text }],
 				} as unknown as (typeof messages)[number];
 			}
+			// non-string/non-array content: leave untouched (nothing to append to).
 		} else {
 			(messages as unknown[]).push({ role: "user", content: [{ type: "text" as const, text }] });
 		}
@@ -273,39 +558,37 @@ export default function (pi: ExtensionAPI): void {
 	});
 
 	// -------------------------------------------------------------------------
-	// tool_call: PreToolUse hooks.
-	// Empty-matcher groups (remind) run for every tool with the real tool_name.
-	// Non-empty-matcher groups (auto-approve) run only for matching tools.
+	// tool_call: PreToolUse hooks. Honors deny (permissionDecision/exit 2) by
+	// returning { block: true, reason, terminate: true } (terminate skips the
+	// automatic follow-up LLM call; requires pi >= 0.84.1). additionalContext is
+	// queued for the next context event. All matching groups run, regardless of matcher.
 	// -------------------------------------------------------------------------
 	pi.on("tool_call", async (event, ctx) => {
-		config ??= loadConfig(ctx.cwd);
-		if (!config?.hooks.PreToolUse) return;
+		const cfg = getConfig(ctx.cwd);
+		if (!cfg?.hooks.PreToolUse) return;
 
-		const sessionId = getSessionId(ctx);
-		const stdin = {
-			type: "pre_tool_use",
-			session_id: sessionId,
+		const stdin = buildStdin("PreToolUse", ctx, {
 			tool_name: event.toolName,
 			tool_input: event.input ?? {},
-		};
-
-		// Empty-matcher groups: remind (runs for every tool).
-		const emptyGroups = config.hooks.PreToolUse.filter((g) => g.matcher === "");
-		const remindContexts = await runGroups(emptyGroups, event.toolName, ctx.cwd, stdin);
-		if (remindContexts.length > 0) pendingContexts.push(...remindContexts);
+		});
 
-		// Non-empty-matcher groups: auto-approve etc. (filtered by toolName).
-		const specificGroups = config.hooks.PreToolUse.filter((g) => g.matcher !== "");
-		await runGroups(specificGroups, event.toolName, ctx.cwd, 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 };
+		if (contexts.length > 0) pendingContexts.push(...contexts);
 	});
 
 	// -------------------------------------------------------------------------
-	// session_shutdown: Stop hooks.
+	// session_shutdown: Stop hooks (cleanup only). CC's Stop `decision: "block"`
+	// is intentionally not honored — pi cannot prevent exit from here.
 	// -------------------------------------------------------------------------
 	pi.on("session_shutdown", async (_event, ctx) => {
-		config ??= loadConfig(ctx.cwd);
-		if (!config) return;
-		const stdin = { type: "stop", session_id: getSessionId(ctx) };
-		await runGroups(config.hooks.Stop, "", ctx.cwd, stdin);
+		const cfg = getConfig(ctx.cwd);
+		if (!cfg) return;
+		const stdin = buildStdin("Stop", ctx);
+		await runGroups(cfg.hooks.Stop, "", ctx.cwd, JSON.stringify(stdin));
 	});
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fyeeme/pi-hooks",
-  "version": "1.0.1",
-  "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",
@@ -44,10 +44,10 @@
     "typecheck": "tsc"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.77.0"
+    "@earendil-works/pi-coding-agent": ">=0.84.1"
   },
   "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.77.0",
+    "@earendil-works/pi-coding-agent": "0.84.1",
     "@types/node": "22.19.19",
     "typescript": "5.9.3"
   }