@axiomatic-labs/claudeflow 2.13.20 → 2.13.21

package/lib/hook-overrides.js

@@ -0,0 +1,177 @@
+// User hook overrides — toggle individual claudeflow hook handlers without
+// editing the template-managed `.claude/settings.json` directly.
+//
+// File: `.claudeflow/config/user-hook-overrides.json`
+// Shape:
+//   { "version": 1,
+//     "disabledHandlers": [
+//       { "event": "SessionStart", "matcher": "", "handler": "SessionStart/foo.js",
+//         "spec": { "command": "node \"$CLAUDE_PROJECT_DIR/.claude/hooks/SessionStart/foo.js\"" } } ] }
+//
+// The `spec` field captures the original hook entry verbatim so the panel
+// can re-enable a handler later without consulting an external snapshot.
+//
+// Two operations:
+//   - `applyHookOverrides(settings, overrides)`: pure function, returns a
+//     new settings object with disabled handlers removed. Called by
+//     install.js right after writing `.claude/settings.json` so the
+//     effective config respects the overrides on every install/update.
+//   - `toggleHookOverride(...)`: stateful, used by the panel server.
+//     Reads / writes the overrides file and the resolved settings file.
+
+const fs = require('fs');
+const path = require('path');
+
+const OVERRIDES_REL = path.join('.claudeflow', 'config', 'user-hook-overrides.json');
+const SETTINGS_REL = path.join('.claude', 'settings.json');
+const HOOK_PATH_REGEX = /\.claude\/hooks\/(.+?\.js)/;
+
+function readJsonSafe(absPath) {
+  try { return JSON.parse(fs.readFileSync(absPath, 'utf8')); } catch { return null; }
+}
+
+function writeJson(absPath, data) {
+  fs.mkdirSync(path.dirname(absPath), { recursive: true });
+  fs.writeFileSync(absPath, JSON.stringify(data, null, 2) + '\n');
+}
+
+function normalizeHandlerPath(command) {
+  if (!command) return '';
+  const m = HOOK_PATH_REGEX.exec(command);
+  return m ? m[1] : command.replace(/^node\s+/, '').replace(/^["']|["']$/g, '').trim();
+}
+
+function defaultOverrides() {
+  return { version: 1, disabledHandlers: [] };
+}
+
+function readOverrides(projectRoot) {
+  const data = readJsonSafe(path.join(projectRoot, OVERRIDES_REL));
+  if (!data || typeof data !== 'object') return defaultOverrides();
+  return {
+    version: data.version || 1,
+    disabledHandlers: Array.isArray(data.disabledHandlers) ? data.disabledHandlers : [],
+  };
+}
+
+function writeOverrides(projectRoot, overrides) {
+  writeJson(path.join(projectRoot, OVERRIDES_REL), overrides);
+}
+
+function matchesOverride(override, event, matcher, handlerCommand) {
+  if (override.event !== event) return false;
+  if ((override.matcher || '') !== (matcher || '')) return false;
+  return normalizeHandlerPath(handlerCommand) === override.handler;
+}
+
+// Returns a fresh settings object with handlers disabled by `overrides` removed.
+// Empty rules are pruned. The shape of `settings.hooks` is preserved otherwise.
+function applyHookOverrides(settings, overrides) {
+  const disabled = (overrides && overrides.disabledHandlers) || [];
+  if (!disabled.length || !settings || !settings.hooks) return settings;
+  const next = JSON.parse(JSON.stringify(settings));
+  const hooks = next.hooks;
+  for (const event of Object.keys(hooks)) {
+    const rules = Array.isArray(hooks[event]) ? hooks[event] : [];
+    for (let i = rules.length - 1; i >= 0; i--) {
+      const rule = rules[i] || {};
+      const matcher = rule.matcher || '';
+      const remaining = (rule.hooks || []).filter(
+        (h) => !disabled.some((d) => matchesOverride(d, event, matcher, h.command || '')),
+      );
+      if (remaining.length === 0) rules.splice(i, 1);
+      else rule.hooks = remaining;
+    }
+    hooks[event] = rules;
+  }
+  return next;
+}
+
+// Apply on disk: read settings.json + overrides, write the pruned settings
+// back. Idempotent — calling twice produces the same file.
+function applyOverridesToFile(projectRoot) {
+  const settingsPath = path.join(projectRoot, SETTINGS_REL);
+  const settings = readJsonSafe(settingsPath);
+  if (!settings) return false;
+  const overrides = readOverrides(projectRoot);
+  if (!overrides.disabledHandlers.length) return false;
+  const next = applyHookOverrides(settings, overrides);
+  fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + '\n');
+  return true;
+}
+
+// Find a hook entry in current settings.json by event/matcher/handler.
+// Used when disabling: we capture the spec before removing it.
+function findHandlerInSettings(settings, event, matcher, handler) {
+  const rules = (settings.hooks && settings.hooks[event]) || [];
+  for (const rule of rules) {
+    if ((rule.matcher || '') !== (matcher || '')) continue;
+    for (const h of rule.hooks || []) {
+      if (normalizeHandlerPath(h.command || '') === handler) return h;
+    }
+  }
+  return null;
+}
+
+// Add an entry back to the live settings under the right event/matcher.
+function restoreHandlerInSettings(settings, event, matcher, spec) {
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks[event]) settings.hooks[event] = [];
+  const rules = settings.hooks[event];
+  let rule = rules.find((r) => (r.matcher || '') === (matcher || ''));
+  if (!rule) {
+    rule = { matcher, hooks: [] };
+    rules.push(rule);
+  }
+  // Avoid duplicate restoration if the spec is already present
+  const already = rule.hooks.some((h) => normalizeHandlerPath(h.command || '') === normalizeHandlerPath(spec.command || ''));
+  if (!already) rule.hooks.push(spec);
+}
+
+// Stateful toggle used by the panel.
+//   - disable=true: capture spec from current settings.json, append to
+//     overrides, remove from settings.json
+//   - disable=false: pop spec from overrides, restore to settings.json
+function toggleHookOverride(projectRoot, { event, matcher = '', handler, disable }) {
+  const settingsPath = path.join(projectRoot, SETTINGS_REL);
+  const settings = readJsonSafe(settingsPath) || { hooks: {} };
+  const overrides = readOverrides(projectRoot);
+  const matcherKey = matcher || '';
+
+  if (disable) {
+    const already = overrides.disabledHandlers.find(
+      (d) => d.event === event && (d.matcher || '') === matcherKey && d.handler === handler,
+    );
+    if (already) return { state: 'noop', reason: 'already-disabled' };
+    const spec = findHandlerInSettings(settings, event, matcherKey, handler);
+    if (!spec) return { state: 'error', reason: 'handler-not-found-in-settings' };
+    overrides.disabledHandlers.push({ event, matcher: matcherKey, handler, spec });
+    writeOverrides(projectRoot, overrides);
+    const next = applyHookOverrides(settings, overrides);
+    fs.writeFileSync(settingsPath, JSON.stringify(next, null, 2) + '\n');
+    return { state: 'disabled' };
+  }
+
+  const idx = overrides.disabledHandlers.findIndex(
+    (d) => d.event === event && (d.matcher || '') === matcherKey && d.handler === handler,
+  );
+  if (idx === -1) return { state: 'noop', reason: 'not-disabled' };
+  const [removed] = overrides.disabledHandlers.splice(idx, 1);
+  if (!removed.spec) return { state: 'error', reason: 'no-spec-recorded' };
+  restoreHandlerInSettings(settings, event, matcherKey, removed.spec);
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  writeOverrides(projectRoot, overrides);
+  return { state: 'enabled' };
+}
+
+module.exports = {
+  OVERRIDES_REL,
+  SETTINGS_REL,
+  applyHookOverrides,
+  applyOverridesToFile,
+  readOverrides,
+  writeOverrides,
+  toggleHookOverride,
+  normalizeHandlerPath,
+  matchesOverride,
+};

