apex-code 0.0.1-alpha.9 → 0.0.4

package/dist/core/hooks/loader.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Hook config parsing and runtime assembly. Parsing is strict and fails
+ * closed: an invalid `hooks` key throws `HookConfigError` with the offending
+ * path, and the session wiring lets that propagate -- a governance entry that
+ * silently loads as nothing is a policy hole, so a malformed key refuses to
+ * start the session instead (the permission-rule posture: a failed rule load
+ * blocks rather than falls open).
+ */
+import { type HookEventName, type HookHandler, type HookHandlerConfig, type HookRuntime, type HooksSettings } from "./types.ts";
+export declare class HookConfigError extends Error {
+    constructor(message: string);
+}
+/**
+ * V1 matcher grammar: exact tool names joined by `|` or `,` with optional
+ * whitespace, mirroring permission-rule matching. Regex matchers are a
+ * recorded non-goal -- grammar creep is how config surfaces rot.
+ */
+export declare function parseMatcher(matcher: string): (toolName: string) => boolean;
+/** Strictly validate raw settings JSON into `HooksSettings`, throwing `HookConfigError` on the first problem. */
+export declare function parseHookSettings(raw: unknown): HooksSettings;
+export type HookHandlerFactory = (config: HookHandlerConfig, event: HookEventName) => HookHandler;
+/**
+ * Assemble the runtime, or return undefined when nothing is configured -- an
+ * absent key constructs nothing, so an unconfigured session spawns no
+ * subprocess and changes no behavior. `createHandler` is the seam tests use to
+ * inject scripted handlers instead of real command/HTTP execution.
+ */
+export declare function loadHookRuntime(settings: HooksSettings | undefined, createHandler?: HookHandlerFactory): HookRuntime | undefined;
+//# sourceMappingURL=loader.d.ts.map

package/dist/core/hooks/loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH,OAAO,EAEN,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,WAAW,EAChB,KAAK,aAAa,EAElB,MAAM,YAAY,CAAC;AAEpB,qBAAa,eAAgB,SAAQ,KAAK;IACzC,YAAY,OAAO,EAAE,MAAM,EAG1B;CACD;AAID;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAU3E;AA8DD,iHAAiH;AACjH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,CAgB7D;AAED,MAAM,MAAM,kBAAkB,GAAG,CAAC,MAAM,EAAE,iBAAiB,EAAE,KAAK,EAAE,aAAa,KAAK,WAAW,CAAC;AAMlG;;;;;GAKG;AACH,wBAAgB,eAAe,CAC9B,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,aAAa,GAAE,kBAA8C,GAC3D,WAAW,GAAG,SAAS,CAgBzB","sourcesContent":["/**\n * Hook config parsing and runtime assembly. Parsing is strict and fails\n * closed: an invalid `hooks` key throws `HookConfigError` with the offending\n * path, and the session wiring lets that propagate -- a governance entry that\n * silently loads as nothing is a policy hole, so a malformed key refuses to\n * start the session instead (the permission-rule posture: a failed rule load\n * blocks rather than falls open).\n */\n\nimport { commandHookHandler } from \"./command-handler.ts\";\nimport { httpHookHandler } from \"./http-handler.ts\";\nimport { createHookRuntime, type RuntimeHookEntry } from \"./runtime.ts\";\nimport {\n\tHOOK_EVENT_NAMES,\n\ttype HookEventName,\n\ttype HookHandler,\n\ttype HookHandlerConfig,\n\ttype HookRuntime,\n\ttype HooksSettings,\n\tMAX_HOOK_TIMEOUT_MS,\n} from \"./types.ts\";\n\nexport class HookConfigError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"HookConfigError\";\n\t}\n}\n\nconst MATCHER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;\n\n/**\n * V1 matcher grammar: exact tool names joined by `|` or `,` with optional\n * whitespace, mirroring permission-rule matching. Regex matchers are a\n * recorded non-goal -- grammar creep is how config surfaces rot.\n */\nexport function parseMatcher(matcher: string): (toolName: string) => boolean {\n\tconst names = matcher\n\t\t.split(/[|,]/)\n\t\t.map((name) => name.trim())\n\t\t.filter((name) => name.length > 0);\n\tif (names.length === 0 || !names.every((name) => MATCHER_NAME_PATTERN.test(name))) {\n\t\tthrow new HookConfigError(`invalid matcher \"${matcher}\" (expected exact tool names joined by \"|\" or \",\")`);\n\t}\n\tconst accepted = new Set(names);\n\treturn (toolName) => accepted.has(toolName);\n}\n\nfunction parseHandlerConfig(event: HookEventName, index: number, raw: unknown): HookHandlerConfig {\n\tconst path = `hooks.${event}[${index}]`;\n\tif (typeof raw !== \"object\" || raw === null || Array.isArray(raw)) {\n\t\tthrow new HookConfigError(`${path}: expected an object`);\n\t}\n\tconst record = raw as Record<string, unknown>;\n\tconst type = record.type;\n\tif (type !== \"command\" && type !== \"http\") {\n\t\tthrow new HookConfigError(`${path}: \"type\" must be \"command\" or \"http\"`);\n\t}\n\tconst allowed =\n\t\ttype === \"command\" ? [\"type\", \"matcher\", \"command\", \"timeoutMs\"] : [\"type\", \"matcher\", \"url\", \"timeoutMs\"];\n\tfor (const key of Object.keys(record)) {\n\t\tif (!allowed.includes(key)) {\n\t\t\tthrow new HookConfigError(`${path}: unknown field \"${key}\" (a mistyped key would silently drop policy)`);\n\t\t}\n\t}\n\tconst matcherField = record.matcher;\n\tif (matcherField !== undefined) {\n\t\tif (typeof matcherField !== \"string\") {\n\t\t\tthrow new HookConfigError(`${path}: \"matcher\" must be a string`);\n\t\t}\n\t\t// Validate the grammar here, at load, so a bad matcher is rejected with\n\t\t// the config path even before any runtime is assembled.\n\t\tparseMatcher(matcherField);\n\t}\n\tconst timeoutField = record.timeoutMs;\n\tif (\n\t\ttimeoutField !== undefined &&\n\t\t(typeof timeoutField !== \"number\" ||\n\t\t\t!Number.isFinite(timeoutField) ||\n\t\t\ttimeoutField <= 0 ||\n\t\t\ttimeoutField > MAX_HOOK_TIMEOUT_MS)\n\t) {\n\t\tthrow new HookConfigError(`${path}: \"timeoutMs\" must be a number between 1 and ${MAX_HOOK_TIMEOUT_MS}`);\n\t}\n\tif (type === \"command\") {\n\t\tconst command = record.command;\n\t\tif (typeof command !== \"string\" || command.trim().length === 0) {\n\t\t\tthrow new HookConfigError(`${path}: \"command\" must be a non-empty string`);\n\t\t}\n\t\treturn {\n\t\t\ttype: \"command\",\n\t\t\tcommand,\n\t\t\t...(matcherField !== undefined ? { matcher: matcherField } : {}),\n\t\t\t...(timeoutField !== undefined ? { timeoutMs: timeoutField } : {}),\n\t\t};\n\t}\n\tconst urlField = record.url;\n\tif (typeof urlField !== \"string\" || !URL.canParse(urlField) || !/^https?:$/.test(new URL(urlField).protocol)) {\n\t\tthrow new HookConfigError(`${path}: \"url\" must be an http(s) URL`);\n\t}\n\treturn {\n\t\ttype: \"http\",\n\t\turl: urlField,\n\t\t...(matcherField !== undefined ? { matcher: matcherField } : {}),\n\t\t...(timeoutField !== undefined ? { timeoutMs: timeoutField } : {}),\n\t};\n}\n\n/** Strictly validate raw settings JSON into `HooksSettings`, throwing `HookConfigError` on the first problem. */\nexport function parseHookSettings(raw: unknown): HooksSettings {\n\tif (typeof raw !== \"object\" || raw === null || Array.isArray(raw)) {\n\t\tthrow new HookConfigError(\"hooks: expected an object keyed by event name\");\n\t}\n\tconst parsed: HooksSettings = {};\n\tfor (const [key, value] of Object.entries(raw as Record<string, unknown>)) {\n\t\tif (!(HOOK_EVENT_NAMES as readonly string[]).includes(key)) {\n\t\t\tthrow new HookConfigError(`hooks.\"${key}\": unknown hook event (v1 supports ${HOOK_EVENT_NAMES.join(\", \")})`);\n\t\t}\n\t\tconst event = key as HookEventName;\n\t\tif (!Array.isArray(value)) {\n\t\t\tthrow new HookConfigError(`hooks.${event}: expected an array of handler configs`);\n\t\t}\n\t\tparsed[event] = value.map((entry, index) => parseHandlerConfig(event, index, entry));\n\t}\n\treturn parsed;\n}\n\nexport type HookHandlerFactory = (config: HookHandlerConfig, event: HookEventName) => HookHandler;\n\nfunction defaultHookHandlerFactory(config: HookHandlerConfig): HookHandler {\n\treturn config.type === \"command\" ? commandHookHandler(config) : httpHookHandler(config);\n}\n\n/**\n * Assemble the runtime, or return undefined when nothing is configured -- an\n * absent key constructs nothing, so an unconfigured session spawns no\n * subprocess and changes no behavior. `createHandler` is the seam tests use to\n * inject scripted handlers instead of real command/HTTP execution.\n */\nexport function loadHookRuntime(\n\tsettings: HooksSettings | undefined,\n\tcreateHandler: HookHandlerFactory = defaultHookHandlerFactory,\n): HookRuntime | undefined {\n\tif (!settings) return undefined;\n\tconst entries: RuntimeHookEntry[] = [];\n\tfor (const event of HOOK_EVENT_NAMES) {\n\t\tconst configs = settings[event];\n\t\tif (!configs || configs.length === 0) continue;\n\t\tfor (const config of configs) {\n\t\t\tconst handler = createHandler(config, event);\n\t\t\tentries.push({\n\t\t\t\tevent,\n\t\t\t\thandler: config.matcher ? { ...handler, matchesTool: parseMatcher(config.matcher) } : handler,\n\t\t\t});\n\t\t}\n\t}\n\tif (entries.length === 0) return undefined;\n\treturn createHookRuntime(entries);\n}\n"]}

