@geraldmaron/construct 1.0.0

package/lib/hooks/dep-audit.mjs

@@ -0,0 +1,155 @@
+#!/usr/bin/env node
+/**
+ * dep-audit.mjs — PostToolUse / Write|Edit (async)
+ *
+ * After editing a dependency manifest, runs the appropriate audit tool and
+ * appends critical/high vulnerabilities to ~/.cx/warn-flags.txt.
+ * Silent when nothing is wrong. Runs async so it never blocks editing.
+ */
+import { readFileSync, writeFileSync, existsSync, appendFileSync } from 'fs';
+import { execSync } from 'child_process';
+import { homedir } from 'os';
+import { join, dirname, basename } from 'path';
+
+const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
+if (!filePath) process.exit(0);
+
+const file = basename(filePath);
+const MANIFESTS = new Set(['package.json', 'Cargo.toml', 'pyproject.toml', 'requirements.txt', 'go.mod', 'go.sum']);
+if (!MANIFESTS.has(file)) process.exit(0);
+
+// Skip node_modules, dist, build, .git
+if (/node_modules|\/dist\/|\/build\/|\/\.git\//.test(filePath)) process.exit(0);
+
+const projectDir = dirname(filePath);
+const warnFlagsPath = join(homedir(), '.cx', 'warn-flags.txt');
+
+function appendWarn(msg) {
+  try { appendFileSync(warnFlagsPath, msg + '\n'); } catch { /* best effort */ }
+  process.stderr.write(`[dep-audit] ${msg}\n`);
+}
+
+// ── npm / yarn / pnpm ─────────────────────────────────────────────────────────
+if (file === 'package.json') {
+  // Skip if this is a workspace root with no dependencies of its own
+  let pkg;
+  try { pkg = JSON.parse(readFileSync(filePath, 'utf8')); } catch { process.exit(0); }
+  const hasDeps = !!(pkg.dependencies || pkg.devDependencies);
+  if (!hasDeps) process.exit(0);
+
+  const runner = existsSync(join(projectDir, 'pnpm-lock.yaml')) ? 'pnpm'
+               : existsSync(join(projectDir, 'yarn.lock'))      ? 'yarn'
+               : 'npm';
+
+  try {
+    // npm/pnpm: --audit-level=high exits non-zero if high/critical found
+    // yarn: audit --level high
+    const auditCmd = runner === 'yarn'
+      ? 'yarn audit --level high --json'
+      : `${runner} audit --audit-level=high --json`;
+
+    const output = execSync(auditCmd, {
+      cwd: projectDir,
+      stdio: 'pipe',
+      timeout: 30_000,
+      env: { ...process.env },
+    }).toString();
+
+    // Parse npm/pnpm JSON output for vuln count
+    const lines = output.split('\n').filter(Boolean);
+    for (const line of lines) {
+      try {
+        const obj = JSON.parse(line);
+        const vulns = obj?.metadata?.vulnerabilities;
+        if (vulns) {
+          const critical = vulns.critical || 0;
+          const high = vulns.high || 0;
+          if (critical > 0 || high > 0) {
+            appendWarn(`Dependency vulnerabilities: ${critical} critical, ${high} high — run \`${runner} audit\` to review`);
+          }
+        }
+      } catch { /* non-JSON line */ }
+    }
+  } catch (e) {
+    // Non-zero exit = vulnerabilities found (for npm/pnpm without --json)
+    const stderr = (e.stderr?.toString() || '').trim();
+    const stdout = (e.stdout?.toString() || '').trim();
+    // Extract vuln summary line
+    const summary = (stdout + '\n' + stderr)
+      .split('\n')
+      .find(l => /vulnerabilit/i.test(l) || /critical|high/i.test(l));
+    if (summary) {
+      appendWarn(`Dependency vulnerabilities found — ${summary.trim()}`);
+    }
+  }
+  process.exit(0);
+}
+
+// ── Rust / Cargo ──────────────────────────────────────────────────────────────
+if (file === 'Cargo.toml') {
+  try {
+    execSync('cargo audit --version', { stdio: 'pipe', timeout: 3000 });
+  } catch {
+    process.exit(0); // cargo-audit not installed, skip silently
+  }
+
+  try {
+    execSync('cargo audit --deny warnings', {
+      cwd: projectDir,
+      stdio: 'pipe',
+      timeout: 30_000,
+    });
+  } catch (e) {
+    const output = (e.stdout?.toString() || '') + (e.stderr?.toString() || '');
+    const vulnLine = output.split('\n').find(l => /error|warning/i.test(l) && /vuln|advisory/i.test(l));
+    appendWarn(`Cargo vulnerabilities found — ${vulnLine?.trim() || 'run `cargo audit` to review'}`);
+  }
+  process.exit(0);
+}
+
+// ── Python ────────────────────────────────────────────────────────────────────
+if (file === 'pyproject.toml' || file === 'requirements.txt') {
+  try {
+    execSync('pip-audit --version', { stdio: 'pipe', timeout: 3000 });
+  } catch {
+    process.exit(0); // pip-audit not installed
+  }
+
+  const target = file === 'requirements.txt'
+    ? `pip-audit -r "${filePath}" --format json`
+    : `pip-audit --format json`;
+
+  try {
+    execSync(target, { cwd: projectDir, stdio: 'pipe', timeout: 30_000 });
+  } catch (e) {
+    const output = (e.stdout?.toString() || '');
+    try {
+      const result = JSON.parse(output);
+      const count = Array.isArray(result) ? result.length : (result.dependencies?.filter(d => d.vulns?.length)?.length || 0);
+      if (count > 0) appendWarn(`Python dependency vulnerabilities: ${count} package${count !== 1 ? 's' : ''} affected — run \`pip-audit\` to review`);
+    } catch {
+      appendWarn('Python dependency vulnerabilities found — run `pip-audit` to review');
+    }
+  }
+  process.exit(0);
+}
+
+// ── Go ────────────────────────────────────────────────────────────────────────
+if (file === 'go.mod' || file === 'go.sum') {
+  try {
+    execSync('govulncheck -version', { stdio: 'pipe', timeout: 3000 });
+  } catch {
+    process.exit(0); // govulncheck not installed
+  }
+
+  try {
+    execSync('govulncheck ./...', { cwd: projectDir, stdio: 'pipe', timeout: 30_000 });
+  } catch (e) {
+    const output = (e.stdout?.toString() || '') + (e.stderr?.toString() || '');
+    const vulnLine = output.split('\n').find(l => /Vulnerability|vuln/i.test(l));
+    appendWarn(`Go dependency vulnerabilities found — ${vulnLine?.trim() || 'run `govulncheck ./...` to review'}`);
+  }
+  process.exit(0);
+}
+
+process.exit(0);

package/lib/hooks/drive-guard.mjs

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/drive-guard.mjs — Drive guard hook — enforces that work/drive commands follow the orchestration policy.
+ *
+ * Runs as PreToolUse on Bash for construct do/drive commands. Validates that the requested goal is routed through the orchestrator rather than bypassing the policy.
+ */
+// Stop hook — blocks session stop when drive mode is active and acceptance criteria lack evidence.
+// Reads .cx/drive-state.json (active loop manifest) + .cx/workflow.json (acceptance criteria).
+// Superior to OmO's boulder: tracks per-criterion evidence, iteration history, momentum score.
+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 driveStatePath = join(cwd, '.cx', 'drive-state.json');
+const workflowPath = join(cwd, '.cx', 'workflow.json');
+
+if (!existsSync(driveStatePath)) process.exit(0);
+
+let driveState = {};
+try { driveState = JSON.parse(readFileSync(driveStatePath, 'utf8')); } catch { process.exit(0); }
+
+if (!driveState.active || driveState.canStop) process.exit(0);
+
+// Collect all acceptance criteria from non-done workflow tasks
+let allCriteria = [];
+let pendingTaskCount = 0;
+try {
+  const wf = JSON.parse(readFileSync(workflowPath, 'utf8'));
+  const activeTasks = (wf.tasks || []).filter(t => t.status !== 'done' && t.status !== 'skipped');
+  pendingTaskCount = activeTasks.length;
+  for (const t of activeTasks) {
+    for (const c of (t.acceptanceCriteria || [])) {
+      if (!allCriteria.includes(c)) allCriteria.push(c);
+    }
+  }
+} catch { /* no workflow — rely on todo count */ }
+
+const criteriaStatus = driveState.criteriaStatus || {};
+const metCriteria = allCriteria.filter(c => criteriaStatus[c]?.met);
+const unmetCriteria = allCriteria.filter(c => !criteriaStatus[c]?.met);
+const pendingTodos = driveState.pendingTodos || 0;
+const iteration = driveState.iteration || 1;
+const momentum = driveState.momentumScore != null ? Math.round(driveState.momentumScore * 100) : null;
+
+// Decide whether to block
+const hasPendingWork = (unmetCriteria.length > 0) || (allCriteria.length === 0 && (pendingTodos > 0 || pendingTaskCount > 0));
+
+if (!hasPendingWork) {
+  // All criteria met or no criteria defined and no pending work — allow stop
+  process.exit(0);
+}
+
+// Emit rich drive-state report
+const lines = [
+  `[drive-guard] Drive mode active — iteration ${iteration}. Cannot stop yet.`,
+  '',
+];
+
+if (unmetCriteria.length > 0) {
+  lines.push(`Unmet criteria (${unmetCriteria.length}/${allCriteria.length}):`);
+  for (const c of unmetCriteria) lines.push(`  ✗ ${c}`);
+  lines.push('');
+}
+
+if (metCriteria.length > 0) {
+  lines.push(`Verified criteria (${metCriteria.length}/${allCriteria.length}):`);
+  for (const c of metCriteria) {
+    const ev = criteriaStatus[c]?.evidence || 'recorded';
+    lines.push(`  ✓ ${c} — ${ev.slice(0, 80)}`);
+  }
+  lines.push('');
+}
+
+if (allCriteria.length === 0) {
+  lines.push(`Remaining tasks: ${pendingTodos} todos, ${pendingTaskCount} workflow tasks`);
+  lines.push('');
+}
+
+if (momentum != null) lines.push(`Momentum: ${momentum}% (iteration ${iteration})`);
+
+lines.push('');
+lines.push(`[drive-guard] Record evidence by updating .cx/drive-state.json criteriaStatus, then criteria will pass.`);
+lines.push(`[drive-guard] To mark a criterion met: set criteriaStatus["<criterion>"] = { met: true, evidence: "..." }`);
+
+process.stderr.write(lines.join('\n') + '\n');
+process.exit(2);

package/lib/hooks/edit-accumulator.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/edit-accumulator.mjs — Edit accumulator hook — batches and summarizes recent file edits for context.
+ *
+ * Runs as PostToolUse after Edit/Write. Maintains a rolling log of recent edits in ~/.cx/edit-log.json for use by other hooks and efficiency reporting.
+ */
+import { appendFileSync, readFileSync, writeFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+
+const TS_EXTS = new Set(['.ts','.tsx','.js','.mjs','.jsx','.cjs']);
+const filePath = process.env.TOOL_INPUT_FILE_PATH || '';
+
+if (!filePath) process.exit(0);
+
+const ext = '.' + filePath.split('.').pop();
+const home = homedir();
+const countPath = `${home}/.cx/files-changed-count.txt`;
+
+// Always increment the total files-changed counter for notify
+try {
+  const current = existsSync(countPath) ? parseInt(readFileSync(countPath, 'utf8').trim() || '0', 10) : 0;
+  writeFileSync(countPath, String(current + 1));
+} catch { /* best effort */ }
+
+// Only accumulate TS/JS files for typecheck
+if (!TS_EXTS.has(ext)) process.exit(0);
+
+const tcPath = `${home}/.cx/pending-typecheck.txt`;
+try {
+  const existing = existsSync(tcPath) ? readFileSync(tcPath, 'utf8').split('\n').filter(Boolean) : [];
+  if (!existing.includes(filePath)) {
+    appendFileSync(tcPath, filePath + '\n');
+  }
+} catch { /* best effort */ }
+
+process.exit(0);

package/lib/hooks/edit-error-recovery.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/edit-error-recovery.mjs — Edit error recovery hook — recovers from failed edit attempts and suggests fixes.
+ *
+ * Runs as PostToolUse when Edit tool returns an error. Reads the error and provides a targeted fix suggestion based on the error type (e.g., old_string not found).
+ */
+import { readFileSync } from 'fs';
+
+const EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit']);
+const EDIT_FAILURE_PATTERNS = [
+  'no match found', 'string not found', 'old_string not found',
+  'file not found', 'no such file', 'cannot find',
+  'already exists', 'permission denied', 'eacces', 'enoent',
+  'content mismatch', 'conflict', 'stale',
+];
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const toolName = input?.tool_name || '';
+if (!EDIT_TOOLS.has(toolName)) process.exit(0);
+
+const errorText = (
+  input?.error || input?.message ||
+  (input?.tool_response ? JSON.stringify(input.tool_response) : '') || ''
+).toLowerCase();
+
+const isEditFailure = EDIT_FAILURE_PATTERNS.some(p => errorText.includes(p));
+if (!isEditFailure) process.exit(0);
+
+const filePath = input?.tool_input?.file_path || input?.tool_input?.path || '';
+
+process.stdout.write([
+  ``,
+  `✗ ${toolName} failed${filePath ? ` on ${filePath}` : ''}.`,
+  ``,
+  `Recovery steps:`,
+  `1. Re-read the file with Read before retrying — content may have changed since your last read`,
+  `2. Use a longer old_string with 3-5 lines of surrounding context to make the match unique`,
+  `3. Check exact whitespace and indentation — tabs vs spaces matter`,
+  `4. If the file doesn't exist yet, use Write instead of Edit`,
+  `5. If getting "already exists" on Write, read the file first and use Edit`,
+  ``,
+].join('\n'));
+
+process.exit(0);

package/lib/hooks/edit-guard.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/edit-guard.mjs — Edit guard hook — validates old_string exists in target file before allowing edits.
+ *
+ * Runs as PreToolUse on Edit. Re-reads the target file and checks that old_string is present to prevent no-op or mismatched edits. Exits 2 (block) when not found.
+ */
+// PreToolUse(Edit|MultiEdit|Write) — hash-anchored edit verification
+// Blocks Edit/MultiEdit when old_string is not found verbatim in the file.
+// Warns (non-blocking) on hash staleness when file changed since last Read.
+import { readFileSync, existsSync } from 'fs';
+import { createHash } from 'crypto';
+import { join, resolve } from 'path';
+import { homedir } from 'os';
+
+const HASH_STORE = join(homedir(), '.cx', 'file-hashes.json');
+
+function storedHash(absPath) {
+  try {
+    const store = JSON.parse(readFileSync(HASH_STORE, 'utf8'));
+    return store[absPath] || null;
+  } catch { return null; }
+}
+
+function fileHash(content) {
+  return createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const toolName = input?.tool_name || '';
+const ti = input?.tool_input || {};
+const cwd = input?.cwd || process.cwd();
+
+function absOf(p) { return p.startsWith('/') ? p : resolve(cwd, p); }
+
+if (toolName === 'Edit') {
+  const { file_path, old_string } = ti;
+  if (!file_path || !old_string) process.exit(0);
+
+  const abs = absOf(file_path);
+  let content;
+  try { content = readFileSync(abs, 'utf8'); } catch { process.exit(0); }
+
+  // Hard block: old_string must exist verbatim
+  if (!content.includes(old_string)) {
+    const preview = old_string.split('\n').slice(0, 3).map(l => l.trimEnd()).join('↵');
+    process.stderr.write(
+      `[edit-guard] BLOCKED: old_string not found in ${file_path}\n` +
+      `[edit-guard] Preview: "${preview.slice(0, 120)}"\n` +
+      `[edit-guard] Fix: re-read the file, copy the exact text including whitespace.\n`
+    );
+    process.exit(2);
+  }
+
+  // Soft warn: hash mismatch means file changed since last Read
+  const stored = storedHash(abs);
+  if (stored && stored.hash !== fileHash(content)) {
+    process.stderr.write(
+      `[edit-guard] WARNING: ${file_path} changed since last Read (hash ${stored.hash} → ${fileHash(content)}). ` +
+      `old_string found — proceeding.\n`
+    );
+  }
+}
+
+if (toolName === 'MultiEdit') {
+  const { file_path, edits } = ti;
+  if (!file_path || !Array.isArray(edits)) process.exit(0);
+
+  const abs = absOf(file_path);
+  let content;
+  try { content = readFileSync(abs, 'utf8'); } catch { process.exit(0); }
+
+  const missing = edits.filter(e => e.old_string && !content.includes(e.old_string));
+  if (missing.length > 0) {
+    const previews = missing.map(e => `  • "${e.old_string.split('\n')[0].slice(0, 80)}"`).join('\n');
+    process.stderr.write(
+      `[edit-guard] BLOCKED: ${missing.length}/${edits.length} old_string(s) not found in ${file_path}\n` +
+      `${previews}\n` +
+      `[edit-guard] Re-read the file and use exact content from the current version.\n`
+    );
+    process.exit(2);
+  }
+
+  const stored = storedHash(abs);
+  if (stored && stored.hash !== fileHash(content)) {
+    process.stderr.write(`[edit-guard] WARNING: ${file_path} changed since last Read. old_strings verified — proceeding.\n`);
+  }
+}
+
+if (toolName === 'Write') {
+  const { file_path } = ti;
+  if (!file_path) process.exit(0);
+  const abs = absOf(file_path);
+  if (!existsSync(abs)) process.exit(0);
+
+  try {
+    const content = readFileSync(abs, 'utf8');
+    const stored = storedHash(abs);
+    if (stored && stored.hash !== fileHash(content)) {
+      process.stderr.write(
+        `[edit-guard] WARNING: ${file_path} was modified since last Read. ` +
+        `Verify this full-file Write is intentional — it will overwrite those changes.\n`
+      );
+    }
+  } catch { /* best effort */ }
+}
+
+process.exit(0);

package/lib/hooks/env-check.mjs

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * env-check.mjs — SessionStart
+ *
+ * Reads .env.example from the project root, compares against .env and
+ * process.env, and writes missing required vars to stdout so Claude sees
+ * them at session open. Silent when everything is in order.
+ */
+import { readFileSync, existsSync, realpathSync } from 'fs';
+import { fileURLToPath } from 'url';
+
+// Resolve symlinks immediately to avoid CJS/ESM loader edge cases during
+// rapid concurrent session-start hook invocations.
+try { realpathSync(fileURLToPath(import.meta.url)); } catch { /* non-critical */ }
+import { join } from 'path';
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { /* no stdin */ }
+
+const cwd = input?.cwd || process.cwd();
+
+// Find .env.example — project root only (don't walk up, avoid false positives)
+const examplePath = join(cwd, '.env.example');
+if (!existsSync(examplePath)) process.exit(0);
+
+// Parse both files into key sets
+function parseEnvFile(path) {
+  if (!existsSync(path)) return new Map();
+  const map = new Map();
+  const lines = readFileSync(path, 'utf8').split('\n');
+  for (const line of lines) {
+    const stripped = line.trim();
+    if (!stripped || stripped.startsWith('#')) continue;
+    const eq = stripped.indexOf('=');
+    if (eq === -1) continue;
+    const key = stripped.slice(0, eq).trim();
+    const val = stripped.slice(eq + 1).trim();
+    if (key) map.set(key, val);
+  }
+  return map;
+}
+
+const example = parseEnvFile(examplePath);
+if (example.size === 0) process.exit(0);
+
+const envFile = parseEnvFile(join(cwd, '.env'));
+
+// A key is "required" if its example value is a non-empty placeholder
+// (not already set to a real value — we don't block on keys with defaults)
+const PLACEHOLDER = /^(YOUR_|<|__|\$\{|REPLACE|ADD_|INSERT_|xxx|TODO)/i;
+const OPTIONAL_COMMENT = /#.*optional/i;
+
+function isRequired(key, exampleVal) {
+  // If value looks like a real default (not a placeholder), it's optional
+  if (!exampleVal) return true; // empty = required
+  if (PLACEHOLDER.test(exampleVal)) return true;
+  // If it has a real value in example, treat as optional with default
+  return false;
+}
+
+const missing = [];
+for (const [key, exampleVal] of example) {
+  if (!isRequired(key, exampleVal)) continue;
+  // Check .env file first, then process.env
+  const inEnvFile = envFile.has(key) && envFile.get(key) !== '' && !PLACEHOLDER.test(envFile.get(key));
+  const inProcessEnv = process.env[key] && !PLACEHOLDER.test(process.env[key]);
+  if (!inEnvFile && !inProcessEnv) {
+    missing.push(key);
+  }
+}
+
+if (missing.length === 0) process.exit(0);
+
+const noun = missing.length === 1 ? 'variable' : 'variables';
+const list = missing.map(k => `  - ${k}`).join('\n');
+process.stdout.write(
+  `## Environment check — ${missing.length} required ${noun} not set\n${list}\nAdd these to .env before running the app.\n`
+);
+
+process.exit(0);

package/lib/hooks/guard-bash.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/guard-bash.mjs — Guard bash hook — blocks dangerous shell commands from running unreviewed.
+ *
+ * Runs as PreToolUse on Bash. Scans the command against a blocklist of destructive patterns (rm -rf, force push to main, etc.) and exits 2 to block matches.
+ */
+import { createInterface } from 'readline';
+
+const BLOCK_PATTERNS = [
+  {
+    pattern: /rm\s+-[a-zA-Z]*r[a-zA-Z]*f\s+\/(?:\s|$)/,
+    reason: 'root filesystem deletion (rm -rf /)',
+  },
+  {
+    pattern: /git\s+push\s+(?:--force|-f)\s+\S+\s+(?:main|master)\b/,
+    reason: 'force push to main/master',
+  },
+  {
+    pattern: /:\(\)\s*\{.*:\|.*:.*&.*\}\s*;.*:/,
+    reason: 'fork bomb',
+  },
+  {
+    pattern: /\bDROP\s+(?:TABLE|DATABASE)\b/i,
+    reason: 'destructive DDL (DROP TABLE/DATABASE)',
+  },
+  {
+    pattern: /\bTRUNCATE\s+TABLE\b/i,
+    reason: 'destructive DDL (TRUNCATE TABLE)',
+  },
+  {
+    pattern: /sudo\s+rm\s+-[a-zA-Z]*r[a-zA-Z]*f\s+\/(?:etc|usr|var|boot)(?:\/|\s|$)/,
+    reason: 'sudo deletion of critical system directory',
+  },
+];
+
+const WARN_PATTERNS = [
+  {
+    pattern: /git\s+push\s+(?:--force|-f)(?!\s+\S+\s+(?:main|master)\b)/,
+    reason: 'force push (not targeting main/master — proceed with caution)',
+  },
+  {
+    pattern: /pip\s+install\s+--break-system-packages/,
+    reason: '--break-system-packages may corrupt system Python environment',
+  },
+];
+
+async function getCommand() {
+  const fromEnv = process.env.TOOL_INPUT_COMMAND;
+  if (fromEnv) return fromEnv;
+
+  return new Promise((resolve) => {
+    let data = '';
+    const rl = createInterface({ input: process.stdin });
+    rl.on('line', (line) => { data += line + '\n'; });
+    rl.on('close', () => {
+      try {
+        const parsed = JSON.parse(data);
+        resolve(parsed?.tool_input?.command ?? parsed?.command ?? '');
+      } catch {
+        resolve('');
+      }
+    });
+  });
+}
+
+const command = await getCommand();
+
+if (!command) process.exit(0);
+
+for (const { pattern, reason } of BLOCK_PATTERNS) {
+  if (pattern.test(command)) {
+    process.stderr.write(`[guard-bash] BLOCKED: ${reason}\nCommand: ${command.slice(0, 200)}\n`);
+    process.exit(2);
+  }
+}
+
+for (const { pattern, reason } of WARN_PATTERNS) {
+  if (pattern.test(command)) {
+    process.stderr.write(`[guard-bash] WARNING: ${reason}\nCommand: ${command.slice(0, 200)}\n`);
+  }
+}
+
+process.exit(0);

package/lib/hooks/mcp-audit.mjs

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/mcp-audit.mjs — MCP audit hook — logs all MCP tool calls for observability and review.
+ *
+ * Runs as PostToolUse on MCP tool calls. Records tool name, input, and output summary to ~/.cx/mcp-audit.json for telemetry and security review.
+ */
+// PostToolUse(mcp__*) — audits every MCP tool call against the active workflow task.
+// Writes .cx/mcp-audit.json: per-server call log with task attribution.
+// Gives per-task MCP usage visibility that per-task scoped MCPs (OmO) cannot provide.
+import { readFileSync, writeFileSync, mkdirSync, 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 mcpTool = match[2];
+
+// Get active task key from workflow
+let activeTaskKey = null;
+let activeTaskTitle = null;
+try {
+  const wf = JSON.parse(readFileSync(join(cwd, '.cx', 'workflow.json'), 'utf8'));
+  activeTaskKey = wf.currentTaskKey || null;
+  if (activeTaskKey) {
+    const t = (wf.tasks || []).find(t => t.key === activeTaskKey);
+    activeTaskTitle = t?.title || null;
+  }
+} catch { /* no workflow */ }
+
+const auditPath = join(cwd, '.cx', 'mcp-audit.json');
+let audit = {};
+try { audit = JSON.parse(readFileSync(auditPath, 'utf8')); } catch { /* fresh */ }
+
+if (!audit[mcpServer]) audit[mcpServer] = [];
+audit[mcpServer].push({
+  tool: mcpTool,
+  ts: new Date().toISOString(),
+  taskKey: activeTaskKey,
+  taskTitle: activeTaskTitle,
+});
+
+// Keep last 200 per server
+if (audit[mcpServer].length > 200) audit[mcpServer] = audit[mcpServer].slice(-200);
+
+try {
+  mkdirSync(join(cwd, '.cx'), { recursive: true });
+  writeFileSync(auditPath, JSON.stringify(audit, null, 2));
+} catch { /* best effort */ }
+
+process.exit(0);