@agimon-ai/doompi-hook 0.0.1-alpha.87 → 0.0.1-alpha.89

package/README.md

@@ -1,11 +1,7 @@
 # @agimon-ai/doompi-hook
 
-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.
+Repository, personal, and Claude Code-compatible plugin hooks for
+[DoomPi](https://www.npmjs.com/package/@agimon-ai/doompi) sessions. Registry rows can run shell commands or compiled TypeScript/JavaScript modules.
 
 > **Alpha:** hook configuration and runtime contracts may change between releases.
 
@@ -13,9 +9,9 @@ after one, at session start, when the agent settles, and at session end. Command
 
 - Node.js 22.19.0 or newer
 - Pi 1.0.0
-- `/bin/bash`
+- `/bin/bash` for command hooks
 
-Configure hooks in `.doom/hooks.yaml`:
+## Registry and activation
 
 ```yaml
 # .doom/hooks.yaml
@@ -26,7 +22,9 @@ groups:
       - event: PreToolUse
         pi:
           matcher: Bash
-          command: .doom/hooks/guard-destructive-commands.sh
+          module: .doom/hooks/guard.ts
+          timeout: 10
+          order: 0
   workflow:
     hooks:
       - event: Stop
@@ -35,15 +33,9 @@ groups:
           skipInSubagent: true
 ```
 
-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
+Each `pi` binding declares exactly one of `command` or `module`. Module paths resolve relative to the declaring repository root or personal `~/.pi/.doom` root, not the directory containing `hooks.yaml`. Personal configuration is `~/.pi/.doom/hooks.yaml`; repository configuration is `<repo>/.doom/hooks.yaml`. A repository group replaces the personal group of the same ID completely.
 
-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:
+The distribution activates this package by default through the `default.packages` list written by `doompi init` or `dpi init`. Keep it there, or declare it in a selected layer. Layers only declare the `hookGroups` to select; they do not define hook implementations:
 
 ```yaml
 # .doom/modes.yaml
@@ -52,53 +44,123 @@ layers:
     hookGroups: [safety, workflow]
 ```
 
-A session with no selected `hookGroups` still runs groups marked `core: true`; other groups remain
-inactive.
+`core: true` always loads. Unset `hookGroups` means all groups; explicit `hookGroups: []` means core groups only. An explicit nonempty list selects those groups plus core. Lower `order` values run first, with declaration order breaking ties. Registry commands and modules interleave in that order, followed by plugin commands. An explicit denial ends the chain.
+
+`matcher` is a regular expression over Claude tool names such as `Bash` and `Write`. Modules receive native Pi events and tool names such as `bash`, not translated command payloads. `skipInSubagent: true` excludes a registry row from child tool dispatch. Use it for parent-owned work; it does not enable child lifecycle dispatch.
+
+## Compiled module authoring
+
+Use the dependency-free public authoring subpath, not the extension/runtime entry:
+
+```ts
+import { defineDoomHook } from '@agimon-ai/doompi-hook/authoring';
+
+export default defineDoomHook({
+  setup(ctx) {
+    let calls = 0;
+    return {
+      tool_call(event, ctx) {
+        calls += 1;
+        if (event.toolName === 'bash' && String(event.input.command).includes('rm -rf')) {
+          return { block: true, reason: 'Use a non-destructive command.' };
+        }
+      },
+      async dispose() {
+        // Release resources owned by this session's setup.
+      },
+    };
+  },
+});
+```
+
+`defineDoomHook` checks the contract while preserving inference. The default export must have `setup(ctx)`, returning handlers synchronously or asynchronously. Only handlers selected by registry rows run:
+
+| Registry event | Native module handler       | Result                                           |
+| -------------- | --------------------------- | ------------------------------------------------ |
+| `SessionStart` | `session_start(event, ctx)` | `void`                                           |
+| `PreToolUse`   | `tool_call(event, ctx)`     | `void` or `{ block?: boolean, reason?: string }` |
+| `PostToolUse`  | `tool_result(event, ctx)`   | `void` or `{ content?, details?, isError? }`     |
+| `Stop`         | `agent_settled(event, ctx)` | `void`, cannot send messages                     |
+
+Optional `dispose()` returns void or a promise. There is no module `SessionEnd` handler. Tool-call handlers may mutate `event.input`, which must remain a JSON object. Accepted mutations flow to later rows and the tool. Tool-result patches accept text/image content, JSON-compatible details, and a boolean error flag. Failed, invalid, or late invocations cannot publish input mutations or result patches. Lifecycle handlers cannot return decisions.
+
+### Full HookContext contract
+
+The authoring subpath exports `HookContext`, `HookHandlers`, `HookModule`, `HookModuleDescriptor`, `AgentSettledEvent`, `Awaitable`, and `JsonValue` types.
+
+```ts
+interface HookContext {
+  readonly sessionId: string;
+  readonly parentSessionId?: string;
+  readonly agent?: string;
+  readonly isSubagent: boolean;
+  readonly cwd: string;
+  readonly repoRoot: string;
+  readonly model?: { readonly provider: string; readonly id: string };
+  readonly signal: AbortSignal;
+  sendMessage(text: string, delivery: 'steer' | 'followUp'): Promise<void>;
+  appendCustomEntry(type: string, data: JsonValue): Promise<void>;
+}
+```
+
+`cwd` is the session working directory; `repoRoot` is its resolved repository root. Optional identity/model fields may be absent, including model in native children. Await context effects. Message delivery uses host prompt admission; admission failures propagate, they are not converted to advisory hook failures. `appendCustomEntry` records JSON-compatible data in session history.
 
-## What a hook sees and can say
+Setup and row calls for the same module and session are serialized. A module referenced by multiple rows shares one setup instance in that session. Keep mutable state inside `setup`, not at module scope: imported modules may be shared across sessions, while setup closures are session-local. In-memory state is not durable across reloads. Explicitly record history entries when durability is needed.
 
-Each command is run through `/bin/bash -c` in the repository root, with the Claude Code payload for
-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.
+Setup receives a lifetime context; handlers receive an invocation context whose signal also reflects cancellation. Invocation effects are revoked after completion. Setup failure, setup/handler timeout, or cancellation quarantines the instance and revokes its context effects. Cooperate with `signal`; revocation cannot stop arbitrary JavaScript or undo already completed external effects.
 
-The last stdout line that starts with `{` is read as the hook's decision:
+## Command payloads and decisions
 
-| Event mapping                   | A decision can                                                     |
-| ------------------------------- | ------------------------------------------------------------------ |
-| `SessionStart` → session start  | add `additionalContext` to the conversation                        |
-| `PreToolUse` → tool call        | block the call with a reason, or steer it with `additionalContext` |
-| `PostToolUse` → tool result     | append text to the result and mark it an error                     |
-| `Stop` → agent settled          | nothing; the hook runs for its side effects                        |
-| `SessionEnd` → session shutdown | nothing; plugin hooks only                                         |
+Commands run through `/bin/bash -c` in the repository root with a Claude-compatible JSON payload on stdin. The environment includes `CLAUDE_PROJECT_DIR`, `CODEX_REPO_ROOT`, `ORIGINAL_REPO_PATH`, and `CLAUDE_PLUGIN_ROOT`. The last field names the root declaring the repository, personal, or plugin configuration. Native child tool payloads use the child's own `session_id` and include `parent_session_id` and `agent_type`.
 
-A hook that exits non-zero, times out, cannot be spawned, or prints unparseable JSON does not fail
-the turn. It is reported to the agent instead, because a guardrail that never ran is otherwise
-indistinguishable from one that passed.
+The last stdout line beginning with `{` is parsed as the decision. Denial is `decision: "block"` or `hookSpecificOutput.permissionDecision: "deny"`; the reason is top-level `reason` or `hookSpecificOutput.reason`. Context is `hookSpecificOutput.additionalContext`.
 
-## Timeouts
+| Event          | Command decision behavior                                                                                                                                                            |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `SessionStart` | Adds additional context to the conversation                                                                                                                                          |
+| `PreToolUse`   | Denial blocks the call. Additional context also blocks the current call with that text as its reason, allowing the agent to reconsider; it does not silently steer an executing tool |
+| `PostToolUse`  | Appends additional context or reason to the result; denial marks it as an error                                                                                                      |
+| `Stop`         | Denial with a reason requests a follow-up turn, capped at five consecutive refusals                                                                                                  |
+| `SessionEnd`   | Plugin commands only, run for side effects                                                                                                                                           |
 
-`timeout` is in seconds and defaults to 10. A hook is spawned in its own process group and, when it
-expires, is sent `SIGTERM` and then `SIGKILL` two seconds later, so a stalled hook does not leave
-the processes it started behind.
+Stop payloads include `stop_hook_active` when a prior refusal is active. After five consecutive refusals, a further refusal is reported without another follow-up turn. A stop without a refusal reason resets the count. This continuation contract belongs to commands, not module `agent_settled` handlers.
 
-## Help guidance
+## Event ownership and children
 
-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.
+Terminal parents use Pi tool and lifecycle handlers. In headless parents, the Pi bridge owns lifecycle rows: `SessionStart`, `Stop`, and plugin-only `SessionEnd`. Server facets alone own headless tool dispatch. The bridge and server tool path share session-local module setup, so lifecycle and tool rows do not create separate instances. Session-start readiness precedes dependent turns/tools. Session-end runs once during shutdown before service disposal.
 
-## Install
+Native children, through either the headless or terminal adapter, run only `PreToolUse` and `PostToolUse`. Registry and plugin tool hooks run, excluding registry rows marked `skipInSubagent`. Children do not run `SessionStart`, `Stop`, or `SessionEnd`. Each child has its own module setup/state and pins its launch selection and module generation, even after the parent reloads or disposes.
 
-For standalone Pi installation:
+## Sync, reload, and failure handling
+
+After changing a module or its imports, registry, or mode selection:
+
+1. Run `doompi sync` (or `dpi sync`). Sync compiles core modules plus the union of mode-selected groups; if any mode leaves selection unset, it compiles all groups.
+2. Run `doompi sync --check` to check drift.
+3. Use `/reload` or restart the terminal session to adopt the published generation. Reopen headless sessions, then exercise the intended events.
+
+Module imports use compiled artifacts from a synchronized descriptor, never a live source fallback. The runtime pins the descriptor at binding creation, including cold lazy imports after configuration replacement. A compilation failure preserves the previous published generation. Sync alone does not replace modules in a running session.
+
+`timeout` is a positive finite number of seconds, defaulting to 10. For modules, the invocation budget includes first import/setup and the handler. Module execution/setup errors, invalid results, and timeouts are advisory, reported as missed checks rather than automatically denying tools. Host readiness, cancellation, and context effect/admission failures are not advisory execution failures. A quarantined module does not resume checking later rows in that session.
+
+Command nonzero exits, spawn failures, invalid JSON, and timeouts are likewise advisory. Timed-out command process groups receive `SIGTERM`, then `SIGKILL` two seconds later.
+
+## Trust and isolation limits
+
+Hooks are executable trusted code. Compilation and generation pinning provide artifact consistency, not a sandbox or authorization boundary. Modules execute in the host Node.js process with its filesystem, network, and process privileges; commands inherit host privileges too. A synchronous infinite loop, `process.exit`, or out-of-memory failure cannot be contained in-process. Prefer `command:` when process isolation and hard termination matter. Session-local setup and serialized calls do not isolate module globals or external side effects. Context revocation only gates the exposed context effects. Do not load untrusted hooks or treat advisory checks as guaranteed enforcement.
+
+## Verification scope
+
+Functional proof covers real Pi bridge exactly-once dispatch, shared lifecycle/tool setup, prompt-admission marker propagation, in-flight cancellation, native command rows, cold descriptor pinning, and both native child adapters retaining modules after parent disposal. Direct/MCP command-row proof uses explicitly mocked tool bodies. This does not establish full intercom plugin integration.
+
+## Help, install, and public API
+
+Help minor mode contributes `doompi-author-hook` while this package and its Help provider are active.
 
 ```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';
@@ -113,14 +175,10 @@ pnpm test
 pnpm lint
 ```
 
+Routed roots and named handlers live under `src/extensions/workspaces/sessions/(backend)/`. `services/hookRuntime/` owns readiness and session lifetimes. The package build generates Pi/server entries; `src/exports/` publishes reusable capabilities.
+
 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/dist/authoring.cjs

@@ -0,0 +1,10 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/services/hookAuthoring/index.ts
+/** Preserve the author's inferred module type while checking the hook contract. */
+function defineDoomHook(module) {
+	return module;
+}
+//#endregion
+exports.defineDoomHook = defineDoomHook;
+
+//# sourceMappingURL=authoring.cjs.map

package/dist/authoring.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.cjs","names":[],"sources":["../src/services/hookAuthoring/index.ts"],"sourcesContent":["import type { HookModule } from '../../types/hookModule';\n\n/** Preserve the author's inferred module type while checking the hook contract. */\nexport function defineDoomHook<T extends HookModule>(module: T): T {\n  return module;\n}\n"],"mappings":";;;AAGA,SAAgB,eAAqC,QAAc;CACjE,OAAO;AACT"}

package/dist/authoring.d.mts

@@ -0,0 +1,7 @@
+import { a as HookModule, i as HookHandlers, l as JsonValue, n as Awaitable, o as HookModuleDescriptor, r as HookContext, t as AgentSettledEvent } from "./hookModule-c2GtLnm1.mjs";
+//#region src/services/hookAuthoring/index.d.ts
+/** Preserve the author's inferred module type while checking the hook contract. */
+export declare function defineDoomHook<T extends HookModule>(module: T): T;
+//#endregion
+export type { AgentSettledEvent, Awaitable, HookContext, HookHandlers, HookModule, HookModuleDescriptor, JsonValue };
+//# sourceMappingURL=authoring.d.mts.map

package/dist/authoring.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.mts","names":[],"sources":["../src/services/hookAuthoring/index.ts"],"mappings":";;;wBAGgB,eAAe,UAAU,YAAY,QAAQ,IAAI"}

package/dist/authoring.mjs

@@ -0,0 +1,9 @@
+//#region src/services/hookAuthoring/index.ts
+/** Preserve the author's inferred module type while checking the hook contract. */
+function defineDoomHook(module) {
+	return module;
+}
+//#endregion
+export { defineDoomHook };
+
+//# sourceMappingURL=authoring.mjs.map

package/dist/authoring.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.mjs","names":[],"sources":["../src/services/hookAuthoring/index.ts"],"sourcesContent":["import type { HookModule } from '../../types/hookModule';\n\n/** Preserve the author's inferred module type while checking the hook contract. */\nexport function defineDoomHook<T extends HookModule>(module: T): T {\n  return module;\n}\n"],"mappings":";;AAGA,SAAgB,eAAqC,QAAc;CACjE,OAAO;AACT"}