@sema-agent/settings-schema 12.2.1 → 13.0.0

package/dist/hooks-config.d.ts

@@ -0,0 +1,235 @@
+/**
+ * `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).
+ *
+ * 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 type { ConfigPath } from "./config-fns.js";
+/** 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 declare const HOOK_EVENTS: readonly ["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", "CwdChanged", "FileChanged", "MessageDisplay", "DirectoryAdded", "PreModelSwitch", "PostModelSwitch"];
+/** One hook event name (the same union as `./hooks`' `HookEventName`, which is the zod enum over {@link HOOK_EVENTS}). */
+type HookEventWord = (typeof HOOK_EVENTS)[number];
+/**
+ * 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 declare const HOOK_ENTRY_TYPES: readonly ["command", "prompt", "agent", "http", "mcp_tool"];
+export type HookEntryType = (typeof HOOK_ENTRY_TYPES)[number];
+/** `shell` values: 'bash' = the user's $SHELL family; 'powershell' = pwsh. Default bash. */
+declare const HOOK_SHELLS: readonly ["bash", "powershell"];
+/**
+ * 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).
+ */
+declare const HOOK_ENTRY_FIELDS: {
+    readonly command: {
+        readonly if: "string?";
+        readonly timeout: "seconds?";
+        readonly statusMessage: "string?";
+        readonly once: "boolean?";
+        readonly command: "text";
+        readonly shell: "shell?";
+        readonly async: "boolean?";
+        readonly asyncRewake: "boolean?";
+    };
+    readonly prompt: {
+        readonly if: "string?";
+        readonly timeout: "seconds?";
+        readonly statusMessage: "string?";
+        readonly once: "boolean?";
+        readonly prompt: "text";
+        readonly model: "string?";
+    };
+    readonly agent: {
+        readonly if: "string?";
+        readonly timeout: "seconds?";
+        readonly statusMessage: "string?";
+        readonly once: "boolean?";
+        readonly prompt: "text";
+        readonly model: "string?";
+    };
+    readonly http: {
+        readonly if: "string?";
+        readonly timeout: "seconds?";
+        readonly statusMessage: "string?";
+        readonly once: "boolean?";
+        readonly url: "text";
+        readonly headers: "stringRecord?";
+        readonly allowedEnvVars: "stringList?";
+    };
+    readonly mcp_tool: {
+        readonly if: "string?";
+        readonly timeout: "seconds?";
+        readonly statusMessage: "string?";
+        readonly once: "boolean?";
+        readonly server: "string";
+        readonly tool: "string";
+        readonly input: "record?";
+    };
+};
+type HookFieldBaseValue<B> = B extends "text" | "string" ? string : B extends "shell" ? (typeof HOOK_SHELLS)[number] : B extends "boolean" ? boolean : B extends "seconds" ? number : B extends "stringRecord" ? Record<string, string> : B extends "stringList" ? string[] : B extends "record" ? Record<string, unknown> : never;
+type HookFieldValue<K> = K extends `${infer B}?` ? HookFieldBaseValue<B> : HookFieldBaseValue<K>;
+type Flat<O> = {
+    [K in keyof O]: O[K];
+};
+/** One entry type's shape, derived from {@link HOOK_ENTRY_FIELDS}: `type` + required fields + optional (`?`) fields. */
+type HookEntryOf<T extends HookEntryType, F = (typeof HOOK_ENTRY_FIELDS)[T]> = Flat<{
+    type: T;
+} & {
+    -readonly [K in keyof F as F[K] extends `${string}?` ? never : K]: HookFieldValue<F[K]>;
+} & {
+    -readonly [K in keyof F as F[K] extends `${string}?` ? K : never]?: HookFieldValue<F[K]>;
+}>;
+/** `command` — shell command on the host that runs the hook (DESIGN POINT ② in `./hooks`). */
+export type CommandHookEntry = HookEntryOf<"command">;
+/** `prompt` — one-shot LLM evaluation of the hook input ($ARGUMENTS = input JSON). */
+export type PromptHookEntry = HookEntryOf<"prompt">;
+/** `agent` — agentic verifier loop over the hook input ($ARGUMENTS = input JSON). */
+export type AgentHookEntry = HookEntryOf<"agent">;
+/** `http` — POST the hook input JSON to a URL. */
+export type HttpHookEntry = HookEntryOf<"http">;
+/** `mcp_tool` — call `tool` on the already-configured MCP server `server` with `input`. */
+export type McpToolHookEntry = HookEntryOf<"mcp_tool">;
+/** One configured hook (CC settings shape + shell superset fields; discriminated on `type`). */
+export type HookEntry = {
+    [T in HookEntryType]: HookEntryOf<T>;
+}[HookEntryType];
+/** One matcher group: `matcher` (read by `hookMatcherSelects` — name list or unanchored JS regex; empty/`*`/absent matches everything) +
+ *  the hooks it fires. */
+export type HookMatcherEntry = {
+    matcher?: string;
+    hooks: HookEntry[];
+};
+/** The hooks config record: keys limited to the {@link HOOK_EVENTS} contract events, all optional. */
+export type HooksConfig = Partial<Record<HookEventWord, HookMatcherEntry[]>>;
+/** What happened to a document's hooks: all loaded / loaded with pieces dropped / the document rejected (nothing in it applies). */
+export declare const HOOKS_CLASSIFICATION_OUTCOMES: readonly ["loaded", "loaded-partial", "rejected"];
+export type HooksClassificationOutcome = (typeof HOOKS_CLASSIFICATION_OUTCOMES)[number];
+/**
+ * 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 declare const HOOKS_DROPPED_PIECE_CODES: readonly ["hooks-not-object", "unknown-event", "event-not-array", "matcher-invalid", "entry-invalid"];
+export type HooksDroppedPieceCode = (typeof HOOKS_DROPPED_PIECE_CODES)[number];
+/**
+ * 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 declare const HOOKS_REJECTION_CODES: readonly ["guard-outside-hooks", "hooks-is-matcher", "guard-under-unknown-event", "guard-event-not-array", "guard-matcher-invalid", "guard-entry-invalid"];
+export type HooksRejectionCode = (typeof HOOKS_REJECTION_CODES)[number];
+/** One dropped piece: `path` = its coordinate (raw segments — see the file header on `outgoingPath`); `field` = for a matcher / entry, the
+ *  contract field whose value is wrong (`"type"` when the type is missing or unknown; absent when the piece is not an object at all). */
+export interface HooksDroppedPiece {
+    readonly code: HooksDroppedPieceCode;
+    readonly path: ConfigPath;
+    readonly field?: string;
+}
+/** One reason the document was rejected: `path` = the offending piece (for `guard-outside-hooks`: the guard sign itself); `field` as above. */
+export interface HooksRejection {
+    readonly code: HooksRejectionCode;
+    readonly path: ConfigPath;
+    readonly field?: string;
+}
+/**
+ * What {@link classifyHooksConfig} answers. `hooks` = what loads: the `hooks` value with every dropped piece removed and every entry carrying
+ * only its contract fields; `undefined` when the document has no `hooks` key, when `hooks` itself was dropped, and always when rejected.
+ * Invariants (by construction): `loaded` ⇔ nothing dropped or rejected; `loaded-partial` ⇔ dropped pieces, no rejection; `rejected` ⇔ at
+ * least one rejection (dropped is then empty — nothing in the document applies).
+ */
+export type HooksClassification = {
+    readonly outcome: "loaded";
+    readonly hooks: HooksConfig | undefined;
+    readonly dropped: readonly [];
+    readonly rejections: readonly [];
+} | {
+    readonly outcome: "loaded-partial";
+    readonly hooks: HooksConfig | undefined;
+    readonly dropped: readonly HooksDroppedPiece[];
+    readonly rejections: readonly [];
+} | {
+    readonly outcome: "rejected";
+    readonly hooks: undefined;
+    readonly dropped: readonly [];
+    readonly rejections: readonly HooksRejection[];
+};
+/**
+ * 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 declare function classifyHooksConfig(settingsDoc: unknown): HooksClassification;
+export declare const CommandHookEntry: z.ZodType<CommandHookEntry>;
+export declare const PromptHookEntry: z.ZodType<PromptHookEntry>;
+export declare const AgentHookEntry: z.ZodType<AgentHookEntry>;
+export declare const HttpHookEntry: z.ZodType<HttpHookEntry>;
+export declare const McpToolHookEntry: z.ZodType<McpToolHookEntry>;
+/** One hook entry of any {@link HOOK_ENTRY_TYPES} type (projection of the classifier). */
+export declare const HookEntry: z.ZodType<HookEntry>;
+/** One matcher group (projection of the classifier). */
+export declare const HookMatcherEntry: z.ZodType<HookMatcherEntry>;
+/**
+ * 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 declare const HooksConfig: z.ZodType<HooksConfig>;
+export {};