@agimon-ai/doompi-hook 0.0.1-alpha.2

package/dist/types/hooks.d.mts

@@ -0,0 +1,145 @@
+//#region src/types/hooks.d.ts
+/**
+ * The hook document contract and the ports that run it.
+ *
+ * Every name here is written in Claude Code's vocabulary, because that is what
+ * `.doom/hooks.yaml` and plugin `hooks.json` files are authored against. The
+ * translation onto Pi's lifecycle happens at the adapter boundary.
+ */
+/** Registry event names. Each is used twice per dispatch, so drift would be silent. */
+declare const HOOK_EVENT: {
+  readonly sessionStart: "SessionStart";
+  readonly preToolUse: "PreToolUse";
+  readonly postToolUse: "PostToolUse";
+  readonly stop: "Stop";
+  readonly sessionEnd: "SessionEnd";
+};
+type HookEventName = (typeof HOOK_EVENT)[keyof typeof HOOK_EVENT];
+interface HookCommand {
+  command: string;
+  /** Seconds before the hook is terminated. Defaults to DEFAULT_HOOK_TIMEOUT_SECONDS. */
+  timeout?: number;
+}
+/** What one registry row declares for the `pi` frontend. */
+interface RegistryBinding {
+  matcher?: string;
+  command: string;
+  timeout?: number;
+  skipInSubagent?: boolean;
+  order?: number;
+}
+/** A registry row plus the group membership used to include or drop it. */
+interface RegistryEntry extends RegistryBinding {
+  event: string;
+  order: number;
+  /** Declaration order across every source, used as the sort tiebreaker. */
+  position: number;
+  groupId: string;
+  core: boolean;
+  /** Root of the config that declared the group, exported as CLAUDE_PLUGIN_ROOT. */
+  baseDirectory: string;
+}
+interface RegistryGroup {
+  core?: boolean;
+  hooks?: Array<{
+    event: string;
+    pi?: RegistryBinding;
+  }>;
+}
+interface RegistryDocument {
+  groups?: Record<string, RegistryGroup>;
+}
+/** One `.doom/hooks.yaml` as read from disk, before it is parsed. */
+interface HookDocumentSource {
+  baseDirectory: string;
+  text: string;
+}
+/** One `.doom/hooks.yaml` after parsing, tagged with the root that declared it. */
+interface ParsedRegistrySource {
+  baseDirectory: string;
+  document: RegistryDocument;
+}
+interface PluginHookGroup {
+  matcher?: string;
+  hooks?: HookCommand[];
+}
+interface PluginHookConfig {
+  hooks?: Record<string, PluginHookGroup[]>;
+}
+/** A parsed plugin config plus the root exported to its commands. */
+interface PluginHookDocument {
+  pluginRoot: string;
+  config: PluginHookConfig;
+}
+/** A hook command paired with the config root it runs against. */
+interface ResolvedHook {
+  hook: HookCommand;
+  root: string;
+}
+/** The JSON a hook may write on stdout to steer or block the call it observed. */
+interface HookDecision {
+  decision?: string;
+  reason?: string;
+  hookSpecificOutput?: {
+    permissionDecision?: string;
+    reason?: string;
+    additionalContext?: string;
+  };
+}
+type HookFailureReason = 'spawn_failed' | 'non_zero_exit' | 'timeout' | 'invalid_json' | 'registry_read' | 'plugin_config';
+interface HookFailure {
+  command: string;
+  message: string;
+  reason: HookFailureReason;
+}
+interface HookOutcome {
+  decision?: HookDecision;
+  failure?: HookFailure;
+}
+/**
+ * The tool fields a payload is built from, named without importing Pi.
+ *
+ * Pi's ToolCallEvent and ToolResultEvent both satisfy this structurally, so the
+ * adapter forwards them unchanged and the payload builder stays host-neutral.
+ */
+interface HookToolEvent {
+  readonly type: string;
+  readonly toolName: string;
+  readonly input: unknown;
+  readonly content?: readonly unknown[];
+  readonly isError?: boolean;
+}
+/** The JSON document handed to a hook on stdin. */
+type HookPayload = Record<string, unknown>;
+interface HookRunOptions {
+  repoRoot: string;
+  /** Exported as CLAUDE_PLUGIN_ROOT so a hook can reach its own scripts. */
+  pluginRoot?: string;
+}
+/** Runs one hook command and reports what it decided or how it failed. */
+interface HookRunner {
+  run(hook: HookCommand, payload: HookPayload, options: HookRunOptions): Promise<HookOutcome>;
+}
+/** Registry rows for this repository, or the failure that emptied them. */
+interface RegistryRead {
+  entries: RegistryEntry[];
+  failure?: HookFailure;
+}
+/** Plugin configs that could be read, and one failure per config that could not. */
+interface PluginDocumentRead {
+  documents: PluginHookDocument[];
+  failures: HookFailure[];
+}
+/** Where a plugin declares its hooks. Mirrors the harness state entry. */
+interface PluginHookSourceRef {
+  readonly pluginRoot: string;
+  readonly configPath: string;
+}
+/** Reads the hook documents a session runs from. */
+interface HookDocumentReader {
+  registry(repoRoot: string): Promise<RegistryRead>;
+  plugins(sources: readonly PluginHookSourceRef[]): Promise<PluginDocumentRead>;
+}
+//#endregion
+export { HOOK_EVENT, HookCommand, HookDecision, HookDocumentReader, HookDocumentSource, HookEventName, HookFailure, HookFailureReason, HookOutcome, HookPayload, HookRunOptions, HookRunner, HookToolEvent, ParsedRegistrySource, PluginDocumentRead, PluginHookConfig, PluginHookDocument, PluginHookGroup, PluginHookSourceRef, RegistryBinding, RegistryDocument, RegistryEntry, RegistryGroup, RegistryRead, ResolvedHook };
+//# sourceMappingURL=hooks.d.mts.map

