@mauribadnights/clooks 0.2.0 → 0.2.2

package/README.md

@@ -97,6 +97,7 @@ settings:
 **Handler types:**
 - `script` -- runs a shell command, pipes hook JSON to stdin, reads JSON from stdout.
 - `inline` -- imports a JS module and calls its default export. Faster; no subprocess overhead.
+- `llm` -- calls Anthropic Messages API. Supports prompt templates, batching, and cost tracking. *(v0.2+)*
 
 ## Observability
 
@@ -171,11 +172,54 @@ handlers:
       batchGroup: analysis    # batched with code-review into one API call
 ```
 
-Requires `@anthropic-ai/sdk` as a peer dependency and `ANTHROPIC_API_KEY` env var.
+**Setup:**
+
+```bash
+npm install @anthropic-ai/sdk    # peer dependency, only needed for llm handlers
+export ANTHROPIC_API_KEY=sk-...  # or set in manifest: settings.anthropicApiKey
+```
+
+**Prompt template variables:**
+
+| Variable | Source | Description |
+|----------|--------|-------------|
+| `$TRANSCRIPT` | Pre-fetched transcript file | Last 50KB of session transcript |
+| `$GIT_STATUS` | `git status --porcelain` | Current working tree status |
+| `$GIT_DIFF` | `git diff --stat` | Changed files summary (max 20KB) |
+| `$ARGUMENTS` | `hook_input.tool_input` | JSON-stringified tool arguments |
+| `$TOOL_NAME` | `hook_input.tool_name` | Name of the tool being called |
+| `$PROMPT` | `hook_input.prompt` | User's prompt (UserPromptSubmit only) |
+| `$CWD` | `hook_input.cwd` | Current working directory |
+
+**LLM handler options:**
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `model` | string | required | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6` |
+| `prompt` | string | required | Prompt template with `$VARIABLE` interpolation |
+| `batchGroup` | string | optional | Group ID -- handlers with same group make one API call |
+| `maxTokens` | number | `1024` | Maximum output tokens |
+| `temperature` | number | `1.0` | Sampling temperature |
+| `filter` | string | optional | Keyword filter (see Filtering) |
+| `timeout` | number | `30000` | Timeout in milliseconds |
+
+**How batching works:**
+
+When multiple LLM handlers share a `batchGroup` on the same event, clooks combines their prompts into a single multi-task API call and splits the structured response back to each handler. This means 3 Haiku calls become 1, saving ~2/3 of the input token cost and eliminating 2 round-trips.
 
 ### Intelligent Filtering
 
-Skip handlers based on keywords. Supports OR (`|`) and NOT (`!`) operators. Matching is case-insensitive against the full hook input JSON.
+Skip handlers based on keywords. The `filter` field works on **all handler types** -- script, inline, and llm.
+
+**Filter syntax:**
+
+```
+filter: "word1|word2"      # run if input contains word1 OR word2
+filter: "!word"            # run unless input contains word
+filter: "word1|!word2"     # run if word1 present AND word2 absent
+```
+
+Matching is case-insensitive against the full JSON-serialized hook input.
 
 ```yaml
 handlers:
@@ -204,9 +248,19 @@ handlers:
       prompt: "Summarize this session:\n$TRANSCRIPT\n\nGit changes:\n$GIT_DIFF"
 ```
 
+**Available prefetch keys:**
+
+| Key | Source | Max size | Description |
+|-----|--------|----------|-------------|
+| `transcript` | `transcript_path` file | 50KB (tail) | Session conversation history |
+| `git_status` | `git status --porcelain` | unbounded | Working tree status |
+| `git_diff` | `git diff --stat` | 20KB | Changed files summary |
+
+Pre-fetched data is cached for the duration of a single event dispatch. Errors on individual keys are silently caught -- a failed `git_status` won't prevent `transcript` from loading.
+
 ### Cost Tracking
 
-Track LLM token usage and costs per handler and model. Pricing is built-in for Haiku 4.5, Sonnet 4.6, and Opus 4.6.
+Track LLM token usage and costs per handler and model.
 
 ```
 $ clooks costs
@@ -222,7 +276,10 @@ LLM Cost Summary
     security-check         $0.0053 (12 calls, avg 178 tokens)
 ```
 
