@mauribadnights/clooks 0.5.1 → 0.5.2

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)

package/docs/guides/llm-handlers.md

@@ -0,0 +1,145 @@
+# LLM Handlers
+
+LLM handlers call the Anthropic Messages API directly from the manifest, with prompt templates, automatic batching, and cost tracking. This guide covers advanced usage beyond the basics in [Handlers](handlers.md).
+
+## Basics
+
+LLM handlers require an Anthropic API key. Provide it in one of two ways:
+
+1. **Environment variable:** `ANTHROPIC_API_KEY=sk-ant-...`
+2. **Manifest setting:** `settings.anthropicApiKey: sk-ant-...`
+
+The Anthropic SDK is lazy-loaded on the first LLM handler invocation. If the SDK is not installed, the handler fails with an actionable error message.
+
+### Supported Models
+
+| Model | Best For |
+|-------|----------|
+| `claude-haiku-4-5` | Fast, cheap checks (guards, simple reviews) |
+| `claude-sonnet-4-6` | Balanced analysis (code review, context synthesis) |
+| `claude-opus-4-6` | Deep reasoning (security audits, architecture review) |
+
+## Prompt Templates
+
+Prompts support `$VARIABLE` interpolation. Variables are replaced with actual values before the API call.
+
+| Variable | Requires Prefetch | Source |
+|----------|-------------------|--------|
+| `$TRANSCRIPT` | Yes (`transcript`) | Session transcript, last 50KB |
+| `$GIT_STATUS` | Yes (`git_status`) | `git status --porcelain` output |
+| `$GIT_DIFF` | Yes (`git_diff`) | `git diff --stat` output, max 20KB |
+| `$ARGUMENTS` | No | JSON-serialized `tool_input` (PreToolUse/PostToolUse) |
+| `$TOOL_NAME` | No | Tool name string (PreToolUse/PostToolUse) |
+| `$PROMPT` | No | User prompt text (UserPromptSubmit) |
+| `$CWD` | No | Current working directory |
+
+Variables that require prefetch will resolve to an empty string if the corresponding prefetch key is not listed in the manifest's `prefetch` array.
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+
+handlers:
+  PreToolUse:
+    - id: reviewer
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        You are reviewing a tool call in a Claude Code session.
+
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+        Working directory: $CWD
+        Git status: $GIT_STATUS
+
+        Flag any issues. Be concise.
+```
+
+## Batching
+
+Handlers with the same `batchGroup` value that fire on the same event are combined into a single API call. This reduces latency and cost when multiple LLM handlers need to analyze the same context.
+
+### How It Works
+
+1. Handlers sharing a `batchGroup` are collected.
+2. Their prompts are rendered individually, then combined into a structured multi-task prompt.
+3. A single API call is made. The model is instructed to return a JSON object keyed by handler ID.
+4. The response is parsed and each handler receives its portion of the result.
+5. Token usage and cost are split evenly across group members.
+
+### Scoping
+
+Batch groups are scoped by `session_id`. Two different Claude Code sessions firing the same batch group at the same time will produce separate API calls. There is no cross-session contamination.
+
+### Edge Cases
+
+- **Single-handler groups:** If a batch group contains only one handler, it falls through to individual execution (no batching overhead).
+- **Mixed models:** If handlers in a group specify different models, the first handler's model is used and a warning is logged.
+- **JSON parse failure:** If the batched response is not valid JSON, all handlers in the group receive the raw text as `additionalContext`.
+
+### Example
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: security-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Check this tool call for security issues:
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+      batchGroup: pre-tool-review
+      filter: "Write|Bash"
+
+    - id: style-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Check if this tool call follows project conventions:
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+      batchGroup: pre-tool-review
+      filter: "Write|Bash"
+```
+
+Both handlers fire on the same `PreToolUse` event with the same `batchGroup`. clooks combines them into one API call, halving latency and cost compared to two separate calls.
+
+## Cost Tracking
+
+All LLM handler invocations are logged to `~/.clooks/costs.jsonl`. Each entry records the timestamp, event, handler ID, model, token usage, cost in USD, and whether the call was batched.
+
+View cost data with:
+
+```bash
+clooks costs
+```
+
+### Pricing
+
+Pricing per million tokens (as of March 2026):
+
+| Model | Input | Output |
+|-------|-------|--------|
+| `claude-haiku-4-5` | $0.80 | $4.00 |
+| `claude-sonnet-4-6` | $3.00 | $15.00 |
+| `claude-opus-4-6` | $15.00 | $75.00 |
+
+For batched calls, the total token cost is split evenly across all handlers in the group.
+
+## Best Practices
+
+**Use Haiku for simple checks.** Guards, keyword detection, and light reviews run well on Haiku at a fraction of the cost. Reserve Sonnet and Opus for tasks that require deeper reasoning.
+
+**Use batchGroup to combine related analyses.** If two handlers analyze the same tool call from different angles, batching them saves an API round-trip and reduces total tokens (the shared context is sent once).
+
+**Set maxTokens conservatively.** Most handler responses are short. Setting `maxTokens: 256` or `maxTokens: 512` prevents runaway token usage on verbose responses.
+
+**Use filter to avoid unnecessary API calls.** An LLM handler without a filter fires on every matching event. Adding `filter: "Write|Edit"` ensures the API is only called when relevant tools are invoked.
+
+**Prefer prefetch over inline context.** If your prompt needs git status or the transcript, add the key to `prefetch` rather than running shell commands in a script handler. Prefetched data is fetched once and shared across all handlers.
+
+---
+
+[Home](../index.md) | [Prev: Handlers](handlers.md) | [Next: Filtering](filtering.md)

