open-multi-agent-kit 0.80.7 → 0.90.0

package/dist/core/headroom.d.ts

@@ -0,0 +1,45 @@
+import { EventEmitter } from "events";
+export interface HeadroomSnapshot {
+    timestamp: number;
+    promptTokens: number;
+    toolOutputTokens: number;
+    responseTokens: number;
+    totalTokens: number;
+    headroomRemaining: number;
+    status: "idle" | "active" | "stressed" | "critical" | "blocked";
+}
+export interface HeadroomPrediction {
+    predictedTokens: number;
+    confidence: number;
+    trend: "increasing" | "stable" | "decreasing";
+    recommendedAction: string;
+}
+export declare class HeadroomMonitor extends EventEmitter {
+    private history;
+    private maxHistory;
+    record(snapshot: HeadroomSnapshot): void;
+    predict(): HeadroomPrediction;
+    getStatus(totalTokens: number, maxTokens: number): HeadroomSnapshot["status"];
+}
+export declare class DynamicContextAllocator extends EventEmitter {
+    private maxTokens;
+    constructor(maxTokens?: number);
+    allocate(currentTokens: number): {
+        maxTokens: number;
+        canAddAgents: boolean;
+    };
+}
+export declare class HeadroomManager extends EventEmitter {
+    private monitor;
+    private allocator;
+    private maxTokens;
+    constructor(maxTokens?: number);
+    check(promptTokens: number, toolOutputTokens?: number, responseTokens?: number): HeadroomSnapshot;
+    predict(): HeadroomPrediction;
+    getAllocation(currentTokens: number): {
+        maxTokens: number;
+        canAddAgents: boolean;
+    };
+}
+export default HeadroomManager;
+//# sourceMappingURL=headroom.d.ts.map

package/dist/core/headroom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"headroom.d.ts","sourceRoot":"","sources":["../../src/core/headroom.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;CAChE;AAED,MAAM,WAAW,kBAAkB;IAClC,eAAe,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,YAAY,GAAG,QAAQ,GAAG,YAAY,CAAC;IAC9C,iBAAiB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,eAAgB,SAAQ,YAAY;IAChD,OAAO,CAAC,OAAO,CAA0B;IACzC,OAAO,CAAC,UAAU,CAAO;IAEzB,MAAM,CAAC,QAAQ,EAAE,gBAAgB,GAAG,IAAI,CAOvC;IAED,OAAO,IAAI,kBAAkB,CAoB5B;IAED,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CA6B5E;CACD;AAED,qBAAa,uBAAwB,SAAQ,YAAY;IACxD,OAAO,CAAC,SAAS,CAAS;IAE1B,YAAY,SAAS,SAAQ,EAG5B;IAED,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAU5E;CACD;AAED,qBAAa,eAAgB,SAAQ,YAAY;IAChD,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,SAAS,CAAS;IAE1B,YAAY,SAAS,SAAQ,EAK5B;IAED,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,gBAAgB,SAAI,EAAE,cAAc,SAAI,GAAG,gBAAgB,CAyBtF;IAED,OAAO,IAAI,kBAAkB,CAE5B;IAED,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,OAAO,CAAA;KAAE,CAEjF;CACD;AAED,eAAe,eAAe,CAAC","sourcesContent":["// OMK v6.2 — Headroom Manager (TypeScript)\n// ==================================================================\n// packages/coding-agent/src/core/headroom.ts\n//\n// STATUS: compatibility utility.\n// This file is preserved for legacy extension/API consumers and regression tests.\n//\n// ACTUAL HEADROOM / TOKEN BUDGET SYSTEM:\n//   - types/jailbreak.ts → defines HeadroomSnapshot, HeadroomPrediction (different shape)\n//   - context-budget-compressors.ts → context budget compression with adapters\n//   - context-budget-token-counter.ts → token counting for budget decisions\n//   - compaction/compaction.ts getCompactionHeadroomThreshold() → headroom threshold\n//   - compaction/compaction.ts shouldCompact() → triggers compaction when headroom low\n//\n// NOTE: types/jailbreak.ts defines similar types (HeadroomSnapshot, HeadroomPrediction)\n// but with different field structures. Both are distinct from this file's types.\n//\n// Keep this utility deterministic and aligned with the active context budget policy.\n\nimport { EventEmitter } from \"events\";\n\nexport interface HeadroomSnapshot {\n\ttimestamp: number;\n\tpromptTokens: number;\n\ttoolOutputTokens: number;\n\tresponseTokens: number;\n\ttotalTokens: number;\n\theadroomRemaining: number;\n\tstatus: \"idle\" | \"active\" | \"stressed\" | \"critical\" | \"blocked\";\n}\n\nexport interface HeadroomPrediction {\n\tpredictedTokens: number;\n\tconfidence: number;\n\ttrend: \"increasing\" | \"stable\" | \"decreasing\";\n\trecommendedAction: string;\n}\n\nexport class HeadroomMonitor extends EventEmitter {\n\tprivate history: HeadroomSnapshot[] = [];\n\tprivate maxHistory = 100;\n\n\trecord(snapshot: HeadroomSnapshot): void {\n\t\tconst sanitized = sanitizeSnapshot(snapshot);\n\t\tthis.history.push(sanitized);\n\t\tif (this.history.length > this.maxHistory) {\n\t\t\tthis.history = this.history.slice(-this.maxHistory);\n\t\t}\n\t\tthis.emit(\"snapshot\", sanitized);\n\t}\n\n\tpredict(): HeadroomPrediction {\n\t\tif (this.history.length < 3) {\n\t\t\treturn { predictedTokens: 0, confidence: 0, trend: \"stable\", recommendedAction: \"collect more data\" };\n\t\t}\n\n\t\tconst recent = this.history.slice(-10);\n\t\tconst first = recent[0].totalTokens;\n\t\tconst last = recent[recent.length - 1].totalTokens;\n\t\tconst delta = last - first;\n\t\tconst slope = delta / Math.max(recent.length - 1, 1);\n\t\tconst trend = Math.abs(delta) <= Math.max(1, last * 0.02) ? \"stable\" : delta > 0 ? \"increasing\" : \"decreasing\";\n\t\tconst projectedTokens = trend === \"increasing\" ? last + Math.max(1, slope) : Math.max(0, last + slope);\n\t\tconst confidence = Math.min(0.95, 0.45 + recent.length * 0.05);\n\n\t\treturn {\n\t\t\tpredictedTokens: Math.round(projectedTokens),\n\t\t\tconfidence,\n\t\t\ttrend,\n\t\t\trecommendedAction: trend === \"increasing\" ? \"compress context\" : \"maintain\",\n\t\t};\n\t}\n\n\tgetStatus(totalTokens: number, maxTokens: number): HeadroomSnapshot[\"status\"] {\n\t\tconst normalizedTotalTokens = normalizeTokenInput(totalTokens);\n\t\tconst normalizedMaxTokens = normalizeTokenLimit(maxTokens);\n\t\tif (normalizedMaxTokens === 0) {\n\t\t\treturn normalizedTotalTokens === 0 ? \"idle\" : \"blocked\";\n\t\t}\n\n\t\tconst ratio = normalizedTotalTokens / normalizedMaxTokens;\n\t\tlet status: HeadroomSnapshot[\"status\"];\n\t\tif (ratio < 0.4) {\n\t\t\tstatus = \"idle\";\n\t\t} else if (ratio < 0.7) {\n\t\t\tstatus = \"active\";\n\t\t} else if (ratio < 0.8) {\n\t\t\tstatus = \"stressed\";\n\t\t} else if (ratio < 0.9) {\n\t\t\tstatus = \"critical\";\n\t\t} else {\n\t\t\tstatus = \"blocked\";\n\t\t}\n\n\t\tconst previous = this.history.at(-1)?.status;\n\t\tif (previous === \"critical\" && status === \"stressed\" && ratio >= 0.75) {\n\t\t\treturn \"critical\";\n\t\t}\n\t\tif (previous === \"blocked\" && status !== \"blocked\" && ratio >= 0.85) {\n\t\t\treturn \"blocked\";\n\t\t}\n\t\treturn status;\n\t}\n}\n\nexport class DynamicContextAllocator extends EventEmitter {\n\tprivate maxTokens: number;\n\n\tconstructor(maxTokens = 15000) {\n\t\tsuper();\n\t\tthis.maxTokens = normalizeTokenLimit(maxTokens);\n\t}\n\n\tallocate(currentTokens: number): { maxTokens: number; canAddAgents: boolean } {\n\t\tif (this.maxTokens === 0) {\n\t\t\treturn { maxTokens: 0, canAddAgents: false };\n\t\t}\n\t\tconst ratio = normalizeTokenInput(currentTokens) / this.maxTokens;\n\t\tif (ratio < 0.4) return { maxTokens: this.maxTokens, canAddAgents: true };\n\t\tif (ratio < 0.7) return { maxTokens: this.maxTokens * 0.9, canAddAgents: true };\n\t\tif (ratio < 0.8) return { maxTokens: this.maxTokens * 0.75, canAddAgents: false };\n\t\tif (ratio < 0.9) return { maxTokens: this.maxTokens * 0.5, canAddAgents: false };\n\t\treturn { maxTokens: 0, canAddAgents: false };\n\t}\n}\n\nexport class HeadroomManager extends EventEmitter {\n\tprivate monitor: HeadroomMonitor;\n\tprivate allocator: DynamicContextAllocator;\n\tprivate maxTokens: number;\n\n\tconstructor(maxTokens = 15000) {\n\t\tsuper();\n\t\tthis.maxTokens = normalizeTokenLimit(maxTokens);\n\t\tthis.monitor = new HeadroomMonitor();\n\t\tthis.allocator = new DynamicContextAllocator(this.maxTokens);\n\t}\n\n\tcheck(promptTokens: number, toolOutputTokens = 0, responseTokens = 0): HeadroomSnapshot {\n\t\tconst normalizedPromptTokens = normalizeTokenInput(promptTokens);\n\t\tconst normalizedToolOutputTokens = normalizeTokenInput(toolOutputTokens);\n\t\tconst normalizedResponseTokens = normalizeTokenInput(responseTokens);\n\t\tconst totalTokens = normalizedPromptTokens + normalizedToolOutputTokens + normalizedResponseTokens;\n\t\tconst status = this.monitor.getStatus(totalTokens, this.maxTokens);\n\t\tthis.allocator.allocate(totalTokens);\n\n\t\tconst snapshot: HeadroomSnapshot = {\n\t\t\ttimestamp: Date.now(),\n\t\t\tpromptTokens: normalizedPromptTokens,\n\t\t\ttoolOutputTokens: normalizedToolOutputTokens,\n\t\t\tresponseTokens: normalizedResponseTokens,\n\t\t\ttotalTokens,\n\t\t\theadroomRemaining: this.maxTokens - totalTokens,\n\t\t\tstatus,\n\t\t};\n\n\t\tthis.monitor.record(snapshot);\n\n\t\tif (status === \"critical\" || status === \"blocked\") {\n\t\t\tthis.emit(\"warning\", { status, message: `Headroom ${status}: ${totalTokens}/${this.maxTokens} tokens` });\n\t\t}\n\n\t\treturn snapshot;\n\t}\n\n\tpredict(): HeadroomPrediction {\n\t\treturn this.monitor.predict();\n\t}\n\n\tgetAllocation(currentTokens: number): { maxTokens: number; canAddAgents: boolean } {\n\t\treturn this.allocator.allocate(currentTokens);\n\t}\n}\n\nexport default HeadroomManager;\n\nfunction sanitizeSnapshot(snapshot: HeadroomSnapshot): HeadroomSnapshot {\n\treturn {\n\t\ttimestamp: Number.isFinite(snapshot.timestamp) ? Math.floor(snapshot.timestamp) : 0,\n\t\tpromptTokens: normalizeTokenInput(snapshot.promptTokens),\n\t\ttoolOutputTokens: normalizeTokenInput(snapshot.toolOutputTokens),\n\t\tresponseTokens: normalizeTokenInput(snapshot.responseTokens),\n\t\ttotalTokens: normalizeTokenInput(snapshot.totalTokens),\n\t\theadroomRemaining: normalizeFiniteInteger(snapshot.headroomRemaining),\n\t\tstatus: snapshot.status,\n\t};\n}\n\nfunction normalizeTokenLimit(value: number): number {\n\treturn normalizeTokenInput(value);\n}\n\nfunction normalizeTokenInput(value: number): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction normalizeFiniteInteger(value: number): number {\n\tif (!Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n"]}

