@hydraharness/harness-hooks-registry 0.1.1-rc.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,36 @@
+# @hydraharness/harness-hooks-registry
+
+`HookRecordRegistry` (`ctx.hookRecords`) owns the user's own hook records. The records live in the `hooks` settings namespace, so one added from a configuration surface is written to `$HYDRA_HOME/settings.yaml` and mounts again on the next start; one added by hand-editing that document mounts without a restart. Each enabled record is mounted on its dialect's bridge — `@hydraharness/harness-hooks-claude-code` or `@hydraharness/harness-hooks-codex` — which owns the payloads, matcher semantics, and extension-point mapping.
+
+## Service API
+
+`list()` projects every stored record with its live status, the events its definitions cover, and how many command hooks they declare. `define(request)` stores one complete definition and converges the mounted set: `mode: 'create'` requires an unused name, and `mode: 'replace'` requires an existing record. These conditions are checked inside the serialized mutation chain, so concurrent creates cannot overwrite one another and an edit cannot recreate a removed record. `setEnabled({ name, enabled })` changes only the desired state. `remove(name)` deletes the record, unmounts it, and deletes any document this registry materialized for it. Every mutation and every reconciliation runs on one serialized chain.
+
+On replacement, omitted `enabled` and `defaultTimeoutMs` retain their stored values. Other omitted optional fields clear the stored values; callers must supply the complete document source, since inline definitions are not returned by `list()`.
+
+## Stored records
+
+Registry writes carry the revision read before constructing the next record list. A concurrent settings change rejects the write with `SettingsConflictError` and refreshes the stored projection; retry against that projection. This prevents stale lists from restoring deleted records or discarding another writer's changes.
+
+`hooks.records` is an ordered list of at most 50 records. A record carries `name` (`[A-Za-z0-9_-]{1,64}`, unique across records), `dialect` (`claude-code` or `codex`), exactly one document source, `defaultTimeoutMs`, and `enabled` (default `false`, so a new record is inert until switched on). `claude-code` records may also carry `pluginRoot` and `projectDir`, which the bridge substitutes into command strings.
+
+The document source is either `configPath` — an absolute path to a hook document the harness reads as-is — or `config`, the definitions stored inline in the settings document as a bare event map or a `{ hooks: … }` wrapper. Inline definitions are capped at 256 KiB and materialized to `$HYDRA_HOME/hooks/<name>.json` on every mount, because both bridges read one file path at load; editing the inline section is therefore enough to change what runs.
+
+`define` parses the definitions with the record's own dialect parser before it persists, so a stored record can never be silently inert. At mount time the same parse decides the record's projection: a record whose document is missing, is not valid JSON, or declares nothing its dialect can run is reported with status `invalid` and the reason instead of failing the process — a hand-edited document must not stop every other record from mounting.
+
+`hooks-registry/reconciled` is emitted after each reconciliation settles, carrying the projection. The package invariant checks the registry's one contract on that event: an accepted enabled record is live and a disabled one is not.
+
+Mounts belong to the registry's Host context, so they retain their declared services and survive disposal of the API caller. Definition validation requires at least one supported synchronous command hook, and the inline-document limit measures UTF-8 bytes.
+
+## Model Experience
+
+Indirectly, through the bridge a record mounts. `@hydraharness/harness-hooks-claude-code` and `@hydraharness/harness-hooks-codex` own everything a hook injects into a request — `SessionStart` and `UserPromptSubmit` context, `PostToolUse` feedback, `Stop` continuation messages — and this package decides only which of their configurations are live. It assembles no model input of its own.
+
+#### KV Cache effect
+
+Independent of this package's own operations, and consequential through them: mounting a record makes its hooks able to inject context into later requests, which the bridges document. Mounting or unmounting between requests does not itself rewrite an existing prefix; a hook that injects a message appends to the conversation like any other message.
+
+## Known Limitations and Deferred Work
+
+- **Process-wide records only** — each bridge reads one document at load, so a record applies to every session in the process. Per-session or project-local hook discovery stays the bridges' own `TODO(per-session-hook-config)`.
+- **No dialect conversion** — a record is mounted by the dialect it declares; the registry never translates a Claude Code document into Codex spelling or the reverse, and each dialect silently drops events the other supports.

package/lib/index.js

