@geraldmaron/construct 1.0.0

package/lib/hooks/mcp-health-check.mjs

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/mcp-health-check.mjs — MCP health check hook — verifies MCP servers are reachable before tool use.
+ *
+ * Runs as PreToolUse on MCP tool calls. Checks that the target MCP server is running and reachable. Emits a warning (does not block) if the server is unavailable.
+ */
+import { readFileSync, writeFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+
+const CACHE_PATH = `${homedir()}/.cx/mcp-health.json`;
+const CACHE_TTL_MS = 60_000;
+const markFailure = process.argv.includes('--mark-failure');
+
+let input = {};
+try {
+  const raw = readFileSync(0, 'utf8').trim();
+  if (raw) input = JSON.parse(raw);
+} catch { /* no stdin or not JSON */ }
+
+const toolName = input?.tool_name || input?.tool_input?.tool_name || '';
+
+if (!toolName.startsWith('mcp__')) {
+  if (!markFailure) { process.stdout.write(JSON.stringify(input) + '\n'); }
+  process.exit(0);
+}
+
+const serverSlug = toolName.split('__')[1] || '';
+
+let cache = {};
+try { cache = JSON.parse(readFileSync(CACHE_PATH, 'utf8')); } catch { /* fresh */ }
+
+if (markFailure) {
+  const entry = cache[serverSlug] || { status: 'healthy', since: 0, failures: 0 };
+  entry.failures = (entry.failures || 0) + 1;
+  entry.status = 'unhealthy';
+  entry.since = Date.now();
+  cache[serverSlug] = entry;
+  try { writeFileSync(CACHE_PATH, JSON.stringify(cache, null, 2)); } catch { /* best effort */ }
+  process.exit(0);
+}
+
+const entry = cache[serverSlug];
+if (entry?.status === 'unhealthy' && (Date.now() - entry.since) < CACHE_TTL_MS) {
+  process.stderr.write(
+    `[mcp-health] The ${serverSlug} connection is unavailable (failed ${entry.failures} time${entry.failures !== 1 ? 's' : ''} recently). Skipping this step.\n`
+  );
+  process.exit(2);
+}
+
+process.stdout.write(JSON.stringify(input) + '\n');
+process.exit(0);

package/lib/hooks/mcp-task-scope.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/mcp-task-scope.mjs — MCP task scope hook — constrains MCP tool use to the active workflow task scope.
+ *
+ * Runs as PreToolUse on MCP tool calls. Reads the active workflow task and warns when MCP tools are used outside the declared task scope.
+ */
+// PreToolUse(mcp__*) — task-aware MCP scope advisor.
+// Reads the active workflow task's mcpScope field.
+// Warns (non-blocking) if calling an MCP not declared for the active task.
+// Exceeds OmO's per-task scoped MCPs: adds attribution, guidance, and audit trail
+// without requiring runtime MCP lifecycle management.
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input?.cwd || process.cwd();
+const toolName = input?.tool_name || '';
+
+const match = toolName.match(/^mcp__([^_]+(?:__[^_]+)*)__/);
+if (!match) process.exit(0);
+const mcpServer = match[1].replace(/__/g, '-');
+
+const workflowPath = join(cwd, '.cx', 'workflow.json');
+if (!existsSync(workflowPath)) process.exit(0);
+
+try {
+  const wf = JSON.parse(readFileSync(workflowPath, 'utf8'));
+  const activeTaskKey = wf.currentTaskKey;
+  if (!activeTaskKey) process.exit(0);
+
+  const task = (wf.tasks || []).find(t => t.key === activeTaskKey);
+  if (!task?.mcpScope || task.mcpScope.length === 0) process.exit(0);
+
+  const scope = task.mcpScope;
+  const inScope = scope.some(s => mcpServer.includes(s) || s.includes(mcpServer));
+
+  if (!inScope) {
+    process.stderr.write(
+      `[mcp-scope] ${mcpServer} is not in mcpScope for task "${activeTaskKey}".\n` +
+      `[mcp-scope] Declared scope: ${scope.join(', ')}. Proceeding — verify this call is intentional.\n`
+    );
+  }
+} catch { /* best effort */ }
+
+process.exit(0);

package/lib/hooks/model-fallback.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/model-fallback.mjs — Model fallback hook — reroutes requests when the primary model is unavailable.
+ *
+ * Runs as PostToolUse when model calls fail. Reads the error, selects a fallback provider from the model router, and retries the request with the alternate model.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { readOpenRouterApiKeyFromOpenCodeConfig } from '../model-router.mjs';
+
+const RATE_LIMIT_PATTERNS = [
+  /\b429\b/i,
+  /rate limit/i,
+  /usage limits?/i,
+  /specified API usage limits?/i,
+  /regain access/i,
+  /weekly limit/i,
+  /monthly limit/i,
+  /daily limit/i,
+  /too many requests/i,
+  /quota exceeded/i,
+  /model unavailable/i,
+  /model.*overloaded/i,
+  /timeout/i,
+  /timed out/i,
+  /ETIMEDOUT/i,
+  /ECONNRESET/i,
+];
+
+const COOLDOWN_MS = 10 * 60 * 1000;
+const statePath = join(homedir(), '.cx', 'construct-model-fallback.json');
+
+function readInput() {
+  try {
+    const raw = readFileSync(0, 'utf8');
+    return raw ? JSON.parse(raw) : {};
+  } catch {
+    return {};
+  }
+}
+
+function flatten(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value === 'string') return value;
+  if (typeof value === 'number' || typeof value === 'boolean') return String(value);
+  if (Array.isArray(value)) return value.map(flatten).join('\n');
+  if (typeof value === 'object') return Object.values(value).map(flatten).join('\n');
+  return '';
+}
+
+function recentlyApplied(now) {
+  try {
+    const state = JSON.parse(readFileSync(statePath, 'utf8'));
+    return typeof state.lastAppliedAt === 'number' && now - state.lastAppliedAt < COOLDOWN_MS;
+  } catch {
+    return false;
+  }
+}
+
+function writeState(payload) {
+  mkdirSync(dirname(statePath), { recursive: true });
+  writeFileSync(statePath, JSON.stringify(payload, null, 2));
+}
+
+const input = readInput();
+const haystack = flatten(input);
+if (!RATE_LIMIT_PATTERNS.some((pattern) => pattern.test(haystack))) process.exit(0);
+
+const now = Date.now();
+if (recentlyApplied(now)) {
+  process.stderr.write('[model-fallback] Rate limit/timeout detected; fallback recently applied, skipping cooldown window.\n');
+  process.exit(0);
+}
+
+const toolkitDir = process.env.CX_TOOLKIT_DIR || join(homedir(), '.construct');
+const constructBin = join(toolkitDir, 'bin', 'construct');
+
+if (!existsSync(constructBin)) {
+  process.stderr.write(`[model-fallback] construct binary not found at ${constructBin}\n`);
+  process.exit(0);
+}
+
+const openRouterApiKey = process.env.OPENROUTER_API_KEY || readOpenRouterApiKeyFromOpenCodeConfig();
+
+if (!openRouterApiKey) {
+  process.stderr.write('[model-fallback] Rate limit/timeout detected; no OpenRouter API key found in OPENROUTER_API_KEY or OpenCode config, so automatic fallback cannot poll models.\n');
+  process.exit(0);
+}
+
+try {
+  process.stderr.write('[model-fallback] Rate limit/timeout detected. Running construct models --apply.\n');
+  execFileSync(constructBin, ['models', '--apply'], {
+    cwd: toolkitDir,
+    stdio: 'inherit',
+    env: { ...process.env, CX_TOOLKIT_DIR: toolkitDir, OPENROUTER_API_KEY: openRouterApiKey },
+    timeout: 120_000,
+  });
+  writeState({ lastAppliedAt: now, reason: 'rate-limit-or-timeout' });
+} catch (error) {
+  process.stderr.write(`[model-fallback] Fallback failed: ${error.message}\n`);
+}
+
+process.exit(0);

