@mauribadnights/clooks 0.2.2 → 0.3.1

package/dist/handlers.d.ts

@@ -3,15 +3,18 @@ import type { HandlerConfig, HandlerResult, HandlerState, HookEvent, HookInput,
 export declare function resetHandlerStates(): void;
 /** Get a copy of the handler states map */
 export declare function getHandlerStates(): Map<string, HandlerState>;
+/** Clean up state for a specific handler ID (used during manifest reload diffs). */
+export declare function cleanupHandlerState(handlerId: string): void;
 /**
  * Reset handler states for handlers that have sessionIsolation: true.
  * Called on SessionStart events.
  */
 export declare function resetSessionIsolatedHandlers(handlers: HandlerConfig[]): void;
 /**
- * Execute all handlers for an event in parallel.
- * Returns merged results array.
- * Optionally accepts pre-fetched context for LLM prompt rendering.
+ * Execute all handlers for an event, respecting dependency order.
+ * Handlers are grouped into "waves" via topological sort.
+ * Within each wave, handlers run in parallel.
+ * Outputs from previous waves are available to dependent handlers via _handlerOutputs.
  */
 export declare function executeHandlers(_event: HookEvent, input: HookInput, handlers: HandlerConfig[], context?: PrefetchContext): Promise<HandlerResult[]>;
 /**

package/dist/handlers.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetHandlerStates = resetHandlerStates;
 exports.getHandlerStates = getHandlerStates;
+exports.cleanupHandlerState = cleanupHandlerState;
 exports.resetSessionIsolatedHandlers = resetSessionIsolatedHandlers;
 exports.executeHandlers = executeHandlers;
 exports.executeScriptHandler = executeScriptHandler;
@@ -13,6 +14,7 @@ const path_1 = require("path");
 const constants_js_1 = require("./constants.js");
 const filter_js_1 = require("./filter.js");
 const llm_js_1 = require("./llm.js");
+const deps_js_1 = require("./deps.js");
 /** Runtime state per handler ID */
 const handlerStates = new Map();
 function getState(id) {
@@ -31,6 +33,10 @@ function resetHandlerStates() {
 function getHandlerStates() {
     return new Map(handlerStates);
 }
+/** Clean up state for a specific handler ID (used during manifest reload diffs). */
+function cleanupHandlerState(handlerId) {
+    handlerStates.delete(handlerId);
+}
 /**
  * Reset handler states for handlers that have sessionIsolation: true.
  * Called on SessionStart events.
@@ -49,17 +55,16 @@ function resetSessionIsolatedHandlers(handlers) {
     }
 }
 /**
- * Execute all handlers for an event in parallel.
- * Returns merged results array.
- * Optionally accepts pre-fetched context for LLM prompt rendering.
+ * Execute all handlers for an event, respecting dependency order.
+ * Handlers are grouped into "waves" via topological sort.
+ * Within each wave, handlers run in parallel.
+ * Outputs from previous waves are available to dependent handlers via _handlerOutputs.
  */
 async function executeHandlers(_event, input, handlers, context) {
-    // Separate LLM handlers from script/inline, applying shared pre-checks
-    const llmHandlers = [];
-    const otherPromises = [];
+    // Pre-check: filter out disabled/auto-disabled/filtered handlers before dep resolution
+    const eligible = [];
     const skippedResults = [];
     for (const handler of handlers) {
-        // Skip disabled handlers (both manifest-disabled and auto-disabled)
         if (handler.enabled === false) {
             skippedResults.push({ id: handler.id, ok: true, output: undefined, duration_ms: 0 });
             continue;
@@ -74,7 +79,6 @@ async function executeHandlers(_event, input, handlers, context) {
             });
             continue;
         }
-        // Evaluate keyword filter before execution
         if (handler.filter) {
             const inputStr = JSON.stringify(input);
             if (!(0, filter_js_1.evaluateFilter)(handler.filter, inputStr)) {
@@ -88,51 +92,82 @@ async function executeHandlers(_event, input, handlers, context) {
                 continue;
             }
         }
-        state.totalFires++;
-        if (handler.type === 'llm') {
-            llmHandlers.push(handler);
-        }
-        else {
-            // Execute script/inline handlers in parallel
-            otherPromises.push(executeOtherHandler(handler, input));
-        }
+        eligible.push(handler);
+    }
+    if (eligible.length === 0) {
+        return skippedResults;
     }
-    // Execute script/inline handlers in parallel
-    const otherResults = otherPromises.length > 0
-        ? await Promise.all(otherPromises)
-        : [];
-    // Execute LLM handlers with batching (graceful — never crashes)
-    let llmResults = [];
-    if (llmHandlers.length > 0) {
-        try {
-            llmResults = await (0, llm_js_1.executeLLMHandlersBatched)(llmHandlers, input, context ?? {});
+    // Resolve execution order into waves
+    let waves;
+    try {
+        waves = (0, deps_js_1.resolveExecutionOrder)(eligible);
+    }
+    catch {
+        // If dep resolution fails, fall back to flat parallel execution
+        waves = [eligible];
+    }
+    const allResults = [...skippedResults];
+    const handlerOutputs = {};
+    for (const wave of waves) {
+        // Mark totalFires for all handlers in this wave
+        for (const handler of wave) {
+            getState(handler.id).totalFires++;
         }
-        catch (err) {
-            // Graceful degradation: if LLM execution entirely fails, return error results
-            const errorMsg = err instanceof Error ? err.message : String(err);
-            llmResults = llmHandlers.map(h => ({
-                id: h.id,
-                ok: false,
-                error: `LLM execution failed: ${errorMsg}`,
-                duration_ms: 0,
-            }));
+        // Build input with _handlerOutputs from previous waves
+        const waveInput = Object.keys(handlerOutputs).length > 0
+            ? { ...input, _handlerOutputs: handlerOutputs }
+            : input;
+        // Separate LLM from script/inline within this wave
+        const llmHandlers = [];
+        const otherPromises = [];
+        for (const handler of wave) {
+            if (handler.type === 'llm') {
+                llmHandlers.push(handler);
+            }
+            else {
+                otherPromises.push(executeOtherHandler(handler, waveInput));
+            }
         }
-    }
-    // Update failure tracking for all executed results
-    for (const result of [...otherResults, ...llmResults]) {
-        const state = getState(result.id);
-        if (result.ok) {
-            state.consecutiveFailures = 0;
+        // Execute script/inline handlers in parallel
+        const otherResults = otherPromises.length > 0
+            ? await Promise.all(otherPromises)
+            : [];
+        // Execute LLM handlers with batching (scoped to this wave)
+        let llmResults = [];
+        if (llmHandlers.length > 0) {
+            try {
+                llmResults = await (0, llm_js_1.executeLLMHandlersBatched)(llmHandlers, waveInput, context ?? {}, input.session_id);
+            }
+            catch (err) {
+                const errorMsg = err instanceof Error ? err.message : String(err);
+                llmResults = llmHandlers.map(h => ({
+                    id: h.id,
+                    ok: false,
+                    error: `LLM execution failed: ${errorMsg}`,
+                    duration_ms: 0,
+                }));
+            }
         }
-        else {
-            state.consecutiveFailures++;
-            state.totalErrors++;
-            if (state.consecutiveFailures >= constants_js_1.MAX_CONSECUTIVE_FAILURES) {
-                state.disabled = true;
+        const waveResults = [...otherResults, ...llmResults];
+        // Update failure tracking and collect outputs for dependents
+        for (const result of waveResults) {
+            const state = getState(result.id);
+            if (result.ok) {
+                state.consecutiveFailures = 0;
+            }
+            else {
+                state.consecutiveFailures++;
+                state.totalErrors++;
+                if (state.consecutiveFailures >= constants_js_1.MAX_CONSECUTIVE_FAILURES) {
+                    state.disabled = true;
+                }
             }
+            // Store output for downstream handlers
+            handlerOutputs[result.id] = result.output;
         }
+        allResults.push(...waveResults);
     }
-    return [...skippedResults, ...otherResults, ...llmResults];
+    return allResults;
 }
 /**
  * Execute a single script or inline handler with error handling.

package/dist/index.d.ts

@@ -1,14 +1,19 @@
 export { createServer, startDaemon, stopDaemon, isDaemonRunning } from './server.js';
-export { loadManifest, validateManifest, createDefaultManifest } from './manifest.js';
+export { loadManifest, loadCompositeManifest, validateManifest, createDefaultManifest } from './manifest.js';
+export { loadPlugins, mergeManifests, validatePluginManifest, loadRegistry, saveRegistry, installPlugin, uninstallPlugin, listPlugins } from './plugin.js';
 export { MetricsCollector } from './metrics.js';
 export { migrate, restore, getSettingsPath } from './migrate.js';
 export type { MigratePathOptions } from './migrate.js';
 export { runDoctor } from './doctor.js';
-export { executeHandlers, resetSessionIsolatedHandlers } from './handlers.js';
+export { executeHandlers, resetSessionIsolatedHandlers, cleanupHandlerState } from './handlers.js';
+export { resolveExecutionOrder } from './deps.js';
+export { DenyCache } from './shortcircuit.js';
+export { RateLimiter } from './ratelimit.js';
 export { startWatcher, stopWatcher } from './watcher.js';
-export { generateAuthToken, validateAuth } from './auth.js';
+export { generateAuthToken, validateAuth, rotateToken } from './auth.js';
+export type { RotateTokenOptions } from './auth.js';
 export { evaluateFilter } from './filter.js';
 export { executeLLMHandler, executeLLMHandlersBatched, calculateCost, resetClient } from './llm.js';
 export { prefetchContext, renderPromptTemplate } from './prefetch.js';
-export { DEFAULT_PORT, CONFIG_DIR, MANIFEST_PATH, PID_FILE, METRICS_FILE, LOG_FILE, COSTS_FILE, DEFAULT_LLM_TIMEOUT, DEFAULT_LLM_MAX_TOKENS, LLM_PRICING } from './constants.js';
-export type { HookEvent, HookInput, HandlerType, HandlerConfig, ScriptHandlerConfig, InlineHandlerConfig, LLMHandlerConfig, LLMModel, Manifest, HandlerResult, MetricEntry, HandlerState, DiagnosticResult, PrefetchKey, PrefetchContext, TokenUsage, CostEntry, } from './types.js';
+export { DEFAULT_PORT, CONFIG_DIR, MANIFEST_PATH, PID_FILE, METRICS_FILE, LOG_FILE, COSTS_FILE, DEFAULT_LLM_TIMEOUT, DEFAULT_LLM_MAX_TOKENS, LLM_PRICING, PLUGINS_DIR, PLUGIN_REGISTRY, PLUGIN_MANIFEST_NAME } from './constants.js';
+export type { HookEvent, HookInput, HandlerType, HandlerConfig, ScriptHandlerConfig, InlineHandlerConfig, LLMHandlerConfig, LLMModel, Manifest, HandlerResult, MetricEntry, HandlerState, DiagnosticResult, PrefetchKey, PrefetchContext, TokenUsage, CostEntry, PluginManifest, InstalledPlugin, PluginRegistry, } from './types.js';

package/dist/index.js

@@ -1,7 +1,8 @@
 "use strict";
 // clooks — public API exports
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = exports.renderPromptTemplate = exports.prefetchContext = exports.resetClient = exports.calculateCost = exports.executeLLMHandlersBatched = exports.executeLLMHandler = exports.evaluateFilter = exports.validateAuth = exports.generateAuthToken = exports.stopWatcher = exports.startWatcher = exports.resetSessionIsolatedHandlers = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.createDefaultManifest = exports.validateManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = void 0;
+exports.PLUGINS_DIR = exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = exports.renderPromptTemplate = exports.prefetchContext = exports.resetClient = exports.calculateCost = exports.executeLLMHandlersBatched = exports.executeLLMHandler = exports.evaluateFilter = exports.rotateToken = exports.validateAuth = exports.generateAuthToken = exports.stopWatcher = exports.startWatcher = exports.RateLimiter = exports.DenyCache = exports.resolveExecutionOrder = exports.cleanupHandlerState = exports.resetSessionIsolatedHandlers = exports.executeHandlers = exports.runDoctor = exports.getSettingsPath = exports.restore = exports.migrate = exports.MetricsCollector = exports.listPlugins = exports.uninstallPlugin = exports.installPlugin = exports.saveRegistry = exports.loadRegistry = exports.validatePluginManifest = exports.mergeManifests = exports.loadPlugins = exports.createDefaultManifest = exports.validateManifest = exports.loadCompositeManifest = exports.loadManifest = exports.isDaemonRunning = exports.stopDaemon = exports.startDaemon = exports.createServer = void 0;
+exports.PLUGIN_MANIFEST_NAME = exports.PLUGIN_REGISTRY = void 0;
 var server_js_1 = require("./server.js");
 Object.defineProperty(exports, "createServer", { enumerable: true, get: function () { return server_js_1.createServer; } });
 Object.defineProperty(exports, "startDaemon", { enumerable: true, get: function () { return server_js_1.startDaemon; } });
@@ -9,8 +10,18 @@ Object.defineProperty(exports, "stopDaemon", { enumerable: true, get: function (
 Object.defineProperty(exports, "isDaemonRunning", { enumerable: true, get: function () { return server_js_1.isDaemonRunning; } });
 var manifest_js_1 = require("./manifest.js");
 Object.defineProperty(exports, "loadManifest", { enumerable: true, get: function () { return manifest_js_1.loadManifest; } });
+Object.defineProperty(exports, "loadCompositeManifest", { enumerable: true, get: function () { return manifest_js_1.loadCompositeManifest; } });
 Object.defineProperty(exports, "validateManifest", { enumerable: true, get: function () { return manifest_js_1.validateManifest; } });
 Object.defineProperty(exports, "createDefaultManifest", { enumerable: true, get: function () { return manifest_js_1.createDefaultManifest; } });
+var plugin_js_1 = require("./plugin.js");
+Object.defineProperty(exports, "loadPlugins", { enumerable: true, get: function () { return plugin_js_1.loadPlugins; } });
+Object.defineProperty(exports, "mergeManifests", { enumerable: true, get: function () { return plugin_js_1.mergeManifests; } });
+Object.defineProperty(exports, "validatePluginManifest", { enumerable: true, get: function () { return plugin_js_1.validatePluginManifest; } });
+Object.defineProperty(exports, "loadRegistry", { enumerable: true, get: function () { return plugin_js_1.loadRegistry; } });
+Object.defineProperty(exports, "saveRegistry", { enumerable: true, get: function () { return plugin_js_1.saveRegistry; } });
+Object.defineProperty(exports, "installPlugin", { enumerable: true, get: function () { return plugin_js_1.installPlugin; } });
+Object.defineProperty(exports, "uninstallPlugin", { enumerable: true, get: function () { return plugin_js_1.uninstallPlugin; } });
+Object.defineProperty(exports, "listPlugins", { enumerable: true, get: function () { return plugin_js_1.listPlugins; } });
 var metrics_js_1 = require("./metrics.js");
 Object.defineProperty(exports, "MetricsCollector", { enumerable: true, get: function () { return metrics_js_1.MetricsCollector; } });
 var migrate_js_1 = require("./migrate.js");
@@ -22,12 +33,20 @@ Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function ()
 var handlers_js_1 = require("./handlers.js");
 Object.defineProperty(exports, "executeHandlers", { enumerable: true, get: function () { return handlers_js_1.executeHandlers; } });
 Object.defineProperty(exports, "resetSessionIsolatedHandlers", { enumerable: true, get: function () { return handlers_js_1.resetSessionIsolatedHandlers; } });
+Object.defineProperty(exports, "cleanupHandlerState", { enumerable: true, get: function () { return handlers_js_1.cleanupHandlerState; } });
+var deps_js_1 = require("./deps.js");
+Object.defineProperty(exports, "resolveExecutionOrder", { enumerable: true, get: function () { return deps_js_1.resolveExecutionOrder; } });
+var shortcircuit_js_1 = require("./shortcircuit.js");
+Object.defineProperty(exports, "DenyCache", { enumerable: true, get: function () { return shortcircuit_js_1.DenyCache; } });
+var ratelimit_js_1 = require("./ratelimit.js");
+Object.defineProperty(exports, "RateLimiter", { enumerable: true, get: function () { return ratelimit_js_1.RateLimiter; } });
 var watcher_js_1 = require("./watcher.js");
 Object.defineProperty(exports, "startWatcher", { enumerable: true, get: function () { return watcher_js_1.startWatcher; } });
 Object.defineProperty(exports, "stopWatcher", { enumerable: true, get: function () { return watcher_js_1.stopWatcher; } });
 var auth_js_1 = require("./auth.js");
 Object.defineProperty(exports, "generateAuthToken", { enumerable: true, get: function () { return auth_js_1.generateAuthToken; } });
 Object.defineProperty(exports, "validateAuth", { enumerable: true, get: function () { return auth_js_1.validateAuth; } });
+Object.defineProperty(exports, "rotateToken", { enumerable: true, get: function () { return auth_js_1.rotateToken; } });
 var filter_js_1 = require("./filter.js");
 Object.defineProperty(exports, "evaluateFilter", { enumerable: true, get: function () { return filter_js_1.evaluateFilter; } });
 var llm_js_1 = require("./llm.js");
@@ -49,3 +68,6 @@ Object.defineProperty(exports, "COSTS_FILE", { enumerable: true, get: function (
 Object.defineProperty(exports, "DEFAULT_LLM_TIMEOUT", { enumerable: true, get: function () { return constants_js_1.DEFAULT_LLM_TIMEOUT; } });
 Object.defineProperty(exports, "DEFAULT_LLM_MAX_TOKENS", { enumerable: true, get: function () { return constants_js_1.DEFAULT_LLM_MAX_TOKENS; } });
 Object.defineProperty(exports, "LLM_PRICING", { enumerable: true, get: function () { return constants_js_1.LLM_PRICING; } });
+Object.defineProperty(exports, "PLUGINS_DIR", { enumerable: true, get: function () { return constants_js_1.PLUGINS_DIR; } });
+Object.defineProperty(exports, "PLUGIN_REGISTRY", { enumerable: true, get: function () { return constants_js_1.PLUGIN_REGISTRY; } });
+Object.defineProperty(exports, "PLUGIN_MANIFEST_NAME", { enumerable: true, get: function () { return constants_js_1.PLUGIN_MANIFEST_NAME; } });

package/dist/llm.d.ts

@@ -16,4 +16,4 @@ export declare function executeLLMHandler(handler: LLMHandlerConfig, input: Hook
  * a single API call with a structured multi-task prompt. Handlers without a
  * batchGroup are executed individually.
  */
-export declare function executeLLMHandlersBatched(handlers: LLMHandlerConfig[], input: HookInput, context: PrefetchContext): Promise<HandlerResult[]>;
+export declare function executeLLMHandlersBatched(handlers: LLMHandlerConfig[], input: HookInput, context: PrefetchContext, sessionId?: string): Promise<HandlerResult[]>;

package/dist/llm.js

@@ -190,15 +190,19 @@ function splitUsage(total, count) {
  * a single API call with a structured multi-task prompt. Handlers without a
  * batchGroup are executed individually.
  */
-async function executeLLMHandlersBatched(handlers, input, context) {
-    // Group by batchGroup
+async function executeLLMHandlersBatched(handlers, input, context, sessionId) {
+    // Group by batchGroup, scoped by sessionId to prevent cross-session batching
     const grouped = new Map();
     const ungrouped = [];
     for (const handler of handlers) {
         if (handler.batchGroup) {
-            const existing = grouped.get(handler.batchGroup) ?? [];
+            // Scope the batch key by sessionId so different sessions never batch together
+            const batchKey = sessionId
+                ? `${handler.batchGroup}:${sessionId}`
+                : handler.batchGroup;
+            const existing = grouped.get(batchKey) ?? [];
             existing.push(handler);
-            grouped.set(handler.batchGroup, existing);
+            grouped.set(batchKey, existing);
         }
         else {
             ungrouped.push(handler);

package/dist/manifest.d.ts

@@ -9,6 +9,10 @@ export declare function loadManifest(): Manifest;
  * Throws on invalid structure.
  */
 export declare function validateManifest(manifest: Manifest): void;
+/**
+ * Load the composite manifest: user manifest + all installed plugins.
+ */
+export declare function loadCompositeManifest(): Manifest;
 /**
  * Create a default commented example manifest.yaml in CONFIG_DIR.
  */

package/dist/manifest.js

@@ -3,10 +3,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadManifest = loadManifest;
 exports.validateManifest = validateManifest;
+exports.loadCompositeManifest = loadCompositeManifest;
 exports.createDefaultManifest = createDefaultManifest;
 const fs_1 = require("fs");
+const path_1 = require("path");
 const yaml_1 = require("yaml");
 const constants_js_1 = require("./constants.js");
+const plugin_js_1 = require("./plugin.js");
+const builtin_hooks_js_1 = require("./builtin-hooks.js");
 /**
  * Load and validate the manifest from disk.
  * Returns a Manifest with empty handlers if the file doesn't exist.
@@ -99,6 +103,14 @@ function validateManifest(manifest) {
         }
     }
 }
+/**
+ * Load the composite manifest: user manifest + all installed plugins.
+ */
+function loadCompositeManifest() {
+    const userManifest = loadManifest();
+    const plugins = (0, plugin_js_1.loadPlugins)();
+    return (0, plugin_js_1.mergeManifests)(userManifest, plugins);
+}
 /**
  * Create a default commented example manifest.yaml in CONFIG_DIR.
  */
@@ -113,8 +125,20 @@ function createDefaultManifest(authToken) {
     if (authToken) {
         settings.authToken = authToken;
     }
+    // Install built-in hook scripts to CONFIG_DIR/hooks/
+    (0, builtin_hooks_js_1.installBuiltinHooks)();
+    const checkUpdatePath = (0, path_1.join)(constants_js_1.HOOKS_DIR, 'check-update.js');
     const example = {
         handlers: {
+            SessionStart: [
+                {
+                    id: 'clooks-check-update',
+                    type: 'script',
+                    command: `node ${checkUpdatePath}`,
+                    timeout: 6000,
+                    enabled: true,
+                },
+            ],
             PreToolUse: [
                 {
                     id: 'example-guard',

package/dist/metrics.d.ts

@@ -7,6 +7,16 @@ interface AggregatedStats {
     minDuration: number;
     maxDuration: number;
 }
+export interface HandlerStats {
+    handler: string;
+    event: string;
+    fires: number;
+    errors: number;
+    filtered: number;
+    avgDuration: number;
+    minDuration: number;
+    maxDuration: number;
+}
 export declare class MetricsCollector {
     private static readonly MAX_ENTRIES;
     private entries;
@@ -22,6 +32,10 @@ export declare class MetricsCollector {
     getStats(): AggregatedStats[];
     /** Get stats for a specific session. */
     getSessionStats(sessionId: string): AggregatedStats[];
+    /** Get per-handler stats (not just per-event). */
+    getHandlerStats(): HandlerStats[];
+    /** Format per-handler stats as a CLI-friendly table. */
+    formatHandlerStatsTable(): string;
     /** Flush is a no-op since we append on every record, but provided for API completeness. */
     flush(): void;
     /** Format stats as a CLI-friendly table. */

package/dist/metrics.js

@@ -95,6 +95,53 @@ class MetricsCollector {
         }
         return stats.sort((a, b) => b.fires - a.fires);
     }
+    /** Get per-handler stats (not just per-event). */
+    getHandlerStats() {
+        const all = this.loadAll();
+        const byHandler = new Map();
+        for (const entry of all) {
+            const existing = byHandler.get(entry.handler) ?? [];
+            existing.push(entry);
+            byHandler.set(entry.handler, existing);
+        }
+        const stats = [];
+        for (const [handler, entries] of byHandler) {
+            const durations = entries.map((e) => e.duration_ms);
+            stats.push({
+                handler,
+                event: entries[0].event,
+                fires: entries.length,
+                errors: entries.filter((e) => !e.ok).length,
+                filtered: entries.filter((e) => e.filtered).length,
+                avgDuration: durations.reduce((a, b) => a + b, 0) / durations.length,
+                minDuration: Math.min(...durations),
+                maxDuration: Math.max(...durations),
+            });
+        }
+        return stats.sort((a, b) => {
+            if (b.fires !== a.fires)
+                return b.fires - a.fires;
+            return b.avgDuration - a.avgDuration;
+        });
+    }
+    /** Format per-handler stats as a CLI-friendly table. */
+    formatHandlerStatsTable() {
+        const stats = this.getHandlerStats();
+        if (stats.length === 0) {
+            return 'No per-handler metrics recorded yet.';
+        }
+        const header = padHandlerRow(['Handler', 'Event', 'Fires', 'Errors', 'Avg ms', 'Max ms']);
+        const separator = '-'.repeat(header.length);
+        const rows = stats.map((s) => padHandlerRow([
+            s.handler,
+            s.event,
+            String(s.fires),
+            String(s.errors),
+            s.avgDuration.toFixed(1),
+            s.maxDuration.toFixed(1),
+        ]));
+        return [header, separator, ...rows].join('\n');
+    }
     /** Flush is a no-op since we append on every record, but provided for API completeness. */
     flush() {
         // Already written on each record()
@@ -249,3 +296,7 @@ function padRow(cols) {
     const widths = [20, 8, 8, 10, 10, 10];
     return cols.map((col, i) => col.padEnd(widths[i])).join('  ');
 }
+function padHandlerRow(cols) {
+    const widths = [35, 20, 7, 7, 8, 8];
+    return cols.map((col, i) => col.padEnd(widths[i])).join('  ');
+}

package/dist/migrate.d.ts

@@ -11,6 +11,15 @@ export interface MigratePathOptions {
  * Find the Claude Code settings.json path.
  */
 export declare function getSettingsPath(options?: MigratePathOptions): string | null;
+/**
+ * Derive a readable handler ID from a hook command.
+ *
+ * "node /path/to/gsd-check-update.js" -> "gsd-check-update"
+ * "node /path/to/hooks/post-action.js" -> "post-action"
+ * "python3 -m almicio.hooks.session_context" -> "almicio-session-context"
+ * "bash -c 'source ~/.zshrc; python3 /path/to/tts-summary.py'" -> "tts-summary"
+ */
+export declare function deriveHandlerId(command: string, event: string, index: number): string;
 /**
  * Migrate Claude Code settings.json command hooks to clooks HTTP hooks.
  *

package/dist/migrate.js

@@ -2,12 +2,14 @@
 // clooks migration utilities — convert shell hooks to HTTP hooks
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getSettingsPath = getSettingsPath;
+exports.deriveHandlerId = deriveHandlerId;
 exports.migrate = migrate;
 exports.restore = restore;
 const fs_1 = require("fs");
 const path_1 = require("path");
 const os_1 = require("os");
 const constants_js_1 = require("./constants.js");
+const builtin_hooks_js_1 = require("./builtin-hooks.js");
 const yaml_1 = require("yaml");
 /**
  * Find the Claude Code settings.json path.
@@ -25,6 +27,46 @@ function getSettingsPath(options) {
     }
     return null;
 }
+/**
+ * Derive a readable handler ID from a hook command.
+ *
+ * "node /path/to/gsd-check-update.js" -> "gsd-check-update"
+ * "node /path/to/hooks/post-action.js" -> "post-action"
+ * "python3 -m almicio.hooks.session_context" -> "almicio-session-context"
+ * "bash -c 'source ~/.zshrc; python3 /path/to/tts-summary.py'" -> "tts-summary"
+ */
+function deriveHandlerId(command, event, index) {
+    let basename = null;
+    // Try python3 -m module.name pattern
+    const moduleMatch = command.match(/python3?\s+-m\s+([\w.]+)/);
+    if (moduleMatch) {
+        const modulePath = moduleMatch[1];
+        const lastSegment = modulePath.split('.').pop() ?? '';
+        if (lastSegment)
+            basename = lastSegment;
+    }
+    // Try to find the last .js or .py file in the command
+    if (!basename) {
+        // Match quoted or unquoted file paths ending in .js or .py
+        const fileMatches = [...command.matchAll(/(?:["'])?([^\s"']+\.(?:js|py))(?:["'])?/g)];
+        if (fileMatches.length > 0) {
+            const lastFile = fileMatches[fileMatches.length - 1][1];
+            // Extract basename without extension
+            const parts = lastFile.split('/');
+            const filename = parts[parts.length - 1];
+            basename = filename.replace(/\.(js|py)$/, '');
+        }
+    }
+    if (!basename) {
+        return `migrated-${event.toLowerCase()}-${index}`;
+    }
+    // Sanitize: replace non-alphanumeric chars with hyphens, lowercase
+    let id = basename.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!id) {
+        return `migrated-${event.toLowerCase()}-${index}`;
+    }
+    return id;
+}
 /**
  * Migrate Claude Code settings.json command hooks to clooks HTTP hooks.
  *
@@ -60,6 +102,7 @@ function migrate(options) {
     // Extract command hooks and build manifest
     const manifestHandlers = {};
     let handlerIndex = 0;
+    const usedIds = new Set();
     // NOTE: In v0.1, matchers from the original rule groups are not preserved in the
     // migrated HTTP hooks — all command hooks are consolidated into matcher-less rule groups.
     // This is acceptable because clooks dispatches based on event type, not matchers.
@@ -82,8 +125,14 @@ function migrate(options) {
             continue;
         manifestHandlers[event] = commandHooks.map((hook) => {
             handlerIndex++;
+            let id = deriveHandlerId(hook.command, event, handlerIndex);
+            // Ensure uniqueness: if ID already used, append index
+            if (usedIds.has(id)) {
+                id = `${id}-${handlerIndex}`;
+            }
+            usedIds.add(id);
             return {
-                id: `migrated-${event.toLowerCase()}-${handlerIndex}`,
+                id,
                 type: 'script',
                 command: hook.command,
                 timeout: hook.timeout ? hook.timeout * 1000 : 5000, // Claude uses seconds, we use ms
@@ -91,6 +140,20 @@ function migrate(options) {
             };
         });
     }
+    // Install built-in hook scripts
+    (0, builtin_hooks_js_1.installBuiltinHooks)();
+    // Add update checker to SessionStart handlers
+    const checkUpdatePath = (0, path_1.join)(constants_js_1.HOOKS_DIR, 'check-update.js');
+    if (!manifestHandlers['SessionStart']) {
+        manifestHandlers['SessionStart'] = [];
+    }
+    manifestHandlers['SessionStart'].unshift({
+        id: 'clooks-check-update',
+        type: 'script',
+        command: `node ${checkUpdatePath}`,
+        timeout: 6000,
+        enabled: true,
+    });
     // Write manifest.yaml
     const manifest = {
         handlers: manifestHandlers,

package/dist/plugin.d.ts

@@ -0,0 +1,50 @@
+import type { PluginManifest, PluginRegistry, InstalledPlugin, Manifest } from './types.js';
+/**
+ * Load the plugin registry (installed.json).
+ */
+export declare function loadRegistry(registryPath?: string): PluginRegistry;
+/**
+ * Save the plugin registry.
+ */
+export declare function saveRegistry(registry: PluginRegistry, registryPath?: string): void;
+/**
+ * Validate a plugin manifest.
+ * Similar to validateManifest but checks plugin-specific fields (name, version required).
+ */
+export declare function validatePluginManifest(manifest: PluginManifest): void;
+/**
+ * Load all installed plugins and return their manifests.
+ */
+export declare function loadPlugins(pluginsDir?: string, registryPath?: string): {
+    name: string;
+    manifest: PluginManifest;
+}[];
+/**
+ * Merge user manifest + plugin manifests into a composite manifest.
+ * Plugin handler IDs are namespaced as "pluginName/handlerId".
+ * Prefetch keys are unioned.
+ * Settings come from user manifest only.
+ */
+export declare function mergeManifests(userManifest: Manifest, plugins: {
+    name: string;
+    manifest: PluginManifest;
+}[]): Manifest;
+/**
+ * Install a plugin from a local directory path.
+ * 1. Read clooks-plugin.yaml from the path
+ * 2. Validate it
+ * 3. Copy the directory to plugins dir under {name}/
+ * 4. Register in installed.json
+ * 5. Resolve $PLUGIN_DIR in handler commands to the installed path
+ */
+export declare function installPlugin(sourcePath: string, pluginsDir?: string, registryPath?: string): InstalledPlugin;
+/**
+ * Uninstall a plugin by name.
+ * 1. Remove from installed.json
+ * 2. Delete the plugin directory
+ */
+export declare function uninstallPlugin(name: string, pluginsDir?: string, registryPath?: string): void;
+/**
+ * List installed plugins.
+ */
+export declare function listPlugins(registryPath?: string): InstalledPlugin[];