unbound-cli 0.8.2 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/api.js

@@ -104,10 +104,42 @@ function request(method, path, { body, query, apiKey, baseUrl } = {}) {
   });
 }
 
+// Plain unauthenticated GET to an arbitrary URL. Returns the raw response body
+// as a UTF-8 string. Callers that want JSON must do JSON.parse() themselves.
+// Used by `unbound oacb` to fetch baseline JSONs and hook scripts from GitHub.
+function getRaw(url) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === 'https:' ? https : http;
+    const req = transport.get(url, { headers: { 'User-Agent': USER_AGENT } }, (res) => {
+      const chunks = [];
+      res.on('data', (chunk) => chunks.push(chunk));
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          resolve(Buffer.concat(chunks).toString('utf8'));
+        } else {
+          reject(new ApiError(res.statusCode, { error: `HTTP ${res.statusCode} fetching ${url}` }));
+        }
+      });
+      res.on('error', (err) => {
+        reject(new Error(`Network error fetching ${parsed.host}: ${err.message}`));
+      });
+    });
+    req.setTimeout(30000, () => {
+      req.destroy();
+      reject(new Error(`Request timed out fetching ${parsed.host}`));
+    });
+    req.on('error', (err) => {
+      reject(new Error(`Network error fetching ${parsed.host}: ${err.message}`));
+    });
+  });
+}
+
 module.exports = {
   ApiError,
   get: (path, opts) => request('GET', path, opts),
   post: (path, opts) => request('POST', path, opts),
   put: (path, opts) => request('PUT', path, opts),
   del: (path, opts) => request('DELETE', path, opts),
+  getRaw,
 };

package/src/commands/oacb.js

