@kontourai/flow-agents 0.1.1

package/context/scripts/hooks/lib/hook-flags.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+/**
+ * Shared hook enable/disable controls.
+ *
+ * Controls:
+ * - SA_HOOK_PROFILE=minimal|standard|strict (default: standard)
+ * - SA_DISABLED_HOOKS=comma,separated,hook,ids
+ */
+
+'use strict';
+
+const VALID_PROFILES = new Set(['minimal', 'standard', 'strict']);
+
+function normalizeId(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function getHookProfile() {
+  const raw = String(process.env.SA_HOOK_PROFILE || 'standard').trim().toLowerCase();
+  return VALID_PROFILES.has(raw) ? raw : 'standard';
+}
+
+function getDisabledHookIds() {
+  const raw = String(process.env.SA_DISABLED_HOOKS || '');
+  if (!raw.trim()) return new Set();
+  return new Set(raw.split(',').map(v => normalizeId(v)).filter(Boolean));
+}
+
+function parseProfiles(rawProfiles, fallback = ['standard', 'strict']) {
+  if (!rawProfiles) return [...fallback];
+  if (Array.isArray(rawProfiles)) {
+    const parsed = rawProfiles.map(v => String(v || '').trim().toLowerCase()).filter(v => VALID_PROFILES.has(v));
+    return parsed.length > 0 ? parsed : [...fallback];
+  }
+  const parsed = String(rawProfiles).split(',').map(v => v.trim().toLowerCase()).filter(v => VALID_PROFILES.has(v));
+  return parsed.length > 0 ? parsed : [...fallback];
+}
+
+function isHookEnabled(hookId, options = {}) {
+  const id = normalizeId(hookId);
+  if (!id) return true;
+  const disabled = getDisabledHookIds();
+  if (disabled.has(id)) return false;
+  const profile = getHookProfile();
+  const allowedProfiles = parseProfiles(options.profiles);
+  return allowedProfiles.includes(profile);
+}
+
+module.exports = { VALID_PROFILES, normalizeId, getHookProfile, getDisabledHookIds, parseProfiles, isHookEnabled };

package/context/scripts/hooks/lib/patterns.sh

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# patterns.sh — Shared detection patterns for governance audit
+# Compatible with bash 3.2+ (no associative arrays)
+
+# --- Secret patterns ---
+_detect_secrets() {
+  local text="$1"
+  local found=""
+  echo "$text" | grep -qE 'AKIA[A-Z0-9]{16}' 2>/dev/null && found="${found}aws_key "
+  echo "$text" | grep -qE 'ASIA[A-Z0-9]{16}' 2>/dev/null && found="${found}aws_sts "
+  echo "$text" | grep -qE '(secret|password|token|api[_-]?key)[[:space:]]*[:=][[:space:]]*["'"'"'][^"'"'"']{8,}' 2>/dev/null && found="${found}generic_secret "
+  echo "$text" | grep -q 'BEGIN.*PRIVATE KEY' 2>/dev/null && found="${found}private_key "
+  echo "$text" | grep -qE 'eyJ[A-Za-z0-9_-]{10,}\.eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}' 2>/dev/null && found="${found}jwt "
+  echo "$text" | grep -qE 'gh[pousr]_[A-Za-z0-9_]{36,}' 2>/dev/null && found="${found}github_token "
+  # Output one per line (trimmed)
+  for t in $found; do echo "$t"; done
+}
+
+# --- AWS policy violation patterns (from internal-rules.md) ---
+_detect_aws_violations() {
+  local text="$1"
+  local found=""
+  echo "$text" | grep -qE '0\.0\.0\.0/0' 2>/dev/null && found="${found}open_cidr "
+  echo "$text" | grep -qF '::/0' 2>/dev/null && found="${found}open_ipv6 "
+  echo "$text" | grep -qEi 'PublicRead|public-read|PublicReadWrite|public-read-write' 2>/dev/null && found="${found}public_acl "
+  echo "$text" | grep -qEi 'BlockPublicAccess.*false|block_public_access.*false' 2>/dev/null && found="${found}block_public_false "
+  echo "$text" | grep -qE '"Effect"[[:space:]]*:[[:space:]]*"Allow".*"Principal"[[:space:]]*:[[:space:]]*"\*"' 2>/dev/null && found="${found}wildcard_principal "
+  echo "$text" | grep -qE '"Scheme"[[:space:]]*:[[:space:]]*"internet-facing"' 2>/dev/null && found="${found}internet_facing "
+  echo "$text" | grep -qEi 'AssignPublicIp.*ENABLED|assign_public_ip.*true' 2>/dev/null && found="${found}public_ip "
+  echo "$text" | grep -qE '"EndpointType"[[:space:]]*:[[:space:]]*"EDGE"' 2>/dev/null && found="${found}public_apigw "
+  for t in $found; do echo "$t"; done
+}
+
+# --- Destructive command patterns ---
+_detect_destructive_ops() {
+  local text="$1"
+  echo "$text" | grep -qEi 'rm[[:space:]]+-[a-zA-Z]*r[a-zA-Z]*f|rm[[:space:]]+-[a-zA-Z]*f[a-zA-Z]*r' 2>/dev/null && return 0
+  echo "$text" | grep -qEi 'git[[:space:]]+push[[:space:]]+.*--force' 2>/dev/null && return 0
+  echo "$text" | grep -qEi 'git[[:space:]]+reset[[:space:]]+--hard' 2>/dev/null && return 0
+  echo "$text" | grep -qEi 'DROP[[:space:]]+TABLE' 2>/dev/null && return 0
+  echo "$text" | grep -qEi 'DELETE[[:space:]]+FROM' 2>/dev/null && return 0
+  return 1
+}
+
+# --- Sensitive file path patterns ---
+_detect_sensitive_paths() {
+  local text="$1"
+  echo "$text" | grep -qEi '\.env|credentials|\.pem$|\.key$|id_rsa' 2>/dev/null && return 0
+  return 1
+}
+
+# --- Elevated privilege patterns ---
+_detect_elevated_privilege() {
+  local text="$1"
+  echo "$text" | grep -qE 'sudo[[:space:]]+|\bchmod[[:space:]]+|\bchown[[:space:]]+' 2>/dev/null && return 0
+  return 1
+}

package/context/scripts/hooks/lib/resolve-formatter.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const BIOME_CONFIGS = ['biome.json', 'biome.jsonc'];
+const PRETTIER_CONFIGS = [
+  '.prettierrc', '.prettierrc.json', '.prettierrc.js', '.prettierrc.cjs',
+  '.prettierrc.mjs', '.prettierrc.yml', '.prettierrc.yaml', '.prettierrc.toml',
+  'prettier.config.js', 'prettier.config.cjs', 'prettier.config.mjs',
+];
+const ROOT_MARKERS = ['package.json', ...BIOME_CONFIGS, ...PRETTIER_CONFIGS];
+
+const FORMATTER_PACKAGES = {
+  biome: { binName: 'biome', pkgName: '@biomejs/biome' },
+  prettier: { binName: 'prettier', pkgName: 'prettier' },
+};
+
+const rootCache = new Map();
+const formatterCache = new Map();
+const binCache = new Map();
+
+function findProjectRoot(startDir) {
+  if (rootCache.has(startDir)) return rootCache.get(startDir);
+  let dir = startDir;
+  while (dir !== path.dirname(dir)) {
+    if (ROOT_MARKERS.some(m => fs.existsSync(path.join(dir, m)))) {
+      rootCache.set(startDir, dir);
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  rootCache.set(startDir, startDir);
+  return startDir;
+}
+
+function detectFormatter(projectRoot) {
+  if (formatterCache.has(projectRoot)) return formatterCache.get(projectRoot);
+  if (BIOME_CONFIGS.some(f => fs.existsSync(path.join(projectRoot, f)))) {
+    formatterCache.set(projectRoot, 'biome');
+    return 'biome';
+  }
+  try {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+      if ('prettier' in pkg) {
+        formatterCache.set(projectRoot, 'prettier');
+        return 'prettier';
+      }
+    }
+  } catch { /* malformed package.json */ }
+  if (PRETTIER_CONFIGS.some(f => fs.existsSync(path.join(projectRoot, f)))) {
+    formatterCache.set(projectRoot, 'prettier');
+    return 'prettier';
+  }
+  formatterCache.set(projectRoot, null);
+  return null;
+}
+
+function resolveFormatterBin(projectRoot, formatter) {
+  const key = `${projectRoot}:${formatter}`;
+  if (binCache.has(key)) return binCache.get(key);
+  const pkg = FORMATTER_PACKAGES[formatter];
+  if (!pkg) { binCache.set(key, null); return null; }
+  const localBin = path.join(projectRoot, 'node_modules', '.bin', pkg.binName);
+  const result = fs.existsSync(localBin)
+    ? { bin: localBin, prefix: [] }
+    : { bin: 'npx', prefix: [pkg.pkgName] };
+  binCache.set(key, result);
+  return result;
+}
+
+function clearCaches() {
+  rootCache.clear();
+  formatterCache.clear();
+  binCache.clear();
+}
+
+module.exports = { findProjectRoot, detectFormatter, resolveFormatterBin, clearCaches };

package/context/scripts/hooks/post-edit-accumulator.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+/**
+ * Post-Edit Accumulator
+ *
+ * Records edited JS/TS file paths to a session-scoped temp file.
+ * stop-format-typecheck.js reads this list at stop time for batch processing.
+ *
+ * Uses telemetry session ID when available, falls back to CWD hash.
+ */
+
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const MAX_STDIN = 1024 * 1024;
+const JS_TS_EXT = /\.(ts|tsx|js|jsx)$/;
+
+function getSessionId() {
+  // Try telemetry session file first
+  const hooksDir = __dirname;
+  const sessionDir = path.resolve(hooksDir, '..', 'telemetry', '..', '..', '.telemetry', 'sessions');
+  try {
+    const files = fs.readdirSync(sessionDir).filter(f => f.endsWith('.session'));
+    if (files.length > 0) {
+      // Most recent by mtime
+      const sorted = files
+        .map(f => ({ name: f, mtime: fs.statSync(path.join(sessionDir, f)).mtimeMs }))
+        .sort((a, b) => b.mtime - a.mtime);
+      const data = JSON.parse(fs.readFileSync(path.join(sessionDir, sorted[0].name), 'utf8'));
+      if (data.session_id) return data.session_id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+    }
+  } catch { /* fall through */ }
+  return crypto.createHash('sha1').update(process.cwd()).digest('hex').slice(0, 12);
+}
+
+function getAccumFile() {
+  return path.join(os.tmpdir(), `flow-agents-edited-${getSessionId()}.txt`);
+}
+
+function run(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    const filePath = input.tool_input?.path || input.tool_input?.file_path || '';
+    if (filePath && JS_TS_EXT.test(filePath)) {
+      fs.appendFileSync(getAccumFile(), filePath + '\n', 'utf8');
+    }
+  } catch { /* pass through */ }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    process.stdout.write(run(data));
+    process.exit(0);
+  });
+}
+
+module.exports = { run, getAccumFile };