package/lib/hooks/pre-compact.mjs

@@ -0,0 +1,212 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/pre-compact.mjs — Pre-compact hook — prepares context summary before compaction runs.
+ *
+ * Runs before context compaction. Writes a structured summary of active workflow, context state, and pending tasks to preserve continuity across the compaction boundary.
+ */
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { writeContextState } from '../context-state.mjs';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input?.cwd || process.cwd();
+const transcriptPath = input?.transcript_path || '';
+
+const filesChanged = [];
+const decisions = [];
+const pendingTodos = [];
+const workflowTasks = [];
+const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
+const efficiencyPath = join(homedir(), '.cx', 'session-efficiency.json');
+let lastSummary = '';
+
+if (transcriptPath && existsSync(transcriptPath)) {
+  try {
+    const transcriptRaw = readFileSync(transcriptPath, 'utf8');
+    let transcript;
+    try {
+      transcript = JSON.parse(transcriptRaw);
+    } catch {
+      transcript = transcriptRaw
+        .split('\n')
+        .filter(Boolean)
+        .map((line) => {
+          try { return JSON.parse(line); } catch { return null; }
+        })
+        .filter(Boolean);
+    }
+    const messages = Array.isArray(transcript) ? transcript : (transcript.messages || []);
+    const recent = messages.slice(-60);
+
+    // Track the latest TodoWrite call to get current todo state
+    let latestTodos = null;
+
+    for (const msg of recent) {
+      if (msg.role === 'tool' || msg.type === 'tool_result') continue;
+
+      // Handle both array-of-blocks and plain-string content formats
+      const blocks = Array.isArray(msg.content)
+        ? msg.content
+        : (typeof msg.content === 'string' ? [{ type: 'text', text: msg.content }] : []);
+
+      for (const block of blocks) {
+        if (block.type === 'tool_use' && (block.name === 'Write' || block.name === 'Edit')) {
+          const fp = block.input?.file_path || block.input?.path || '';
+          if (fp && !filesChanged.includes(fp)) filesChanged.push(fp);
+        }
+        if (block.type === 'tool_use' && block.name === 'TodoWrite') {
+          const todos = block.input?.todos;
+          if (Array.isArray(todos)) latestTodos = todos;
+        }
+        if (block.type === 'text' && msg.role === 'assistant') {
+          const text = (block.text || '').trim();
+          // Prefer the last substantive response (>80 chars) over short one-liners
+          if (text.length > 80 || (!lastSummary && text.length > 0)) {
+            lastSummary = text.slice(0, 400);
+          }
+          const decisionMatches = text.match(/(?:^|\n)(?:DECISION:|Decision:|\*\*Decision\*\*:)\s*([^\n]+)/g) || [];
+          for (const match of decisionMatches) {
+            const cleaned = match.replace(/^\n?/, '').replace(/^(?:DECISION:|Decision:|\*\*Decision\*\*:)\s*/, '').trim();
+            if (cleaned && !decisions.includes(cleaned)) decisions.push(cleaned);
+          }
+        }
+      }
+    }
+
+    // Extract pending/in_progress todos from latest TodoWrite
+    if (latestTodos) {
+      for (const todo of latestTodos) {
+        if (todo.status === 'pending' || todo.status === 'in_progress') {
+          pendingTodos.push(todo);
+        }
+      }
+    }
+
+    // Extract active workflow tasks from .cx/workflow.json
+    const workflowPath = join(cwd, '.cx', 'workflow.json');
+    if (existsSync(workflowPath)) {
+      try {
+        const wf = JSON.parse(readFileSync(workflowPath, 'utf8'));
+        const tasks = wf?.tasks || wf?.state?.tasks || [];
+        for (const task of tasks) {
+          if (task.status !== 'done' && task.status !== 'skipped') {
+            workflowTasks.push({ key: task.key || task.id, title: task.title || task.description || '' });
+          }
+        }
+      } catch { /* best effort */ }
+    }
+  } catch { /* best effort */ }
+}
+
+const warnFlags = (() => {
+  try { return readFileSync(warnFlagsPath, 'utf8').trim(); } catch { return ''; }
+})();
+
+const efficiencySummary = (() => {
+  try {
+    const stats = JSON.parse(readFileSync(efficiencyPath, 'utf8'));
+    const parts = [
+      `${stats.readCount || 0} reads`,
+      `${stats.uniqueFileCount || 0} unique files`,
+    ];
+    if (stats.repeatedReadCount) parts.push(`${stats.repeatedReadCount} repeated reads`);
+    if (stats.largeReadCount) parts.push(`${stats.largeReadCount} large reads`);
+    if (stats.totalBytesRead) parts.push(`${Math.round(stats.totalBytesRead / 1024)} KB read`);
+    return parts.join(' · ');
+  } catch {
+    return '';
+  }
+})();
+
+const projectName = cwd.split('/').pop() || 'project';
+const date = new Date().toISOString().slice(0, 16).replace('T', ' ');
+
+const contextLines = [
+  `# Session Context`,
+  `Last saved: ${date}`,
+  ``,
+  `## What was in progress`,
+  lastSummary || '(no summary available)',
+  ``,
+];
+
+if (filesChanged.length) {
+  contextLines.push('## Files changed this session');
+  for (const f of filesChanged.slice(0, 20)) contextLines.push(`- ${f}`);
+  contextLines.push('');
+}
+
+if (decisions.length) {
+  contextLines.push('## Decisions captured');
+  for (const decision of decisions.slice(-10)) contextLines.push(`- ${decision}`);
+  contextLines.push('');
+}
+
+if (pendingTodos.length) {
+  contextLines.push('## Pending TODOs');
+  for (const todo of pendingTodos) {
+    const status = todo.status === 'in_progress' ? '[~]' : '[ ]';
+    contextLines.push(`${status} ${todo.content || todo.title || todo.text || JSON.stringify(todo)}`);
+  }
+  contextLines.push('');
+}
+
+if (workflowTasks.length) {
+  contextLines.push('## Active workflow tasks');
+  for (const task of workflowTasks.slice(0, 10)) {
+    contextLines.push(`- ${task.key}: ${task.title}`);
+  }
+  contextLines.push('');
+}
+
+if (efficiencySummary) {
+  contextLines.push('## Session efficiency snapshot');
+  contextLines.push(efficiencySummary);
+  contextLines.push('');
+}
+
+contextLines.push('## Open issues');
+contextLines.push(warnFlags || 'None');
+
+const content = contextLines.join('\n') + '\n';
+const contextJson = {
+  source: 'pre-compact',
+  projectName,
+  lastSummary,
+  filesChanged: filesChanged.slice(0, 20),
+  decisions: decisions.slice(-10),
+  pendingTodos: pendingTodos.slice(0, 20),
+  workflowTasks: workflowTasks.slice(0, 10),
+  efficiencySummary,
+  warnFlags: warnFlags || 'None',
+};
+
+const projectCxDir = join(cwd, '.cx');
+try { mkdirSync(projectCxDir, { recursive: true }); } catch { /* exists */ }
+try { writeContextState(cwd, { ...contextJson, contextSummary: lastSummary }, { markdown: content }); } catch { /* best effort */ }
+if (decisions.length) {
+  const decisionsDir = join(projectCxDir, 'decisions');
+  const slug = `${date.replace(/[^0-9]/g, '')}-session-decisions`;
+  const decisionDoc = [
+    '# Session Decisions',
+    `Captured: ${date}`,
+    '',
+    '## Decisions',
+    ...decisions.slice(-10).map((decision) => `- ${decision}`),
+    '',
+    '## Files changed',
+    ...(filesChanged.length ? filesChanged.slice(0, 20).map((file) => `- ${file}`) : ['- None captured']),
+    '',
+  ].join('\n');
+  try { mkdirSync(decisionsDir, { recursive: true }); } catch { /* exists */ }
+  try { writeFileSync(join(decisionsDir, `${slug}.md`), decisionDoc); } catch { /* best effort */ }
+}
+
+const globalCxDir = join(homedir(), '.cx');
+try { mkdirSync(globalCxDir, { recursive: true }); } catch { /* exists */ }
+try { writeContextState(homedir(), { ...contextJson, contextSummary: lastSummary }, { markdown: content }); } catch { /* best effort */ }
+
+process.exit(0);