package/dist/core/hooks/loader.js

@@ -0,0 +1,139 @@
+/**
+ * Hook config parsing and runtime assembly. Parsing is strict and fails
+ * closed: an invalid `hooks` key throws `HookConfigError` with the offending
+ * path, and the session wiring lets that propagate -- a governance entry that
+ * silently loads as nothing is a policy hole, so a malformed key refuses to
+ * start the session instead (the permission-rule posture: a failed rule load
+ * blocks rather than falls open).
+ */
+import { commandHookHandler } from "./command-handler.js";
+import { httpHookHandler } from "./http-handler.js";
+import { createHookRuntime } from "./runtime.js";
+import { HOOK_EVENT_NAMES, MAX_HOOK_TIMEOUT_MS, } from "./types.js";
+export class HookConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HookConfigError";
+    }
+}
+const MATCHER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;
+/**
+ * V1 matcher grammar: exact tool names joined by `|` or `,` with optional
+ * whitespace, mirroring permission-rule matching. Regex matchers are a
+ * recorded non-goal -- grammar creep is how config surfaces rot.
+ */
+export function parseMatcher(matcher) {
+    const names = matcher
+        .split(/[|,]/)
+        .map((name) => name.trim())
+        .filter((name) => name.length > 0);
+    if (names.length === 0 || !names.every((name) => MATCHER_NAME_PATTERN.test(name))) {
+        throw new HookConfigError(`invalid matcher "${matcher}" (expected exact tool names joined by "|" or ",")`);
+    }
+    const accepted = new Set(names);
+    return (toolName) => accepted.has(toolName);
+}
+function parseHandlerConfig(event, index, raw) {
+    const path = `hooks.${event}[${index}]`;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new HookConfigError(`${path}: expected an object`);
+    }
+    const record = raw;
+    const type = record.type;
+    if (type !== "command" && type !== "http") {
+        throw new HookConfigError(`${path}: "type" must be "command" or "http"`);
+    }
+    const allowed = type === "command" ? ["type", "matcher", "command", "timeoutMs"] : ["type", "matcher", "url", "timeoutMs"];
+    for (const key of Object.keys(record)) {
+        if (!allowed.includes(key)) {
+            throw new HookConfigError(`${path}: unknown field "${key}" (a mistyped key would silently drop policy)`);
+        }
+    }
+    const matcherField = record.matcher;
+    if (matcherField !== undefined) {
+        if (typeof matcherField !== "string") {
+            throw new HookConfigError(`${path}: "matcher" must be a string`);
+        }
+        // Validate the grammar here, at load, so a bad matcher is rejected with
+        // the config path even before any runtime is assembled.
+        parseMatcher(matcherField);
+    }
+    const timeoutField = record.timeoutMs;
+    if (timeoutField !== undefined &&
+        (typeof timeoutField !== "number" ||
+            !Number.isFinite(timeoutField) ||
+            timeoutField <= 0 ||
+            timeoutField > MAX_HOOK_TIMEOUT_MS)) {
+        throw new HookConfigError(`${path}: "timeoutMs" must be a number between 1 and ${MAX_HOOK_TIMEOUT_MS}`);
+    }
+    if (type === "command") {
+        const command = record.command;
+        if (typeof command !== "string" || command.trim().length === 0) {
+            throw new HookConfigError(`${path}: "command" must be a non-empty string`);
+        }
+        return {
+            type: "command",
+            command,
+            ...(matcherField !== undefined ? { matcher: matcherField } : {}),
+            ...(timeoutField !== undefined ? { timeoutMs: timeoutField } : {}),
+        };
+    }
+    const urlField = record.url;
+    if (typeof urlField !== "string" || !URL.canParse(urlField) || !/^https?:$/.test(new URL(urlField).protocol)) {
+        throw new HookConfigError(`${path}: "url" must be an http(s) URL`);
+    }
+    return {
+        type: "http",
+        url: urlField,
+        ...(matcherField !== undefined ? { matcher: matcherField } : {}),
+        ...(timeoutField !== undefined ? { timeoutMs: timeoutField } : {}),
+    };
+}
+/** Strictly validate raw settings JSON into `HooksSettings`, throwing `HookConfigError` on the first problem. */
+export function parseHookSettings(raw) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        throw new HookConfigError("hooks: expected an object keyed by event name");
+    }
+    const parsed = {};
+    for (const [key, value] of Object.entries(raw)) {
+        if (!HOOK_EVENT_NAMES.includes(key)) {
+            throw new HookConfigError(`hooks."${key}": unknown hook event (v1 supports ${HOOK_EVENT_NAMES.join(", ")})`);
+        }
+        const event = key;
+        if (!Array.isArray(value)) {
+            throw new HookConfigError(`hooks.${event}: expected an array of handler configs`);
+        }
+        parsed[event] = value.map((entry, index) => parseHandlerConfig(event, index, entry));
+    }
+    return parsed;
+}
+function defaultHookHandlerFactory(config) {
+    return config.type === "command" ? commandHookHandler(config) : httpHookHandler(config);
+}
+/**
+ * Assemble the runtime, or return undefined when nothing is configured -- an
+ * absent key constructs nothing, so an unconfigured session spawns no
+ * subprocess and changes no behavior. `createHandler` is the seam tests use to
+ * inject scripted handlers instead of real command/HTTP execution.
+ */
+export function loadHookRuntime(settings, createHandler = defaultHookHandlerFactory) {
+    if (!settings)
+        return undefined;
+    const entries = [];
+    for (const event of HOOK_EVENT_NAMES) {
+        const configs = settings[event];
+        if (!configs || configs.length === 0)
+            continue;
+        for (const config of configs) {
+            const handler = createHandler(config, event);
+            entries.push({
+                event,
+                handler: config.matcher ? { ...handler, matchesTool: parseMatcher(config.matcher) } : handler,
+            });
+        }
+    }
+    if (entries.length === 0)
+        return undefined;
+    return createHookRuntime(entries);
+}
+//# sourceMappingURL=loader.js.map

