feat(hooks): token optimization — dedup escalation, auto-route, prewarm, script-suggest

- dedup-reads: escalate to [STOP] at 5+ reads (was soft-only at 3+)
- desire-path-hook: auto-route Bash→Glob/Read/Grep with inline suggestions
- prewarm-tools: SessionStart hook emits top deferred tool pre-fetch hint
- script-suggest: detects multi-tool patterns matching existing scripts

Author: StackMemory Bot (CLI)

src/hooks/dedup-reads.cjs

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+// dedup-reads.cjs — PostToolUse hook for Claude Code
+//
+// Detects duplicate file reads in a session and warns when a file is read 3+
+// times without being modified in between. Helps reduce wasted tool calls.
+//
+// Install in ~/.claude/settings.json (or .claude/settings.local.json per-project):
+//
+//   {
+//     "hooks": {
+//       "PostToolUse": [
+//         {
+//           "matcher": "Read",
+//           "hooks": [
+//             { "type": "command", "command": "node /Users/jwu/Dev/stackmemory/src/hooks/dedup-reads.cjs" }
+//           ]
+//         }
+//       ]
+//     }
+//   }
+//
+// Opt out: STACKMEMORY_DEDUP_READS=0
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+if (process.env.STACKMEMORY_DEDUP_READS === '0' || process.env.STACKMEMORY_DEDUP_READS === 'false') {
+  process.exit(0);
+}
+
+const SM_DIR = path.join(process.env.HOME || '', '.stackmemory');
+const DP_DIR = path.join(SM_DIR, 'desire-paths');
+
+function run() {
+  let raw = '';
+  try {
+    raw = fs.readFileSync(0, 'utf-8');
+  } catch {
+    return;
+  }
+
+  let input;
+  try {
+    input = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  const toolName = input.tool_name || input.toolName;
+  const toolInput = input.tool_input || input.input || {};
+
+  let filePath;
+
+  if (toolName === 'Read') {
+    filePath = toolInput.file_path || toolInput.filePath;
+  } else if (toolName === 'Bash') {
+    // Codex reads files via Bash (cat, sed, head, nl, etc.) — extract file path
+    const cmd = toolInput.command || '';
+    const readMatch = cmd.match(/^(?:cat|head|tail|sed\s+-n|nl)\s+['"]?([^\s'";<>|&]+)/);
+    if (readMatch && readMatch[1] && !readMatch[1].startsWith('-')) {
+      filePath = readMatch[1];
+    }
+  }
+
+  if (!filePath) return;
+
+  const sessionId = input.session_id || input.sessionId
+    || process.env.STACKMEMORY_SESSION || process.env.CLAUDE_SESSION_ID
+    || 'default';
+
+  // Get current mtime
+  let mtimeMs = 0;
+  try {
+    mtimeMs = fs.statSync(filePath).mtimeMs;
+  } catch {
+    // File may not exist (e.g., error read) — skip tracking
+    return;
+  }
+
+  fs.mkdirSync(DP_DIR, { recursive: true });
+
+  const stateFile = path.join(DP_DIR, `dedup-${sessionId}.json`);
+  const lockFile = stateFile + '.lock';
+
+  // Acquire lock (spin up to 200ms)
+  let lockFd;
+  const deadline = Date.now() + 200;
+  while (Date.now() < deadline) {
+    try {
+      lockFd = fs.openSync(lockFile, 'wx');
+      break;
+    } catch {
+      // Lock held — spin briefly
+      const wait = Date.now() + 5;
+      while (Date.now() < wait) {} // busy-wait 5ms (no setTimeout in sync hook)
+    }
+  }
+  if (lockFd === undefined) return; // couldn't acquire lock — skip silently
+
+  try {
+    // Load state under lock
+    let state = {};
+    try {
+      state = JSON.parse(fs.readFileSync(stateFile, 'utf-8'));
+    } catch {
+      // First call or corrupted — start fresh
+    }
+
+    const entry = state[filePath];
+
+    if (!entry) {
+      state[filePath] = { count: 1, lastMtime: mtimeMs };
+    } else if (mtimeMs !== entry.lastMtime) {
+      state[filePath] = { count: 1, lastMtime: mtimeMs };
+    } else {
+      entry.count += 1;
+      entry.lastMtime = mtimeMs;
+
+      if (entry.count >= 3) {
+        const basename = path.basename(filePath);
+        let msg;
+        if (entry.count >= 5) {
+          msg = `[STOP] ${basename} read ${entry.count}x (unchanged). You already have this content. Do NOT read again — use what you have.`;
+        } else {
+          msg = `[dedup] ${basename} read ${entry.count}x this session (unchanged) — use cached content`;
+        }
+        process.stdout.write(JSON.stringify({ systemMessage: msg }) + '\n');
+      }
+    }
+
+    fs.writeFileSync(stateFile, JSON.stringify(state), 'utf-8');
+  } finally {
+    // Release lock
+    try { fs.closeSync(lockFd); } catch {}
+    try { fs.unlinkSync(lockFile); } catch {}
+  }
+}
+
+try {
+  run();
+} catch {
+  // Non-fatal — never crash the hook pipeline
+}

src/hooks/desire-path-hook.sh

@@ -62,3 +62,35 @@ fi
 # Append entry (no content/data — just tool + target pattern)
 TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
 echo "{\"ts\":\"${TIMESTAMP}\",\"sid\":\"${SESSION_ID}\",\"tool\":\"${TOOL_NAME}\",\"target\":\"${FIRST_ARG}\",\"dur\":${DURATION}}" >> "$STREAM_FILE"
+
+# --- Script suggestions: detect patterns that match existing scripts ---
+echo "$INPUT" | node "$(dirname "$0")/script-suggest.cjs" 2>/dev/null
+
+# --- Auto-route: suggest dedicated tools for replaceable Bash calls ---
+if [ "$TOOL_NAME" = "Bash" ] && [ -n "$FIRST_ARG" ]; then
+  SUGGESTION=$(echo "$FIRST_ARG" | node -e "
+    const cmd = require('fs').readFileSync(0,'utf-8').trim();
+    // ls/find → Glob
+    if (/^ls\s/.test(cmd) || /^find\s/.test(cmd)) {
+      const dir = cmd.replace(/^(ls|find)\s+/, '').split(/\s/)[0] || '.';
+      console.log('[route] Use Glob instead of \"' + cmd.slice(0,40) + '\" — e.g. Glob(pattern=\"**/*\", path=\"' + dir + '\")');
+    }
+    // cat/head/tail → Read
+    else if (/^(cat|head|tail|sed\s+-n|nl)\s/.test(cmd)) {
+      const file = cmd.replace(/^(cat|head|tail|sed\s+-n|nl)\s+/, '').split(/\s/)[0] || '';
+      if (file && !file.startsWith('-')) {
+        console.log('[route] Use Read instead of \"' + cmd.slice(0,40) + '\" — Read(file_path=\"' + file + '\")');
+      }
+    }
+    // grep/rg → Grep
+    else if (/^(grep|rg|ag)\s/.test(cmd)) {
+      const parts = cmd.split(/\s+/);
+      const pattern = parts[1] || '';
+      console.log('[route] Use Grep instead of \"' + cmd.slice(0,40) + '\" — Grep(pattern=\"' + pattern + '\")');
+    }
+  " 2>/dev/null)
+
+  if [ -n "$SUGGESTION" ]; then
+    echo "{\"systemMessage\":\"$SUGGESTION\"}"
+  fi
+fi

src/hooks/prewarm-tools.cjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * prewarm-tools.cjs — SessionStart hook
+ *
+ * Emits a system message telling Claude to pre-fetch schemas for
+ * the most frequently used deferred MCP tools, avoiding repeated
+ * ToolSearch calls mid-conversation.
+ *
+ * Data source: ~/.stackmemory/desire-paths/action-stream.jsonl
+ * Learns from actual usage — top N deferred tools by frequency.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SM_DIR = path.join(process.env.HOME || '', '.stackmemory');
+const STREAM_FILE = path.join(SM_DIR, 'desire-paths', 'action-stream.jsonl');
+const CACHE_FILE = path.join(SM_DIR, 'desire-paths', 'prewarm-cache.json');
+const CACHE_TTL = 24 * 60 * 60 * 1000; // 24h
+
+// Known deferred tool prefixes (MCP tools that need ToolSearch)
+const DEFERRED_PREFIXES = ['mcp__', 'TaskCreate', 'TaskUpdate', 'TaskGet', 'WebFetch', 'WebSearch'];
+
+function isDeferred(tool) {
+  return DEFERRED_PREFIXES.some(p => tool.startsWith(p));
+}
+
+function getTopTools() {
+  // Check cache first
+  try {
+    const cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
+    if (Date.now() - cache.ts < CACHE_TTL && cache.tools?.length > 0) {
+      return cache.tools;
+    }
+  } catch {}
+
+  // Parse action stream
+  if (!fs.existsSync(STREAM_FILE)) return [];
+
+  const counts = {};
+  const lines = fs.readFileSync(STREAM_FILE, 'utf-8').split('\n');
+
+  for (const line of lines) {
+    if (!line) continue;
+    try {
+      const d = JSON.parse(line);
+      const tool = d.tool || '';
+      if (isDeferred(tool)) {
+        counts[tool] = (counts[tool] || 0) + 1;
+      }
+    } catch {}
+  }
+
+  // Sort by frequency, take top 8
+  const sorted = Object.entries(counts)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 8)
+    .map(([tool]) => tool);
+
+  // Cache result
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({ ts: Date.now(), tools: sorted }));
+  } catch {}
+
+  return sorted;
+}
+
+function main() {
+  const tools = getTopTools();
+  if (tools.length === 0) return;
+
+  // Group by prefix for efficient ToolSearch queries
+  const mcpTools = tools.filter(t => t.startsWith('mcp__'));
+  const builtinTools = tools.filter(t => !t.startsWith('mcp__'));
+
+  const parts = [];
+  if (mcpTools.length > 0) {
+    parts.push(`select:${mcpTools.join(',')}`);
+  }
+  if (builtinTools.length > 0) {
+    parts.push(`select:${builtinTools.join(',')}`);
+  }
+
+  const msg = `[prewarm] Frequently used deferred tools detected. Pre-fetch with: ToolSearch(query="${parts[0]}", max_results=${tools.length})`;
+  process.stdout.write(JSON.stringify({ systemMessage: msg }) + '\n');
+}
+
+try {
+  main();
+} catch {}