package/dist/core/headroom.js

@@ -0,0 +1,171 @@
+// OMK v6.2 — Headroom Manager (TypeScript)
+// ==================================================================
+// packages/coding-agent/src/core/headroom.ts
+//
+// STATUS: compatibility utility.
+// This file is preserved for legacy extension/API consumers and regression tests.
+//
+// ACTUAL HEADROOM / TOKEN BUDGET SYSTEM:
+//   - types/jailbreak.ts → defines HeadroomSnapshot, HeadroomPrediction (different shape)
+//   - context-budget-compressors.ts → context budget compression with adapters
+//   - context-budget-token-counter.ts → token counting for budget decisions
+//   - compaction/compaction.ts getCompactionHeadroomThreshold() → headroom threshold
+//   - compaction/compaction.ts shouldCompact() → triggers compaction when headroom low
+//
+// NOTE: types/jailbreak.ts defines similar types (HeadroomSnapshot, HeadroomPrediction)
+// but with different field structures. Both are distinct from this file's types.
+//
+// Keep this utility deterministic and aligned with the active context budget policy.
+import { EventEmitter } from "events";
+export class HeadroomMonitor extends EventEmitter {
+    history = [];
+    maxHistory = 100;
+    record(snapshot) {
+        const sanitized = sanitizeSnapshot(snapshot);
+        this.history.push(sanitized);
+        if (this.history.length > this.maxHistory) {
+            this.history = this.history.slice(-this.maxHistory);
+        }
+        this.emit("snapshot", sanitized);
+    }
+    predict() {
+        if (this.history.length < 3) {
+            return { predictedTokens: 0, confidence: 0, trend: "stable", recommendedAction: "collect more data" };
+        }
+        const recent = this.history.slice(-10);
+        const first = recent[0].totalTokens;
+        const last = recent[recent.length - 1].totalTokens;
+        const delta = last - first;
+        const slope = delta / Math.max(recent.length - 1, 1);
+        const trend = Math.abs(delta) <= Math.max(1, last * 0.02) ? "stable" : delta > 0 ? "increasing" : "decreasing";
+        const projectedTokens = trend === "increasing" ? last + Math.max(1, slope) : Math.max(0, last + slope);
+        const confidence = Math.min(0.95, 0.45 + recent.length * 0.05);
+        return {
+            predictedTokens: Math.round(projectedTokens),
+            confidence,
+            trend,
+            recommendedAction: trend === "increasing" ? "compress context" : "maintain",
+        };
+    }
+    getStatus(totalTokens, maxTokens) {
+        const normalizedTotalTokens = normalizeTokenInput(totalTokens);
+        const normalizedMaxTokens = normalizeTokenLimit(maxTokens);
+        if (normalizedMaxTokens === 0) {
+            return normalizedTotalTokens === 0 ? "idle" : "blocked";
+        }
+        const ratio = normalizedTotalTokens / normalizedMaxTokens;
+        let status;
+        if (ratio < 0.4) {
+            status = "idle";
+        }
+        else if (ratio < 0.7) {
+            status = "active";
+        }
+        else if (ratio < 0.8) {
+            status = "stressed";
+        }
+        else if (ratio < 0.9) {
+            status = "critical";
+        }
+        else {
+            status = "blocked";
+        }
+        const previous = this.history.at(-1)?.status;
+        if (previous === "critical" && status === "stressed" && ratio >= 0.75) {
+            return "critical";
+        }
+        if (previous === "blocked" && status !== "blocked" && ratio >= 0.85) {
+            return "blocked";
+        }
+        return status;
+    }
+}
+export class DynamicContextAllocator extends EventEmitter {
+    maxTokens;
+    constructor(maxTokens = 15000) {
+        super();
+        this.maxTokens = normalizeTokenLimit(maxTokens);
+    }
+    allocate(currentTokens) {
+        if (this.maxTokens === 0) {
+            return { maxTokens: 0, canAddAgents: false };
+        }
+        const ratio = normalizeTokenInput(currentTokens) / this.maxTokens;
+        if (ratio < 0.4)
+            return { maxTokens: this.maxTokens, canAddAgents: true };
+        if (ratio < 0.7)
+            return { maxTokens: this.maxTokens * 0.9, canAddAgents: true };
+        if (ratio < 0.8)
+            return { maxTokens: this.maxTokens * 0.75, canAddAgents: false };
+        if (ratio < 0.9)
+            return { maxTokens: this.maxTokens * 0.5, canAddAgents: false };
+        return { maxTokens: 0, canAddAgents: false };
+    }
+}
+export class HeadroomManager extends EventEmitter {
+    monitor;
+    allocator;
+    maxTokens;
+    constructor(maxTokens = 15000) {
+        super();
+        this.maxTokens = normalizeTokenLimit(maxTokens);
+        this.monitor = new HeadroomMonitor();
+        this.allocator = new DynamicContextAllocator(this.maxTokens);
+    }
+    check(promptTokens, toolOutputTokens = 0, responseTokens = 0) {
+        const normalizedPromptTokens = normalizeTokenInput(promptTokens);
+        const normalizedToolOutputTokens = normalizeTokenInput(toolOutputTokens);
+        const normalizedResponseTokens = normalizeTokenInput(responseTokens);
+        const totalTokens = normalizedPromptTokens + normalizedToolOutputTokens + normalizedResponseTokens;
+        const status = this.monitor.getStatus(totalTokens, this.maxTokens);
+        this.allocator.allocate(totalTokens);
+        const snapshot = {
+            timestamp: Date.now(),
+            promptTokens: normalizedPromptTokens,
+            toolOutputTokens: normalizedToolOutputTokens,
+            responseTokens: normalizedResponseTokens,
+            totalTokens,
+            headroomRemaining: this.maxTokens - totalTokens,
+            status,
+        };
+        this.monitor.record(snapshot);
+        if (status === "critical" || status === "blocked") {
+            this.emit("warning", { status, message: `Headroom ${status}: ${totalTokens}/${this.maxTokens} tokens` });
+        }
+        return snapshot;
+    }
+    predict() {
+        return this.monitor.predict();
+    }
+    getAllocation(currentTokens) {
+        return this.allocator.allocate(currentTokens);
+    }
+}
+export default HeadroomManager;
+function sanitizeSnapshot(snapshot) {
+    return {
+        timestamp: Number.isFinite(snapshot.timestamp) ? Math.floor(snapshot.timestamp) : 0,
+        promptTokens: normalizeTokenInput(snapshot.promptTokens),
+        toolOutputTokens: normalizeTokenInput(snapshot.toolOutputTokens),
+        responseTokens: normalizeTokenInput(snapshot.responseTokens),
+        totalTokens: normalizeTokenInput(snapshot.totalTokens),
+        headroomRemaining: normalizeFiniteInteger(snapshot.headroomRemaining),
+        status: snapshot.status,
+    };
+}
+function normalizeTokenLimit(value) {
+    return normalizeTokenInput(value);
+}
+function normalizeTokenInput(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        return 0;
+    }
+    return Math.floor(value);
+}
+function normalizeFiniteInteger(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Math.floor(value);
+}
+//# sourceMappingURL=headroom.js.map