package/docs/guides/manifest.md

@@ -0,0 +1,237 @@
+# Manifest Reference
+
+The manifest file (`~/.clooks/manifest.yaml`) is the single configuration source for the clooks daemon. It defines which handlers run, when they fire, and how the daemon behaves.
+
+## Structure
+
+A manifest has three top-level sections:
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+  - git_diff
+
+handlers:
+  EventName:
+    - id: handler-id
+      type: script|inline|llm
+      # ...type-specific and shared fields
+
+settings:
+  port: 7890
+  logLevel: info
+  authToken: token
+  anthropicApiKey: sk-...
+```
+
+All sections are optional. A minimal manifest needs only a `handlers` block with at least one event and one handler.
+
+## Settings
+
+Global daemon configuration lives under `settings`:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `port` | number | 7890 | HTTP server port (1-65535) |
+| `logLevel` | string | `"info"` | Log verbosity: `debug`, `info`, `warn`, `error` |
+| `authToken` | string | — | Bearer token for HTTP authentication. Auto-generated by `clooks init` |
+| `anthropicApiKey` | string | — | Anthropic API key. Alternative to setting the `ANTHROPIC_API_KEY` env var |
+
+```yaml
+settings:
+  port: 7890
+  logLevel: info
+  authToken: clooks_a1b2c3d4e5f6
+```
+
+## Prefetch
+
+The `prefetch` array declares context that should be fetched once per hook invocation and shared across all handlers. This avoids redundant work when multiple handlers need the same data.
+
+| Key | Description | Size Limit |
+|-----|-------------|------------|
+| `transcript` | Last portion of the session transcript file | 50KB (tail) |
+| `git_status` | Output of `git status --porcelain` in the session's cwd | — |
+| `git_diff` | Output of `git diff --no-ext-diff --stat` in the session's cwd | 20KB (truncated) |
+
+Prefetched data is available to LLM handler prompts as template variables: `$TRANSCRIPT`, `$GIT_STATUS`, `$GIT_DIFF`. Each key is fetched independently — a failure in one does not block the others.
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+```
+
+## Handler Events
+
+Handlers are grouped by the Claude Code hook event they respond to. clooks supports all 9 events:
+
+| Event | When It Fires |
+|-------|---------------|
+| `SessionStart` | A new Claude Code session begins |
+| `UserPromptSubmit` | The user submits a prompt |
+| `PreToolUse` | Before Claude executes a tool |
+| `PostToolUse` | After a tool finishes executing |
+| `Stop` | Claude finishes its response |
+| `SubagentStart` | A subagent session starts |
+| `SubagentStop` | A subagent session ends |
+| `Notification` | Claude sends a notification |
+| `ConfigChange` | Claude Code configuration changes |
+
+See [Hook Events Reference](../reference/hook-events.md) for full payload documentation per event.
+
+Each event key contains an array of handler definitions:
+
+```yaml
+handlers:
+  PreToolUse:
+    - id: first-handler
+      type: script
+      command: "node ~/hooks/check.js"
+    - id: second-handler
+      type: llm
+      model: claude-haiku-4-5
+      prompt: "Review this tool call: $TOOL_NAME"
+```
+
+## Shared Handler Fields
+
+Every handler, regardless of type, supports these fields:
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `id` | string | required | Unique identifier across the entire manifest |
+| `type` | string | required | `script`, `inline`, or `llm` |
+| `enabled` | boolean | `true` | Toggle handler without removing it from the manifest |
+| `filter` | string | — | Keyword filter applied to hook input. See [Filtering](filtering.md) |
+| `timeout` | number | 5000 / 30000 | Milliseconds before handler is killed. Default is 5000ms for script/inline, 30000ms for LLM |
+| `async` | boolean | `false` | Fire-and-forget execution. See [Async Handlers](async-handlers.md) |
+| `depends` | string[] | — | Handler IDs this handler must wait for. See [Dependencies](dependencies.md) |
+| `sessionIsolation` | boolean | `false` | Reset handler state (error counts, auto-disable) on every `SessionStart` |
+| `agent` | string | — | Comma-separated agent names. Only fires in matching sessions. See [Filtering](filtering.md) |
+| `project` | string | — | Glob pattern matched against session cwd. See [Filtering](filtering.md) |
+
+Type-specific fields are covered in [Handlers](handlers.md).
+
+## Hot Reload
+
+The daemon watches `manifest.yaml` for filesystem changes. When the file is saved:
+
+1. The new manifest is parsed and validated.
+2. Handler lists are diffed against the previous version.
+3. State for removed handlers is cleaned up.
+4. Handlers with `sessionIsolation: true` that changed are reset.
+5. The new handler set becomes active immediately.
+
+No daemon restart is needed. Invalid manifests are rejected and the previous configuration continues running. Changes are logged at the `info` level.
+
+## Validation
+
+Run `clooks doctor` to validate your manifest structure. The validator enforces:
+
+- The `handlers` key must be an object.
+- Each event key must be a valid hook event name (`SessionStart`, `PreToolUse`, etc.).
+- Each event must contain an array of handler objects.
+- Every handler must have a string `id` and a valid `type`.
+- Handler IDs must be unique across the entire manifest (not just within an event).
+- Script handlers must have a `command` field.
+- Inline handlers must have a `module` field.
+- LLM handlers must have both `model` and `prompt` fields. Model must be one of: `claude-haiku-4-5`, `claude-sonnet-4-6`, `claude-opus-4-6`.
+- `prefetch` must be an array containing only valid keys: `transcript`, `git_status`, `git_diff`.
+- `settings.port` must be a number between 1 and 65535.
+- `settings.logLevel` must be one of: `debug`, `info`, `warn`, `error`.
+
+Invalid manifests produce specific error messages identifying the problem. For example:
+
+```
+Error: Unknown hook event: "PreTool". Valid events: SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop, SubagentStart, SubagentStop, Notification, ConfigChange
+```
+
+```
+Error: Duplicate handler id: "my-guard"
+```
+
+## Complete Example
+
+```yaml
+prefetch:
+  - transcript
+  - git_status
+  - git_diff
+
+handlers:
+  SessionStart:
+    - id: check-update
+      type: script
+      command: "node ~/.clooks/hooks/check-update.js"
+      timeout: 6000
+
+  UserPromptSubmit:
+    - id: prompt-logger
+      type: inline
+      module: ~/.clooks/hooks/log-prompt.js
+      async: true
+
+  PreToolUse:
+    - id: bash-guard
+      type: script
+      command: "node ~/.clooks/hooks/bash-guard.js"
+      filter: "Bash"
+      timeout: 3000
+
+    - id: write-review
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Review this file write for potential issues:
+        Tool: $TOOL_NAME
+        Arguments: $ARGUMENTS
+        Git status: $GIT_STATUS
+      filter: "Write"
+      batchGroup: code-review
+
+    - id: style-check
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Check if this write follows project style conventions:
+        $ARGUMENTS
+      filter: "Write"
+      batchGroup: code-review
+      depends: []
+
+    - id: deep-analysis
+      type: llm
+      model: claude-sonnet-4-6
+      prompt: |
+        Perform deep security and correctness review:
+        $ARGUMENTS
+        Context from prior checks available in input.
+      depends: [write-review, style-check]
+      filter: "Write"
+
+  PostToolUse:
+    - id: metrics-collector
+      type: inline
+      module: ~/.clooks/hooks/metrics.js
+      async: true
+
+  Stop:
+    - id: session-summary
+      type: llm
+      model: claude-haiku-4-5
+      prompt: |
+        Summarize what was accomplished in this session:
+        $TRANSCRIPT
+      maxTokens: 512
+
+settings:
+  port: 7890
+  logLevel: info
+  authToken: clooks_a1b2c3d4e5f6
+```
+
+---
+
+[Home](../index.md) | [Prev: Migration](../getting-started/migration.md) | [Next: Handlers](handlers.md)

