claudeye 1.0.7 → 1.0.8

package/README.md

@@ -160,7 +160,7 @@ claudeye --remove-hooks
 
 Selection is saved to `~/.claudeye/hooks-config.json`. In non-TTY environments (CI/piped), the 11 default policies are used automatically. Re-running `--install-hooks` re-opens the selector with your current choices pre-loaded.
 
-> **Web UI** — You can also toggle individual policies on/off from the **Hooks → Policies** tab in the Claudeye dashboard without re-running the CLI. Changes take effect immediately for the next hook invocation.
+> **Web UI** — You can also toggle individual policies on/off from the **Policies** page in the Claudeye dashboard without re-running the CLI. Changes take effect immediately for the next hook invocation.
 
 ### Scoped Installation
 
@@ -217,6 +217,119 @@ claudeye --list-hooks --cwd /path/to/project
 
 **Avoid installing hooks in multiple scopes for the same project.** Claude Code merges settings from all scopes, so duplicate hooks may cause the same policy to evaluate twice. If `--list-hooks` shows hooks in multiple scopes, remove the extra installation with `--remove-hooks --scope <scope>`.
 
+### Policy Params
+
+Tune builtin policies without replacing them. Add a `policyParams` key to any `.claudeye/hooks-config.json` file:
+
+```json
+{
+  "enabledPolicies": ["block-sudo", "block-push-master", "warn-large-file-write"],
+  "policyParams": {
+    "block-sudo": {
+      "allowPatterns": ["sudo systemctl status *", "sudo journalctl *"]
+    },
+    "block-push-master": {
+      "protectedBranches": ["main", "master", "release"]
+    },
+    "warn-large-file-write": {
+      "thresholdKb": 512
+    }
+  }
+}
+```
+
+Config files are read from three scopes in priority order (first wins for params):
+1. `{cwd}/.claudeye/hooks-config.json` — project (can be committed)
+2. `{cwd}/.claudeye/hooks-config.local.json` — local (gitignore this)
+3. `~/.claudeye/hooks-config.json` — global (managed by `--install-hooks`)
+
+`enabledPolicies` are unioned across all three scopes.
+
+| Policy | Param | Type | Default | Description |
+|---|---|---|---|---|
+| `block-sudo` | `allowPatterns` | `string[]` | `[]` | Token-matched patterns to allow (e.g. `"sudo systemctl *"`) |
+| `block-rm-rf` | `allowPaths` | `string[]` | `[]` | Paths exempt from catastrophic-deletion blocking |
+| `block-read-outside-cwd` | `allowPaths` | `string[]` | `[]` | Paths outside cwd allowed for reading |
+| `block-push-master` | `protectedBranches` | `string[]` | `["main","master"]` | Branch names blocked from `git push` |
+| `block-work-on-main` | `protectedBranches` | `string[]` | `["main","master"]` | Branch names blocked for commits/merges |
+| `sanitize-api-keys` | `additionalPatterns` | `{regex,label}[]` | `[]` | Extra credential patterns to redact from output |
+| `block-secrets-write` | `additionalPatterns` | `string[]` | `[]` | Extra filename substrings to block writing |
+| `warn-large-file-write` | `thresholdKb` | `number` | `1024` | Threshold in KB above which file writes warn |
+
+> **`allowPatterns` safety** — `block-sudo` matches patterns against **parsed argv tokens**, not the raw command string. This prevents shell injection bypass like `sudo systemctl status; rm -rf /` from matching the pattern `sudo systemctl status *`.
+
+> **Web UI** — Policy params can also be edited directly from the **Policies tab** in the dashboard. Click the gear icon next to any policy with configurable parameters to open the editor.
+
+### Custom Hooks
+
+Register arbitrary hook logic in a JavaScript file using the `custom` keyword with `--install-hooks`:
+
+```bash
+claudeye --install-hooks custom ./my-hooks.js
+```
+
+**`my-hooks.js`**:
+```js
+import { customPolicies, allow, deny, instruct } from "claudeye";
+
+customPolicies.add({
+  name: "block-production-writes",
+  description: "Prevent writes to production config files",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName === "Write") {
+      const path = ctx.toolInput?.file_path ?? "";
+      if (path.includes("production") || path.includes("prod.")) {
+        return deny("Writing to production config is blocked");
+      }
+    }
+    return allow();
+  },
+});
+```
+
+- **`ctx`** fields: `eventType`, `toolName`, `toolInput`, `payload`, `session`, `params`
+- **Return values**: `allow()`, `deny(message)`, `instruct(message)` — `deny(message)` is surfaced to Claude as `"Blocked by claudeye: <message>"`, consistent with builtin policy output
+- **Transitive imports**: files imported by your hooks entry point are automatically rewritten
+- **Fail-open**: any error or 10-second timeout returns `allow` and logs a warning — Claude is never blocked by a broken hook
+- **View loaded hooks**: `claudeye --list-hooks` shows a Custom Hooks section when a path is configured; the Policies tab in the dashboard shows each custom policy as a rich row with its name, description, and event scope (where defined), aligned with the built-in policy layout — edit the JS file to add, remove, or reorder them
+- **Remove**: `claudeye --remove-hooks custom` clears the path from global config
+- **Validation**: the file is loaded and validated at install time — if it has syntax errors, import failures, or registers no hooks, the install fails with an error and config is left unchanged
+
+**TypeScript types** (exported from `claudeye`):
+
+```ts
+interface PolicyContext {
+  eventType: string;
+  toolName?: string;
+  toolInput?: Record<string, unknown>;
+  payload: Record<string, unknown>;
+  session?: {
+    sessionId?: string;
+    transcriptPath?: string;
+    cwd?: string;
+    permissionMode?: string;
+    hookEventName?: string;
+  };
+  params?: Record<string, unknown>;
+}
+
+type PolicyDecision = "allow" | "deny" | "instruct";
+
+interface PolicyResult {
+  decision: PolicyDecision;
+  reason?: string;
+  message?: string;
+}
+
+interface CustomHook {
+  name: string;
+  description?: string;
+  match?: { events?: HookEventType[] };
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+}
+```
+
 ### LLM-Powered Policies
 
 Some policies (like `verify-intent`) use an external LLM to make intelligent decisions. These require a one-time configuration of an OpenAI-compatible API provider.
