@mauribadnights/clooks 0.1.0 → 0.2.2

package/README.md

@@ -1,50 +1,61 @@
 # clooks
 
-Persistent hook runtime for Claude Code — eliminate cold starts, get observability.
+**Persistent hook runtime for Claude Code.** Eliminate cold starts. Get observability.
 
-## The Problem
+[![npm version](https://img.shields.io/npm/v/@mauribadnights/clooks.svg)](https://www.npmjs.com/package/@mauribadnights/clooks)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-Claude Code spawns a fresh process for every hook invocation. Power users with multiple hooks (safety guards, context injectors, custom scripts) accumulate **100+ process spawns per session**. Each Node.js cold start costs 50-100ms. That's 6-11 seconds of pure overhead per session — and you get zero visibility into what your hooks are doing.
+## Performance
 
-## How clooks Fixes It
+| Metric | Without clooks | With clooks | Improvement |
+|--------|---------------|-------------|-------------|
+| Single hook invocation | ~34.6ms | ~0.31ms | **112x faster** |
+| Full session (120 invocations) | ~3,986ms | ~23ms | **99% time saved** |
+| 5 parallel handlers | ~424ms | ~96ms | **4.4x faster** |
 
-One persistent HTTP server handles all your hooks. Claude Code's [built-in HTTP hook support](https://docs.anthropic.com/en/docs/claude-code/hooks) POSTs to `localhost:7890` instead of spawning processes. **One process instead of hundreds.**
+> Benchmarked on Apple Silicon (M-series), Node v24.4.1. Run `npm run bench` to reproduce.
 
-```
-┌─────────────┐     POST /hooks/PreToolUse     ┌──────────────────┐
-│             │ ──────────────────────────────► │                  │
-│ Claude Code │     POST /hooks/Stop           │  clooks daemon  │
-│             │ ──────────────────────────────► │  (persistent)    │
-│             │     POST /hooks/...            │                  │
-│             │ ──────────────────────────────► │  ┌────────────┐ │
-│             │                                │  │ handler A  │ │
-│             │ ◄────────────── JSON ───────── │  │ handler B  │ │
-│             │                                │  │ handler C  │ │
-└─────────────┘                                │  └────────────┘ │
-                                               │  metrics.jsonl  │
-                                               └──────────────────┘
-```
+## The Problem
+
+Claude Code spawns a fresh process for every hook invocation. Each Node.js cold start costs 30-40ms. Power users with multiple hooks accumulate 100+ process spawns per session -- that is 4-6 seconds of pure overhead, with zero visibility into what your hooks are doing or how they fail.
 
 ## Quick Start
 
 ```bash
-npm install -g clooks
+npm install -g @mauribadnights/clooks
 
-# If you have existing hooks in settings.json:
-clooks migrate    # converts command hooks → HTTP hooks + manifest
+# Option A: Migrate existing hooks automatically
+clooks migrate     # converts command hooks to HTTP hooks + manifest
+clooks start       # starts the daemon
 
-# Or start fresh:
-clooks init       # creates ~/.clooks/manifest.yaml
+# Option B: Start fresh
+clooks init        # creates ~/.clooks/manifest.yaml
+clooks start
+```
+
+That is it. Claude Code will now POST to your daemon instead of spawning processes.
+
+## How It Works
 
-clooks start      # starts the daemon
 ```
+Claude Code                          clooks daemon (localhost:7890)
+    |                                        |
+    |-- SessionStart ------> POST /hooks/SessionStart ------> [handler1, handler2]
+    |-- UserPromptSubmit --> POST /hooks/UserPromptSubmit --> [handler3]
+    |-- PreToolUse (x50) --> POST /hooks/PreToolUse --------> [handler4, handler5]
+    |-- Stop --------------> POST /hooks/Stop ---------------> [handler6]
+    |                                        |
+    |<-------------- JSON responses ---------|
+```
+
+One persistent process. Zero cold starts. Full observability.
 
-That's it. Claude Code will now POST to your daemon instead of spawning processes.
+After `clooks migrate`, your `settings.json` is rewritten so that `SessionStart` runs a single command hook (`clooks ensure-running`) and all other hooks become HTTP POSTs. The daemon loads handlers from `~/.clooks/manifest.yaml` and dispatches them in parallel per event. Handlers that fail 3 times consecutively are auto-disabled to prevent cascading failures.
 
 ## Commands
 
 | Command | Description |
-|---|---|
+|---------|-------------|
 | `clooks start` | Start the daemon (background by default, `--foreground` for debug) |
 | `clooks stop` | Stop the daemon |
 | `clooks status` | Show daemon status, uptime, and handler count |
@@ -53,7 +64,7 @@ That's it. Claude Code will now POST to your daemon instead of spawning processe
 | `clooks restore` | Restore original `settings.json` from backup |
 | `clooks doctor` | Run diagnostic health checks |
 | `clooks init` | Create default config directory and example manifest |
-| `clooks ensure-running` | Start daemon if not running (used by SessionStart hook) |
+| `clooks ensure-running` | Start daemon if not already running (used by SessionStart hook) |
 
 ## Manifest Format
 
@@ -63,13 +74,13 @@ Handlers are defined in `~/.clooks/manifest.yaml`:
 handlers:
   PreToolUse:
     - id: safety-guard
-      type: script
+      type: script                    # runs a shell command
       command: node ~/hooks/guard.js
       timeout: 3000
       enabled: true
 
     - id: context-injector
-      type: inline
+      type: inline                    # imports a JS module directly (no subprocess)
       module: ~/hooks/context.js
       timeout: 2000
 
@@ -84,10 +95,13 @@ 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)
+- `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
 
-## Stats
+### Execution Metrics
 
 ```
 $ clooks stats
@@ -101,53 +115,186 @@ UserPromptSubmit    12        1         1.8         0.9         4.2
 Total fires: 71 | Total errors: 1 | Spawns saved: ~71
 ```
 
-## How It Works with Claude Code
+### Diagnostics
+
+```
+$ clooks doctor
+
+[pass] Daemon is running (PID 44721, uptime 2h 13m)
+[pass] Port 7890 is responding
+[pass] Manifest loaded: 4 handlers across 3 events
+[pass] settings.json has HTTP hooks pointing to clooks
+[pass] No handlers in circuit-breaker state
+[warn] 1 handler error in last 24h (session-logger on Stop)
+```
+
+## Comparison
+
+| | Without clooks | With clooks |
+|---|---|---|
+| **Process model** | New process per hook invocation | One persistent HTTP server |
+| **Cold start overhead** | 30-40ms per invocation | 0ms (already running) |
+| **State management** | Stateless -- each invocation starts fresh | Persistent -- share state across invocations |
+| **Observability** | None | Metrics, stats, logs, doctor diagnostics |
+| **Error handling** | Silent failures | Auto-disable after 3 consecutive failures |
+
+## Configuration Reference
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| Port | `7890` | HTTP server port |
+| Config directory | `~/.clooks/` | Root configuration directory |
+| Manifest | `~/.clooks/manifest.yaml` | Handler definitions |
+| Metrics | `~/.clooks/metrics.jsonl` | Execution metrics log |
+| Daemon log | `~/.clooks/daemon.log` | Server output log |
+| PID file | `~/.clooks/daemon.pid` | Process ID file |
+
+## v0.2 Features
+
+### LLM Handlers
+
+Call the Anthropic Messages API directly from your manifest. Handlers with the same `batchGroup` are combined into a single API call, saving tokens and latency.
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: code-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review this tool call for $TOOL_NAME with args: $ARGUMENTS"
+      batchGroup: analysis
+      timeout: 15000
+
+    - id: security-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Check for security issues in $TOOL_NAME call: $ARGUMENTS"
+      batchGroup: analysis    # batched with code-review into one API call
+```
 
-After `clooks migrate`, your `settings.json` looks like this:
+**Setup:**
 
-```json
-{
-  "hooks": {
-    "SessionStart": [{ "hooks": [
-      { "type": "command", "command": "clooks ensure-running" }
-    ]}],
-    "PreToolUse": [{ "hooks": [
-      { "type": "http", "url": "http://localhost:7890/hooks/PreToolUse" }
-    ]}]
-  }
-}
+```bash
+npm install @anthropic-ai/sdk    # peer dependency, only needed for llm handlers
+export ANTHROPIC_API_KEY=sk-...  # or set in manifest: settings.anthropicApiKey
 ```
 
-The `SessionStart` command hook ensures the daemon is running (fast no-op if already up). All other hooks are HTTP POSTs — no process spawning, no cold starts.
+**Prompt template variables:**
 
-Handlers that fail 3 times consecutively are auto-disabled to prevent cascading failures.
+| 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 |
 
-## Configuration
+**LLM handler options:**
 
-| Item | Default |
-|---|---|
-| Port | `7890` |
-| Config directory | `~/.clooks/` |
-| Manifest | `~/.clooks/manifest.yaml` |
-| Metrics | `~/.clooks/metrics.jsonl` |
-| Daemon log | `~/.clooks/daemon.log` |
-| PID file | `~/.clooks/daemon.pid` |
+| 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 |
 
-## Comparison
+**How batching works:**
 
-|  | Without clooks | With clooks |
-|---|---|---|
-| **Process model** | New process per hook invocation | One persistent HTTP server |
-| **Cold start** | 50-100ms per invocation | 0ms (already running) |
-| **State** | Stateless — each invocation starts fresh | Persistent — share state across invocations |
-| **Observability** | None | Metrics, stats, logs, doctor diagnostics |
-| **Failure handling** | Silent | Auto-disable after 3 consecutive failures |
+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.
 
-## License
+### Intelligent Filtering
 
-MIT
+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:
+  PreToolUse:
+    - id: bash-guard
+      type: script
+      command: node ~/hooks/guard.js
+      filter: "Bash|Execute|!Read"   # runs for Bash/Execute, never for Read
+```
+
+### Shared Context Pre-fetch
+
+Fetch transcript, git status, or git diff once per hook event and share across all handlers. Avoids redundant I/O when multiple handlers need the same data. Use `$VARIABLE` interpolation in LLM prompts.
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+  - git_diff
+
+handlers:
+  Stop:
+    - id: session-summary
+      type: llm
+      model: claude-haiku-4-5
+      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.
+
+```
+$ clooks costs
+
+LLM Cost Summary
+  Total: $0.0142 (4,280 tokens)
+
+  By Model:
+    claude-haiku-4-5       $0.0142 (4,280 tokens)
+
+  By Handler:
+    code-review            $0.0089 (12 calls, avg 178 tokens)
+    security-check         $0.0053 (12 calls, avg 178 tokens)
+```
+
+- 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
 
-- **v0.2:** Matcher support in manifest, LLM call batching, token cost tracking
 - **v0.3:** Plugin ecosystem, dependency resolution between handlers
+- **v0.4:** Visual dashboard for hook management and metrics
+
+## Contributing
+
+Issues and pull requests are welcome. Run the test suite before submitting:
+
+```bash
+npm test
+npm run bench
+```
+
+## License
+
+MIT

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.1.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) {
@@ -113,6 +116,20 @@ program
     .action(() => {
     const metrics = new metrics_js_1.MetricsCollector();
     console.log(metrics.formatStatsTable());
+    // Append cost summary if LLM data exists
+    const costStats = metrics.getCostStats();
+    if (costStats.totalCost > 0) {
+        console.log('');
+        console.log(metrics.formatCostTable());
+    }
+});
+// --- costs ---
+program
+    .command('costs')
+    .description('Show LLM cost breakdown')
+    .action(() => {
+    const metrics = new metrics_js_1.MetricsCollector();
+    console.log(metrics.formatCostTable());
 });
 // --- migrate ---
 program
@@ -192,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/constants.d.ts

@@ -7,4 +7,12 @@ export declare const LOG_FILE: string;
 export declare const SETTINGS_BACKUP: string;
 export declare const MAX_CONSECUTIVE_FAILURES = 3;
 export declare const DEFAULT_HANDLER_TIMEOUT = 5000;
+export declare const COSTS_FILE: string;
+export declare const DEFAULT_LLM_TIMEOUT = 30000;
+export declare const DEFAULT_LLM_MAX_TOKENS = 1024;
+/** Pricing per million tokens (USD) — as of March 2026 */
+export declare const LLM_PRICING: Record<string, {
+    input: number;
+    output: number;
+}>;
 export declare const HOOK_EVENTS: string[];

package/dist/constants.js

@@ -1,7 +1,7 @@
 "use strict";
 // clooks constants
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.HOOK_EVENTS = exports.DEFAULT_HANDLER_TIMEOUT = exports.MAX_CONSECUTIVE_FAILURES = exports.SETTINGS_BACKUP = exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = void 0;
+exports.HOOK_EVENTS = exports.LLM_PRICING = exports.DEFAULT_LLM_MAX_TOKENS = exports.DEFAULT_LLM_TIMEOUT = exports.COSTS_FILE = exports.DEFAULT_HANDLER_TIMEOUT = exports.MAX_CONSECUTIVE_FAILURES = exports.SETTINGS_BACKUP = exports.LOG_FILE = exports.METRICS_FILE = exports.PID_FILE = exports.MANIFEST_PATH = exports.CONFIG_DIR = exports.DEFAULT_PORT = void 0;
 const os_1 = require("os");
 const path_1 = require("path");
 exports.DEFAULT_PORT = 7890;
@@ -13,6 +13,15 @@ exports.LOG_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'daemon.log');
 exports.SETTINGS_BACKUP = (0, path_1.join)(exports.CONFIG_DIR, 'settings.backup.json');
 exports.MAX_CONSECUTIVE_FAILURES = 3;
 exports.DEFAULT_HANDLER_TIMEOUT = 5000; // ms