@@ -0,0 +1,386 @@
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+import { Service } from "@hydraharness/cordis";
+import z from "@hydraharness/schemastery";
+import { writeFileAtomic } from "@hydraharness/harness-atomic-write";
+import { resolveHydraHome } from "@hydraharness/harness-home-paths";
+import { settingsNamespace } from "@hydraharness/harness-settings";
+import { apply, inject as inject$1 } from "@hydraharness/harness-hooks-claude-code";
+import { apply as apply$1, inject as inject$2 } from "@hydraharness/harness-hooks-codex";
+import { parseClaudeCodeConfig } from "@hydraharness/harness-hooks-claude-code/config";
+import { parseCodexConfig } from "@hydraharness/harness-hooks-codex/config";
+//#region lib/types/index.js
+/**
+* User-declared hook records: one settings-backed registry that mounts every
+* enabled record on its dialect's bridge (`@hydraharness/harness-hooks-claude-code` or
+* `@hydraharness/harness-hooks-codex`) and unmounts it when the record is disabled,
+* redefined, or removed. The stored document (`hooks.records` in the harness
+* settings file) is the only source of truth, so a hook added from a
+* configuration surface survives a restart and one added by hand-editing that
+* document mounts without one.
+*
+* A record either points at an existing hook document (`configPath`) or carries
+* its definitions inline. Inline definitions are materialized under the harness
+* home, because both bridges read one file path at load.
+* @module @hydraharness/harness-hooks-registry
+*/
+/** Settings namespace holding every user-declared hook record. */
+const HOOKS_SETTINGS_NAMESPACE = settingsNamespace("hooks");
+/** Accepted record name. */
+const RECORD_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/u;
+const MAX_RECORDS = 50;
+const MAX_INLINE_BYTES = 256 * 1024;
+const DEFAULT_HOOK_TIMEOUT_MS = 6e5;
+const StoredRecordSchema = z.object({
+	name: z.string().required(),
+	dialect: z.union([z.const("claude-code"), z.const("codex")]).default("claude-code"),
+	configPath: z.string().default(""),
+	config: z.dict(z.any()).default({}),
+	pluginRoot: z.string().default(""),
+	projectDir: z.string().default(""),
+	defaultTimeoutMs: z.number().step(1).min(1).default(DEFAULT_HOOK_TIMEOUT_MS),
+	enabled: z.boolean().default(false)
+});
+const HooksSettingsSchema = z.object({ records: z.array(StoredRecordSchema).max(MAX_RECORDS).default([]) });
+/** Which document source a stored record declares. */
+function sourceKind(record) {
+	return record.configPath === "" ? "inline" : "file";
+}
+/**
+* Reject a definition this registry could not mount. Every check answers a
+* constraint the schema cannot express: the name grammar, that exactly one
+* document source is declared, that a path is absolute, and that inline
+* definitions stay inside the document budget.
+* @param record - one stored record to judge.
+* @param label - operation name used in the diagnostic.
+*/
+function assertMountable(record, label) {
+	if (!RECORD_NAME_PATTERN.test(record.name)) throw new Error(`${label}: record name must match ${String(RECORD_NAME_PATTERN)}`);
+	const inline = Object.keys(record.config).length > 0;
+	if (record.configPath === "" && !inline) throw new Error(`${label}: record ${record.name} needs either a configPath or inline hook definitions`);
+	if (record.configPath !== "" && inline) throw new Error(`${label}: record ${record.name} declares both a configPath and inline hook definitions`);
+	if (record.configPath !== "" && !isAbsolute(record.configPath)) throw new Error(`${label}: record ${record.name} configPath must be absolute`);
+	if (inline && Buffer.byteLength(JSON.stringify(record.config), "utf8") > MAX_INLINE_BYTES) throw new Error(`${label}: record ${record.name} inline hooks exceed ${String(MAX_INLINE_BYTES)} bytes`);
+	if (record.dialect === "codex" && (record.pluginRoot !== "" || record.projectDir !== "")) throw new Error(`${label}: record ${record.name} substitution roots apply to claude-code records only`);
+}
+/** Reject a stored section whose records collide, so no mount silently wins. */
+function assertUniqueNames(settings) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const record of settings.records) {
+		if (seen.has(record.name)) throw new Error(`hookRecords: record name ${JSON.stringify(record.name)} is declared more than once`);
+		seen.add(record.name);
+	}
+}
+/**
+* Parse one document with its dialect's parser, so what the registry reports is
+* exactly what the bridge will run.
+* @param dialect - the record's config dialect.
+* @param raw - parsed JSON document.
+* @returns the event names covered and the total command-hook count.
+*/
+function summarize(dialect, raw) {
+	const parsed = dialect === "claude-code" ? parseClaudeCodeConfig(raw) : parseCodexConfig(raw);
+	const events = Object.keys(parsed.config).sort();
+	let hookCount = 0;
+	for (const groups of Object.values(parsed.config)) for (const group of groups) hookCount += group.hooks.length;
+	if (hookCount === 0) throw new Error(`hookRecords: ${dialect} document contains no supported synchronous command hooks`);
+	return {
+		events,
+		hookCount
+	};
+}
+/**
+* Fold one write request onto the record it replaces. Every field is restated
+* by the caller: unlike a credential, nothing here is withheld from a read, so
+* an omission is a deliberate clear.
+* @param request - complete definition supplied by the caller.
+* @param previous - the record being replaced, when one exists.
+* @returns the next stored record.
+*/
+function foldDefinition(request, previous) {
+	return {
+		name: request.name.trim(),
+		dialect: request.dialect,
+		configPath: (request.configPath ?? "").trim(),
+		config: { ...request.config },
+		pluginRoot: (request.pluginRoot ?? "").trim(),
+		projectDir: (request.projectDir ?? "").trim(),
+		defaultTimeoutMs: request.defaultTimeoutMs ?? previous?.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+		enabled: request.enabled ?? previous?.enabled ?? false
+	};
+}
+/** Services required by the registry; the bridges themselves need `shell`. */
+const inject = ["settings", "shell"];
+/**
+* Settings-backed hook records with their live bridge mounts. Reconciliation is
+* idempotent and runs on one serialized chain, so a document commit from any
+* source — this service's own write, another process, or a hand edit —
+* converges the mounted set on the stored one.
+* Mutations reject with `SettingsConflictError` if another writer changes the
+* stored section after the read; retry uses the refreshed projection.
+*/
+var HookRecordRegistry = class extends Service {
+	static inject = inject;
+	/** Bridge mounts belong to this Host service, not to a traced API caller. */
+	owner;
+	static Config = z.object({ hydraHome: z.string() });
+	settings;
+	live = /* @__PURE__ */ new Map();
+	/** Stored records this registry refuses to mount, with the refusal reason. */
+	invalid = /* @__PURE__ */ new Map();
+	/** Directory holding the documents materialized from inline definitions. */
+	inlineRoot;
+	tail = Promise.resolve();
+	stopped = false;
+	constructor(ctx, config = {}) {
+		super(ctx, "hookRecords");
+		this.owner = ctx;
+		this.inlineRoot = join(resolveHydraHome(config.hydraHome), "hooks");
+		this.settings = ctx.settings.register(HOOKS_SETTINGS_NAMESPACE, HooksSettingsSchema, { validate: assertUniqueNames });
+	}
+	async [Service.init]() {
+		this.ctx.effect(() => () => this.shutdown(), "hookRecords.dispose");
+		this.ctx.effect(() => this.settings.watch(() => this.enqueue(() => this.reconcile())), "hookRecords.settingsWatch");
+		await this.enqueue(() => this.reconcile());
+	}
+	/**
+	* Project every stored record with its live state.
+	* @returns the current record projection, in stored order.
+	*/
+	list() {
+		return { records: this.settings.get().records.map((record) => this.view(record)) };
+	}
+	/**
+	* Create or replace one complete definition as requested, then
+	* converge the mounted set. A definition this registry could not mount is
+	* refused before anything persists.
+	* @param request - complete record definition.
+	* @returns the refreshed projection.
+	* @throws If create names an existing record or replace names a missing record.
+	*/
+	define(request) {
+		return this.enqueue(async () => {
+			const revision = this.settings.revision;
+			const records = this.settings.get().records;
+			const index = records.findIndex((candidate) => candidate.name === request.name.trim());
+			if (request.mode === "create" && index !== -1) throw new Error(`hookRecords.define: record ${request.name} already exists`);
+			if (request.mode === "replace" && index === -1) throw new Error(`hookRecords.define: record ${request.name} is not configured`);
+			const record = foldDefinition(request, index === -1 ? void 0 : records[index]);
+			assertMountable(record, "hookRecords.define");
+			summarize(record.dialect, await this.readDefinitions(record));
+			const next = index === -1 ? [...records, record] : records.map((candidate, position) => position === index ? record : candidate);
+			if (next.length > MAX_RECORDS) throw new Error(`hookRecords.define: at most ${String(MAX_RECORDS)} records are supported`);
+			await this.ctx.settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+			await this.reconcile();
+			return this.list();
+		});
+	}
+	/**
+	* Change one stored record's desired state.
+	* @param request - target record and desired state.
+	* @returns the refreshed projection.
+	*/
+	setEnabled(request) {
+		return this.enqueue(async () => {
+			const revision = this.settings.revision;
+			const records = this.settings.get().records;
+			const index = records.findIndex((candidate) => candidate.name === request.name);
+			if (index === -1) throw new Error(`hookRecords.setEnabled: record ${request.name} is not configured`);
+			const next = records.map((candidate, position) => position === index ? {
+				...candidate,
+				enabled: request.enabled
+			} : candidate);
+			await this.ctx.settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+			await this.reconcile();
+			return this.list();
+		});
+	}
+	/**
+	* Remove one stored record, unmount it, and delete any document this registry
+	* materialized for it.
+	* @param name - stored record name.
+	* @returns the refreshed projection.
+	*/
+	remove(name) {
+		return this.enqueue(async () => {
+			const revision = this.settings.revision;
+			const records = this.settings.get().records;
+			if (!records.some((candidate) => candidate.name === name)) throw new Error(`hookRecords.remove: record ${name} is not configured`);
+			await this.ctx.settings.replace(HOOKS_SETTINGS_NAMESPACE, { records: records.filter((candidate) => candidate.name !== name) }, revision);
+			await this.reconcile();
+			await rm(this.inlinePath(name), { force: true });
+			return this.list();
+		});
+	}
+	/** Serialize every mutation and reconciliation on one chain. */
+	enqueue(task) {
+		const run = this.tail.then(task, task);
+		this.tail = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	/**
+	* Converge the mounted set on the stored one: unmount every record that is
+	* gone, disabled, or redefined, then mount every enabled record that is not
+	* already live from the same definition. A record whose document is missing,
+	* unparseable, or refused by its dialect is recorded as `invalid` with the
+	* diagnostic and does not stop the others.
+	*/
+	async reconcile() {
+		if (this.stopped) return;
+		const records = new Map(this.settings.get().records.map((record) => [record.name, record]));
+		this.invalid.clear();
+		for (const [name, mount] of [...this.live]) {
+			const record = records.get(name);
+			if (record?.enabled === true && recordDigest(record) === mount.digest) continue;
+			this.live.delete(name);
+			await disposeQuietly(mount.fiber);
+		}
+		for (const record of records.values()) {
+			if (!record.enabled || this.live.has(record.name)) continue;
+			await this.mount(record);
+		}
+		this.ctx.emit("hooks-registry/reconciled", this.list());
+	}
+	/**
+	* Materialize the record's document when it is inline, then start its
+	* dialect's bridge. A refusal is stored as `invalid` rather than thrown: a
+	* hand-edited document must not stop every other record from mounting.
+	*/
+	async mount(record) {
+		let configPath;
+		let summary;
+		try {
+			assertMountable(record, "hookRecords");
+			configPath = await this.materialize(record);
+			summary = summarize(record.dialect, await this.readDefinitions(record));
+		} catch (error) {
+			/* v8 ignore next -- validation, JSON parsing, and local filesystem operations throw Error instances. */
+			this.invalid.set(record.name, error instanceof Error ? error.message : String(error));
+			return;
+		}
+		const fiber = record.dialect === "claude-code" ? this.owner.plugin({
+			name: `hook-record:${record.name}`,
+			inject: inject$1,
+			apply
+		}, {
+			configPath,
+			defaultTimeoutMs: record.defaultTimeoutMs,
+			...record.pluginRoot === "" ? {} : { pluginRoot: record.pluginRoot },
+			...record.projectDir === "" ? {} : { projectDir: record.projectDir }
+		}) : this.owner.plugin({
+			name: `hook-record:${record.name}`,
+			inject: inject$2,
+			apply: apply$1
+		}, {
+			configPath,
+			defaultTimeoutMs: record.defaultTimeoutMs
+		});
+		const mount = {
+			fiber,
+			digest: recordDigest(record),
+			events: summary.events,
+			hookCount: summary.hookCount,
+			status: "started"
+		};
+		this.live.set(record.name, mount);
+		try {
+			await fiber;
+		} catch (error) {
+			mount.status = "failed";
+			/* v8 ignore next -- Cordis normalizes plugin failures to Error before fiber.await rejects. */
+			mount.detail = error instanceof Error ? error.message : String(error);
+		}
+	}
+	/**
+	* Resolve the document path the bridge reads: a `file` record's own path, or
+	* the harness-home document this registry writes from inline definitions.
+	* Materialization is idempotent and re-runs per mount, so an edited inline
+	* section always reaches the bridge.
+	*/
+	async materialize(record) {
+		if (sourceKind(record) === "file") return record.configPath;
+		const path = this.inlinePath(record.name);
+		await mkdir(this.inlineRoot, {
+			recursive: true,
+			mode: 448
+		});
+		await writeFileAtomic(path, `${JSON.stringify(record.config, void 0, 2)}\n`, {
+			mode: 384,
+			dirMode: 448
+		});
+		return path;
+	}
+	/** Read one record's raw definitions, from its file or its inline section. */
+	async readDefinitions(record) {
+		if (sourceKind(record) === "inline") return record.config;
+		let text;
+		try {
+			text = await readFile(record.configPath, "utf8");
+		} catch (cause) {
+			throw new Error(`hookRecords: record ${record.name} cannot read ${record.configPath}`, { cause });
+		}
+		try {
+			return JSON.parse(text);
+		} catch (cause) {
+			throw new Error(`hookRecords: record ${record.name} document is not valid JSON`, { cause });
+		}
+	}
+	/** Path of the document this registry materializes for one inline record. */
+	inlinePath(name) {
+		return join(this.inlineRoot, `${name}.json`);
+	}
+	/** Project one stored record with its live state. */
+	view(record) {
+		const mount = this.live.get(record.name);
+		const invalid = this.invalid.get(record.name);
+		const status = invalid !== void 0 ? "invalid" : !record.enabled ? "stopped" : mount?.status ?? "stopped";
+		const detail = invalid ?? mount?.detail;
+		return {
+			name: record.name,
+			dialect: record.dialect,
+			source: sourceKind(record),
+			enabled: record.enabled,
+			status,
+			...detail === void 0 || status === "stopped" ? {} : { detail },
+			...sourceKind(record) === "file" ? { configPath: record.configPath } : {},
+			events: mount?.events ?? [],
+			hookCount: mount?.hookCount ?? 0,
+			...record.pluginRoot === "" ? {} : { pluginRoot: record.pluginRoot },
+			...record.projectDir === "" ? {} : { projectDir: record.projectDir }
+		};
+	}
+	/** Refuse new work, then unmount every live record. */
+	async shutdown() {
+		this.stopped = true;
+		/* v8 ignore next -- enqueue stores a fulfilled tail after either task outcome. */
+		await this.tail.catch(() => void 0);
+		this.invalid.clear();
+		for (const [name, mount] of [...this.live]) {
+			this.live.delete(name);
+			await disposeQuietly(mount.fiber);
+		}
+	}
+};
+/**
+* Digest of everything a mount is started from, so reconciliation can tell a
+* redefined record from an untouched one without restarting a live bridge on
+* every unrelated document commit. The desired state is excluded: enablement is
+* handled by mount and unmount, not by a restart.
+*/
+function recordDigest(record) {
+	const { enabled: _desired, ...definition } = record;
+	return JSON.stringify(definition);
+}
+/**
+* Unmount one bridge and swallow its teardown failure. The record it served is
+* already out of the live map, so a disposal error cannot restore it, and
+* letting it escape would strand every later record in the same reconcile.
+* @param fiber - the mount to tear down.
+*/
+async function disposeQuietly(fiber) {
+	try {
+		await fiber.dispose();
+	} catch (_hookMountTeardownFailure) {}
+}
+//#endregion
+export { HOOKS_SETTINGS_NAMESPACE, HookRecordRegistry, HookRecordRegistry as default, inject };

package/lib/invariant.js

@@ -0,0 +1,32 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hydraharness/harness-hooks-registry`.
+* @module @hydraharness/harness-hooks-registry/invariant
+*/
+const PACKAGE_NAME = "@hydraharness/harness-hooks-registry";
+/** Cordis companion plugin name. */
+const name = "hooks-registry-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* The registry's contract is that the mounted bridge set follows the stored
+* records once reconciliation settles: an enabled record it accepted is live,
+* and a disabled one is not. Both sides ride the reconciliation event, so the
+* check observes the authoritative projection rather than re-deriving it.
+*/
+const install = (ctx, fail) => {
+	ctx.on("hooks-registry/reconciled", (snapshot) => {
+		for (const record of snapshot.records) {
+			if (record.enabled && record.status === "stopped") fail(`enabled hook record ${JSON.stringify(record.name)} has no live bridge after reconciliation`);
+			if (!record.enabled && record.status !== "stopped") fail(`disabled hook record ${JSON.stringify(record.name)} still reports ${record.status}`);
+		}
+	});
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,117 @@
+/**
+ * User-declared hook records: one settings-backed registry that mounts every
+ * enabled record on its dialect's bridge (`@hydraharness/harness-hooks-claude-code` or
+ * `@hydraharness/harness-hooks-codex`) and unmounts it when the record is disabled,
+ * redefined, or removed. The stored document (`hooks.records` in the harness
+ * settings file) is the only source of truth, so a hook added from a
+ * configuration surface survives a restart and one added by hand-editing that
+ * document mounts without one.
+ *
+ * A record either points at an existing hook document (`configPath`) or carries
+ * its definitions inline. Inline definitions are materialized under the harness
+ * home, because both bridges read one file path at load.
+ * @module @hydraharness/harness-hooks-registry
+ */
+import { Service, type Context } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import type { HookRecordDefinitionRequest, HookRecordEnablementRequest, HookRecordSnapshot } from './types.ts';
+export type * from './types.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        /** User-declared hook records and their live bridge mounts. */
+        hookRecords: HookRecordRegistry;
+    }
+}
+/** Settings namespace holding every user-declared hook record. */
+export declare const HOOKS_SETTINGS_NAMESPACE: import("@hydraharness/harness-settings").SettingsNamespace;
+/** Registry configuration. */
+export interface Config {
+    /** Override the resolved harness home that holds materialized inline documents. */
+    hydraHome?: string;
+}
+/** Services required by the registry; the bridges themselves need `shell`. */
+export declare const inject: string[];
+/**
+ * Settings-backed hook records with their live bridge mounts. Reconciliation is
+ * idempotent and runs on one serialized chain, so a document commit from any
+ * source — this service's own write, another process, or a hand edit —
+ * converges the mounted set on the stored one.
+ * Mutations reject with `SettingsConflictError` if another writer changes the
+ * stored section after the read; retry uses the refreshed projection.
+ */
+export declare class HookRecordRegistry extends Service {
+    static inject: string[];
+    /** Bridge mounts belong to this Host service, not to a traced API caller. */
+    private readonly owner;
+    static Config: z<Config>;
+    private readonly settings;
+    private readonly live;
+    /** Stored records this registry refuses to mount, with the refusal reason. */
+    private readonly invalid;
+    /** Directory holding the documents materialized from inline definitions. */
+    private readonly inlineRoot;
+    private tail;
+    private stopped;
+    constructor(ctx: Context, config?: Config);
+    protected [Service.init](): Promise<void>;
+    /**
+     * Project every stored record with its live state.
+     * @returns the current record projection, in stored order.
+     */
+    list(): HookRecordSnapshot;
+    /**
+     * Create or replace one complete definition as requested, then
+     * converge the mounted set. A definition this registry could not mount is
+     * refused before anything persists.
+     * @param request - complete record definition.
+     * @returns the refreshed projection.
+     * @throws If create names an existing record or replace names a missing record.
+     */
+    define(request: HookRecordDefinitionRequest): Promise<HookRecordSnapshot>;
+    /**
+     * Change one stored record's desired state.
+     * @param request - target record and desired state.
+     * @returns the refreshed projection.
+     */
+    setEnabled(request: HookRecordEnablementRequest): Promise<HookRecordSnapshot>;
+    /**
+     * Remove one stored record, unmount it, and delete any document this registry
+     * materialized for it.
+     * @param name - stored record name.
+     * @returns the refreshed projection.
+     */
+    remove(name: string): Promise<HookRecordSnapshot>;
+    /** Serialize every mutation and reconciliation on one chain. */
+    private enqueue;
+    /**
+     * Converge the mounted set on the stored one: unmount every record that is
+     * gone, disabled, or redefined, then mount every enabled record that is not
+     * already live from the same definition. A record whose document is missing,
+     * unparseable, or refused by its dialect is recorded as `invalid` with the
+     * diagnostic and does not stop the others.
+     */
+    private reconcile;
+    /**
+     * Materialize the record's document when it is inline, then start its
+     * dialect's bridge. A refusal is stored as `invalid` rather than thrown: a
+     * hand-edited document must not stop every other record from mounting.
+     */
+    private mount;
+    /**
+     * Resolve the document path the bridge reads: a `file` record's own path, or
+     * the harness-home document this registry writes from inline definitions.
+     * Materialization is idempotent and re-runs per mount, so an edited inline
+     * section always reaches the bridge.
+     */
+    private materialize;
+    /** Read one record's raw definitions, from its file or its inline section. */
+    private readDefinitions;
+    /** Path of the document this registry materializes for one inline record. */
+    private inlinePath;
+    /** Project one stored record with its live state. */
+    private view;
+    /** Refuse new work, then unmount every live record. */
+    private shutdown;
+}
+export default HookRecordRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.js

@@ -0,0 +1,434 @@
+/**
+ * User-declared hook records: one settings-backed registry that mounts every
+ * enabled record on its dialect's bridge (`@hydraharness/harness-hooks-claude-code` or
+ * `@hydraharness/harness-hooks-codex`) and unmounts it when the record is disabled,
+ * redefined, or removed. The stored document (`hooks.records` in the harness
+ * settings file) is the only source of truth, so a hook added from a
+ * configuration surface survives a restart and one added by hand-editing that
+ * document mounts without one.
+ *
+ * A record either points at an existing hook document (`configPath`) or carries
+ * its definitions inline. Inline definitions are materialized under the harness
+ * home, because both bridges read one file path at load.
+ * @module @hydraharness/harness-hooks-registry
+ */
+import { mkdir, readFile, rm } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { Service } from '@hydraharness/cordis';
+import z from '@hydraharness/schemastery';
+import { writeFileAtomic } from '@hydraharness/harness-atomic-write';
+import { resolveHydraHome } from '@hydraharness/harness-home-paths';
+import { settingsNamespace } from '@hydraharness/harness-settings';
+import { apply as applyClaudeCodeHooks, inject as claudeCodeInject, } from '@hydraharness/harness-hooks-claude-code';
+import { apply as applyCodexHooks, inject as codexInject } from '@hydraharness/harness-hooks-codex';
+import { parseClaudeCodeConfig } from '@hydraharness/harness-hooks-claude-code/config';
+import { parseCodexConfig } from '@hydraharness/harness-hooks-codex/config';
+/** Settings namespace holding every user-declared hook record. */
+export const HOOKS_SETTINGS_NAMESPACE = settingsNamespace('hooks');
+/** Accepted record name. */
+const RECORD_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/u;
+const MAX_RECORDS = 50;
+const MAX_INLINE_BYTES = 256 * 1024;
+const DEFAULT_HOOK_TIMEOUT_MS = 600_000;
+const StoredRecordSchema = z.object({
+    name: z.string().required(),
+    dialect: z.union([z.const('claude-code'), z.const('codex')]).default('claude-code'),
+    configPath: z.string().default(''),
+    // Inline definitions stay opaque to the schema: each dialect owns its own
+    // document grammar, and both parsers already refuse what they cannot run.
+    config: z.dict(z.any()).default({}),
+    pluginRoot: z.string().default(''),
+    projectDir: z.string().default(''),
+    defaultTimeoutMs: z.number().step(1).min(1).default(DEFAULT_HOOK_TIMEOUT_MS),
+    enabled: z.boolean().default(false),
+});
+const HooksSettingsSchema = z.object({
+    records: z.array(StoredRecordSchema).max(MAX_RECORDS).default([]),
+});
+/** Which document source a stored record declares. */
+function sourceKind(record) {
+    return record.configPath === '' ? 'inline' : 'file';
+}
+/**
+ * Reject a definition this registry could not mount. Every check answers a
+ * constraint the schema cannot express: the name grammar, that exactly one
+ * document source is declared, that a path is absolute, and that inline
+ * definitions stay inside the document budget.
+ * @param record - one stored record to judge.
+ * @param label - operation name used in the diagnostic.
+ */
+function assertMountable(record, label) {
+    if (!RECORD_NAME_PATTERN.test(record.name)) {
+        throw new Error(`${label}: record name must match ${String(RECORD_NAME_PATTERN)}`);
+    }
+    const inline = Object.keys(record.config).length > 0;
+    if (record.configPath === '' && !inline) {
+        throw new Error(`${label}: record ${record.name} needs either a configPath or inline hook definitions`);
+    }
+    if (record.configPath !== '' && inline) {
+        throw new Error(`${label}: record ${record.name} declares both a configPath and inline hook definitions`);
+    }
+    if (record.configPath !== '' && !isAbsolute(record.configPath)) {
+        throw new Error(`${label}: record ${record.name} configPath must be absolute`);
+    }
+    if (inline && Buffer.byteLength(JSON.stringify(record.config), 'utf8') > MAX_INLINE_BYTES) {
+        throw new Error(`${label}: record ${record.name} inline hooks exceed ${String(MAX_INLINE_BYTES)} bytes`);
+    }
+    if (record.dialect === 'codex' && (record.pluginRoot !== '' || record.projectDir !== '')) {
+        throw new Error(`${label}: record ${record.name} substitution roots apply to claude-code records only`);
+    }
+}
+/** Reject a stored section whose records collide, so no mount silently wins. */
+function assertUniqueNames(settings) {
+    const seen = new Set();
+    for (const record of settings.records) {
+        if (seen.has(record.name)) {
+            throw new Error(`hookRecords: record name ${JSON.stringify(record.name)} is declared more than once`);
+        }
+        seen.add(record.name);
+    }
+}
+/**
+ * Parse one document with its dialect's parser, so what the registry reports is
+ * exactly what the bridge will run.
+ * @param dialect - the record's config dialect.
+ * @param raw - parsed JSON document.
+ * @returns the event names covered and the total command-hook count.
+ */
+function summarize(dialect, raw) {
+    const parsed = dialect === 'claude-code' ? parseClaudeCodeConfig(raw) : parseCodexConfig(raw);
+    const events = Object.keys(parsed.config).sort();
+    let hookCount = 0;
+    for (const groups of Object.values(parsed.config)) {
+        for (const group of groups)
+            hookCount += group.hooks.length;
+    }
+    if (hookCount === 0)
+        throw new Error(`hookRecords: ${dialect} document contains no supported synchronous command hooks`);
+    return { events, hookCount };
+}
+/**
+ * Fold one write request onto the record it replaces. Every field is restated
+ * by the caller: unlike a credential, nothing here is withheld from a read, so
+ * an omission is a deliberate clear.
+ * @param request - complete definition supplied by the caller.
+ * @param previous - the record being replaced, when one exists.
+ * @returns the next stored record.
+ */
+function foldDefinition(request, previous) {
+    return {
+        name: request.name.trim(),
+        dialect: request.dialect,
+        configPath: (request.configPath ?? '').trim(),
+        config: { ...request.config },
+        pluginRoot: (request.pluginRoot ?? '').trim(),
+        projectDir: (request.projectDir ?? '').trim(),
+        defaultTimeoutMs: request.defaultTimeoutMs ?? previous?.defaultTimeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS,
+        enabled: request.enabled ?? previous?.enabled ?? false,
+    };
+}
+/** Services required by the registry; the bridges themselves need `shell`. */
+export const inject = ['settings', 'shell'];
+/**
+ * Settings-backed hook records with their live bridge mounts. Reconciliation is
+ * idempotent and runs on one serialized chain, so a document commit from any
+ * source — this service's own write, another process, or a hand edit —
+ * converges the mounted set on the stored one.
+ * Mutations reject with `SettingsConflictError` if another writer changes the
+ * stored section after the read; retry uses the refreshed projection.
+ */
+export class HookRecordRegistry extends Service {
+    static inject = inject;
+    /** Bridge mounts belong to this Host service, not to a traced API caller. */
+    owner;
+    static Config = z.object({
+        hydraHome: z.string(),
+    });
+    settings;
+    live = new Map();
+    /** Stored records this registry refuses to mount, with the refusal reason. */
+    invalid = new Map();
+    /** Directory holding the documents materialized from inline definitions. */
+    inlineRoot;
+    tail = Promise.resolve();
+    stopped = false;
+    constructor(ctx, config = {}) {
+        super(ctx, 'hookRecords');
+        this.owner = ctx;
+        this.inlineRoot = join(resolveHydraHome(config.hydraHome), 'hooks');
+        this.settings = ctx.settings.register(HOOKS_SETTINGS_NAMESPACE, HooksSettingsSchema, {
+            // Refuse a colliding section where it is written: two records claiming
+            // one name would make which definitions run depend on mount order.
+            validate: assertUniqueNames,
+        });
+    }
+    async [Service.init]() {
+        this.ctx.effect(() => () => this.shutdown(), 'hookRecords.dispose');
+        this.ctx.effect(() => this.settings.watch(() => this.enqueue(() => this.reconcile())), 'hookRecords.settingsWatch');
+        await this.enqueue(() => this.reconcile());
+    }
+    /**
+     * Project every stored record with its live state.
+     * @returns the current record projection, in stored order.
+     */
+    list() {
+        return { records: this.settings.get().records.map(record => this.view(record)) };
+    }
+    /**
+     * Create or replace one complete definition as requested, then
+     * converge the mounted set. A definition this registry could not mount is
+     * refused before anything persists.
+     * @param request - complete record definition.
+     * @returns the refreshed projection.
+     * @throws If create names an existing record or replace names a missing record.
+     */
+    define(request) {
+        return this.enqueue(async () => {
+            const revision = this.settings.revision;
+            const records = this.settings.get().records;
+            const index = records.findIndex(candidate => candidate.name === request.name.trim());
+            if (request.mode === 'create' && index !== -1)
+                throw new Error(`hookRecords.define: record ${request.name} already exists`);
+            if (request.mode === 'replace' && index === -1)
+                throw new Error(`hookRecords.define: record ${request.name} is not configured`);
+            const record = foldDefinition(request, index === -1 ? undefined : records[index]);
+            assertMountable(record, 'hookRecords.define');
+            // The dialect parser is the authority on whether these definitions run;
+            // refusing here means a stored record can never be silently inert.
+            summarize(record.dialect, await this.readDefinitions(record));
+            const next = index === -1
+                ? [...records, record]
+                : records.map((candidate, position) => position === index ? record : candidate);
+            if (next.length > MAX_RECORDS)
+                throw new Error(`hookRecords.define: at most ${String(MAX_RECORDS)} records are supported`);
+            await this.ctx.settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+            await this.reconcile();
+            return this.list();
+        });
+    }
+    /**
+     * Change one stored record's desired state.
+     * @param request - target record and desired state.
+     * @returns the refreshed projection.
+     */
+    setEnabled(request) {
+        return this.enqueue(async () => {
+            const revision = this.settings.revision;
+            const records = this.settings.get().records;
+            const index = records.findIndex(candidate => candidate.name === request.name);
+            if (index === -1)
+                throw new Error(`hookRecords.setEnabled: record ${request.name} is not configured`);
+            const next = records.map((candidate, position) => position === index
+                ? { ...candidate, enabled: request.enabled }
+                : candidate);
+            await this.ctx.settings.update(HOOKS_SETTINGS_NAMESPACE, { records: next }, revision);
+            await this.reconcile();
+            return this.list();
+        });
+    }
+    /**
+     * Remove one stored record, unmount it, and delete any document this registry
+     * materialized for it.
+     * @param name - stored record name.
+     * @returns the refreshed projection.
+     */
+    remove(name) {
+        return this.enqueue(async () => {
+            const revision = this.settings.revision;
+            const records = this.settings.get().records;
+            if (!records.some(candidate => candidate.name === name)) {
+                throw new Error(`hookRecords.remove: record ${name} is not configured`);
+            }
+            await this.ctx.settings.replace(HOOKS_SETTINGS_NAMESPACE, { records: records.filter(candidate => candidate.name !== name) }, revision);
+            await this.reconcile();
+            await rm(this.inlinePath(name), { force: true });
+            return this.list();
+        });
+    }
+    /* jscpd:ignore-start -- hook and MCP registries intentionally share serialized reconciliation. */
+    /** Serialize every mutation and reconciliation on one chain. */
+    enqueue(task) {
+        const run = this.tail.then(task, task);
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * Converge the mounted set on the stored one: unmount every record that is
+     * gone, disabled, or redefined, then mount every enabled record that is not
+     * already live from the same definition. A record whose document is missing,
+     * unparseable, or refused by its dialect is recorded as `invalid` with the
+     * diagnostic and does not stop the others.
+     */
+    async reconcile() {
+        if (this.stopped)
+            return;
+        const records = new Map(this.settings.get().records.map(record => [record.name, record]));
+        this.invalid.clear();
+        for (const [name, mount] of [...this.live]) {
+            const record = records.get(name);
+            if (record?.enabled === true && recordDigest(record) === mount.digest)
+                continue;
+            this.live.delete(name);
+            await disposeQuietly(mount.fiber);
+        }
+        for (const record of records.values()) {
+            if (!record.enabled || this.live.has(record.name))
+                continue;
+            await this.mount(record);
+        }
+        // The projection is published only after every mount settled, so an
+        // observer cannot read a record whose bridge is still loading.
+        this.ctx.emit('hooks-registry/reconciled', this.list());
+    }
+    /* jscpd:ignore-end */
+    /**
+     * Materialize the record's document when it is inline, then start its
+     * dialect's bridge. A refusal is stored as `invalid` rather than thrown: a
+     * hand-edited document must not stop every other record from mounting.
+     */
+    async mount(record) {
+        let configPath;
+        let summary;
+        try {
+            assertMountable(record, 'hookRecords');
+            configPath = await this.materialize(record);
+            summary = summarize(record.dialect, await this.readDefinitions(record));
+        }
+        catch (error) {
+            /* v8 ignore next -- validation, JSON parsing, and local filesystem operations throw Error instances. */
+            this.invalid.set(record.name, error instanceof Error ? error.message : String(error));
+            return;
+        }
+        const fiber = record.dialect === 'claude-code'
+            ? this.owner.plugin({
+                name: `hook-record:${record.name}`,
+                inject: claudeCodeInject,
+                apply: applyClaudeCodeHooks,
+            }, {
+                configPath,
+                defaultTimeoutMs: record.defaultTimeoutMs,
+                ...record.pluginRoot === '' ? {} : { pluginRoot: record.pluginRoot },
+                ...record.projectDir === '' ? {} : { projectDir: record.projectDir },
+            })
+            : this.owner.plugin({
+                name: `hook-record:${record.name}`,
+                inject: codexInject,
+                apply: applyCodexHooks,
+            }, {
+                configPath,
+                defaultTimeoutMs: record.defaultTimeoutMs,
+            });
+        const mount = {
+            fiber,
+            digest: recordDigest(record),
+            events: summary.events,
+            hookCount: summary.hookCount,
+            status: 'started',
+        };
+        this.live.set(record.name, mount);
+        try {
+            await fiber;
+        }
+        catch (error) {
+            mount.status = 'failed';
+            /* v8 ignore next -- Cordis normalizes plugin failures to Error before fiber.await rejects. */
+            mount.detail = error instanceof Error ? error.message : String(error);
+        }
+    }
+    /**
+     * Resolve the document path the bridge reads: a `file` record's own path, or
+     * the harness-home document this registry writes from inline definitions.
+     * Materialization is idempotent and re-runs per mount, so an edited inline
+     * section always reaches the bridge.
+     */
+    async materialize(record) {
+        if (sourceKind(record) === 'file')
+            return record.configPath;
+        const path = this.inlinePath(record.name);
+        await mkdir(this.inlineRoot, { recursive: true, mode: 0o700 });
+        await writeFileAtomic(path, `${JSON.stringify(record.config, undefined, 2)}\n`, { mode: 0o600, dirMode: 0o700 });
+        return path;
+    }
+    /** Read one record's raw definitions, from its file or its inline section. */
+    async readDefinitions(record) {
+        if (sourceKind(record) === 'inline')
+            return record.config;
+        let text;
+        try {
+            text = await readFile(record.configPath, 'utf8');
+        }
+        catch (cause) {
+            throw new Error(`hookRecords: record ${record.name} cannot read ${record.configPath}`, { cause });
+        }
+        try {
+            return JSON.parse(text);
+        }
+        catch (cause) {
+            throw new Error(`hookRecords: record ${record.name} document is not valid JSON`, { cause });
+        }
+    }
+    /** Path of the document this registry materializes for one inline record. */
+    inlinePath(name) {
+        return join(this.inlineRoot, `${name}.json`);
+    }
+    /** Project one stored record with its live state. */
+    view(record) {
+        const mount = this.live.get(record.name);
+        const invalid = this.invalid.get(record.name);
+        const status = invalid !== undefined
+            ? 'invalid'
+            : !record.enabled ? 'stopped' : mount?.status ?? 'stopped';
+        const detail = invalid ?? mount?.detail;
+        return {
+            name: record.name,
+            dialect: record.dialect,
+            source: sourceKind(record),
+            enabled: record.enabled,
+            status,
+            ...detail === undefined || status === 'stopped' ? {} : { detail },
+            ...sourceKind(record) === 'file' ? { configPath: record.configPath } : {},
+            events: mount?.events ?? [],
+            hookCount: mount?.hookCount ?? 0,
+            ...record.pluginRoot === '' ? {} : { pluginRoot: record.pluginRoot },
+            ...record.projectDir === '' ? {} : { projectDir: record.projectDir },
+        };
+    }
+    /* jscpd:ignore-start -- hook and MCP shutdowns intentionally share teardown semantics. */
+    /** Refuse new work, then unmount every live record. */
+    async shutdown() {
+        this.stopped = true;
+        /* v8 ignore next -- enqueue stores a fulfilled tail after either task outcome. */
+        await this.tail.catch(() => undefined);
+        this.invalid.clear();
+        for (const [name, mount] of [...this.live]) {
+            this.live.delete(name);
+            await disposeQuietly(mount.fiber);
+        }
+    }
+}
+/**
+ * Digest of everything a mount is started from, so reconciliation can tell a
+ * redefined record from an untouched one without restarting a live bridge on
+ * every unrelated document commit. The desired state is excluded: enablement is
+ * handled by mount and unmount, not by a restart.
+ */
+function recordDigest(record) {
+    const { enabled: _desired, ...definition } = record;
+    return JSON.stringify(definition);
+}
+/**
+ * Unmount one bridge and swallow its teardown failure. The record it served is
+ * already out of the live map, so a disposal error cannot restore it, and
+ * letting it escape would strand every later record in the same reconcile.
+ * @param fiber - the mount to tear down.
+ */
+async function disposeQuietly(fiber) {
+    try {
+        await fiber.dispose();
+    }
+    catch (_hookMountTeardownFailure) {
+        // The fiber is inactive either way; nothing here can act on the failure.
+    }
+}
+export default HookRecordRegistry;
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-hooks-registry`.
+ * @module @hydraharness/harness-hooks-registry/invariant
+ */
+import type { Context } from '@hydraharness/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "hooks-registry-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,34 @@
+/**
+ * Package-owned invariant companion for `@hydraharness/harness-hooks-registry`.
+ * @module @hydraharness/harness-hooks-registry/invariant
+ */
+const PACKAGE_NAME = '@hydraharness/harness-hooks-registry';
+/** Cordis companion plugin name. */
+export const name = 'hooks-registry-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * The registry's contract is that the mounted bridge set follows the stored
+ * records once reconciliation settles: an enabled record it accepted is live,
+ * and a disabled one is not. Both sides ride the reconciliation event, so the
+ * check observes the authoritative projection rather than re-deriving it.
+ */
+const install = (ctx, fail) => {
+    ctx.on('hooks-registry/reconciled', (snapshot) => {
+        for (const record of snapshot.records) {
+            if (record.enabled && record.status === 'stopped') {
+                fail(`enabled hook record ${JSON.stringify(record.name)} has no live bridge after reconciliation`);
+            }
+            if (!record.enabled && record.status !== 'stopped') {
+                fail(`disabled hook record ${JSON.stringify(record.name)} still reports ${record.status}`);
+            }
+        }
+    });
+};
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,89 @@
+/** Public types for the user-declared hook registry. */
+import type { JsonValue } from '@hydraharness/harness-session/types';
+/** Hook config dialect a record is written in, selecting its bridge. */
+export type HookDialect = 'claude-code' | 'codex';
+/** Where a record's hook definitions come from. */
+export type HookSourceKind = 'file' | 'inline';
+/**
+ * Live state of one stored record. `invalid` is a stored record this registry
+ * refuses to mount — an unreadable path, an unparseable document, or a
+ * definition the dialect rejects — never a hook execution failure.
+ */
+export type HookRecordStatus = 'stopped' | 'started' | 'failed' | 'invalid';
+/** One stored hook record as a configuration surface sees it. */
+export interface HookRecordView {
+    readonly name: string;
+    readonly dialect: HookDialect;
+    readonly source: HookSourceKind;
+    /** Desired state stored in the document, independent of {@link status}. */
+    readonly enabled: boolean;
+    readonly status: HookRecordStatus;
+    /** Why a record is `invalid`, or the mount failure summary. */
+    readonly detail?: string;
+    /** Absolute document path of a `file` record. */
+    readonly configPath?: string;
+    /**
+     * Event names the mounted definitions cover, in dialect spelling. Empty until
+     * the record's definitions are read, and for a record this registry refuses.
+     */
+    readonly events: readonly string[];
+    /** How many command hooks the definitions declare across every event. */
+    readonly hookCount: number;
+    /** Substitution root a `claude-code` record supplies for `${CLAUDE_PLUGIN_ROOT}`. */
+    readonly pluginRoot?: string;
+    /** Substitution root a `claude-code` record supplies for `${CLAUDE_PROJECT_DIR}`. */
+    readonly projectDir?: string;
+}
+/** Complete immutable projection returned by every registry operation. */
+export interface HookRecordSnapshot {
+    readonly records: readonly HookRecordView[];
+}
+/**
+ * Complete definition of one hook record. A write replaces the named record
+ * wholesale, so an omitted optional field clears the stored one. Exactly one of
+ * `configPath` and `config` must be supplied.
+ */
+export interface HookRecordDefinitionRequest {
+    /** Create requires an unused name; replace requires an existing record. */
+    readonly mode: 'create' | 'replace';
+    /** Stable record name; `[A-Za-z0-9_-]{1,64}`. */
+    readonly name: string;
+    readonly dialect: HookDialect;
+    /** Absolute path to an existing hook document the harness reads as-is. */
+    readonly configPath?: string;
+    /**
+     * Hook definitions stored inline in the settings document: either a bare
+     * event map or a `{ hooks: … }` wrapper, in the record's dialect. The registry
+     * materializes them into a file for the bridge to read. Each dialect owns its
+     * own document grammar, so the values stay lossless JSON rather than a shape
+     * this package restates.
+     */
+    readonly config?: Readonly<Record<string, JsonValue>>;
+    /** Replaces `${CLAUDE_PLUGIN_ROOT}` in `claude-code` commands. */
+    readonly pluginRoot?: string;
+    /** Replaces `${CLAUDE_PROJECT_DIR}` in `claude-code` commands and env. */
+    readonly projectDir?: string;
+    /** Default per-hook timeout in milliseconds when a hook declares none. */
+    readonly defaultTimeoutMs?: number;
+    /** Desired state; a new record defaults to disabled. */
+    readonly enabled?: boolean;
+}
+/** Change one stored record's desired state without touching its definition. */
+export interface HookRecordEnablementRequest {
+    readonly name: string;
+    readonly enabled: boolean;
+}
+declare module '@hydraharness/cordis' {
+    interface Events {
+        /**
+         * The mounted bridge set now matches the stored records. Emitted after each
+         * reconciliation settles — including the one at startup and the ones a
+         * document change triggers — so an observer never reads the projection
+         * between a committed record change and the mount that follows it.
+         * @param snapshot - the projection as of this reconciliation.
+         * @mode emit
+         */
+        'hooks-registry/reconciled'(snapshot: HookRecordSnapshot): void;
+    }
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/types/types.js

@@ -0,0 +1,3 @@
+/** Public types for the user-declared hook registry. */
+export {};
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@hydraharness/harness-hooks-registry",
+  "description": "Settings-backed hook records that mount and unmount Claude Code and Codex hook bridges",
+  "hydra": {
+    "plugin": {
+      "application": "Save hook definitions and enable or disable their execution bridges."
+    }
+  },
+  "version": "0.1.1-rc.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/hooks/hooks-registry"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@hydraharness/harness-atomic-write": "^0.1.1-rc.5",
+    "@hydraharness/schemastery": "^3.18.2",
+    "@hydraharness/harness-home-paths": "^0.1.1-rc.5"
+  },
+  "peerDependencies": {
+    "@hydraharness/harness-hooks-claude-code": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-settings": "^0.1.1-rc.5",
+    "@hydraharness/harness-hooks-codex": "^0.1.1-rc.5",
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5"
+  },
+  "devDependencies": {
+    "@hydraharness/harness-hooks-codex": "^0.1.1-rc.5",
+    "@hydraharness/harness-hooks-claude-code": "^0.1.1-rc.5",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.5",
+    "@hydraharness/harness-session": "^0.1.1-rc.5",
+    "@hydraharness/harness-settings": "^0.1.1-rc.5",
+    "@hydraharness/harness-settings-file": "^0.1.1-rc.5",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/cordis": "^4.0.2"
+  }
+}