package/context/scripts/hooks/pre-commit-quality.js

@@ -0,0 +1,194 @@
+#!/usr/bin/env node
+/**
+ * Pre-Commit Quality Gate
+ *
+ * Intercepts git commit commands and runs quality checks:
+ * - Staged file content scanning (secrets, debugger, console.log, TODO)
+ * - Commit message validation (conventional commits)
+ * - Linter execution (ESLint, Pylint, golint)
+ *
+ * Exit codes: 0 = allow (warnings only), 2 = block (errors found)
+ */
+
+'use strict';
+
+const { spawnSync } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const MAX_STDIN = 1024 * 1024;
+const CHECKABLE_EXT = ['.js', '.jsx', '.ts', '.tsx', '.py', '.go', '.rs'];
+
+const SECRET_PATTERNS = [
+  { pattern: /sk-[a-zA-Z0-9]{20,}/, name: 'OpenAI API key' },
+  { pattern: /ghp_[a-zA-Z0-9]{36}/, name: 'GitHub PAT' },
+  { pattern: /AKIA[A-Z0-9]{16}/, name: 'AWS Access Key' },
+  { pattern: /api[_-]?key\s*[=:]\s*['"][^'"]+['"]/i, name: 'API key' },
+];
+
+function getStagedFiles() {
+  const r = spawnSync('git', ['diff', '--cached', '--name-only', '--diff-filter=ACMR'], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  return r.status === 0 ? r.stdout.trim().split('\n').filter(Boolean) : [];
+}
+
+function getStagedContent(filePath) {
+  const r = spawnSync('git', ['show', `:${filePath}`], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] });
+  return r.status === 0 ? r.stdout : null;
+}
+
+function findFileIssues(filePath) {
+  const issues = [];
+  const content = getStagedContent(filePath);
+  if (!content) return issues;
+
+  content.split('\n').forEach((line, i) => {
+    const lineNum = i + 1;
+    if (line.includes('console.log') && !line.trim().startsWith('//') && !line.trim().startsWith('*')) {
+      issues.push({ severity: 'warning', message: `console.log at line ${lineNum}` });
+    }
+    if (/\bdebugger\b/.test(line) && !line.trim().startsWith('//')) {
+      issues.push({ severity: 'error', message: `debugger statement at line ${lineNum}` });
+    }
+    const todo = line.match(/\/\/\s*(TODO|FIXME):?\s*(.+)/);
+    if (todo && !todo[2].match(/#\d+|issue/i)) {
+      issues.push({ severity: 'info', message: `${todo[1]} without issue ref at line ${lineNum}` });
+    }
+    for (const { pattern, name } of SECRET_PATTERNS) {
+      if (pattern.test(line)) {
+        issues.push({ severity: 'error', message: `Potential ${name} at line ${lineNum}` });
+      }
+    }
+  });
+  return issues;
+}
+
+function validateCommitMessage(command) {
+  const m = command.match(/(?:-m|--message)[=\s]+["']?([^"']+)["']?/);
+  if (!m) return null;
+  const msg = m[1];
+  const issues = [];
+  const conventional = /^(feat|fix|docs|style|refactor|test|chore|build|ci|perf|revert)(\(.+\))?!?:\s*.+/;
+  if (!conventional.test(msg)) {
+    issues.push({ message: 'Not conventional commit format', suggestion: 'type(scope): description' });
+  }
+  if (msg.length > 72) issues.push({ message: `Too long (${msg.length}/72 chars)` });
+  if (conventional.test(msg)) {
+    const after = msg.split(':')[1];
+    if (after && /^\s*[A-Z]/.test(after)) issues.push({ message: 'Lowercase after colon' });
+  }
+  if (msg.endsWith('.')) issues.push({ message: 'No trailing period' });
+  return { message: msg, issues };
+}
+
+function runLinter(files) {
+  const results = {};
+  const jsFiles = files.filter(f => /\.(js|jsx|ts|tsx)$/.test(f));
+  if (jsFiles.length > 0) {
+    const eslintPath = path.join(process.cwd(), 'node_modules', '.bin', 'eslint');
+    if (fs.existsSync(eslintPath)) {
+      const r = spawnSync(eslintPath, ['--format', 'compact', ...jsFiles], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000 });
+      results.eslint = { success: r.status === 0, output: r.stdout || r.stderr };
+    }
+  }
+  const pyFiles = files.filter(f => f.endsWith('.py'));
+  if (pyFiles.length > 0) {
+    try {
+      const r = spawnSync('pylint', ['--output-format=text', ...pyFiles], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000 });
+      if (!r.error || r.error.code !== 'ENOENT') results.pylint = { success: r.status === 0, output: r.stdout || r.stderr };
+    } catch { /* not available */ }
+  }
+  const goFiles = files.filter(f => f.endsWith('.go'));
+  if (goFiles.length > 0) {
+    try {
+      const r = spawnSync('golint', goFiles, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: 30000 });
+      if (!r.error || r.error.code !== 'ENOENT') results.golint = { success: !r.stdout || !r.stdout.trim(), output: r.stdout };
+    } catch { /* not available */ }
+  }
+  return results;
+}
+
+function evaluate(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    const command = input.tool_input?.command || '';
+    if (!command.includes('git commit') || command.includes('--amend')) {
+      return { output: rawInput, exitCode: 0 };
+    }
+
+    const staged = getStagedFiles();
+    if (staged.length === 0) {
+      process.stderr.write('[Hook] No staged files found.\n');
+      return { output: rawInput, exitCode: 0 };
+    }
+
+    process.stderr.write(`[Hook] Checking ${staged.length} staged file(s)...\n`);
+    const checkable = staged.filter(f => CHECKABLE_EXT.some(ext => f.endsWith(ext)));
+    let errors = 0, warnings = 0, infos = 0;
+
+    for (const file of checkable) {
+      const issues = findFileIssues(file);
+      if (issues.length > 0) {
+        process.stderr.write(`\n[FILE] ${file}\n`);
+        for (const issue of issues) {
+          const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARNING' : 'INFO';
+          process.stderr.write(`  ${label} ${issue.message}\n`);
+          if (issue.severity === 'error') errors++;
+          else if (issue.severity === 'warning') warnings++;
+          else infos++;
+        }
+      }
+    }
+
+    const msgResult = validateCommitMessage(command);
+    if (msgResult && msgResult.issues.length > 0) {
+      process.stderr.write('\nCommit Message Issues:\n');
+      for (const issue of msgResult.issues) {
+        process.stderr.write(`  WARNING ${issue.message}\n`);
+        if (issue.suggestion) process.stderr.write(`     TIP ${issue.suggestion}\n`);
+        warnings++;
+      }
+    }
+
+    const lintResults = runLinter(checkable);
+    for (const [name, result] of Object.entries(lintResults)) {
+      if (result && !result.success) {
+        process.stderr.write(`\n${name} Issues:\n${result.output}\n`);
+        errors++;
+      }
+    }
+
+    const total = errors + warnings + infos;
+    if (total > 0) {
+      process.stderr.write(`\nSummary: ${total} issue(s) (${errors} error, ${warnings} warning, ${infos} info)\n`);
+      if (errors > 0) {
+        process.stderr.write('[Hook] ERROR: Commit blocked. Fix critical issues first.\n');
+        return { output: rawInput, exitCode: 2 };
+      }
+      process.stderr.write('[Hook] WARNING: Warnings found but commit allowed.\n');
+    } else {
+      process.stderr.write('[Hook] PASS: All checks passed!\n');
+    }
+  } catch (e) {
+    process.stderr.write(`[Hook] Error: ${e.message}\n`);
+  }
+  return { output: rawInput, exitCode: 0 };
+}
+
+function run(rawInput) {
+  return evaluate(rawInput).output;
+}
+
+if (require.main === module) {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (data.length < MAX_STDIN) data += chunk.substring(0, MAX_STDIN - data.length);
+  });
+  process.stdin.on('end', () => {
+    const result = evaluate(data);
+    process.stdout.write(result.output);
+    process.exit(result.exitCode);
+  });
+}
+
+module.exports = { run, evaluate };