package/lib/hooks/pre-push-gate.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * pre-push-gate.mjs — PreToolUse / Bash
+ *
+ * Intercepts `git push` commands. Detects available test and build scripts
+ * in the project, runs them in parallel, and blocks the push if either fails.
+ * Silent and instant when there's nothing to run.
+ */
+import { readFileSync, existsSync } from 'fs';
+import { execSync, spawnSync } from 'child_process';
+import { dirname, join } from 'path';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { /* no stdin */ }
+
+// Must always echo stdin for PreToolUse chaining
+const echo = () => { process.stdout.write(JSON.stringify(input) + '\n'); process.exit(0); };
+
+const command = input?.tool_input?.command || input?.command || '';
+
+// Only act on git push
+if (!/\bgit\s+push\b/.test(command)) { echo(); }
+
+// Find nearest package.json / Cargo.toml / pyproject.toml from cwd
+const cwd = input?.cwd || process.cwd();
+
+function findUp(filename, from) {
+  let dir = from;
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, filename);
+    if (existsSync(candidate)) return { path: candidate, dir };
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// ── Node/npm project ──────────────────────────────────────────────────────────
+function runNpmGate(projectDir) {
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(join(projectDir, 'package.json'), 'utf8')); } catch { return null; }
+
+  const scripts = pkg.scripts || {};
+  const hasTest  = !!(scripts.test  && !scripts.test.includes('no test specified'));
+  const hasBuild = !!(scripts.build);
+  const hasCi    = !!(scripts['test:ci'] || scripts['test:run']);
+
+  const testScript  = scripts['test:ci'] ? 'test:ci' : scripts['test:run'] ? 'test:run' : 'test';
+  const runner = existsSync(join(projectDir, 'pnpm-lock.yaml')) ? 'pnpm'
+               : existsSync(join(projectDir, 'yarn.lock'))      ? 'yarn'
+               : 'npm';
+
+  const jobs = [];
+  if (hasTest || hasCi) jobs.push({ label: 'tests',  cmd: runner, args: ['run', testScript], timeout: 90_000 });
+  if (hasBuild)         jobs.push({ label: 'build',  cmd: runner, args: ['run', 'build'],    timeout: 120_000 });
+
+  return { projectDir, jobs };
+}
+
+// ── Rust/Cargo project ────────────────────────────────────────────────────────
+function runCargoGate(projectDir) {
+  const jobs = [
+    { label: 'tests', cmd: 'cargo', args: ['test', '--quiet'], timeout: 120_000 },
+    { label: 'build', cmd: 'cargo', args: ['build', '--quiet'], timeout: 120_000 },
+  ];
+  return { projectDir, jobs };
+}
+
+// ── Python project ────────────────────────────────────────────────────────────
+function runPythonGate(projectDir) {
+  const hasPytest = (() => { try { execSync('pytest --version', { stdio: 'pipe', timeout: 3000 }); return true; } catch { return false; } })();
+  if (!hasPytest) return null;
+  const jobs = [{ label: 'tests', cmd: 'pytest', args: ['--tb=short', '-q'], timeout: 90_000 }];
+  return { projectDir, jobs };
+}
+
+// Detect project type
+let gate = null;
+const npm     = findUp('package.json', cwd);
+const cargo   = findUp('Cargo.toml', cwd);
+const pyproj  = findUp('pyproject.toml', cwd) || findUp('setup.py', cwd);
+
+if (npm)    gate = runNpmGate(npm.dir);
+else if (cargo)  gate = runCargoGate(cargo.dir);
+else if (pyproj) gate = runPythonGate(pyproj.dir);
+
+// Nothing to check
+if (!gate || gate.jobs.length === 0) { echo(); }
+
+// Run jobs in parallel via Promise.all simulation (spawnSync is synchronous — run sequentially)
+// For true parallel, we use spawnSync with a short timeout and report errors
+const failures = [];
+
+for (const job of gate.jobs) {
+  const result = spawnSync(job.cmd, job.args, {
+    cwd: gate.projectDir,
+    encoding: 'utf8',
+    timeout: job.timeout,
+    stdio: 'pipe',
+    env: { ...process.env, CI: '1', FORCE_COLOR: '0' },
+  });
+
+  if (result.status !== 0 || result.error) {
+    const stderr = (result.stderr || '').trim();
+    const stdout = (result.stdout || '').trim();
+    const detail = stderr || stdout;
+    // Extract first meaningful error line (skip blank, generic lines)
+    const firstError = detail.split('\n')
+      .map(l => l.trim())
+      .filter(l => l && !/^>/.test(l) && !/^\s*at /.test(l))
+      .slice(0, 3)
+      .join(' · ');
+
+    failures.push({ label: job.label, detail: firstError || `exited ${result.status}` });
+  }
+}
+
+if (failures.length === 0) { echo(); }
+
+// Block the push
+const summary = failures
+  .map(f => `${f.label} failed — ${f.detail}`)
+  .join('\n');
+
+process.stderr.write(
+  `[pre-push-gate] Push blocked — fix these before pushing:\n${summary}\n\nRun the failing checks locally, then push again.\n`
+);
+process.exit(2);