package/dist/types/hooks.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.mts","names":[],"sources":["../../src/types/hooks.ts"],"mappings":";;;;;;;;;cASa;;;;;;;KAQD,wBAAwB,yBAAyB;UAE5C;EACf;;EAEA;;;UAIe;EACf;EACA;EACA;EACA;EACA;;;UAIe,sBAAsB;EACrC;EACA;;EAEA;EACA;EACA;;EAEA;;UAGe;EACf;EACA,QAAQ;IAAQ;IAAe,KAAK;;;UAGrB;EACf,SAAS,eAAe;;;UAIT;EACf;EACA;;;UAIe;EACf;EACA,UAAU;;UAGK;EACf;EACA,QAAQ;;UAGO;EACf,QAAQ,eAAe;;;UAIR;EACf;EACA,QAAQ;;;UAIO;EACf,MAAM;EACN;;;UAIe;EACf;EACA;EACA;IACE;IACA;IACA;;;KAIQ;UAQK;EACf;EACA;EACA,QAAQ;;UAGO;EACf,WAAW;EACX,UAAU;;;;;;;;UASK;WACN;WACA;WACA;WACA;WACA;;;KAIC,cAAc;UAET;EACf;;EAEA;;;UAIe;EACf,IAAI,MAAM,aAAa,SAAS,aAAa,SAAS,iBAAiB,QAAQ;;;UAIhE;EACf,SAAS;EACT,UAAU;;;UAIK;EACf,WAAW;EACX,UAAU;;;UAIK;WACN;WACA;;;UAIM;EACf,SAAS,mBAAmB,QAAQ;EACpC,QAAQ,kBAAkB,wBAAwB,QAAQ"}

package/dist/types/hooks.mjs

@@ -0,0 +1,2 @@
+const e={sessionStart:`SessionStart`,preToolUse:`PreToolUse`,postToolUse:`PostToolUse`,stop:`Stop`,sessionEnd:`SessionEnd`};export{e as HOOK_EVENT};
+//# sourceMappingURL=hooks.mjs.map