package/lib/install.js

@@ -4,6 +4,7 @@ const { execSync, execFileSync } = require('child_process');
 const { requireAuth } = require('./auth.js');
 const { getLatestRelease, downloadReleaseAsset } = require('./download.js');
 const { writeLocalVersion, readLocalVersion } = require('./version.js');
+const { applyOverridesToFile: applyHookOverridesToFile } = require('./hook-overrides.js');
 const ui = require('./ui.js');
 
 // Template skills are shipped inside the ZIP. Copy every managed
@@ -85,6 +86,10 @@ async function run() {
     fs.mkdirSync(path.join(cwd, '.claude'), { recursive: true });
     if (fs.existsSync(srcSettings)) {
       syncClaudeSettings(srcSettings, dstSettings);
+      // Re-apply user hook overrides (if any) so disabled handlers stay
+      // disabled across update — without this, every update would resurrect
+      // hooks the user explicitly turned off via `claudeflow panel`.
+      applyHookOverridesToFile(cwd);
     }
 
     // Upsert playwright entry in .mcp.json with project-specific CDP port.

package/lib/panel.js

@@ -21,6 +21,11 @@ const {
   checkStaleLockfiles,
   readPlaywrightCdpEndpoint,
 } = require('./doctor.js');
+const {
+  readOverrides,
+  toggleHookOverride,
+  normalizeHandlerPath,
+} = require('./hook-overrides.js');
 
 const IDLE_SHUTDOWN_MS = 30 * 60 * 1000; // 30 min
 
@@ -85,38 +90,68 @@ function getHooksInfo(cwd) {
   try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); }
   catch { return { settingsFound: false, events: [] }; }
 
