apex-code 0.0.1-alpha.8 → 0.0.4

package/dist/core/hooks/command-handler.js

@@ -0,0 +1,112 @@
+import { spawn } from "node:child_process";
+import { DEFAULT_HOOK_TIMEOUT_MS, } from "./types.js";
+// A runaway formatter can emit megabytes; the decision that matters is at the
+// start, so cap what we retain rather than what the child may write.
+const MAX_HOOK_OUTPUT_CHARS = 1_000_000;
+function truncate(text) {
+    return text.length > 200 ? `${text.slice(0, 200)}...` : text;
+}
+/**
+ * Shared decision parsing for command stdout and HTTP response bodies.
+ * Non-JSON output, a non-object, or an unknown decision value is "no decision"
+ * plus a warning -- never an allow (spec, Risks).
+ */
+export function parseHookDecisionOutput(text) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0)
+        return { ok: true };
+    let parsed;
+    try {
+        parsed = JSON.parse(trimmed);
+    }
+    catch {
+        return { ok: true, warning: `hook output was not valid JSON: ${truncate(trimmed)}` };
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        return { ok: true, warning: `hook output was not a JSON object: ${truncate(trimmed)}` };
+    }
+    const decision = parsed.decision;
+    if (decision === undefined)
+        return { ok: true };
+    if (decision !== "allow" && decision !== "block" && decision !== "ask") {
+        return { ok: true, warning: `hook output had an unknown decision: ${truncate(String(decision))}` };
+    }
+    const reason = parsed.reason;
+    return {
+        ok: true,
+        decision: { decision, ...(typeof reason === "string" && reason.length > 0 ? { reason } : {}) },
+    };
+}
+/**
+ * A command handler runs through the platform shell (`sh -c`, PowerShell on
+ * Windows) with the event payload on stdin and its decision on stdout.
+ *
+ * Exit-code table (behavioral reference:
+ * docs/research/2026-08-31-harness-landscape.md § 2.1): exit 0 + JSON = that
+ * decision; exit 0 + no output = no decision; exit 2 = block with stderr as
+ * the reason; any other nonzero exit (and spawn failure, and timeout) is a
+ * failure outcome, which the runtime turns into a fail-closed block.
+ */
+export function commandHookHandler(config) {
+    const timeoutMs = config.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+    const commandRef = truncate(config.command);
+    return {
+        async execute(payload) {
+            const shell = process.platform === "win32" ? "powershell.exe" : "sh";
+            const args = process.platform === "win32" ? ["-NoProfile", "-Command", config.command] : ["-c", config.command];
+            return await new Promise((resolve) => {
+                const child = spawn(shell, args, { stdio: ["pipe", "pipe", "pipe"] });
+                let stdout = "";
+                let stderr = "";
+                let settled = false;
+                const finish = (outcome) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    resolve(outcome);
+                };
+                const timer = setTimeout(() => {
+                    child.kill();
+                    finish({ ok: false, warning: `hook timed out after ${timeoutMs}ms: ${commandRef}` });
+                }, timeoutMs);
+                child.stdout.on("data", (chunk) => {
+                    if (stdout.length < MAX_HOOK_OUTPUT_CHARS)
+                        stdout += chunk.toString("utf8");
+                });
+                child.stderr.on("data", (chunk) => {
+                    if (stderr.length < MAX_HOOK_OUTPUT_CHARS)
+                        stderr += chunk.toString("utf8");
+                });
+                // A hook that closes stdin early must not crash the write; the exit code decides.
+                child.stdin.on("error", () => { });
+                child.on("error", (error) => finish({ ok: false, warning: `hook failed to spawn: ${error.message}` }));
+                child.on("close", (code) => {
+                    if (code === 0) {
+                        finish(parseHookDecisionOutput(stdout));
+                    }
+                    else if (code === 2) {
+                        finish({
+                            ok: true,
+                            decision: {
+                                decision: "block",
+                                reason: stderr.trim() || stdout.trim() || "blocked by hook (exit 2)",
+                            },
+                        });
+                    }
+                    else if (code === null) {
+                        finish({ ok: false, warning: `hook terminated by a signal: ${commandRef}` });
+                    }
+                    else {
+                        finish({
+                            ok: false,
+                            warning: `hook exited with exit code ${code}: ${stderr.trim() || stdout.trim() || commandRef}`,
+                        });
+                    }
+                });
+                child.stdin.end(JSON.stringify(payload));
+            });
+        },
+    };
+}
+//# sourceMappingURL=command-handler.js.map

