@agimon-ai/doompi-hook 0.0.1-alpha.5 → 0.0.1-alpha.52

package/README.md

@@ -1,11 +1,21 @@
 # @agimon-ai/doompi-hook
 
-Claude-Code-compatible repository and plugin hooks for
+Claude Code-compatible repository and plugin hooks for
 [DoomPi](https://www.npmjs.com/package/@agimon-ai/doompi) sessions.
 
 A **hook** is a shell command the repository runs at a point in the session: before a tool call,
 after one, at session start, when the agent settles, and at session end. Commands are declared in
-`.doom/hooks.yaml`, grouped so a mode can turn a whole family of them on or off:
+`.doom/hooks.yaml`, grouped so a mode can turn a whole family of them on or off.
+
+> **Alpha:** hook configuration and runtime contracts may change between releases.
+
+## Requirements
+
+- Node.js 22.19.0 or newer
+- Pi 0.85.0
+- `/bin/bash`
+
+Configure hooks in `.doom/hooks.yaml`:
 
 ```yaml
 # .doom/hooks.yaml
@@ -25,14 +35,15 @@ groups:
           skipInSubagent: true
 ```
 
-A group marked `core: true` always loads. Every other group loads only when the active mode selected
-it. The same document is read from the global `.doom` directory and from the repository, and a
-repository group replaces the global group of the same id outright.
+A group marked `core: true` always loads. Every other group loads only when the active mode selects
+it. The same document is read from the global `.doom` directory and from the repository. A
+repository group replaces the global group of the same ID outright.
 
 ## Activation
 
-The DoomPi distribution activates this package by default. Layers only declare the `hookGroups`
-that should run in a major mode:
+The distribution activates this package by default through the `default.packages` list written by
+`doompi init` and `dpi init` in `.doom/modes.yaml`. Keep it there, or declare it in a selected layer,
+for hooks to run. Layers only declare the `hookGroups` to select; they do not define the hook commands:
 
 ```yaml
 # .doom/modes.yaml
@@ -41,14 +52,16 @@ layers:
     hookGroups: [safety, workflow]
 ```
 
-A session with no selected `hookGroups` still runs groups marked `core: true`; other groups remain inactive.
+A session with no selected `hookGroups` still runs groups marked `core: true`; other groups remain
+inactive.
 
 ## What a hook sees and can say
 
 Each command is run through `/bin/bash -c` in the repository root, with the Claude Code payload for
-the event on stdin and `CLAUDE_PROJECT_DIR`, `CODEX_REPO_ROOT`, `ORIGINAL_REPO_PATH` and — for a
-hook declared by a plugin or a global config — `CLAUDE_PLUGIN_ROOT` in the environment. Tool names
-in the payload and in `matcher` are Claude names (`Bash`, `Write`), not Pi's.
+the event on stdin. The environment includes `CLAUDE_PROJECT_DIR`, `CODEX_REPO_ROOT`, and
+`ORIGINAL_REPO_PATH`. Every resolved hook also receives `CLAUDE_PLUGIN_ROOT`, set to the root that
+declared its repository, personal, or plugin configuration. Tool names in the payload and in
+`matcher` are Claude names (`Bash`, `Write`), not Pi's.
 
 The last stdout line that starts with `{` is read as the hook's decision:
 
@@ -70,14 +83,44 @@ indistinguishable from one that passed.
 expires, is sent `SIGTERM` and then `SIGKILL` two seconds later, so a stalled hook does not leave
 the processes it started behind.
 
-## Installation
+## Help guidance
+
+While the Help minor mode is active, this package contributes `doompi-author-hook`. The prompt
+covers `.doom/hooks.yaml`, group activation, commands, payloads, decisions, and verification, and
+is withdrawn when the package or Help provider unloads.
 
-DoomPi already includes this package. For standalone Pi installation:
+## Install
+
+For standalone Pi installation:
 
 ```bash
 pi install npm:@agimon-ai/doompi-hook
 ```
 
+## Public API
+
+```ts
+import { createBashHookRunner, hookExtension } from '@agimon-ai/doompi-hook';
+import type { HookDecision, HookEventName } from '@agimon-ai/doompi-hook';
+```
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
+
 ## License
 
 MIT
+
+## Extension lifecycle and source layout
+
+`extensions/pi.ts` declares Config-dependent service bindings, typed controller events, and Help resources. The readiness gate in `services/hookRuntime/` keeps session-start hooks ahead of dependent events and rejects stale generations. Session-end hooks finish during `session_shutdown` before the shared helper disposes the service binding.
+
+`extensions/server.ts` declares the server hooks from `controllers/serverHooks.ts`. Controllers dispatch through `services/<name>/`; constants and shared types have their own roots. Flat `exports/` publishes reusable capabilities, and extension entry points are built directly.

package/llms.txt

@@ -2,6 +2,10 @@
 
 Claude-Code-compatible repository and plugin hooks for Doom Pi sessions.
 
-## Resources
+## How to author
 
-- [Package README](./README.md): the `.doom/hooks.yaml` document, group selection, the event mapping, and what a hook decision can do.
+- [Author DoomPi hooks](./src/prompts/doompi-author-hook/SKILL.md): Create `.doom/hooks.yaml` groups and Claude-compatible hook commands.
+
+## Package reference
+
+- [Package README](./README.md): The hook registry, group selection, event mapping, decisions, and failure handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agimon-ai/doompi-hook",
-  "version": "0.0.1-alpha.5",
+  "version": "0.0.1-alpha.52",
   "description": "Claude-Code-compatible repository and plugin hook runner for DoomPi sessions.",
   "keywords": [
     "ai",
@@ -16,18 +16,28 @@
     "repository-hooks"
   ],
   "homepage": "https://agimon.ai",
+  "bugs": {
+    "url": "https://github.com/AgiFlow/doompi/issues"
+  },
   "license": "MIT",
   "author": "Vuong Ngo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgiFlow/doompi.git",
+    "directory": "packages/default/doompi-hook"
+  },
   "files": [
     "dist",
     "llms.txt",
     "README.md",
+    "src/prompts",
     "LICENSE",
     "package.json"
   ],
   "type": "module",
   "main": "./dist/index.cjs",