package/dist/core/headroom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headroom.js","sourceRoot":"","sources":["../../src/core/headroom.ts"],"names":[],"mappings":"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","sourcesContent":["// OMK v6.2 — Headroom Manager (TypeScript)\n// ==================================================================\n// packages/coding-agent/src/core/headroom.ts\n//\n// STATUS: compatibility utility.\n// This file is preserved for legacy extension/API consumers and regression tests.\n//\n// ACTUAL HEADROOM / TOKEN BUDGET SYSTEM:\n//   - types/jailbreak.ts → defines HeadroomSnapshot, HeadroomPrediction (different shape)\n//   - context-budget-compressors.ts → context budget compression with adapters\n//   - context-budget-token-counter.ts → token counting for budget decisions\n//   - compaction/compaction.ts getCompactionHeadroomThreshold() → headroom threshold\n//   - compaction/compaction.ts shouldCompact() → triggers compaction when headroom low\n//\n// NOTE: types/jailbreak.ts defines similar types (HeadroomSnapshot, HeadroomPrediction)\n// but with different field structures. Both are distinct from this file's types.\n//\n// Keep this utility deterministic and aligned with the active context budget policy.\n\nimport { EventEmitter } from \"events\";\n\nexport interface HeadroomSnapshot {\n\ttimestamp: number;\n\tpromptTokens: number;\n\ttoolOutputTokens: number;\n\tresponseTokens: number;\n\ttotalTokens: number;\n\theadroomRemaining: number;\n\tstatus: \"idle\" | \"active\" | \"stressed\" | \"critical\" | \"blocked\";\n}\n\nexport interface HeadroomPrediction {\n\tpredictedTokens: number;\n\tconfidence: number;\n\ttrend: \"increasing\" | \"stable\" | \"decreasing\";\n\trecommendedAction: string;\n}\n\nexport class HeadroomMonitor extends EventEmitter {\n\tprivate history: HeadroomSnapshot[] = [];\n\tprivate maxHistory = 100;\n\n\trecord(snapshot: HeadroomSnapshot): void {\n\t\tconst sanitized = sanitizeSnapshot(snapshot);\n\t\tthis.history.push(sanitized);\n\t\tif (this.history.length > this.maxHistory) {\n\t\t\tthis.history = this.history.slice(-this.maxHistory);\n\t\t}\n\t\tthis.emit(\"snapshot\", sanitized);\n\t}\n\n\tpredict(): HeadroomPrediction {\n\t\tif (this.history.length < 3) {\n\t\t\treturn { predictedTokens: 0, confidence: 0, trend: \"stable\", recommendedAction: \"collect more data\" };\n\t\t}\n\n\t\tconst recent = this.history.slice(-10);\n\t\tconst first = recent[0].totalTokens;\n\t\tconst last = recent[recent.length - 1].totalTokens;\n\t\tconst delta = last - first;\n\t\tconst slope = delta / Math.max(recent.length - 1, 1);\n\t\tconst trend = Math.abs(delta) <= Math.max(1, last * 0.02) ? \"stable\" : delta > 0 ? \"increasing\" : \"decreasing\";\n\t\tconst projectedTokens = trend === \"increasing\" ? last + Math.max(1, slope) : Math.max(0, last + slope);\n\t\tconst confidence = Math.min(0.95, 0.45 + recent.length * 0.05);\n\n\t\treturn {\n\t\t\tpredictedTokens: Math.round(projectedTokens),\n\t\t\tconfidence,\n\t\t\ttrend,\n\t\t\trecommendedAction: trend === \"increasing\" ? \"compress context\" : \"maintain\",\n\t\t};\n\t}\n\n\tgetStatus(totalTokens: number, maxTokens: number): HeadroomSnapshot[\"status\"] {\n\t\tconst normalizedTotalTokens = normalizeTokenInput(totalTokens);\n\t\tconst normalizedMaxTokens = normalizeTokenLimit(maxTokens);\n\t\tif (normalizedMaxTokens === 0) {\n\t\t\treturn normalizedTotalTokens === 0 ? \"idle\" : \"blocked\";\n\t\t}\n\n\t\tconst ratio = normalizedTotalTokens / normalizedMaxTokens;\n\t\tlet status: HeadroomSnapshot[\"status\"];\n\t\tif (ratio < 0.4) {\n\t\t\tstatus = \"idle\";\n\t\t} else if (ratio < 0.7) {\n\t\t\tstatus = \"active\";\n\t\t} else if (ratio < 0.8) {\n\t\t\tstatus = \"stressed\";\n\t\t} else if (ratio < 0.9) {\n\t\t\tstatus = \"critical\";\n\t\t} else {\n\t\t\tstatus = \"blocked\";\n\t\t}\n\n\t\tconst previous = this.history.at(-1)?.status;\n\t\tif (previous === \"critical\" && status === \"stressed\" && ratio >= 0.75) {\n\t\t\treturn \"critical\";\n\t\t}\n\t\tif (previous === \"blocked\" && status !== \"blocked\" && ratio >= 0.85) {\n\t\t\treturn \"blocked\";\n\t\t}\n\t\treturn status;\n\t}\n}\n\nexport class DynamicContextAllocator extends EventEmitter {\n\tprivate maxTokens: number;\n\n\tconstructor(maxTokens = 15000) {\n\t\tsuper();\n\t\tthis.maxTokens = normalizeTokenLimit(maxTokens);\n\t}\n\n\tallocate(currentTokens: number): { maxTokens: number; canAddAgents: boolean } {\n\t\tif (this.maxTokens === 0) {\n\t\t\treturn { maxTokens: 0, canAddAgents: false };\n\t\t}\n\t\tconst ratio = normalizeTokenInput(currentTokens) / this.maxTokens;\n\t\tif (ratio < 0.4) return { maxTokens: this.maxTokens, canAddAgents: true };\n\t\tif (ratio < 0.7) return { maxTokens: this.maxTokens * 0.9, canAddAgents: true };\n\t\tif (ratio < 0.8) return { maxTokens: this.maxTokens * 0.75, canAddAgents: false };\n\t\tif (ratio < 0.9) return { maxTokens: this.maxTokens * 0.5, canAddAgents: false };\n\t\treturn { maxTokens: 0, canAddAgents: false };\n\t}\n}\n\nexport class HeadroomManager extends EventEmitter {\n\tprivate monitor: HeadroomMonitor;\n\tprivate allocator: DynamicContextAllocator;\n\tprivate maxTokens: number;\n\n\tconstructor(maxTokens = 15000) {\n\t\tsuper();\n\t\tthis.maxTokens = normalizeTokenLimit(maxTokens);\n\t\tthis.monitor = new HeadroomMonitor();\n\t\tthis.allocator = new DynamicContextAllocator(this.maxTokens);\n\t}\n\n\tcheck(promptTokens: number, toolOutputTokens = 0, responseTokens = 0): HeadroomSnapshot {\n\t\tconst normalizedPromptTokens = normalizeTokenInput(promptTokens);\n\t\tconst normalizedToolOutputTokens = normalizeTokenInput(toolOutputTokens);\n\t\tconst normalizedResponseTokens = normalizeTokenInput(responseTokens);\n\t\tconst totalTokens = normalizedPromptTokens + normalizedToolOutputTokens + normalizedResponseTokens;\n\t\tconst status = this.monitor.getStatus(totalTokens, this.maxTokens);\n\t\tthis.allocator.allocate(totalTokens);\n\n\t\tconst snapshot: HeadroomSnapshot = {\n\t\t\ttimestamp: Date.now(),\n\t\t\tpromptTokens: normalizedPromptTokens,\n\t\t\ttoolOutputTokens: normalizedToolOutputTokens,\n\t\t\tresponseTokens: normalizedResponseTokens,\n\t\t\ttotalTokens,\n\t\t\theadroomRemaining: this.maxTokens - totalTokens,\n\t\t\tstatus,\n\t\t};\n\n\t\tthis.monitor.record(snapshot);\n\n\t\tif (status === \"critical\" || status === \"blocked\") {\n\t\t\tthis.emit(\"warning\", { status, message: `Headroom ${status}: ${totalTokens}/${this.maxTokens} tokens` });\n\t\t}\n\n\t\treturn snapshot;\n\t}\n\n\tpredict(): HeadroomPrediction {\n\t\treturn this.monitor.predict();\n\t}\n\n\tgetAllocation(currentTokens: number): { maxTokens: number; canAddAgents: boolean } {\n\t\treturn this.allocator.allocate(currentTokens);\n\t}\n}\n\nexport default HeadroomManager;\n\nfunction sanitizeSnapshot(snapshot: HeadroomSnapshot): HeadroomSnapshot {\n\treturn {\n\t\ttimestamp: Number.isFinite(snapshot.timestamp) ? Math.floor(snapshot.timestamp) : 0,\n\t\tpromptTokens: normalizeTokenInput(snapshot.promptTokens),\n\t\ttoolOutputTokens: normalizeTokenInput(snapshot.toolOutputTokens),\n\t\tresponseTokens: normalizeTokenInput(snapshot.responseTokens),\n\t\ttotalTokens: normalizeTokenInput(snapshot.totalTokens),\n\t\theadroomRemaining: normalizeFiniteInteger(snapshot.headroomRemaining),\n\t\tstatus: snapshot.status,\n\t};\n}\n\nfunction normalizeTokenLimit(value: number): number {\n\treturn normalizeTokenInput(value);\n}\n\nfunction normalizeTokenInput(value: number): number {\n\tif (!Number.isFinite(value) || value < 0) {\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n\nfunction normalizeFiniteInteger(value: number): number {\n\tif (!Number.isFinite(value)) {\n\t\treturn 0;\n\t}\n\treturn Math.floor(value);\n}\n"]}

