@fyeeme/pi-hooks 1.0.4 → 1.0.6

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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.6] - 2026-10-01
+
+### Changed
+
+- Peer dependency floor raised to `@earendil-works/pi-coding-agent >= 0.99.0`; dev toolchain pinned to 0.99.2 (typecheck and tests pass against 0.99.2 unchanged).
+
+### Breaking Changes
+
+- The hooks config file is now `hook.json` (was `hooks.json`), in all three locations: `~/.pi/agent/hook.json` (user-global), `<project>/.pi/hook.json`, and the home-directory fallback `~/.pi/hook.json`. Rename your existing config file; `PI_HOOKS_CONFIG` is unaffected.
+
+### Fixed
+
+- README: pi registers MCP tools as `mcp__<server>__<tool>` (same as Claude Code), not `<server>_<tool>` — fixed the matcher guidance and the Serena example config (`serena_.*` → `mcp__serena__.*`); a wrong matcher silently never matched, disabling `auto-approve`.
+
+### Added
+
+- Ship `pi.yml`, a pi-adapted Serena context (based on upstream `claude-code.yml`): symbol-first steering via `serena start-mcp-server --context pi`, plus trimming of the six Serena tools that duplicate pi built-ins. See README "Recommended: steer at the context level, not only via hooks".
+- Document the `denyAsContext` per-hook flag (shipped in 1.0.4) in the README protocol section.
+
+## [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

package/README.md

