@mauribadnights/clooks 0.3.1 → 0.4.0

package/agents/clooks.md

@@ -0,0 +1,146 @@
+---
+name: clooks
+description: Expert assistant for clooks — the persistent hook runtime for Claude Code
+model: sonnet
+---
+
+You are the clooks expert agent. You have deep knowledge of the clooks architecture, configuration, and troubleshooting.
+
+## What is clooks
+
+clooks is a persistent HTTP daemon (localhost:7890) that handles Claude Code hooks. Instead of spawning a fresh process for every hook invocation, Claude Code POSTs to the daemon, which dispatches to handlers defined in ~/.clooks/manifest.yaml. This eliminates cold-start overhead (112x faster) and provides observability, filtering, LLM batching, and more.
+
+## Your capabilities
+
+You can read and modify the user's clooks configuration:
+- **Manifest:** ~/.clooks/manifest.yaml — defines all handlers
+- **Daemon log:** ~/.clooks/daemon.log — server output and errors
+- **Metrics:** ~/.clooks/metrics.jsonl — execution metrics (fires, errors, latency)
+- **Costs:** ~/.clooks/costs.jsonl — LLM token usage and costs
+- **Plugins:** ~/.clooks/plugins/ — installed plugins with their own handlers
+- **Settings:** ~/.claude/settings.json — Claude Code hook entries pointing to the daemon
+
+You can run clooks CLI commands:
+- `clooks doctor` — diagnose issues
+- `clooks stats -t` — show metrics (text mode since you're an agent)
+- `clooks costs` — show LLM cost breakdown
+- `clooks status` — daemon status
+- `clooks plugins` — list installed plugins
+- `clooks service status` — system service status
+
+## Architecture
+
+### Handler types
+- **script** — spawns `sh -c "command"`, pipes hook JSON to stdin, reads stdout (~5-35ms)
+- **inline** — imports a JS module, calls default export in-process (~0ms after first load)
+- **llm** — calls Anthropic Messages API with prompt template and $VARIABLE interpolation
+
+### Handler fields
+Every handler has:
+- `id` (required) — unique identifier
+- `type` (required) — script, inline, or llm
+- `filter` — keyword filter: "word1|word2|!word3" (OR logic, ! negates, case-insensitive)
+- `project` — glob against cwd: "*/Driffusion/*" (only fire in matching directories)
+- `agent` — agent name match: "builder,coo" (only fire in matching agent sessions)
+- `depends` — array of handler IDs this handler waits for
+- `async` — boolean, fire-and-forget (doesn't block Claude's response)
+- `sessionIsolation` — boolean, reset handler state on SessionStart
+- `timeout` — milliseconds
+- `enabled` — boolean
+
+### LLM handler extra fields
+- `model` — claude-haiku-4-5, claude-sonnet-4-6, or claude-opus-4-6
+- `prompt` — template with $TRANSCRIPT, $GIT_STATUS, $GIT_DIFF, $ARGUMENTS, $TOOL_NAME, $PROMPT, $CWD
+- `batchGroup` — handlers with same group + same session = one API call
+- `maxTokens`, `temperature`
+
+### Plugin system
+Plugins ship a `clooks-plugin.yaml` with handlers. Install via `clooks add <path>`. Handler IDs are namespaced as `pluginName/handlerId`. Manage with `clooks plugins`, `clooks remove <name>`.
+
+### Dependency resolution
+Handlers with `depends: [other-handler-id]` execute in topological order (waves). Wave 0 = no deps, Wave 1 = depends on Wave 0, etc. Parallel within each wave.
+
+### Short-circuit chains
+PreToolUse deny → PostToolUse handlers auto-skipped for that tool call (30s TTL cache).
+
+### Manifest format
+```yaml
+handlers:
+  PreToolUse:
+    - id: safety-guard
+      type: script
+      command: node ~/hooks/guard.js
+      filter: "Bash|!Read"
+      project: "*/my-project/*"
+      timeout: 3000
+
+  UserPromptSubmit:
+    - id: learning-detector
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Analyze for learning evidence: $PROMPT"
+      batchGroup: analysis
+      async: true
+
+  Stop:
+    - id: session-logger
+      type: inline
+      module: ~/.clooks/handlers/logger.js
+
+prefetch:
+  - transcript
+  - git_status
+
+settings:
+  port: 7890
+  logLevel: info
+  authToken: abc123
+```
+
+### Settings.json integration
+Claude Code settings.json has HTTP hooks pointing to the daemon:
+```json
+{
+  "hooks": {
+    "PostToolUse": [{ "hooks": [{ "type": "http", "url": "http://localhost:7890/hooks/PostToolUse" }] }]
+  }
+}
+```
+SessionStart includes a command hook for `clooks ensure-running` that auto-starts the daemon.
+`clooks sync` ensures settings.json has HTTP hooks for all events with handlers.
+
+### System service
+`clooks service install` creates a launchd plist (macOS), systemd unit (Linux), or scheduled task (Windows) that keeps the daemon alive across sleep/wake/crashes.
+
+## How to help users
+
+### Diagnosing issues
+1. Run `clooks doctor` — check for errors/warnings
+2. Read ~/.clooks/daemon.log — look for errors, auth failures, parse failures
+3. Run `clooks stats -t` — check for high error rates or slow handlers
+4. Check ~/.clooks/manifest.yaml — validate handler configs
+5. Check ~/.claude/settings.json — verify HTTP hooks point to localhost:7890
+
+### Common problems
+- **ECONNREFUSED** — daemon not running. `clooks start` or `clooks service install`
+- **HTTP 401** — auth token mismatch between manifest and settings.json. `clooks rotate-token`
+- **HTTP 429** — rate limited from too many auth failures. Restart daemon: `clooks stop && clooks start`
+- **Handler always filtered** — check filter/project/agent fields, run with `clooks stats -t` to see filtered count
+- **Slow handler** — check avg ms in stats. Consider `async: true` if it doesn't need to inject context
+- **Stale PID** — `rm ~/.clooks/daemon.pid && clooks start`
+
+### Optimizing performance
+- Convert Python script handlers to inline JS handlers (1000ms → <1ms)
+- Mark non-blocking handlers as `async: true`
+- Use `filter` to skip irrelevant invocations
+- Use `project`/`agent` to scope handlers to relevant contexts
+- Batch LLM handlers with `batchGroup`
+- Use `prefetch` to avoid redundant file reads
+
+### Writing new handlers
+Help users write handlers for their specific needs. Always:
+- Generate unique, descriptive IDs
+- Set appropriate timeouts
+- Add filters when the handler doesn't need every invocation
+- Use async for analysis/logging that doesn't affect Claude's response
+- Test with `echo '{"session_id":"test","cwd":"/tmp","hook_event_name":"PostToolUse"}' | node handler.js`

package/dist/agent.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Install/update the clooks agent to ~/.claude/agents/clooks.md.
+ * Returns true if installed/updated, false if already up to date.
+ */
+export declare function installAgent(): boolean;
+/**
+ * Check if the clooks agent is installed.
+ */
+export declare function isAgentInstalled(): boolean;

package/dist/agent.js

@@ -0,0 +1,43 @@
+"use strict";
+// clooks agent — auto-install the clooks expert agent to ~/.claude/agents/
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.installAgent = installAgent;
+exports.isAgentInstalled = isAgentInstalled;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const AGENT_SOURCE = (0, path_1.join)(__dirname, '..', 'agents', 'clooks.md');
+const AGENT_DEST_DIR = (0, path_1.join)((0, os_1.homedir)(), '.claude', 'agents');
+const AGENT_DEST = (0, path_1.join)(AGENT_DEST_DIR, 'clooks.md');
+/**
+ * Install/update the clooks agent to ~/.claude/agents/clooks.md.
+ * Returns true if installed/updated, false if already up to date.
+ */
+function installAgent() {
+    // Read source agent from package
+    let source;
+    try {
+        source = (0, fs_1.readFileSync)(AGENT_SOURCE, 'utf-8');
+    }
+    catch {
+        return false; // Agent file not found in package
+    }
+    // Check if already installed and identical
+    if ((0, fs_1.existsSync)(AGENT_DEST)) {
+        const existing = (0, fs_1.readFileSync)(AGENT_DEST, 'utf-8');
+        if (existing === source)
+            return false; // Already up to date
+    }
+    // Install/update
+    if (!(0, fs_1.existsSync)(AGENT_DEST_DIR)) {
+        (0, fs_1.mkdirSync)(AGENT_DEST_DIR, { recursive: true });
+    }
+    (0, fs_1.writeFileSync)(AGENT_DEST, source, 'utf-8');
+    return true;
+}
+/**
+ * Check if the clooks agent is installed.
+ */
+function isAgentInstalled() {
+    return (0, fs_1.existsSync)(AGENT_DEST);
+}

package/dist/cli.js

@@ -10,14 +10,18 @@ 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 service_js_1 = require("./service.js");
 const constants_js_1 = require("./constants.js");
+const tui_js_1 = require("./tui.js");
+const agent_js_1 = require("./agent.js");
 const fs_1 = require("fs");
 const path_1 = require("path");
 const program = new commander_1.Command();
 program
     .name('clooks')
     .description('Persistent hook runtime for Claude Code')
-    .version('0.3.1');
+    .version('0.4.0');
 // --- start ---
 program
     .command('start')
@@ -27,10 +31,18 @@ program
     .action(async (opts) => {
     const noWatch = opts.watch === false;
     if (!opts.foreground) {
-        // Background mode: check if already running, then spawn detached
+        // Background mode: check if already running and healthy
         if ((0, server_js_1.isDaemonRunning)()) {
-            console.log('Daemon is already running.');
-            process.exit(0);
+            const healthy = await (0, server_js_1.isDaemonHealthy)();
+            if (healthy) {
+                console.log('Daemon is already running.');
+                process.exit(0);
+            }
+            // PID alive but daemon unhealthy — stale process after sleep/lid-close
+            const stalePid = (0, server_js_1.cleanupStaleDaemon)();
+            if (stalePid) {
+                console.log(`Cleaned up stale daemon (pid ${stalePid}), starting fresh`);
+            }
         }
         // Ensure config dir exists
         if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
@@ -40,6 +52,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}`);
@@ -88,6 +105,8 @@ program
     }
     const pid = (0, fs_1.existsSync)(constants_js_1.PID_FILE) ? (0, fs_1.readFileSync)(constants_js_1.PID_FILE, 'utf-8').trim() : '?';
     // Try to hit health endpoint
+    // Service status
+    const serviceStatus = (0, service_js_1.getServiceStatus)();
     try {
         const { get } = await import('http');
         const data = await new Promise((resolve, reject) => {
@@ -107,9 +126,11 @@ program
         console.log(`Uptime: ${formatUptime(health.uptime)}`);
         console.log(`Handlers loaded: ${health.handlers_loaded}`);
         console.log(`Plugins: ${pluginCount}`);
+        console.log(`Service: ${serviceStatus}`);
     }
     catch {
         console.log(`Status: running (pid ${pid})`);
+        console.log(`Service: ${serviceStatus}`);
         console.log(`Note: Could not reach health endpoint on port ${constants_js_1.DEFAULT_PORT}`);
     }
 });
@@ -117,17 +138,25 @@ program
 program
     .command('stats')
     .description('Show hook execution metrics')
-    .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) {
+    .option('-t, --text', 'Plain text output (default when piped)')
+    .action((opts) => {
+    if (opts.text || !process.stdout.isTTY) {
+        // Text output (forced via flag or non-TTY/piped stdout)
+        const metrics = new metrics_js_1.MetricsCollector();
+        console.log(metrics.formatStatsTable());
         console.log('');
-        console.log(metrics.formatCostTable());
+        console.log('Per Handler:');
+        console.log(metrics.formatHandlerStatsTable());
+        // Append cost summary if LLM data exists
+        const costStats = metrics.getCostStats();
+        if (costStats.totalCost > 0) {
+            console.log('');
+            console.log(metrics.formatCostTable());
+        }
+    }
+    else {
+        // Interactive TUI (default for terminals)
+        (0, tui_js_1.launchDashboard)();
     }
 });
 // --- costs ---
@@ -151,6 +180,20 @@ program
         console.log(`  Handlers created: ${result.handlersCreated}`);
         console.log(`  Backup: ~/.clooks/settings.backup.json`);
         console.log('\nRun "clooks start" to start the daemon.');
+        // Auto-install clooks agent
+        if ((0, agent_js_1.installAgent)()) {
+            console.log('Agent updated: claude --agent clooks');
+        }
+        // Auto-install system service
+        if (!(0, service_js_1.isServiceInstalled)()) {
+            try {
+                (0, service_js_1.installService)();
+                console.log('System service installed (auto-start on login, auto-restart on crash).');
+            }
+            catch {
+                console.log('Note: Could not install system service. Run "clooks service install" manually.');
+            }
+        }
     }
     catch (err) {
         console.error('Migration failed:', err instanceof Error ? err.message : err);
@@ -187,14 +230,48 @@ 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
-        process.exit(0);
+        const healthy = await (0, server_js_1.isDaemonHealthy)();
+        if (healthy) {
+            // Already running and healthy — sync settings silently and exit fast
+            (0, sync_js_1.syncSettings)();
+            process.exit(0);
+        }
+        // PID alive but daemon unhealthy — stale process after sleep/lid-close
+        const stalePid = (0, server_js_1.cleanupStaleDaemon)();
+        if (stalePid) {
+            // Log to daemon.log for visibility
+            const { appendFileSync } = await import('fs');
+            const { LOG_FILE } = await import('./constants.js');
+            try {
+                appendFileSync(LOG_FILE, `[${new Date().toISOString()}] Cleaned up stale daemon (pid ${stalePid}), starting fresh\n`, 'utf-8');
+            }
+            catch {
+                // ignore
+            }
+        }
     }
     // Ensure config dir exists
     if (!(0, fs_1.existsSync)(constants_js_1.CONFIG_DIR)) {
@@ -206,6 +283,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 ---
@@ -221,6 +300,20 @@ program
     console.log(`Created: ${path}`);
     console.log(`Auth token: ${token}`);
     console.log('Edit this file to configure your hook handlers.');
+    // Auto-install clooks agent
+    if ((0, agent_js_1.installAgent)()) {
+        console.log('Agent updated: claude --agent clooks');
+    }
+    // Auto-install system service
+    if (!(0, service_js_1.isServiceInstalled)()) {
+        try {
+            (0, service_js_1.installService)();
+            console.log('System service installed (auto-start on login, auto-restart on crash).');
+        }
+        catch {
+            console.log('Note: Could not install system service. Run "clooks service install" manually.');
+        }
+    }
 });
 // --- rotate-token ---
 program
@@ -255,6 +348,10 @@ program
         console.log(`Updating: ${currentVersion} \u2192 ${latest}`);
         execSync('npm install -g @mauribadnights/clooks@latest', { stdio: 'inherit' });
         console.log(`Updated to ${latest}.`);
+        // Auto-install/update clooks agent
+        if ((0, agent_js_1.installAgent)()) {
+            console.log('Agent updated: claude --agent clooks');
+        }
         // Restart daemon if running
         if ((0, server_js_1.isDaemonRunning)()) {
             console.log('Restarting daemon...');
@@ -294,6 +391,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);
@@ -344,6 +446,44 @@ program
         }
     }
 });
+// --- service ---
+const service = program.command('service').description('Manage clooks system service');
+service.command('install')
+    .description('Install as system service (auto-start, auto-restart)')
+    .action(() => {
+    try {
+        (0, service_js_1.installService)();
+        console.log('Service installed. clooks will now:');
+        console.log('  - Start automatically on login');
+        console.log('  - Restart automatically if it crashes');
+        console.log('  - Survive sleep/wake cycles');
+    }
+    catch (err) {
+        console.error('Failed to install service:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+service.command('uninstall')
+    .description('Remove system service')
+    .action(() => {
+    try {
+        (0, service_js_1.uninstallService)();
+        console.log('Service removed.');
+    }
+    catch (err) {
+        console.error('Failed to uninstall service:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
+service.command('status')
+    .description('Show service status')
+    .action(() => {
+    const status = (0, service_js_1.getServiceStatus)();
+    console.log(`Service: ${status}`);
+    if (status === 'not-installed') {
+        console.log('Run "clooks service install" to install.');
+    }
+});
 program.parse();
 function formatUptime(seconds) {
     if (seconds < 60)

package/dist/doctor.js

@@ -10,7 +10,9 @@ const os_1 = require("os");
 const constants_js_1 = require("./constants.js");
 const manifest_js_1 = require("./manifest.js");
 const server_js_1 = require("./server.js");
+const service_js_1 = require("./service.js");
 const plugin_js_1 = require("./plugin.js");
+const agent_js_1 = require("./agent.js");
 const yaml_1 = require("yaml");
 /**
  * Run all diagnostic checks and return results.
@@ -35,6 +37,10 @@ async function runDoctor() {
     results.push(checkAuthToken());
     // 9. Plugin health checks
     results.push(...checkPluginHealth());
+    // 10. System service
+    results.push(checkService());
+    // 11. clooks agent
+    results.push(checkAgent());
     return results;
 }
 function checkConfigDir() {
@@ -276,3 +282,17 @@ function checkPluginHealth() {
     }
     return results;
 }
+function checkService() {
+    const status = (0, service_js_1.getServiceStatus)();
+    if (status === 'running')
+        return { check: 'System service', status: 'ok', message: 'Installed and running' };
+    if (status === 'stopped')
+        return { check: 'System service', status: 'warn', message: 'Installed but not running' };
+    return { check: 'System service', status: 'warn', message: 'Not installed. Run "clooks service install" for auto-restart.' };
+}
+function checkAgent() {
+    if ((0, agent_js_1.isAgentInstalled)()) {
+        return { check: 'clooks agent', status: 'ok', message: 'Installed at ~/.claude/agents/clooks.md' };
+    }
+    return { check: 'clooks agent', status: 'warn', message: 'Not installed. Run "clooks init" to install.' };
+}

package/dist/handlers.d.ts

@@ -1,4 +1,10 @@
 import type { HandlerConfig, HandlerResult, HandlerState, HookEvent, HookInput, PrefetchContext } from './types.js';
+/** Match handler agent field against current session agent (case-insensitive, comma-separated) */
+declare function matchAgent(pattern: string, currentAgent: string): boolean;
+/** Match handler project field against cwd path */
+declare function matchProject(pattern: string, cwd: string): boolean;
+/** Exported for testing */
+export { matchAgent, matchProject };
 /** Reset all handler states (useful for testing) */
 export declare function resetHandlerStates(): void;
 /** Get a copy of the handler states map */
@@ -16,7 +22,7 @@ export declare function resetSessionIsolatedHandlers(handlers: HandlerConfig[]):
  * 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[]>;
+export declare function executeHandlers(_event: HookEvent, input: HookInput, handlers: HandlerConfig[], context?: PrefetchContext, onAsyncResult?: (result: HandlerResult) => void, currentAgent?: string): Promise<HandlerResult[]>;
 /**
  * Execute a script handler: spawn a child process, pipe input JSON to stdin,
  * read stdout as JSON response.

package/dist/handlers.js

@@ -1,6 +1,8 @@
 "use strict";
 // clooks hook handlers — execution engine
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.matchAgent = matchAgent;
+exports.matchProject = matchProject;
 exports.resetHandlerStates = resetHandlerStates;
 exports.getHandlerStates = getHandlerStates;
 exports.cleanupHandlerState = cleanupHandlerState;
@@ -15,6 +17,23 @@ 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");
+/** Match handler agent field against current session agent (case-insensitive, comma-separated) */
+function matchAgent(pattern, currentAgent) {
+    const agents = pattern.split(',').map(a => a.trim().toLowerCase());
+    return agents.includes(currentAgent.toLowerCase());
+}
+/** Match handler project field against cwd path */
+function matchProject(pattern, cwd) {
+    if (!cwd)
+        return false;
+    // If pattern has wildcards, extract the literal parts and check includes
+    if (pattern.includes('*')) {
+        const parts = pattern.split('*').filter(Boolean);
+        return parts.every(part => cwd.includes(part));
+    }
+    // Exact match or prefix match
+    return cwd.startsWith(pattern) || cwd === pattern;
+}
 /** Runtime state per handler ID */
 const handlerStates = new Map();
 function getState(id) {
@@ -60,7 +79,7 @@ function resetSessionIsolatedHandlers(handlers) {
  * 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) {
+async function executeHandlers(_event, input, handlers, context, onAsyncResult, currentAgent) {
     // Pre-check: filter out disabled/auto-disabled/filtered handlers before dep resolution
     const eligible = [];
     const skippedResults = [];
@@ -79,6 +98,20 @@ async function executeHandlers(_event, input, handlers, context) {
             });
             continue;
         }
+        // Agent matching
+        if (handler.agent) {
+            if (!currentAgent || !matchAgent(handler.agent, currentAgent)) {
+                skippedResults.push({ id: handler.id, ok: true, duration_ms: 0, filtered: true });
+                continue;
+            }
+        }
+        // Project matching (glob against cwd)
+        if (handler.project) {
+            if (!matchProject(handler.project, input.cwd)) {
+                skippedResults.push({ id: handler.id, ok: true, duration_ms: 0, filtered: true });
+                continue;
+            }
+        }
         if (handler.filter) {
             const inputStr = JSON.stringify(input);
             if (!(0, filter_js_1.evaluateFilter)(handler.filter, inputStr)) {
@@ -97,14 +130,83 @@ async function executeHandlers(_event, input, handlers, context) {
     if (eligible.length === 0) {
         return skippedResults;
     }
+    // Separate async handlers from sync handlers
+    // Async handlers with dependents (or depended upon) are forced synchronous
+    const eligibleIds = new Set(eligible.map(h => h.id));
+    const dependedUpon = new Set();
+    for (const h of eligible) {
+        if (h.depends) {
+            for (const dep of h.depends) {
+                if (eligibleIds.has(dep))
+                    dependedUpon.add(dep);
+            }
+        }
+    }
+    const syncHandlers = [];
+    const asyncHandlers = [];
+    for (const handler of eligible) {
+        if (handler.async) {
+            const hasDependents = dependedUpon.has(handler.id);
+            const hasDeps = handler.depends?.some(d => eligibleIds.has(d)) ?? false;
+            if (hasDependents || hasDeps) {
+                // Async handler has dependency relationships — force synchronous
+                console.warn(`[clooks] Warning: async handler "${handler.id}" has dependency relationships, running synchronously`);
+                syncHandlers.push(handler);
+            }
+            else {
+                asyncHandlers.push(handler);
+            }
+        }
+        else {
+            syncHandlers.push(handler);
+        }
+    }
+    // Fire async handlers without awaiting
+    for (const handler of asyncHandlers) {
+        getState(handler.id).totalFires++;
+        if (handler.type === 'llm') {
+            (0, llm_js_1.executeLLMHandlersBatched)([handler], input, context ?? {}, input.session_id).then(results => {
+                for (const result of results) {
+                    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;
+                    }
+                    onAsyncResult?.(result);
+                }
+            }).catch(() => { }); // never crash
+        }
+        else {
+            executeOtherHandler(handler, input).then(result => {
+                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;
+                }
+                onAsyncResult?.(result);
+            }).catch(() => { }); // never crash
+        }
+    }
+    // Execute sync handlers with dependency resolution
+    if (syncHandlers.length === 0) {
+        return skippedResults;
+    }
     // Resolve execution order into waves
     let waves;
     try {
-        waves = (0, deps_js_1.resolveExecutionOrder)(eligible);
+        waves = (0, deps_js_1.resolveExecutionOrder)(syncHandlers);
     }
     catch {
         // If dep resolution fails, fall back to flat parallel execution
-        waves = [eligible];
+        waves = [syncHandlers];
     }
     const allResults = [...skippedResults];
     const handlerOutputs = {};