package/dist/core/hooks/command-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-handler.js","sourceRoot":"","sources":["../../../src/core/hooks/command-handler.ts"],"names":[],"mappings":"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","sourcesContent":["import { spawn } from \"node:child_process\";\nimport {\n\tDEFAULT_HOOK_TIMEOUT_MS,\n\ttype HookCommandHandlerConfig,\n\ttype HookEventPayload,\n\ttype HookHandler,\n\ttype HookOutcome,\n} from \"./types.ts\";\n\n// A runaway formatter can emit megabytes; the decision that matters is at the\n// start, so cap what we retain rather than what the child may write.\nconst MAX_HOOK_OUTPUT_CHARS = 1_000_000;\n\nfunction truncate(text: string): string {\n\treturn text.length > 200 ? `${text.slice(0, 200)}...` : text;\n}\n\n/**\n * Shared decision parsing for command stdout and HTTP response bodies.\n * Non-JSON output, a non-object, or an unknown decision value is \"no decision\"\n * plus a warning -- never an allow (spec, Risks).\n */\nexport function parseHookDecisionOutput(text: string): HookOutcome {\n\tconst trimmed = text.trim();\n\tif (trimmed.length === 0) return { ok: true };\n\tlet parsed: unknown;\n\ttry {\n\t\tparsed = JSON.parse(trimmed);\n\t} catch {\n\t\treturn { ok: true, warning: `hook output was not valid JSON: ${truncate(trimmed)}` };\n\t}\n\tif (typeof parsed !== \"object\" || parsed === null || Array.isArray(parsed)) {\n\t\treturn { ok: true, warning: `hook output was not a JSON object: ${truncate(trimmed)}` };\n\t}\n\tconst decision = (parsed as { decision?: unknown }).decision;\n\tif (decision === undefined) return { ok: true };\n\tif (decision !== \"allow\" && decision !== \"block\" && decision !== \"ask\") {\n\t\treturn { ok: true, warning: `hook output had an unknown decision: ${truncate(String(decision))}` };\n\t}\n\tconst reason = (parsed as { reason?: unknown }).reason;\n\treturn {\n\t\tok: true,\n\t\tdecision: { decision, ...(typeof reason === \"string\" && reason.length > 0 ? { reason } : {}) },\n\t};\n}\n\n/**\n * A command handler runs through the platform shell (`sh -c`, PowerShell on\n * Windows) with the event payload on stdin and its decision on stdout.\n *\n * Exit-code table (behavioral reference:\n * docs/research/2026-08-31-harness-landscape.md § 2.1): exit 0 + JSON = that\n * decision; exit 0 + no output = no decision; exit 2 = block with stderr as\n * the reason; any other nonzero exit (and spawn failure, and timeout) is a\n * failure outcome, which the runtime turns into a fail-closed block.\n */\nexport function commandHookHandler(config: HookCommandHandlerConfig): HookHandler {\n\tconst timeoutMs = config.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;\n\tconst commandRef = truncate(config.command);\n\treturn {\n\t\tasync execute(payload: HookEventPayload): Promise<HookOutcome> {\n\t\t\tconst shell = process.platform === \"win32\" ? \"powershell.exe\" : \"sh\";\n\t\t\tconst args =\n\t\t\t\tprocess.platform === \"win32\" ? [\"-NoProfile\", \"-Command\", config.command] : [\"-c\", config.command];\n\t\t\treturn await new Promise<HookOutcome>((resolve) => {\n\t\t\t\tconst child = spawn(shell, args, { stdio: [\"pipe\", \"pipe\", \"pipe\"] });\n\t\t\t\tlet stdout = \"\";\n\t\t\t\tlet stderr = \"\";\n\t\t\t\tlet settled = false;\n\t\t\t\tconst finish = (outcome: HookOutcome) => {\n\t\t\t\t\tif (settled) return;\n\t\t\t\t\tsettled = true;\n\t\t\t\t\tclearTimeout(timer);\n\t\t\t\t\tresolve(outcome);\n\t\t\t\t};\n\t\t\t\tconst timer = setTimeout(() => {\n\t\t\t\t\tchild.kill();\n\t\t\t\t\tfinish({ ok: false, warning: `hook timed out after ${timeoutMs}ms: ${commandRef}` });\n\t\t\t\t}, timeoutMs);\n\t\t\t\tchild.stdout.on(\"data\", (chunk: Buffer) => {\n\t\t\t\t\tif (stdout.length < MAX_HOOK_OUTPUT_CHARS) stdout += chunk.toString(\"utf8\");\n\t\t\t\t});\n\t\t\t\tchild.stderr.on(\"data\", (chunk: Buffer) => {\n\t\t\t\t\tif (stderr.length < MAX_HOOK_OUTPUT_CHARS) stderr += chunk.toString(\"utf8\");\n\t\t\t\t});\n\t\t\t\t// A hook that closes stdin early must not crash the write; the exit code decides.\n\t\t\t\tchild.stdin.on(\"error\", () => {});\n\t\t\t\tchild.on(\"error\", (error) => finish({ ok: false, warning: `hook failed to spawn: ${error.message}` }));\n\t\t\t\tchild.on(\"close\", (code) => {\n\t\t\t\t\tif (code === 0) {\n\t\t\t\t\t\tfinish(parseHookDecisionOutput(stdout));\n\t\t\t\t\t} else if (code === 2) {\n\t\t\t\t\t\tfinish({\n\t\t\t\t\t\t\tok: true,\n\t\t\t\t\t\t\tdecision: {\n\t\t\t\t\t\t\t\tdecision: \"block\",\n\t\t\t\t\t\t\t\treason: stderr.trim() || stdout.trim() || \"blocked by hook (exit 2)\",\n\t\t\t\t\t\t\t},\n\t\t\t\t\t\t});\n\t\t\t\t\t} else if (code === null) {\n\t\t\t\t\t\tfinish({ ok: false, warning: `hook terminated by a signal: ${commandRef}` });\n\t\t\t\t\t} else {\n\t\t\t\t\t\tfinish({\n\t\t\t\t\t\t\tok: false,\n\t\t\t\t\t\t\twarning: `hook exited with exit code ${code}: ${stderr.trim() || stdout.trim() || commandRef}`,\n\t\t\t\t\t\t});\n\t\t\t\t\t}\n\t\t\t\t});\n\t\t\t\tchild.stdin.end(JSON.stringify(payload));\n\t\t\t});\n\t\t},\n\t};\n}\n"]}