package/lib/hooks/read-tracker.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/read-tracker.mjs — Read tracker hook — tracks file reads for efficiency analysis.
+ *
+ * Runs as PostToolUse after Read tool calls. Logs each read to ~/.cx/read-log.json including file path, line count, and session timestamp for efficiency reporting.
+ */
+// PostToolUse(Read) — records file content hash after each Read call
+// Powers hash-staleness check in edit-guard.mjs
+import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+
+const CX_DIR = join(homedir(), '.cx');
+const HASH_STORE = join(CX_DIR, 'file-hashes.json');
+const EFFICIENCY_STORE = join(CX_DIR, 'session-efficiency.json');
+const WARN_FLAGS = join(CX_DIR, 'warn-flags.txt');
+const SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
+const REPEATED_READ_WARNING_THRESHOLD = 5;
+const LARGE_READ_WARNING_THRESHOLD = 3;
+const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
+
+function loadEfficiencyStats(nowIso) {
+  const fresh = {
+    sessionStartedAt: nowIso,
+    lastUpdatedAt: nowIso,
+    readCount: 0,
+    uniqueFileCount: 0,
+    repeatedReadCount: 0,
+    largeReadCount: 0,
+    totalBytesRead: 0,
+    warnings: {},
+    files: {},
+  };
+
+  try {
+    const existing = JSON.parse(readFileSync(EFFICIENCY_STORE, 'utf8'));
+    const lastUpdated = new Date(existing.lastUpdatedAt || 0).getTime();
+    if (!lastUpdated || Date.now() - lastUpdated > SESSION_IDLE_RESET_MS) return fresh;
+    return { ...fresh, ...existing, warnings: existing.warnings || {}, files: existing.files || {} };
+  } catch {
+    return fresh;
+  }
+}
+
+function appendWarning(message) {
+  try { appendFileSync(WARN_FLAGS, `${message}\n`); } catch { /* best effort */ }
+}
+
+function topRepeatedPath(files) {
+  return Object.entries(files || {})
+    .map(([filePath, value]) => ({ filePath, count: Number(value?.count || 0) }))
+    .filter((entry) => entry.count > 1)
+    .sort((a, b) => b.count - a.count || a.filePath.localeCompare(b.filePath))[0];
+}
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+if ((input?.tool_name || '') !== 'Read') process.exit(0);
+
+const rawPath = input?.tool_input?.file_path || '';
+if (!rawPath) process.exit(0);
+
+const absPath = rawPath.startsWith('/') ? rawPath : resolve(input?.cwd || process.cwd(), rawPath);
+if (!existsSync(absPath)) process.exit(0);
+
+try {
+  const content = readFileSync(absPath, 'utf8');
+  const hash = createHash('sha256').update(content).digest('hex').slice(0, 16);
+  const nowIso = new Date().toISOString();
+  const requestedLimit = Number(input?.tool_input?.limit || 0);
+  const effectiveLimit = requestedLimit > 0 ? requestedLimit : 2000;
+  const isLargeRead = effectiveLimit > 400;
+
+  mkdirSync(CX_DIR, { recursive: true });
+  let store = {};
+  try { store = JSON.parse(readFileSync(HASH_STORE, 'utf8')); } catch { /* fresh */ }
+
+  store[absPath] = { hash, ts: nowIso, size: content.length };
+
+  // Prune entries older than 2 hours
+  const cutoff = Date.now() - 2 * 60 * 60 * 1000;
+  for (const [k, v] of Object.entries(store)) {
+    if (new Date(v.ts).getTime() < cutoff) delete store[k];
+  }
+
+  writeFileSync(HASH_STORE, JSON.stringify(store, null, 2));
+
+  const stats = loadEfficiencyStats(nowIso);
+  const existingFile = stats.files[absPath];
+  stats.readCount += 1;
+  stats.totalBytesRead += content.length;
+  if (isLargeRead) stats.largeReadCount += 1;
+  if (existingFile) {
+    stats.repeatedReadCount += 1;
+  } else {
+    stats.uniqueFileCount += 1;
+  }
+  stats.files[absPath] = {
+    count: (existingFile?.count || 0) + 1,
+    size: content.length,
+    lastReadAt: nowIso,
+    lastRequestedLimit: effectiveLimit,
+  };
+
+  if (stats.repeatedReadCount >= REPEATED_READ_WARNING_THRESHOLD && !stats.warnings.repeatedReads) {
+    const top = topRepeatedPath(stats.files);
+    const topNote = top ? ` Top repeat: ${top.filePath} (${top.count}x).` : '';
+    appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session.${topNote} Use rg or construct distill before re-reading more files.`);
+    stats.warnings.repeatedReads = nowIso;
+  }
+
+  if (stats.largeReadCount >= LARGE_READ_WARNING_THRESHOLD && !stats.warnings.largeReads) {
+    appendWarning(`Efficiency: ${stats.largeReadCount} large reads this session — prefer rg/glob plus targeted reads under 400 lines.`);
+    stats.warnings.largeReads = nowIso;
+  }
+
+  if (stats.totalBytesRead >= TOTAL_BYTES_WARNING_THRESHOLD && !stats.warnings.totalBytes) {
+    appendWarning(`Efficiency: ${Math.round(stats.totalBytesRead / 1024)} KB read this session — consider distill/query-focused retrieval or compact context before continuing.`);
+    stats.warnings.totalBytes = nowIso;
+  }
+
+  stats.lastUpdatedAt = nowIso;
+
+  writeFileSync(EFFICIENCY_STORE, JSON.stringify(stats, null, 2));
+} catch { /* best effort */ }
+
+process.exit(0);