package/dist/core/hooks/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../../src/core/hooks/loader.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,iBAAiB,EAAyB,MAAM,cAAc,CAAC;AACxE,OAAO,EACN,gBAAgB,EAMhB,mBAAmB,GACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACzC,YAAY,OAAe,EAAE;QAC5B,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAAA,CAC9B;CACD;AAED,MAAM,oBAAoB,GAAG,kBAAkB,CAAC;AAEhD;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,OAAe,EAAiC;IAC5E,MAAM,KAAK,GAAG,OAAO;SACnB,KAAK,CAAC,MAAM,CAAC;SACb,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,oBAAoB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;QACnF,MAAM,IAAI,eAAe,CAAC,oBAAoB,OAAO,oDAAoD,CAAC,CAAC;IAC5G,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAChC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;AAAA,CAC5C;AAED,SAAS,kBAAkB,CAAC,KAAoB,EAAE,KAAa,EAAE,GAAY,EAAqB;IACjG,MAAM,IAAI,GAAG,SAAS,KAAK,IAAI,KAAK,GAAG,CAAC;IACxC,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,sBAAsB,CAAC,CAAC;IAC1D,CAAC;IACD,MAAM,MAAM,GAAG,GAA8B,CAAC;IAC9C,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;IACzB,IAAI,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,MAAM,EAAE,CAAC;QAC3C,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,sCAAsC,CAAC,CAAC;IAC1E,CAAC;IACD,MAAM,OAAO,GACZ,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,CAAC,CAAC;IAC5G,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvC,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,oBAAoB,GAAG,+CAA+C,CAAC,CAAC;QAC1G,CAAC;IACF,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,CAAC;IACpC,IAAI,YAAY,KAAK,SAAS,EAAE,CAAC;QAChC,IAAI,OAAO,YAAY,KAAK,QAAQ,EAAE,CAAC;YACtC,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,8BAA8B,CAAC,CAAC;QAClE,CAAC;QACD,wEAAwE;QACxE,wDAAwD;QACxD,YAAY,CAAC,YAAY,CAAC,CAAC;IAC5B,CAAC;IACD,MAAM,YAAY,GAAG,MAAM,CAAC,SAAS,CAAC;IACtC,IACC,YAAY,KAAK,SAAS;QAC1B,CAAC,OAAO,YAAY,KAAK,QAAQ;YAChC,CAAC,MAAM,CAAC,QAAQ,CAAC,YAAY,CAAC;YAC9B,YAAY,IAAI,CAAC;YACjB,YAAY,GAAG,mBAAmB,CAAC,EACnC,CAAC;QACF,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,gDAAgD,mBAAmB,EAAE,CAAC,CAAC;IACzG,CAAC;IACD,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;QACxB,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChE,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,wCAAwC,CAAC,CAAC;QAC5E,CAAC;QACD,OAAO;YACN,IAAI,EAAE,SAAS;YACf,OAAO;YACP,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAChE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAClE,CAAC;IACH,CAAC;IACD,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC;IAC5B,IAAI,OAAO,QAAQ,KAAK,QAAQ,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,QAAQ,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9G,MAAM,IAAI,eAAe,CAAC,GAAG,IAAI,gCAAgC,CAAC,CAAC;IACpE,CAAC;IACD,OAAO;QACN,IAAI,EAAE,MAAM;QACZ,GAAG,EAAE,QAAQ;QACb,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAChE,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAClE,CAAC;AAAA,CACF;AAED,iHAAiH;AACjH,MAAM,UAAU,iBAAiB,CAAC,GAAY,EAAiB;IAC9D,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACnE,MAAM,IAAI,eAAe,CAAC,+CAA+C,CAAC,CAAC;IAC5E,CAAC;IACD,MAAM,MAAM,GAAkB,EAAE,CAAC;IACjC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAA8B,CAAC,EAAE,CAAC;QAC3E,IAAI,CAAE,gBAAsC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5D,MAAM,IAAI,eAAe,CAAC,UAAU,GAAG,sCAAsC,gBAAgB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC9G,CAAC;QACD,MAAM,KAAK,GAAG,GAAoB,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,eAAe,CAAC,SAAS,KAAK,wCAAwC,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC,kBAAkB,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;IACtF,CAAC;IACD,OAAO,MAAM,CAAC;AAAA,CACd;AAID,SAAS,yBAAyB,CAAC,MAAyB,EAAe;IAC1E,OAAO,MAAM,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC;AAAA,CACxF;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC9B,QAAmC,EACnC,aAAa,GAAuB,yBAAyB,EACnC;IAC1B,IAAI,CAAC,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,OAAO,GAAuB,EAAE,CAAC;IACvC,KAAK,MAAM,KAAK,IAAI,gBAAgB,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAC/C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC9B,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;YAC7C,OAAO,CAAC,IAAI,CAAC;gBACZ,KAAK;gBACL,OAAO,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,YAAY,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,OAAO;aAC7F,CAAC,CAAC;QACJ,CAAC;IACF,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,OAAO,iBAAiB,CAAC,OAAO,CAAC,CAAC;AAAA,CAClC","sourcesContent":["/**\n * Hook config parsing and runtime assembly. Parsing is strict and fails\n * closed: an invalid `hooks` key throws `HookConfigError` with the offending\n * path, and the session wiring lets that propagate -- a governance entry that\n * silently loads as nothing is a policy hole, so a malformed key refuses to\n * start the session instead (the permission-rule posture: a failed rule load\n * blocks rather than falls open).\n */\n\nimport { commandHookHandler } from \"./command-handler.ts\";\nimport { httpHookHandler } from \"./http-handler.ts\";\nimport { createHookRuntime, type RuntimeHookEntry } from \"./runtime.ts\";\nimport {\n\tHOOK_EVENT_NAMES,\n\ttype HookEventName,\n\ttype HookHandler,\n\ttype HookHandlerConfig,\n\ttype HookRuntime,\n\ttype HooksSettings,\n\tMAX_HOOK_TIMEOUT_MS,\n} from \"./types.ts\";\n\nexport class HookConfigError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = \"HookConfigError\";\n\t}\n}\n\nconst MATCHER_NAME_PATTERN = /^[A-Za-z0-9_-]+$/;\n\n/**\n * V1 matcher grammar: exact tool names joined by `|` or `,` with optional\n * whitespace, mirroring permission-rule matching. Regex matchers are a\n * recorded non-goal -- grammar creep is how config surfaces rot.\n */\nexport function parseMatcher(matcher: string): (toolName: string) => boolean {\n\tconst names = matcher\n\t\t.split(/[|,]/)\n\t\t.map((name) => name.trim())\n\t\t.filter((name) => name.length > 0);\n\tif (names.length === 0 || !names.every((name) => MATCHER_NAME_PATTERN.test(name))) {\n\t\tthrow new HookConfigError(`invalid matcher \"${matcher}\" (expected exact tool names joined by \"|\" or \",\")`);\n\t}\n\tconst accepted = new Set(names);\n\treturn (toolName) => accepted.has(toolName);\n}\n\nfunction parseHandlerConfig(event: HookEventName, index: number, raw: unknown): HookHandlerConfig {\n\tconst path = `hooks.${event}[${index}]`;\n\tif (typeof raw !== \"object\" || raw === null || Array.isArray(raw)) {\n\t\tthrow new HookConfigError(`${path}: expected an object`);\n\t}\n\tconst record = raw as Record<string, unknown>;\n\tconst type = record.type;\n\tif (type !== \"command\" && type !== \"http\") {\n\t\tthrow new HookConfigError(`${path}: \"type\" must be \"command\" or \"http\"`);\n\t}\n\tconst allowed =\n\t\ttype === \"command\" ? [\"type\", \"matcher\", \"command\", \"timeoutMs\"] : [\"type\", \"matcher\", \"url\", \"timeoutMs\"];\n\tfor (const key of Object.keys(record)) {\n\t\tif (!allowed.includes(key)) {\n\t\t\tthrow new HookConfigError(`${path}: unknown field \"${key}\" (a mistyped key would silently drop policy)`);\n\t\t}\n\t}\n\tconst matcherField = record.matcher;\n\tif (matcherField !== undefined) {\n\t\tif (typeof matcherField !== \"string\") {\n\t\t\tthrow new HookConfigError(`${path}: \"matcher\" must be a string`);\n\t\t}\n\t\t// Validate the grammar here, at load, so a bad matcher is rejected with\n\t\t// the config path even before any runtime is assembled.\n\t\tparseMatcher(matcherField);\n\t}\n\tconst timeoutField = record.timeoutMs;\n\tif (\n\t\ttimeoutField !== undefined &&\n\t\t(typeof timeoutField !== \"number\" ||\n\t\t\t!Number.isFinite(timeoutField) ||\n\t\t\ttimeoutField <= 0 ||\n\t\t\ttimeoutField > MAX_HOOK_TIMEOUT_MS)\n\t) {\n\t\tthrow new HookConfigError(`${path}: \"timeoutMs\" must be a number between 1 and ${MAX_HOOK_TIMEOUT_MS}`);\n\t}\n\tif (type === \"command\") {\n\t\tconst command = record.command;\n\t\tif (typeof command !== \"string\" || command.trim().length === 0) {\n\t\t\tthrow new HookConfigError(`${path}: \"command\" must be a non-empty string`);\n\t\t}\n\t\treturn {\n\t\t\ttype: \"command\",\n\t\t\tcommand,\n\t\t\t...(matcherField !== undefined ? { matcher: matcherField } : {}),\n\t\t\t...(timeoutField !== undefined ? { timeoutMs: timeoutField } : {}),\n\t\t};\n\t}\n\tconst urlField = record.url;\n\tif (typeof urlField !== \"string\" || !URL.canParse(urlField) || !/^https?:$/.test(new URL(urlField).protocol)) {\n\t\tthrow new HookConfigError(`${path}: \"url\" must be an http(s) URL`);\n\t}\n\treturn {\n\t\ttype: \"http\",\n\t\turl: urlField,\n\t\t...(matcherField !== undefined ? { matcher: matcherField } : {}),\n\t\t...(timeoutField !== undefined ? { timeoutMs: timeoutField } : {}),\n\t};\n}\n\n/** Strictly validate raw settings JSON into `HooksSettings`, throwing `HookConfigError` on the first problem. */\nexport function parseHookSettings(raw: unknown): HooksSettings {\n\tif (typeof raw !== \"object\" || raw === null || Array.isArray(raw)) {\n\t\tthrow new HookConfigError(\"hooks: expected an object keyed by event name\");\n\t}\n\tconst parsed: HooksSettings = {};\n\tfor (const [key, value] of Object.entries(raw as Record<string, unknown>)) {\n\t\tif (!(HOOK_EVENT_NAMES as readonly string[]).includes(key)) {\n\t\t\tthrow new HookConfigError(`hooks.\"${key}\": unknown hook event (v1 supports ${HOOK_EVENT_NAMES.join(\", \")})`);\n\t\t}\n\t\tconst event = key as HookEventName;\n\t\tif (!Array.isArray(value)) {\n\t\t\tthrow new HookConfigError(`hooks.${event}: expected an array of handler configs`);\n\t\t}\n\t\tparsed[event] = value.map((entry, index) => parseHandlerConfig(event, index, entry));\n\t}\n\treturn parsed;\n}\n\nexport type HookHandlerFactory = (config: HookHandlerConfig, event: HookEventName) => HookHandler;\n\nfunction defaultHookHandlerFactory(config: HookHandlerConfig): HookHandler {\n\treturn config.type === \"command\" ? commandHookHandler(config) : httpHookHandler(config);\n}\n\n/**\n * Assemble the runtime, or return undefined when nothing is configured -- an\n * absent key constructs nothing, so an unconfigured session spawns no\n * subprocess and changes no behavior. `createHandler` is the seam tests use to\n * inject scripted handlers instead of real command/HTTP execution.\n */\nexport function loadHookRuntime(\n\tsettings: HooksSettings | undefined,\n\tcreateHandler: HookHandlerFactory = defaultHookHandlerFactory,\n): HookRuntime | undefined {\n\tif (!settings) return undefined;\n\tconst entries: RuntimeHookEntry[] = [];\n\tfor (const event of HOOK_EVENT_NAMES) {\n\t\tconst configs = settings[event];\n\t\tif (!configs || configs.length === 0) continue;\n\t\tfor (const config of configs) {\n\t\t\tconst handler = createHandler(config, event);\n\t\t\tentries.push({\n\t\t\t\tevent,\n\t\t\t\thandler: config.matcher ? { ...handler, matchesTool: parseMatcher(config.matcher) } : handler,\n\t\t\t});\n\t\t}\n\t}\n\tif (entries.length === 0) return undefined;\n\treturn createHookRuntime(entries);\n}\n"]}