-  "types": "./dist/index.d.mts",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
   "jsnext:main": "./dist/index.mjs",
   "exports": {
     ".": {
@@ -35,34 +45,45 @@
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
+    "./api-contracts": {
+      "types": "./dist/api-contracts.d.mts",
+      "import": "./dist/api-contracts.mjs",
+      "require": "./dist/api-contracts.cjs"
+    },
     "./extensions/pi": {
       "types": "./dist/extensions/pi.d.mts",
       "import": "./dist/extensions/pi.mjs",
       "require": "./dist/extensions/pi.cjs"
     },
+    "./extensions/server": {
+      "types": "./dist/extensions/server.d.mts",
+      "import": "./dist/extensions/server.mjs",
+      "require": "./dist/extensions/server.cjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "@deepseek-ai/cordis": "4.0.1",
-    "yaml": "2.9.0",
-    "@agimon-ai/doompi-config": "0.0.1-alpha.27",
-    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.27",
-    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.27"
+    "@agimon-ai/doompi-config": "0.0.1-alpha.74",
+    "@agimon-ai/doompi-core": "0.0.1-alpha.75",
+    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.72",
+    "@deepseek-ai/cordis": "4.0.2",
+    "yaml": "2.9.0"
   },
   "devDependencies": {
-    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.26",
-    "@earendil-works/pi-coding-agent": "0.84.2",
-    "@types/node": "26.1.1",
-    "@vitest/coverage-v8": "4.1.10",
-    "tsdown": "0.22.14",
-    "typescript": "6.0.3",
-    "vitest": "4.1.10"
+    "@agimon-ai/doompi-build": "0.0.1-alpha.4",
+    "@agimon-ai/vibe-lint-plugin-doom-extension": "0.0.1-alpha.70",
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "@types/node": "26.5.1",
+    "@vitest/coverage-v8": "5.0.0",
+    "tsdown": "0.23.0",
+    "typescript": "7.0.2",
+    "vitest": "5.0.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "0.84.2"
+    "@earendil-works/pi-coding-agent": "0.85.1"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {
@@ -72,6 +93,17 @@
   "engines": {
     "node": ">=22.19.0"
   },
+  "doompiServer": {
+    "entry": "./generated/server.ts",
+    "dist": "./dist/extensions/server.mjs",
+    "scopes": [
+      "session"
+    ],
+    "contracts": {
+      "entry": "./src/exports/apiContracts.ts",
+      "dist": "./dist/api-contracts.mjs"
+    }
+  },
   "pi": {
     "extensions": [
       "./dist/extensions/pi.mjs"

package/src/prompts/doompi-author-hook/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: doompi-author-hook
+description: Author DoomPi repository or plugin hooks. Use when creating or changing .doom/hooks.yaml, selecting hook groups from modes.yaml, writing hook commands, or adapting Claude Code hook payloads and decisions to DoomPi.
+---
+
+# Author DoomPi hooks
+
+Write the smallest hook that enforces the requested policy, and treat every hook command as executable repository code.
+
+## Repository registry
+
+Define repository and personal hooks in `.doom/hooks.yaml`:
+
+```yaml
+groups:
+  safety:
+    core: true
+    hooks:
+      - event: PreToolUse
+        pi:
+          matcher: Bash
+          command: .doom/hooks/guard-destructive-commands.sh
+          timeout: 10
+          skipInSubagent: true
+          order: 0
+```
+
+- Personal configuration comes from `~/.pi/.doom/hooks.yaml`; repository configuration comes from `<repo>/.doom/hooks.yaml`.
+- A repository group replaces a personal group with the same ID as one complete value.
+- `core: true` runs regardless of the selected groups. Otherwise, add the group ID to a layer's `hookGroups` in `modes.yaml`.
+- `matcher` is a regular expression over Claude tool names such as `Bash` and `Write`, even though Pi uses lowercase tool names internally.
+- Use `skipInSubagent: true` when running the hook in a child could duplicate or close parent-owned work. Lower `order` values run first, with declaration order as the tiebreaker.
+
+Supported repository events are `SessionStart`, `PreToolUse`, `PostToolUse`, and `Stop`. `SessionEnd` is resolved only from plugin `hooks.json` documents.
+
+## Command contract
+
+DoomPi runs each command through `/bin/bash -c` from the repository root and writes the Claude-compatible event payload to stdin. The environment includes `CLAUDE_PROJECT_DIR`, `CODEX_REPO_ROOT`, `ORIGINAL_REPO_PATH`, and `CLAUDE_PLUGIN_ROOT`. For `.doom/hooks.yaml`, `CLAUDE_PLUGIN_ROOT` is the root that declared the personal or repository document.
+
+The final stdout line beginning with `{` is parsed as the hook decision. Use Claude Code decision fields only when the event supports them. `PreToolUse` may deny a tool or add context, `PostToolUse` may append context or mark a result as denied, and `SessionStart` may add context. `Stop` and `SessionEnd` run for side effects.
+
+Hook failures are advisory: nonzero exits, invalid JSON, spawn failures, and timeouts are reported to the agent instead of crashing the turn. Set `timeout` in seconds only when the 10-second default is unsuitable. A timeout terminates the command's process group.
+
+## Verification
+
+Before enabling a new hook broadly:
+
+1. Run the command directly with a representative JSON payload on stdin.
+2. Start DoomPi with the intended major mode and confirm the group appears in `doompi --explain` output.
+3. Exercise the exact lifecycle event in a disposable session, including a child session when `skipInSubagent` matters.
+4. Confirm failure output reaches the agent and that repeated shutdown does not repeat external side effects unexpectedly.