intentdna 1.6.4 → 1.7.0

package/dist/compiler/diagnostics.js

@@ -0,0 +1,30 @@
+export class DNADiagnosticsError extends Error {
+    diagnostics;
+    constructor(message, diagnostics) {
+        super(message);
+        this.name = "DNADiagnosticsError";
+        this.diagnostics = diagnostics;
+    }
+}
+export function hasDiagnosticErrors(diagnostics) {
+    return diagnostics.some((diagnostic) => diagnostic.severity === "error");
+}
+export function formatDiagnostic(diagnostic) {
+    const location = [diagnostic.file, diagnostic.path].filter(Boolean).join(":");
+    const prefix = location ? `${location}: ` : "";
+    const hint = diagnostic.hint ? ` (${diagnostic.hint})` : "";
+    return `${diagnostic.severity.toUpperCase()} ${diagnostic.code}: ${prefix}${diagnostic.message}${hint}`;
+}
+export function formatDiagnostics(diagnostics) {
+    return diagnostics.map(formatDiagnostic).join("\n");
+}
+export function diagnosticsFromError(error, file) {
+    if (error instanceof DNADiagnosticsError)
+        return error.diagnostics;
+    return [{
+            severity: "error",
+            code: "unexpected_error",
+            message: error instanceof Error ? error.message : String(error),
+            file,
+        }];
+}

package/dist/compiler/index.d.ts

@@ -10,6 +10,9 @@ export { activateDNA } from "./activate.js";
 export { compileDNA } from "./compile.js";
 export { compileWorkflow } from "./workflow.js";
 export type { CompileWorkflowOptions, CompileWorkflowResult, CompileWorkflowError, } from "./workflow.js";
+export type { Diagnostic, DiagnosticSeverity } from "./diagnostics.js";
+export { DNADiagnosticsError, formatDiagnostic, formatDiagnostics } from "./diagnostics.js";
+export { assertNoNamespaceCollisions, checkNamespaceCollisions, detectDNAConfigs, expandDNAInputFiles, loadDNAWithDiagnostics, resolveDNAInputs, resolveSpeciesReference, } from "./input-resolver.js";
 /**
  * Load and parse a DNA file from disk.
  */

package/dist/compiler/index.js

@@ -4,29 +4,26 @@
  * Full compilation pipeline:
  *   DNA files → parse → cascade → activate (+ epigenetic) → compile → IR
  */
-import { readFile } from "node:fs/promises";
-import { validateDNA } from "../schema/validate.js";
-import { parseYAML } from "../schema/yaml-parser.js";
 import { cascadeDNA } from "./cascade.js";
 import { activateDNA } from "./activate.js";
 import { compileDNA } from "./compile.js";
+import { DNADiagnosticsError, formatDiagnostics } from "./diagnostics.js";
+import { loadDNAWithDiagnostics } from "./input-resolver.js";
 export { cascadeDNA } from "./cascade.js";
 export { activateDNA } from "./activate.js";
 export { compileDNA } from "./compile.js";
 export { compileWorkflow } from "./workflow.js";