package/dist/core/hook-inventory.d.ts

@@ -2,13 +2,15 @@
  * Minimal hook inventory for the loadout runtime.
  *
  * The external harness resolves `scriptPath` to an actual shell script.
- * This module only provides the canonical names and builtin flag so the
- * loadout layer can validate allow/exclude/require selectors.
+ * This module provides canonical names plus safe policy metadata so the
+ * loadout layer can validate selectors without executing hooks.
  */
+import type { HookPolicyMetadata } from "./hooks/index.ts";
 export interface HookDescriptor {
     name: string;
     scriptPath?: string;
     builtin: boolean;
+    policy: HookPolicyMetadata;
 }
 export interface HookInventory {
     hooks: readonly HookDescriptor[];

package/dist/core/hook-inventory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"hook-inventory.d.ts","sourceRoot":"","sources":["../../src/core/hook-inventory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CACjC;AAED,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EASlD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAqBlE","sourcesContent":["/**\n * Minimal hook inventory for the loadout runtime.\n *\n * The external harness resolves `scriptPath` to an actual shell script.\n * This module only provides the canonical names and builtin flag so the\n * loadout layer can validate allow/exclude/require selectors.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\n\nexport interface HookDescriptor {\n\tname: string;\n\tscriptPath?: string;\n\tbuiltin: boolean;\n}\n\nexport interface HookInventory {\n\thooks: readonly HookDescriptor[];\n}\n\nexport const BUILTIN_HOOKS: readonly HookDescriptor[] = [\n\t{ name: \"pre-shell-guard\", builtin: true },\n\t{ name: \"protect-secrets\", builtin: true },\n\t{ name: \"session-context\", builtin: true },\n\t{ name: \"precompact-checkpoint\", builtin: true },\n\t{ name: \"typecheck-after-edit\", builtin: true },\n\t{ name: \"stop-verify\", builtin: true },\n\t{ name: \"subagent-stop-audit\", builtin: true },\n\t{ name: \"npm-audit-summary\", builtin: true },\n];\n\n/**\n * Load the hook inventory. Builtin hooks are always present; if an agent\n * directory is provided and its `hooks` subdirectory exists, any shell scripts\n * discovered there are appended as non-builtin descriptors.\n */\nexport function loadHookInventory(agentDir?: string): HookInventory {\n\tconst hooks: HookDescriptor[] = [...BUILTIN_HOOKS];\n\tif (agentDir) {\n\t\ttry {\n\t\t\tconst hooksDir = path.join(agentDir, \"hooks\");\n\t\t\tconst entries = fs.readdirSync(hooksDir);\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (!entry.endsWith(\".sh\")) continue;\n\t\t\t\tconst name = entry.slice(0, -3);\n\t\t\t\tif (hooks.some((h) => h.name === name)) continue;\n\t\t\t\thooks.push({\n\t\t\t\t\tname,\n\t\t\t\t\tscriptPath: path.join(hooksDir, entry),\n\t\t\t\t\tbuiltin: false,\n\t\t\t\t});\n\t\t\t}\n\t\t} catch {\n\t\t\t// Hooks directory may be absent; builtin inventory is sufficient.\n\t\t}\n\t}\n\treturn { hooks };\n}\n"]}
+{"version":3,"file":"hook-inventory.d.ts","sourceRoot":"","sources":["../../src/core/hook-inventory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAG3D,MAAM,WAAW,cAAc;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,kBAAkB,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC7B,KAAK,EAAE,SAAS,cAAc,EAAE,CAAC;CACjC;AAMD,eAAO,MAAM,aAAa,EAAE,SAAS,cAAc,EAyElD,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,aAAa,CAsBlE","sourcesContent":["/**\n * Minimal hook inventory for the loadout runtime.\n *\n * The external harness resolves `scriptPath` to an actual shell script.\n * This module provides canonical names plus safe policy metadata so the\n * loadout layer can validate selectors without executing hooks.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { HookPolicyMetadata } from \"./hooks/index.ts\";\nimport { DEFAULT_HOOK_POLICY, sanitizeHookPolicy } from \"./hooks/index.ts\";\n\nexport interface HookDescriptor {\n\tname: string;\n\tscriptPath?: string;\n\tbuiltin: boolean;\n\tpolicy: HookPolicyMetadata;\n}\n\nexport interface HookInventory {\n\thooks: readonly HookDescriptor[];\n}\n\nfunction builtinHook(name: string, policy: HookPolicyMetadata): HookDescriptor {\n\treturn { name, builtin: true, policy: sanitizeHookPolicy(policy) };\n}\n\nexport const BUILTIN_HOOKS: readonly HookDescriptor[] = [\n\tbuiltinHook(\"pre-shell-guard\", {\n\t\tstages: [\"tool_call\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 3_000,\n\t}),\n\tbuiltinHook(\"protect-secrets\", {\n\t\tstages: [\"tool_call\", \"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"session-context\", {\n\t\tstages: [\"session_start\"],\n\t\teffects: [\"mutator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"precompact-checkpoint\", {\n\t\tstages: [\"pre_compact\"],\n\t\teffects: [\"observer\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"typecheck-after-edit\", {\n\t\tstages: [\"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 30_000,\n\t}),\n\tbuiltinHook(\"stop-verify\", {\n\t\tstages: [\"session_stop\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 30_000,\n\t}),\n\tbuiltinHook(\"subagent-stop-audit\", {\n\t\tstages: [\"session_stop\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 10_000,\n\t}),\n\tbuiltinHook(\"npm-audit-summary\", {\n\t\tstages: [\"session_stop\"],\n\t\teffects: [\"observer\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 30_000,\n\t}),\n\tbuiltinHook(\"bounded-evidence\", {\n\t\tstages: [\"tool_result\", \"session_stop\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 10_000,\n\t}),\n\tbuiltinHook(\"document-artifact-guard\", {\n\t\tstages: [\"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"component-spec-before-build\", {\n\t\tstages: [\"tool_call\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"visual-diff-after-edit\", {\n\t\tstages: [\"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 10_000,\n\t}),\n];\n\n/**\n * Load the hook inventory. Builtin hooks are always present; if an agent\n * directory is provided and its `hooks` subdirectory exists, any shell scripts\n * discovered there are appended as non-builtin descriptors.\n */\nexport function loadHookInventory(agentDir?: string): HookInventory {\n\tconst hooks: HookDescriptor[] = [...BUILTIN_HOOKS];\n\tif (agentDir) {\n\t\ttry {\n\t\t\tconst hooksDir = path.join(agentDir, \"hooks\");\n\t\t\tconst entries = fs.readdirSync(hooksDir).sort();\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (!entry.endsWith(\".sh\")) continue;\n\t\t\t\tconst name = entry.slice(0, -3);\n\t\t\t\tif (hooks.some((h) => h.name === name)) continue;\n\t\t\t\thooks.push({\n\t\t\t\t\tname,\n\t\t\t\t\tscriptPath: path.join(hooksDir, entry),\n\t\t\t\t\tbuiltin: false,\n\t\t\t\t\tpolicy: sanitizeHookPolicy(DEFAULT_HOOK_POLICY),\n\t\t\t\t});\n\t\t\t}\n\t\t} catch {\n\t\t\t// Hooks directory may be absent; builtin inventory is sufficient.\n\t\t}\n\t}\n\treturn { hooks };\n}\n"]}

package/dist/core/hook-inventory.js

@@ -2,20 +2,88 @@
  * Minimal hook inventory for the loadout runtime.
  *
  * The external harness resolves `scriptPath` to an actual shell script.
- * This module only provides the canonical names and builtin flag so the
- * loadout layer can validate allow/exclude/require selectors.
+ * This module provides canonical names plus safe policy metadata so the
+ * loadout layer can validate selectors without executing hooks.
  */
 import fs from "node:fs";
 import path from "node:path";
+import { DEFAULT_HOOK_POLICY, sanitizeHookPolicy } from "./hooks/index.js";
+function builtinHook(name, policy) {
+    return { name, builtin: true, policy: sanitizeHookPolicy(policy) };
+}
 export const BUILTIN_HOOKS = [
-    { name: "pre-shell-guard", builtin: true },
-    { name: "protect-secrets", builtin: true },
-    { name: "session-context", builtin: true },
-    { name: "precompact-checkpoint", builtin: true },
-    { name: "typecheck-after-edit", builtin: true },
-    { name: "stop-verify", builtin: true },
-    { name: "subagent-stop-audit", builtin: true },
-    { name: "npm-audit-summary", builtin: true },
+    builtinHook("pre-shell-guard", {
+        stages: ["tool_call"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 3_000,
+    }),
+    builtinHook("protect-secrets", {
+        stages: ["tool_call", "tool_result"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 5_000,
+    }),
+    builtinHook("session-context", {
+        stages: ["session_start"],
+        effects: ["mutator"],
+        failureMode: "fail-closed",
+        timeoutMs: 5_000,
+    }),
+    builtinHook("precompact-checkpoint", {
+        stages: ["pre_compact"],
+        effects: ["observer"],
+        failureMode: "fail-closed",
+        timeoutMs: 5_000,
+    }),
+    builtinHook("typecheck-after-edit", {
+        stages: ["tool_result"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 30_000,
+    }),
+    builtinHook("stop-verify", {
+        stages: ["session_stop"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 30_000,
+    }),
+    builtinHook("subagent-stop-audit", {
+        stages: ["session_stop"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 10_000,
+    }),
+    builtinHook("npm-audit-summary", {
+        stages: ["session_stop"],
+        effects: ["observer"],
+        failureMode: "fail-closed",
+        timeoutMs: 30_000,
+    }),
+    builtinHook("bounded-evidence", {
+        stages: ["tool_result", "session_stop"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 10_000,
+    }),
+    builtinHook("document-artifact-guard", {
+        stages: ["tool_result"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 5_000,
+    }),
+    builtinHook("component-spec-before-build", {
+        stages: ["tool_call"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 5_000,
+    }),
+    builtinHook("visual-diff-after-edit", {
+        stages: ["tool_result"],
+        effects: ["validator"],
+        failureMode: "fail-closed",
+        timeoutMs: 10_000,
+    }),
 ];
 /**
  * Load the hook inventory. Builtin hooks are always present; if an agent
@@ -27,7 +95,7 @@ export function loadHookInventory(agentDir) {
     if (agentDir) {
         try {
             const hooksDir = path.join(agentDir, "hooks");
-            const entries = fs.readdirSync(hooksDir);
+            const entries = fs.readdirSync(hooksDir).sort();
             for (const entry of entries) {
                 if (!entry.endsWith(".sh"))
                     continue;
@@ -38,6 +106,7 @@ export function loadHookInventory(agentDir) {
                     name,
                     scriptPath: path.join(hooksDir, entry),
                     builtin: false,
+                    policy: sanitizeHookPolicy(DEFAULT_HOOK_POLICY),
                 });
             }
         }

package/dist/core/hook-inventory.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook-inventory.js","sourceRoot":"","sources":["../../src/core/hook-inventory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAY7B,MAAM,CAAC,MAAM,aAAa,GAA8B;IACvD,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC1C,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC1C,EAAE,IAAI,EAAE,iBAAiB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC1C,EAAE,IAAI,EAAE,uBAAuB,EAAE,OAAO,EAAE,IAAI,EAAE;IAChD,EAAE,IAAI,EAAE,sBAAsB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC/C,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,IAAI,EAAE;IACtC,EAAE,IAAI,EAAE,qBAAqB,EAAE,OAAO,EAAE,IAAI,EAAE;IAC9C,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,IAAI,EAAE;CAC5C,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAiB,EAAiB;IACnE,MAAM,KAAK,GAAqB,CAAC,GAAG,aAAa,CAAC,CAAC;IACnD,IAAI,QAAQ,EAAE,CAAC;QACd,IAAI,CAAC;YACJ,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;YAC9C,MAAM,OAAO,GAAG,EAAE,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;YACzC,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC;oBAAE,SAAS;gBACrC,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;gBAChC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,CAAC;oBAAE,SAAS;gBACjD,KAAK,CAAC,IAAI,CAAC;oBACV,IAAI;oBACJ,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC;oBACtC,OAAO,EAAE,KAAK;iBACd,CAAC,CAAC;YACJ,CAAC;QACF,CAAC;QAAC,MAAM,CAAC;YACR,kEAAkE;QACnE,CAAC;IACF,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,CAAC;AAAA,CACjB","sourcesContent":["/**\n * Minimal hook inventory for the loadout runtime.\n *\n * The external harness resolves `scriptPath` to an actual shell script.\n * This module only provides the canonical names and builtin flag so the\n * loadout layer can validate allow/exclude/require selectors.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\n\nexport interface HookDescriptor {\n\tname: string;\n\tscriptPath?: string;\n\tbuiltin: boolean;\n}\n\nexport interface HookInventory {\n\thooks: readonly HookDescriptor[];\n}\n\nexport const BUILTIN_HOOKS: readonly HookDescriptor[] = [\n\t{ name: \"pre-shell-guard\", builtin: true },\n\t{ name: \"protect-secrets\", builtin: true },\n\t{ name: \"session-context\", builtin: true },\n\t{ name: \"precompact-checkpoint\", builtin: true },\n\t{ name: \"typecheck-after-edit\", builtin: true },\n\t{ name: \"stop-verify\", builtin: true },\n\t{ name: \"subagent-stop-audit\", builtin: true },\n\t{ name: \"npm-audit-summary\", builtin: true },\n];\n\n/**\n * Load the hook inventory. Builtin hooks are always present; if an agent\n * directory is provided and its `hooks` subdirectory exists, any shell scripts\n * discovered there are appended as non-builtin descriptors.\n */\nexport function loadHookInventory(agentDir?: string): HookInventory {\n\tconst hooks: HookDescriptor[] = [...BUILTIN_HOOKS];\n\tif (agentDir) {\n\t\ttry {\n\t\t\tconst hooksDir = path.join(agentDir, \"hooks\");\n\t\t\tconst entries = fs.readdirSync(hooksDir);\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (!entry.endsWith(\".sh\")) continue;\n\t\t\t\tconst name = entry.slice(0, -3);\n\t\t\t\tif (hooks.some((h) => h.name === name)) continue;\n\t\t\t\thooks.push({\n\t\t\t\t\tname,\n\t\t\t\t\tscriptPath: path.join(hooksDir, entry),\n\t\t\t\t\tbuiltin: false,\n\t\t\t\t});\n\t\t\t}\n\t\t} catch {\n\t\t\t// Hooks directory may be absent; builtin inventory is sufficient.\n\t\t}\n\t}\n\treturn { hooks };\n}\n"]}
+{"version":3,"file":"hook-inventory.js","sourceRoot":"","sources":["../../src/core/hook-inventory.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Minimal hook inventory for the loadout runtime.\n *\n * The external harness resolves `scriptPath` to an actual shell script.\n * This module provides canonical names plus safe policy metadata so the\n * loadout layer can validate selectors without executing hooks.\n */\n\nimport fs from \"node:fs\";\nimport path from \"node:path\";\nimport type { HookPolicyMetadata } from \"./hooks/index.ts\";\nimport { DEFAULT_HOOK_POLICY, sanitizeHookPolicy } from \"./hooks/index.ts\";\n\nexport interface HookDescriptor {\n\tname: string;\n\tscriptPath?: string;\n\tbuiltin: boolean;\n\tpolicy: HookPolicyMetadata;\n}\n\nexport interface HookInventory {\n\thooks: readonly HookDescriptor[];\n}\n\nfunction builtinHook(name: string, policy: HookPolicyMetadata): HookDescriptor {\n\treturn { name, builtin: true, policy: sanitizeHookPolicy(policy) };\n}\n\nexport const BUILTIN_HOOKS: readonly HookDescriptor[] = [\n\tbuiltinHook(\"pre-shell-guard\", {\n\t\tstages: [\"tool_call\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 3_000,\n\t}),\n\tbuiltinHook(\"protect-secrets\", {\n\t\tstages: [\"tool_call\", \"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"session-context\", {\n\t\tstages: [\"session_start\"],\n\t\teffects: [\"mutator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"precompact-checkpoint\", {\n\t\tstages: [\"pre_compact\"],\n\t\teffects: [\"observer\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"typecheck-after-edit\", {\n\t\tstages: [\"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 30_000,\n\t}),\n\tbuiltinHook(\"stop-verify\", {\n\t\tstages: [\"session_stop\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 30_000,\n\t}),\n\tbuiltinHook(\"subagent-stop-audit\", {\n\t\tstages: [\"session_stop\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 10_000,\n\t}),\n\tbuiltinHook(\"npm-audit-summary\", {\n\t\tstages: [\"session_stop\"],\n\t\teffects: [\"observer\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 30_000,\n\t}),\n\tbuiltinHook(\"bounded-evidence\", {\n\t\tstages: [\"tool_result\", \"session_stop\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 10_000,\n\t}),\n\tbuiltinHook(\"document-artifact-guard\", {\n\t\tstages: [\"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"component-spec-before-build\", {\n\t\tstages: [\"tool_call\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 5_000,\n\t}),\n\tbuiltinHook(\"visual-diff-after-edit\", {\n\t\tstages: [\"tool_result\"],\n\t\teffects: [\"validator\"],\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: 10_000,\n\t}),\n];\n\n/**\n * Load the hook inventory. Builtin hooks are always present; if an agent\n * directory is provided and its `hooks` subdirectory exists, any shell scripts\n * discovered there are appended as non-builtin descriptors.\n */\nexport function loadHookInventory(agentDir?: string): HookInventory {\n\tconst hooks: HookDescriptor[] = [...BUILTIN_HOOKS];\n\tif (agentDir) {\n\t\ttry {\n\t\t\tconst hooksDir = path.join(agentDir, \"hooks\");\n\t\t\tconst entries = fs.readdirSync(hooksDir).sort();\n\t\t\tfor (const entry of entries) {\n\t\t\t\tif (!entry.endsWith(\".sh\")) continue;\n\t\t\t\tconst name = entry.slice(0, -3);\n\t\t\t\tif (hooks.some((h) => h.name === name)) continue;\n\t\t\t\thooks.push({\n\t\t\t\t\tname,\n\t\t\t\t\tscriptPath: path.join(hooksDir, entry),\n\t\t\t\t\tbuiltin: false,\n\t\t\t\t\tpolicy: sanitizeHookPolicy(DEFAULT_HOOK_POLICY),\n\t\t\t\t});\n\t\t\t}\n\t\t} catch {\n\t\t\t// Hooks directory may be absent; builtin inventory is sufficient.\n\t\t}\n\t}\n\treturn { hooks };\n}\n"]}

package/dist/core/hooks/fail-closed.d.ts

@@ -1,6 +1,9 @@
-import type { FailClosedToolCallResult, FailClosedToolResult, HookFailure } from "./types.ts";
+import type { FailClosedToolCallResult, FailClosedToolResult, HookFailure, HookPolicyMetadata } from "./types.ts";
 export declare const FAIL_CLOSED_REASON = "Tool execution was blocked by fail-closed hook policy.";
+export declare const MAX_HOOK_TIMEOUT_MS = 30000;
+export declare const DEFAULT_HOOK_POLICY: HookPolicyMetadata;
 export declare function sanitizeHookFailure(failure?: unknown): HookFailure;
+export declare function sanitizeHookPolicy(policy?: unknown): HookPolicyMetadata;
 export declare function formatFailClosedReason(failure?: unknown): string;
 export declare function createFailClosedToolCallResult(failure?: unknown): FailClosedToolCallResult;
 export declare function createFailClosedToolResult(failure?: unknown): FailClosedToolResult;

package/dist/core/hooks/fail-closed.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fail-closed.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/fail-closed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EAGX,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,kBAAkB,2DAA2D,CAAC;AAsC3F,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,WAAW,CAWlE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAGhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAK1F;AAED,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAMlF","sourcesContent":["import type {\n\tFailClosedToolCallResult,\n\tFailClosedToolResult,\n\tHookFailure,\n\tHookFailureCode,\n\tHookFailureStage,\n} from \"./types.ts\";\n\nexport const FAIL_CLOSED_REASON = \"Tool execution was blocked by fail-closed hook policy.\";\n\nconst DEFAULT_HOOK_FAILURE: HookFailure = {\n\ttype: \"hook_failure\",\n\tsanitized: true,\n\tcode: \"hook_failed\",\n\tstage: \"unknown\",\n};\n\nconst HOOK_FAILURE_CODES: ReadonlySet<string> = new Set<string>([\n\t\"hook_failed\",\n\t\"hook_rejected\",\n\t\"hook_timeout\",\n\t\"hook_unavailable\",\n]);\n\nconst HOOK_FAILURE_STAGES: ReadonlySet<string> = new Set<string>([\"tool_call\", \"tool_result\", \"unknown\"]);\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\nfunction isHookFailureCode(value: unknown): value is HookFailureCode {\n\treturn typeof value === \"string\" && HOOK_FAILURE_CODES.has(value);\n}\n\nfunction isHookFailureStage(value: unknown): value is HookFailureStage {\n\treturn typeof value === \"string\" && HOOK_FAILURE_STAGES.has(value);\n}\n\nfunction readHookFailureCode(value: unknown): HookFailureCode {\n\treturn isHookFailureCode(value) ? value : DEFAULT_HOOK_FAILURE.code;\n}\n\nfunction readHookFailureStage(value: unknown): HookFailureStage {\n\treturn isHookFailureStage(value) ? value : DEFAULT_HOOK_FAILURE.stage;\n}\n\nexport function sanitizeHookFailure(failure?: unknown): HookFailure {\n\tif (!isRecord(failure)) {\n\t\treturn { ...DEFAULT_HOOK_FAILURE };\n\t}\n\n\treturn {\n\t\ttype: \"hook_failure\",\n\t\tsanitized: true,\n\t\tcode: readHookFailureCode(failure.code),\n\t\tstage: readHookFailureStage(failure.stage),\n\t};\n}\n\nexport function formatFailClosedReason(failure?: unknown): string {\n\tvoid failure;\n\treturn FAIL_CLOSED_REASON;\n}\n\nexport function createFailClosedToolCallResult(failure?: unknown): FailClosedToolCallResult {\n\treturn {\n\t\tblock: true,\n\t\treason: formatFailClosedReason(failure),\n\t};\n}\n\nexport function createFailClosedToolResult(failure?: unknown): FailClosedToolResult {\n\treturn {\n\t\tcontent: [{ type: \"text\", text: formatFailClosedReason(failure) }],\n\t\tdetails: sanitizeHookFailure(failure),\n\t\tisError: true,\n\t};\n}\n"]}
+{"version":3,"file":"fail-closed.d.ts","sourceRoot":"","sources":["../../../src/core/hooks/fail-closed.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,wBAAwB,EACxB,oBAAoB,EACpB,WAAW,EAIX,kBAAkB,EAElB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,kBAAkB,2DAA2D,CAAC;AAC3F,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAC1C,eAAO,MAAM,mBAAmB,EAAE,kBAKhC,CAAC;AA0FH,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,WAAW,CAWlE;AAED,wBAAgB,kBAAkB,CAAC,MAAM,CAAC,EAAE,OAAO,GAAG,kBAAkB,CAgBvE;AAED,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,CAGhE;AAED,wBAAgB,8BAA8B,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,wBAAwB,CAK1F;AAED,wBAAgB,0BAA0B,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAMlF","sourcesContent":["import type {\n\tFailClosedToolCallResult,\n\tFailClosedToolResult,\n\tHookFailure,\n\tHookFailureCode,\n\tHookFailureStage,\n\tHookPolicyEffect,\n\tHookPolicyMetadata,\n\tHookPolicyStage,\n} from \"./types.ts\";\n\nexport const FAIL_CLOSED_REASON = \"Tool execution was blocked by fail-closed hook policy.\";\nexport const MAX_HOOK_TIMEOUT_MS = 30_000;\nexport const DEFAULT_HOOK_POLICY: HookPolicyMetadata = freezeHookPolicy({\n\tstages: [\"tool_call\", \"tool_result\"],\n\teffects: [\"validator\"],\n\tfailureMode: \"fail-closed\",\n\ttimeoutMs: 5_000,\n});\n\nconst DEFAULT_HOOK_FAILURE: HookFailure = freezeHookFailure({\n\ttype: \"hook_failure\",\n\tsanitized: true,\n\tcode: \"hook_failed\",\n\tstage: \"unknown\",\n});\n\nconst HOOK_FAILURE_CODES: ReadonlySet<string> = new Set<string>([\n\t\"hook_failed\",\n\t\"hook_rejected\",\n\t\"hook_timeout\",\n\t\"hook_unavailable\",\n]);\n\nconst HOOK_FAILURE_STAGES: ReadonlySet<string> = new Set<string>([\"tool_call\", \"tool_result\", \"unknown\"]);\nconst HOOK_POLICY_STAGES: readonly HookPolicyStage[] = [\n\t\"tool_call\",\n\t\"tool_result\",\n\t\"session_start\",\n\t\"pre_compact\",\n\t\"session_stop\",\n];\nconst HOOK_POLICY_EFFECTS: readonly HookPolicyEffect[] = [\"validator\", \"mutator\", \"observer\"];\nconst HOOK_POLICY_STAGE_SET: ReadonlySet<string> = new Set<string>(HOOK_POLICY_STAGES);\nconst HOOK_POLICY_EFFECT_SET: ReadonlySet<string> = new Set<string>(HOOK_POLICY_EFFECTS);\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\nfunction isHookFailureCode(value: unknown): value is HookFailureCode {\n\treturn typeof value === \"string\" && HOOK_FAILURE_CODES.has(value);\n}\n\nfunction isHookFailureStage(value: unknown): value is HookFailureStage {\n\treturn typeof value === \"string\" && HOOK_FAILURE_STAGES.has(value);\n}\n\nfunction isHookPolicyStage(value: unknown): value is HookPolicyStage {\n\treturn typeof value === \"string\" && HOOK_POLICY_STAGE_SET.has(value);\n}\n\nfunction isHookPolicyEffect(value: unknown): value is HookPolicyEffect {\n\treturn typeof value === \"string\" && HOOK_POLICY_EFFECT_SET.has(value);\n}\n\nfunction readHookFailureCode(value: unknown): HookFailureCode {\n\treturn isHookFailureCode(value) ? value : DEFAULT_HOOK_FAILURE.code;\n}\n\nfunction readHookFailureStage(value: unknown): HookFailureStage {\n\treturn isHookFailureStage(value) ? value : DEFAULT_HOOK_FAILURE.stage;\n}\n\nfunction freezeHookFailure(failure: HookFailure): HookFailure {\n\treturn Object.freeze({ ...failure });\n}\n\nfunction freezeHookPolicy(policy: HookPolicyMetadata): HookPolicyMetadata {\n\treturn Object.freeze({\n\t\tstages: Object.freeze([...policy.stages]),\n\t\teffects: Object.freeze([...policy.effects]),\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: policy.timeoutMs,\n\t});\n}\n\nfunction sanitizePolicyStages(value: unknown): readonly HookPolicyStage[] {\n\tif (!Array.isArray(value)) return [...DEFAULT_HOOK_POLICY.stages];\n\tconst present = new Set(value.filter(isHookPolicyStage));\n\tif (present.size === 0) return [...DEFAULT_HOOK_POLICY.stages];\n\treturn HOOK_POLICY_STAGES.filter((stage) => present.has(stage));\n}\n\nfunction sanitizePolicyEffects(value: unknown): readonly HookPolicyEffect[] {\n\tif (!Array.isArray(value)) return [...DEFAULT_HOOK_POLICY.effects];\n\tconst present = new Set(value.filter(isHookPolicyEffect));\n\tif (present.size === 0) return [...DEFAULT_HOOK_POLICY.effects];\n\treturn HOOK_POLICY_EFFECTS.filter((effect) => present.has(effect));\n}\n\nfunction sanitizePolicyTimeout(value: unknown): number {\n\tif (typeof value !== \"number\" || !Number.isFinite(value)) return DEFAULT_HOOK_POLICY.timeoutMs;\n\tconst timeoutMs = Math.trunc(value);\n\tif (timeoutMs <= 0 || timeoutMs > MAX_HOOK_TIMEOUT_MS) return DEFAULT_HOOK_POLICY.timeoutMs;\n\treturn timeoutMs;\n}\n\nexport function sanitizeHookFailure(failure?: unknown): HookFailure {\n\tif (!isRecord(failure)) {\n\t\treturn freezeHookFailure(DEFAULT_HOOK_FAILURE);\n\t}\n\n\treturn freezeHookFailure({\n\t\ttype: \"hook_failure\",\n\t\tsanitized: true,\n\t\tcode: readHookFailureCode(failure.code),\n\t\tstage: readHookFailureStage(failure.stage),\n\t});\n}\n\nexport function sanitizeHookPolicy(policy?: unknown): HookPolicyMetadata {\n\tif (!isRecord(policy)) {\n\t\treturn freezeHookPolicy({\n\t\t\tstages: [...DEFAULT_HOOK_POLICY.stages],\n\t\t\teffects: [...DEFAULT_HOOK_POLICY.effects],\n\t\t\tfailureMode: \"fail-closed\",\n\t\t\ttimeoutMs: DEFAULT_HOOK_POLICY.timeoutMs,\n\t\t});\n\t}\n\n\treturn freezeHookPolicy({\n\t\tstages: sanitizePolicyStages(policy.stages),\n\t\teffects: sanitizePolicyEffects(policy.effects),\n\t\tfailureMode: \"fail-closed\",\n\t\ttimeoutMs: sanitizePolicyTimeout(policy.timeoutMs),\n\t});\n}\n\nexport function formatFailClosedReason(failure?: unknown): string {\n\tvoid failure;\n\treturn FAIL_CLOSED_REASON;\n}\n\nexport function createFailClosedToolCallResult(failure?: unknown): FailClosedToolCallResult {\n\treturn {\n\t\tblock: true,\n\t\treason: formatFailClosedReason(failure),\n\t};\n}\n\nexport function createFailClosedToolResult(failure?: unknown): FailClosedToolResult {\n\treturn {\n\t\tcontent: [{ type: \"text\", text: formatFailClosedReason(failure) }],\n\t\tdetails: sanitizeHookFailure(failure),\n\t\tisError: true,\n\t};\n}\n"]}

package/dist/core/hooks/fail-closed.js

@@ -1,10 +1,17 @@
 export const FAIL_CLOSED_REASON = "Tool execution was blocked by fail-closed hook policy.";
-const DEFAULT_HOOK_FAILURE = {
+export const MAX_HOOK_TIMEOUT_MS = 30_000;
+export const DEFAULT_HOOK_POLICY = freezeHookPolicy({
+    stages: ["tool_call", "tool_result"],
+    effects: ["validator"],
+    failureMode: "fail-closed",
+    timeoutMs: 5_000,
+});
+const DEFAULT_HOOK_FAILURE = freezeHookFailure({
     type: "hook_failure",
     sanitized: true,
     code: "hook_failed",
     stage: "unknown",
-};
+});
 const HOOK_FAILURE_CODES = new Set([
     "hook_failed",
     "hook_rejected",
@@ -12,6 +19,16 @@ const HOOK_FAILURE_CODES = new Set([
     "hook_unavailable",
 ]);
 const HOOK_FAILURE_STAGES = new Set(["tool_call", "tool_result", "unknown"]);
+const HOOK_POLICY_STAGES = [
+    "tool_call",
+    "tool_result",
+    "session_start",
+    "pre_compact",
+    "session_stop",
+];
+const HOOK_POLICY_EFFECTS = ["validator", "mutator", "observer"];
+const HOOK_POLICY_STAGE_SET = new Set(HOOK_POLICY_STAGES);
+const HOOK_POLICY_EFFECT_SET = new Set(HOOK_POLICY_EFFECTS);
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
@@ -21,22 +38,79 @@ function isHookFailureCode(value) {
 function isHookFailureStage(value) {
     return typeof value === "string" && HOOK_FAILURE_STAGES.has(value);
 }
+function isHookPolicyStage(value) {
+    return typeof value === "string" && HOOK_POLICY_STAGE_SET.has(value);
+}
+function isHookPolicyEffect(value) {
+    return typeof value === "string" && HOOK_POLICY_EFFECT_SET.has(value);
+}
 function readHookFailureCode(value) {
     return isHookFailureCode(value) ? value : DEFAULT_HOOK_FAILURE.code;
 }
 function readHookFailureStage(value) {
     return isHookFailureStage(value) ? value : DEFAULT_HOOK_FAILURE.stage;
 }
+function freezeHookFailure(failure) {
+    return Object.freeze({ ...failure });
+}
+function freezeHookPolicy(policy) {
+    return Object.freeze({
+        stages: Object.freeze([...policy.stages]),
+        effects: Object.freeze([...policy.effects]),
+        failureMode: "fail-closed",
+        timeoutMs: policy.timeoutMs,
+    });
+}
+function sanitizePolicyStages(value) {
+    if (!Array.isArray(value))
+        return [...DEFAULT_HOOK_POLICY.stages];
+    const present = new Set(value.filter(isHookPolicyStage));
+    if (present.size === 0)
+        return [...DEFAULT_HOOK_POLICY.stages];
+    return HOOK_POLICY_STAGES.filter((stage) => present.has(stage));
+}
+function sanitizePolicyEffects(value) {
+    if (!Array.isArray(value))
+        return [...DEFAULT_HOOK_POLICY.effects];
+    const present = new Set(value.filter(isHookPolicyEffect));
+    if (present.size === 0)
+        return [...DEFAULT_HOOK_POLICY.effects];
+    return HOOK_POLICY_EFFECTS.filter((effect) => present.has(effect));
+}
+function sanitizePolicyTimeout(value) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return DEFAULT_HOOK_POLICY.timeoutMs;
+    const timeoutMs = Math.trunc(value);
+    if (timeoutMs <= 0 || timeoutMs > MAX_HOOK_TIMEOUT_MS)
+        return DEFAULT_HOOK_POLICY.timeoutMs;
+    return timeoutMs;
+}
 export function sanitizeHookFailure(failure) {
     if (!isRecord(failure)) {
-        return { ...DEFAULT_HOOK_FAILURE };
+        return freezeHookFailure(DEFAULT_HOOK_FAILURE);
     }
-    return {
+    return freezeHookFailure({
         type: "hook_failure",
         sanitized: true,
         code: readHookFailureCode(failure.code),
         stage: readHookFailureStage(failure.stage),
-    };
+    });
+}
+export function sanitizeHookPolicy(policy) {
+    if (!isRecord(policy)) {
+        return freezeHookPolicy({
+            stages: [...DEFAULT_HOOK_POLICY.stages],
+            effects: [...DEFAULT_HOOK_POLICY.effects],
+            failureMode: "fail-closed",
+            timeoutMs: DEFAULT_HOOK_POLICY.timeoutMs,
+        });
+    }
+    return freezeHookPolicy({
+        stages: sanitizePolicyStages(policy.stages),
+        effects: sanitizePolicyEffects(policy.effects),
+        failureMode: "fail-closed",
+        timeoutMs: sanitizePolicyTimeout(policy.timeoutMs),
+    });
 }
 export function formatFailClosedReason(failure) {
     void failure;