+  const overrides = readOverrides(cwd);
+  const disabledIndex = new Map();
+  for (const d of overrides.disabledHandlers || []) {
+    disabledIndex.set(`${d.event}|${d.matcher || ''}|${d.handler}`, d);
+  }
+
   const hooks = settings.hooks || {};
-  const events = [];
+  const eventsMap = new Map();
   let totalHandlers = 0;
   let warnings = 0;
+  let disabledCount = 0;
 
   for (const [event, rules] of Object.entries(hooks)) {
-    const handlers = [];
+    if (!eventsMap.has(event)) eventsMap.set(event, []);
     for (const rule of rules) {
       const matcher = rule.matcher || '';
       for (const h of rule.hooks || []) {
         const cmd = h.command || '';
-        const handlerPath = cmd
-          .replace(/^node\s+/, '')
-          .replace(/^"?\$CLAUDE_PROJECT_DIR"?\/?\.claude\/hooks\//, '')
-          .replace(/^.*\/\.claude\/hooks\//, '')
-          .replace(/^"?\$CLAUDE_PROJECT_DIR"?\/?/, '')
-          .replace(/"/g, '')
-          .trim();
+        const handlerPath = normalizeHandlerPath(cmd) || (cmd ? cmd : '');
         const isEmpty = !handlerPath;
         if (isEmpty) warnings++;
-        handlers.push({
+        eventsMap.get(event).push({
           handler: handlerPath || '(empty command)',
-          matcher: matcher || '(any)',
+          matcher: matcher || '',
+          matcherDisplay: matcher || '(any)',
           empty: isEmpty,
+          disabled: false,
           rawCommand: cmd,
         });
         totalHandlers++;
       }
     }
-    events.push({ event, count: handlers.length, handlers });
   }
-  return { settingsFound: true, events, totalHandlers, warnings };
+
+  // Add disabled handlers (live in overrides, not in settings.json)
+  for (const d of overrides.disabledHandlers || []) {
+    if (!eventsMap.has(d.event)) eventsMap.set(d.event, []);
+    eventsMap.get(d.event).push({
+      handler: d.handler,
+      matcher: d.matcher || '',
+      matcherDisplay: d.matcher || '(any)',
+      empty: false,
+      disabled: true,
+      rawCommand: (d.spec && d.spec.command) || '',
+    });
+    disabledCount++;
+  }
+
+  const events = Array.from(eventsMap.entries()).map(([event, handlers]) => ({
+    event,
+    count: handlers.length,
+    handlers,
+  }));
+
+  return {
+    settingsFound: true,
+    events,
+    totalHandlers: totalHandlers + disabledCount,
+    activeHandlers: totalHandlers,
+    disabledHandlers: disabledCount,
+    warnings,
+  };
 }
 
 function getMcpInfo(cwd) {
@@ -297,6 +332,11 @@ details[open] summary { padding-bottom: 8px; border-bottom: 1px solid var(--bord
 .warning { color: var(--warn); }
 .toggle { display: inline-flex; align-items: center; gap: 6px; cursor: pointer; user-select: none; }
 .toggle input { accent-color: var(--accent); }
+.disabled-row { opacity: 0.55; }
+.disabled-row .matcher { font-style: italic; }
+.toast { position: fixed; bottom: 18px; right: 18px; background: var(--panel); border: 1px solid var(--border); padding: 10px 14px; border-radius: 6px; font-size: 13px; box-shadow: 0 4px 12px rgba(0,0,0,0.4); }
+.toast.err { border-color: var(--err); }
+.toast.ok { border-color: var(--ok); }
 </style>
 </head>
 <body>
@@ -451,14 +491,23 @@ function renderHooks() {
   const h = state.hooks;
   if (!h.settingsFound) return '<h2>Hooks</h2><p class="error">.claude/settings.json not found</p>';
   const items = h.events.map(ev => {
-    const handlers = ev.handlers.map(handler => {
-      const mark = handler.empty ? '<span class="warning">⚠ empty command</span>' : '';
-      return \`<div class="handler"><span>\${escapeHtml(handler.handler)} \${mark}</span><span class="matcher">\${escapeHtml(handler.matcher)}</span></div>\`;
+    const handlers = ev.handlers.map(hd => {
+      const mark = hd.empty ? '<span class="warning">⚠ empty command</span>' : '';
+      const cls = hd.disabled ? 'handler disabled-row' : 'handler';
+      const checked = hd.disabled ? '' : 'checked';
+      const dataset = \`data-event="\${escapeHtml(ev.event)}" data-matcher="\${escapeHtml(hd.matcher)}" data-handler="\${escapeHtml(hd.handler)}"\`;
+      const status = hd.disabled ? '<span class="badge info">disabled</span>' : '';
+      return \`<div class="\${cls}">
+        <label class="toggle"><input type="checkbox" class="hook-toggle" \${dataset} \${checked} \${hd.empty ? 'disabled' : ''} />
+          <span>\${escapeHtml(hd.handler)} \${status} \${mark}</span></label>
+        <span class="matcher">\${escapeHtml(hd.matcherDisplay)}</span>
+      </div>\`;
     }).join('');
     return \`<details><summary>\${escapeHtml(ev.event)} <span class="muted">(\${ev.count})</span></summary>\${handlers}</details>\`;
   }).join('');
   return \`<h2>Hooks</h2>
-    <p class="sub">\${h.events.length} events · \${h.totalHandlers} handlers\${h.warnings ? ' · <span class="warning">' + h.warnings + ' warnings</span>' : ''}</p>
+    <p class="sub">\${h.events.length} events · \${h.activeHandlers} active\${h.disabledHandlers ? ' · <span class="muted">' + h.disabledHandlers + ' disabled</span>' : ''}\${h.warnings ? ' · <span class="warning">' + h.warnings + ' warnings</span>' : ''}</p>
+    <p class="sub muted">Uncheck a handler to disable it. Disabled handlers are recorded in <code>.claudeflow/config/user-hook-overrides.json</code> and survive <code>claudeflow update</code>. Toggling rewrites <code>.claude/settings.json</code> immediately; reload Claude Code to pick up the change.</p>
     \${items}\`;
 }
 
@@ -513,6 +562,46 @@ function renderDoctor() {
     </div>\`;
 }
 
+function showToast(msg, kind) {
+  const el = document.createElement('div');
+  el.className = 'toast ' + (kind || 'ok');
+  el.textContent = msg;
+  document.body.appendChild(el);
+  setTimeout(() => el.remove(), 2400);
+}
+
+async function toggleHook(event, matcher, handler, disable) {
+  try {
+    const r = await fetch('/api/hooks/toggle', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ event, matcher, handler, disable }),
+    });
+    const result = await r.json();
+    if (!r.ok || result.state === 'error') {
+      showToast('Toggle failed: ' + (result.reason || result.error || 'unknown'), 'err');
+    } else if (result.state === 'noop') {
+      showToast('Already in target state (' + result.reason + ')', 'ok');
+    } else {
+      showToast(disable ? 'Disabled. Reload Claude Code to apply.' : 'Enabled. Reload Claude Code to apply.', 'ok');
+    }
+  } catch (e) {
+    showToast('Network error: ' + e.message, 'err');
+  }
+  await refresh();
+}
+
+document.addEventListener('change', (e) => {
+  const t = e.target;
+  if (t && t.classList && t.classList.contains('hook-toggle')) {
+    const event = t.dataset.event;
+    const matcher = t.dataset.matcher;
+    const handler = t.dataset.handler;
+    const disable = !t.checked;
+    toggleHook(event, matcher, handler, disable);
+  }
+});
+
 document.getElementById('refresh').onclick = refresh;
 document.getElementById('auto').onchange = (e) => {
   if (timer) clearInterval(timer);
@@ -532,8 +621,26 @@ function readClaudeMdSafe(cwd) {
   catch { return ''; }
 }
 
+function readRequestBody(req, limit = 64 * 1024) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let total = 0;
+    req.on('data', (c) => {
+      total += c.length;
+      if (total > limit) {
+        reject(new Error('Request body too large'));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+    });
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+    req.on('error', reject);
+  });
+}
+
 function handler(cwd) {
-  return (req, res) => {
+  return async (req, res) => {
     try {
       const url = new URL(req.url, 'http://localhost');
       const route = url.pathname;
@@ -543,10 +650,27 @@ function handler(cwd) {
         res.end(body);
       };
 
-      if (route === '/' || route === '/index.html') return send(200, renderHtml(), 'text/html; charset=utf-8');
-      if (route === '/api/status') return send(200, JSON.stringify(collectStatus(cwd)), 'application/json');
-      if (route === '/api/claude-md') return send(200, readClaudeMdSafe(cwd), 'text/plain; charset=utf-8');
-      if (route === '/healthz') return send(200, 'ok', 'text/plain');
+      if (req.method === 'GET') {
+        if (route === '/' || route === '/index.html') return send(200, renderHtml(), 'text/html; charset=utf-8');
+        if (route === '/api/status') return send(200, JSON.stringify(collectStatus(cwd)), 'application/json');
+        if (route === '/api/claude-md') return send(200, readClaudeMdSafe(cwd), 'text/plain; charset=utf-8');
+        if (route === '/healthz') return send(200, 'ok', 'text/plain');
+      }
+
+      if (req.method === 'POST' && route === '/api/hooks/toggle') {
+        const raw = await readRequestBody(req);
+        let payload;
+        try { payload = JSON.parse(raw); }
+        catch { return send(400, JSON.stringify({ error: 'invalid json' }), 'application/json'); }
+        const { event, matcher, handler: hdlr, disable } = payload;
+        if (typeof event !== 'string' || typeof hdlr !== 'string' || typeof disable !== 'boolean') {
+          return send(400, JSON.stringify({ error: 'event, handler, disable required' }), 'application/json');
+        }
+        const result = toggleHookOverride(cwd, { event, matcher: matcher || '', handler: hdlr, disable });
+        const status = result.state === 'error' ? 500 : 200;
+        return send(status, JSON.stringify(result), 'application/json');
+      }
+
       send(404, JSON.stringify({ error: 'not found' }), 'application/json');
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'application/json' });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiomatic-labs/claudeflow",
-  "version": "2.13.20",
+  "version": "2.13.21",
   "description": "Claudeflow — AI-powered development toolkit for Claude Code. Skills, agents, hooks, and quality gates that ship production apps.",
   "bin": {
     "claudeflow": "./bin/cli.js"