package/context/scripts/hooks/quality-gate.js

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+/**
+ * Quality Gate Hook (strict profile only)
+ *
+ * Runs per-file quality checks immediately after edits.
+ * Skips JS/TS when Biome is configured (handled by stop batch).
+ *
+ * Non-blocking — always exits 0, logs warnings to stderr.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const { findProjectRoot, detectFormatter, resolveFormatterBin } = require('./lib/resolve-formatter');
+
+const MAX_STDIN = 1024 * 1024;
+
+function exec(cmd, args, cwd = process.cwd()) {
+  return spawnSync(cmd, args, { cwd, encoding: 'utf8', env: process.env, timeout: 15000 });
+}
+
+function log(msg) { process.stderr.write(`${msg}\n`); }
+
+function checkFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) return;
+  filePath = path.resolve(filePath);
+  const ext = path.extname(filePath).toLowerCase();
+  const fix = String(process.env.SA_QUALITY_GATE_FIX || '').toLowerCase() === 'true';
+  const strict = String(process.env.SA_QUALITY_GATE_STRICT || '').toLowerCase() === 'true';
+
+  if (['.ts', '.tsx', '.js', '.jsx', '.json', '.md'].includes(ext)) {
+    const root = findProjectRoot(path.dirname(filePath));
+    const formatter = detectFormatter(root);
+    if (formatter === 'biome') {
+      if (['.ts', '.tsx', '.js', '.jsx'].includes(ext)) return; // handled by stop batch
+      const resolved = resolveFormatterBin(root, 'biome');
+      if (!resolved) return;
+      const args = [...resolved.prefix, 'check', filePath];
+      if (fix) args.push('--write');
+      const r = exec(resolved.bin, args, root);
+      if (r.status !== 0 && strict) log(`[QualityGate] Biome check failed for ${filePath}`);
+      return;
+    }
+    if (formatter === 'prettier') {
+      const resolved = resolveFormatterBin(root, 'prettier');
+      if (!resolved) return;
+      const r = exec(resolved.bin, [...resolved.prefix, fix ? '--write' : '--check', filePath], root);
+      if (r.status !== 0 && strict) log(`[QualityGate] Prettier check failed for ${filePath}`);
+      return;
+    }
+    return;
+  }
+
+  if (ext === '.go') {
+    if (fix) {
+      const r = exec('gofmt', ['-w', filePath]);
+      if (r.status !== 0 && strict) log(`[QualityGate] gofmt failed for ${filePath}`);
+    } else if (strict) {
+      const r = exec('gofmt', ['-l', filePath]);
+      if (r.stdout && r.stdout.trim()) log(`[QualityGate] gofmt check failed for ${filePath}`);
+    }
+    return;
+  }
+
+  if (ext === '.py') {
+    const args = ['format'];
+    if (!fix) args.push('--check');
+    args.push(filePath);
+    const r = exec('ruff', args);
+    if (r.status !== 0 && strict) log(`[QualityGate] Ruff check failed for ${filePath}`);
+  }
+}
+
+function run(rawInput) {
+  try {
+    const input = JSON.parse(rawInput);
+    checkFile(input.tool_input?.path || input.tool_input?.file_path || '');
+  } catch { /* ignore */ }
+  return rawInput;
+}
+
+if (require.main === module) {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => {
+    if (raw.length < MAX_STDIN) raw += chunk.substring(0, MAX_STDIN - raw.length);
+  });
+  process.stdin.on('end', () => process.stdout.write(run(raw)));
+}
+
+module.exports = { run };

package/context/scripts/hooks/report-only-guard.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Report-Only Guard Hook
+ *
+ * Blocks ALL file writes. Wire this to reviewer/verifier agents
+ * that must only report findings, never modify code.
+ *
+ * Exit codes: 0 = allow, 2 = block
+ */
+
+'use strict';
+
+function run() {
+  return {
+    exitCode: 2,
+    stderr: 'BLOCKED: This agent is report-only — it cannot modify files. ' +
+      'Report findings to the orchestrator, which routes fixes back through execute-plan.',
+  };
+}
+
+module.exports = { run };