@mauribadnights/clooks 0.3.0 → 0.3.2

package/dist/cli.js

@@ -10,6 +10,7 @@ const migrate_js_1 = require("./migrate.js");
 const doctor_js_1 = require("./doctor.js");
 const auth_js_1 = require("./auth.js");
 const plugin_js_1 = require("./plugin.js");
+const sync_js_1 = require("./sync.js");
 const constants_js_1 = require("./constants.js");
 const fs_1 = require("fs");
 const path_1 = require("path");
@@ -17,7 +18,7 @@ const program = new commander_1.Command();
 program
     .name('clooks')
     .description('Persistent hook runtime for Claude Code')
-    .version('0.3.0');
+    .version('0.3.2');
 // --- start ---
 program
     .command('start')
@@ -40,6 +41,11 @@ program
         (0, server_js_1.startDaemonBackground)({ noWatch });
         // Give it a moment to start
         await new Promise((r) => setTimeout(r, 500));
+        // Sync settings.json with manifest
+        const syncAdded = (0, sync_js_1.syncSettings)();
+        if (syncAdded.length > 0) {
+            console.log(`Synced HTTP hooks for: ${syncAdded.join(', ')}`);
+        }
         if ((0, server_js_1.isDaemonRunning)()) {
             const pid = (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim();
             console.log(`Daemon started (pid ${pid}), listening on 127.0.0.1:${constants_js_1.DEFAULT_PORT}`);
@@ -120,6 +126,9 @@ program
     .action(() => {
     const metrics = new metrics_js_1.MetricsCollector();
     console.log(metrics.formatStatsTable());
+    console.log('');
+    console.log('Per Handler:');
+    console.log(metrics.formatHandlerStatsTable());
     // Append cost summary if LLM data exists
     const costStats = metrics.getCostStats();
     if (costStats.totalCost > 0) {
@@ -184,13 +193,31 @@ program
     if (errors > 0)
         process.exit(1);
 });
+// --- sync ---
+program
+    .command('sync')
+    .description('Sync settings.json with manifest (add missing HTTP hook entries)')
+    .action(() => {
+    const added = (0, sync_js_1.syncSettings)();
+    if (added.length === 0) {
+        console.log('Settings already in sync.');
+    }
+    else {
+        console.log(`Added HTTP hooks for: ${added.join(', ')}`);
+        const settingsPath = (0, migrate_js_1.getSettingsPath)();
+        if (settingsPath) {
+            console.log(`Settings updated: ${settingsPath}`);
+        }
+    }
+});
 // --- ensure-running ---
 program
     .command('ensure-running')
     .description('Start daemon if not already running (used by SessionStart hook)')
     .action(async () => {
     if ((0, server_js_1.isDaemonRunning)()) {
-        // Already running — exit silently and fast
+        // Already running — sync settings silently and exit fast
+        (0, sync_js_1.syncSettings)();
         process.exit(0);
     }
     // Ensure config dir exists
@@ -203,6 +230,8 @@ program
         (0, manifest_js_1.createDefaultManifest)();
     }
     (0, server_js_1.startDaemonBackground)();
+    // Sync settings silently after starting
+    (0, sync_js_1.syncSettings)();
     process.exit(0);
 });
 // --- init ---
@@ -291,6 +320,11 @@ program
             ? Object.values(installed.manifest.handlers).reduce((sum, arr) => sum + (arr?.length ?? 0), 0)
             : 0;
         console.log(`Installed plugin ${plugin.name} v${plugin.version} (${handlerCount} handlers)`);
+        // Sync settings.json to add HTTP hooks for any new events
+        const syncAdded = (0, sync_js_1.syncSettings)();
+        if (syncAdded.length > 0) {
+            console.log(`Synced HTTP hooks for: ${syncAdded.join(', ')}`);
+        }
     }
     catch (err) {
         console.error('Plugin install failed:', err instanceof Error ? err.message : err);

package/dist/index.d.ts

@@ -11,6 +11,8 @@ export { DenyCache } from './shortcircuit.js';
 export { RateLimiter } from './ratelimit.js';
 export { startWatcher, stopWatcher } from './watcher.js';
 export { generateAuthToken, validateAuth, rotateToken } from './auth.js';
+export { syncSettings } from './sync.js';
+export type { SyncOptions } from './sync.js';
 export type { RotateTokenOptions } from './auth.js';
 export { evaluateFilter } from './filter.js';
 export { executeLLMHandler, executeLLMHandlersBatched, calculateCost, resetClient } from './llm.js';

package/dist/index.js

@@ -1,8 +1,8 @@
 "use strict";
 // clooks — public API exports
 Object.defineProperty(exports, "__esModule", { value: true });
-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;
+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.syncSettings = 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 = exports.PLUGINS_DIR = 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; } });
@@ -47,6 +47,8 @@ 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 sync_js_1 = require("./sync.js");
+Object.defineProperty(exports, "syncSettings", { enumerable: true, get: function () { return sync_js_1.syncSettings; } });
 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");

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,6 +2,7 @@
 // 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");