package/dist/core/hooks/http-handler.d.ts

@@ -0,0 +1,10 @@
+import { type HookHandler, type HookHttpHandlerConfig } from "./types.ts";
+/**
+ * An HTTP handler POSTs the event payload and reads the decision from the 200
+ * response body. The URL comes from settings only -- no environment-variable
+ * interpolation into headers or URLs (spec, Non-goals). A non-200 response,
+ * a transport failure, or a timeout is a failure outcome, which the runtime
+ * turns into a fail-closed block on `tool_call`.
+ */
+export declare function httpHookHandler(config: HookHttpHandlerConfig): HookHandler;
+//# sourceMappingURL=http-handler.d.ts.map

package/dist/core/hooks/http-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-handler.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/http-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAGN,KAAK,WAAW,EAChB,KAAK,qBAAqB,EAE1B,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,WAAW,CAwB1E","sourcesContent":["import { parseHookDecisionOutput } from \"./command-handler.ts\";\nimport {\n\tDEFAULT_HOOK_TIMEOUT_MS,\n\ttype HookEventPayload,\n\ttype HookHandler,\n\ttype HookHttpHandlerConfig,\n\ttype HookOutcome,\n} from \"./types.ts\";\n\n/**\n * An HTTP handler POSTs the event payload and reads the decision from the 200\n * response body. The URL comes from settings only -- no environment-variable\n * interpolation into headers or URLs (spec, Non-goals). A non-200 response,\n * a transport failure, or a timeout is a failure outcome, which the runtime\n * turns into a fail-closed block on `tool_call`.\n */\nexport function httpHookHandler(config: HookHttpHandlerConfig): HookHandler {\n\tconst timeoutMs = config.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;\n\treturn {\n\t\tasync execute(payload: HookEventPayload): Promise<HookOutcome> {\n\t\t\ttry {\n\t\t\t\tconst response = await fetch(config.url, {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: { \"content-type\": \"application/json\" },\n\t\t\t\t\tbody: JSON.stringify(payload),\n\t\t\t\t\tsignal: AbortSignal.timeout(timeoutMs),\n\t\t\t\t});\n\t\t\t\tif (!response.ok) {\n\t\t\t\t\treturn { ok: false, warning: `hook endpoint returned HTTP ${response.status}` };\n\t\t\t\t}\n\t\t\t\treturn parseHookDecisionOutput(await response.text());\n\t\t\t} catch (error) {\n\t\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\t\tif (/timeout|timed out|abort/i.test(message)) {\n\t\t\t\t\treturn { ok: false, warning: `hook timed out after ${timeoutMs}ms` };\n\t\t\t\t}\n\t\t\t\treturn { ok: false, warning: `hook request failed: ${message}` };\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

package/dist/core/hooks/http-handler.js