-Cost data also appears in `clooks stats` when LLM handlers have been used.
+- Costs are persisted to `~/.clooks/costs.jsonl`
+- Built-in pricing (per million tokens): Haiku ($0.80 / $4.00), Sonnet ($3.00 / $15.00), Opus ($15.00 / $75.00)
+- Batching savings are estimated based on shared input tokens
+- Cost data also appears in `clooks stats` when LLM handlers have been used
 
 ## Roadmap
 

package/dist/auth.d.ts

@@ -0,0 +1,4 @@
+/** Generate a random auth token (32 hex chars). */
+export declare function generateAuthToken(): string;
+/** Validate an auth token from request headers. */
+export declare function validateAuth(authHeader: string | undefined, expectedToken: string): boolean;

package/dist/auth.js

@@ -0,0 +1,27 @@
+"use strict";
+// clooks auth — token-based request authentication
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAuthToken = generateAuthToken;
+exports.validateAuth = validateAuth;
+const crypto_1 = require("crypto");
+/** Generate a random auth token (32 hex chars). */
+function generateAuthToken() {
+    return (0, crypto_1.randomBytes)(16).toString('hex');
+}
+/** Validate an auth token from request headers. */
+function validateAuth(authHeader, expectedToken) {
+    if (!expectedToken)
+        return true; // No token configured = no auth required
+    if (!authHeader)
+        return false;
+    // Support "Bearer <token>" format
+    const token = authHeader.startsWith('Bearer ')
+        ? authHeader.slice(7)
+        : authHeader;
+    // Constant-time comparison to prevent timing attacks
+    if (token.length !== expectedToken.length)
+        return false;
+    const bufA = Buffer.from(token);
+    const bufB = Buffer.from(expectedToken);
+    return (0, crypto_1.timingSafeEqual)(bufA, bufB);
+}

package/dist/cli.js

@@ -8,19 +8,22 @@ const metrics_js_1 = require("./metrics.js");
 const server_js_1 = require("./server.js");
 const migrate_js_1 = require("./migrate.js");
 const doctor_js_1 = require("./doctor.js");
+const auth_js_1 = require("./auth.js");
 const constants_js_1 = require("./constants.js");
 const fs_1 = require("fs");
 const program = new commander_1.Command();
 program
     .name('clooks')
     .description('Persistent hook runtime for Claude Code')
-    .version('0.2.0');
+    .version('0.2.2');
 // --- start ---
 program
     .command('start')
     .description('Start the clooks daemon')
     .option('-f, --foreground', 'Run in foreground (default: background/detached)')
