@cleocode/caamp 2026.10.8 → 2026.10.9-rc.ci.676

package/dist/hooks.d.ts

@@ -0,0 +1,812 @@
+/**
+ * CAAMP Hooks Normalizer - Type Definitions
+ *
+ * Defines the canonical CAAMP hook event taxonomy and provider mapping types.
+ * CAAMP provides a unified hook interface across all providers — consumers
+ * use canonical event names, and the normalizer translates to/from
+ * provider-native names.
+ */
+
+/**
+ * Definition of a canonical hook event including its category and behavior.
+ *
+ * @remarks
+ * Each canonical event has a category for grouping, a human-readable description,
+ * and a `canBlock` flag indicating whether a hook handler can prevent the
+ * associated action from proceeding.
+ *
+ * @public
+ */
+interface CanonicalEventDefinition {
+    /** The lifecycle category this event belongs to (e.g. `"session"`, `"tool"`). */
+    category: HookCategory;
+    /** Human-readable description of when this event fires. */
+    description: string;
+    /** Whether a hook handler can block or cancel the associated action. */
+    canBlock: boolean;
+}
+/**
+ * The type of hook system a provider uses.
+ *
+ * @remarks
+ * - `"config"` — hooks defined in a configuration file (e.g. Claude Code `.claude/settings.json`)
+ * - `"plugin"` — hooks implemented via a plugin/extension system
+ * - `"none"` — provider does not support hooks
+ *
+ * @public
+ */
+type HookSystemType = 'config' | 'plugin' | 'extension' | 'none';
+/**
+ * The mechanism a provider uses to execute hook handlers.
+ *
+ * @remarks
+ * - `"command"` — shell command execution
+ * - `"http"` — HTTP webhook callback
+ * - `"prompt"` — LLM prompt injection
+ * - `"agent"` — sub-agent delegation
+ * - `"plugin"` — native plugin API call
+ *
+ * @public
+ */
+type HookHandlerType = 'command' | 'http' | 'prompt' | 'agent' | 'plugin' | 'extension';
+/**
+ * Mapping of a single canonical event to a provider's native representation.
+ *
+ * @remarks
+ * Each entry in a provider's hook profile maps one canonical event to the
+ * provider's native event name. If `supported` is `false`, the provider
+ * does not fire this event. Optional `notes` capture caveats or limitations.
+ *
+ * @public
+ */
+interface HookMapping {
+    /** The provider-native event name, or `null` if the event has no native equivalent. */
+    nativeName: string | null;
+    /** Whether this canonical event is supported by the provider. */
+    supported: boolean;
+    /**
+     * Optional notes about support limitations or behavioral differences.
+     *
+     * @defaultValue `undefined`
+     */
+    notes?: string;
+}
+/**
+ * Complete hook profile for a single provider.
+ *
+ * @remarks
+ * Describes the provider's hook system type, configuration location, supported
+ * handler types, and the full mapping of canonical events to native names.
+ * This is the primary data structure loaded from `providers/hook-mappings.json`.
+ *
+ * @public
+ */
+interface ProviderHookProfile {
+    /** The type of hook system the provider uses (`"config"`, `"plugin"`, or `"none"`). */
+    hookSystem: HookSystemType;
+    /** Filesystem path template to the provider's hook configuration file, or `null`. */
+    hookConfigPath: string | null;
+    /** The configuration format used for hooks (e.g. `"json"`, `"yaml"`), or `null`. */
+    hookFormat: string | null;
+    /** The handler execution mechanisms this provider supports. */
+    handlerTypes: HookHandlerType[];
+    /** Whether the provider's hook system is considered experimental or unstable. */
+    experimental: boolean;
+    /** Project-local delivery and version evidence; absence is unverified. */
+    projectDelivery?: ProviderProjectHookCapability;
+    /** Provider event mappings; domain-only canonical events have no native representation. */
+    mappings: Partial<Record<CanonicalHookEvent, HookMapping>>;
+    /** Optional registry context for extension-based providers. */
+    notes?: string;
+    /** Registry-owned native event catalog name. */
+    nativeEventCatalog?: string;
+    /** Native event names that exist only in this provider with no canonical equivalent. */
+    providerOnlyEvents: string[];
+}
+/**
+ * A fully resolved hook event with both canonical and native names.
+ *
+ * @remarks
+ * Returned by batch translation functions. Contains all the context needed
+ * to register or invoke a hook handler: the canonical name for CAAMP logic,
+ * the native name for provider-specific calls, and metadata about category
+ * and blocking behavior.
+ *
+ * @public
+ */
+interface NormalizedHookEvent {
+    /** The CAAMP canonical event name. */
+    canonical: CanonicalHookEvent;
+    /** The provider-native event name. */
+    native: string;
+    /** The provider this event was resolved for. */
+    providerId: string;
+    /** The lifecycle category of this event. */
+    category: HookCategory;
+    /** Whether a handler for this event can block the associated action. */
+    canBlock: boolean;
+}
+/**
+ * Result of querying whether a provider supports a specific canonical event.
+ *
+ * @remarks
+ * Returned by `getHookSupport()`. Includes the native name translation
+ * and any notes about support limitations. When `supported` is `false`,
+ * `native` will be `null`.
+ *
+ * @public
+ */
+interface HookSupportResult {
+    /** The canonical event that was queried. */
+    canonical: CanonicalHookEvent;
+    /** Whether the provider supports this event. */
+    supported: boolean;
+    /** The provider-native event name, or `null` if unsupported. */
+    native: string | null;
+    /**
+     * Optional notes about support caveats.
+     *
+     * @defaultValue `undefined`
+     */
+    notes?: string;
+}
+/**
+ * Aggregated hook support summary for a single provider.
+ *
+ * @remarks
+ * Provides a high-level view of a provider's hook capabilities including
+ * counts, coverage percentage, and lists of supported/unsupported events.
+ * Useful for CLI display and provider comparison features.
+ *
+ * @public
+ */
+interface ProviderHookSummary {
+    /** The provider identifier. */
+    providerId: string;
+    /** The type of hook system the provider uses. */
+    hookSystem: HookSystemType;
+    /** Whether the provider's hook system is experimental. */
+    experimental: boolean;
+    /** Number of canonical events this provider supports. */
+    supportedCount: number;
+    /** Total number of canonical events in the taxonomy. */
+    totalCanonical: number;
+    /** List of canonical events this provider supports. */
+    supported: CanonicalHookEvent[];
+    /** List of canonical events this provider does not support. */
+    unsupported: CanonicalHookEvent[];
+    /** Native events unique to this provider with no canonical mapping. */
+    providerOnly: string[];
+    /** Percentage of canonical events supported (0-100). */
+    coverage: number;
+}
+/**
+ * Cross-provider hook support matrix comparing multiple providers.
+ *
+ * @remarks
+ * Built by `buildHookMatrix()`. Provides a two-dimensional view of which
+ * canonical events are supported by which providers, with native name
+ * translations. Used to render comparison tables in the CLI.
+ *
+ * @public
+ */
+interface CrossProviderMatrix {
+    /** The canonical events included in this matrix (rows). */
+    events: CanonicalHookEvent[];
+    /** The provider IDs included in this matrix (columns). */
+    providers: string[];
+    /** Nested record mapping each canonical event to each provider's hook mapping. */
+    matrix: Record<CanonicalHookEvent, Record<string, HookMapping>>;
+}
+/**
+ * Schema for the `providers/hook-mappings.json` data file.
+ *
+ * @remarks
+ * This interface represents the top-level structure of the hook mappings
+ * JSON file that serves as the single source of truth for all provider
+ * hook configurations. It is loaded and cached by the normalizer module.
+ *
+ * @public
+ */
+interface HookMappingsFile {
+    /** Semver version string of the hook mappings schema. */
+    version: string;
+    /** ISO 8601 date string of the last update to mappings data. */
+    lastUpdated: string;
+    /** Human-readable description of the mappings file purpose. */
+    description: string;
+    /** Definitions for every canonical event in the taxonomy. */
+    canonicalEvents: Record<CanonicalHookEvent, CanonicalEventDefinition>;
+    /** Hook profiles keyed by provider ID. */
+    providerMappings: Record<string, ProviderHookProfile>;
+}
+/** Registry evidence for project-local delivery; native trust is independent. */
+interface ProviderProjectHookCapability {
+    /** Native command timeout units, when documented for project delivery. */
+    timeoutUnit?: 'seconds' | 'milliseconds';
+    /** Safe project-relative config destination, null when unsupported. */
+    configPath: string | null;
+    /** Documentation-reviewed versions, not live certifications. */
+    documentedVersions: string[];
+    /** Versions whose actual harness invocation was verified. */
+    verifiedVersions: string[];
+    /** Official evidence source. */
+    documentation: string;
+    /** Registry review date. */
+    reviewedAt: string;
+    /** Installation never grants native hook or project trust. */
+    trust: 'native-unverified';
+}
+
+/**
+ * All hook event categories (8 total).
+ * @public
+ */
+declare const HOOK_CATEGORIES: readonly ["agent", "context", "memory", "pipeline", "prompt", "session", "task", "tool"];
+/** Union type of valid hook category strings. */
+type HookCategory = (typeof HOOK_CATEGORIES)[number];
+/**
+ * All canonical hook events (31 total: 16 provider, 15 domain).
+ *
+ * This replaces the previously hardcoded tuple in types.ts.
+ * Single source of truth: providers/hook-mappings.json
+ * @public
+ */
+declare const CANONICAL_HOOK_EVENTS: readonly ["ConfigChange", "Notification", "PermissionRequest", "PostCompact", "PostModel", "PostToolUse", "PostToolUseFailure", "PreCompact", "PreModel", "PreToolUse", "PromptSubmit", "ResponseComplete", "SessionEnd", "SessionStart", "SubagentStart", "SubagentStop", "ApprovalExpired", "ApprovalGranted", "ApprovalRequested", "MemoryDecisionStored", "MemoryLearningStored", "MemoryObserved", "MemoryPatternStored", "PipelineManifestAppended", "PipelineStageCompleted", "SessionEnded", "SessionStarted", "TaskBlocked", "TaskCompleted", "TaskCreated", "TaskStarted"];
+/** Union type of all canonical hook event names. */
+type CanonicalHookEvent = (typeof CANONICAL_HOOK_EVENTS)[number];
+/** Complete fallback profiles generated from the registry. */
+declare const GENERATED_PROVIDER_HOOK_PROFILES: Record<string, ProviderHookProfile>;
+/** Provider native-to-canonical maps generated from the same registry. */
+declare const PROVIDER_NATIVE_EVENT_MAPS: Record<string, Record<string, string>>;
+
+/**
+ * CAAMP Hooks Normalizer
+ *
+ * Translates between CAAMP canonical hook events and provider-native
+ * event names. Provides query functions for hook support, cross-provider
+ * comparison, and event normalization.
+ *
+ * This module follows the same pattern as `src/core/mcp/transforms.ts` —
+ * a translation layer that lets consumers use one canonical interface
+ * while CAAMP handles provider-specific differences.
+ */
+
+/**
+ * Reset the cached hook mappings data.
+ *
+ * @remarks
+ * Clears the in-memory cache so the next query function call will
+ * re-read `providers/hook-mappings.json` from disk. This is primarily
+ * intended for test isolation — production code should not need to call this.
+ *
+ * @example
+ * ```typescript
+ * import { resetHookMappings, getHookMappingsVersion } from "./normalizer.js";
+ *
+ * // Force a fresh load from disk
+ * resetHookMappings();
+ * const version = getHookMappingsVersion();
+ * ```
+ *
+ * @public
+ */
+declare function resetHookMappings(): void;
+/**
+ * Get the canonical event definition (category, description, canBlock).
+ *
+ * @remarks
+ * Looks up the definition from the hook mappings data file. The returned
+ * object contains the event's category, human-readable description, and
+ * whether handlers can block the associated action.
+ *
+ * @param event - The canonical event name to look up.
+ * @returns The event definition containing category, description, and canBlock flag.
+ *
+ * @example
+ * ```typescript
+ * import { getCanonicalEvent } from "./normalizer.js";
+ *
+ * const def = getCanonicalEvent("PreToolUse");
+ * console.log(def.category);  // "tool"
+ * console.log(def.canBlock);  // true
+ * ```
+ *
+ * @public
+ */
+declare function getCanonicalEvent(event: CanonicalHookEvent): CanonicalEventDefinition;
+/**
+ * Get all canonical event definitions.
+ *
+ * @remarks
+ * Returns the complete map of canonical event names to their definitions.
+ * Useful for iterating over the full taxonomy or building UI displays
+ * of all available events.
+ *
+ * @returns A record mapping every canonical event name to its definition.
+ *
+ * @example
+ * ```typescript
+ * import { getAllCanonicalEvents } from "./normalizer.js";
+ *
+ * const events = getAllCanonicalEvents();
+ * for (const [name, def] of Object.entries(events)) {
+ *   console.log(`${name}: ${def.description}`);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function getAllCanonicalEvents(): Record<CanonicalHookEvent, CanonicalEventDefinition>;
+/**
+ * Get canonical events filtered by category.
+ *
+ * @remarks
+ * Filters the canonical event list to only those belonging to the specified
+ * category. Useful for displaying events grouped by lifecycle phase
+ * (e.g. all `"tool"` events or all `"session"` events).
+ *
+ * @param category - The hook category to filter by (e.g. `"session"`, `"tool"`).
+ * @returns Array of canonical event names that belong to the specified category.
+ *
+ * @example
+ * ```typescript
+ * import { getCanonicalEventsByCategory } from "./normalizer.js";
+ *
+ * const toolEvents = getCanonicalEventsByCategory("tool");
+ * // ["PreToolUse", "PostToolUse", "PostToolUseFailure"]
+ * ```
+ *
+ * @public
+ */
+declare function getCanonicalEventsByCategory(category: HookCategory): CanonicalHookEvent[];
+/**
+ * Get the full hook profile for a provider.
+ *
+ * @remarks
+ * Returns the complete hook configuration for a provider including its
+ * hook system type, config path, handler types, and all event mappings.
+ * Returns `undefined` if the provider has no hook mappings defined.
+ *
+ * @param providerId - The provider identifier (e.g. `"claude-code"`, `"gemini-cli"`).
+ * @returns The provider's hook profile, or `undefined` if not found.
+ *
+ * @example
+ * ```typescript
+ * import { getProviderHookProfile } from "./normalizer.js";
+ *
+ * const profile = getProviderHookProfile("claude-code");
+ * if (profile) {
+ *   console.log(profile.hookSystem); // "config"
+ *   console.log(profile.experimental); // false
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function getProviderHookProfile(providerId: string): ProviderHookProfile | undefined;
+/**
+ * Get all provider IDs that have hook mappings.
+ *
+ * @remarks
+ * Returns the list of provider identifiers present in the hook mappings
+ * data file. This reflects all providers for which CAAMP has hook
+ * translation data, regardless of whether they support any events.
+ *
+ * @returns Array of provider ID strings.
+ *
+ * @example
+ * ```typescript
+ * import { getMappedProviderIds } from "./normalizer.js";
+ *
+ * const ids = getMappedProviderIds();
+ * // ["claude-code", "gemini-cli", "cursor", "kimi", ...]
+ * ```
+ *
+ * @public
+ */
+declare function getMappedProviderIds(): string[];
+/**
+ * Translate a CAAMP canonical event name to the provider's native name.
+ *
+ * @remarks
+ * This is the primary forward-translation function. Given a canonical
+ * event and a provider ID, it returns the provider-specific event name
+ * that should be used when configuring hooks for that provider.
+ * Returns `null` if the provider is unknown or does not support the event.
+ *
+ * @param canonical - The CAAMP canonical event name to translate.
+ * @param providerId - The target provider identifier.
+ * @returns The native event name, or `null` if unsupported.
+ *
+ * @example
+ * ```typescript
+ * import { toNative } from "./normalizer.js";
+ *
+ * toNative("PreToolUse", "claude-code");   // "PreToolUse"
+ * toNative("PreToolUse", "gemini-cli");    // "BeforeTool"
+ * toNative("PreToolUse", "cursor");        // "preToolUse"
+ * toNative("PreToolUse", "kimi");          // null
+ * ```
+ *
+ * @public
+ */
+declare function toNative(canonical: CanonicalHookEvent, providerId: string): string | null;
+/**
+ * Translate a provider-native event name to the CAAMP canonical name.
+ *
+ * @remarks
+ * This is the reverse-translation function. Scans all event mappings
+ * for the given provider to find a canonical match for the native name.
+ * Returns `null` if no mapping is found or the provider is unknown.
+ *
+ * @param nativeName - The provider-native event name to look up.
+ * @param providerId - The provider identifier to search within.
+ * @returns The canonical event name, or `null` if no mapping exists.
+ *
+ * @example
+ * ```typescript
+ * import { toCanonical } from "./normalizer.js";
+ *
+ * toCanonical("BeforeTool", "gemini-cli");     // "PreToolUse"
+ * toCanonical("stop", "cursor");               // "ResponseComplete"
+ * toCanonical("UserPromptSubmit", "claude-code"); // "PromptSubmit"
+ * ```
+ *
+ * @public
+ */
+declare function toCanonical(nativeName: string, providerId: string): CanonicalHookEvent | null;
+/**
+ * Batch-translate multiple canonical events to native names for a provider.
+ *
+ * @remarks
+ * Translates an array of canonical events in a single call, returning
+ * only the events that the provider actually supports. Each result
+ * includes category and blocking metadata. Unsupported events are
+ * silently excluded from the output.
+ *
+ * @param canonicals - Array of canonical event names to translate.
+ * @param providerId - The target provider identifier.
+ * @returns Array of normalized events (only supported ones included).
+ *
+ * @example
+ * ```typescript
+ * import { toNativeBatch } from "./normalizer.js";
+ *
+ * const events = toNativeBatch(
+ *   ["PreToolUse", "PostToolUse", "ConfigChange"],
+ *   "claude-code",
+ * );
+ * // Returns NormalizedHookEvent[] for supported events only
+ * ```
+ *
+ * @public
+ */
+declare function toNativeBatch(canonicals: CanonicalHookEvent[], providerId: string): NormalizedHookEvent[];
+/**
+ * Check if a provider supports a specific canonical hook event.
+ *
+ * @remarks
+ * A quick boolean check that avoids returning the full mapping details.
+ * Returns `false` if the provider is unknown or the event is not supported.
+ *
+ * @param canonical - The canonical event name to check.
+ * @param providerId - The provider identifier to check against.
+ * @returns `true` if the provider supports this canonical event, `false` otherwise.
+ *
+ * @example
+ * ```typescript
+ * import { supportsHook } from "./normalizer.js";
+ *
+ * supportsHook("PreToolUse", "claude-code"); // true
+ * supportsHook("PreToolUse", "kimi");        // false
+ * ```
+ *
+ * @public
+ */
+declare function supportsHook(canonical: CanonicalHookEvent, providerId: string): boolean;
+/**
+ * Get full hook support details for a canonical event on a provider.
+ *
+ * @remarks
+ * Returns a structured result with the native name translation and any
+ * notes about support limitations. Unlike `supportsHook()`, this always
+ * returns a result object even when the provider is unknown (with
+ * `supported: false`).
+ *
+ * @param canonical - The canonical event name to query.
+ * @param providerId - The provider identifier to query against.
+ * @returns Support result including native name and optional notes.
+ *
+ * @example
+ * ```typescript
+ * import { getHookSupport } from "./normalizer.js";
+ *
+ * const result = getHookSupport("PreToolUse", "claude-code");
+ * console.log(result.supported); // true
+ * console.log(result.native);    // "PreToolUse"
+ * ```
+ *
+ * @public
+ */
+declare function getHookSupport(canonical: CanonicalHookEvent, providerId: string): HookSupportResult;
+/**
+ * Get all supported canonical events for a provider.
+ *
+ * @remarks
+ * Filters the full canonical event list to only those that the provider
+ * supports. Returns an empty array if the provider is unknown.
+ *
+ * @param providerId - The provider identifier to query.
+ * @returns Array of canonical event names the provider supports.
+ *
+ * @example
+ * ```typescript
+ * import { getSupportedEvents } from "./normalizer.js";
+ *
+ * const events = getSupportedEvents("claude-code");
+ * // ["SessionStart", "SessionEnd", "PreToolUse", ...]
+ * ```
+ *
+ * @public
+ */
+declare function getSupportedEvents(providerId: string): CanonicalHookEvent[];
+/**
+ * Get all unsupported canonical events for a provider.
+ *
+ * @remarks
+ * Returns the complement of `getSupportedEvents()`. If the provider is
+ * unknown, all canonical events are returned since none are supported.
+ *
+ * @param providerId - The provider identifier to query.
+ * @returns Array of canonical event names the provider does not support.
+ *
+ * @example
+ * ```typescript
+ * import { getUnsupportedEvents } from "./normalizer.js";
+ *
+ * const missing = getUnsupportedEvents("kimi");
+ * // Returns all canonical events (kimi has no hook support)
+ * ```
+ *
+ * @public
+ */
+declare function getUnsupportedEvents(providerId: string): CanonicalHookEvent[];
+/**
+ * Get providers that support a specific canonical event.
+ *
+ * @remarks
+ * Scans all provider mappings and returns the IDs of those that support
+ * the given canonical event. Useful for determining which providers can
+ * be targeted when configuring a specific hook.
+ *
+ * @param canonical - The canonical event name to search for.
+ * @returns Array of provider IDs that support this event.
+ *
+ * @example
+ * ```typescript
+ * import { getProvidersForEvent } from "./normalizer.js";
+ *
+ * const providers = getProvidersForEvent("PreToolUse");
+ * // ["claude-code", "gemini-cli", "cursor"]
+ * ```
+ *
+ * @public
+ */
+declare function getProvidersForEvent(canonical: CanonicalHookEvent): string[];
+/**
+ * Get canonical events common to all specified providers.
+ *
+ * @remarks
+ * Computes the intersection of supported events across multiple providers.
+ * Returns only events that every listed provider supports. Useful for
+ * determining which hooks can be configured uniformly across a set of
+ * target providers.
+ *
+ * @param providerIds - Array of provider IDs to intersect.
+ * @returns Array of canonical events supported by all specified providers.
+ *
+ * @example
+ * ```typescript
+ * import { getCommonEvents } from "./normalizer.js";
+ *
+ * const common = getCommonEvents(["claude-code", "gemini-cli"]);
+ * // Returns only events both providers support
+ * ```
+ *
+ * @public
+ */
+declare function getCommonEvents(providerIds: string[]): CanonicalHookEvent[];
+/**
+ * Get a summary of hook support for a provider.
+ *
+ * @remarks
+ * Builds an aggregated view of a provider's hook capabilities including
+ * counts, coverage percentage, and categorized event lists. Returns
+ * `undefined` if the provider has no hook mappings. Used by the CLI
+ * `hooks show` command for provider overviews.
+ *
+ * @param providerId - The provider identifier to summarize.
+ * @returns The hook support summary, or `undefined` if the provider is not found.
+ *
+ * @example
+ * ```typescript
+ * import { getProviderSummary } from "./normalizer.js";
+ *
+ * const summary = getProviderSummary("claude-code");
+ * if (summary) {
+ *   console.log(`${summary.coverage}% coverage`);
+ *   console.log(`${summary.supportedCount}/${summary.totalCanonical} events`);
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function getProviderSummary(providerId: string): ProviderHookSummary | undefined;
+/**
+ * Build a cross-provider hook support matrix.
+ *
+ * @remarks
+ * Constructs a two-dimensional matrix showing which canonical events are
+ * supported by which providers, with native name translations. When no
+ * provider IDs are specified, all mapped providers are included. Used by
+ * the CLI `hooks matrix` command for comparison tables.
+ *
+ * @param providerIds - Optional array of provider IDs to include. Defaults to all mapped providers.
+ * @returns The cross-provider matrix with events, providers, and mapping data.
+ *
+ * @example
+ * ```typescript
+ * import { buildHookMatrix } from "./normalizer.js";
+ *
+ * const matrix = buildHookMatrix(["claude-code", "gemini-cli"]);
+ * for (const event of matrix.events) {
+ *   for (const provider of matrix.providers) {
+ *     console.log(`${event} @ ${provider}: ${matrix.matrix[event][provider].supported}`);
+ *   }
+ * }
+ * ```
+ *
+ * @public
+ */
+declare function buildHookMatrix(providerIds?: string[]): CrossProviderMatrix;
+/**
+ * Get the hook system type for a provider.
+ *
+ * @remarks
+ * Returns the provider's hook system type: `"config"` for file-based hooks,
+ * `"plugin"` for extension-based hooks, or `"none"` if the provider does
+ * not support hooks. Returns `"none"` for unknown providers.
+ *
+ * @param providerId - The provider identifier to query.
+ * @returns The hook system type (`"config"`, `"plugin"`, or `"none"`).
+ *
+ * @example
+ * ```typescript
+ * import { getHookSystemType } from "./normalizer.js";
+ *
+ * getHookSystemType("claude-code"); // "config"
+ * getHookSystemType("unknown");     // "none"
+ * ```
+ *
+ * @public
+ */
+declare function getHookSystemType(providerId: string): HookSystemType;
+/**
+ * Get the resolved hook config path for a provider.
+ *
+ * @remarks
+ * Resolves the provider's hook configuration file path by expanding
+ * registry template variables (e.g. `~` to the home directory). Returns
+ * `null` if the provider has no hook config path defined or is unknown.
+ *
+ * @param providerId - The provider identifier to query.
+ * @returns The resolved filesystem path, or `null` if not available.
+ *
+ * @example
+ * ```typescript
+ * import { getHookConfigPath } from "./normalizer.js";
+ *
+ * const path = getHookConfigPath("claude-code");
+ * // "/home/user/.claude/settings.json" (resolved from template)
+ * ```
+ *
+ * @public
+ */
+declare function getHookConfigPath(providerId: string): string | null;
+/**
+ * Get provider-only events (native events with no canonical mapping).
+ *
+ * @remarks
+ * Some providers define hook events that have no equivalent in the CAAMP
+ * canonical taxonomy. This function returns those provider-specific event
+ * names. Returns an empty array for unknown providers.
+ *
+ * @param providerId - The provider identifier to query.
+ * @returns Array of native event names unique to this provider.
+ *
+ * @example
+ * ```typescript
+ * import { getProviderOnlyEvents } from "./normalizer.js";
+ *
+ * const extras = getProviderOnlyEvents("claude-code");
+ * // Returns any events specific to Claude Code with no canonical equivalent
+ * ```
+ *
+ * @public
+ */
+declare function getProviderOnlyEvents(providerId: string): string[];
+/**
+ * Translate a canonical event to native names across multiple providers.
+ *
+ * @remarks
+ * Performs a fan-out translation of a single canonical event to all
+ * specified providers simultaneously. The result record only includes
+ * providers that actually support the event — unsupported providers
+ * are silently excluded.
+ *
+ * @param canonical - The canonical event name to translate.
+ * @param providerIds - Array of provider IDs to translate for.
+ * @returns Record mapping provider IDs to their native event names (supported only).
+ *
+ * @example
+ * ```typescript
+ * import { translateToAll } from "./normalizer.js";
+ *
+ * const result = translateToAll("PreToolUse", ["claude-code", "gemini-cli", "kimi"]);
+ * // { "claude-code": "PreToolUse", "gemini-cli": "BeforeTool" }
+ * // (kimi excluded — unsupported)
+ * ```
+ *
+ * @public
+ */
+declare function translateToAll(canonical: CanonicalHookEvent, providerIds: string[]): Record<string, string>;
+/**
+ * Find the best canonical match for a native event name across all providers.
+ *
+ * @remarks
+ * Scans every provider's mappings to find canonical events that match the
+ * given native name. Useful when you have a native name but do not know
+ * which provider it belongs to. Multiple results are possible if different
+ * providers use the same native name for different canonical events.
+ *
+ * @param nativeName - The provider-native event name to resolve.
+ * @returns Array of matches, each containing the provider ID and canonical event name.
+ *
+ * @example
+ * ```typescript
+ * import { resolveNativeEvent } from "./normalizer.js";
+ *
+ * const matches = resolveNativeEvent("BeforeTool");
+ * // [{ providerId: "gemini-cli", canonical: "PreToolUse" }]
+ * ```
+ *
+ * @public
+ */
+declare function resolveNativeEvent(nativeName: string): Array<{
+    providerId: string;
+    canonical: CanonicalHookEvent;
+}>;
+/**
+ * Get the version of the hook mappings data.
+ *
+ * @remarks
+ * Returns the semver version string from the hook mappings JSON file.
+ * This can be used to check compatibility or display the data version
+ * in diagnostic output.
+ *
+ * @returns The semver version string of the loaded hook mappings data.
+ *
+ * @example
+ * ```typescript
+ * import { getHookMappingsVersion } from "./normalizer.js";
+ *
+ * const version = getHookMappingsVersion();
+ * console.log(`Hook mappings v${version}`);
+ * ```
+ *
+ * @public
+ */
+declare function getHookMappingsVersion(): string;
+
+export { CANONICAL_HOOK_EVENTS, type CanonicalEventDefinition, type CanonicalHookEvent, type CrossProviderMatrix, GENERATED_PROVIDER_HOOK_PROFILES, HOOK_CATEGORIES, type HookCategory, type HookHandlerType, type HookMapping, type HookMappingsFile, type HookSupportResult, type HookSystemType, type NormalizedHookEvent, PROVIDER_NATIVE_EVENT_MAPS, type ProviderHookProfile, type ProviderHookSummary, type ProviderProjectHookCapability, buildHookMatrix, getAllCanonicalEvents, getCanonicalEvent, getCanonicalEventsByCategory, getCommonEvents, getHookConfigPath, getHookMappingsVersion, getHookSupport, getHookSystemType, getMappedProviderIds, getProviderHookProfile, getProviderOnlyEvents, getProviderSummary, getProvidersForEvent, getSupportedEvents, getUnsupportedEvents, resetHookMappings, resolveNativeEvent, supportsHook, toCanonical, toNative, toNativeBatch, translateToAll };