@@ -0,0 +1,36 @@
+import { parseHookDecisionOutput } from "./command-handler.js";
+import { DEFAULT_HOOK_TIMEOUT_MS, } from "./types.js";
+/**
+ * An HTTP handler POSTs the event payload and reads the decision from the 200
+ * response body. The URL comes from settings only -- no environment-variable
+ * interpolation into headers or URLs (spec, Non-goals). A non-200 response,
+ * a transport failure, or a timeout is a failure outcome, which the runtime
+ * turns into a fail-closed block on `tool_call`.
+ */
+export function httpHookHandler(config) {
+    const timeoutMs = config.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;
+    return {
+        async execute(payload) {
+            try {
+                const response = await fetch(config.url, {
+                    method: "POST",
+                    headers: { "content-type": "application/json" },
+                    body: JSON.stringify(payload),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                if (!response.ok) {
+                    return { ok: false, warning: `hook endpoint returned HTTP ${response.status}` };
+                }
+                return parseHookDecisionOutput(await response.text());
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                if (/timeout|timed out|abort/i.test(message)) {
+                    return { ok: false, warning: `hook timed out after ${timeoutMs}ms` };
+                }
+                return { ok: false, warning: `hook request failed: ${message}` };
+            }
+        },
+    };
+}
+//# sourceMappingURL=http-handler.js.map

package/dist/core/hooks/http-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-handler.js","sourceRoot":"","sources":["../../../src/core/hooks/http-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/D,OAAO,EACN,uBAAuB,GAKvB,MAAM,YAAY,CAAC;AAEpB;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,MAA6B,EAAe;IAC3E,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,uBAAuB,CAAC;IAC9D,OAAO;QACN,KAAK,CAAC,OAAO,CAAC,OAAyB,EAAwB;YAC9D,IAAI,CAAC;gBACJ,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE;oBACxC,MAAM,EAAE,MAAM;oBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;oBAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;oBAC7B,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC;iBACtC,CAAC,CAAC;gBACH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;oBAClB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,+BAA+B,QAAQ,CAAC,MAAM,EAAE,EAAE,CAAC;gBACjF,CAAC;gBACD,OAAO,uBAAuB,CAAC,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;YACvD,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;gBACvE,IAAI,0BAA0B,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC9C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,SAAS,IAAI,EAAE,CAAC;gBACtE,CAAC;gBACD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,OAAO,EAAE,wBAAwB,OAAO,EAAE,EAAE,CAAC;YAClE,CAAC;QAAA,CACD;KACD,CAAC;AAAA,CACF","sourcesContent":["import { parseHookDecisionOutput } from \"./command-handler.ts\";\nimport {\n\tDEFAULT_HOOK_TIMEOUT_MS,\n\ttype HookEventPayload,\n\ttype HookHandler,\n\ttype HookHttpHandlerConfig,\n\ttype HookOutcome,\n} from \"./types.ts\";\n\n/**\n * An HTTP handler POSTs the event payload and reads the decision from the 200\n * response body. The URL comes from settings only -- no environment-variable\n * interpolation into headers or URLs (spec, Non-goals). A non-200 response,\n * a transport failure, or a timeout is a failure outcome, which the runtime\n * turns into a fail-closed block on `tool_call`.\n */\nexport function httpHookHandler(config: HookHttpHandlerConfig): HookHandler {\n\tconst timeoutMs = config.timeoutMs ?? DEFAULT_HOOK_TIMEOUT_MS;\n\treturn {\n\t\tasync execute(payload: HookEventPayload): Promise<HookOutcome> {\n\t\t\ttry {\n\t\t\t\tconst response = await fetch(config.url, {\n\t\t\t\t\tmethod: \"POST\",\n\t\t\t\t\theaders: { \"content-type\": \"application/json\" },\n\t\t\t\t\tbody: JSON.stringify(payload),\n\t\t\t\t\tsignal: AbortSignal.timeout(timeoutMs),\n\t\t\t\t});\n\t\t\t\tif (!response.ok) {\n\t\t\t\t\treturn { ok: false, warning: `hook endpoint returned HTTP ${response.status}` };\n\t\t\t\t}\n\t\t\t\treturn parseHookDecisionOutput(await response.text());\n\t\t\t} catch (error) {\n\t\t\t\tconst message = error instanceof Error ? error.message : String(error);\n\t\t\t\tif (/timeout|timed out|abort/i.test(message)) {\n\t\t\t\t\treturn { ok: false, warning: `hook timed out after ${timeoutMs}ms` };\n\t\t\t\t}\n\t\t\t\treturn { ok: false, warning: `hook request failed: ${message}` };\n\t\t\t}\n\t\t},\n\t};\n}\n"]}

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":"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","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