package/dist/types/hooks.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.mjs","names":[],"sources":["../../src/types/hooks.ts"],"sourcesContent":["/**\n * The hook document contract and the ports that run it.\n *\n * Every name here is written in Claude Code's vocabulary, because that is what\n * `.doom/hooks.yaml` and plugin `hooks.json` files are authored against. The\n * translation onto Pi's lifecycle happens at the adapter boundary.\n */\n\n/** Registry event names. Each is used twice per dispatch, so drift would be silent. */\nexport const HOOK_EVENT = {\n  sessionStart: 'SessionStart',\n  preToolUse: 'PreToolUse',\n  postToolUse: 'PostToolUse',\n  stop: 'Stop',\n  sessionEnd: 'SessionEnd',\n} as const;\n\nexport type HookEventName = (typeof HOOK_EVENT)[keyof typeof HOOK_EVENT];\n\nexport interface HookCommand {\n  command: string;\n  /** Seconds before the hook is terminated. Defaults to DEFAULT_HOOK_TIMEOUT_SECONDS. */\n  timeout?: number;\n}\n\n/** What one registry row declares for the `pi` frontend. */\nexport interface RegistryBinding {\n  matcher?: string;\n  command: string;\n  timeout?: number;\n  skipInSubagent?: boolean;\n  order?: number;\n}\n\n/** A registry row plus the group membership used to include or drop it. */\nexport interface RegistryEntry extends RegistryBinding {\n  event: string;\n  order: number;\n  /** Declaration order across every source, used as the sort tiebreaker. */\n  position: number;\n  groupId: string;\n  core: boolean;\n  /** Root of the config that declared the group, exported as CLAUDE_PLUGIN_ROOT. */\n  baseDirectory: string;\n}\n\nexport interface RegistryGroup {\n  core?: boolean;\n  hooks?: Array<{ event: string; pi?: RegistryBinding }>;\n}\n\nexport interface RegistryDocument {\n  groups?: Record<string, RegistryGroup>;\n}\n\n/** One `.doom/hooks.yaml` as read from disk, before it is parsed. */\nexport interface HookDocumentSource {\n  baseDirectory: string;\n  text: string;\n}\n\n/** One `.doom/hooks.yaml` after parsing, tagged with the root that declared it. */\nexport interface ParsedRegistrySource {\n  baseDirectory: string;\n  document: RegistryDocument;\n}\n\nexport interface PluginHookGroup {\n  matcher?: string;\n  hooks?: HookCommand[];\n}\n\nexport interface PluginHookConfig {\n  hooks?: Record<string, PluginHookGroup[]>;\n}\n\n/** A parsed plugin config plus the root exported to its commands. */\nexport interface PluginHookDocument {\n  pluginRoot: string;\n  config: PluginHookConfig;\n}\n\n/** A hook command paired with the config root it runs against. */\nexport interface ResolvedHook {\n  hook: HookCommand;\n  root: string;\n}\n\n/** The JSON a hook may write on stdout to steer or block the call it observed. */\nexport interface HookDecision {\n  decision?: string;\n  reason?: string;\n  hookSpecificOutput?: {\n    permissionDecision?: string;\n    reason?: string;\n    additionalContext?: string;\n  };\n}\n\nexport type HookFailureReason =\n  | 'spawn_failed'\n  | 'non_zero_exit'\n  | 'timeout'\n  | 'invalid_json'\n  | 'registry_read'\n  | 'plugin_config';\n\nexport interface HookFailure {\n  command: string;\n  message: string;\n  reason: HookFailureReason;\n}\n\nexport interface HookOutcome {\n  decision?: HookDecision;\n  failure?: HookFailure;\n}\n\n/**\n * The tool fields a payload is built from, named without importing Pi.\n *\n * Pi's ToolCallEvent and ToolResultEvent both satisfy this structurally, so the\n * adapter forwards them unchanged and the payload builder stays host-neutral.\n */\nexport interface HookToolEvent {\n  readonly type: string;\n  readonly toolName: string;\n  readonly input: unknown;\n  readonly content?: readonly unknown[];\n  readonly isError?: boolean;\n}\n\n/** The JSON document handed to a hook on stdin. */\nexport type HookPayload = Record<string, unknown>;\n\nexport interface HookRunOptions {\n  repoRoot: string;\n  /** Exported as CLAUDE_PLUGIN_ROOT so a hook can reach its own scripts. */\n  pluginRoot?: string;\n}\n\n/** Runs one hook command and reports what it decided or how it failed. */\nexport interface HookRunner {\n  run(hook: HookCommand, payload: HookPayload, options: HookRunOptions): Promise<HookOutcome>;\n}\n\n/** Registry rows for this repository, or the failure that emptied them. */\nexport interface RegistryRead {\n  entries: RegistryEntry[];\n  failure?: HookFailure;\n}\n\n/** Plugin configs that could be read, and one failure per config that could not. */\nexport interface PluginDocumentRead {\n  documents: PluginHookDocument[];\n  failures: HookFailure[];\n}\n\n/** Where a plugin declares its hooks. Mirrors the harness state entry. */\nexport interface PluginHookSourceRef {\n  readonly pluginRoot: string;\n  readonly configPath: string;\n}\n\n/** Reads the hook documents a session runs from. */\nexport interface HookDocumentReader {\n  registry(repoRoot: string): Promise<RegistryRead>;\n  plugins(sources: readonly PluginHookSourceRef[]): Promise<PluginDocumentRead>;\n}\n"],"mappings":"AASA,MAAa,EAAa,CACxB,aAAc,eACd,WAAY,aACZ,YAAa,cACb,KAAM,OACN,WAAY,YACd"}