@@ -271,7 +384,7 @@ claudeye --install-hooks verify-intent
 
 ### Hook Activity Dashboard
 
-Every policy evaluation is logged to `~/.claudeye/cache/hook-activity/` and displayed at `/hooks` in the dashboard. You can filter by decision (allow/deny), event type, and policy name — with pagination and auto-refresh.
+Every policy evaluation is logged to `~/.claudeye/cache/hook-activity/` and displayed at `/policies` in the dashboard. You can filter by decision (allow/deny), event type, and policy name — with pagination and auto-refresh.
 
 Deny events are also reported to anonymous telemetry (if enabled) so you can track how often policies fire across machines.
 
@@ -390,7 +503,7 @@ The hook response format (`hookSpecificOutput` with `permissionDecision` and `pe
 
 #### Verification
 
-After installing hooks and configuring `setting_sources`, you can verify by checking the `/hooks` activity dashboard. Both Claude Code and Agent SDK hook events appear in the same activity log.
+After installing hooks and configuring `setting_sources`, you can verify by checking the `/policies` activity dashboard. Both Claude Code and Agent SDK hook events appear in the same activity log.
 
 #### Common Pitfall
 
@@ -498,8 +611,8 @@ The free tier ships 13 built-in policies with more added in every update. For te
 | `--max-queue-items <num>` | Max items to enqueue per scan (0=unlimited) | `500` |
 | `--logging <level>` | Log level: `info`, `warn`, `error` (applies to dashboard server; hooks read `CLAUDEYE_LOG_LEVEL` env var) | `warn` |
 | `--disable-telemetry` | Disable anonymous usage analytics | enabled |
-| `--install-hooks [policies]` | Install hooks (interactive, or: `all`, `name1 name2 ...`) | - |
-| `--remove-hooks [policies]` | Remove hooks (all, or: `name1 name2 ...` to disable specific) | - |
+| `--install-hooks [policies\|custom <path>]` | Install hooks (interactive, or: `all`, `name1 name2 ...`, or `custom <path>` to register a custom hooks JS file) | - |
+| `--remove-hooks [policies\|custom]` | Remove hooks (all, or: `name1 name2 ...` to disable specific, or `custom` to clear the custom hooks path) | - |
 | `--list-hooks` | Show hook policies in a table with enabled status, descriptions, and a separate Beta section | - |
 | `--configure-llm` | Configure LLM provider for smart policies (interactive, or pass flags below) | - |
 | `--llm-api-key <key>` | API key for the LLM provider | - |
@@ -2398,6 +2511,7 @@ All views auto-refresh and self-hide when there's no queue activity.
 | `CLAUDEYE_QUEUE_MAX_ITEMS` | Max items to enqueue per scan (0=unlimited) | `500` |
 | `CLAUDEYE_LOG_LEVEL` | Log verbosity for both dashboard server and hook processes: `info`, `warn`, `error` | `warn` |
 | `CLAUDEYE_HOOK_LOG_FILE` | Enable hook file logging: `1` or `true` for default dir (`~/.claudeye/logs/`), or an absolute path for a custom directory | disabled |
+| `CLAUDEYE_DISABLE_PAGES` | Comma-separated pages to hide from nav and block direct access: `policies`, `dashboard`, `projects`. The first non-disabled page (policies → projects → dashboard) becomes the root `/` landing page. | unset |
 
 At `info` level, all log lines (including `ACTIVITY` lines for user actions) are emitted. At `warn` (default), only warnings and errors appear. At `error`, only errors are shown.
 

package/bin/claudeye.mjs

@@ -52,10 +52,15 @@ if (platform() !== "win32") {
   try { chmodSync(binPath, 0o755); } catch {}
 }
 
+// Tell the hook handler where to find dist/index.js (for custom hooks ESM shim)
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const distPath = join(__dirname, "..", "dist");
+
 // Exec the binary with --mode=cli and forward all args
 try {
   execFileSync(binPath, ["--mode=cli", ...process.argv.slice(2)], {
     stdio: "inherit",
+    env: { ...process.env, CLAUDEYE_DIST_PATH: distPath },
   });
 } catch (err) {
   // execFileSync throws on non-zero exit — exit with the same code

package/dist/index.d.ts

@@ -393,3 +393,59 @@ export interface ClaudeyeApp {
 export declare function createApp(): ClaudeyeApp;
 export declare function getQueueCondition(): { fn: ConditionFunction; cacheable: boolean } | null;
 export declare function clearQueueCondition(): void;
+
+// ── Hooks API ──────────────────────────────────────────────────────────────
+
+export type PolicyDecision = "allow" | "deny" | "instruct";
+
+export type HookEventType =
+  | "SessionStart"
+  | "SessionEnd"
+  | "UserPromptSubmit"
+  | "PreToolUse"
+  | "PostToolUse"
+  | "PostToolUseFailure"
+  | "PermissionRequest"
+  | "Notification"
+  | "SubagentStart"
+  | "SubagentStop"
+  | "Stop"
+  | "TeammateIdle"
+  | "TaskCompleted"
+  | "ConfigChange"
+  | "WorktreeCreate"
+  | "WorktreeRemove"
+  | "PreCompact";
+
+export interface PolicyResult {
+  decision: PolicyDecision;
+  reason?: string;
+  message?: string;
+}
+
+export interface PolicyContext {
+  eventType: string;
+  payload: Record<string, unknown>;
+  toolName?: string;
+  toolInput?: Record<string, unknown>;
+  session?: {
+    sessionId?: string;
+    transcriptPath?: string;
+    cwd?: string;
+    permissionMode?: string;
+    hookEventName?: string;
+  };
+  params?: Record<string, unknown>;
+}
+
+export interface CustomHook {
+  name: string;
+  description?: string;
+  match?: { events?: HookEventType[] };
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+}
+
+export declare const customPolicies: { add(hook: CustomHook): void };
+export declare function allow(): PolicyResult;
+export declare function deny(reason: string): PolicyResult;
+export declare function instruct(reason: string): PolicyResult;

package/dist/index.js

@@ -463,8 +463,39 @@ function createApp() {
   return app;
 }
 
+// ── Hooks API ──────────────────────────────────────────────────────────────
+
+const CUSTOM_HOOKS_KEY = "__claudeye_custom_hooks__";
+
+function getHooksRegistry() {
+  if (!Array.isArray(globalThis[CUSTOM_HOOKS_KEY])) globalThis[CUSTOM_HOOKS_KEY] = [];
+  return globalThis[CUSTOM_HOOKS_KEY];
+}
+
+const customPolicies = {
+  add(hook) {
+    getHooksRegistry().push(hook);
+  },
+};
+
+function allow() {
+  return { decision: "allow" };
+}
+
+function deny(reason) {
+  return { decision: "deny", reason };
+}
+
+function instruct(reason) {
+  return { decision: "instruct", reason };
+}
+
 // ── Exports ────────────────────────────────────────────────────────────────
 
 exports.createApp = createApp;
 exports.getQueueCondition = getQueueCondition;
 exports.clearQueueCondition = clearQueueCondition;
+exports.customPolicies = customPolicies;
+exports.allow = allow;
+exports.deny = deny;
+exports.instruct = instruct;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claudeye",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "Watchtower for Claude Code & Agents SDK — replay sessions, run custom evals, debug agent traces locally",
   "bin": {
     "claudeye": "./bin/claudeye.mjs"
@@ -61,10 +61,10 @@
     "access": "public"
   },
   "optionalDependencies": {
-    "@claudeye/linux-x64": "1.0.7",
-    "@claudeye/linux-arm64": "1.0.7",
-    "@claudeye/darwin-x64": "1.0.7",
-    "@claudeye/darwin-arm64": "1.0.7",
-    "@claudeye/win32-x64": "1.0.7"
+    "@claudeye/linux-x64": "1.0.8",
+    "@claudeye/linux-arm64": "1.0.8",
+    "@claudeye/darwin-x64": "1.0.8",
+    "@claudeye/darwin-arm64": "1.0.8",
+    "@claudeye/win32-x64": "1.0.8"
   }
 }

package/scripts/preuninstall.mjs

@@ -2,8 +2,12 @@
 /**
  * preuninstall script for the claudeye wrapper package.
  *
- * Removes claudeye hook entries from Claude Code's ~/.claude/settings.json.
- * Does NOT touch ~/.claudeye/ (preserves cache, hooks-config, instance-id).
+ * Removes claudeye hook entries from all reachable Claude Code settings files:
+ *   - ~/.claude/settings.json            (user scope — always attempted)
+ *   - {cwd}/.claude/settings.json        (project scope — if it exists)
+ *   - {cwd}/.claude/settings.local.json  (local scope — if it exists)
+ *
+ * Does NOT delete ~/.claudeye/ (preserves cache, hooks-config, instance-id).
  *
  * Never exits non-zero — uninstall must not be blocked by cleanup failures.
  * No external dependencies — Node.js built-ins only.
@@ -15,63 +19,101 @@ import { trackInstallEvent } from "./telemetry.mjs";
 
 const CLAUDEYE_HOOK_MARKER = "__claudeye_hook__";
 
-let removed = 0;
+/**
+ * Remove all claudeye-marked hook entries from a single settings file.
+ * Returns the number of hook entries removed (not matchers).
+ * Writes the file only when at least one hook was removed.
+ */
+function removeHooksFromFile(settingsPath) {
+  if (!existsSync(settingsPath)) return 0;
 
-try {
-  const settingsPath = resolve(homedir(), ".claude", "settings.json");
+  let settings;
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+  } catch {
+    return 0; // Corrupt or unreadable — nothing to do
+  }
+
+  if (!settings?.hooks) return 0;
+
+  let hooksRemoved = 0;
+
+  for (const eventType of Object.keys(settings.hooks)) {
+    const matchers = settings.hooks[eventType];
+    if (!Array.isArray(matchers)) continue;
+
+    for (let i = matchers.length - 1; i >= 0; i--) {
+      const matcher = matchers[i];
+      if (!matcher.hooks) continue;
+
+      const before = matcher.hooks.length;
+      matcher.hooks = matcher.hooks.filter((h) => {
+        if (h[CLAUDEYE_HOOK_MARKER] === true) return false; // marked entry
+        // Fallback for legacy installs that predate the marker
+        const cmd = typeof h.command === "string" ? h.command : "";
+        if (cmd.includes("claudeye") && cmd.includes("--hook")) return false;
+        return true;
+      });
+      hooksRemoved += before - matcher.hooks.length;
+
+      // Remove now-empty matchers
+      if (matcher.hooks.length === 0) {
+        matchers.splice(i, 1);
+      }
+    }
+
+    // Remove now-empty event type arrays
+    if (matchers.length === 0) {
+      delete settings.hooks[eventType];
+    }
+  }
+
+  // Remove now-empty hooks object
+  if (Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
+  }
 
-  if (existsSync(settingsPath)) {
-    let settings;
-    let parsed = false;
+  if (hooksRemoved > 0) {
     try {
-      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
-      parsed = true;
+      writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
     } catch {
-      // Corrupt or unreadable — nothing to do
+      // Best-effort — don't block uninstall
     }
+  }
 
-    if (parsed && settings.hooks) {
-      for (const eventType of Object.keys(settings.hooks)) {
-        const matchers = settings.hooks[eventType];
-        if (!Array.isArray(matchers)) continue;
-
-        for (let i = matchers.length - 1; i >= 0; i--) {
-          const matcher = matchers[i];
-          if (!matcher.hooks) continue;
-
-          matcher.hooks = matcher.hooks.filter(
-            (h) => h[CLAUDEYE_HOOK_MARKER] !== true
-          );
-
-          // Remove empty matchers
-          if (matcher.hooks.length === 0) {
-            matchers.splice(i, 1);
-            removed++;
-          }
-        }
-
-        // Remove empty event type arrays
-        if (matchers.length === 0) {
-          delete settings.hooks[eventType];
-        }
-      }
+  return hooksRemoved;
+}
 
-      // Remove empty hooks object
-      if (Object.keys(settings.hooks).length === 0) {
-        delete settings.hooks;
-      }
+let totalRemoved = 0;
 
-      if (removed > 0) {
-        writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
-        console.log(`[claudeye] Removed ${removed} hook(s) from ~/.claude/settings.json.`);
-      }
+try {
+  const home = homedir();
+  const projectCwd = process.cwd();
 
-      console.log(
-        `[claudeye] Note: project/local scope hooks must be removed manually if they were installed.\n` +
-        `  Run: claudeye --remove-hooks --scope project  (or --scope local)`
-      );
+  // Build list of settings files to clean, deduped in case cwd === home
+  const candidates = [
+    resolve(home, ".claude", "settings.json"),              // user scope
+    resolve(projectCwd, ".claude", "settings.json"),        // project scope
+    resolve(projectCwd, ".claude", "settings.local.json"),  // local scope
+  ];
+  const seen = new Set();
+  const settingsPaths = candidates.filter((p) => {
+    if (seen.has(p)) return false;
+    seen.add(p);
+    return true;
+  });
+
+  for (const settingsPath of settingsPaths) {
+    const removed = removeHooksFromFile(settingsPath);
+    if (removed > 0) {
+      console.log(`[claudeye] Removed ${removed} hook(s) from ${settingsPath}.`);
+      totalRemoved += removed;
     }
   }
+
+  if (totalRemoved === 0) {
+    console.log("[claudeye] No hook entries found to remove.");
+  }
 } catch {
   // Never block uninstall
 }
@@ -81,6 +123,6 @@ try {
   await trackInstallEvent("package_uninstalled", {
     platform: platform(),
     arch: arch(),
-    hooks_removed: removed,
+    hooks_removed: totalRemoved,
   });
 } catch {}