package/dist/core/hooks/runtime.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The hook runtime: an immutable handler list keyed by event, plus the two
+ * emission shapes the session seam consumes. Decision logic lives here so the
+ * restriction-only rule is enforced in exactly one place -- `decideToolCall`
+ * returns a block or nothing, never an allow that could bypass the gate.
+ */
+import type { HookEventName, HookHandler, HookRuntime } from "./types.ts";
+export interface RuntimeHookEntry {
+    event: HookEventName;
+    handler: HookHandler;
+}
+export declare function createHookRuntime(entries: RuntimeHookEntry[]): HookRuntime;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/core/hooks/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE1E,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,aAAa,CAAC;IACrB,OAAO,EAAE,WAAW,CAAC;CACrB;AAQD,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,WAAW,CA6C1E","sourcesContent":["/**\n * The hook runtime: an immutable handler list keyed by event, plus the two\n * emission shapes the session seam consumes. Decision logic lives here so the\n * restriction-only rule is enforced in exactly one place -- `decideToolCall`\n * returns a block or nothing, never an allow that could bypass the gate.\n */\n\nimport type { HookEventName, HookHandler, HookRuntime } from \"./types.ts\";\n\nexport interface RuntimeHookEntry {\n\tevent: HookEventName;\n\thandler: HookHandler;\n}\n\nfunction accepted(handler: HookHandler, toolName: string | undefined): boolean {\n\tif (!handler.matchesTool) return true;\n\tif (toolName === undefined) return true;\n\treturn handler.matchesTool(toolName);\n}\n\nexport function createHookRuntime(entries: RuntimeHookEntry[]): HookRuntime {\n\tconst byEvent = new Map<HookEventName, HookHandler[]>();\n\tfor (const entry of entries) {\n\t\tconst handlers = byEvent.get(entry.event);\n\t\tif (handlers) {\n\t\t\thandlers.push(entry.handler);\n\t\t} else {\n\t\t\tbyEvent.set(entry.event, [entry.handler]);\n\t\t}\n\t}\n\n\treturn {\n\t\thasHandlers(event) {\n\t\t\treturn (byEvent.get(event)?.length ?? 0) > 0;\n\t\t},\n\t\thandlersFor(event) {\n\t\t\treturn byEvent.get(event) ?? [];\n\t\t},\n\t\tasync decideToolCall(toolName, payload) {\n\t\t\tfor (const handler of byEvent.get(\"tool_call\") ?? []) {\n\t\t\t\tif (!accepted(handler, toolName)) continue;\n\t\t\t\tconst outcome = await handler.execute(payload);\n\t\t\t\tif (!outcome.ok) {\n\t\t\t\t\t// Fail closed: a hook that cannot run must not widen authority.\n\t\t\t\t\t// This is the spawn-failure and timeout path too.\n\t\t\t\t\treturn { block: true, reason: outcome.warning };\n\t\t\t\t}\n\t\t\t\t// Restriction-only (spec): `block` short-circuits; `allow` and\n\t\t\t\t// `ask` fall through so the permission gate stays the last check.\n\t\t\t\tif (outcome.decision?.decision === \"block\") {\n\t\t\t\t\treturn { block: true, reason: outcome.decision.reason ?? \"blocked by a declarative hook\" };\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn undefined;\n\t\t},\n\t\tasync emitObserve(event, payload) {\n\t\t\tfor (const handler of byEvent.get(event) ?? []) {\n\t\t\t\tif (!accepted(handler, payload.toolName)) continue;\n\t\t\t\t// Observe-only: awaited for ordering, but a failure is swallowed\n\t\t\t\t// because no decision is read from these events.\n\t\t\t\tconst outcome = await handler.execute(payload);\n\t\t\t\tif (!outcome.ok) continue;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/hooks/runtime.js