@@ -5,12 +5,14 @@ A Claude Code-compatible hooks runner for [pi](https://pi.dev). Reads your hooks
 **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
+2. `~/.pi/agent/hook.json` — user-global, **top priority**
+3. `<project>/.pi/hook.json` — project-local fallback
+4. `~/.pi/hook.json` — home-directory 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.
 
+> **Breaking change from 1.0.5:** the config file was renamed `hooks.json` → `hook.json` (all three locations). Rename your existing file; `PI_HOOKS_CONFIG` is unaffected.
+
 ## Install
 
 Requires the [pi](https://pi.dev) CLI.
@@ -48,7 +50,7 @@ See the Pi Packages guide on [pi.dev](https://pi.dev) for the full list of sourc
 
 ## Configuration
 
-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):
+Create `~/.pi/agent/hook.json` (user-global, highest file priority — runs in every project) or `.pi/hook.json` in a project root (used only when no global config defines hooks):
 
 ```json
 {
@@ -70,12 +72,13 @@ Create `~/.pi/agent/hooks.json` (user-global, highest file priority — runs in
         "hooks": [
           {
             "type": "command",
-            "command": "serena-hooks remind --client=claude-code"
+            "command": "serena-hooks remind --client=claude-code",
+            "denyAsContext": true
           }
         ]
       },
       {
-        "matcher": "plugin_serena_serena_.*",
+        "matcher": "mcp__serena__.*",
         "hooks": [
           {
             "type": "command",
@@ -101,9 +104,9 @@ Create `~/.pi/agent/hooks.json` (user-global, highest file priority — runs in
 
 ## Event Mapping
 
-| hooks.json event | pi event | Notes |
+| hook.json event | pi event | Notes |
 |---|---|---|
-| `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. |
+| `SessionStart` | `session_start` | Runs when a session starts, resumes, forks, or switches — **not** on `reload` (a runtime rebind must not re-run hooks mid-session). `matcher` matches the mapped Claude Code source: `startup` (default), `resume` (resume + fork), `clear` (new session); 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. |
 
@@ -114,9 +117,9 @@ Create `~/.pi/agent/hooks.json` (user-global, highest file priority — runs in
 - `""` or `"*"` — match all
 - `"Edit|Write"` — match either
 - `"Notebook.*"` — prefix match
-- `"plugin_serena_serena_.*"` — all serena tools
+- `"mcp__serena__.*"` — all tools of the `serena` MCP server
 
-> **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).
+> **Breaking change from 1.0.x:** matchers were previously interpreted as **globs** (`*`/`?`). If you upgraded, convert patterns like `mcp__serena__*` → `mcp__serena__.*`. Invalid regex matches nothing and warns once per pattern (never throws).
 
 ## Protocol
 
@@ -136,21 +139,25 @@ 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.
-- each hook may set `"timeout"` (seconds, default 60); matching hooks run in **parallel**.
+- each hook may set `"timeout"` (seconds, default 60); matching hooks run in **parallel** (capped at 8 concurrent).
+- pressing Esc mid-turn kills running hook processes (SIGTERM → SIGKILL escalation, same as the timeout path); an already-aborted turn does not spawn hooks at all.
+- safety caps: hook stdout is capped at 10 MB (the hook is killed beyond that); injected `additionalContext` is capped at 50 KB / 2000 lines with a truncation notice.
+- each hook may set `"denyAsContext": true` — demote a deny (`permissionDecision: "deny"`, or exit 2 carrying a JSON deny payload) to `additionalContext`: the tool call proceeds and the nudge text is injected before the next LLM call (appended to the last user message) instead of blocking. Intended for nudge-style hooks like `serena-hooks remind`, where hard-blocking a read burst stops the agent dead. Injected text: the hook's `additionalContext` if present, otherwise the deny reason.
 
 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), so target them with regex like `plugin_serena_serena_.*`. Check your actual tool names with `/mcp` in pi to set the correct `matcher`.
+Pi names MCP tools `mcp__<server>__<tool>` (same scheme as Claude Code), so target them with regex like `mcp__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`:
+[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/hook.json` (global) or the project's `.pi/hook.json`:
 
 ```json
 {
@@ -164,10 +171,16 @@ Pi names MCP tools as `<serverName>_<toolName>` (not `mcp__server__tool` like Cl
     "PreToolUse": [
       {
         "matcher": "",
-        "hooks": [{ "type": "command", "command": "serena-hooks remind --client=claude-code" }]
+        "hooks": [
+          {
+            "type": "command",
+            "command": "serena-hooks remind --client=claude-code",
+            "denyAsContext": true
+          }
+        ]
       },
       {
-        "matcher": "serena_.*",
+        "matcher": "mcp__serena__.*",
         "hooks": [{ "type": "command", "command": "serena-hooks auto-approve --client=claude-code" }]
       }
     ],
@@ -186,16 +199,45 @@ 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. |
+| `PreToolUse` (`""`) | `remind` | Nudges the agent to prefer Serena's symbolic tools over raw `read`/`grep`. Runs before every tool call. Set `denyAsContext: true` so its deny becomes a context nudge instead of a hard block (recommended). |
+| `PreToolUse` (`mcp__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.
+**Get the matcher prefix right.** pi registers an MCP server's tools as `mcp__<server>__<tool>`. With Serena registered as the `serena` MCP server in `mcp.json` (the default), tools are named `mcp__serena__find_symbol`, `mcp__serena__find_referencing_symbols`, … → use `mcp__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.
 
+### Recommended: steer at the context level, not only via hooks
+
+`serena-hooks remind` is a **fallback**, not the main steering mechanism. Serena gates it behind a burst counter (8 consecutive `read`/`grep` calls in the currently installed release line, 3 in upstream master) plus a 120-second silence window after every nudge — so most `read` calls legitimately produce no output. The primary layer is Serena's **context system**: `serena start-mcp-server --context <name>` injects a behavior-constraining prompt and trims tools that duplicate the host agent's built-ins.
+
+This package ships [`pi.yml`](./pi.yml) — a pi-adapted context based on Serena's own `claude-code.yml`: symbol-first read/edit rules written against pi's tool names (`read`/`bash`/`edit`), and `excluded_tools` trimming the six Serena tools that duplicate pi built-ins (`read_file`, `execute_shell_command`, `find_file`, `list_dir`, `search_for_pattern`, `create_text_file`). Install and wire it up:
+
+```bash
+cp pi.yml ~/.serena/contexts/   # user contexts dir; a same-named context overrides the built-ins
+```
+
+```jsonc
+// ~/.pi/agent/mcp.json
+"serena": {
+  "type": "stdio",
+  "command": "serena",
+  "args": ["start-mcp-server", "--project-from-cwd", "--context", "pi"]
+}
+```
+
+Optionally control how the model reaches Serena's tools with `exposure` / `toolExposure` (see pi's MCP docs for 0.99+ semantics): `"exposure": "codemode"` has the model batch Serena calls inside codemode scripts, `"exposure": "deferred"` loads them one by one via `tool_search`, and `toolExposure` can single out tools (e.g. `"initial_instructions": "direct"`).
+
+What changes with `pi.yml` (`single_project: true` + `--project-from-cwd`):
+
+- the project auto-activates at startup; `activate_project` and `get_current_config` are dropped from the toolset (the SessionStart `activate` hook still helps — it nudges the agent to read the manual via `initial_instructions`);
+- the six duplicate tools disappear, removing the temptation to use them;
+- the symbol-first rules ride in the system prompt instead of arriving as after-the-fact nudges.
+
+Keep the hooks as a fallback: `remind` with `denyAsContext: true` (catches bursts the prompt didn't prevent), `activate`, and `cleanup` all stay useful; `auto-approve` remains inert under pi (see warning above).
+
 ## Config Override
 
 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

@@ -7,9 +7,9 @@
  * 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)
+ *   2. ~/.pi/agent/hook.json   (user-global, via getAgentDir())
+ *   3. <cwd>/.pi/hook.json     (project-local)
+ *   4. ~/.pi/hook.json         (legacy home location)
  *
  * and maps:
  *   SessionStart  → session_start        (source = mapped reason)
@@ -167,9 +167,9 @@ export function loadConfig(cwd: string): HooksConfig | null {
 	const candidates = envPath
 		? [envPath]
 		: [
-				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
+				join(getAgentDir(), "hook.json"), // ~/.pi/agent/hook.json — user-global, top priority
+			join(cwd, CONFIG_DIR_NAME, "hook.json"), // project-local
+			join(homedir(), CONFIG_DIR_NAME, "hook.json"), // legacy home
 			];
 
 	// First valid config that defines hooks wins. A candidate that parses but
@@ -284,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 =

package/package.json

@@ -1,54 +1,54 @@
 {
-  "name": "@fyeeme/pi-hooks",
-  "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",
-  "publishConfig": {
-    "access": "public"
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/fyeeme/pi-packages"
-  },
-  "bugs": {
-    "url": "https://github.com/fyeeme/pi-packages/issues"
-  },
-  "homepage": "https://github.com/fyeeme/pi-packages#readme",
-  "engines": {
-    "node": ">=18"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "hooks",
-    "claude-code",
-    "serena",
-    "automation",
-    "lifecycle"
-  ],
-  "files": [
-    "index.ts",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "scripts": {
-    "test": "vitest --run",
-    "typecheck": "tsc"
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.84.1"
-  },
-  "devDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.1",
-    "@types/node": "22.19.19",
-    "typescript": "5.9.3"
-  }
+	"name": "@fyeeme/pi-hooks",
+	"version": "1.0.6",
+	"description": "Claude Code-compatible hooks runner for pi. Reads hooks config (priority: ~/.pi/agent/hook.json, then project .pi/hook.json) and maps SessionStart, PreToolUse, and Stop events to pi lifecycle events.",
+	"type": "module",
+	"license": "MIT",
+	"author": "fyeeme",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/fyeeme/pi-packages"
+	},
+	"bugs": {
+		"url": "https://github.com/fyeeme/pi-packages/issues"
+	},
+	"homepage": "https://github.com/fyeeme/pi-packages#readme",
+	"engines": {
+		"node": ">=18"
+	},
+	"keywords": [
+		"pi-package",
+		"pi",
+		"hooks",
+		"claude-code",
+		"serena",
+		"automation",
+		"lifecycle"
+	],
+	"files": [
+		"index.ts",
+		"README.md",
+		"LICENSE",
+		"CHANGELOG.md"
+	],
+	"pi": {
+		"extensions": [
+			"./index.ts"
+		]
+	},
+	"scripts": {
+		"test": "vitest --run",
+		"typecheck": "tsc"
+	},
+	"peerDependencies": {
+		"@earendil-works/pi-coding-agent": ">=0.99.0"
+	},
+	"devDependencies": {
+		"@earendil-works/pi-coding-agent": "0.99.2",
+		"@types/node": "22.19.19",
+		"typescript": "5.9.3"
+	}
 }