@mauribadnights/clooks 0.3.2 → 0.4.1

package/dist/types.d.ts

@@ -11,6 +11,7 @@ export interface HookInput {
     tool_name?: string;
     tool_input?: Record<string, unknown>;
     source?: string;
+    agent_type?: string;
     stop_hook_active?: boolean;
     [key: string]: unknown;
 }
@@ -32,6 +33,9 @@ export interface LLMHandlerConfig {
     enabled?: boolean;
     sessionIsolation?: boolean;
     depends?: string[];
+    async?: boolean;
+    agent?: string;
+    project?: string;
 }
 /** Script handler config */
 export interface ScriptHandlerConfig {
@@ -43,6 +47,9 @@ export interface ScriptHandlerConfig {
     enabled?: boolean;
     sessionIsolation?: boolean;
     depends?: string[];
+    async?: boolean;
+    agent?: string;
+    project?: string;
 }
 /** Inline handler config */
 export interface InlineHandlerConfig {
@@ -54,6 +61,9 @@ export interface InlineHandlerConfig {
     enabled?: boolean;
     sessionIsolation?: boolean;
     depends?: string[];
+    async?: boolean;
+    agent?: string;
+    project?: string;
 }
 /** Union of all handler configs */
 export type HandlerConfig = ScriptHandlerConfig | InlineHandlerConfig | LLMHandlerConfig;
@@ -103,6 +113,7 @@ export interface MetricEntry {
     usage?: TokenUsage;
     cost_usd?: number;
     session_id?: string;
+    agent_type?: string;
 }
 /** Extended handler result with cost info */
 export interface HandlerResult {

package/docs/DASHBOARD-VISION.md

@@ -0,0 +1,66 @@
+# Dashboard Vision — Visual Hook Manager
+
+> **Status:** Future feature idea — NOT to be implemented now.
+> **Target version:** v0.4 or later, after the plugin ecosystem (v0.3) is in place.
+
+## Overview
+
+A web-based dashboard (accessible at `localhost:7890/dashboard` or similar) that provides a graphical interface for creating, configuring, and monitoring hooks — no YAML editing required.
+
+## Hook Builder UI
+
+The core feature: a visual hook creator.
+
+### Event Selection
+
+- Dropdown to select the hook event: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, etc.
+- Visual explanation of when each event fires and how often
+
+### Handler Type
+
+- Dropdown: **Script**, **Inline**, **LLM** (v0.2+)
+- Each type shows its relevant configuration fields dynamically
+
+### Configuration
+
+- **Script handlers**: text field for the command, timeout slider, enable/disable toggle
+- **LLM handlers**: model selector dropdown (Haiku/Sonnet/Opus), prompt textarea with syntax highlighting, temperature slider, max tokens input, batch group selector
+- **Inline handlers**: file picker for the JS module
+
+### Pre-built Actions (Quick Hooks)
+
+Predefined hook templates users can enable with one click:
+
+| Quick Hook | Description |
+|---|---|
+| Auto-commit on Stop | Commits staged changes when Claude stops |
+| Dangerous command guard | Blocks `rm -rf`, `git push --force` on PreToolUse |
+| Session logger | Records session start/stop times |
+| Cost tracker | Monitors LLM usage across hooks |
+| Context warning | Alerts when context window is running low |
+| Custom | Blank template to build your own |
+
+### Filter Configuration
+
+- Visual filter builder: keyword chips, include/exclude toggle
+- Preview: shows sample inputs and whether the filter would match
+
+## Monitoring Dashboard
+
+- Real-time view of hook fires, handler execution times, errors
+- Per-handler graphs (fires over time, latency distribution)
+- LLM cost tracker with daily/weekly charts
+- Health status of all handlers (green/yellow/red)
+
+## Manifest Sync
+
+- Dashboard reads and writes `~/.clooks/manifest.yaml`
+- Changes are live-reloaded by the daemon (no restart needed)
+- Shows diff of pending changes before applying
+- Version history of manifest changes
+
+## Technology
+
+- Served by the clooks daemon itself (add routes to existing HTTP server)
+- Frontend: lightweight — could be vanilla HTML/CSS/JS or a small framework like Preact
+- No build step for the dashboard — serve static files from a `dashboard/` directory

package/docs/DEFERRED-FIXES.md

@@ -0,0 +1,35 @@
+# Deferred Fixes (Historical)
+
+> **All issues in this document were resolved in v0.3.0. This file is kept for historical reference.**
+
+These issues were identified in the v0.2.1 audit and deferred to v0.3.0.
+
+## Session Isolation + LLM Batching Violation -- RESOLVED
+
+**Problem:** Two concurrent sessions with handlers sharing a `batchGroup` would batch together into one API call, violating session isolation guarantees.
+
+**Resolution:** Batch groups are now scoped to `{batchGroup}:{session_id}`. Session ID is passed into `executeLLMHandlersBatched()` and plugins can declare batch groups as session-scoped or global.
+
+## Auth Token Rotation -- RESOLVED
+
+**Problem:** Token was generated once at `clooks init` with no expiration or revocation mechanism.
+
+**Resolution:** `clooks rotate-token` generates a new token, updates manifest and settings.json, and hot-reloads the daemon without restart.
+
+## Manifest Reload Doesn't Trigger Session Reset -- RESOLVED
+
+**Problem:** File watcher reloaded manifest but didn't reset session-isolated handler state.
+
+**Resolution:** Manifest reload now diffs old vs new handlers. New handlers get fresh state, removed handlers get cleaned up, and changed handlers with `sessionIsolation: true` are reset.
+
+## Health Endpoint Auth -- RESOLVED
+
+**Problem:** `/health` bypassed auth, exposing operational details to unauthenticated clients.
+
+**Resolution:** Split into `/health` (public, returns `{ status: "ok" }` only) and `/health/detail` (authenticated, returns uptime, handler count, plugin list).
+
+## Rate Limiting on Auth Failures -- RESOLVED
+
+**Problem:** Failed auth attempts were logged but not throttled.
+
+**Resolution:** In-memory rate limiter rejects with 429 after repeated failed auth attempts within a time window. Resets on successful auth.

package/docs/generate-diagram.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Generate clooks architecture diagram as PNG using matplotlib."""
+
+import matplotlib.pyplot as plt
+import matplotlib.patches as patches
+from pathlib import Path
+
+# --- Colors ---
+BG = "#FFFFFF"
+CLR_CLAUDE_FILL = "#E8F0FE"
+CLR_CLAUDE_EDGE = "#4285F4"
+CLR_DAEMON_FILL = "#F3E8FF"
+CLR_DAEMON_EDGE = "#7C3AED"
+CLR_SCRIPT_FILL = "#FFF7ED"
+CLR_SCRIPT_EDGE = "#EA580C"
+CLR_INLINE_FILL = "#ECFDF5"
+CLR_INLINE_EDGE = "#059669"
+CLR_LLM_FILL = "#FFF1F2"
+CLR_LLM_EDGE = "#E11D48"
+CLR_ARROW = "#475569"
+CLR_TEXT = "#1E293B"
+CLR_DIM = "#64748B"
+CLR_ACCENT = "#7C3AED"
+
+FONT = "sans-serif"
+
+
+def rounded_box(ax, x, y, w, h, facecolor, edgecolor, lw=1.8):
+    """Draw a FancyBboxPatch and return it."""
+    rect = patches.FancyBboxPatch(
+        (x, y), w, h,
+        boxstyle="round,pad=0.12",
+        facecolor=facecolor,
+        edgecolor=edgecolor,
+        linewidth=lw,
+    )
+    ax.add_patch(rect)
+    return rect
+
+
+def arrow(ax, x1, y1, x2, y2, label=None, label_offset_y=0.18, color=CLR_ARROW):
+    """Draw an arrow with optional centered label."""
+    ax.annotate(
+        "", xy=(x2, y2), xytext=(x1, y1),
+        arrowprops=dict(
+            arrowstyle="->,head_width=0.25,head_length=0.12",
+            color=color, lw=1.6, connectionstyle="arc3,rad=0",
+        ),
+    )
+    if label:
+        mx = (x1 + x2) / 2
+        my = (y1 + y2) / 2 + label_offset_y
+        ax.text(mx, my, label, ha="center", va="center",
+                fontsize=9, color=CLR_DIM, family=FONT,
+                bbox=dict(boxstyle="round,pad=0.2", facecolor="white",
+                          edgecolor="#E2E8F0", linewidth=0.8, alpha=0.95))
+
+
+def main():
+    fig, ax = plt.subplots(figsize=(14, 6))
+    ax.set_xlim(0, 14)
+    ax.set_ylim(0, 6)
+    ax.set_aspect("equal")
+    ax.axis("off")
+    fig.patch.set_facecolor(BG)
+
+    # ── Title ──
+    ax.text(7, 5.65, "clooks architecture", ha="center", va="center",
+            fontsize=15, fontweight="bold", color=CLR_TEXT, family=FONT)
+    ax.text(7, 5.35, "Persistent hook runtime for Claude Code",
+            ha="center", va="center", fontsize=9.5, color=CLR_DIM, family=FONT)
+
+    # =====================================================================
+    # COLUMN 1 — Claude Code (left)
+    # =====================================================================
+    cx, cy, cw, ch = 0.4, 1.4, 2.8, 3.6
+    rounded_box(ax, cx, cy, cw, ch, CLR_CLAUDE_FILL, CLR_CLAUDE_EDGE)
+
+    ax.text(cx + cw / 2, cy + ch - 0.35, "Claude Code",
+            ha="center", va="center", fontsize=12, fontweight="bold",
+            color=CLR_CLAUDE_EDGE, family=FONT)
+
+    ax.text(cx + cw / 2, cy + ch - 0.75, "Hook Events:",
+            ha="center", va="center", fontsize=9, color=CLR_DIM, family=FONT)
+
+    events = ["SessionStart", "UserPromptSubmit", "PreToolUse", "PostToolUse", "Stop"]
+    for i, ev in enumerate(events):
+        ax.text(cx + cw / 2, cy + ch - 1.15 - i * 0.42, ev,
+                ha="center", va="center", fontsize=8.5, color=CLR_TEXT,
+                family="monospace")
+
+    # =====================================================================
+    # COLUMN 2 — clooks daemon (center)
+    # =====================================================================
+    dx, dy, dw, dh = 5.2, 1.0, 3.4, 4.0
+    rounded_box(ax, dx, dy, dw, dh, CLR_DAEMON_FILL, CLR_DAEMON_EDGE)
+
+    ax.text(dx + dw / 2, dy + dh - 0.35, "clooks daemon",
+            ha="center", va="center", fontsize=12, fontweight="bold",
+            color=CLR_DAEMON_EDGE, family=FONT)
+
+    ax.text(dx + dw / 2, dy + dh - 0.72, "localhost:7890",
+            ha="center", va="center", fontsize=9, color=CLR_DIM,
+            family="monospace")
+
+    features = ["Router", "Prefetch", "Dep Resolution", "Metrics", "Circuit Breaker"]
+    bullet_x = dx + 0.5
+    for i, feat in enumerate(features):
+        fy = dy + dh - 1.2 - i * 0.42
+        ax.text(bullet_x, fy, "\u2022  " + feat,
+                ha="left", va="center", fontsize=8.5, color=CLR_TEXT,
+                family=FONT)
+
+    # =====================================================================
+    # COLUMN 3 — Handler boxes (right)
+    # =====================================================================
+    hx, hw, hh = 10.2, 3.2, 0.9
+    handler_gap = 1.2
+
+    handlers = [
+        ("Script Handler", "~5\u201335 ms", CLR_SCRIPT_FILL, CLR_SCRIPT_EDGE),
+        ("Inline Handler", "<1 ms", CLR_INLINE_FILL, CLR_INLINE_EDGE),
+        ("LLM Handler", "API call", CLR_LLM_FILL, CLR_LLM_EDGE),
+    ]
+
+    # Position handlers: top one aligns near daemon top, stack downward
+    top_handler_y = 3.8
+    handler_centers = []
+
+    for i, (label, timing, fill, edge) in enumerate(handlers):
+        hy = top_handler_y - i * handler_gap
+        rounded_box(ax, hx, hy, hw, hh, fill, edge)
+        ax.text(hx + hw / 2, hy + hh / 2 + 0.12, label,
+                ha="center", va="center", fontsize=10.5, fontweight="bold",
+                color=edge, family=FONT)
+        ax.text(hx + hw / 2, hy + hh / 2 - 0.2, timing,
+                ha="center", va="center", fontsize=8.5, color=CLR_DIM,
+                family="monospace")
+        handler_centers.append(hy + hh / 2)
+
+    # =====================================================================
+    # ARROWS
+    # =====================================================================
+
+    # Claude Code -> Daemon  (horizontal, at midpoint)
+    mid_y = cy + ch / 2
+    arrow(ax, cx + cw, mid_y, dx, mid_y, label="HTTP POST", label_offset_y=0.22)
+
+    # Daemon -> each Handler
+    daemon_right_x = dx + dw
+    for hc_y in handler_centers:
+        arrow(ax, daemon_right_x, hc_y, hx, hc_y)
+
+    # Daemon -> Claude Code return arrow (below the forward arrow)
+    return_y = mid_y - 0.55
+    arrow(ax, dx, return_y, cx + cw, return_y,
+          label="JSON response", label_offset_y=-0.25, color="#94A3B8")
+
+    # =====================================================================
+    # FOOTNOTE — bootstrap note
+    # =====================================================================
+    ax.text(7, 0.35, 'SessionStart fires "clooks ensure-running" to bootstrap daemon',
+            ha="center", va="center", fontsize=8.5, color=CLR_DIM, family=FONT,
+            style="italic",
+            bbox=dict(boxstyle="round,pad=0.3", facecolor="#F8FAFC",
+                      edgecolor="#E2E8F0", linewidth=0.8))
+
+    # ── Save ──
+    out_path = Path(__file__).parent / "architecture.png"
+    fig.savefig(out_path, dpi=300, bbox_inches="tight",
+                facecolor=BG, edgecolor="none")
+    plt.close(fig)
+    print(f"Saved: {out_path}  ({out_path.stat().st_size / 1024:.0f} KB)")
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mauribadnights/clooks",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Persistent hook runtime for Claude Code — eliminates process spawning overhead and gives you observability",
   "bin": {
     "clooks": "./dist/cli.js"
@@ -32,7 +32,9 @@
   },
   "files": [
     "dist",
+    "docs",
     "hooks",
+    "agents",
     "README.md",
     "LICENSE"
   ],