package/docs/guides/short-circuit.md

@@ -0,0 +1,31 @@
+# Short-Circuit
+
+## Overview
+
+When a PreToolUse handler blocks a tool call (returns `decision: "block"`), clooks automatically skips PostToolUse handlers for that same tool. This prevents wasted execution on tools that were already denied.
+
+## How It Works
+
+1. PreToolUse handler returns `{ decision: "block", reason: "..." }`
+2. Server records denial in an in-memory DenyCache, keyed by `session_id:tool_name`
+3. When PostToolUse fires for the same session + tool, clooks checks the DenyCache
+4. If denied: PostToolUse handlers are skipped entirely
+5. Cache entries expire after 30 seconds (prevents memory leaks)
+
+## Configuration
+
+This is automatic — no configuration needed. It works for all PreToolUse handlers that return a `block` decision.
+
+The server also checks for `hookSpecificOutput.permissionDecision: "deny"` as an alternative denial signal.
+
+## Cache Lifecycle
+
+- Entries auto-expire after 30 seconds
+- Periodic cleanup runs every 60 seconds
+- Cache is in-memory only — cleared on daemon restart
+
+> **Note:** The 30-second TTL is deliberately short. It only needs to survive long enough for the matching PostToolUse event to arrive, which typically happens within milliseconds of the PreToolUse denial.
+
+---
+
+[Home](../index.md) | [Prev: Async Handlers](async-handlers.md) | [Next: System Service](system-service.md)