@sema-agent/settings-schema 12.3.0 → 13.0.1

package/dist/hooks-config.js

@@ -0,0 +1,466 @@
+/**
+ * `hooks-config` — the hooks CONFIG surface: what a settings document's `hooks` key may carry (the shape `TaskRequest.settings.hooks`
+ * carries on the wire and the shell reads from settings JSON: `{ [eventName]: [{ matcher?, hooks: [entry, …] }] }`).
+ * Re-exported whole by `./hooks` (and the main barrel) — this file is where the surface is DEFINED, `./hooks` is where it is imported from.
+ *
+ * ONE READER. "Can this document's hooks be loaded, and which pieces must go?" has one answer: {@link classifyHooksConfig}. The zod faces
+ * below ({@link HooksConfig}, {@link HookMatcherEntry}, {@link HookEntry} and the per-type five) are its PROJECTIONS — accepted ⇔ the
+ * classifier says `"loaded"`, the parsed value is what it loaded, each issue is one of its pieces (code + coordinate). There is no second
+ * statement of what a valid hook entry is: the per-type field table {@link HOOK_ENTRY_FIELDS} is read by the classifier at run time and by
+ * the entry TYPES at compile time (they are derived from it).
+ *
+ * GRANULARITY = CC 2.1.296 (`cli296.js:237470`, `Yy` → `on`): four levels of piece — the `hooks` key, an event, a matcher, an entry.
+ *   · Outside the guard events, a bad piece is DROPPED alone (the rest of the document — its `permissions.deny`, its `env` — still applies).
+ *   · The GUARD events are `PreToolUse` and `PermissionRequest` (CC's `SV`): their hooks may be what guards the permissions declared beside
+ *     them, so ANY bad piece in a guard event REJECTS the whole document (nothing in it is applied), except a guard event whose value is
+ *     `null` — that one is dropped (CC: a warning, the key is removed).
+ *   · A GUARD SIGN is an object member keyed by a guard-event name whose value is not null / undefined / `[]`, or a matcher-shaped object
+ *     (`{ matcher?, hooks }` holding a non-empty `hooks` array, or a single entry under `hooks` with `matcher` present or a string `type`) in
+ *     any place other than a matcher's legal place (an element of the array under an event name). String VALUES are not scanned: a value
+ *     that merely spells `PreToolUse` is not a sign. A piece holding a sign is never dropped — dropping it could make a misplaced guard vanish —
+ *     the document is rejected instead, wherever the sign sits: outside `hooks`, under an unknown event, in a non-array event value, in a matcher's
+ *     or an entry's fields (including fields the contract does not know and would otherwise not carry).
+ *   · `field` — ONE LAW for drops and rejections alike: when the bad piece is a matcher or an entry (an object), `field` is the KEY on it that makes it
+ *     bad — a contract field whose value is wrong, or, for a piece rejected because it holds a guard sign, the member that holds the sign (an unknown
+ *     field the contract would strip; a contract field carrying more than its kind, such as `headers` or `input`; `hooks` for an entry that is itself
+ *     matcher-shaped). Absent only when the piece is not an object — and for the pieces above matchers, which have no fields to name. One piece, one
+ *     `field`: the first wrong contract field, or the first sign in document order; a sign on the piece itself decides before a wrong contract field
+ *     of the same piece does (it is why the piece is rejected rather than dropped).
+ *
+ * CC 2.1.296 DIVERGENCES (each in the stricter direction — a document CC would load may be rejected here, never the reverse): listed once,
+ * in `docs/CC-DIVERGENCE.md` (section "hooks classifier", H1–H7) — the whole-subtree guard-sign scan is the first of them.
+ *
+ * COORDINATES are raw {@link ConfigPath} segments (the keys as written). An unknown event name or a key outside `hooks` is user text and may be
+ * anything, a pasted credential included: pass a coordinate through `outgoingPath` before it leaves the process (log, UI, wire). The classifier
+ * echoes no values and writes no sentences — the sentences are the consumers' (same law as `DROPPED_ENTRY_REASON_CODES`).
+ *
+ * SELF-CONTAINED. {@link classifyHooksConfig} and the module-private declarations it uses reference nothing outside themselves except
+ * {@link HOOK_EVENTS} and JavaScript built-ins (no zod): a consumer that copies the function into its own bundle (client-core's generator
+ * does, with the private declarations it uses) copies one closure plus the event vocabulary. The hooks-classify test file (group ⑤) holds this.
+ *
+ * Input is a settings document as parsed from JSON. Values JSON cannot produce (accessors, class instances, cycles) are not part of the
+ * contract; cycles are tolerated, a throwing accessor propagates.
+ */
+import { z } from "zod";
+import { buildQuotedIssue, fixed } from "./quoted-issue.js";
+// ── event vocabulary ───────────────────────────────────────────────────────────────────────────────────────
+// The two halves below are where each word came from (CC 2.1.198's own table, then the later additions) — provenance for the
+// reader of this file, not a contract: they are module-private, and the ONE exported closed set is {@link HOOK_EVENTS}.
+/** CC 2.1.198 full hook-event set (jP array) — 27 events. Order matches the shell's HOOK_EVENTS. */
+const CC_198_HOOK_EVENTS = [
+    "PreToolUse",
+    "PostToolUse",
+    "PostToolUseFailure",
+    "PostToolBatch",
+    "Notification",
+    "UserPromptSubmit",
+    "UserPromptExpansion",
+    "SessionStart",
+    "SessionEnd",
+    "Stop",
+    "StopFailure",
+    "SubagentStart",
+    "SubagentStop",
+    "PreCompact",
+    "PostCompact",
+    "PermissionRequest",
+    "PermissionDenied",
+    "Setup",
+    "TeammateIdle",
+    "TaskCreated",
+    "TaskCompleted",
+    "Elicitation",
+    "ElicitationResult",
+    "ConfigChange",
+    "WorktreeCreate",
+    "WorktreeRemove",
+    "InstructionsLoaded",
+];
+/**
+ * Post-CC-2.1.198 additions (sema superset; CC added them after 198).
+ * APPEND-ONLY: new members go at the tail (1.3.0 `DirectoryAdded`, CC 2.1.219 — CC's own tuple places it
+ * between FileChanged and MessageDisplay; the declaration order here is not normative, the enum is a set).
+ * 2.0.0 appends the model-switch pair (`PreModelSwitch` / `PostModelSwitch`, CC 2.1.259 — absent from the
+ * 2.1.250 corpus, so 250→259 is when they landed upstream).
+ *
+ * 🔴 This list is no longer maintained by hand-reading a CLI bundle: `test/upstream-drift.test.ts` fails
+ * (naming the missing words) whenever the CC anchor snapshot in `test/fixtures/cc-hook-events.json` holds an
+ * event this set does not, and that snapshot is produced by `scripts/extract-cc-hook-events.mjs`, never typed.
+ */
+const POST_198_HOOK_EVENTS = ["CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+/** The full 33-event contract set = CC 198's 27 + the 6 post-198 events — the one exported closed set of hook event names. */
+export const HOOK_EVENTS = [...CC_198_HOOK_EVENTS, ...POST_198_HOOK_EVENTS];
+/** The guard events (CC 2.1.296 `SV`): their hooks may guard the permissions declared beside them — see the file header. */
+const HOOK_GUARD_EVENTS = ["PreToolUse", "PermissionRequest"];
+// ── entry vocabulary and the one field table ───────────────────────────────────────────────────────────────
+/**
+ * The hook entry `type` closed set — CC 2.1.296's five (`cli296.js:237454`): `command` (shell command on the host that runs the hook),
+ * `prompt` (one-shot LLM evaluation of the hook input), `agent` (agentic verifier loop), `http` (POST the hook input to a URL),
+ * `mcp_tool` (call a tool on an already-configured MCP server). An entry of another type is a bad piece — and in a guard event that rejects
+ * the whole document, which is why `test/upstream-drift.test.ts` ①b holds this set against the CC anchor snapshot.
+ */
+export const HOOK_ENTRY_TYPES = ["command", "prompt", "agent", "http", "mcp_tool"];
+/** `shell` values: 'bash' = the user's $SHELL family; 'powershell' = pwsh. Default bash. */
+const HOOK_SHELLS = ["bash", "powershell"];
+/** Fields every entry type takes: `if` = permission-rule syntax (e.g. "Bash(git *)") evaluated against tool_name/tool_input before the hook
+ *  runs (tool events only; shell superset field, CC-compatible); `timeout` = seconds for this entry (default `DEFAULT_HOOK_TIMEOUT_SECONDS`);
+ *  `statusMessage` = spinner status message; `once` = run once, then remove. */
+const HOOK_ENTRY_COMMON_FIELDS = { if: "string?", timeout: "seconds?", statusMessage: "string?", once: "boolean?" };
+/**
+ * THE field table of a hook entry, per type — read by {@link classifyHooksConfig} (which field is bad, what is carried) and by the entry
+ * types below (derived from it). Field order = the order a loaded entry's keys come out in.
+ *  · command: `shell` (see above), `async` = run in background without blocking, `asyncRewake` = background + wake the model on exit 2;
+ *  · prompt / agent: `prompt` ($ARGUMENTS = the hook input JSON), `model`;
+ *  · http: `url`, `headers` (values may reference $NAMEs listed in `allowedEnvVars` — env-NAME interpolation only, the config never carries a
+ *    secret value; `interpolateHookEnvVars` is the one reading), `allowedEnvVars`;
+ *  · mcp_tool: `server` (an already-configured MCP server's name), `tool`, `input` (the tool's arguments; string values may interpolate
+ *    `${path}` from the hook input JSON — CC 2.1.296 semantics, the runner's business).
+ */
+const HOOK_ENTRY_FIELDS = {
+    command: { command: "text", shell: "shell?", async: "boolean?", asyncRewake: "boolean?", ...HOOK_ENTRY_COMMON_FIELDS },
+    prompt: { prompt: "text", model: "string?", ...HOOK_ENTRY_COMMON_FIELDS },
+    agent: { prompt: "text", model: "string?", ...HOOK_ENTRY_COMMON_FIELDS },
+    http: { url: "text", headers: "stringRecord?", allowedEnvVars: "stringList?", ...HOOK_ENTRY_COMMON_FIELDS },
+    mcp_tool: { server: "string", tool: "string", input: "record?", ...HOOK_ENTRY_COMMON_FIELDS },
+};
+// ── classification vocabulary ──────────────────────────────────────────────────────────────────────────────
+/** What happened to a document's hooks: all loaded / loaded with pieces dropped / the document rejected (nothing in it applies). */
+export const HOOKS_CLASSIFICATION_OUTCOMES = ["loaded", "loaded-partial", "rejected"];
+/**
+ * Why a piece was DROPPED (closed; one word per level of piece, no `other`):
+ *  · `hooks-not-object` — `hooks` is null / a scalar / an array holding only scalars ⇒ the whole `hooks` key goes;
+ *  · `unknown-event`    — a key under `hooks` that is not a {@link HOOK_EVENTS} name;
+ *  · `event-not-array`  — a known event whose value is not an array (for a guard event: only `null`);
+ *  · `matcher-invalid`  — a matcher that is not an object, whose `matcher` is not a string or whose `hooks` is not an array (non-guard event);
+ *  · `entry-invalid`    — an entry that is not an object, has no / an unknown `type`, or a field outside its kind (non-guard event).
+ */
+export const HOOKS_DROPPED_PIECE_CODES = ["hooks-not-object", "unknown-event", "event-not-array", "matcher-invalid", "entry-invalid"];
+/**
+ * Why the document was REJECTED (closed; each is "a guard may be in this piece"):
+ *  · `guard-outside-hooks`       — a guard sign outside `hooks` (top level, under another key, or the document itself matcher-shaped);
+ *  · `hooks-is-matcher`          — `hooks` is an array holding objects / arrays, a single matcher, or a single entry;
+ *  · `guard-under-unknown-event` — an unknown event name holding a guard sign;
+ *  · `guard-event-not-array`     — a guard event whose value is not an array (and not null), or a known event whose non-array value holds a sign;
+ *  · `guard-matcher-invalid`     — a bad matcher in a guard event, or a matcher holding a sign (in any event);
+ *  · `guard-entry-invalid`       — a bad entry in a guard event, or an entry holding a sign (in any event).
+ */
+export const HOOKS_REJECTION_CODES = [
+    "guard-outside-hooks",
+    "hooks-is-matcher",
+    "guard-under-unknown-event",
+    "guard-event-not-array",
+    "guard-matcher-invalid",
+    "guard-entry-invalid",
+];
+/** A JSON object: not null, not an array, prototype `Object.prototype` or null. */
+function hookIsRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+/** The first own key of `node` (in key order) that names a guard event with a value other than null / undefined / `[]` (CC `ei`). */
+function hookGuardKeyOf(node) {
+    for (const key of Object.keys(node)) {
+        if (!HOOK_GUARD_EVENTS.includes(key))
+            continue;
+        const value = node[key];
+        if (value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0))
+            return key;
+    }
+    return undefined;
+}
+/** Matcher-shaped: `hooks` is a non-empty array, or a single object with `matcher` present beside it or a string `type` inside it. */
+function hookLooksLikeMatcher(value) {
+    if (!hookIsRecord(value))
+        return false;
+    const inner = Object.hasOwn(value, "hooks") ? value.hooks : undefined;
+    if (Array.isArray(inner))
+        return inner.length > 0;
+    return hookIsRecord(inner) && (Object.hasOwn(value, "matcher") || typeof inner.type === "string");
+}
+/**
+ * The coordinate of the first guard sign (document order) in `root`'s subtree, or undefined. `place` is where `root` sits: `matcherList` =
+ * the array under an event name (its elements are in a matcher's legal place), `matcher` = one such element, `other` = anywhere else.
+ * A guard-event member's coordinate ends with its key; a matcher-shaped object's is the object's own. Iterative, whole subtree, each object
+ * visited once per place (cycles terminate).
+ */
+function hookGuardSignIn(root, rootPath, place) {
+    const frames = [];
+    const pending = [[root, -1, place]];
+    const seen = { matcherList: new Set(), matcher: new Set(), other: new Set() };
+    const pathTo = (frame, tail) => {
+        const segments = [...tail];
+        for (let f = frame; f >= 0; f = frames[f].parent)
+            segments.unshift(frames[f].key);
+        return [...rootPath, ...segments];
+    };
+    while (pending.length > 0) {
+        const [node, frame, at] = pending.pop();
+        if (node === null || typeof node !== "object" || seen[at].has(node))
+            continue;
+        seen[at].add(node);
+        if (Array.isArray(node)) {
+            for (let i = node.length - 1; i >= 0; i--) {
+                frames.push({ key: i, parent: frame });
+                pending.push([node[i], frames.length - 1, at === "matcherList" ? "matcher" : "other"]);
+            }
+            continue;
+        }
+        const guardKey = hookGuardKeyOf(node);
+        if (guardKey !== undefined)
+            return pathTo(frame, [guardKey]);
+        if (at !== "matcher" && hookLooksLikeMatcher(node))
+            return pathTo(frame, []);
+        const keys = Object.keys(node);
+        for (let i = keys.length - 1; i >= 0; i--) {
+            frames.push({ key: keys[i], parent: frame });
+            pending.push([node[keys[i]], frames.length - 1, "other"]);
+        }
+    }
+    return undefined;
+}
+/** The key of the object piece at `at` that holds `sign` (a coordinate at or below `at`, as {@link hookGuardSignIn} reports it): the first segment
+ *  below `at`; `hooks` when the sign IS the piece itself (a matcher-shaped object — its `hooks` member is what makes it one). */
+function hookSignKeyOf(at, sign) {
+    const key = sign[at.length];
+    return key === undefined ? "hooks" : String(key);
+}
+/** Does `value` fit the field kind `base` (the kind without its `?`)? */
+function hookFieldFits(base, value) {
+    switch (base) {
+        case "text":
+            return typeof value === "string" && value.length > 0 && !value.includes("\0");
+        case "string":
+            return typeof value === "string";
+        case "shell":
+            return typeof value === "string" && HOOK_SHELLS.includes(value);
+        case "boolean":
+            return typeof value === "boolean";
+        case "seconds":
+            return typeof value === "number" && Number.isFinite(value) && value > 0;
+        case "stringRecord":
+            return hookIsRecord(value) && Object.values(value).every((v) => typeof v === "string");
+        case "stringList":
+            if (!Array.isArray(value))
+                return false;
+            for (let i = 0; i < value.length; i++)
+                if (typeof value[i] !== "string")
+                    return false;
+            return true;
+        case "record":
+            return hookIsRecord(value);
+        default: {
+            const unknownKind = base;
+            throw new Error(`hook entry field table: unknown field kind '${String(unknownKind)}'`);
+        }
+    }
+}
+/** One entry → `{ entry }` (its contract fields, in table order; records and lists copied) or `{ field? }` (the first field that is wrong). */
+function hookEntryRead(entry) {
+    if (!hookIsRecord(entry))
+        return {};
+    const type = Object.hasOwn(entry, "type") ? entry.type : undefined;
+    if (typeof type !== "string" || !Object.hasOwn(HOOK_ENTRY_FIELDS, type))
+        return { field: "type" };
+    const fields = HOOK_ENTRY_FIELDS[type];
+    const out = { type };
+    for (const field of Object.keys(fields)) {
+        const kind = fields[field];
+        const optional = kind.endsWith("?");
+        const value = Object.hasOwn(entry, field) ? entry[field] : undefined;
+        if (value === undefined) {
+            if (optional)
+                continue;
+            return { field };
+        }
+        const base = (optional ? kind.slice(0, -1) : kind);
+        if (!hookFieldFits(base, value))
+            return { field };
+        out[field] = Array.isArray(value) ? value.slice() : hookIsRecord(value) ? Object.fromEntries(Object.entries(value)) : value;
+    }
+    return { entry: out };
+}
+/** One matcher (at `at`, under a guard event or not) → what loads of it, reporting its bad pieces / signs into the two sinks. */
+function hookMatcherRead(matcher, at, guardEvent, reject, drop) {
+    if (!hookIsRecord(matcher)) {
+        if (guardEvent || hookGuardSignIn(matcher, at, "matcher") !== undefined)
+            reject("guard-matcher-invalid", at);
+        else
+            drop("matcher-invalid", at);
+        return undefined;
+    }
+    const entries = Object.hasOwn(matcher, "hooks") ? matcher.hooks : undefined;
+    // a sign at the matcher level: a guard-event key on the matcher itself, or anywhere in its fields other than a well-formed entry list;
+    // the member that holds the first one (document order — the order hookGuardSignIn reports) is the rejection's `field`
+    const signField = hookGuardKeyOf(matcher) ??
+        Object.keys(matcher).find((key) => !(key === "hooks" && Array.isArray(entries)) && hookGuardSignIn(matcher[key], [...at, key], "other") !== undefined);
+    if (signField !== undefined) {
+        reject("guard-matcher-invalid", at, signField);
+        return undefined;
+    }
+    const entrySigns = [];
+    if (Array.isArray(entries))
+        for (let j = 0; j < entries.length; j++)
+            entrySigns.push(hookGuardSignIn(entries[j], [...at, "hooks", j], "other"));
+    const name = Object.hasOwn(matcher, "matcher") ? matcher.matcher : undefined;
+    const badField = name !== undefined && typeof name !== "string" ? "matcher" : !Array.isArray(entries) ? "hooks" : undefined;
+    if (badField !== undefined || !Array.isArray(entries)) {
+        if (guardEvent || entrySigns.some((sign) => sign !== undefined))
+            reject("guard-matcher-invalid", at, badField);
+        else
+            drop("matcher-invalid", at, badField);
+        return undefined;
+    }
+    const kept = [];
+    for (let j = 0; j < entries.length; j++) {
+        const where = [...at, "hooks", j];
+        const sign = entrySigns[j];
+        if (sign !== undefined) {
+            reject("guard-entry-invalid", where, hookIsRecord(entries[j]) ? hookSignKeyOf(where, sign) : undefined);
+            continue;
+        }
+        const read = hookEntryRead(entries[j]);
+        if (read.entry !== undefined)
+            kept.push(read.entry);
+        else if (guardEvent)
+            reject("guard-entry-invalid", where, read.field);
+        else
+            drop("entry-invalid", where, read.field);
+    }
+    return typeof name === "string" ? { matcher: name, hooks: kept } : { hooks: kept };
+}
+/** The `hooks` value → what loads of it (undefined when nothing does), reporting its bad pieces / signs into the two sinks. */
+function hookBlockRead(hooks, reject, drop) {
+    if (!hookIsRecord(hooks)) {
+        if (Array.isArray(hooks) && hooks.some((x) => x !== null && typeof x === "object"))
+            reject("hooks-is-matcher", ["hooks"]);
+        else
+            drop("hooks-not-object", ["hooks"]);
+        return undefined;
+    }
+    if (hookLooksLikeMatcher(hooks) || typeof hooks.type === "string") {
+        reject("hooks-is-matcher", ["hooks"]);
+        return undefined;
+    }
+    const loaded = {};
+    for (const event of Object.keys(hooks)) {
+        const value = hooks[event];
+        const at = ["hooks", event];
+        if (!HOOK_EVENTS.includes(event)) {
+            if (hookGuardSignIn(value, at, Array.isArray(value) ? "matcherList" : "other") !== undefined)
+                reject("guard-under-unknown-event", at);
+            else
+                drop("unknown-event", at);
+            continue;
+        }
+        const guardEvent = HOOK_GUARD_EVENTS.includes(event);
+        if (!Array.isArray(value)) {
+            if ((guardEvent && value !== null) || hookGuardSignIn(value, at, "other") !== undefined)
+                reject("guard-event-not-array", at);
+            else
+                drop("event-not-array", at);
+            continue;
+        }
+        const matchers = [];
+        for (let i = 0; i < value.length; i++) {
+            const read = hookMatcherRead(value[i], [...at, i], guardEvent, reject, drop);
+            if (read !== undefined)
+                matchers.push(read);
+        }
+        loaded[event] = matchers; // a known event name — never a prototype key
+    }
+    return loaded;
+}
+/**
+ * THE one reading of a settings document's hooks (see the file header for the law): which pieces drop, whether the document is rejected,
+ * and what loads. Pure: reads `settingsDoc` (the WHOLE document — guard signs outside `hooks` count), never modifies it, no I/O, no sentences.
+ * Rejections and drops are listed in document order.
+ *
+ * COPYING THIS FUNCTION (client-core's generator, or any consumer that emits it as source): its one free name besides JavaScript built-ins is
+ * {@link HOOK_EVENTS}. The copy's scope must be GIVEN that name, bound to this package's runtime export `HOOK_EVENTS` (the upstream constant —
+ * the generator injects it as a registered value, it does not re-declare it). Never paste a literal event list into the generated text: that is
+ * a second event table, which the upstream drift gate (it watches `HOOK_EVENTS`) cannot see, and which goes stale the first time CC adds an event.
+ * The module-private declarations the closure uses (the `HOOK_*` constants and `hook*` helpers below the classifier line) are copied with it;
+ * the hooks-classify test file (group ⑤) pins that the free names are exactly these.
+ */
+export function classifyHooksConfig(settingsDoc) {
+    const rejections = [];
+    const dropped = [];
+    const reject = (code, path, field) => {
+        rejections.push(field === undefined ? { code, path } : { code, path, field });
+    };
+    const drop = (code, path, field) => {
+        dropped.push(field === undefined ? { code, path } : { code, path, field });
+    };
+    let hooks;
+    if (settingsDoc !== null && typeof settingsDoc === "object" && !Array.isArray(settingsDoc)) {
+        const doc = settingsDoc;
+        for (const key of Object.keys(doc)) {
+            const value = doc[key];
+            if (key === "hooks") {
+                hooks = hookBlockRead(value, reject, drop);
+                continue;
+            }
+            // the document itself written as a matcher: its top-level `matcher` key is the evidence, reported at that key's place
+            const sign = key === "matcher" && hookLooksLikeMatcher(doc)
+                ? [key]
+                : HOOK_GUARD_EVENTS.includes(key) && value !== null && value !== undefined && !(Array.isArray(value) && value.length === 0)
+                    ? [key]
+                    : hookGuardSignIn(value, [key], "other");
+            if (sign !== undefined)
+                reject("guard-outside-hooks", sign);
+        }
+    }
+    else {
+        const sign = hookGuardSignIn(settingsDoc, [], "other");
+        if (sign !== undefined)
+            reject("guard-outside-hooks", sign);
+    }
+    if (rejections.length > 0)
+        return { outcome: "rejected", hooks: undefined, dropped: [], rejections };
+    if (dropped.length > 0)
+        return { outcome: "loaded-partial", hooks, dropped, rejections: [] };
+    return { outcome: "loaded", hooks, dropped: [], rejections: [] };
+}
+// ── zod faces: projections of the classifier ───────────────────────────────────────────────────────────────
+/**
+ * A zod face that READS {@link classifyHooksConfig} (never a second judgement): `carry(value)` places the value into a carrier settings
+ * document — a matcher / an entry goes under `Stop`, a non-guard event, so a bad piece is a drop with its own coordinate rather than a rejection
+ * of the carrier — `strip` is how many leading coordinate segments are the carrier's, `take(hooks)` picks the value back out of what loaded.
+ * Accepted ⇔ `"loaded"`; each piece becomes one custom issue: message = its code, path = its coordinate below the carrier + its `field`.
+ */
+function hooksFace(carry, strip, take) {
+    return z.unknown().transform((value, ctx) => {
+        const c = classifyHooksConfig(carry(value));
+        if (c.outcome === "loaded")
+            return take(c.hooks ?? {});
+        for (const piece of [...c.rejections, ...c.dropped]) {
+            ctx.addIssue({ code: "custom", path: [...piece.path.slice(strip), ...(piece.field === undefined ? [] : [piece.field])], ...buildQuotedIssue `${fixed(piece.code)}` });
+        }
+        return z.NEVER;
+    });
+}
+/** The carrier for one entry of type `type`: the value itself when it says that type, else an untyped object (⇒ the issue names `type`). */
+function entryOfType(value, type) {
+    return value !== null && typeof value === "object" && value.type === type ? value : {};
+}
+const entryFace = (type) => hooksFace((v) => ({ hooks: { Stop: [{ hooks: [entryOfType(v, type)] }] } }), 5, (h) => h.Stop[0].hooks[0]);
+export const CommandHookEntry = entryFace("command");
+export const PromptHookEntry = entryFace("prompt");
+export const AgentHookEntry = entryFace("agent");
+export const HttpHookEntry = entryFace("http");
+export const McpToolHookEntry = entryFace("mcp_tool");
+/** One hook entry of any {@link HOOK_ENTRY_TYPES} type (projection of the classifier). */
+export const HookEntry = hooksFace((v) => ({ hooks: { Stop: [{ hooks: [v] }] } }), 5, (h) => h.Stop[0].hooks[0]);
+/** One matcher group (projection of the classifier). */
+export const HookMatcherEntry = hooksFace((v) => ({ hooks: { Stop: [v] } }), 3, (h) => h.Stop[0]);
+/**
+ * The hooks config record (projection of the classifier): accepted ⇔ {@link classifyHooksConfig} loads all of it; the parsed value is what it
+ * loaded (entries carry their contract fields only). Strict on purpose — a wire / an API carrying hooks refuses a bad piece outright (each
+ * issue = one piece: message = its code, path = its coordinate); a settings file loader asks the classifier itself and drops what it may.
+ *
+ * 🔴 The event-name set is closed: an event this package has not adopted yet is an unknown event (dropped from a settings file, refused here).
+ * That blast radius is why {@link HOOK_EVENTS} and {@link HOOK_ENTRY_TYPES} have an upstream drift gate rather than a human promise.
+ */
+export const HooksConfig = hooksFace((v) => ({ hooks: v }), 1, (h) => h);