@fyeeme/pi-hooks 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.5] - 2026-09-16
+
+### Fixed
+
+- A bare exit code 2 with no parseable JSON on stdout is no longer treated as a deny: it is logged as a suspected broken hook command and the tool call proceeds. A crash or misconfiguration (e.g. `python3` exiting 2 for "can't open file") previously hard-blocked every tool call for the rest of the session. Structured JSON denies (`permissionDecision: "deny"`, or exit 2 carrying a deny payload) are unchanged.
+
+## [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

package/README.md

@@ -136,7 +136,8 @@ Commands may return JSON on stdout, or control flow via exit codes:
 ```
 
 - 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** (PreToolUse) **with a JSON deny payload** (`permissionDecision: "deny"`) → 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** without parseable JSON (e.g. a broken command like `python3` failing to open a script) → treated as a crash, not a deny: warning on stderr, tool call proceeds. This keeps a misconfigured hook from hard-blocking every tool call.
 - exit code **2** (Stop) → ignored (pi cannot block exit).
 - other non-zero → logged, execution continues.
 - non-JSON stdout → logged as a warning, ignored.

package/index.ts

@@ -51,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 {
@@ -105,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 });
 		}
@@ -242,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 };
 }
@@ -262,6 +284,18 @@ export function parseHookOutput(command: string, stdout: string, exitCode: numbe
 		}
 	}
 
+	// A bare exit code 2 with no parseable stdout is indistinguishable from a
+	// broken hook command (e.g. `python3` exits 2 for "can't open file"), and
+	// taking it as a deny hard-blocks EVERY tool call for the rest of the
+	// session. Treat the unstructured case as a suspected crash instead: warn
+	// and allow. A structured JSON deny still blocks, whatever the exit code.
+	if (exitCode === 2 && output === null) {
+		console.error(
+			`[hooks] exit 2 without a JSON deny payload from ${command} — likely a broken command, not a deny; allowing the call`,
+		);
+		return { context: null, block: null };
+	}
+
 	const context = output?.hookSpecificOutput?.additionalContext ?? null;
 	const deny = exitCode === 2 || output?.hookSpecificOutput?.permissionDecision === "deny";
 	const reason =
@@ -282,6 +316,7 @@ async function runCommand(
 	cwd: string,
 	stdinText: string,
 	timeoutMs: number,
+	denyAsContext: boolean,
 	signal?: AbortSignal,
 ): Promise<HookResult> {
 	return new Promise((resolve) => {
@@ -377,7 +412,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) => {
@@ -407,13 +443,14 @@ async function runGroups(
 ): 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,
 			});
 		}
 	}
@@ -425,7 +462,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, signal)))));
+		results.push(
+			...(await Promise.all(batch.map((c) => runCommand(c.command, cwd, stdinText, c.timeoutMs, c.denyAsContext, signal)))),
+		);
 	}
 
 	const contexts: string[] = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fyeeme/pi-hooks",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "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",