@@ -0,0 +1,931 @@
+'use strict';
+
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+const api = require('../api');
+const config = require('../config');
+const output = require('../output');
+
+const OACB_RAW_BASE = 'https://raw.githubusercontent.com/websentry-ai/oacb';
+const OACB_PINNED_REF = 'v0.1.1';
+const TIERS = ['shadow', 'baseline', 'strict', 'paranoid'];
+const HOOKS_DIR = path.join(os.homedir(), '.claude', 'hooks');
+const SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const SETTINGS_BACKUP_PATH = path.join(os.homedir(), '.claude', 'settings.json.oacb-backup');
+const HOOK_NAMES = ['oacb-enforce.sh', 'oacb-prompt-guard.sh', 'oacb-mcp-guard.sh', 'oacb-config-audit.sh', 'oacb-post-tool.sh'];
+const HOOK_NAME_MAP = {
+  enforce: 'oacb-enforce.sh',
+  'prompt-guard': 'oacb-prompt-guard.sh',
+  'mcp-guard': 'oacb-mcp-guard.sh',
+  'config-audit': 'oacb-config-audit.sh',
+  'post-tool': 'oacb-post-tool.sh',
+};
+
+function register(program) {
+  const cmd = program
+    .command('oacb')
+    .description('OACB — Open Autonomous Coding-agent Baseline. Apply, audit, and manage the security baseline for Claude Code.')
+    .addHelpText('after', `
+Quick start:
+  unbound oacb check                       # verify install state
+  unbound oacb apply                       # pick a tier interactively
+  unbound oacb apply --tier shadow         # shadow tier (log-only, safe first step)
+  unbound oacb apply --tier baseline       # turn on enforcement
+  unbound oacb apply --tier strict         # regulated / pre-prod
+  unbound oacb apply --tier paranoid       # FedRAMP / high-sensitivity
+  unbound oacb doctor                      # verify hooks block what they should
+  unbound oacb audit                       # score current settings vs baseline
+  unbound oacb diff --to baseline          # see what changes at the next tier
+
+Read the framework at https://github.com/websentry-ai/oacb before applying baseline or higher.
+    `);
+
+  cmd.command('check')
+    .description('Pre-flight: verify Claude Code install, version, and OACB state')
+    .action(async () => {
+      try { await handleCheck(); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('audit')
+    .description('Score current Claude Code settings against the OACB baseline; report gaps by ASI ID')
+    .option('--tier <tier>', `tier to compare against (${TIERS.join('|')})`, 'baseline')
+    .option('--format <fmt>', 'output format: table | json', 'table')
+    .action(async (opts) => {
+      try { await handleAudit(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('apply')
+    .description('Apply an OACB tier: download hooks + write ~/.claude/settings.json overlay')
+    .option('--tier <tier>', `tier to apply (${TIERS.join('|')}); prompted if omitted`)
+    .option('--overrides <path>', 'path to a local JSON file layered on top of the baseline tier')
+    .option('--dry-run', 'show what would be written without writing anything', false)
+    .option('--local-hooks <dir>', 'dev: copy hook scripts from a local directory instead of downloading from GitHub (overrides OACB_LOCAL_HOOKS_DIR)')
+    .action(async (opts) => {
+      try { await handleApply(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('doctor')
+    .description('Run the OACB conformance suite against installed hooks to verify enforcement')
+    .option('--tier <tier>', `tier to test (${TIERS.join('|')})`, 'baseline')
+    .option('--format <fmt>', 'output format: table | json', 'table')
+    .option('--verbose', 'print each test case result as it runs', false)
+    .action(async (opts) => {
+      try { await handleDoctor(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('diff')
+    .description('Show the settings delta between two OACB tiers')
+    .option('--from <tier>', 'source tier (auto-detected from settings.json if omitted)')
+    .option('--to <tier>', 'target tier', 'baseline')
+    .action(async (opts) => {
+      try { await handleDiff(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('remove')
+    .description('Remove OACB from ~/.claude/settings.json and delete installed hook scripts')
+    .option('--dry-run', 'show what would be removed without writing anything', false)
+    .action(async (opts) => {
+      try { await handleRemove(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+}
+
+// ─── Handlers ────────────────────────────────────────────────────────────────
+
+async function handleCheck() {
+  const cfg = config.readConfig();
+  const hasUnboundSession = !!cfg.api_key;
+
+  let claudeCodeVersion = null;
+  try {
+    const { execSync } = require('node:child_process');
+    claudeCodeVersion = execSync('claude --version', {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 3000,
+    }).toString().trim();
+  } catch (_) { /* not on PATH */ }
+
+  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
+  let claudeSettingsExist = false;
+  try { await fs.access(settingsPath); claudeSettingsExist = true; } catch (_) {}
+
+  const appliedTier = await detectCurrentTier();
+
+  const hookStates = await Promise.all(
+    HOOK_NAMES.map(async (n) => {
+      try { await fs.access(path.join(HOOKS_DIR, n)); return true; }
+      catch (_) { return false; }
+    })
+  );
+  const hooksInstalledCount = hookStates.filter(Boolean).length;
+
+  output.keyValue([
+    ['Unbound session', hasUnboundSession ? 'logged in' : 'not logged in (optional — login enables backend sync)'],
+    ['Claude Code on PATH', claudeCodeVersion || 'not detected'],
+    ['~/.claude/settings.json', claudeSettingsExist ? 'found' : 'not found'],
+    ['OACB tier applied', appliedTier !== 'none' ? appliedTier : 'none (run `unbound oacb apply`)'],
+    ['Hooks installed', `${hooksInstalledCount} / ${HOOK_NAMES.length}`],
+    ['OACB pinned ref', OACB_PINNED_REF],
+  ]);
+
+  if (!claudeCodeVersion) {
+    output.warn('`claude` not on PATH — is Claude Code installed?');
+  } else if (!isVersionSupported(claudeCodeVersion)) {
+    output.warn(`Claude Code ${claudeCodeVersion} is outside OACB tested range (>=2.1.83 <3.0.0). Proceed with caution.`);
+  }
+
+  if (appliedTier === 'none') {
+    output.warn('No OACB tier applied. Run `unbound oacb apply` to start with shadow tier.');
+  }
+
+  output.success('Pre-flight complete.');
+}
+
+async function handleAudit({ tier, format }) {
+  validateTier(tier);
+  const spin = output.spinner(`Fetching OACB ${tier} baseline...`);
+  let baseline;
+  try {
+    baseline = await fetchBaseline(tier);
+    spin.stop();
+  } catch (e) {
+    spin.fail(`Could not fetch baseline: ${e.message}`);
+    throw e;
+  }
+
+  const current = await loadMergedSettings();
+  const gaps = computeGaps(current, baseline);
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({ tier, ref: OACB_PINNED_REF, gaps }, null, 2) + '\n');
+    return;
+  }
+
+  output.info(`OACB audit — tier=${tier}  ref=${OACB_PINNED_REF}`);
+  if (gaps.length === 0) {
+    output.success('No gaps. Current settings satisfy the OACB tier baseline.');
+    return;
+  }
+
+  output.warn(`${gaps.length} gap(s) found:`);
+  output.table(
+    gaps.map(g => ({ asi: g.asi, id: g.ruleId, desc: g.description })),
+    [
+      { key: 'asi', header: 'ASI' },
+      { key: 'id', header: 'Rule ID' },
+      { key: 'desc', header: 'Description' },
+    ]
+  );
+  output.info(`Run \`unbound oacb apply --tier ${tier}\` to remediate.`);
+}
+
+async function handleApply({ tier, overrides, dryRun, localHooks }) {
+  if (!tier) {
+    tier = await output.select('Select OACB security tier:', [
+      { label: 'shadow    — log-only, safe first step (recommended start)', value: 'shadow' },
+      { label: 'baseline  — enforcement enabled',                           value: 'baseline' },
+      { label: 'strict    — regulated / pre-prod environments',             value: 'strict' },
+      { label: 'paranoid  — FedRAMP / high-sensitivity',                    value: 'paranoid' },
+    ]);
+  }
+  validateTier(tier);
+
+  const spin = output.spinner(`Fetching OACB ${tier} baseline from GitHub...`);
+  let baseline;
+  try {
+    baseline = await fetchBaseline(tier);
+    spin.stop();
+  } catch (e) {
+    spin.fail(`Could not fetch baseline: ${e.message}`);
+    throw e;
+  }
+
+  let effective = deepClone(baseline);
+  if (overrides) {
+    const overrideJson = JSON.parse(await fs.readFile(overrides, 'utf8'));
+    effective = mergeOverrides(effective, overrideJson);
+  }
+
+  if (dryRun) {
+    output.info(`--dry-run: showing what would be merged into ${SETTINGS_PATH}`);
+    const oacbHooks = buildOacbHookEntries(effective);
+    process.stdout.write(JSON.stringify({
+      _oacbMeta: { tier, appliedAt: '<now>', ref: OACB_PINNED_REF },
+      permissions: effective.permissions,
+      autoMode: effective.autoMode,
+      hooks: oacbHooks,
+    }, null, 2) + '\n');
+    output.info('  Hook scripts that would be installed:');
+    for (const name of HOOK_NAMES) {
+      process.stdout.write(`    ${path.join(HOOKS_DIR, name)}\n`);
+    }
+    return;
+  }
+
+  if (tier !== 'shadow') {
+    output.warn(`Applying tier=${tier}. This WILL block tool calls matching deny rules.`);
+    output.warn('If you have not run shadow tier for 2+ weeks, consider starting there first.');
+  }
+
+  const hooksLocalDir = localHooks || process.env.OACB_LOCAL_HOOKS_DIR || null;
+  const hookSpin = output.spinner(
+    hooksLocalDir
+      ? `Installing OACB hook scripts from local path: ${hooksLocalDir}...`
+      : 'Downloading and installing OACB hook scripts...'
+  );
+  try {
+    await installHooks(hooksLocalDir);
+    hookSpin.succeed(`Installed ${HOOK_NAMES.length} hooks to ${HOOKS_DIR}`);
+  } catch (e) {
+    hookSpin.fail(`Hook installation failed: ${e.message}`);
+    throw e;
+  }
+
+  const settingsSpin = output.spinner(`Merging OACB settings into ${SETTINGS_PATH}...`);
+  try {
+    await writeSettingsOverlay(effective, tier);
+    settingsSpin.succeed(`Updated ${SETTINGS_PATH} (backup at ${SETTINGS_BACKUP_PATH})`);
+  } catch (e) {
+    settingsSpin.fail(`Settings write failed: ${e.message}`);
+    throw e;
+  }
+
+  // Backend policy push — only if logged in; non-fatal if it fails
+  // TODO: use later if required, logic works
+  // if (config.isLoggedIn()) {
+  //   const backendSpin = output.spinner('Pushing deny policies to Unbound backend...');
+  //   try {
+  //     const count = await applyRulesToBackend(effective, tier);
+  //     backendSpin.succeed(`Pushed ${count} policies to backend.`);
+  //   } catch (e) {
+  //     backendSpin.fail(`Backend push skipped: ${e.message}`);
+  //     output.info('Local install succeeded. Run `unbound login` to re-enable backend sync.');
+  //   }
+  // } else {
+  //   output.info('No Unbound session — local install only. Run `unbound login` to enable backend policy sync.');
+  // }
+
+  output.success(`OACB ${tier} applied.`);
+  if (tier === 'shadow') {
+    output.info('Shadow: hooks log but never block. Review ~/.claude/hooks/oacb-audit.log for 2 weeks, then `unbound oacb apply --tier baseline`.');
+  }
+  output.info('Verify with: unbound oacb doctor --tier ' + tier);
+}
+
+async function handleDoctor({ tier, format, verbose }) {
+  validateTier(tier);
+
+  // Verify at least the enforce hook is installed
+  const enforcePath = path.join(HOOKS_DIR, 'oacb-enforce.sh');
+  try {
+    await fs.access(enforcePath);
+  } catch {
+    output.error(`OACB hooks not installed. Run \`unbound oacb apply --tier ${tier}\` first.`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const spin = output.spinner('Fetching conformance corpus...');
+  let corpus;
+  try {
+    corpus = await fetchConformanceCorpus();
+    spin.stop();
+  } catch (e) {
+    spin.fail(`Could not fetch corpus: ${e.message}`);
+    throw e;
+  }
+
+  // Run cases that have an expectation for this tier and are not RESIDUAL
+  const cases = corpus.filter(c =>
+    !c.id.endsWith('-RESIDUAL') &&
+    c.tiers &&
+    c.tiers[tier] !== undefined
+  );
+
+  if (format !== 'json') {
+    output.info(`Running ${cases.length} conformance cases for tier=${tier}...`);
+  }
+
+  const results = [];
+  for (const testCase of cases) {
+    const hookBin = path.join(HOOKS_DIR, HOOK_NAME_MAP[testCase.hook || 'enforce']);
+    const result = runConformanceCase(testCase, hookBin, tier);
+    results.push(result);
+    if (format !== 'json' && verbose) {
+      const icon = result.passed ? '✔' : '✘';
+      process.stderr.write(`  ${icon} ${result.id}\n`);
+    }
+  }
+
+  const passed = results.filter(r => r.passed).length;
+  const failed = results.filter(r => !r.passed);
+
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify({
+      tier,
+      ref: OACB_PINNED_REF,
+      passed,
+      total: cases.length,
+      results,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  output.info(`${passed} / ${cases.length} cases passed`);
+
+  if (failed.length > 0) {
+    output.warn('Failures:');
+    output.table(
+      failed.map(f => ({
+        id: f.id,
+        expected: `exit ${f.expectedExit}`,
+        got: `exit ${f.actualExit}`,
+        note: f.note || '',
+      })),
+      [
+        { key: 'id', header: 'Case ID' },
+        { key: 'expected', header: 'Expected' },
+        { key: 'got', header: 'Got' },
+        { key: 'note', header: 'Note' },
+      ]
+    );
+    process.exitCode = 1;
+  } else {
+    output.success('All conformance cases passed.');
+  }
+}
+
+async function handleDiff({ from, to }) {
+  validateTier(to);
+  if (from) validateTier(from);
+
+  const fromTier = from || await detectCurrentTier();
+  const resolvedFrom = fromTier === 'none' ? 'shadow' : fromTier;
+  if (!from && fromTier === 'none') {
+    output.warn('No OACB tier applied; using shadow as diff base.');
+  }
+
+  const spin = output.spinner(`Fetching ${resolvedFrom} and ${to} tier settings...`);
+  let a, b;
+  try {
+    [a, b] = await Promise.all([fetchBaseline(resolvedFrom), fetchBaseline(to)]);
+    spin.stop();
+  } catch (e) {
+    spin.fail(`Fetch failed: ${e.message}`);
+    throw e;
+  }
+
+  output.info(`Diff: ${resolvedFrom} → ${to}`);
+  process.stdout.write(JSON.stringify(computeDeepDiff(a, b), null, 2) + '\n');
+}
+
+async function handleRemove({ dryRun }) {
+  let settings = {};
+  try {
+    settings = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8'));
+  } catch (_) {
+    output.warn(`${SETTINGS_PATH} not found — nothing to remove.`);
+    return;
+  }
+
+  const meta = settings._oacbMeta;
+  if (!meta) {
+    output.warn('No OACB installation found in settings.json (_oacbMeta missing).');
+    return;
+  }
+
+  const tier = meta.tier;
+  output.info(`Removing OACB (tier=${tier}) from ${SETTINGS_PATH}...`);
+
+  // Use the stored contribution snapshot when available — it records exactly what OACB
+  // wrote, so user rules that coincidentally match the baseline are not deleted.
+  // Fall back to fetching the remote baseline for legacy installs without a snapshot.
+  let contribution = meta.contribution;
+  if (!contribution) {
+    const spin = output.spinner(`Fetching ${tier} baseline to compute what to remove...`);
+    try {
+      const baseline = await fetchBaseline(tier);
+      spin.stop();
+      contribution = { permissions: baseline.permissions || {}, autoMode: baseline.autoMode || {} };
+    } catch (e) {
+      spin.fail(`Could not fetch baseline: ${e.message}`);
+      throw e;
+    }
+  }
+
+  const cleaned = deepClone(settings);
+
+  // Remove permission list entries contributed by OACB
+  if (contribution.permissions && cleaned.permissions) {
+    const contributedDeny = new Set(contribution.permissions.deny || []);
+    const contributedAsk = new Set(contribution.permissions.ask || []);
+    const contributedAllow = new Set(contribution.permissions.allow || []);
+    if (cleaned.permissions.deny) {
+      cleaned.permissions.deny = cleaned.permissions.deny.filter(r => !contributedDeny.has(r));
+      if (!cleaned.permissions.deny.length) delete cleaned.permissions.deny;
+    }
+    if (cleaned.permissions.ask) {
+      cleaned.permissions.ask = cleaned.permissions.ask.filter(r => !contributedAsk.has(r));
+      if (!cleaned.permissions.ask.length) delete cleaned.permissions.ask;
+    }
+    if (cleaned.permissions.allow) {
+      cleaned.permissions.allow = cleaned.permissions.allow.filter(r => !contributedAllow.has(r));
+      if (!cleaned.permissions.allow.length) delete cleaned.permissions.allow;
+    }
+
+    for (const scalarKey of ['defaultMode', 'disableBypassPermissionsMode', 'allowManagedHooksOnly', 'allowManagedPermissionRulesOnly', 'allowManagedMcpServersOnly']) {
+      const prev = contribution.permissions[scalarKey];
+      if (prev !== undefined && cleaned.permissions[scalarKey] === prev) {
+        delete cleaned.permissions[scalarKey];
+      }
+    }
+
+    if (!Object.keys(cleaned.permissions).length) delete cleaned.permissions;
+  }
+
+  // Remove hook entries where command matches an OACB hook script
+  const oacbHookRe = /oacb-[^/\\]+\.sh$/;
+  if (cleaned.hooks) {
+    for (const event of Object.keys(cleaned.hooks)) {
+      cleaned.hooks[event] = (cleaned.hooks[event] || []).map(entry => {
+        if (!entry.hooks) return entry;
+        const filteredHooks = entry.hooks.filter(h => !oacbHookRe.test(h.command || ''));
+        if (!filteredHooks.length) return null;
+        return { ...entry, hooks: filteredHooks };
+      }).filter(Boolean);
+      if (!cleaned.hooks[event].length) delete cleaned.hooks[event];
+    }
+    if (!Object.keys(cleaned.hooks).length) delete cleaned.hooks;
+  }
+
+  // Remove autoMode keys contributed by OACB (only if values still match what was applied)
+  if (contribution.autoMode && cleaned.autoMode) {
+    for (const k of Object.keys(contribution.autoMode)) {
+      if (JSON.stringify(cleaned.autoMode[k]) === JSON.stringify(contribution.autoMode[k])) {
+        delete cleaned.autoMode[k];
+      }
+    }
+    if (!Object.keys(cleaned.autoMode).length) delete cleaned.autoMode;
+  }
+
+  delete cleaned._oacbMeta;
+
+  if (dryRun) {
+    output.info('--dry-run: showing cleaned settings.json (not written)');
+    process.stdout.write(JSON.stringify(cleaned, null, 2) + '\n');
+    output.info('Hook scripts that would be deleted:');
+    for (const name of HOOK_NAMES) {
+      process.stdout.write(`  ${path.join(HOOKS_DIR, name)}\n`);
+    }
+    return;
+  }
+
+  await fs.writeFile(SETTINGS_PATH, JSON.stringify(cleaned, null, 2) + '\n', { mode: 0o600 });
+  output.success(`Wrote cleaned ${SETTINGS_PATH}`);
+
+  const deleted = [];
+  const missing = [];
+  await Promise.all(
+    HOOK_NAMES.map(async (name) => {
+      const p = path.join(HOOKS_DIR, name);
+      try {
+        await fs.unlink(p);
+        deleted.push(name);
+      } catch (_) {
+        missing.push(name);
+      }
+    })
+  );
+
+  if (deleted.length) output.success(`Deleted hook scripts: ${deleted.join(', ')}`);
+  if (missing.length) output.info(`Hook scripts not found (already gone): ${missing.join(', ')}`);
+
+  output.success('OACB removed. Your original settings have been preserved minus the OACB additions.');
+  output.info('Run `unbound oacb check` to verify clean state.');
+}
+
+// ─── Fetch helpers ────────────────────────────────────────────────────────────
+
+async function fetchBaseline(tier) {
+  const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/baseline/claude-code/managed-settings.${tier}.json`;
+  return JSON.parse(await api.getRaw(url));
+}
+
+async function fetchConformanceCorpus() {
+  const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/conformance-tests/expected.json`;
+  const parsed = JSON.parse(await api.getRaw(url));
+  return Array.isArray(parsed) ? parsed : (parsed.cases || []);
+}
+
+// ─── Settings helpers ─────────────────────────────────────────────────────────
+
+async function detectCurrentTier() {
+  try {
+    const raw = await fs.readFile(SETTINGS_PATH, 'utf8');
+    return JSON.parse(raw)._oacbMeta?.tier || 'none';
+  } catch (_) {
+    return 'none';
+  }
+}
+
+async function loadMergedSettings() {
+  try { return JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8')); }
+  catch (_) { return {}; }
+}
+
+// ─── Gap analysis ─────────────────────────────────────────────────────────────
+
+const RULE_ASI_MAP = [
+  { re: /rm -r[fF]|rm -fr/, asi: 'ASI02', id: 'OACB-RM-001' },
+  { re: /terraform destroy|terraform apply -auto-approve/, asi: 'ASI02', id: 'OACB-TF-001' },
+  { re: /drizzle-kit push --force|prisma migrate reset|alembic downgrade/, asi: 'ASI02', id: 'OACB-DB-001' },
+  { re: /git push --force|git push -f /, asi: 'ASI05', id: 'OACB-GIT-001' },
+  { re: /eval |history /, asi: 'ASI05', id: 'OACB-EVAL-001' },
+  { re: /find \/ -delete|find ~ -delete/, asi: 'ASI02', id: 'OACB-FIND-001' },
+  { re: /\.env|\.ssh|\.aws|\.netrc|\.config\/gh|\.kube|\.docker|\.npmrc|\.pypirc|\.m2|\.gnupg/, asi: 'ASI07', id: 'OACB-READ-001' },
+  { re: /\.claude|\.cursor|\.codex|CLAUDE\.md|AGENTS\.md/, asi: 'ASI04', id: 'OACB-CONFIG-001' },
+];
+
+function classifyRule(rulePattern) {
+  for (const { re, asi } of RULE_ASI_MAP) {
+    if (re.test(rulePattern)) return asi;
+  }
+  return 'ASI02';
+}
+
+function ruleIdFromPattern(rulePattern) {
+  for (const { re, id } of RULE_ASI_MAP) {
+    if (re.test(rulePattern)) return id;
+  }
+  return 'OACB-DENY';
+}
+
+function computeGaps(current, baseline) {
+  const gaps = [];
+  const curDeny = new Set(current.permissions?.deny || []);
+
+  // Missing deny rules — deduplicate by rule ID so we report one gap per category
+  const reportedIds = new Set();
+  for (const rule of (baseline.permissions?.deny || [])) {
+    if (!curDeny.has(rule)) {
+      const ruleId = ruleIdFromPattern(rule);
+      if (!reportedIds.has(ruleId)) {
+        reportedIds.add(ruleId);
+        gaps.push({
+          asi: classifyRule(rule),
+          ruleId,
+          description: `One or more deny rules for ${ruleId} are missing (e.g. "${rule}")`,
+          recommendation: `Run \`unbound oacb apply --tier ${baseline._oacb?.tier || 'baseline'}\``,
+        });
+      }
+    }
+  }
+
+  // Hooks wired?
+  if (!hasOacbHook(current, 'PreToolUse', 'oacb-enforce.sh')) {
+    gaps.push({
+      asi: 'ASI02',
+      ruleId: 'OACB-HOOK-001',
+      description: 'oacb-enforce.sh not registered in PreToolUse hooks',
+      recommendation: 'Run `unbound oacb apply --tier <tier>` to install and register hooks',
+    });
+  }
+
+  // disableBypassPermissionsMode
+  const baseBypass = baseline.permissions?.disableBypassPermissionsMode;
+  const curBypass = current.permissions?.disableBypassPermissionsMode;
+  if (baseBypass && curBypass !== baseBypass) {
+    gaps.push({
+      asi: 'ASI03',
+      ruleId: 'OACB-BYPASS-001',
+      description: `disableBypassPermissionsMode should be "${baseBypass}", found "${curBypass || 'unset'}"`,
+      recommendation: 'Set permissions.disableBypassPermissionsMode in settings.local.json',
+    });
+  }
+
+  return gaps;
+}
+
+function hasOacbHook(settings, event, hookFile) {
+  const hooks = settings.hooks?.[event] || [];
+  return hooks.some(entry =>
+    (entry.hooks || []).some(h =>
+      typeof h.command === 'string' && h.command.includes(hookFile)
+    )
+  );
+}
+
+// ─── Hook installation ────────────────────────────────────────────────────────
+
+async function installHooks(localDir = null) {
+  await fs.mkdir(HOOKS_DIR, { recursive: true });
+  await Promise.all(
+    HOOK_NAMES.map(async (name) => {
+      let content;
+      if (localDir) {
+        content = await fs.readFile(path.join(localDir, name), 'utf8');
+      } else {
+        const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/baseline/claude-code/hooks/${name}`;
+        content = await api.getRaw(url);
+      }
+      await fs.writeFile(path.join(HOOKS_DIR, name), content, { mode: 0o755 });
+    })
+  );
+}
+
+// Build the OACB hook entries with ~/.claude/hooks/ paths (not the MDM paths)
+function buildOacbHookEntries(baseline) {
+  const hooks = deepClone(baseline.hooks || {});
+  for (const entries of Object.values(hooks)) {
+    for (const entry of entries) {
+      for (const h of entry.hooks || []) {
+        if (h.command) {
+          h.command = path.join(HOOKS_DIR, path.basename(h.command));
+        }
+      }
+    }
+  }
+  return hooks;
+}
+
+// Strip a previously applied OACB overlay from settings, preserving user additions.
+// Uses the contribution snapshot stored in _oacbMeta.contribution when present;
+// falls back to the backup file for legacy installs that predate contribution tracking.
+async function stripOacbFromSettings(settings) {
+  const contribution = settings._oacbMeta?.contribution;
+
+  // Legacy fallback: no contribution stored, restore from frozen backup
+  if (!contribution) {
+    try {
+      return JSON.parse(await fs.readFile(SETTINGS_BACKUP_PATH, 'utf8'));
+    } catch (_) {}
+    // No backup either — strip hooks via regex and drop meta
+    const cleaned = deepClone(settings);
+    const oacbHookRe = /oacb-[^/\\]+\.sh$/;
+    if (cleaned.hooks) {
+      for (const event of Object.keys(cleaned.hooks)) {
+        cleaned.hooks[event] = (cleaned.hooks[event] || []).map(entry => {
+          if (!entry.hooks) return entry;
+          const filtered = entry.hooks.filter(h => !oacbHookRe.test(h.command || ''));
+          if (!filtered.length) return null;
+          return { ...entry, hooks: filtered };
+        }).filter(Boolean);
+        if (!cleaned.hooks[event].length) delete cleaned.hooks[event];
+      }
+      if (!Object.keys(cleaned.hooks).length) delete cleaned.hooks;
+    }
+    delete cleaned._oacbMeta;
+    return cleaned;
+  }
+
+  const cleaned = deepClone(settings);
+
+  // Remove permission list entries contributed by OACB
+  if (contribution.permissions && cleaned.permissions) {
+    for (const listKey of ['deny', 'ask', 'allow']) {
+      const contributed = new Set(contribution.permissions[listKey] || []);
+      if (contributed.size && cleaned.permissions[listKey]) {
+        cleaned.permissions[listKey] = cleaned.permissions[listKey].filter(r => !contributed.has(r));
+        if (!cleaned.permissions[listKey].length) delete cleaned.permissions[listKey];
+      }
+    }
+    for (const scalarKey of ['defaultMode', 'disableBypassPermissionsMode', 'allowManagedHooksOnly', 'allowManagedPermissionRulesOnly', 'allowManagedMcpServersOnly']) {
+      const prev = contribution.permissions[scalarKey];
+      if (prev !== undefined && cleaned.permissions[scalarKey] === prev) {
+        delete cleaned.permissions[scalarKey];
+      }
+    }
+    if (!Object.keys(cleaned.permissions).length) delete cleaned.permissions;
+  }
+
+  // Remove OACB hook entries by command path pattern
+  const oacbHookRe = /oacb-[^/\\]+\.sh$/;
+  if (cleaned.hooks) {
+    for (const event of Object.keys(cleaned.hooks)) {
+      cleaned.hooks[event] = (cleaned.hooks[event] || []).map(entry => {
+        if (!entry.hooks) return entry;
+        const filtered = entry.hooks.filter(h => !oacbHookRe.test(h.command || ''));
+        if (!filtered.length) return null;
+        return { ...entry, hooks: filtered };
+      }).filter(Boolean);
+      if (!cleaned.hooks[event].length) delete cleaned.hooks[event];
+    }
+    if (!Object.keys(cleaned.hooks).length) delete cleaned.hooks;
+  }
+
+  // Remove autoMode keys contributed by OACB (only if values still match what was applied)
+  if (contribution.autoMode && cleaned.autoMode) {
+    for (const k of Object.keys(contribution.autoMode)) {
+      if (JSON.stringify(cleaned.autoMode[k]) === JSON.stringify(contribution.autoMode[k])) {
+        delete cleaned.autoMode[k];
+      }
+    }
+    if (!Object.keys(cleaned.autoMode).length) delete cleaned.autoMode;
+  }
+
+  delete cleaned._oacbMeta;
+  return cleaned;
+}
+
+// Merge OACB settings into the existing settings.json.
+// On first apply: backup settings.json first.
+// On re-apply: strip the previous OACB contribution from the live file so user
+// additions made since the last apply are preserved.
+async function writeSettingsOverlay(baseline, tier) {
+  await fs.mkdir(path.dirname(SETTINGS_PATH), { recursive: true });
+
+  let existing = {};
+  try { existing = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8')); } catch (_) {}
+
+  if (existing._oacbMeta) {
+    // Re-apply: strip previous OACB contribution, preserving user additions
+    existing = await stripOacbFromSettings(existing);
+  } else {
+    // First apply: write backup for disaster recovery
+    await fs.writeFile(SETTINGS_BACKUP_PATH, JSON.stringify(existing, null, 2) + '\n', { mode: 0o600 });
+  }
+
+  const merged = deepClone(existing);
+
+  // permissions: union deny/ask arrays, set scalar keys
+  merged.permissions = merged.permissions || {};
+  const perm = baseline.permissions || {};
+  for (const listKey of ['deny', 'ask', 'allow']) {
+    if (perm[listKey]?.length) {
+      merged.permissions[listKey] = [
+        ...new Set([...(merged.permissions[listKey] || []), ...perm[listKey]]),
+      ];
+    }
+  }
+  for (const scalarKey of ['defaultMode', 'disableBypassPermissionsMode', 'allowManagedHooksOnly', 'allowManagedPermissionRulesOnly', 'allowManagedMcpServersOnly']) {
+    if (perm[scalarKey] !== undefined) merged.permissions[scalarKey] = perm[scalarKey];
+  }
+
+  // hooks: add OACB hook entries alongside existing entries (don't replace)
+  const oacbHooks = buildOacbHookEntries(baseline);
+  merged.hooks = merged.hooks || {};
+  for (const [event, entries] of Object.entries(oacbHooks)) {
+    merged.hooks[event] = [...(merged.hooks[event] || []), ...entries];
+  }
+
+  // autoMode: deep merge
+  if (baseline.autoMode) {
+    merged.autoMode = mergeOverrides(merged.autoMode || {}, baseline.autoMode);
+  }
+
+  // Tracking metadata — contribution snapshot enables clean stripping on next re-apply
+  merged._oacbMeta = {
+    tier,
+    appliedAt: new Date().toISOString(),
+    ref: OACB_PINNED_REF,
+    contribution: {
+      permissions: deepClone(perm),
+      autoMode: deepClone(baseline.autoMode || {}),
+    },
+  };
+
+  await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+  return merged;
+}
+
+// ─── Backend policy push ──────────────────────────────────────────────────────
+
+// TODO: implement later if required, logic is sound - Dinesh Veluswamy
+// async function applyRulesToBackend(settings, tier) {
+//   const denyRules = settings.permissions?.deny || [];
+//   let count = 0;
+//   for (const rule of denyRules) {
+//     try {
+//       await api.post('/api/v1/command-policies/', {
+//         body: { name: `oacb/${tier}/${rule}`, action: 'BLOCK', rule, source: 'oacb', tier },
+//       });
+//       count++;
+//     } catch (e) {
+//       if (e.statusCode === 409) { count++; } // already exists — idempotent
+//       else throw e;
+//     }
+//   }
+//   return count;
+// }
+
+// ─── Conformance runner ───────────────────────────────────────────────────────
+
+function runConformanceCase(testCase, hookBin, tier) {
+  const tierExpect = testCase.tiers[tier];
+  const stdinData = JSON.stringify(testCase.stdin || {});
+
+  const result = spawnSync(hookBin, [], {
+    input: stdinData,
+    env: { ...process.env, OACB_TIER: tier },
+    encoding: 'utf8',
+    timeout: 10000,
+  });
+
+  if (result.error) {
+    return {
+      id: testCase.id,
+      passed: false,
+      expectedExit: tierExpect.exit,
+      actualExit: -1,
+      note: result.error.message,
+    };
+  }
+
+  const actualExit = result.status ?? 1;
+  const expectedExit = tierExpect.exit;
+  const stderrCheck = tierExpect.stderr_contains;
+
+  let passed = actualExit === expectedExit;
+  let note;
+  if (passed && stderrCheck && !(result.stderr || '').includes(stderrCheck)) {
+    passed = false;
+    note = `stderr missing expected string: "${stderrCheck}"`;
+  }
+
+  return { id: testCase.id, passed, expectedExit, actualExit, note };
+}
+
+// ─── Deep diff ────────────────────────────────────────────────────────────────
+
+function computeDeepDiff(a, b) {
+  const diff = {};
+  const allKeys = new Set([...Object.keys(a || {}), ...Object.keys(b || {})]);
+  for (const k of allKeys) {
+    if (k.startsWith('_')) continue;
+    if (!(k in a)) {
+      diff[k] = { added: b[k] };
+    } else if (!(k in b)) {
+      diff[k] = { removed: a[k] };
+    } else if (Array.isArray(a[k]) && Array.isArray(b[k])) {
+      const added = b[k].filter(x => !a[k].includes(x));
+      const removed = a[k].filter(x => !b[k].includes(x));
+      if (added.length || removed.length) diff[k] = { added, removed };
+    } else if (typeof a[k] === 'object' && a[k] !== null && typeof b[k] === 'object' && b[k] !== null) {
+      const nested = computeDeepDiff(a[k], b[k]);
+      if (Object.keys(nested).length) diff[k] = nested;
+    } else if (a[k] !== b[k]) {
+      diff[k] = { from: a[k], to: b[k] };
+    }
+  }
+  return diff;
+}
+
+// ─── Pure utilities ───────────────────────────────────────────────────────────
+
+function validateTier(t) {
+  if (!TIERS.includes(t)) throw new Error(`Invalid tier '${t}'. Expected one of: ${TIERS.join(', ')}`);
+}
+
+function mergeOverrides(base, overrides) {
+  const result = deepClone(base);
+  for (const [k, v] of Object.entries(overrides)) {
+    if (k === '_oacbMeta') continue;
+    if (Array.isArray(result[k]) && Array.isArray(v)) {
+      result[k] = [...new Set([...result[k], ...v])];
+    } else if (typeof result[k] === 'object' && result[k] !== null && typeof v === 'object' && v !== null && !Array.isArray(v)) {
+      result[k] = mergeOverrides(result[k], v);
+    } else {
+      result[k] = v;
+    }
+  }
+  return result;
+}
+
+function deepClone(obj) {
+  return JSON.parse(JSON.stringify(obj));
+}
+
+function isVersionSupported(v) {
+  const m = v.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!m) return false;
+  const [maj, min, pat] = [m[1], m[2], m[3]].map(Number);
+  if (maj < 2) return false;
+  if (maj === 2 && min < 1) return false;
+  if (maj === 2 && min === 1 && pat < 83) return false;
+  if (maj >= 3) return false;
+  return true;
+}
+
+module.exports = {
+  register,
+  // exported for unit tests only — not part of the public API
+  __test__: {
+    validateTier,
+    isVersionSupported,
+    computeGaps,
+    mergeOverrides,
+    computeDeepDiff,
+    buildOacbHookEntries,
+    ruleIdFromPattern,
+    classifyRule,
+    hasOacbHook,
+    runConformanceCase,
+  },
+};

package/src/index.js

@@ -181,6 +181,7 @@ require('./commands/setup').register(program);
 require('./commands/discover').register(program);
 require('./commands/onboard').register(program);
 require('./commands/chat').register(program);
+require('./commands/oacb').register(program);
 
 // config command for managing CLI settings
 const configCmd = program

package/test/oacb.test.js

@@ -0,0 +1,307 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const os = require('node:os');
+const path = require('node:path');
+
+const {
+  validateTier,
+  isVersionSupported,
+  computeGaps,
+  mergeOverrides,
+  computeDeepDiff,
+  buildOacbHookEntries,
+  ruleIdFromPattern,
+  classifyRule,
+  hasOacbHook,
+} = require('../src/commands/oacb').__test__;
+
+// ─── validateTier ─────────────────────────────────────────────────────────────
+
+test('validateTier: accepts all four valid tiers', () => {
+  for (const t of ['shadow', 'baseline', 'strict', 'paranoid']) {
+    assert.doesNotThrow(() => validateTier(t));
+  }
+});
+
+test('validateTier: rejects unknown tier', () => {
+  assert.throws(() => validateTier('custom'), /Invalid tier/);
+});
+
+test('validateTier: rejects empty string', () => {
+  assert.throws(() => validateTier(''), /Invalid tier/);
+});
+
+// ─── isVersionSupported ───────────────────────────────────────────────────────
+
+test('isVersionSupported: supported version returns true', () => {
+  assert.equal(isVersionSupported('2.1.83'), true);
+  assert.equal(isVersionSupported('2.5.0'), true);
+  assert.equal(isVersionSupported('2.99.0'), true);
+});
+
+test('isVersionSupported: version below floor returns false', () => {
+  assert.equal(isVersionSupported('2.1.82'), false);
+  assert.equal(isVersionSupported('2.0.99'), false);
+  assert.equal(isVersionSupported('1.99.0'), false);
+});
+
+test('isVersionSupported: v3+ returns false', () => {
+  assert.equal(isVersionSupported('3.0.0'), false);
+  assert.equal(isVersionSupported('3.1.0'), false);
+});
+
+test('isVersionSupported: non-semver string returns false', () => {
+  assert.equal(isVersionSupported(''), false);
+  assert.equal(isVersionSupported('latest'), false);
+});
+
+test('isVersionSupported: handles version prefix in claude --version output', () => {
+  // `claude --version` may return "2.3.7" or "claude 2.3.7" — match by first semver
+  assert.equal(isVersionSupported('claude 2.3.7'), true);
+  assert.equal(isVersionSupported('claude 1.0.0'), false);
+});
+
+// ─── ruleIdFromPattern / classifyRule ────────────────────────────────────────
+
+test('ruleIdFromPattern: RM pattern', () => {
+  assert.equal(ruleIdFromPattern('Bash(rm -rf /*)'), 'OACB-RM-001');
+});
+
+test('ruleIdFromPattern: TF pattern', () => {
+  assert.equal(ruleIdFromPattern('Bash(terraform destroy *)'), 'OACB-TF-001');
+});
+
+test('ruleIdFromPattern: credential read pattern', () => {
+  assert.equal(ruleIdFromPattern('Read(**/.aws/credentials)'), 'OACB-READ-001');
+});
+
+test('classifyRule: rm maps to ASI02', () => {
+  assert.equal(classifyRule('Bash(rm -rf /*)'), 'ASI02');
+});
+
+test('classifyRule: credential read maps to ASI07', () => {
+  assert.equal(classifyRule('Read(**/.env)'), 'ASI07');
+});
+
+// ─── mergeOverrides ───────────────────────────────────────────────────────────
+
+test('mergeOverrides: scalar override wins', () => {
+  const base = { a: 1, b: 2 };
+  const override = { b: 99 };
+  assert.deepEqual(mergeOverrides(base, override), { a: 1, b: 99 });
+});
+
+test('mergeOverrides: array union (no duplicates)', () => {
+  const base = { deny: ['A', 'B'] };
+  const override = { deny: ['B', 'C'] };
+  const result = mergeOverrides(base, override);
+  assert.deepEqual(result.deny.sort(), ['A', 'B', 'C']);
+});
+
+test('mergeOverrides: nested object recurses', () => {
+  const base = { permissions: { deny: ['A'], defaultMode: 'acceptEdits' } };
+  const override = { permissions: { deny: ['B'], defaultMode: 'auto' } };
+  const result = mergeOverrides(base, override);
+  assert.deepEqual(result.permissions.deny.sort(), ['A', 'B']);
+  assert.equal(result.permissions.defaultMode, 'auto');
+});
+
+test('mergeOverrides: _oacbMeta key is skipped', () => {
+  const base = { a: 1 };
+  const override = { a: 2, _oacbMeta: { tier: 'baseline' } };
+  const result = mergeOverrides(base, override);
+  assert.equal(result.a, 2);
+  assert.equal(result._oacbMeta, undefined);
+});
+
+test('mergeOverrides: does not mutate base', () => {
+  const base = { deny: ['A'] };
+  mergeOverrides(base, { deny: ['B'] });
+  assert.deepEqual(base.deny, ['A']);
+});
+
+// ─── computeDeepDiff ─────────────────────────────────────────────────────────
+
+test('computeDeepDiff: identical objects produce empty diff', () => {
+  const obj = { permissions: { deny: ['A'] }, autoMode: { environment: [] } };
+  assert.deepEqual(computeDeepDiff(obj, obj), {});
+});
+
+test('computeDeepDiff: added key', () => {
+  const a = { x: 1 };
+  const b = { x: 1, y: 2 };
+  assert.deepEqual(computeDeepDiff(a, b), { y: { added: 2 } });
+});
+
+test('computeDeepDiff: removed key', () => {
+  const a = { x: 1, y: 2 };
+  const b = { x: 1 };
+  assert.deepEqual(computeDeepDiff(a, b), { y: { removed: 2 } });
+});
+
+test('computeDeepDiff: changed scalar', () => {
+  assert.deepEqual(computeDeepDiff({ a: 1 }, { a: 2 }), { a: { from: 1, to: 2 } });
+});
+
+test('computeDeepDiff: array diff shows added/removed items', () => {
+  const a = { deny: ['A', 'B'] };
+  const b = { deny: ['A', 'C'] };
+  const diff = computeDeepDiff(a, b);
+  assert.deepEqual(diff.deny.added, ['C']);
+  assert.deepEqual(diff.deny.removed, ['B']);
+});
+
+test('computeDeepDiff: _-prefixed keys are skipped', () => {
+  const a = { _oacb: { tier: 'shadow' }, x: 1 };
+  const b = { _oacb: { tier: 'baseline' }, x: 1 };
+  assert.deepEqual(computeDeepDiff(a, b), {});
+});
+
+// ─── computeGaps ─────────────────────────────────────────────────────────────
+
+const BASELINE_FIXTURE = {
+  _oacb: { tier: 'baseline' },
+  permissions: {
+    deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'],
+    disableBypassPermissionsMode: 'disable',
+  },
+  autoMode: {},
+  hooks: {
+    PreToolUse: [
+      {
+        matcher: 'Bash',
+        hooks: [{ type: 'command', command: '/usr/local/share/oacb/hooks/oacb-enforce.sh', timeout: 5000 }],
+      },
+    ],
+  },
+};
+
+test('computeGaps: fully-compliant settings → no gaps', () => {
+  const current = {
+    permissions: {
+      deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'],
+      disableBypassPermissionsMode: 'disable',
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  assert.deepEqual(computeGaps(current, BASELINE_FIXTURE), []);
+});
+
+test('computeGaps: missing deny rule reports a gap', () => {
+  const current = {
+    permissions: {
+      deny: ['Bash(rm -rf /*)'], // missing terraform destroy
+      disableBypassPermissionsMode: 'disable',
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  const gaps = computeGaps(current, BASELINE_FIXTURE);
+  assert.ok(gaps.some(g => g.ruleId === 'OACB-TF-001'), 'expected OACB-TF-001 gap');
+});
+
+test('computeGaps: missing hook reports OACB-HOOK-001', () => {
+  const current = {
+    permissions: { deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'], disableBypassPermissionsMode: 'disable' },
+    hooks: {}, // no hooks
+  };
+  const gaps = computeGaps(current, BASELINE_FIXTURE);
+  assert.ok(gaps.some(g => g.ruleId === 'OACB-HOOK-001'), 'expected OACB-HOOK-001 gap');
+});
+
+test('computeGaps: wrong disableBypassPermissionsMode reports OACB-BYPASS-001', () => {
+  const current = {
+    permissions: {
+      deny: ['Bash(rm -rf /*)', 'Bash(terraform destroy *)'],
+      disableBypassPermissionsMode: 'enable', // wrong
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  const gaps = computeGaps(current, BASELINE_FIXTURE);
+  assert.ok(gaps.some(g => g.ruleId === 'OACB-BYPASS-001'), 'expected OACB-BYPASS-001 gap');
+});
+
+test('computeGaps: empty current settings reports multiple gaps', () => {
+  const gaps = computeGaps({}, BASELINE_FIXTURE);
+  assert.ok(gaps.length > 0, 'expected gaps for empty settings');
+});
+
+test('computeGaps: deduplicates gap by rule ID', () => {
+  // Both rm patterns map to OACB-RM-001 — should report it only once
+  const baseline = {
+    _oacb: { tier: 'baseline' },
+    permissions: {
+      deny: ['Bash(rm -rf /*)', 'Bash(rm -rf ~*)', 'Bash(rm -fr /*)'],
+      disableBypassPermissionsMode: 'disable',
+    },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: '/usr/local/share/oacb/hooks/oacb-enforce.sh' }] },
+      ],
+    },
+  };
+  const current = {
+    permissions: { deny: [], disableBypassPermissionsMode: 'disable' },
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: `${os.homedir()}/.claude/hooks/oacb-enforce.sh` }] },
+      ],
+    },
+  };
+  const gaps = computeGaps(current, baseline);
+  const rmGaps = gaps.filter(g => g.ruleId === 'OACB-RM-001');
+  assert.equal(rmGaps.length, 1, 'OACB-RM-001 should appear exactly once');
+});
+
+// ─── buildOacbHookEntries ─────────────────────────────────────────────────────
+
+test('buildOacbHookEntries: hook paths are rewritten to ~/.claude/hooks/', () => {
+  const hooks = buildOacbHookEntries(BASELINE_FIXTURE);
+  const hookCmd = hooks.PreToolUse[0].hooks[0].command;
+  const expectedPath = path.join(os.homedir(), '.claude', 'hooks', 'oacb-enforce.sh');
+  assert.equal(hookCmd, expectedPath);
+});
+
+test('buildOacbHookEntries: does not mutate original baseline', () => {
+  const originalCmd = BASELINE_FIXTURE.hooks.PreToolUse[0].hooks[0].command;
+  buildOacbHookEntries(BASELINE_FIXTURE);
+  assert.equal(BASELINE_FIXTURE.hooks.PreToolUse[0].hooks[0].command, originalCmd);
+});
+
+test('buildOacbHookEntries: returns all hook events from baseline', () => {
+  const hooks = buildOacbHookEntries(BASELINE_FIXTURE);
+  assert.ok(Array.isArray(hooks.PreToolUse), 'PreToolUse should be present');
+});
+
+// ─── hasOacbHook ─────────────────────────────────────────────────────────────
+
+test('hasOacbHook: detects hook present in settings', () => {
+  const settings = {
+    hooks: {
+      PreToolUse: [
+        { hooks: [{ type: 'command', command: '/Users/test/.claude/hooks/oacb-enforce.sh' }] },
+      ],
+    },
+  };
+  assert.equal(hasOacbHook(settings, 'PreToolUse', 'oacb-enforce.sh'), true);
+});
+
+test('hasOacbHook: returns false when hook not present', () => {
+  const settings = { hooks: { PreToolUse: [] } };
+  assert.equal(hasOacbHook(settings, 'PreToolUse', 'oacb-enforce.sh'), false);
+});
+
+test('hasOacbHook: returns false when event not present', () => {
+  assert.equal(hasOacbHook({}, 'PreToolUse', 'oacb-enforce.sh'), false);
+});