@@ -0,0 +1,63 @@
+/**
+ * The hook runtime: an immutable handler list keyed by event, plus the two
+ * emission shapes the session seam consumes. Decision logic lives here so the
+ * restriction-only rule is enforced in exactly one place -- `decideToolCall`
+ * returns a block or nothing, never an allow that could bypass the gate.
+ */
+function accepted(handler, toolName) {
+    if (!handler.matchesTool)
+        return true;
+    if (toolName === undefined)
+        return true;
+    return handler.matchesTool(toolName);
+}
+export function createHookRuntime(entries) {
+    const byEvent = new Map();
+    for (const entry of entries) {
+        const handlers = byEvent.get(entry.event);
+        if (handlers) {
+            handlers.push(entry.handler);
+        }
+        else {
+            byEvent.set(entry.event, [entry.handler]);
+        }
+    }
+    return {
+        hasHandlers(event) {
+            return (byEvent.get(event)?.length ?? 0) > 0;
+        },
+        handlersFor(event) {
+            return byEvent.get(event) ?? [];
+        },
+        async decideToolCall(toolName, payload) {
+            for (const handler of byEvent.get("tool_call") ?? []) {
+                if (!accepted(handler, toolName))
+                    continue;
+                const outcome = await handler.execute(payload);
+                if (!outcome.ok) {
+                    // Fail closed: a hook that cannot run must not widen authority.
+                    // This is the spawn-failure and timeout path too.
+                    return { block: true, reason: outcome.warning };
+                }
+                // Restriction-only (spec): `block` short-circuits; `allow` and
+                // `ask` fall through so the permission gate stays the last check.
+                if (outcome.decision?.decision === "block") {
+                    return { block: true, reason: outcome.decision.reason ?? "blocked by a declarative hook" };
+                }
+            }
+            return undefined;
+        },
+        async emitObserve(event, payload) {
+            for (const handler of byEvent.get(event) ?? []) {
+                if (!accepted(handler, payload.toolName))
+                    continue;
+                // Observe-only: awaited for ordering, but a failure is swallowed
+                // because no decision is read from these events.
+                const outcome = await handler.execute(payload);
+                if (!outcome.ok)
+                    continue;
+            }
+        },
+    };
+}
+//# sourceMappingURL=runtime.js.map

package/dist/core/hooks/runtime.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.js","sourceRoot":"","sources":["../../../src/core/hooks/runtime.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH,SAAS,QAAQ,CAAC,OAAoB,EAAE,QAA4B,EAAW;IAC9E,IAAI,CAAC,OAAO,CAAC,WAAW;QAAE,OAAO,IAAI,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;AAAA,CACrC;AAED,MAAM,UAAU,iBAAiB,CAAC,OAA2B,EAAe;IAC3E,MAAM,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IACxD,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC1C,IAAI,QAAQ,EAAE,CAAC;YACd,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAC9B,CAAC;aAAM,CAAC;YACP,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC;QAC3C,CAAC;IACF,CAAC;IAED,OAAO;QACN,WAAW,CAAC,KAAK,EAAE;YAClB,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC;QAAA,CAC7C;QACD,WAAW,CAAC,KAAK,EAAE;YAClB,OAAO,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QAAA,CAChC;QACD,KAAK,CAAC,cAAc,CAAC,QAAQ,EAAE,OAAO,EAAE;YACvC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,EAAE,CAAC;gBACtD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC;oBAAE,SAAS;gBAC3C,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC/C,IAAI,CAAC,OAAO,CAAC,EAAE,EAAE,CAAC;oBACjB,gEAAgE;oBAChE,kDAAkD;oBAClD,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;gBACjD,CAAC;gBACD,+DAA+D;gBAC/D,kEAAkE;gBAClE,IAAI,OAAO,CAAC,QAAQ,EAAE,QAAQ,KAAK,OAAO,EAAE,CAAC;oBAC5C,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,MAAM,IAAI,+BAA+B,EAAE,CAAC;gBAC5F,CAAC;YACF,CAAC;YACD,OAAO,SAAS,CAAC;QAAA,CACjB;QACD,KAAK,CAAC,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE;YACjC,KAAK,MAAM,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;gBAChD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC;oBAAE,SAAS;gBACnD,iEAAiE;gBACjE,iDAAiD;gBACjD,MAAM,OAAO,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;gBAC/C,IAAI,CAAC,OAAO,CAAC,EAAE;oBAAE,SAAS;YAC3B,CAAC;QAAA,CACD;KACD,CAAC;AAAA,CACF","sourcesContent":["/**\n * The hook runtime: an immutable handler list keyed by event, plus the two\n * emission shapes the session seam consumes. Decision logic lives here so the\n * restriction-only rule is enforced in exactly one place -- `decideToolCall`\n * returns a block or nothing, never an allow that could bypass the gate.\n */\n\nimport type { HookEventName, HookHandler, HookRuntime } from \"./types.ts\";\n\nexport interface RuntimeHookEntry {\n\tevent: HookEventName;\n\thandler: HookHandler;\n}\n\nfunction accepted(handler: HookHandler, toolName: string | undefined): boolean {\n\tif (!handler.matchesTool) return true;\n\tif (toolName === undefined) return true;\n\treturn handler.matchesTool(toolName);\n}\n\nexport function createHookRuntime(entries: RuntimeHookEntry[]): HookRuntime {\n\tconst byEvent = new Map<HookEventName, HookHandler[]>();\n\tfor (const entry of entries) {\n\t\tconst handlers = byEvent.get(entry.event);\n\t\tif (handlers) {\n\t\t\thandlers.push(entry.handler);\n\t\t} else {\n\t\t\tbyEvent.set(entry.event, [entry.handler]);\n\t\t}\n\t}\n\n\treturn {\n\t\thasHandlers(event) {\n\t\t\treturn (byEvent.get(event)?.length ?? 0) > 0;\n\t\t},\n\t\thandlersFor(event) {\n\t\t\treturn byEvent.get(event) ?? [];\n\t\t},\n\t\tasync decideToolCall(toolName, payload) {\n\t\t\tfor (const handler of byEvent.get(\"tool_call\") ?? []) {\n\t\t\t\tif (!accepted(handler, toolName)) continue;\n\t\t\t\tconst outcome = await handler.execute(payload);\n\t\t\t\tif (!outcome.ok) {\n\t\t\t\t\t// Fail closed: a hook that cannot run must not widen authority.\n\t\t\t\t\t// This is the spawn-failure and timeout path too.\n\t\t\t\t\treturn { block: true, reason: outcome.warning };\n\t\t\t\t}\n\t\t\t\t// Restriction-only (spec): `block` short-circuits; `allow` and\n\t\t\t\t// `ask` fall through so the permission gate stays the last check.\n\t\t\t\tif (outcome.decision?.decision === \"block\") {\n\t\t\t\t\treturn { block: true, reason: outcome.decision.reason ?? \"blocked by a declarative hook\" };\n\t\t\t\t}\n\t\t\t}\n\t\t\treturn undefined;\n\t\t},\n\t\tasync emitObserve(event, payload) {\n\t\t\tfor (const handler of byEvent.get(event) ?? []) {\n\t\t\t\tif (!accepted(handler, payload.toolName)) continue;\n\t\t\t\t// Observe-only: awaited for ordering, but a failure is swallowed\n\t\t\t\t// because no decision is read from these events.\n\t\t\t\tconst outcome = await handler.execute(payload);\n\t\t\t\tif (!outcome.ok) continue;\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/hooks/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Declarative hooks (spec 2026-08-31-declarative-hooks): a settings-file path
+ * onto the extension event catalog, for operators who will never author a
+ * TypeScript extension. Version one maps five events onto command and HTTP
+ * handlers, with decisions read only from `tool_call`.
+ *
+ * The decision vocabulary is restriction-only: `block` short-circuits, `ask`
+ * defers to the permission gate, and `allow` is recorded but never bypasses
+ * the gate. A hook can narrow what runs, never widen it -- which is what makes
+ * trust-gated project-scope hooks safe where project-sandbox profiles are not
+ * (ADR 0016).
+ */
+export declare const HOOK_EVENT_NAMES: readonly ["tool_call", "tool_result", "session_start", "turn_end", "session_before_compact"];
+export type HookEventName = (typeof HOOK_EVENT_NAMES)[number];
+export interface HookCommandHandlerConfig {
+    type: "command";
+    /** Tool-name exact or `|`/`,`-separated list; absent matches every tool. Only consulted for events that carry a tool name. */
+    matcher?: string;
+    /** Shell command; the event payload arrives as JSON on stdin, the decision as JSON on stdout. */
+    command: string;
+    /** Default 10s (DEFAULT_HOOK_TIMEOUT_MS). A handler that outlives its timeout fails closed on `tool_call`. */
+    timeoutMs?: number;
+}
+export interface HookHttpHandlerConfig {
+    type: "http";
+    matcher?: string;
+    /** The event payload is POSTed here; the decision is read from the 200 response body. URLs come from settings only -- never environment interpolation. */
+    url: string;
+    timeoutMs?: number;
+}
+export type HookHandlerConfig = HookCommandHandlerConfig | HookHttpHandlerConfig;
+export type HooksSettings = Partial<Record<HookEventName, HookHandlerConfig[]>>;
+export interface HookDecision {
+    decision: "allow" | "block" | "ask";
+    reason?: string;
+}
+export interface HookEventPayload {
+    type: HookEventName;
+    toolName?: string;
+    toolCallId?: string;
+    input?: unknown;
+    reason?: string;
+}
+export type HookOutcome = {
+    ok: true;
+    decision?: HookDecision;
+    warning?: string;
+} | {
+    ok: false;
+    warning: string;
+};
+export interface HookHandler {
+    /** Absent on a handler means it matches every tool. */
+    matchesTool?(toolName: string): boolean;
+    execute(payload: HookEventPayload): Promise<HookOutcome>;
+}
+/** What a `tool_call` hook hands back to the session: the same shape the beforeToolCall seam already consumes. */
+export interface HookToolCallBlock {
+    block: true;
+    reason: string;
+}
+export interface HookRuntime {
+    hasHandlers(event: HookEventName): boolean;
+    /** Test and diagnostic accessor; the runtime never mutates the handlers it holds. */
+    handlersFor(event: HookEventName): readonly HookHandler[];
+    /**
+     * `tool_call` decisions, restriction-only: `block` returns a block for the
+     * seam to consume, every other outcome (allow, ask, no decision) returns
+     * undefined so the permission gate still evaluates the call. A handler that
+     * fails or times out fails closed.
+     */
+    decideToolCall(toolName: string, payload: HookEventPayload): Promise<HookToolCallBlock | undefined>;
+    /**
+     * Observe-only emission for `tool_result` and lifecycle events: handlers are
+     * awaited in order, failures are swallowed, and no decision is ever read.
+     */
+    emitObserve(event: HookEventName, payload: HookEventPayload): Promise<void>;
+}
+/** Default per-handler timeout. A hung formatter must not stall the loop indefinitely. */
+export declare const DEFAULT_HOOK_TIMEOUT_MS = 10000;
+/** Hard cap on configured timeouts. */
+export declare const MAX_HOOK_TIMEOUT_MS = 60000;
+//# sourceMappingURL=types.d.ts.map