package/dist/types/telemetry.cjs

@@ -0,0 +1,2 @@
+const e={hookFailed:`doom_pi_hook.failed`,hookRegistryReadFailed:`doom_pi_hook.registry_read_failed`};exports.HOOK_TELEMETRY_EVENT=e;
+//# sourceMappingURL=telemetry.cjs.map

package/dist/types/telemetry.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.cjs","names":[],"sources":["../../src/types/telemetry.ts"],"sourcesContent":["/** Telemetry events this package reports, and the port that records them. */\nexport const HOOK_TELEMETRY_EVENT = {\n  hookFailed: 'doom_pi_hook.failed',\n  hookRegistryReadFailed: 'doom_pi_hook.registry_read_failed',\n} as const;\n\nexport type HookTelemetryEventName = (typeof HOOK_TELEMETRY_EVENT)[keyof typeof HOOK_TELEMETRY_EVENT];\nexport type HookTelemetryAttributes = Record<string, string | number | boolean>;\n\n/**\n * A hook that never ran is indistinguishable from one that passed, which is why\n * both a failed run and an unreadable registry are worth reporting rather than\n * swallowing.\n */\nexport interface HookTelemetry {\n  recordError(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;\n  recordWarning(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;\n}\n"],"mappings":"AACA,MAAa,EAAuB,CAClC,WAAY,sBACZ,uBAAwB,mCAC1B"}

package/dist/types/telemetry.d.cts

@@ -0,0 +1,20 @@
+//#region src/types/telemetry.d.ts
+/** Telemetry events this package reports, and the port that records them. */
+declare const HOOK_TELEMETRY_EVENT: {
+  readonly hookFailed: "doom_pi_hook.failed";
+  readonly hookRegistryReadFailed: "doom_pi_hook.registry_read_failed";
+};
+type HookTelemetryEventName = (typeof HOOK_TELEMETRY_EVENT)[keyof typeof HOOK_TELEMETRY_EVENT];
+type HookTelemetryAttributes = Record<string, string | number | boolean>;
+/**
+ * A hook that never ran is indistinguishable from one that passed, which is why
+ * both a failed run and an unreadable registry are worth reporting rather than
+ * swallowing.
+ */
+interface HookTelemetry {
+  recordError(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;
+  recordWarning(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;
+}
+//#endregion
+export { HOOK_TELEMETRY_EVENT, HookTelemetry, HookTelemetryAttributes, HookTelemetryEventName };
+//# sourceMappingURL=telemetry.d.cts.map

package/dist/types/telemetry.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.cts","names":[],"sources":["../../src/types/telemetry.ts"],"mappings":";;cACa;WAAA;WAAA;;KAKD,iCAAiC,mCAAmC;KACpE,0BAA0B;;;;;;UAOrB;EACf,YAAY,OAAO,wBAAwB,gBAAgB,aAAa,0BAA0B;EAClG,cAAc,OAAO,wBAAwB,gBAAgB,aAAa,0BAA0B"}

package/dist/types/telemetry.d.mts

@@ -0,0 +1,20 @@
+//#region src/types/telemetry.d.ts
+/** Telemetry events this package reports, and the port that records them. */
+declare const HOOK_TELEMETRY_EVENT: {
+  readonly hookFailed: "doom_pi_hook.failed";
+  readonly hookRegistryReadFailed: "doom_pi_hook.registry_read_failed";
+};
+type HookTelemetryEventName = (typeof HOOK_TELEMETRY_EVENT)[keyof typeof HOOK_TELEMETRY_EVENT];
+type HookTelemetryAttributes = Record<string, string | number | boolean>;
+/**
+ * A hook that never ran is indistinguishable from one that passed, which is why
+ * both a failed run and an unreadable registry are worth reporting rather than
+ * swallowing.
+ */
+interface HookTelemetry {
+  recordError(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;
+  recordWarning(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;
+}
+//#endregion
+export { HOOK_TELEMETRY_EVENT, HookTelemetry, HookTelemetryAttributes, HookTelemetryEventName };
+//# sourceMappingURL=telemetry.d.mts.map

package/dist/types/telemetry.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.d.mts","names":[],"sources":["../../src/types/telemetry.ts"],"mappings":";;cACa;WAAA;WAAA;;KAKD,iCAAiC,mCAAmC;KACpE,0BAA0B;;;;;;UAOrB;EACf,YAAY,OAAO,wBAAwB,gBAAgB,aAAa,0BAA0B;EAClG,cAAc,OAAO,wBAAwB,gBAAgB,aAAa,0BAA0B"}

package/dist/types/telemetry.mjs

@@ -0,0 +1,2 @@
+const e={hookFailed:`doom_pi_hook.failed`,hookRegistryReadFailed:`doom_pi_hook.registry_read_failed`};export{e as HOOK_TELEMETRY_EVENT};
+//# sourceMappingURL=telemetry.mjs.map

package/dist/types/telemetry.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.mjs","names":[],"sources":["../../src/types/telemetry.ts"],"sourcesContent":["/** Telemetry events this package reports, and the port that records them. */\nexport const HOOK_TELEMETRY_EVENT = {\n  hookFailed: 'doom_pi_hook.failed',\n  hookRegistryReadFailed: 'doom_pi_hook.registry_read_failed',\n} as const;\n\nexport type HookTelemetryEventName = (typeof HOOK_TELEMETRY_EVENT)[keyof typeof HOOK_TELEMETRY_EVENT];\nexport type HookTelemetryAttributes = Record<string, string | number | boolean>;\n\n/**\n * A hook that never ran is indistinguishable from one that passed, which is why\n * both a failed run and an unreadable registry are worth reporting rather than\n * swallowing.\n */\nexport interface HookTelemetry {\n  recordError(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;\n  recordWarning(event: HookTelemetryEventName, error: unknown, attributes?: HookTelemetryAttributes): Promise<void>;\n}\n"],"mappings":"AACA,MAAa,EAAuB,CAClC,WAAY,sBACZ,uBAAwB,mCAC1B"}

package/llms.txt

@@ -0,0 +1,7 @@
+# Doom Pi Hook
+
+Claude-Code-compatible repository and plugin hooks for Doom Pi sessions.
+
+## Resources
+
+- [Package README](./README.md): the `.doom/hooks.yaml` document, group selection, the event mapping, and what a hook decision can do.

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@agimon-ai/doompi-hook",
+  "version": "0.0.1-alpha.2",
+  "description": "Claude-Code-compatible repository and plugin hook runner for DoomPi sessions.",
+  "keywords": [
+    "ai",
+    "claude-code-hooks",
+    "coding-agent",
+    "developer-tools",
+    "doompi",
+    "guardrails",
+    "hooks",
+    "pi-coding-agent",
+    "pi-extension",
+    "pi-package",
+    "repository-hooks"
+  ],
+  "homepage": "https://agimon.ai",
+  "license": "MIT",
+  "author": "Vuong Ngo",
+  "files": [
+    "dist",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.mts",
+  "jsnext:main": "./dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./extensions/pi": {
+      "types": "./dist/extensions/pi.d.mts",
+      "import": "./dist/extensions/pi.mjs",
+      "require": "./dist/extensions/pi.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.24",
+    "@agimon-ai/doompi-telemetry": "0.0.1-alpha.24",
+    "@agimon-ai/doompi-extension-contracts": "0.0.1-alpha.24"
+  },
+  "devDependencies": {
+    "@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/vibe-lint-plugin-doom-extension": "0.0.1-alpha.24"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.84.2"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "pi": {
+    "extensions": [
+      "./dist/extensions/pi.mjs"
+    ]
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest --run",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint . && oxfmt . --check",
+    "fixcode": "oxlint . --fix && oxfmt ."
+  }
+}