+    .option('--no-watch', 'Disable file watching for manifest changes')
     .action(async (opts) => {
+    const noWatch = opts.watch === false;
     if (!opts.foreground) {
         // Background mode: check if already running, then spawn detached
         if ((0, server_js_1.isDaemonRunning)()) {
@@ -32,7 +35,7 @@ program
             (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
         }
         console.log('Starting clooks daemon in background...');
-        (0, server_js_1.startDaemonBackground)();
+        (0, server_js_1.startDaemonBackground)({ noWatch });
         // Give it a moment to start
         await new Promise((r) => setTimeout(r, 500));
         if ((0, server_js_1.isDaemonRunning)()) {
@@ -51,7 +54,7 @@ program
         const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
         const handlerCount = Object.values(manifest.handlers)
             .reduce((sum, arr) => sum + (arr?.length ?? 0), 0);
-        await (0, server_js_1.startDaemon)(manifest, metrics);
+        await (0, server_js_1.startDaemon)(manifest, metrics, { noWatch });
         console.log(`clooks daemon running on 127.0.0.1:${port} (${handlerCount} handler${handlerCount !== 1 ? 's' : ''})`);
     }
     catch (err) {
@@ -206,8 +209,10 @@ program
     if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
         (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
     }
-    const path = (0, manifest_js_1.createDefaultManifest)();
+    const token = (0, auth_js_1.generateAuthToken)();
+    const path = (0, manifest_js_1.createDefaultManifest)(token);
     console.log(`Created: ${path}`);
+    console.log(`Auth token: ${token}`);
     console.log('Edit this file to configure your hook handlers.');
 });
 program.parse();

package/dist/doctor.js

@@ -29,6 +29,8 @@ async function runDoctor() {
     results.push(checkSettingsHooks());
     // 7. No stale PID file
     results.push(checkStalePid());
+    // 8. Auth token consistency (if configured)
+    results.push(checkAuthToken());
     return results;
 }
 function checkConfigDir() {
@@ -166,3 +168,55 @@ function checkStalePid() {
         return { check: 'Stale PID', status: 'error', message: `Stale PID file: process ${pid} is dead. Remove ${constants_js_1.PID_FILE} or run "clooks start".` };
     }
 }
+function checkAuthToken() {
+    try {
+        const manifest = (0, manifest_js_1.loadManifest)();
+        const authToken = manifest.settings?.authToken;
+        if (!authToken) {
+            return { check: 'Auth token', status: 'ok', message: 'No auth token configured (open access)' };
+        }
+        // Check that settings.json hooks include matching Authorization header
+        const candidates = [
+            (0, path_1.join)((0, os_1.homedir)(), '.claude', 'settings.local.json'),
+            (0, path_1.join)((0, os_1.homedir)(), '.claude', 'settings.json'),
+        ];
+        for (const path of candidates) {
+            if (!(0, fs_1.existsSync)(path))
+                continue;
+            try {
+                const raw = (0, fs_1.readFileSync)(path, 'utf-8');
+                const settings = JSON.parse(raw);
+                if (!settings.hooks)
+                    continue;
+                const expectedHeader = `Bearer ${authToken}`;
+                const httpHooks = [];
+                for (const ruleGroups of Object.values(settings.hooks)) {
+                    for (const rule of ruleGroups) {
+                        if (!Array.isArray(rule.hooks))
+                            continue;
+                        for (const hook of rule.hooks) {
+                            if (hook.type === 'http' && hook.url?.includes(`localhost:${constants_js_1.DEFAULT_PORT}`)) {
+                                httpHooks.push(hook);
+                            }
+                        }
+                    }
+                }
+                if (httpHooks.length === 0) {
+                    return { check: 'Auth token', status: 'warn', message: 'Auth token set but no HTTP hooks found in settings.json' };
+                }
+                const missingAuth = httpHooks.filter(h => h.headers?.['Authorization'] !== expectedHeader);
+                if (missingAuth.length > 0) {
+                    return { check: 'Auth token', status: 'error', message: `Auth token set but ${missingAuth.length} HTTP hook(s) missing matching Authorization header. Run "clooks migrate".` };
+                }
+                return { check: 'Auth token', status: 'ok', message: 'Auth token matches settings.json hook headers' };
+            }
+            catch {
+                continue;
+            }
+        }
+        return { check: 'Auth token', status: 'warn', message: 'Auth token set but could not verify settings.json headers' };
+    }
+    catch {
+        return { check: 'Auth token', status: 'ok', message: 'Could not load manifest for auth check' };
+    }
+}

package/dist/handlers.d.ts

@@ -3,6 +3,11 @@ 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>;
+/**
+ * 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.

package/dist/handlers.js

@@ -3,6 +3,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resetHandlerStates = resetHandlerStates;
 exports.getHandlerStates = getHandlerStates;
+exports.resetSessionIsolatedHandlers = resetSessionIsolatedHandlers;
 exports.executeHandlers = executeHandlers;
 exports.executeScriptHandler = executeScriptHandler;
 exports.executeInlineHandler = executeInlineHandler;
@@ -30,6 +31,23 @@ function resetHandlerStates() {
 function getHandlerStates() {
     return new Map(handlerStates);
 }
+/**
+ * Reset handler states for handlers that have sessionIsolation: true.
+ * Called on SessionStart events.
+ */
+function resetSessionIsolatedHandlers(handlers) {
+    for (const handler of handlers) {
+        if (handler.sessionIsolation) {
+            const state = handlerStates.get(handler.id);
+            if (state) {
+                state.consecutiveFailures = 0;
+                state.disabled = false;
+                state.totalFires = 0;
+                state.totalErrors = 0;
+            }
+        }
+    }
+}
 /**
  * Execute all handlers for an event in parallel.
  * Returns merged results array.

package/dist/index.d.ts

@@ -4,7 +4,9 @@ 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 } from './handlers.js';
+export { executeHandlers, resetSessionIsolatedHandlers } from './handlers.js';
+export { startWatcher, stopWatcher } from './watcher.js';
+export { generateAuthToken, validateAuth } from './auth.js';
 export { evaluateFilter } from './filter.js';
 export { executeLLMHandler, executeLLMHandlersBatched, calculateCost, resetClient } from './llm.js';
 export { prefetchContext, renderPromptTemplate } from './prefetch.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 "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.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.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;
 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; } });
@@ -21,6 +21,13 @@ var doctor_js_1 = require("./doctor.js");
 Object.defineProperty(exports, "runDoctor", { enumerable: true, get: function () { return doctor_js_1.runDoctor; } });
 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; } });
+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; } });
 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/manifest.d.ts

@@ -12,4 +12,4 @@ export declare function validateManifest(manifest: Manifest): void;
 /**
  * Create a default commented example manifest.yaml in CONFIG_DIR.
  */
-export declare function createDefaultManifest(): string;
+export declare function createDefaultManifest(authToken?: string): string;

package/dist/manifest.js

@@ -102,10 +102,17 @@ function validateManifest(manifest) {
 /**
  * Create a default commented example manifest.yaml in CONFIG_DIR.
  */
-function createDefaultManifest() {
+function createDefaultManifest(authToken) {
     if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
         (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
     }
+    const settings = {
+        port: 7890,
+        logLevel: 'info',
+    };
+    if (authToken) {
+        settings.authToken = authToken;
+    }
     const example = {
         handlers: {
             PreToolUse: [
@@ -118,10 +125,7 @@ function createDefaultManifest() {
                 },
             ],
         },
-        settings: {
-            port: 7890,
-            logLevel: 'info',
-        },
+        settings,
     };
     const yamlStr = '# clooks manifest — define your hook handlers here\n' +
         '# Docs: https://github.com/mauribadnights/clooks\n' +

package/dist/metrics.d.ts

@@ -8,8 +8,15 @@ interface AggregatedStats {
     maxDuration: number;
 }
 export declare class MetricsCollector {
+    private static readonly MAX_ENTRIES;
     private entries;
-    /** Record a metric entry in memory and append to disk. */
+    private ringIndex;
+    private totalRecorded;
+    private static readonly METRICS_MAX_BYTES;
+    private static readonly COSTS_MAX_BYTES;
+    /** Rotate a log file if it exceeds maxBytes. Keeps one backup (.1). */
+    private rotateIfNeeded;
+    /** Record a metric entry in memory (ring buffer) and append to disk. */
     record(entry: MetricEntry): void;
     /** Get aggregated stats per event type. */
     getStats(): AggregatedStats[];

package/dist/metrics.js

@@ -6,15 +6,43 @@ const fs_1 = require("fs");
 const path_1 = require("path");
 const constants_js_1 = require("./constants.js");
 class MetricsCollector {
+    static MAX_ENTRIES = 1000;
     entries = [];
-    /** Record a metric entry in memory and append to disk. */
+    ringIndex = 0;
+    totalRecorded = 0;
+    static METRICS_MAX_BYTES = 5 * 1024 * 1024; // 5MB
+    static COSTS_MAX_BYTES = 1 * 1024 * 1024; // 1MB
+    /** Rotate a log file if it exceeds maxBytes. Keeps one backup (.1). */
+    rotateIfNeeded(filePath, maxBytes) {
+        try {
+            if (!(0, fs_1.existsSync)(filePath))
+                return;
+            const stat = (0, fs_1.statSync)(filePath);
+            if (stat.size >= maxBytes) {
+                (0, fs_1.renameSync)(filePath, filePath + '.1');
+            }
+        }
+        catch {
+            // Non-critical — rotation failure is not fatal
+        }
+    }
+    /** Record a metric entry in memory (ring buffer) and append to disk. */
     record(entry) {
-        this.entries.push(entry);
+        // Ring buffer: overwrite oldest when full
+        if (this.entries.length < MetricsCollector.MAX_ENTRIES) {
+            this.entries.push(entry);
+        }
+        else {
+            this.entries[this.ringIndex] = entry;
+            this.ringIndex = (this.ringIndex + 1) % MetricsCollector.MAX_ENTRIES;
+        }
+        this.totalRecorded++;
         try {
             const dir = (0, path_1.dirname)(constants_js_1.METRICS_FILE);
             if (!(0, fs_1.existsSync)(dir)) {
                 (0, fs_1.mkdirSync)(dir, { recursive: true });
             }
+            this.rotateIfNeeded(constants_js_1.METRICS_FILE, MetricsCollector.METRICS_MAX_BYTES);
             (0, fs_1.appendFileSync)(constants_js_1.METRICS_FILE, JSON.stringify(entry) + '\n', 'utf-8');
         }
         catch {
@@ -46,10 +74,7 @@ class MetricsCollector {
     }
     /** Get stats for a specific session. */
     getSessionStats(sessionId) {
-        const all = this.loadAll().filter((e) => {
-            // MetricEntry doesn't have session_id, but we stored it in the entry if available
-            return e.session_id === sessionId;
-        });
+        const all = this.loadAll().filter((e) => e.session_id === sessionId);
         const byEvent = new Map();
         for (const entry of all) {
             const existing = byEvent.get(entry.event) ?? [];
@@ -108,6 +133,7 @@ class MetricsCollector {
             if (!(0, fs_1.existsSync)(dir)) {
                 (0, fs_1.mkdirSync)(dir, { recursive: true });
             }
+            this.rotateIfNeeded(constants_js_1.COSTS_FILE, MetricsCollector.COSTS_MAX_BYTES);
             (0, fs_1.appendFileSync)(constants_js_1.COSTS_FILE, JSON.stringify(entry) + '\n', 'utf-8');
         }
         catch {

package/dist/migrate.js

@@ -129,10 +129,14 @@ function migrate(options) {
         }
         // Add HTTP hook
         if (hadHandlers > 0) {
-            hookEntries.push({
+            const httpHook = {
                 type: 'http',
                 url: `http://localhost:${constants_js_1.DEFAULT_PORT}/hooks/${eventName}`,
-            });
+            };
+            if (manifest.settings?.authToken) {
+                httpHook.headers = { Authorization: `Bearer ${manifest.settings.authToken}` };
+            }
+            hookEntries.push(httpHook);
         }
         if (hookEntries.length > 0) {
             // Wrap in a single rule group (no matcher — clooks handles dispatch)

package/dist/server.d.ts

@@ -1,4 +1,5 @@
 import { type Server } from 'http';
+import type { FSWatcher } from 'fs';
 import { MetricsCollector } from './metrics.js';
 import type { Manifest } from './types.js';
 export interface ServerContext {
@@ -6,6 +7,7 @@ export interface ServerContext {
     metrics: MetricsCollector;
     startTime: number;
     manifest: Manifest;
+    watcher?: FSWatcher;
 }
 /**
  * Create the HTTP server for hook handling.
@@ -14,7 +16,9 @@ export declare function createServer(manifest: Manifest, metrics: MetricsCollect
 /**
  * Start the daemon: bind the server and write PID file.
  */
-export declare function startDaemon(manifest: Manifest, metrics: MetricsCollector): Promise<ServerContext>;
+export declare function startDaemon(manifest: Manifest, metrics: MetricsCollector, options?: {
+    noWatch?: boolean;
+}): Promise<ServerContext>;
 /**
  * Stop a running daemon by reading PID file and sending SIGTERM.
  */
@@ -26,4 +30,6 @@ export declare function isDaemonRunning(): boolean;
 /**
  * Start daemon as a detached background process.
  */
-export declare function startDaemonBackground(): void;
+export declare function startDaemonBackground(options?: {
+    noWatch?: boolean;
+}): void;

package/dist/server.js

@@ -11,7 +11,10 @@ const fs_1 = require("fs");
 const child_process_1 = require("child_process");
 const handlers_js_1 = require("./handlers.js");
 const prefetch_js_1 = require("./prefetch.js");
+const watcher_js_1 = require("./watcher.js");
+const auth_js_1 = require("./auth.js");
 const constants_js_1 = require("./constants.js");
+const manifest_js_1 = require("./manifest.js");
 function log(msg) {
     const line = `[${new Date().toISOString()}] ${msg}\n`;
     try {
@@ -79,21 +82,32 @@ function sendJson(res, status, data) {
  */
 function createServer(manifest, metrics) {
     const startTime = Date.now();
+    const ctx = { server: null, metrics, startTime, manifest };
+    const authToken = manifest.settings?.authToken ?? '';
     const server = (0, http_1.createServer)(async (req, res) => {
         const url = req.url ?? '/';
         const method = req.method ?? 'GET';
-        // Health check endpoint
+        // Health check endpoint — no auth required for monitoring
         if (method === 'GET' && url === '/health') {
-            const handlerCount = Object.values(manifest.handlers)
+            const handlerCount = Object.values(ctx.manifest.handlers)
                 .reduce((sum, arr) => sum + (arr?.length ?? 0), 0);
             sendJson(res, 200, {
                 status: 'ok',
                 uptime: Math.floor((Date.now() - startTime) / 1000),
                 handlers_loaded: handlerCount,
-                port: manifest.settings?.port ?? constants_js_1.DEFAULT_PORT,
+                port: ctx.manifest.settings?.port ?? constants_js_1.DEFAULT_PORT,
             });
             return;
         }
+        // Auth check for all POST requests
+        if (method === 'POST' && authToken) {
+            const authHeader = req.headers['authorization'];
+            if (!(0, auth_js_1.validateAuth)(authHeader, authToken)) {
+                log(`Auth failure from ${req.socket.remoteAddress}`);
+                sendJson(res, 401, { error: 'Unauthorized' });
+                return;
+            }
+        }
         // Hook endpoint: POST /hooks/:eventName
         const hookMatch = url.match(/^\/hooks\/([A-Za-z]+)$/);
         if (method === 'POST' && hookMatch) {
@@ -103,7 +117,14 @@ function createServer(manifest, metrics) {
                 return;
             }
             const event = eventName;
-            const handlers = manifest.handlers[event] ?? [];
+            // On SessionStart, reset session-isolated handlers across ALL events
+            if (event === 'SessionStart') {
+                const allHandlers = Object.values(ctx.manifest.handlers)
+                    .flat()
+                    .filter((h) => h != null);
+                (0, handlers_js_1.resetSessionIsolatedHandlers)(allHandlers);
+            }
+            const handlers = ctx.manifest.handlers[event] ?? [];
             if (handlers.length === 0) {
                 sendJson(res, 200, {});
                 return;
@@ -122,8 +143,8 @@ function createServer(manifest, metrics) {
             try {
                 // Pre-fetch shared context if configured
                 let context;
-                if (manifest.prefetch && manifest.prefetch.length > 0) {
-                    context = await (0, prefetch_js_1.prefetchContext)(manifest.prefetch, input);
+                if (ctx.manifest.prefetch && ctx.manifest.prefetch.length > 0) {
+                    context = await (0, prefetch_js_1.prefetchContext)(ctx.manifest.prefetch, input);
                 }
                 const results = await (0, handlers_js_1.executeHandlers)(event, input, handlers, context);
                 // Record metrics and costs
@@ -138,6 +159,7 @@ function createServer(manifest, metrics) {
                         filtered: result.filtered,
                         usage: result.usage,
                         cost_usd: result.cost_usd,
+                        session_id: input.session_id,
                     });
                     // Track cost for LLM handlers
                     if (result.usage && result.cost_usd !== undefined && result.cost_usd > 0) {
@@ -170,12 +192,13 @@ function createServer(manifest, metrics) {
         // 404 for everything else
         sendJson(res, 404, { error: 'Not found' });
     });
-    return { server, metrics, startTime, manifest };
+    ctx.server = server;
+    return ctx;
 }
 /**
  * Start the daemon: bind the server and write PID file.
  */
-function startDaemon(manifest, metrics) {
+function startDaemon(manifest, metrics, options) {
     return new Promise((resolve, reject) => {
         const ctx = createServer(manifest, metrics);
         const port = manifest.settings?.port ?? constants_js_1.DEFAULT_PORT;
@@ -195,12 +218,28 @@ function startDaemon(manifest, metrics) {
                 (0, fs_1.mkdirSync)(constants_js_1.CONFIG_DIR, { recursive: true });
             }
             (0, fs_1.writeFileSync)(constants_js_1.PID_FILE, String(process.pid), 'utf-8');
+            // Start file watcher unless disabled
+            if (!options?.noWatch) {
+                ctx.watcher = (0, watcher_js_1.startWatcher)(constants_js_1.MANIFEST_PATH, () => {
+                    try {
+                        const newManifest = (0, manifest_js_1.loadManifest)();
+                        ctx.manifest = newManifest;
+                        log('Manifest reloaded successfully');
+                    }
+                    catch (err) {
+                        log(`Manifest reload failed (keeping previous config): ${err instanceof Error ? err.message : err}`);
+                    }
+                }, (err) => {
+                    log(`Watcher error: ${err.message}`);
+                }) ?? undefined;
+            }
             log(`Daemon started on 127.0.0.1:${port} (pid ${process.pid})`);
             resolve(ctx);
         });
         // Graceful shutdown
         const shutdown = () => {
             log('Shutting down...');
+            (0, watcher_js_1.stopWatcher)(ctx.watcher ?? null);
             ctx.server.close(() => {
                 try {
                     if ((0, fs_1.existsSync)(constants_js_1.PID_FILE))
@@ -283,8 +322,12 @@ function isDaemonRunning() {
 /**
  * Start daemon as a detached background process.
  */
-function startDaemonBackground() {
-    const child = (0, child_process_1.spawn)(process.execPath, [process.argv[1], 'start', '--foreground'], {
+function startDaemonBackground(options) {
+    const args = [process.argv[1], 'start', '--foreground'];
+    if (options?.noWatch) {
+        args.push('--no-watch');
+    }
+    const child = (0, child_process_1.spawn)(process.execPath, args, {
         detached: true,
         stdio: 'ignore',
     });

package/dist/types.d.ts

@@ -30,6 +30,7 @@ export interface LLMHandlerConfig {
     filter?: string;
     timeout?: number;
     enabled?: boolean;
+    sessionIsolation?: boolean;
 }
 /** Script handler config */
 export interface ScriptHandlerConfig {
@@ -39,6 +40,7 @@ export interface ScriptHandlerConfig {
     filter?: string;
     timeout?: number;
     enabled?: boolean;
+    sessionIsolation?: boolean;
 }
 /** Inline handler config */
 export interface InlineHandlerConfig {
@@ -48,6 +50,7 @@ export interface InlineHandlerConfig {
     filter?: string;
     timeout?: number;
     enabled?: boolean;
+    sessionIsolation?: boolean;
 }
 /** Union of all handler configs */
 export type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfig;
@@ -67,6 +70,7 @@ export interface Manifest {
         port?: number;
         logLevel?: 'debug' | 'info' | 'warn' | 'error';
         anthropicApiKey?: string;
+        authToken?: string;
     };
 }
 /** Token usage from API response */
@@ -95,6 +99,7 @@ export interface MetricEntry {
     filtered?: boolean;
     usage?: TokenUsage;
     cost_usd?: number;
+    session_id?: string;
 }
 /** Extended handler result with cost info */
 export interface HandlerResult {

package/dist/watcher.d.ts

@@ -0,0 +1,18 @@
+import { type FSWatcher } from 'fs';
+type ReloadCallback = () => void;
+type ErrorCallback = (err: Error) => void;
+export interface WatcherOptions {
+    onReload: ReloadCallback;
+    onError?: ErrorCallback;
+}
+/**
+ * Watch manifest.yaml for changes.
+ * Calls onReload when changes detected (debounced).
+ * If the manifest file doesn't exist, watches the config directory for its creation.
+ */
+export declare function startWatcher(manifestPath: string, onReload: ReloadCallback, onError?: ErrorCallback): FSWatcher | null;
+/**
+ * Stop watching for file changes.
+ */
+export declare function stopWatcher(watcher: FSWatcher | null): void;
+export {};

package/dist/watcher.js

@@ -0,0 +1,120 @@
+"use strict";
+// clooks file watcher — watch manifest.yaml for changes and hot-reload
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startWatcher = startWatcher;
+exports.stopWatcher = stopWatcher;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const DEBOUNCE_MS = 500;
+/**
+ * Watch manifest.yaml for changes.
+ * Calls onReload when changes detected (debounced).
+ * If the manifest file doesn't exist, watches the config directory for its creation.
+ */
+function startWatcher(manifestPath, onReload, onError) {
+    let lastChange = 0;
+    // If manifest exists, watch it directly
+    if ((0, fs_1.existsSync)(manifestPath)) {
+        return watchFile(manifestPath, onReload, onError);
+    }
+    // Manifest doesn't exist — watch the config directory for its creation
+    const configDir = (0, path_1.dirname)(manifestPath);
+    if (!(0, fs_1.existsSync)(configDir)) {
+        try {
+            (0, fs_1.mkdirSync)(configDir, { recursive: true });
+        }
+        catch {
+            // Can't create config dir — give up
+            if (onError)
+                onError(new Error(`Cannot create config directory: ${configDir}`));
+            return null;
+        }
+    }
+    const baseName = manifestPath.split('/').pop() ?? manifestPath.split('\\').pop() ?? '';
+    let dirWatcher = null;
+    try {
+        dirWatcher = (0, fs_1.watch)(configDir, (eventType, filename) => {
+            if (filename !== baseName)
+                return;
+            if (!(0, fs_1.existsSync)(manifestPath))
+                return;
+            const now = Date.now();
+            if (now - lastChange < DEBOUNCE_MS)
+                return;
+            lastChange = now;
+            // Manifest appeared — close directory watcher, start file watcher
+            try {
+                dirWatcher?.close();
+            }
+            catch {
+                // ignore
+            }
+            // Switch to watching the file directly
+            const fileWatcher = watchFile(manifestPath, onReload, onError);
+            if (fileWatcher) {
+                // Copy the ref so stopWatcher can close it (caller still holds the dir watcher ref)
+                // We can't replace the caller's reference, but the dir watcher is closed.
+                // The onReload fires so the caller picks up the new manifest.
+            }
+            try {
+                onReload();
+            }
+            catch (err) {
+                if (onError)
+                    onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        dirWatcher.on('error', (err) => {
+            if (onError)
+                onError(err);
+        });
+        return dirWatcher;
+    }
+    catch {
+        if (onError)
+            onError(new Error(`Failed to watch config directory: ${configDir}`));
+        return null;
+    }
+}
+/** Watch an existing file directly. */
+function watchFile(filePath, onReload, onError) {
+    let lastChange = 0;
+    try {
+        const watcher = (0, fs_1.watch)(filePath, (eventType) => {
+            if (eventType !== 'change' && eventType !== 'rename')
+                return;
+            const now = Date.now();
+            if (now - lastChange < DEBOUNCE_MS)
+                return;
+            lastChange = now;
+            try {
+                onReload();
+            }
+            catch (err) {
+                if (onError)
+                    onError(err instanceof Error ? err : new Error(String(err)));
+            }
+        });
+        watcher.on('error', (err) => {
+            if (onError)
+                onError(err);
+        });
+        return watcher;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Stop watching for file changes.
+ */
+function stopWatcher(watcher) {
+    if (watcher) {
+        try {
+            watcher.close();
+        }
+        catch {
+            // Ignore close errors
+        }
+    }
+}

package/package.json

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