package/dist/core/hooks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,gBAAgB,8FAMnB,CAAC;AACX,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAE9D,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,SAAS,CAAC;IAChB,8HAA8H;IAC9H,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,iGAAiG;IACjG,OAAO,EAAE,MAAM,CAAC;IAChB,8GAA8G;IAC9G,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0JAA0J;IAC1J,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,iBAAiB,GAAG,wBAAwB,GAAG,qBAAqB,CAAC;AAEjF,MAAM,MAAM,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC,aAAa,EAAE,iBAAiB,EAAE,CAAC,CAAC,CAAC;AAEhF,MAAM,WAAW,YAAY;IAC5B,QAAQ,EAAE,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,WAAW,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,YAAY,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnH,MAAM,WAAW,WAAW;IAC3B,uDAAuD;IACvD,WAAW,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;CACzD;AAED,kHAAkH;AAClH,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,IAAI,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC3B,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC;IAC3C,qFAAqF;IACrF,WAAW,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,WAAW,EAAE,CAAC;IAC1D;;;;;OAKG;IACH,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAAC;IACpG;;;OAGG;IACH,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5E;AAED,0FAA0F;AAC1F,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAC9C,uCAAuC;AACvC,eAAO,MAAM,mBAAmB,QAAS,CAAC","sourcesContent":["/**\n * Declarative hooks (spec 2026-08-31-declarative-hooks): a settings-file path\n * onto the extension event catalog, for operators who will never author a\n * TypeScript extension. Version one maps five events onto command and HTTP\n * handlers, with decisions read only from `tool_call`.\n *\n * The decision vocabulary is restriction-only: `block` short-circuits, `ask`\n * defers to the permission gate, and `allow` is recorded but never bypasses\n * the gate. A hook can narrow what runs, never widen it -- which is what makes\n * trust-gated project-scope hooks safe where project-sandbox profiles are not\n * (ADR 0016).\n */\n\nexport const HOOK_EVENT_NAMES = [\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"session_start\",\n\t\"turn_end\",\n\t\"session_before_compact\",\n] as const;\nexport type HookEventName = (typeof HOOK_EVENT_NAMES)[number];\n\nexport interface HookCommandHandlerConfig {\n\ttype: \"command\";\n\t/** Tool-name exact or `|`/`,`-separated list; absent matches every tool. Only consulted for events that carry a tool name. */\n\tmatcher?: string;\n\t/** Shell command; the event payload arrives as JSON on stdin, the decision as JSON on stdout. */\n\tcommand: string;\n\t/** Default 10s (DEFAULT_HOOK_TIMEOUT_MS). A handler that outlives its timeout fails closed on `tool_call`. */\n\ttimeoutMs?: number;\n}\n\nexport interface HookHttpHandlerConfig {\n\ttype: \"http\";\n\tmatcher?: string;\n\t/** The event payload is POSTed here; the decision is read from the 200 response body. URLs come from settings only -- never environment interpolation. */\n\turl: string;\n\ttimeoutMs?: number;\n}\n\nexport type HookHandlerConfig = HookCommandHandlerConfig | HookHttpHandlerConfig;\n\nexport type HooksSettings = Partial<Record<HookEventName, HookHandlerConfig[]>>;\n\nexport interface HookDecision {\n\tdecision: \"allow\" | \"block\" | \"ask\";\n\treason?: string;\n}\n\nexport interface HookEventPayload {\n\ttype: HookEventName;\n\ttoolName?: string;\n\ttoolCallId?: string;\n\tinput?: unknown;\n\treason?: string;\n}\n\nexport type HookOutcome = { ok: true; decision?: HookDecision; warning?: string } | { ok: false; warning: string };\n\nexport interface HookHandler {\n\t/** Absent on a handler means it matches every tool. */\n\tmatchesTool?(toolName: string): boolean;\n\texecute(payload: HookEventPayload): Promise<HookOutcome>;\n}\n\n/** What a `tool_call` hook hands back to the session: the same shape the beforeToolCall seam already consumes. */\nexport interface HookToolCallBlock {\n\tblock: true;\n\treason: string;\n}\n\nexport interface HookRuntime {\n\thasHandlers(event: HookEventName): boolean;\n\t/** Test and diagnostic accessor; the runtime never mutates the handlers it holds. */\n\thandlersFor(event: HookEventName): readonly HookHandler[];\n\t/**\n\t * `tool_call` decisions, restriction-only: `block` returns a block for the\n\t * seam to consume, every other outcome (allow, ask, no decision) returns\n\t * undefined so the permission gate still evaluates the call. A handler that\n\t * fails or times out fails closed.\n\t */\n\tdecideToolCall(toolName: string, payload: HookEventPayload): Promise<HookToolCallBlock | undefined>;\n\t/**\n\t * Observe-only emission for `tool_result` and lifecycle events: handlers are\n\t * awaited in order, failures are swallowed, and no decision is ever read.\n\t */\n\temitObserve(event: HookEventName, payload: HookEventPayload): Promise<void>;\n}\n\n/** Default per-handler timeout. A hung formatter must not stall the loop indefinitely. */\nexport const DEFAULT_HOOK_TIMEOUT_MS = 10_000;\n/** Hard cap on configured timeouts. */\nexport const MAX_HOOK_TIMEOUT_MS = 60_000;\n"]}

