@mauribadnights/clooks 0.5.0 → 0.5.2

package/docs/guides/async-handlers.md

@@ -0,0 +1,42 @@
+# Async Handlers
+
+## Overview
+
+Set `async: true` on any handler to execute it without blocking Claude Code's response. The handler runs in the background; its output is NOT included in the hook response.
+
+## Use Cases
+
+- Logging and analytics
+- Session tracking
+- Background notifications
+- Non-critical metric collection
+
+## Configuration
+
+```yaml
+handlers:
+  UserPromptSubmit:
+    - id: prompt-analytics
+      type: inline
+      module: ~/hooks/analytics.js
+      async: true
+```
+
+## Behavior
+
+- Fires immediately, does not await completion
+- Errors are swallowed (logged to `daemon.log` but don't affect response)
+- Results delivered via internal `onAsyncResult` callback
+- Metrics still recorded for async handlers
+
+## Limitations
+
+- Output NOT included in hook response to Claude Code
+- If `depends` is set on an async handler, it is forced synchronous (with warning)
+- Cannot be depended upon by other handlers
+
+> **Note:** Async handlers are ideal for side effects that should never slow down the user experience. If you need the handler's output to influence Claude's behavior, use a synchronous handler instead.
+
+---
+
+[Home](../index.md) | [Prev: Dependencies](dependencies.md) | [Next: Short-Circuit](short-circuit.md)

package/docs/guides/dependencies.md

@@ -0,0 +1,153 @@
+# Dependencies
+
+Handlers can declare dependencies on other handlers using the `depends` field. clooks resolves dependencies into execution "waves" using topological sort (Kahn's algorithm), running independent handlers in parallel while respecting ordering constraints.
+
+## Overview
+
+Without dependencies, all handlers for an event run in parallel. With dependencies, handlers are grouped into sequential waves:
+
+- **Wave 0:** Handlers with no dependencies.
+- **Wave 1:** Handlers whose dependencies are all in wave 0.
+- **Wave N:** Handlers whose dependencies are all in waves 0 through N-1.
+
+Handlers within the same wave run in parallel. Waves execute sequentially.
+
+## How It Works
+
+1. The dependency graph is built from `depends` fields across all eligible handlers for the event.
+2. Handlers are sorted into waves using Kahn's algorithm (BFS topological sort).
+3. Wave 0 executes first. All handlers in wave 0 run in parallel.
+4. When wave 0 completes, wave 1 starts. Its handlers can access outputs from wave 0.
+5. This continues until all waves have executed.
+
+## Example
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: context-loader
+      type: inline
+      module: ~/hooks/context.js
+      # No depends -- Wave 0
+
+    - id: security-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Check security of $TOOL_NAME with args: $ARGUMENTS"
+      # No depends -- Wave 0 (parallel with context-loader)
+
+    - id: deep-review
+      type: llm
+      model: claude-sonnet-4-6
+      prompt: "Perform deep review with full context: $ARGUMENTS"
+      depends: [context-loader, security-check]
+      # Both deps in Wave 0 -- this runs in Wave 1
+```
+
+Execution order:
+
+```
+Wave 0: context-loader + security-check (parallel)
+   |
+   v
+Wave 1: deep-review (after both wave 0 handlers complete)
+```
+
+## Accessing Dependency Outputs
+
+Handlers in wave N receive outputs from all previous waves via the `_handlerOutputs` field injected into their input:
+
+```json
+{
+  "session_id": "...",
+  "cwd": "...",
+  "hook_event_name": "PreToolUse",
+  "tool_name": "Write",
+  "_handlerOutputs": {
+    "context-loader": {
+      "additionalContext": "Loaded project context..."
+    },
+    "security-check": {
+      "additionalContext": "No security issues found."
+    }
+  }
+}
+```
+
+For inline handlers, access it directly from the input object:
+
+```javascript
+export default async function(input) {
+  const priorResults = input._handlerOutputs || {};
+  const securityResult = priorResults['security-check'];
+
+  // Use prior results to inform this handler's logic
+  if (securityResult?.additionalContext?.includes('issue')) {
+    return { decision: 'block', reason: 'Security issue detected upstream' };
+  }
+
+  return { additionalContext: 'All clear after deep review.' };
+}
+```
+
+For LLM handlers, dependency outputs are available in the input but not directly interpolable into prompt templates. Use an inline handler as a dependency to prepare context that downstream LLM handlers can consume.
+
+## Cycle Detection
+
+Circular dependencies are detected at execution time. If a cycle exists, clooks throws an error identifying the affected handler IDs:
+
+```
+Error: Dependency cycle detected among handlers: handler-a, handler-b
+```
+
+The daemon logs the error and skips all handlers involved in the cycle. Other handlers in the same event that are not part of the cycle execute normally.
+
+## Cross-Plugin Dependencies
+
+Plugin handlers are namespaced as `pluginName/handlerId`. Dependency references follow these rules:
+
+| Reference Style | Resolves To |
+|-----------------|-------------|
+| `depends: [other-handler]` | Same-plugin handler (auto-namespaced) |
+| `depends: [other-plugin/handler-id]` | Handler from a different plugin |
+| `depends: [user-handler-id]` | Handler defined in the user manifest |
+
+Example with a plugin handler depending on a user-defined handler:
+
+```yaml
+# In clooks-plugin.yaml (plugin: my-plugin)
+handlers:
+  PreToolUse:
+    - id: plugin-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review after context load: $ARGUMENTS"
+      depends: [context-loader]  # References user manifest handler
+```
+
+The fully qualified ID of this handler is `my-plugin/plugin-review`. Other plugins or user handlers can depend on it using that full name.
+
+## Async and Dependencies
+
+Async handlers (`async: true`) that participate in dependency relationships are forced to run synchronously. This applies when:
+
+- An async handler has `depends` referencing other handlers in the same event.
+- Other handlers in the same event list an async handler in their `depends`.
+
+In both cases, clooks logs a warning and runs the handler synchronously:
+
+```
+[clooks] Warning: async handler "my-handler" has dependency relationships, running synchronously
+```
+
+This is because fire-and-forget execution cannot guarantee dependency ordering. If you need a handler to be truly async, remove it from all dependency chains.
+
+## Dependencies and Filtering
+
+Dependencies are resolved after filtering. If a handler's dependency is filtered out (by keyword filter, agent, or project scope), the dependency is treated as satisfied. The dependent handler will not find that dependency's output in `_handlerOutputs`, but it will not be blocked waiting for it.
+
+Only dependencies referencing handlers within the current event's eligible set are considered. References to unknown handler IDs are silently ignored.
+
+---
+
+[Home](../index.md) | [Prev: Filtering](filtering.md) | [Next: Async Handlers](async-handlers.md)

package/docs/guides/filtering.md

@@ -0,0 +1,153 @@
+# Filtering
+
+Handlers can be scoped to fire only under specific conditions. clooks provides three filtering mechanisms: keyword filters, agent scoping, and project scoping. All filters are AND'd together -- a handler only fires if every applicable filter passes.
+
+## Keyword Filters
+
+The `filter` field applies a keyword match against the JSON-stringified hook input. Matching is case-insensitive.
+
+### Syntax
+
+| Pattern | Meaning |
+|---------|---------|
+| `"word1\|word2"` | Match if ANY keyword is found (OR) |
+| `"!word"` | Exclude if keyword is found (NOT) |
+| `"word1\|!word2"` | Match if word1 is present AND word2 is absent |
+
+The filter string is split on `|`. Each term is classified as positive (no prefix) or negative (`!` prefix). The rules are:
+
+1. If ANY negative term is found in the input, the handler is **blocked**.
+2. If there are positive terms, at least ONE must be found for the handler to **fire**.
+3. If there are only negative terms and none matched, the handler **fires**.
+
+### Examples
+
+**Fire only for Bash or Execute tools:**
+
+```yaml
+- id: bash-guard
+  type: script
+  command: "node ~/hooks/guard.js"
+  filter: "Bash|Execute"
+```
+
+**Fire for everything except Read and Glob:**
+
+```yaml
+- id: write-logger
+  type: inline
+  module: ~/hooks/logger.js
+  filter: "!Read|!Glob"
+```
+
+This works because both `Read` and `Glob` are negative terms. The handler fires whenever neither term appears in the input.
+
+**Fire for Write unless "test" appears in the input:**
+
+```yaml
+- id: write-review
+  type: llm
+  model: claude-haiku-4-5
+  prompt: "Review: $ARGUMENTS"
+  filter: "Write|!test"
+```
+
+Here `Write` is a positive term and `test` is negative. The handler fires when the input contains "Write" but does not contain "test".
+
+> **Note:** The filter matches against the entire JSON-stringified hook input, not just the tool name. This means field values, file paths, and argument content are all searchable.
+
+## Agent Scoping
+
+The `agent` field restricts a handler to specific Claude Code agent sessions.
+
+### Syntax
+
+A comma-separated list of agent names (case-insensitive). The handler only fires when the current session's agent matches one of the listed names.
+
+```yaml
+- id: builder-guard
+  type: script
+  command: "node ~/hooks/builder-guard.js"
+  agent: "builder"
+```
+
+```yaml
+- id: multi-agent-hook
+  type: inline
+  module: ~/hooks/shared.js
+  agent: "builder,coo"
+```
+
+### How Agent Detection Works
+
+The agent name is extracted from the `agent_type` field of the `SessionStart` event payload. clooks caches this per `session_id`. Subsequent events in the same session use the cached value.
+
+If `agent` is omitted from a handler, it fires in all sessions regardless of agent type.
+
+## Project Scoping
+
+The `project` field restricts a handler to sessions running in specific directories. It is matched against the `cwd` field of the hook input.
+
+### Matching Rules
+
+- **With wildcards (`*`):** The pattern is split on `*` and each literal segment must appear in the cwd path. Order does not matter.
+- **Without wildcards:** The cwd must start with the pattern (prefix match) or equal it exactly.
+
+### Examples
+
+**Only fire in Driffusion projects:**
+
+```yaml
+- id: driffusion-lint
+  type: script
+  command: "node ~/hooks/driffusion-lint.js"
+  project: "*/Driffusion/*"
+```
+
+This matches any cwd containing `/Driffusion/` anywhere in the path.
+
+**Only fire in a specific directory:**
+
+```yaml
+- id: work-hook
+  type: inline
+  module: ~/hooks/work.js
+  project: "/Users/me/work"
+```
+
+This matches any cwd that starts with `/Users/me/work`.
+
+## Combining Filters
+
+All filters are evaluated in order. A handler fires only if every condition passes:
+
+1. `enabled` is not `false`.
+2. The handler is not auto-disabled (consecutive failures < 3).
+3. `agent` matches the current session agent (if specified).
+4. `project` matches the session cwd (if specified).
+5. `filter` keyword match passes (if specified).
+
+If any condition fails, the handler is skipped. Skipped handlers are recorded in metrics with `filtered: true` and zero execution time.
+
+### Full Example
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: targeted-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review: $ARGUMENTS"
+      filter: "Write|Edit"
+      agent: "builder"
+      project: "*/Driffusion/*"
+```
+
+This handler fires only when:
+- The tool call input contains "Write" or "Edit".
+- The session is running the `builder` agent.
+- The working directory contains `/Driffusion/` in its path.
+
+---
+
+[Home](../index.md) | [Prev: LLM Handlers](llm-handlers.md) | [Next: Dependencies](dependencies.md)

package/docs/guides/handlers.md

@@ -0,0 +1,236 @@
+# Handlers
+
+clooks supports three handler types: **script**, **inline**, and **llm**. Each type trades off between flexibility and performance. This guide covers how each type works, when to use it, and how to structure the output.
+
+## Script Handlers
+
+Script handlers run shell commands via `sh -c`. They are the most portable option -- any language that reads stdin and writes stdout works.
+
+### How They Work
+
+1. clooks spawns a child process with the handler's `command`.
+2. The full `HookInput` JSON is piped to the process's stdin.
+3. The process writes its response to stdout.
+4. If stdout is valid JSON, it is used directly. If not, the raw text is wrapped as `{"additionalContext": "..."}`.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `command` | string | Shell command to execute via `sh -c` |
+
+### Default Timeout
+
+5000ms. Override with the `timeout` field.
+
+### Example Configuration
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: bash-guard
+      type: script
+      command: "node ~/.clooks/hooks/bash-guard.js"
+      filter: "Bash"
+      timeout: 3000
+```
+
+### Example Script (Node.js)
+
+```javascript
+#!/usr/bin/env node
+
+// Read HookInput from stdin
+let data = '';
+process.stdin.on('data', chunk => { data += chunk; });
+process.stdin.on('end', () => {
+  const input = JSON.parse(data);
+
+  // Check if the Bash command looks dangerous
+  const args = input.tool_input || {};
+  const command = args.command || '';
+
+  if (command.includes('rm -rf /')) {
+    // Block the tool call
+    console.log(JSON.stringify({
+      decision: 'block',
+      reason: 'Dangerous rm -rf command detected'
+    }));
+  } else {
+    // Add context for Claude
+    console.log(JSON.stringify({
+      additionalContext: `Bash command reviewed: ${command.slice(0, 80)}`
+    }));
+  }
+});
+```
+
+> **Note:** Non-zero exit codes are treated as handler failures. Stderr output is captured and included in the error message.
+
+## Inline Handlers
+
+Inline handlers import an ES module in-process. There is no subprocess overhead, making them the fastest handler type.
+
+### How They Work
+
+1. clooks dynamically imports the module specified by `module`.
+2. The module's default export is called with the `HookInput` object.
+3. The return value becomes the handler output.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `module` | string | Path to a `.js` or `.ts` file with a default export function |
+
+### Default Timeout
+
+5000ms. Override with the `timeout` field.
+
+### Example Configuration
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: context-injector
+      type: inline
+      module: ~/.clooks/hooks/context.js
+      filter: "Write|Edit"
+```
+
+### Example Module
+
+```typescript
+// ~/.clooks/hooks/context.ts
+import type { HookInput } from '@mauribadnights/clooks';
+
+export default async function(input: HookInput) {
+  const toolName = input.tool_name ?? 'unknown';
+  const cwd = input.cwd;
+
+  // Return value becomes handler output
+  return {
+    additionalContext: `Tool ${toolName} executing in ${cwd}`
+  };
+}
+```
+
+> **Note:** The module must have a default export that is a function. If the export is missing or not a function, the handler fails with an error message identifying the module.
+
+## LLM Handlers
+
+LLM handlers call the Anthropic Messages API with prompt templates. They require no scripts -- the prompt is defined directly in the manifest.
+
+### How They Work
+
+1. The handler's `prompt` template is rendered by replacing `$VARIABLES` with actual values.
+2. The rendered prompt is sent to the Anthropic API using the specified `model`.
+3. The response text is returned as `{"additionalContext": "..."}`.
+
+### Required Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `model` | string | `claude-haiku-4-5`, `claude-sonnet-4-6`, or `claude-opus-4-6` |
+| `prompt` | string | Prompt template with `$VARIABLE` interpolation |
+
+### Optional Fields
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `maxTokens` | number | 1024 | Maximum tokens in the API response |
+| `temperature` | number | 1.0 | Sampling temperature |
+| `batchGroup` | string | — | Group ID for batching multiple handlers into one API call |
+
+### Default Timeout
+
+30000ms. Override with the `timeout` field.
+
+### Prompt Variables
+
+| Variable | Source |
+|----------|--------|
+| `$TRANSCRIPT` | Session transcript (requires `transcript` in prefetch) |
+| `$GIT_STATUS` | `git status --porcelain` (requires `git_status` in prefetch) |
+| `$GIT_DIFF` | `git diff --stat` (requires `git_diff` in prefetch) |
+| `$ARGUMENTS` | JSON-serialized `tool_input` (PreToolUse/PostToolUse) |
+| `$TOOL_NAME` | Tool name (PreToolUse/PostToolUse) |
+| `$PROMPT` | User prompt text (UserPromptSubmit) |
+| `$CWD` | Current working directory |
+
+### Example Configuration
+
+```yaml
+prefetch:
+  - git_status
+
+handlers:
+  PreToolUse:
+    - id: code-reviewer
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Review this tool call for potential issues.
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+        Git status: $GIT_STATUS
+
+        If there is a problem, explain it briefly. Otherwise say "Looks good."
+      filter: "Write|Edit"
+      maxTokens: 256
+```
+
+See [LLM Handlers](llm-handlers.md) for batching, cost tracking, and advanced usage.
+
+## Handler Output Format
+
+Handlers communicate back to Claude Code through their output. There are two primary output shapes.
+
+### Adding Context
+
+Return an `additionalContext` string to inject information into Claude's context window:
+
+```json
+{
+  "additionalContext": "Information to inject into Claude's context"
+}
+```
+
+This is the most common output. Claude sees this text as additional context when deciding its next action.
+
+### Blocking a Tool (PreToolUse only)
+
+PreToolUse handlers can block a tool call by returning a `decision` of `"block"`:
+
+```json
+{
+  "decision": "block",
+  "reason": "This operation is not allowed because..."
+}
+```
+
+When a handler blocks a tool, Claude receives the reason and must find an alternative approach. Multiple handlers can run for the same event -- if any handler blocks, the tool is blocked.
+
+### No Output
+
+Returning nothing (empty stdout for scripts, `undefined` for inline) is valid. The handler is recorded as successful with no output.
+
+## Auto-Disable
+
+Handlers that fail repeatedly are automatically disabled to prevent cascading problems:
+
+- After **3 consecutive failures**, the handler is marked as disabled.
+- Disabled handlers are skipped on subsequent invocations (logged as auto-disabled).
+- State is tracked per handler ID in memory.
+
+To re-enable a disabled handler:
+
+- **Edit the manifest** -- any manifest reload resets state for changed handlers.
+- **Use `sessionIsolation: true`** -- state resets automatically on every `SessionStart` event.
+- **Restart the daemon** -- `clooks restart` clears all in-memory state.
+
+Check current handler status with `clooks stats`, which shows error counts and disabled state per handler.
+
+---
+
+[Home](../index.md) | [Prev: Manifest](manifest.md) | [Next: LLM Handlers](llm-handlers.md)