@hailer/mcp 1.0.29 → 1.1.2

package/.claude/hooks/context-watchdog.cjs

@@ -0,0 +1,292 @@
+#!/usr/bin/env node
+/**
+ * <hook-name>context-watchdog</hook-name>
+ *
+ * <purpose>
+ * Auto-detect context exhaustion and trigger handoff before context is lost.
+ * Three layers:
+ *   1. PreCompact (auto) - escalating response by compaction count:
+ *        1st: inform (context still good after one compaction)
+ *        2nd: strongly urge handoff (summary-of-summary, quality degrades)
+ *        3rd+: yolo=auto-handoff, interactive=block until acknowledged
+ *   2. PostToolUse (Task) - count agent calls, warn at thresholds
+ *   3. Stop - if yolo + compact fired, block stop until handoff written
+ * </purpose>
+ *
+ * <triggers>
+ * - PreCompact (matcher: auto)
+ * - PostToolUse (matcher: Task)
+ * - Stop (matcher: "")
+ * </triggers>
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// --- Config ---
+const EARLY_WARNING_CALLS = 20;   // Soft heads-up
+const URGENT_WARNING_CALLS = 35;  // Strong warning
+const MAX_STOP_BLOCKS = 2;        // Prevent infinite stop-block loops
+
+// --- Helpers ---
+
+function ordinal(n) {
+  const s = ['th', 'st', 'nd', 'rd'];
+  const v = n % 100;
+  return n + (s[(v - 20) % 10] || s[v] || s[0]);
+}
+
+function getProjectRoot() {
+  let dir = process.cwd();
+  while (dir !== '/' && !fs.existsSync(path.join(dir, '.claude'))) {
+    dir = path.dirname(dir);
+  }
+  return dir;
+}
+
+function statePath(projectRoot) {
+  return path.join(projectRoot, '.claude', '.context-watchdog.json');
+}
+
+function loadState(projectRoot, sessionId) {
+  const fp = statePath(projectRoot);
+  try {
+    if (fs.existsSync(fp)) {
+      const state = JSON.parse(fs.readFileSync(fp, 'utf8'));
+      if (state.sessionId === sessionId) return state;
+    }
+  } catch {}
+  // New session or corrupted state - reset
+  return {
+    sessionId,
+    toolCalls: 0,
+    compactCount: 0,
+    lastWarning: 'none', // none | early | urgent | compact
+    stopBlocks: 0,
+  };
+}
+
+function saveState(projectRoot, state) {
+  try {
+    fs.writeFileSync(statePath(projectRoot), JSON.stringify(state));
+  } catch {}
+}
+
+function isYoloMode(projectRoot) {
+  try {
+    const statePath = path.join(projectRoot, '.claude', 'yolo-state.json');
+    const state = JSON.parse(fs.readFileSync(statePath, 'utf8'));
+    return state.mode === 'yolo';
+  } catch {
+    return false;
+  }
+}
+
+function handoffRecentlyWritten(projectRoot) {
+  const fp = path.join(projectRoot, 'SESSION-HANDOFF.md');
+  try {
+    if (fs.existsSync(fp)) {
+      const age = Date.now() - fs.statSync(fp).mtimeMs;
+      return age < 120_000; // Written within last 2 minutes
+    }
+  } catch {}
+  return false;
+}
+
+// Output helpers - schema differs by hook event type
+let _hookEvent = null; // Set during processHook
+
+function allow(message) {
+  if (_hookEvent === 'Stop') {
+    // Stop schema: { continue?, stopReason? }
+    console.log(JSON.stringify({}));
+  } else if (_hookEvent === 'PreCompact') {
+    // PreCompact: just output empty or with message
+    if (message) {
+      console.log(JSON.stringify({ additionalContext: message }));
+    } else {
+      console.log(JSON.stringify({}));
+    }
+  } else {
+    // PreToolUse/PostToolUse schema
+    const out = { decision: 'allow' };
+    if (message) out.message = message;
+    console.log(JSON.stringify(out));
+  }
+  process.exit(0);
+}
+
+function block(reason) {
+  if (_hookEvent === 'Stop') {
+    // Stop schema: continue=true means "don't stop, keep going"
+    console.log(JSON.stringify({ continue: true, stopReason: reason }));
+  } else {
+    console.log(JSON.stringify({ decision: 'block', reason }));
+  }
+  process.exit(0);
+}
+
+// --- Main ---
+
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    processHook(JSON.parse(input));
+  } catch {
+    allow();
+  }
+});
+
+function processHook(data) {
+  const projectRoot = getProjectRoot();
+  const sessionId = data.session_id || '';
+  const state = loadState(projectRoot, sessionId);
+  const yolo = isYoloMode(projectRoot);
+  const event = data.hook_event_name;
+  _hookEvent = event; // Set for allow/block output formatting
+
+  // ─── Layer 1: PreCompact (auto) ────────────────────────
+  // Context IS full. Escalating response by compaction count.
+  if (event === 'PreCompact') {
+    state.compactCount++;
+    state.lastWarning = 'compact';
+    saveState(projectRoot, state);
+
+    // 1st compaction: inform — context is still usable
+    if (state.compactCount === 1) {
+      if (yolo) {
+        allow(
+          `📋 Context compacting (1st time). Still usable.\n\n` +
+          `Save progress soon:\n` +
+          `1. Update DEVELOPMENT.md with current progress\n` +
+          `2. Write SESSION-HANDOFF.md\n` +
+          `3. Run /save\n\n` +
+          `You can continue working after this compaction.`
+        );
+      } else {
+        allow(`📋 Context compacting (1st time). Context is still good — consider running /handoff soon to preserve state.`);
+      }
+    }
+
+    // 2nd compaction: strongly urge handoff — quality starts degrading
+    if (state.compactCount === 2) {
+      if (yolo) {
+        allow(
+          `⚠️ CONTEXT COMPACTING 2nd TIME — quality will degrade.\n\n` +
+          `You MUST save progress NOW before continuing:\n` +
+          `1. Update DEVELOPMENT.md with current progress\n` +
+          `2. Write SESSION-HANDOFF.md with full current state and next steps\n` +
+          `3. Run /save "Handoff: 2nd compaction"\n` +
+          `4. Tell user: "Context compacted twice. Recommend starting fresh with /recap."\n\n` +
+          `Do this BEFORE any other work. After handoff, you may continue but expect degraded recall.`
+        );
+      } else {
+        allow(
+          `⚠️ Context compacting for the 2nd time. Earlier details are now a summary-of-a-summary.\n\n` +
+          `Strongly recommended: run /handoff now and start a fresh session with /recap.\n` +
+          `Continuing risks: forgetting decisions, re-reading files, repeating mistakes.`
+        );
+      }
+    }
+
+    // 3rd+ compaction: force handoff
+    if (state.compactCount >= 3) {
+      if (yolo) {
+        allow(
+          `🛑 CONTEXT COMPACTING ${ordinal(state.compactCount)} TIME — session is degraded.\n\n` +
+          `IMMEDIATELY write handoff and stop:\n` +
+          `1. Update DEVELOPMENT.md with ALL current progress\n` +
+          `2. Write SESSION-HANDOFF.md with full state, pending tasks, and next steps\n` +
+          `3. Run /save "Auto-handoff: ${state.compactCount}x compacted"\n` +
+          `4. Tell user: "Context compacted ${state.compactCount} times. Start new conversation with /recap to continue."\n\n` +
+          `Do NOT continue working. Quality is too degraded.`
+        );
+      } else {
+        allow(
+          `🛑 Context compacting for the ${ordinal(state.compactCount)} time — session is significantly degraded.\n\n` +
+          `You should run /handoff and start fresh. Continuing will lead to:\n` +
+          `- Forgotten decisions and context\n` +
+          `- Re-reading files already read\n` +
+          `- Potential mistakes from lost context\n\n` +
+          `Please run /handoff now.`
+        );
+      }
+    }
+  }
+
+  // ─── Layer 2: PostToolUse (Task) - agent call counter ──
+  if (event === 'PostToolUse' && data.tool_name === 'Task') {
+    state.toolCalls++;
+    saveState(projectRoot, state);
+
+    // Skip warnings if compact already fired (more urgent message already sent)
+    if (state.lastWarning === 'compact') {
+      allow();
+    }
+
+    // Urgent warning
+    if (state.toolCalls === URGENT_WARNING_CALLS && state.lastWarning !== 'urgent') {
+      state.lastWarning = 'urgent';
+      saveState(projectRoot, state);
+
+      if (yolo) {
+        allow(
+          `⚠️ Context getting full: ${state.toolCalls} agent calls this session.\n\n` +
+          `Save progress NOW before auto-compaction hits:\n` +
+          `1. Update DEVELOPMENT.md with progress\n` +
+          `2. Write SESSION-HANDOFF.md\n` +
+          `3. Run /save\n` +
+          `Then continue working (or tell user to start fresh).`
+        );
+      } else {
+        allow(`📊 ${state.toolCalls} agent calls this session. Context may be getting full - consider /handoff.`);
+      }
+    }
+
+    // Early warning
+    if (state.toolCalls === EARLY_WARNING_CALLS && state.lastWarning === 'none') {
+      state.lastWarning = 'early';
+      saveState(projectRoot, state);
+
+      if (yolo) {
+        allow(`📊 Context check: ${state.toolCalls} agent calls. Consider saving progress with /save soon.`);
+      }
+      // Silent in non-yolo mode at early threshold
+    }
+
+    allow();
+  }
+
+  // ─── Layer 3: Stop - safety net ────────────────────────
+  // Block stop if context was heavily compacted and no handoff written.
+  if (event === 'Stop') {
+    // Prevent infinite loop: if stop hook already active, let it through
+    if (data.stop_hook_active) {
+      allow();
+    }
+
+    // After 2+ compactions (any mode), block stop until handoff is written
+    const shouldBlock = state.compactCount >= 2 && state.stopBlocks < MAX_STOP_BLOCKS;
+
+    if (shouldBlock && !handoffRecentlyWritten(projectRoot)) {
+      state.stopBlocks++;
+      saveState(projectRoot, state);
+      block(
+        `Context was compacted ${state.compactCount} time(s) but no handoff found.\n\n` +
+        `Before stopping, you MUST:\n` +
+        `1. Write SESSION-HANDOFF.md with current state and next steps\n` +
+        `2. Update DEVELOPMENT.md with progress\n` +
+        `3. Run /save "Handoff: ${state.compactCount}x compacted"\n` +
+        `4. Tell user: "Session degraded after ${state.compactCount} compactions. Start fresh with /recap."`
+      );
+    }
+
+    allow();
+  }
+
+  // Default - unknown event, output safe empty JSON
+  console.log(JSON.stringify({}));
+  process.exit(0);
+}