@@ -26,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.
  *
@@ -61,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.
@@ -83,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

package/dist/ratelimit.d.ts

@@ -5,8 +5,13 @@ export declare class RateLimiter {
     constructor(maxAttempts?: number, windowMs?: number);
     /** Check if source is rate-limited. Returns true if allowed. */
     check(source: string): boolean;
-    /** Record an attempt from source. */
-    record(source: string): void;
+    /** Record an auth failure from source. */
+    recordFailure(source: string): void;
+    /**
+     * How many seconds until the rate limit resets for a given source.
+     * Returns 0 if the source is not rate-limited.
+     */
+    retryAfter(source: string): number;
     /** Clean up old entries. */
     cleanup(): void;
 }

package/dist/ratelimit.js

@@ -1,9 +1,13 @@
 "use strict";
 // clooks rate limiting — protect against auth brute-force
+//
+// IMPORTANT: This rate limiter should ONLY be used when auth is configured.
+// It tracks auth failures per source IP. When the limit is exceeded, requests
+// from that source are blocked with 429 until the window expires.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.RateLimiter = void 0;
 class RateLimiter {
-    attempts = new Map(); // source → timestamps
+    attempts = new Map(); // source → auth failure timestamps
     maxAttempts;
     windowMs;
     constructor(maxAttempts = 10, windowMs = 60_000) {
@@ -16,17 +20,34 @@ class RateLimiter {
         const timestamps = this.attempts.get(source);
         if (!timestamps)
             return true;
-        // Count recent attempts within window
+        // Count recent auth failures within window
         const recent = timestamps.filter(t => now - t <= this.windowMs);
         return recent.length < this.maxAttempts;
     }
-    /** Record an attempt from source. */
-    record(source) {
+    /** Record an auth failure from source. */
+    recordFailure(source) {
         const now = Date.now();
         const timestamps = this.attempts.get(source) ?? [];
         timestamps.push(now);
         this.attempts.set(source, timestamps);
     }
+    /**
+     * How many seconds until the rate limit resets for a given source.
+     * Returns 0 if the source is not rate-limited.
+     */
+    retryAfter(source) {
+        const now = Date.now();
+        const timestamps = this.attempts.get(source);
+        if (!timestamps)
+            return 0;
+        const recent = timestamps.filter(t => now - t <= this.windowMs);
+        if (recent.length < this.maxAttempts)
+            return 0;
+        // The oldest recent attempt determines when the window expires
+        const oldest = Math.min(...recent);
+        const expiresAt = oldest + this.windowMs;
+        return Math.ceil((expiresAt - now) / 1000);
+    }
     /** Clean up old entries. */
     cleanup() {
         const now = Date.now();

package/dist/server.js

@@ -131,17 +131,24 @@ function createServer(manifest, metrics) {
             });
             return;
         }
-        // Auth check for all POST requests
+        // Auth check for all POST requests — only when auth token is configured
         if (method === 'POST' && authToken) {
             const source = req.socket.remoteAddress ?? 'unknown';
-            // Rate limiting check
+            // Rate limiting: check if this source has too many auth failures
             if (!rateLimiter.check(source)) {
-                sendJson(res, 429, { error: 'Too many requests' });
+                const retryAfter = rateLimiter.retryAfter(source);
+                const body = JSON.stringify({ error: 'Too many auth failures' });
+                res.writeHead(429, {
+                    'Content-Type': 'application/json',
+                    'Content-Length': Buffer.byteLength(body),
+                    'Retry-After': String(retryAfter),
+                });
+                res.end(body);
                 return;
             }
             const authHeader = req.headers['authorization'];
             if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
-                rateLimiter.record(source);
+                rateLimiter.recordFailure(source);
                 log(`Auth failure from ${source}`);
                 sendJson(res, 401, { error: 'Unauthorized' });
                 return;

package/dist/sync.d.ts

@@ -0,0 +1,13 @@
+import type { Manifest } from './types.js';
+export interface SyncOptions {
+    settingsPath?: string;
+    manifestPath?: string;
+    /** Override composite manifest loading — used for testing */
+    manifest?: Manifest;
+}
+/**
+ * Ensure settings.json has HTTP hooks for every event that has handlers in the manifest.
+ * Adds missing HTTP hook entries without touching existing ones.
+ * Returns list of events that were added.
+ */
+export declare function syncSettings(options?: SyncOptions): string[];

package/dist/sync.js

@@ -0,0 +1,153 @@
+"use strict";
+// clooks sync — ensure settings.json has HTTP hooks for every event with handlers
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncSettings = syncSettings;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const manifest_js_1 = require("./manifest.js");
+const constants_js_1 = require("./constants.js");
+/**
+ * Find the Claude Code settings.json path.
+ * Checks settings.local.json first, then settings.json.
+ */
+function findSettingsPath() {
+    const home = (0, os_1.homedir)();
+    const candidates = [
+        (0, path_1.join)(home, '.claude', 'settings.local.json'),
+        (0, path_1.join)(home, '.claude', 'settings.json'),
+    ];
+    for (const candidate of candidates) {
+        if ((0, fs_1.existsSync)(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+/**
+ * Ensure settings.json has HTTP hooks for every event that has handlers in the manifest.
+ * Adds missing HTTP hook entries without touching existing ones.
+ * Returns list of events that were added.
+ */
+function syncSettings(options) {
+    // Determine settings path
+    const settingsPath = options?.settingsPath ?? findSettingsPath();
+    if (!settingsPath || !(0, fs_1.existsSync)(settingsPath)) {
+        return []; // No settings file found — nothing to sync
+    }
+    // Load manifest
+    let manifest;
+    if (options?.manifest) {
+        manifest = options.manifest;
+    }
+    else {
+        manifest = (0, manifest_js_1.loadCompositeManifest)();
+    }
+    const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
+    const authToken = manifest.settings?.authToken;
+    // Find all events that have at least one handler
+    const eventsWithHandlers = new Set();
+    for (const [event, handlers] of Object.entries(manifest.handlers)) {
+        if (handlers && handlers.length > 0) {
+            eventsWithHandlers.add(event);
+        }
+    }
+    // Read settings.json
+    let raw;
+    try {
+        raw = (0, fs_1.readFileSync)(settingsPath, 'utf-8');
+    }
+    catch {
+        return [];
+    }
+    let settings;
+    try {
+        settings = JSON.parse(raw);
+    }
+    catch {
+        return [];
+    }
+    if (!settings.hooks) {
+        settings.hooks = {};
+    }
+    const added = [];
+    // Check each event with handlers
+    for (const event of eventsWithHandlers) {
+        const hookUrl = `http://localhost:${port}/hooks/${event}`;
+        // Check if settings.json already has an HTTP hook pointing to this URL
+        const ruleGroups = settings.hooks[event] ?? [];
+        let hasHttpHook = false;
+        for (const rule of ruleGroups) {
+            if (!Array.isArray(rule.hooks))
+                continue;
+            for (const hook of rule.hooks) {
+                if (hook.type === 'http' && hook.url === hookUrl) {
+                    hasHttpHook = true;
+                    break;
+                }
+            }
+            if (hasHttpHook)
+                break;
+        }
+        if (!hasHttpHook) {
+            // Add HTTP hook in a new rule group
+            const httpHook = {
+                type: 'http',
+                url: hookUrl,
+            };
+            if (authToken) {
+                httpHook.headers = { Authorization: `Bearer ${authToken}` };
+            }
+            if (!settings.hooks[event]) {
+                settings.hooks[event] = [];
+            }
+            // Check if there's already a rule group without a matcher we can append to
+            const existingRules = settings.hooks[event];
+            const unmatchedRule = existingRules.find(r => !r.matcher);
+            if (unmatchedRule) {
+                unmatchedRule.hooks.push(httpHook);
+            }
+            else {
+                existingRules.push({ hooks: [httpHook] });
+            }
+            added.push(event);
+        }
+    }
+    // Ensure SessionStart always has the `clooks ensure-running` command hook
+    if (!settings.hooks['SessionStart']) {
+        settings.hooks['SessionStart'] = [];
+    }
+    const sessionRules = settings.hooks['SessionStart'];
+    let hasEnsureRunning = false;
+    for (const rule of sessionRules) {
+        if (!Array.isArray(rule.hooks))
+            continue;
+        for (const hook of rule.hooks) {
+            if (hook.type === 'command' && hook.command === 'clooks ensure-running') {
+                hasEnsureRunning = true;
+                break;
+            }
+        }
+        if (hasEnsureRunning)
+            break;
+    }
+    if (!hasEnsureRunning) {
+        const unmatchedRule = sessionRules.find(r => !r.matcher);
+        const ensureHook = { type: 'command', command: 'clooks ensure-running' };
+        if (unmatchedRule) {
+            // Prepend ensure-running before HTTP hooks
+            unmatchedRule.hooks.unshift(ensureHook);
+        }
+        else {
+            sessionRules.unshift({ hooks: [ensureHook] });
+        }
+        if (!added.includes('SessionStart')) {
+            added.push('SessionStart');
+        }
+    }
+    // Write settings.json back only if changes were made
+    if (added.length > 0) {
+        (0, fs_1.writeFileSync)(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+    }
+    return added;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mauribadnights/clooks",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
   "bin": {
     "clooks": "./dist/cli.js"