package/dist/core/hooks/types.js

@@ -0,0 +1,24 @@
+/**
+ * Declarative hooks (spec 2026-08-31-declarative-hooks): a settings-file path
+ * onto the extension event catalog, for operators who will never author a
+ * TypeScript extension. Version one maps five events onto command and HTTP
+ * handlers, with decisions read only from `tool_call`.
+ *
+ * The decision vocabulary is restriction-only: `block` short-circuits, `ask`
+ * defers to the permission gate, and `allow` is recorded but never bypasses
+ * the gate. A hook can narrow what runs, never widen it -- which is what makes
+ * trust-gated project-scope hooks safe where project-sandbox profiles are not
+ * (ADR 0016).
+ */
+export const HOOK_EVENT_NAMES = [
+    "tool_call",
+    "tool_result",
+    "session_start",
+    "turn_end",
+    "session_before_compact",
+];
+/** Default per-handler timeout. A hung formatter must not stall the loop indefinitely. */
+export const DEFAULT_HOOK_TIMEOUT_MS = 10_000;
+/** Hard cap on configured timeouts. */
+export const MAX_HOOK_TIMEOUT_MS = 60_000;
+//# sourceMappingURL=types.js.map

package/dist/core/hooks/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/hooks/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B,WAAW;IACX,aAAa;IACb,eAAe;IACf,UAAU;IACV,wBAAwB;CACf,CAAC;AAsEX,0FAA0F;AAC1F,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC;AAC9C,uCAAuC;AACvC,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC","sourcesContent":["/**\n * Declarative hooks (spec 2026-08-31-declarative-hooks): a settings-file path\n * onto the extension event catalog, for operators who will never author a\n * TypeScript extension. Version one maps five events onto command and HTTP\n * handlers, with decisions read only from `tool_call`.\n *\n * The decision vocabulary is restriction-only: `block` short-circuits, `ask`\n * defers to the permission gate, and `allow` is recorded but never bypasses\n * the gate. A hook can narrow what runs, never widen it -- which is what makes\n * trust-gated project-scope hooks safe where project-sandbox profiles are not\n * (ADR 0016).\n */\n\nexport const HOOK_EVENT_NAMES = [\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"session_start\",\n\t\"turn_end\",\n\t\"session_before_compact\",\n] as const;\nexport type HookEventName = (typeof HOOK_EVENT_NAMES)[number];\n\nexport interface HookCommandHandlerConfig {\n\ttype: \"command\";\n\t/** Tool-name exact or `|`/`,`-separated list; absent matches every tool. Only consulted for events that carry a tool name. */\n\tmatcher?: string;\n\t/** Shell command; the event payload arrives as JSON on stdin, the decision as JSON on stdout. */\n\tcommand: string;\n\t/** Default 10s (DEFAULT_HOOK_TIMEOUT_MS). A handler that outlives its timeout fails closed on `tool_call`. */\n\ttimeoutMs?: number;\n}\n\nexport interface HookHttpHandlerConfig {\n\ttype: \"http\";\n\tmatcher?: string;\n\t/** The event payload is POSTed here; the decision is read from the 200 response body. URLs come from settings only -- never environment interpolation. */\n\turl: string;\n\ttimeoutMs?: number;\n}\n\nexport type HookHandlerConfig = HookCommandHandlerConfig | HookHttpHandlerConfig;\n\nexport type HooksSettings = Partial<Record<HookEventName, HookHandlerConfig[]>>;\n\nexport interface HookDecision {\n\tdecision: \"allow\" | \"block\" | \"ask\";\n\treason?: string;\n}\n\nexport interface HookEventPayload {\n\ttype: HookEventName;\n\ttoolName?: string;\n\ttoolCallId?: string;\n\tinput?: unknown;\n\treason?: string;\n}\n\nexport type HookOutcome = { ok: true; decision?: HookDecision; warning?: string } | { ok: false; warning: string };\n\nexport interface HookHandler {\n\t/** Absent on a handler means it matches every tool. */\n\tmatchesTool?(toolName: string): boolean;\n\texecute(payload: HookEventPayload): Promise<HookOutcome>;\n}\n\n/** What a `tool_call` hook hands back to the session: the same shape the beforeToolCall seam already consumes. */\nexport interface HookToolCallBlock {\n\tblock: true;\n\treason: string;\n}\n\nexport interface HookRuntime {\n\thasHandlers(event: HookEventName): boolean;\n\t/** Test and diagnostic accessor; the runtime never mutates the handlers it holds. */\n\thandlersFor(event: HookEventName): readonly HookHandler[];\n\t/**\n\t * `tool_call` decisions, restriction-only: `block` returns a block for the\n\t * seam to consume, every other outcome (allow, ask, no decision) returns\n\t * undefined so the permission gate still evaluates the call. A handler that\n\t * fails or times out fails closed.\n\t */\n\tdecideToolCall(toolName: string, payload: HookEventPayload): Promise<HookToolCallBlock | undefined>;\n\t/**\n\t * Observe-only emission for `tool_result` and lifecycle events: handlers are\n\t * awaited in order, failures are swallowed, and no decision is ever read.\n\t */\n\temitObserve(event: HookEventName, payload: HookEventPayload): Promise<void>;\n}\n\n/** Default per-handler timeout. A hung formatter must not stall the loop indefinitely. */\nexport const DEFAULT_HOOK_TIMEOUT_MS = 10_000;\n/** Hard cap on configured timeouts. */\nexport const MAX_HOOK_TIMEOUT_MS = 60_000;\n"]}