+exports.COSTS_FILE = (0, path_1.join)(exports.CONFIG_DIR, 'costs.jsonl');
+exports.DEFAULT_LLM_TIMEOUT = 30000; // ms
+exports.DEFAULT_LLM_MAX_TOKENS = 1024;
+/** Pricing per million tokens (USD) — as of March 2026 */
+exports.LLM_PRICING = {
+    'claude-haiku-4-5': { input: 0.80, output: 4.00 },
+    'claude-sonnet-4-6': { input: 3.00, output: 15.00 },
+    'claude-opus-4-6': { input: 15.00, output: 75.00 },
+};
 exports.HOOK_EVENTS = [
     'SessionStart',
     'UserPromptSubmit',

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() {
@@ -93,7 +95,9 @@ function checkHandlerCommands() {
         const manifest = (0, manifest_js_1.loadManifest)();
         for (const [_event, handlers] of Object.entries(manifest.handlers)) {
             for (const handler of handlers) {
-                if (handler.type !== 'script' || !handler.command)
+                if (handler.type !== 'script')
+                    continue;
+                if (!handler.command)
                     continue;
                 // Extract the base command (first word)
                 const baseCmd = handler.command.split(/\s+/)[0];
@@ -164,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/filter.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Evaluate a keyword filter against input text.
+ *
+ * Filter syntax:
+ *   "word1|word2|word3"  — match if ANY keyword found (OR)
+ *   "!word"              — exclude if keyword found (NOT)
+ *   Mixed: "word1|word2|!word3" — match word1 OR word2, but NOT if word3 present
+ *
+ * Returns true if handler should execute, false if filtered out.
+ */
+export declare function evaluateFilter(filter: string, input: string): boolean;

package/dist/filter.js

@@ -0,0 +1,42 @@
+"use strict";
+// clooks filter engine — keyword-based handler filtering
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.evaluateFilter = evaluateFilter;
+/**
+ * Evaluate a keyword filter against input text.
+ *
+ * Filter syntax:
+ *   "word1|word2|word3"  — match if ANY keyword found (OR)
+ *   "!word"              — exclude if keyword found (NOT)
+ *   Mixed: "word1|word2|!word3" — match word1 OR word2, but NOT if word3 present
+ *
+ * Returns true if handler should execute, false if filtered out.
+ */
+function evaluateFilter(filter, input) {
+    const terms = filter.split('|').map((t) => t.trim()).filter(Boolean);
+    if (terms.length === 0)
+        return true;
+    const positive = [];
+    const negative = [];
+    for (const term of terms) {
+        if (term.startsWith('!')) {
+            negative.push(term.slice(1));
+        }
+        else {
+            positive.push(term);
+        }
+    }
+    const lowerInput = input.toLowerCase();
+    // If ANY negative term is found → blocked
+    for (const neg of negative) {
+        if (lowerInput.includes(neg.toLowerCase())) {
+            return false;
+        }
+    }
+    // If there are positive terms, at least ONE must match
+    if (positive.length > 0) {
+        return positive.some((pos) => lowerInput.includes(pos.toLowerCase()));
+    }
+    // Only negative terms and none matched → allow
+    return true;
+}

package/dist/handlers.d.ts

@@ -1,13 +1,19 @@
-import type { HandlerConfig, HandlerResult, HandlerState, HookEvent, HookInput } from './types.js';
+import type { HandlerConfig, HandlerResult, HandlerState, HookEvent, HookInput, PrefetchContext } from './types.js';
 /** Reset all handler states (useful for testing) */
 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.
+ * Optionally accepts pre-fetched context for LLM prompt rendering.
  */
-export declare function executeHandlers(_event: HookEvent, input: HookInput, handlers: HandlerConfig[]): Promise<HandlerResult[]>;
+export declare function executeHandlers(_event: HookEvent, input: HookInput, handlers: HandlerConfig[], context?: PrefetchContext): Promise<HandlerResult[]>;
 /**
  * Execute a script handler: spawn a child process, pipe input JSON to stdin,
  * read stdout as JSON response.