+export { DNADiagnosticsError, formatDiagnostic, formatDiagnostics } from "./diagnostics.js";
+export { assertNoNamespaceCollisions, checkNamespaceCollisions, detectDNAConfigs, expandDNAInputFiles, loadDNAWithDiagnostics, resolveDNAInputs, resolveSpeciesReference, } from "./input-resolver.js";
 /**
  * Load and parse a DNA file from disk.
  */
 export async function loadDNA(filePath) {
-    const raw = await readFile(filePath, "utf-8");
-    const isYAML = filePath.endsWith(".yaml") || filePath.endsWith(".yml");
-    const dna = (isYAML ? parseYAML(raw) : JSON.parse(raw));
-    const result = validateDNA(dna);
-    if (!result.valid) {
-        const messages = result.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n");
-        throw new Error(`Invalid DNA file ${filePath}:\n${messages}`);
+    const result = await loadDNAWithDiagnostics(filePath);
+    if (!result.dna) {
+        throw new DNADiagnosticsError(`Invalid DNA file ${filePath}:\n${formatDiagnostics(result.diagnostics)}`, result.diagnostics);
     }
-    return dna;
+    return result.dna;
 }
 /**
  * Full compilation pipeline: load DNA files, cascade, activate context, compile to IR.

package/dist/compiler/input-resolver.d.ts

@@ -0,0 +1,25 @@
+import type { IntentDNA } from "../schema/types.js";
+import type { Diagnostic } from "./diagnostics.js";
+export interface ResolveDNAInputOptions {
+    cwd?: string;
+    includeDiagnostics?: boolean;
+}
+export interface ResolvedDNAInputs {
+    files: string[];
+    dnas: IntentDNA[];
+    diagnostics: Diagnostic[];
+}
+export declare function parseDNAFile(filePath: string): Promise<IntentDNA>;
+export declare function resolveSpeciesReference(ref: string): string | null;
+export declare function detectDNAConfigs(projectDir?: string): Promise<string[]>;
+export interface ExpandDNAInputOptions {
+    cwd?: string;
+}
+export declare function expandDNAInputFiles(files: string[], options?: ExpandDNAInputOptions): Promise<string[]>;
+export declare function checkNamespaceCollisions(configPaths: string[]): Promise<Diagnostic[]>;
+export declare function assertNoNamespaceCollisions(configPaths: string[]): Promise<void>;
+export declare function loadDNAWithDiagnostics(filePath: string): Promise<{
+    dna?: IntentDNA;
+    diagnostics: Diagnostic[];
+}>;
+export declare function resolveDNAInputs(files: string[], options?: ResolveDNAInputOptions): Promise<ResolvedDNAInputs>;

package/dist/compiler/input-resolver.js

@@ -0,0 +1,175 @@
+import { readdir, readFile, stat } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { validateDNA } from "../schema/validate.js";
+import { parseYAML } from "../schema/yaml-parser.js";
+import { DNADiagnosticsError, hasDiagnosticErrors } from "./diagnostics.js";
+const DNA_CONFIG_CANDIDATES = [
+    ".dna/config.yaml",
+    ".dna/config.yml",
+    ".dna/config.json",
+    ".dna.yaml",
+    ".dna.yml",
+    ".dna.json",
+];
+async function fileExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parseDNAContent(filePath, raw) {
+    const isYAML = filePath.endsWith(".yaml") || filePath.endsWith(".yml");
+    return (isYAML ? parseYAML(raw) : JSON.parse(raw));
+}
+export async function parseDNAFile(filePath) {
+    const raw = await readFile(filePath, "utf-8");
+    return parseDNAContent(filePath, raw);
+}
+export function resolveSpeciesReference(ref) {
+    if (!ref.startsWith("species:"))
+        return null;
+    const name = ref.slice("species:".length);
+    const thisDir = dirname(fileURLToPath(import.meta.url));
+    return resolve(thisDir, "..", "species", `${name}.dna.json`);
+}
+export async function detectDNAConfigs(projectDir = process.cwd()) {
+    const configsDir = resolve(projectDir, ".dna", "configs");
+    try {
+        const files = await readdir(configsDir);
+        const configs = files
+            .filter((file) => file.endsWith(".yaml") || file.endsWith(".yml"))
+            .sort()
+            .map((file) => resolve(configsDir, file));
+        if (configs.length > 0)
+            return configs;
+    }
+    catch {
+        // Directory does not exist.
+    }
+    for (const candidate of DNA_CONFIG_CANDIDATES) {
+        const path = resolve(projectDir, candidate);
+        if (await fileExists(path))
+            return [path];
+    }
+    return [];
+}
+export async function expandDNAInputFiles(files, options) {
+    const cwd = options?.cwd ?? process.cwd();
+    const expanded = [];
+    const seen = new Set();
+    const add = (path, position) => {
+        if (seen.has(path))
+            return;
+        seen.add(path);
+        if (position === "front")
+            expanded.unshift(path);
+        else
+            expanded.push(path);
+    };
+    for (const file of files) {
+        const abs = resolve(cwd, file);
+        add(abs, "back");
+        try {
+            const dna = await parseDNAFile(abs);
+            for (const ref of dna.cascade?.inherits ?? []) {
+                const speciesPath = resolveSpeciesReference(ref);
+                if (speciesPath)
+                    add(speciesPath, "front");
+            }
+        }
+        catch {
+            // Validation/loading reports the concrete parse error later.
+        }
+    }
+    return expanded;
+}
+export async function checkNamespaceCollisions(configPaths) {
+    const diagnostics = [];
+    const namespaces = new Map();
+    for (const configPath of configPaths) {
+        try {
+            const data = await parseDNAFile(configPath);
+            const namespace = typeof data.namespace === "string" ? data.namespace : undefined;
+            if (!namespace)
+                continue;
+            const previous = namespaces.get(namespace);
+            if (previous) {
+                diagnostics.push({
+                    severity: "error",
+                    code: "namespace_conflict",
+                    message: `Namespace "${namespace}" conflict: ${previous} and ${configPath}. Each template must have a unique namespace.`,
+                    file: configPath,
+                });
+            }
+            else {
+                namespaces.set(namespace, configPath);
+            }
+        }
+        catch {
+            // Parse/validation errors are reported by the load step.
+        }
+    }
+    return diagnostics;
+}
+export async function assertNoNamespaceCollisions(configPaths) {
+    const diagnostics = await checkNamespaceCollisions(configPaths);
+    if (diagnostics.length > 0) {
+        throw new DNADiagnosticsError(diagnostics[0].message, diagnostics);
+    }
+}
+export async function loadDNAWithDiagnostics(filePath) {
+    const diagnostics = [];
+    try {
+        const dna = await parseDNAFile(filePath);
+        const result = validateDNA(dna);
+        for (const warning of result.warnings ?? []) {
+            diagnostics.push({
+                severity: "warning",
+                code: "schema_warning",
+                message: warning.message,
+                file: filePath,
+                path: warning.path,
+            });
+        }
+        for (const error of result.errors) {
+            diagnostics.push({
+                severity: "error",
+                code: "schema_error",
+                message: error.message,
+                file: filePath,
+                path: error.path,
+            });
+        }
+        return { dna: result.valid ? dna : undefined, diagnostics };
+    }
+    catch (error) {
+        diagnostics.push({
+            severity: "error",
+            code: "parse_error",
+            message: error instanceof Error ? error.message : String(error),
+            file: filePath,
+        });
+        return { diagnostics };
+    }
+}
+export async function resolveDNAInputs(files, options) {
+    const cwd = options?.cwd ?? process.cwd();
+    const inputFiles = files.length > 0 ? files : await detectDNAConfigs(cwd);
+    const expandedFiles = await expandDNAInputFiles(inputFiles, { cwd });
+    const diagnostics = await checkNamespaceCollisions(expandedFiles);
+    const dnas = [];
+    for (const file of expandedFiles) {
+        const result = await loadDNAWithDiagnostics(file);
+        diagnostics.push(...result.diagnostics);
+        if (result.dna)
+            dnas.push(result.dna);
+    }
+    if (hasDiagnosticErrors(diagnostics)) {
+        throw new DNADiagnosticsError("DNA input resolution failed", diagnostics);
+    }
+    return { files: expandedFiles, dnas, diagnostics };
+}

package/dist/hooks/cli.d.ts

@@ -14,7 +14,7 @@
  *
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
-import type { ArtifactFact, ConstraintIR, VerifierSpec } from "../schema/types.js";
+import type { ArtifactFact, ConstraintIR, RoleDef, VerifierSpec } from "../schema/types.js";
 import type { HookEvent, HookOutput } from "./protocol.js";
 import { blockOutput } from "./protocol.js";
 import { readWorkflowState } from "./state.js";
@@ -39,6 +39,15 @@ export declare function computeSummary(traces: Array<{
     reason?: string;
 }>): SessionSummary;
 export declare function formatSummary(s: SessionSummary): string | null;
+export interface RunHookEventOptions {
+    event: HookEvent;
+    ir: ConstraintIR;
+    rawInput: Record<string, unknown>;
+    projectDir: string;
+    sessionId?: string;
+    roles?: Record<string, RoleDef>;
+}
+export declare function runHookEvent(options: RunHookEventOptions): Promise<HookOutput>;
 declare function recordProducedArtifacts(projectDir: string, ir: ConstraintIR, wfState: {
     workflow: string;
     current_step: string;

package/dist/hooks/cli.js

@@ -15,20 +15,20 @@
  * Fail-open: all errors → { continue: true, suppressOutput: true }
  */
 import { mkdir, readFile, realpath, stat, unlink, writeFile } from "node:fs/promises";
+import { realpathSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { randomUUID } from "node:crypto";
+import { fileURLToPath } from "node:url";
 import { readStdin, writeOutput, silentOutput, allowOutput, blockOutput, stopOutput } from "./protocol.js";
 import { validateHookInput } from "./schema.js";
 import { enforcePreToolUse, enforcePostToolUse, enforceUserPromptSubmit, enforceSubagentStop, enforcePreCompact, enforceNotification, enforceSessionStart, enforceStop, extractBashWritePaths, checkReflectionLimit, checkContextReadiness, checkWorkflowBoundary, } from "./enforce.js";
 import { appendAudit, readWorkflowState, appendTrace, rotateTraces, readTraces, cleanStaleState, readSurgeonAttempts, writeSurgeonAttempts, appendSessionRead, readSessionReads, appendVerifierResult, appendCompletedArtifact, artifactIdentity, buildArtifactKey, readArtifactManifest, resolveArtifactTemplate, safePathComponent, writeArtifactManifest } from "./state.js";
+import { hookEventsForSurface } from "./event-registry.js";
 import { writeAuditEvent } from "../audit/index.js";
 // ── Constants ──────────────────────────────────────────────
 const DEFAULT_IR_PATH = ".dna/compiled/ir.json";
-const VALID_EVENTS = new Set([
-    "PreToolUse", "PostToolUse", "UserPromptSubmit",
-    "SubagentStop", "PreCompact", "Notification", "Stop", "SessionStart",
-]);
+const VALID_EVENTS = new Set(hookEventsForSurface("cli"));
 export function computeSummary(traces) {
     let blocks = 0, warns = 0;
     const toolCounts = new Map();
@@ -103,14 +103,18 @@ async function main() {
         writeOutput(silentOutput());
         return;
     }
+    const output = await runHookEvent({ event, ir, rawInput, projectDir, sessionId });
+    writeOutput(output);
+}
+export async function runHookEvent(options) {
+    const { event, ir, rawInput, projectDir, sessionId, roles } = options;
     const state = {};
     let wfStateRaw = null;
     // Load workflow state for events that need it (handoff context + PreCompact preservation)
     if (event === "PreToolUse" || event === "PostToolUse" || event === "PreCompact") {
         const workflowState = await readWorkflowStateForHook(projectDir, event, sessionId);
         if ("output" in workflowState) {
-            writeOutput(workflowState.output);
-            return;
+            return workflowState.output;
         }
         wfStateRaw = workflowState.state;
         if (wfStateRaw && wfStateRaw.active) {
@@ -123,9 +127,8 @@ async function main() {
             };
             const artifactFacts = await resolveWorkflowArtifactFactsForHook(projectDir, ir, wfStateRaw, event, sessionId);
             if ("output" in artifactFacts) {
-                writeOutput(artifactFacts.output);
                 appendArtifactResolverTrace(projectDir, event, wfStateRaw, artifactFacts.output, sessionId);
-                return;
+                return artifactFacts.output;
             }
             state.artifactFacts = artifactFacts.facts;
         }
@@ -141,7 +144,6 @@ async function main() {
     if (event === "PreToolUse") {
         const gateResult = await handlePreToolGates(ir, rawInput, wfStateRaw, projectDir, sessionId);
         if (gateResult) {
-            writeOutput(gateResult.output);
             appendTrace(projectDir, {
                 trace_id: randomUUID(),
                 event,
@@ -154,24 +156,22 @@ async function main() {
                 duration_ms: 0,
                 timestamp: new Date().toISOString(),
             }, sessionId).catch(() => { });
-            return;
+            return gateResult.output;
         }
     }
     // Special handling for Stop — needs async workflow state read + session summary
     if (event === "Stop") {
         const workflowState = await readWorkflowStateForHook(projectDir, event, sessionId);
         if ("output" in workflowState) {
-            writeOutput(workflowState.output);
-            return;
+            return workflowState.output;
         }
         const wfState = workflowState.state;
         let stopArtifactFacts = [];
         if (wfState?.active) {
             const artifactFacts = await finalizeAndResolveArtifactsForHook(projectDir, ir, wfState, event, sessionId);
             if ("output" in artifactFacts) {
-                writeOutput(artifactFacts.output);
                 appendArtifactResolverTrace(projectDir, event, wfState, artifactFacts.output, sessionId);
-                return;
+                return artifactFacts.output;
             }
             stopArtifactFacts = artifactFacts.facts;
         }
@@ -219,7 +219,6 @@ async function main() {
             }
         }
         catch { /* fail-open */ }
-        writeOutput(stopOutput);
         // Trace for Stop
         appendTrace(projectDir, {
             trace_id: randomUUID(),
@@ -230,11 +229,11 @@ async function main() {
             duration_ms: 0,
             timestamp: new Date().toISOString(),
         }, sessionId).catch(() => { });
-        return;
+        return stopOutput;
     }
     // Dispatch to enforcement engine with timing
     const start = Date.now();
-    let result = dispatch(event, ir, rawInput, state);
+    let result = dispatch(event, ir, rawInput, state, roles);
     let output = result?.output ?? silentOutput();
     const durationMs = Date.now() - start;
     // PostToolUse side effects: session read tracking + surgeon reflection gate.
@@ -306,7 +305,6 @@ async function main() {
         }
         catch { /* fail-open: pattern detection never blocks */ }
     }
-    writeOutput(output);
     // Trace logging (async, fail-open)
     const decision = output.continue === false ? "block"
         : output.hookSpecificOutput?.additionalContext?.startsWith("WARN") ? "warn"
@@ -341,9 +339,10 @@ async function main() {
             session_id: sessionId,
         }).catch(() => { }); // Fail-open
     }
+    return output;
 }
 // ── Dispatch ───────────────────────────────────────────────
-function dispatch(event, ir, input, state) {
+function dispatch(event, ir, input, state, roles) {
     switch (event) {
         case "PreToolUse":
             return enforcePreToolUse(ir, {
@@ -353,7 +352,7 @@ function dispatch(event, ir, input, state) {
                 cwd: typeof input.cwd === "string" ? input.cwd : undefined,
                 sessionId: typeof input.session_id === "string" ? input.session_id
                     : typeof input.sessionId === "string" ? input.sessionId : undefined,
-            }, state);
+            }, state, roles);
         case "PostToolUse":
             return enforcePostToolUse(ir, {
                 tool_name: String(input.tool_name ?? ""),
@@ -576,7 +575,7 @@ async function finalizeAndResolveArtifacts(projectDir, ir, wfState, sessionId) {
 }
 function artifactResolverErrorOutput(event, error) {
     const detail = error instanceof Error ? error.message : String(error);
-    return blockOutput(`[Intent DNA] ${event} artifact resolver failed: ${detail}`);
+    return blockOutput(`[Intent DNA] ${event} artifact resolver failed: ${detail}. Fix the workflow/session identifiers in DNA state, then rerun the hook or \`dna sync\`.`);
 }
 async function readWorkflowStateForHook(projectDir, event, sessionId) {
     try {
@@ -691,7 +690,8 @@ export function appendStopVerifierWarnings(output, verifierResults, currentStep)
     if (warningVerifierFailures.length === 0)
         return output;
     const warningText = `[Intent DNA] Verifier warnings at step '${currentStep ?? "unknown"}':\n` +
-        warningVerifierFailures.map((result) => `  - ${result.message ?? result.verifier_id}`).join("\n");
+        warningVerifierFailures.map((result) => `  - ${result.message ?? result.verifier_id}`).join("\n") +
+        "\nFix the warning above before relying on this step, or rerun the verifier after repair.";
     return appendOutputText(output, warningText, "Stop");
 }
 function trimEvidence(raw) {
@@ -1523,7 +1523,20 @@ function toKebabCase(s) {
         .toLowerCase();
 }
 // ── Entry Point ────────────────────────────────────────────
-main().catch(() => {
-    // Fail-open: never block Claude Code on unexpected errors
-    writeOutput(silentOutput());
-});
+function isDirectEntryPoint() {
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return realpathSync(entry) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch {
+        return resolve(entry) === resolve(fileURLToPath(import.meta.url));
+    }
+}
+if (isDirectEntryPoint()) {
+    main().catch(() => {
+        // Fail-open: never block Claude Code on unexpected errors
+        writeOutput(silentOutput());
+    });
+}

package/dist/hooks/event-registry.d.ts

@@ -0,0 +1,17 @@
+export declare const HOOK_EVENT_NAMES: readonly ["PreToolUse", "PostToolUse", "UserPromptSubmit", "SubagentStop", "PreCompact", "Notification", "Stop", "SessionStart"];
+export type HookEvent = typeof HOOK_EVENT_NAMES[number];
+export declare const SETTINGS_HOOK_EVENT_KEYS: readonly ["preToolUse", "postToolUse", "userPromptSubmit", "subagentStop", "preCompact", "notification", "stop"];
+export type SettingsHookEventKey = typeof SETTINGS_HOOK_EVENT_KEYS[number];
+export type HookSurface = "protocol" | "cli" | "settings" | "manifest" | "mcp";
+export interface HookEventMetadata {
+    event: HookEvent;
+    settingsKey?: SettingsHookEventKey;
+    manifestTimeout: number;
+    surfaces: Record<HookSurface, boolean>;
+}
+export declare const HOOK_EVENT_REGISTRY: readonly HookEventMetadata[];
+export declare function getHookEventMetadata(event: unknown): HookEventMetadata | undefined;
+export declare function getHookEventBySettingsKey(key: unknown): HookEventMetadata | undefined;
+export declare function hookEventsForSurface(surface: HookSurface): HookEvent[];
+export declare function settingsHookEventKeys(): SettingsHookEventKey[];
+export declare function isHookEventSupportedBySurface(event: unknown, surface: HookSurface): event is HookEvent;

package/dist/hooks/event-registry.js

@@ -0,0 +1,89 @@
+export const HOOK_EVENT_NAMES = [
+    "PreToolUse",
+    "PostToolUse",
+    "UserPromptSubmit",
+    "SubagentStop",
+    "PreCompact",
+    "Notification",
+    "Stop",
+    "SessionStart",
+];
+export const SETTINGS_HOOK_EVENT_KEYS = [
+    "preToolUse",
+    "postToolUse",
+    "userPromptSubmit",
+    "subagentStop",
+    "preCompact",
+    "notification",
+    "stop",
+];
+export const HOOK_EVENT_REGISTRY = [
+    {
+        event: "PreToolUse",
+        settingsKey: "preToolUse",
+        manifestTimeout: 5,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: true },
+    },
+    {
+        event: "PostToolUse",
+        settingsKey: "postToolUse",
+        manifestTimeout: 3,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: true },
+    },
+    {
+        event: "UserPromptSubmit",
+        settingsKey: "userPromptSubmit",
+        manifestTimeout: 5,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: true },
+    },
+    {
+        event: "SubagentStop",
+        settingsKey: "subagentStop",
+        manifestTimeout: 3,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: true },
+    },
+    {
+        event: "PreCompact",
+        settingsKey: "preCompact",
+        manifestTimeout: 3,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: true },
+    },
+    {
+        event: "Notification",
+        settingsKey: "notification",
+        manifestTimeout: 3,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: true },
+    },
+    {
+        event: "Stop",
+        settingsKey: "stop",
+        manifestTimeout: 45,
+        surfaces: { protocol: true, cli: true, settings: true, manifest: true, mcp: false },
+    },
+    {
+        event: "SessionStart",
+        manifestTimeout: 5,
+        surfaces: { protocol: true, cli: true, settings: false, manifest: true, mcp: true },
+    },
+];
+const EVENT_BY_NAME = new Map(HOOK_EVENT_REGISTRY.map((entry) => [entry.event, entry]));
+const EVENT_BY_SETTINGS_KEY = new Map(HOOK_EVENT_REGISTRY.flatMap((entry) => entry.settingsKey ? [[entry.settingsKey, entry]] : []));
+export function getHookEventMetadata(event) {
+    return typeof event === "string" ? EVENT_BY_NAME.get(event) : undefined;
+}
+export function getHookEventBySettingsKey(key) {
+    return typeof key === "string" ? EVENT_BY_SETTINGS_KEY.get(key) : undefined;
+}
+export function hookEventsForSurface(surface) {
+    return HOOK_EVENT_REGISTRY
+        .filter((entry) => entry.surfaces[surface])
+        .map((entry) => entry.event);
+}
+export function settingsHookEventKeys() {
+    return HOOK_EVENT_REGISTRY
+        .filter((entry) => entry.surfaces.settings && entry.settingsKey)
+        .map((entry) => entry.settingsKey);
+}
+export function isHookEventSupportedBySurface(event, surface) {
+    return getHookEventMetadata(event)?.surfaces[surface] === true;
+}

package/dist/hooks/protocol.d.ts

@@ -6,7 +6,7 @@
  *
  * Protocol reference: docs/references/cc-source-analysis.md §2
  */
-export type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "SubagentStop" | "PreCompact" | "Notification" | "Stop" | "SessionStart";
+export type { HookEvent } from "./event-registry.js";
 /** Base fields present in all hook inputs */
 export interface HookInputBase {
     cwd?: string;

package/dist/hooks/schema.js

@@ -3,6 +3,7 @@
  * Zero external dependencies. Hand-written validators.
  * Fail-open: invalid input → log warning + return { valid: false, ... }
  */
+import { isHookEventSupportedBySurface } from "./event-registry.js";
 /**
  * Validate hook input against expected schema for each event type.
  * Returns normalized input (camelCase) on success.
@@ -20,6 +21,9 @@ export function validateHookInput(event, raw) {
         normalized.sessionId = sessionId;
         delete normalized.session_id;
     }
+    if (!isHookEventSupportedBySurface(event, "protocol")) {
+        return { valid: false, errors: [`Unknown event type: ${event}`] };
+    }
     switch (event) {
         case "PreToolUse":
             if (typeof input.tool_name !== "string") {
@@ -58,7 +62,7 @@ export function validateHookInput(event, raw) {
             // Minimal validation — these events have no required fields beyond base
             break;
         default:
-            errors.push(`Unknown event type: ${event}`);
+            break;
     }
     return {
         valid: errors.length === 0,

package/dist/hooks/state.d.ts

@@ -136,6 +136,7 @@ export declare function writeSessionReads(projectDir: string, state: SessionRead
  */
 export declare function appendSessionRead(projectDir: string, filePath: string, sessionId?: string): Promise<void>;
 export interface VerifierResultEntry {
+    result_id?: string;
     verifier_id: string;
     when: VerifierWhen;
     severity: VerifierSeverity;
@@ -151,6 +152,7 @@ export interface VerifierResultEntry {
     message?: string;
     timestamp: string;
 }
+export declare function verifierResultId(result: Omit<VerifierResultEntry, "result_id"> | VerifierResultEntry): string;
 export declare function readVerifierResults(projectDir: string, sessionId?: string): Promise<VerifierResultEntry[]>;
 export declare function writeVerifierResults(projectDir: string, results: VerifierResultEntry[], sessionId?: string): Promise<void>;
 export declare function appendVerifierResult(projectDir: string, result: VerifierResultEntry, sessionId?: string): Promise<void>;