package/dist/core/mcp/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Reads the ecosystem-standard `{ "mcpServers": { … } }` shape from a project
+ * `.mcp.json` and a global `mcp.json`, project winning per server name.
+ *
+ * Every failure degrades. A malformed file yields no servers and one diagnostic; a
+ * malformed entry drops itself and leaves its siblings intact. A config file is the
+ * first thing a user hand-edits, so a parse error must never take the session down.
+ */
+import { type McpConfig } from "./types.ts";
+export declare const PROJECT_CONFIG_FILENAME = ".mcp.json";
+export declare function globalMcpConfigPath(): string;
+export declare function loadMcpConfig(options?: {
+    projectPath?: string;
+    globalPath?: string;
+}): McpConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/core/mcp/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../../src/core/mcp/config.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,OAAO,EAGN,KAAK,SAAS,EAKd,MAAM,YAAY,CAAC;AAIpB,eAAO,MAAM,uBAAuB,cAAc,CAAC;AAEnD,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAgJD,wBAAgB,aAAa,CAAC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAO,GAAG,SAAS,CAYpG","sourcesContent":["/**\n * Reads the ecosystem-standard `{ \"mcpServers\": { … } }` shape from a project\n * `.mcp.json` and a global `mcp.json`, project winning per server name.\n *\n * Every failure degrades. A malformed file yields no servers and one diagnostic; a\n * malformed entry drops itself and leaves its siblings intact. A config file is the\n * first thing a user hand-edits, so a parse error must never take the session down.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { CONFIG_DIR_NAME } from \"../../config.ts\";\nimport { ALL_CAPABILITIES, type Capability } from \"../tools/contract.ts\";\nimport {\n\tDEFAULT_IDLE_TIMEOUT_MINUTES,\n\tDEFAULT_LIFECYCLE,\n\ttype McpConfig,\n\ttype McpConfigDiagnostic,\n\ttype McpLifecycle,\n\ttype McpServerConfig,\n\ttype McpTransport,\n} from \"./types.ts\";\n\nconst LIFECYCLES: readonly McpLifecycle[] = [\"lazy\", \"eager\", \"keep-alive\", \"lazy-keep-alive\"];\n\nexport const PROJECT_CONFIG_FILENAME = \".mcp.json\";\n\nexport function globalMcpConfigPath(): string {\n\treturn join(homedir(), CONFIG_DIR_NAME, \"mcp.json\");\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction stringRecord(value: unknown): Record<string, string> {\n\tif (!isRecord(value)) return {};\n\tconst out: Record<string, string> = {};\n\tfor (const [key, item] of Object.entries(value)) {\n\t\tif (typeof item === \"string\") out[key] = item;\n\t}\n\treturn out;\n}\n\nfunction stringArray(value: unknown): string[] {\n\treturn Array.isArray(value) ? value.filter((item): item is string => typeof item === \"string\") : [];\n}\n\nfunction parseTransport(entry: Record<string, unknown>): McpTransport | string {\n\tconst command = typeof entry.command === \"string\" ? entry.command : undefined;\n\tconst url = typeof entry.url === \"string\" ? entry.url : undefined;\n\n\tif (command && url) return \"declares both command and url; exactly one is required\";\n\tif (command) {\n\t\treturn {\n\t\t\tkind: \"stdio\",\n\t\t\tcommand,\n\t\t\targs: stringArray(entry.args),\n\t\t\tenv: stringRecord(entry.env),\n\t\t\tcwd: typeof entry.cwd === \"string\" ? entry.cwd : undefined,\n\t\t};\n\t}\n\tif (url) {\n\t\treturn {\n\t\t\tkind: \"http\",\n\t\t\turl,\n\t\t\theaders: stringRecord(entry.headers),\n\t\t\tbearerTokenEnv: typeof entry.bearerTokenEnv === \"string\" ? entry.bearerTokenEnv : undefined,\n\t\t};\n\t}\n\treturn \"declares neither command nor url\";\n}\n\n/**\n * An absent `capabilities` is the common case, not an edge case: a config pasted from\n * another host carries no Apex-specific field. Those servers get the full set, which\n * keeps them classified (never `UNCLASSIFIED`) without narrowing anything the user\n * did not ask to narrow.\n */\nfunction parseCapabilities(entry: Record<string, unknown>, report: (message: string) => void): ReadonlySet<Capability> {\n\tif (!(\"capabilities\" in entry)) return ALL_CAPABILITIES;\n\tif (!Array.isArray(entry.capabilities)) {\n\t\treport(\"capabilities is not an array; falling back to the full capability set\");\n\t\treturn ALL_CAPABILITIES;\n\t}\n\n\tconst resolved = new Set<Capability>();\n\tconst unknown: string[] = [];\n\tfor (const candidate of entry.capabilities) {\n\t\tif (typeof candidate === \"string\" && ALL_CAPABILITIES.has(candidate as Capability)) {\n\t\t\tresolved.add(candidate as Capability);\n\t\t} else {\n\t\t\tunknown.push(String(candidate));\n\t\t}\n\t}\n\tif (unknown.length > 0) report(`unknown capabilities dropped: ${unknown.join(\", \")}`);\n\treturn resolved;\n}\n\nfunction parseLifecycle(entry: Record<string, unknown>, report: (message: string) => void): McpLifecycle {\n\tconst value = entry.lifecycle;\n\tif (value === undefined) return DEFAULT_LIFECYCLE;\n\tif (typeof value === \"string\" && LIFECYCLES.includes(value as McpLifecycle)) return value as McpLifecycle;\n\treport(`unknown lifecycle ${JSON.stringify(value)}; using ${DEFAULT_LIFECYCLE}`);\n\treturn DEFAULT_LIFECYCLE;\n}\n\nfunction parseIdleTimeout(entry: Record<string, unknown>): number {\n\tconst value = entry.idleTimeout;\n\treturn typeof value === \"number\" && Number.isFinite(value) && value >= 0 ? value : DEFAULT_IDLE_TIMEOUT_MINUTES;\n}\n\nfunction parseAuth(\n\tentry: Record<string, unknown>,\n\ttransport: McpTransport,\n\treport: (message: string) => void,\n): \"oauth\" | undefined {\n\tconst value = entry.auth;\n\tif (value === undefined) return undefined;\n\tif (transport.kind !== \"http\") {\n\t\treport(\"auth is only supported on HTTP servers; ignoring\");\n\t\treturn undefined;\n\t}\n\tif (value === \"oauth\") return \"oauth\";\n\treport(`unknown auth ${JSON.stringify(value)}; only \"oauth\" is supported; ignoring`);\n\treturn undefined;\n}\n\nfunction readServers(path: string, diagnostics: McpConfigDiagnostic[]): Map<string, McpServerConfig> {\n\tconst servers = new Map<string, McpServerConfig>();\n\tif (!existsSync(path)) return servers;\n\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(readFileSync(path, \"utf-8\"));\n\t} catch (error) {\n\t\tdiagnostics.push({\n\t\t\tpath,\n\t\t\tserver: undefined,\n\t\t\tmessage: `could not be parsed as JSON: ${error instanceof Error ? error.message : String(error)}`,\n\t\t});\n\t\treturn servers;\n\t}\n\n\tif (!isRecord(parsed) || !isRecord(parsed.mcpServers)) {\n\t\tdiagnostics.push({ path, server: undefined, message: \"has no mcpServers object\" });\n\t\treturn servers;\n\t}\n\n\tfor (const [name, raw] of Object.entries(parsed.mcpServers)) {\n\t\tif (!isRecord(raw)) {\n\t\t\tdiagnostics.push({ path, server: name, message: \"entry is not an object\" });\n\t\t\tcontinue;\n\t\t}\n\t\tconst transport = parseTransport(raw);\n\t\tif (typeof transport === \"string\") {\n\t\t\tdiagnostics.push({ path, server: name, message: transport });\n\t\t\tcontinue;\n\t\t}\n\t\tconst report = (message: string) => diagnostics.push({ path, server: name, message });\n\t\tservers.set(name, {\n\t\t\tname,\n\t\t\ttransport,\n\t\t\tauth: parseAuth(raw, transport, report),\n\t\t\tcapabilities: parseCapabilities(raw, report),\n\t\t\tlifecycle: parseLifecycle(raw, report),\n\t\t\tidleTimeoutMinutes: parseIdleTimeout(raw),\n\t\t});\n\t}\n\n\treturn servers;\n}\n\nexport function loadMcpConfig(options: { projectPath?: string; globalPath?: string } = {}): McpConfig {\n\tconst diagnostics: McpConfigDiagnostic[] = [];\n\tconst globalPath = options.globalPath ?? globalMcpConfigPath();\n\n\tconst servers = readServers(globalPath, diagnostics);\n\tif (options.projectPath) {\n\t\tfor (const [name, config] of readServers(options.projectPath, diagnostics)) {\n\t\t\tservers.set(name, config);\n\t\t}\n\t}\n\n\treturn { servers, diagnostics };\n}\n"]}