Subpath Exports

Subpath	Exports
@pivanov/agent-hooks-bridge	defineHook, run, runInit, runInstall, runUninstall, runDoctor, unified types
@pivanov/agent-hooks-bridge/claude	claudeAdapter (IHostAdapter)
@pivanov/agent-hooks-bridge/cursor	cursorAdapter (IHostAdapter)
@pivanov/agent-hooks-bridge/codex	codexAdapter (IHostAdapter)
@pivanov/agent-hooks-bridge/types	Unified + per-host native types
@pivanov/agent-hooks-bridge/schema	unifiedEventSchema, UNIFIED_EVENT_SCHEMA_ID (programmatic)
@pivanov/agent-hooks-bridge/schema.json	Raw JSON Schema file (for non-TS validators)
@pivanov/agent-hooks-bridge/cli	The CLI dispatcher (used by the bin)
@pivanov/agent-hooks-bridge/install	Programmatic install entrypoint
@pivanov/agent-hooks-bridge/uninstall	Programmatic uninstall entrypoint

IHostAdapter

interface IHostAdapter {
  readonly id: "claude" | "cursor" | "codex";
  readonly capabilities: ReadonlySet<TUnifiedEventName>;
  parse(raw: Record<string, unknown>): TUnifiedEvent;
  serialize(response: IHookResponse, event: TUnifiedEvent): INativeResponse;
}

interface INativeResponse {
  stdout: Record<string, unknown> | null;
  exit_code: 0 | 1 | 2;
}

Direct adapter usage

Use the per-host adapter when wiring the bridge into a custom transport (an HTTP handler, a daemon IPC layer, a test harness) instead of stdin/stdout:

import { claudeAdapter } from "@pivanov/agent-hooks-bridge/claude";

const event = claudeAdapter.parse(rawStdinJson);
const response = await myDaemon.evaluate(event);
const native = claudeAdapter.serialize(response, event);

process.stdout.write(`${JSON.stringify(native.stdout)}\n`);
process.exit(native.exit_code);

run() is this sequence wrapped around stdin reading and exit-code handling.

JSON Schema

Two ways to validate hook payloads against the unified event shape:

// programmatic (TS-friendly; the schema is a typed Record<string, unknown>)
import { unifiedEventSchema, UNIFIED_EVENT_SCHEMA_ID } from "@pivanov/agent-hooks-bridge/schema";

// raw JSON file (for AJV, ajv-cli, json-schema-cli, jq plugins, Python's jsonschema, etc.)
import schema from "@pivanov/agent-hooks-bridge/schema.json" with { type: "json" };

The $id is stable across releases: https://pivanov.github.io/agent-hooks-bridge/schema/unified-event.json. Five oneOf variants discriminated on event. Required fields per variant match the TypeScript types; optional fields are documented in the schema's properties blocks.

Notes

• /types is types-only; no runtime code.
• There is no /runtime subpath; run is on the root export.
• There is no /testing subpath.
• /schema is a tiny TS shim that re-exports the JSON file as a typed constant. Use /schema.json directly if you don't need the constant.