unbound-cli 0.9.1 → 0.9.3

package/src/commands/oacb.js

@@ -4,16 +4,38 @@ const fs = require('node:fs/promises');
 const path = require('node:path');
 const os = require('node:os');
 const { spawnSync } = require('node:child_process');
+const TOML = require('@iarna/toml');
 const api = require('../api');
 const config = require('../config');
 const output = require('../output');
 
+const crypto = require('node:crypto');
+
 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 OACB_PINNED_REF = 'v0.2.0';
+const PKG_VERSION = '0.2.0';
+const TIERS = ['shadow', 'receipts', 'baseline', 'strict', 'paranoid'];
+const AGENTS = ['claude-code', 'codex'];
+
+// Consent receipt path
+const CONSENT_RECEIPT_PATH = path.join(os.homedir(), '.claude', 'oacb-consent.json');
+
+// Claude Code paths
+const CLAUDE_HOOKS_DIR = path.join(os.homedir(), '.claude', 'hooks');
+const CLAUDE_SETTINGS_PATH = path.join(os.homedir(), '.claude', 'settings.json');
+const CLAUDE_SETTINGS_BACKUP_PATH = path.join(os.homedir(), '.claude', 'settings.json.oacb-backup');
+
+// Codex paths
+const CODEX_HOOKS_DIR = path.join(os.homedir(), '.codex', 'hooks');
+const CODEX_CONFIG_PATH = path.join(os.homedir(), '.codex', 'config.toml');
+const CODEX_META_PATH = path.join(os.homedir(), '.codex', 'oacb-meta.json');
+const CODEX_CONSENT_RECEIPT_PATH = path.join(os.homedir(), '.codex', 'oacb-consent.json');
+
+// Legacy aliases kept for backward compat with internal helpers
+const HOOKS_DIR = CLAUDE_HOOKS_DIR;
+const SETTINGS_PATH = CLAUDE_SETTINGS_PATH;
+const SETTINGS_BACKUP_PATH = CLAUDE_SETTINGS_BACKUP_PATH;
+
 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',
@@ -26,31 +48,33 @@ const HOOK_NAME_MAP = {
 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.')
+    .description('OACB — Open Autonomous Coding-agent Baseline. Apply, audit, and manage the security baseline for AI coding agents.')
     .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
+  unbound oacb check                                # verify install state (all agents)
+  unbound oacb apply                                # pick a tier interactively (claude-code)
+  unbound oacb apply --agent codex --tier baseline  # apply to Codex CLI
+  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')
+    .description('Pre-flight: verify agent installs, versions, 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')
+    .description('Score current agent settings against the OACB baseline; report gaps by ASI ID')
+    .option('--agent <agent>', `agent to audit (${AGENTS.join('|')})`, 'claude-code')
     .option('--tier <tier>', `tier to compare against (${TIERS.join('|')})`, 'baseline')
     .option('--format <fmt>', 'output format: table | json', 'table')
     .action(async (opts) => {
@@ -59,11 +83,16 @@ Read the framework at https://github.com/websentry-ai/oacb before applying basel
     });
 
   cmd.command('apply')
-    .description('Apply an OACB tier: download hooks + write ~/.claude/settings.json overlay')
+    .description('Apply an OACB tier: download hooks + write agent config')
+    .option('--agent <agent>', `agent to configure (${AGENTS.join('|')}); prompted if omitted`)
     .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('--overrides <path>', 'path to a local JSON file layered on top of the baseline tier (claude-code only)')
+    .option('--dry-run', 'go through all steps but do not write files', false)
+    .option('--preview-only', 'print policy + dry-run, do not install', false)
+    .option('--yes', 'non-interactive (CI / MDM); still writes consent record', false)
+    .option('--print-policy', 'emit resolved policy JSON to stdout', false)
     .option('--local-hooks <dir>', 'dev: copy hook scripts from a local directory instead of downloading from GitHub (overrides OACB_LOCAL_HOOKS_DIR)')
+    .option('--local-managed-settings <dir>', 'dev: load managed-settings/config from a local directory instead of downloading from GitHub (overrides OACB_LOCAL_SETTINGS_DIR)')
     .action(async (opts) => {
       try { await handleApply(opts); }
       catch (e) { output.error(e.message); process.exitCode = 1; }
@@ -71,6 +100,7 @@ Read the framework at https://github.com/websentry-ai/oacb before applying basel
 
   cmd.command('doctor')
     .description('Run the OACB conformance suite against installed hooks to verify enforcement')
+    .option('--agent <agent>', `agent to test (${AGENTS.join('|')})`, 'claude-code')
     .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)
@@ -80,7 +110,7 @@ Read the framework at https://github.com/websentry-ai/oacb before applying basel
     });
 
   cmd.command('diff')
-    .description('Show the settings delta between two OACB tiers')
+    .description('Show the settings delta between two OACB tiers (claude-code only)')
     .option('--from <tier>', 'source tier (auto-detected from settings.json if omitted)')
     .option('--to <tier>', 'target tier', 'baseline')
     .action(async (opts) => {
@@ -89,12 +119,38 @@ Read the framework at https://github.com/websentry-ai/oacb before applying basel
     });
 
   cmd.command('remove')
-    .description('Remove OACB from ~/.claude/settings.json and delete installed hook scripts')
+    .description('Remove OACB from agent config and delete installed hook scripts')
+    .option('--agent <agent>', `agent to remove from (${AGENTS.join('|')})`, 'claude-code')
     .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; }
     });
+
+  cmd.command('why')
+    .description('Explain the most recent block or warn from the OACB audit log')
+    .option('--agent <agent>', `agent to read audit log from (${AGENTS.join('|')})`, 'claude-code')
+    .action(async (opts) => {
+      try { await handleWhy(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('rules')
+    .description('Browse the OACB rule registry')
+    .option('--risk <level>', 'filter by risk level (low|medium|high|critical)')
+    .option('--search <term>', 'substring match on rule ID or description')
+    .action(async (opts) => {
+      try { await handleRules(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
+
+  cmd.command('status')
+    .description('Show OACB install state: tier, expiry, and last 7 days of audit counts')
+    .option('--agent <agent>', `agent to inspect (${AGENTS.join('|')})`, 'claude-code')
+    .action(async (opts) => {
+      try { await handleStatus(opts); }
+      catch (e) { output.error(e.message); process.exitCode = 1; }
+    });
 }
 
 // ─── Handlers ────────────────────────────────────────────────────────────────
@@ -103,35 +159,59 @@ async function handleCheck() {
   const cfg = config.readConfig();
   const hasUnboundSession = !!cfg.api_key;
 
+  const { execSync } = require('node:child_process');
+
   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 */ }
+  } catch (_) {}
+
+  let codexVersion = null;
+  try {
+    codexVersion = execSync('codex --version', {
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 3000,
+    }).toString().trim();
+  } catch (_) {}
 
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
   let claudeSettingsExist = false;
-  try { await fs.access(settingsPath); claudeSettingsExist = true; } catch (_) {}
+  try { await fs.access(CLAUDE_SETTINGS_PATH); claudeSettingsExist = true; } catch (_) {}
 
-  const appliedTier = await detectCurrentTier();
+  let codexConfigExists = false;
+  try { await fs.access(CODEX_CONFIG_PATH); codexConfigExists = true; } catch (_) {}
 
-  const hookStates = await Promise.all(
+  const claudeTier = await detectCurrentTier();
+  const codexTier = await detectCodexTier();
+
+  const claudeHookStates = await Promise.all(
+    HOOK_NAMES.map(async (n) => {
+      try { await fs.access(path.join(CLAUDE_HOOKS_DIR, n)); return true; }
+      catch (_) { return false; }
+    })
+  );
+  const codexHookStates = await Promise.all(
     HOOK_NAMES.map(async (n) => {
-      try { await fs.access(path.join(HOOKS_DIR, n)); return true; }
+      try { await fs.access(path.join(CODEX_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)'],
+    ['Unbound session', hasUnboundSession ? 'logged in' : 'not logged in (optional)'],
+    ['─── Claude Code ───', ''],
     ['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 tier applied', claudeTier !== 'none' ? claudeTier : 'none (run `unbound oacb apply`)'],
+    ['Hooks installed', `${claudeHookStates.filter(Boolean).length} / ${HOOK_NAMES.length}`],
+    ['─── Codex CLI ─────', ''],
+    ['Codex on PATH', codexVersion || 'not detected'],
+    ['~/.codex/config.toml', codexConfigExists ? 'found' : 'not found'],
+    ['OACB tier applied', codexTier !== 'none' ? codexTier : 'none (run `unbound oacb apply --agent codex`)'],
+    ['Hooks installed', `${codexHookStates.filter(Boolean).length} / ${HOOK_NAMES.length}`],
+    ['─────────────────', ''],
     ['OACB pinned ref', OACB_PINNED_REF],
   ]);
 
@@ -141,34 +221,44 @@ async function handleCheck() {
     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.');
+  if (claudeTier === 'none' && codexTier === 'none') {
+    output.warn('No OACB tier applied to any agent. Run `unbound oacb apply` to start with shadow tier.');
   }
 
   output.success('Pre-flight complete.');
 }
 
-async function handleAudit({ tier, format }) {
+async function handleAudit({ agent, tier, format }) {
+  validateAgent(agent);
   validateTier(tier);
-  const spin = output.spinner(`Fetching OACB ${tier} baseline...`);
+
+  const spin = output.spinner(`Fetching OACB ${agent} ${tier} baseline...`);
   let baseline;
   try {
-    baseline = await fetchBaseline(tier);
+    baseline = await fetchBaseline(tier, agent);
     spin.stop();
   } catch (e) {
     spin.fail(`Could not fetch baseline: ${e.message}`);
     throw e;
   }
 
-  const current = await loadMergedSettings();
-  const gaps = computeGaps(current, baseline);
+  let current;
+  if (agent === 'codex') {
+    current = await loadCodexConfig();
+  } else {
+    current = await loadMergedSettings();
+  }
+
+  const gaps = agent === 'codex'
+    ? computeCodexGaps(current, baseline)
+    : computeGaps(current, baseline);
 
   if (format === 'json') {
-    process.stdout.write(JSON.stringify({ tier, ref: OACB_PINNED_REF, gaps }, null, 2) + '\n');
+    process.stdout.write(JSON.stringify({ agent, tier, ref: OACB_PINNED_REF, gaps }, null, 2) + '\n');
     return;
   }
 
-  output.info(`OACB audit — tier=${tier}  ref=${OACB_PINNED_REF}`);
+  output.info(`OACB audit — agent=${agent} tier=${tier}  ref=${OACB_PINNED_REF}`);
   if (gaps.length === 0) {
     output.success('No gaps. Current settings satisfy the OACB tier baseline.');
     return;
@@ -183,111 +273,255 @@ async function handleAudit({ tier, format }) {
       { key: 'desc', header: 'Description' },
     ]
   );
-  output.info(`Run \`unbound oacb apply --tier ${tier}\` to remediate.`);
+  output.info(`Run \`unbound oacb apply --agent ${agent} --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' },
+async function handleApply({ agent: agentFlag, tier, overrides, dryRun, previewOnly, yes: nonInteractive, printPolicy, localHooks, localManagedSettings }) {
+  if (previewOnly) dryRun = true;
+
+  if (overrides && agentFlag === 'codex') {
+    output.warn('--overrides is not supported for the codex agent and will be ignored.');
+    overrides = undefined;
+  }
+
+  // ── Agent selection ───────────────────────────────────────────────────────
+  // --agent flag: single agent, skip prompt. No flag: multi-select (or CI default).
+  let agents;
+  if (agentFlag) {
+    validateAgent(agentFlag);
+    agents = [agentFlag];
+  } else if (nonInteractive) {
+    agents = ['claude-code'];
+  } else {
+    agents = await output.multiSelect('Select agents to configure:', [
+      { label: 'claude-code — Claude Code CLI', value: 'claude-code' },
+      { label: 'codex       — OpenAI Codex CLI', value: 'codex' },
     ]);
+    if (agents.length === 0) {
+      output.warn('No agents selected — nothing to do.');
+      return;
+    }
+  }
+
+  // ── Tier selection (shared across agents) ─────────────────────────────────
+  if (!tier) {
+    if (nonInteractive) {
+      tier = 'shadow';
+    } else {
+      tier = await output.select('Select OACB security tier:', [
+        { label: 'shadow    — silent observation, logs all commands, blocks nothing', value: 'shadow' },
+        { label: 'receipts  — visible warnings, engineer sees risky commands, can abort. Expires in 30 days', value: 'receipts' },
+        { label: 'baseline  — standard enforcement, blocks critical ops, asks before high-risk', value: 'baseline' },
+        { label: 'strict    — tighter, warns on medium, blocks high and critical',    value: 'strict' },
+        { label: 'paranoid  — maximum, blocks medium/high/critical, disables auto mode', value: 'paranoid' },
+      ]);
+    }
   }
   validateTier(tier);
 
-  const spin = output.spinner(`Fetching OACB ${tier} baseline from GitHub...`);
-  let baseline;
+  // ── Shared ceremony (runs once regardless of how many agents are selected) ─
+  // printPolicy and nonInteractive skip the ceremony.
+  const runCeremony = !nonInteractive && !printPolicy;
+  if (runCeremony) printTierMatrix(tier);
+
+  // ── printPolicy: emit resolved policy for each agent and return ───────────
+  if (printPolicy) {
+    for (const agent of agents) {
+      if (agents.length > 1) output.info(`\n── ${agent} ──`);
+      const baseline = await _fetchBaseline(tier, agent, localManagedSettings);
+      if (agent === 'codex') {
+        process.stdout.write(TOML.stringify(mergeCodexConfig({}, baseline)) + '\n');
+      } else {
+        let effective = deepClone(baseline);
+        if (overrides) effective = mergeOverrides(effective, JSON.parse(await fs.readFile(overrides, 'utf8')));
+        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');
+      }
+    }
+    return;
+  }
+
+  // ── dryRun: show per-agent diffs, then one shared history dry-run, return ─
+  if (dryRun) {
+    for (const agent of agents) {
+      if (agents.length > 1) output.info(`\n── ${agent} ──`);
+      const baseline = await _fetchBaseline(tier, agent, localManagedSettings);
+      if (agent === 'codex') {
+        output.info(`--dry-run: showing what would be merged into ${CODEX_CONFIG_PATH}`);
+        process.stdout.write(TOML.stringify(mergeCodexConfig({}, baseline)) + '\n');
+        output.info('  Hook scripts that would be installed:');
+        for (const name of HOOK_NAMES) process.stdout.write(`    ${path.join(CODEX_HOOKS_DIR, name)}\n`);
+      } else {
+        let effective = deepClone(baseline);
+        if (overrides) effective = mergeOverrides(effective, JSON.parse(await fs.readFile(overrides, 'utf8')));
+        output.info(`--dry-run: showing what would be merged into ${CLAUDE_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(CLAUDE_HOOKS_DIR, name)}\n`);
+      }
+    }
+    if (runCeremony) await historyDryRun(tier, agents[0]);
+    return;
+  }
+
+  // ── History dry-run (once, shared) before writing anything ────────────────
+  if (runCeremony) await historyDryRun(tier, agents[0]);
+
+  // ── Install per agent ─────────────────────────────────────────────────────
+  for (const agent of agents) {
+    if (agents.length > 1) output.info(`\n── Applying to ${agent} ──`);
+    const baseline = await _fetchBaseline(tier, agent, localManagedSettings);
+    if (agent === 'codex') {
+      await _applyCodex({ baseline, tier, localHooks });
+    } else {
+      await _applyClaudeCode({ baseline, tier, overrides, localHooks });
+    }
+  }
+}
+
+// Fetch baseline config for a given tier + agent, respecting local override dir.
+async function _fetchBaseline(tier, agent, localManagedSettings) {
+  const settingsLocalDir = localManagedSettings || process.env.OACB_LOCAL_SETTINGS_DIR || null;
+  const spin = output.spinner(
+    settingsLocalDir
+      ? `Loading OACB ${agent} ${tier} baseline from local path...`
+      : `Fetching OACB ${agent} ${tier} baseline...`
+  );
   try {
-    baseline = await fetchBaseline(tier);
+    let baseline;
+    if (settingsLocalDir) {
+      if (agent === 'codex') {
+        baseline = TOML.parse(await fs.readFile(path.join(settingsLocalDir, `config.${tier}.toml`), 'utf8'));
+      } else {
+        baseline = JSON.parse(await fs.readFile(path.join(settingsLocalDir, `managed-settings.${tier}.json`), 'utf8'));
+      }
+    } else {
+      baseline = await fetchBaseline(tier, agent);
+    }
     spin.stop();
+    return baseline;
   } catch (e) {
-    spin.fail(`Could not fetch baseline: ${e.message}`);
+    spin.fail(`Could not load baseline: ${e.message}`);
     throw e;
   }
+}
 
+// Install OACB for claude-code (hooks + settings overlay + consent receipt).
+async function _applyClaudeCode({ baseline, tier, overrides, localHooks }) {
   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') {
+  if (tier !== 'shadow' && tier !== 'receipts') {
     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...'
+    hooksLocalDir ? `Installing hooks from local path: ${hooksLocalDir}...` : 'Downloading and installing OACB hook scripts...'
   );
   try {
-    await installHooks(hooksLocalDir);
-    hookSpin.succeed(`Installed ${HOOK_NAMES.length} hooks to ${HOOKS_DIR}`);
+    await installHooks(hooksLocalDir, 'claude-code');
+    hookSpin.succeed(`Installed ${HOOK_NAMES.length} hooks to ${CLAUDE_HOOKS_DIR}`);
   } catch (e) {
     hookSpin.fail(`Hook installation failed: ${e.message}`);
     throw e;
   }
 
-  const settingsSpin = output.spinner(`Merging OACB settings into ${SETTINGS_PATH}...`);
+  const expires = tier === 'receipts' ? computeExpiryDate(30) : null;
+  const settingsSpin = output.spinner(`Merging OACB settings into ${CLAUDE_SETTINGS_PATH}...`);
   try {
-    await writeSettingsOverlay(effective, tier);
-    settingsSpin.succeed(`Updated ${SETTINGS_PATH} (backup at ${SETTINGS_BACKUP_PATH})`);
+    await writeSettingsOverlay(effective, tier, expires ? { OACB_EXPIRES: expires } : undefined);
+    settingsSpin.succeed(`Updated ${CLAUDE_SETTINGS_PATH} (backup at ${CLAUDE_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.`);
+  await writeConsentReceipt(tier, 'claude-code').catch(() => {});
+
+  output.success(`OACB ${tier} applied (claude-code).`);
   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`.');
+  } else if (tier === 'receipts') {
+    output.info('Receipts: engineer sees WARN banners for risky commands and can abort. Expires in 30 days.');
+  }
+  output.info(`Verify with: unbound oacb doctor --tier ${tier}`);
+  output.info('');
+  output.info('  unbound oacb status          — current tier, expiry, last 7d counts');
+  output.info('  unbound oacb why             — explain the most recent block or warn');
+  output.info('  unbound oacb rules --risk critical  — browse the rule list');
+  output.info('  unbound oacb remove          — uninstall');
+}
+
+// Install OACB for codex (hooks + config.toml + consent receipt).
+async function _applyCodex({ baseline, tier, localHooks }) {
+  if (tier !== 'shadow' && tier !== 'receipts') {
+    output.warn(`Applying Codex tier=${tier}. approval_policy and sandbox_mode will be set accordingly.`);
+  }
+
+  const hooksLocalDir = localHooks || process.env.OACB_LOCAL_HOOKS_DIR || null;
+  const hookSpin = output.spinner(
+    hooksLocalDir ? `Installing Codex hooks from local path: ${hooksLocalDir}...` : 'Downloading and installing Codex hook scripts...'
+  );
+  try {
+    await installHooks(hooksLocalDir, 'codex');
+    hookSpin.succeed(`Installed ${HOOK_NAMES.length} hooks to ${CODEX_HOOKS_DIR}`);
+  } catch (e) {
+    hookSpin.fail(`Hook installation failed: ${e.message}`);
+    throw e;
   }
-  output.info('Verify with: unbound oacb doctor --tier ' + tier);
+
+  const configSpin = output.spinner(`Merging OACB settings into ${CODEX_CONFIG_PATH}...`);
+  try {
+    await writeCodexConfig(baseline, tier);
+    configSpin.succeed(`Updated ${CODEX_CONFIG_PATH}`);
+  } catch (e) {
+    configSpin.fail(`Config write failed: ${e.message}`);
+    throw e;
+  }
+
+  await writeConsentReceipt(tier, 'codex').catch(() => {});
+
+  output.success(`OACB ${tier} applied (codex).`);
+  if (tier === 'shadow') {
+    output.info('Shadow: hooks log but never block. Review ~/.codex/hooks/oacb-audit.log for 2 weeks, then `unbound oacb apply --agent codex --tier baseline`.');
+  } else if (tier === 'receipts') {
+    output.info('Receipts: engineer sees WARN banners for risky commands and can abort. Expires in 30 days.');
+  }
+  output.info(`Verify with: unbound oacb doctor --agent codex --tier ${tier}`);
+  output.info('');
+  output.info('  unbound oacb status --agent codex    — current tier, expiry, last 7d counts');
+  output.info('  unbound oacb why --agent codex       — explain the most recent block or warn');
+  output.info('  unbound oacb rules --risk critical   — browse the rule list');
+  output.info('  unbound oacb remove --agent codex    — uninstall');
+  output.info(`  unbound oacb apply --agent codex --tier baseline  — graduate to baseline`);
 }
 
-async function handleDoctor({ tier, format, verbose }) {
+async function handleDoctor({ agent, tier, format, verbose }) {
+  validateAgent(agent);
   validateTier(tier);
 
-  // Verify at least the enforce hook is installed
-  const enforcePath = path.join(HOOKS_DIR, 'oacb-enforce.sh');
+  const hooksDir = agent === 'codex' ? CODEX_HOOKS_DIR : CLAUDE_HOOKS_DIR;
+  const enforcePath = path.join(hooksDir, 'oacb-enforce.sh');
   try {
     await fs.access(enforcePath);
   } catch {
-    output.error(`OACB hooks not installed. Run \`unbound oacb apply --tier ${tier}\` first.`);
+    output.error(`OACB hooks not installed for ${agent}. Run \`unbound oacb apply --agent ${agent} --tier ${tier}\` first.`);
     process.exitCode = 1;
     return;
   }
@@ -302,20 +536,26 @@ async function handleDoctor({ tier, format, verbose }) {
     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
-  );
+  const cases = corpus.filter(c => {
+    if (c.id.endsWith('-RESIDUAL')) return false;
+    if (!c.tiers || c.tiers[tier] === undefined) return false;
+    // Filter by agent: skip cases scoped to other agents
+    if (c.agents && !c.agents.includes(agent)) return false;
+    return true;
+  });
 
   if (format !== 'json') {
-    output.info(`Running ${cases.length} conformance cases for tier=${tier}...`);
+    output.info(`Running ${cases.length} conformance cases for agent=${agent} tier=${tier}...`);
   }
 
   const results = [];
   for (const testCase of cases) {
-    const hookBin = path.join(HOOKS_DIR, HOOK_NAME_MAP[testCase.hook || 'enforce']);
+    const hookFile = HOOK_NAME_MAP[testCase.hook || 'enforce'];
+    if (!hookFile) {
+      results.push({ id: testCase.id, passed: false, error: `unknown hook name '${testCase.hook}' in conformance corpus` });
+      continue;
+    }
+    const hookBin = path.join(hooksDir, hookFile);
     const result = runConformanceCase(testCase, hookBin, tier);
     results.push(result);
     if (format !== 'json' && verbose) {
@@ -329,11 +569,7 @@ async function handleDoctor({ tier, format, verbose }) {
 
   if (format === 'json') {
     process.stdout.write(JSON.stringify({
-      tier,
-      ref: OACB_PINNED_REF,
-      passed,
-      total: cases.length,
-      results,
+      agent, tier, ref: OACB_PINNED_REF, passed, total: cases.length, results,
     }, null, 2) + '\n');
     return;
   }
@@ -386,12 +622,20 @@ async function handleDiff({ from, to }) {
   process.stdout.write(JSON.stringify(computeDeepDiff(a, b), null, 2) + '\n');
 }
 
-async function handleRemove({ dryRun }) {
+async function handleRemove({ agent, dryRun }) {
+  validateAgent(agent);
+
+  if (agent === 'codex') {
+    await _removeCodex({ dryRun });
+    return;
+  }
+
+  // ── claude-code path ──────────────────────────────────────────────────────
   let settings = {};
   try {
-    settings = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8'));
+    settings = JSON.parse(await fs.readFile(CLAUDE_SETTINGS_PATH, 'utf8'));
   } catch (_) {
-    output.warn(`${SETTINGS_PATH} not found — nothing to remove.`);
+    output.warn(`${CLAUDE_SETTINGS_PATH} not found — nothing to remove.`);
     return;
   }
 
@@ -402,16 +646,13 @@ async function handleRemove({ dryRun }) {
   }
 
   const tier = meta.tier;
-  output.info(`Removing OACB (tier=${tier}) from ${SETTINGS_PATH}...`);
+  output.info(`Removing OACB (tier=${tier}) from ${CLAUDE_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);
+      const baseline = await fetchBaseline(tier, 'claude-code');
       spin.stop();
       contribution = { permissions: baseline.permissions || {}, autoMode: baseline.autoMode || {} };
     } catch (e) {
@@ -422,7 +663,6 @@ async function handleRemove({ dryRun }) {
 
   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 || []);
@@ -450,7 +690,6 @@ async function handleRemove({ dryRun }) {
     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)) {
@@ -465,7 +704,6 @@ async function handleRemove({ dryRun }) {
     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])) {
@@ -482,38 +720,87 @@ async function handleRemove({ dryRun }) {
     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`);
+      process.stdout.write(`  ${path.join(CLAUDE_HOOKS_DIR, name)}\n`);
+    }
+    return;
+  }
+
+  await fs.writeFile(CLAUDE_SETTINGS_PATH, JSON.stringify(cleaned, null, 2) + '\n', { mode: 0o600 });
+  output.success(`Wrote cleaned ${CLAUDE_SETTINGS_PATH}`);
+
+  try { await fs.unlink(CONSENT_RECEIPT_PATH); } catch (_) {}
+
+  await _deleteHooks(CLAUDE_HOOKS_DIR);
+  output.success('OACB removed from Claude Code. Run `unbound oacb check` to verify clean state.');
+}
+
+async function _removeCodex({ dryRun }) {
+  let meta = null;
+  try {
+    meta = JSON.parse(await fs.readFile(CODEX_META_PATH, 'utf8'));
+  } catch (_) {}
+
+  let existing = {};
+  try {
+    existing = TOML.parse(await fs.readFile(CODEX_CONFIG_PATH, 'utf8'));
+  } catch (_) {
+    output.warn(`${CODEX_CONFIG_PATH} not found — nothing to remove.`);
+    return;
+  }
+
+  if (!meta) {
+    // Check for OACB hooks in config even without meta
+    const hasHook = Object.values(existing.hooks || {}).flat().some(e =>
+      (e.hooks || []).some(h => /oacb-/.test(h.command || ''))
+    );
+    if (!hasHook) {
+      output.warn('No OACB installation found in Codex config.');
+      return;
+    }
+  }
+
+  const cleaned = stripOacbFromCodexConfig(existing);
+
+  if (dryRun) {
+    output.info(`--dry-run: showing cleaned ${CODEX_CONFIG_PATH} (not written)`);
+    process.stdout.write(TOML.stringify(cleaned) + '\n');
+    output.info('Hook scripts that would be deleted:');
+    for (const name of HOOK_NAMES) {
+      process.stdout.write(`  ${path.join(CODEX_HOOKS_DIR, name)}\n`);
     }
     return;
   }
 
-  await fs.writeFile(SETTINGS_PATH, JSON.stringify(cleaned, null, 2) + '\n', { mode: 0o600 });
-  output.success(`Wrote cleaned ${SETTINGS_PATH}`);
+  await fs.writeFile(CODEX_CONFIG_PATH, TOML.stringify(cleaned), { mode: 0o600 });
+  output.success(`Wrote cleaned ${CODEX_CONFIG_PATH}`);
+
+  try { await fs.unlink(CODEX_META_PATH); } catch (_) {}
+  try { await fs.unlink(CODEX_CONSENT_RECEIPT_PATH); } catch (_) {}
+
+  await _deleteHooks(CODEX_HOOKS_DIR);
+  output.success('OACB removed from Codex. Run `unbound oacb check` to verify clean state.');
+}
 
+async function _deleteHooks(hooksDir) {
   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);
-      }
+      try { await fs.unlink(path.join(hooksDir, name)); 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) {
+async function fetchBaseline(tier, agent = 'claude-code') {
+  if (agent === 'codex') {
+    const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/baseline/codex/config.${tier}.toml`;
+    return TOML.parse(await api.getRaw(url));
+  }
   const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/baseline/claude-code/managed-settings.${tier}.json`;
   return JSON.parse(await api.getRaw(url));
 }
@@ -528,15 +815,39 @@ async function fetchConformanceCorpus() {
 
 async function detectCurrentTier() {
   try {
-    const raw = await fs.readFile(SETTINGS_PATH, 'utf8');
+    const raw = await fs.readFile(CLAUDE_SETTINGS_PATH, 'utf8');
     return JSON.parse(raw)._oacbMeta?.tier || 'none';
   } catch (_) {
     return 'none';
   }
 }
 
+async function detectCodexTier() {
+  try {
+    const meta = JSON.parse(await fs.readFile(CODEX_META_PATH, 'utf8'));
+    return meta.tier || 'none';
+  } catch (_) {}
+  // Fallback: scan TOML for OACB_TIER env in hook entries
+  try {
+    const cfg = TOML.parse(await fs.readFile(CODEX_CONFIG_PATH, 'utf8'));
+    for (const entries of Object.values(cfg.hooks || {})) {
+      for (const entry of entries) {
+        for (const h of entry.hooks || []) {
+          if (h.env?.OACB_TIER) return h.env.OACB_TIER;
+        }
+      }
+    }
+  } catch (_) {}
+  return 'none';
+}
+
 async function loadMergedSettings() {
-  try { return JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8')); }
+  try { return JSON.parse(await fs.readFile(CLAUDE_SETTINGS_PATH, 'utf8')); }
+  catch (_) { return {}; }
+}
+
+async function loadCodexConfig() {
+  try { return TOML.parse(await fs.readFile(CODEX_CONFIG_PATH, 'utf8')); }
   catch (_) { return {}; }
 }
 
@@ -571,7 +882,6 @@ 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)) {
@@ -588,7 +898,6 @@ function computeGaps(current, baseline) {
     }
   }
 
-  // Hooks wired?
   if (!hasOacbHook(current, 'PreToolUse', 'oacb-enforce.sh')) {
     gaps.push({
       asi: 'ASI02',
@@ -598,7 +907,6 @@ function computeGaps(current, baseline) {
     });
   }
 
-  // disableBypassPermissionsMode
   const baseBypass = baseline.permissions?.disableBypassPermissionsMode;
   const curBypass = current.permissions?.disableBypassPermissionsMode;
   if (baseBypass && curBypass !== baseBypass) {
@@ -613,6 +921,42 @@ function computeGaps(current, baseline) {
   return gaps;
 }
 
+function computeCodexGaps(current, baselineConfig) {
+  const gaps = [];
+
+  if (current.approval_policy !== baselineConfig.approval_policy) {
+    gaps.push({
+      asi: 'ASI03',
+      ruleId: 'OACB-CODEX-POLICY-001',
+      description: `approval_policy should be "${baselineConfig.approval_policy}", found "${current.approval_policy || 'unset'}"`,
+      recommendation: 'Run `unbound oacb apply --agent codex --tier <tier>` to remediate',
+    });
+  }
+
+  if (current.sandbox_mode !== baselineConfig.sandbox_mode) {
+    gaps.push({
+      asi: 'ASI03',
+      ruleId: 'OACB-CODEX-POLICY-002',
+      description: `sandbox_mode should be "${baselineConfig.sandbox_mode}", found "${current.sandbox_mode || 'unset'}"`,
+      recommendation: 'Run `unbound oacb apply --agent codex --tier <tier>` to remediate',
+    });
+  }
+
+  const hasEnforceHook = (current.hooks?.PreToolUse || []).some(e =>
+    (e.hooks || []).some(h => /oacb-enforce\.sh/.test(h.command || ''))
+  );
+  if (!hasEnforceHook) {
+    gaps.push({
+      asi: 'ASI02',
+      ruleId: 'OACB-HOOK-001',
+      description: 'oacb-enforce.sh not registered in hooks.PreToolUse',
+      recommendation: 'Run `unbound oacb apply --agent codex --tier <tier>` to install hooks',
+    });
+  }
+
+  return gaps;
+}
+
 function hasOacbHook(settings, event, hookFile) {
   const hooks = settings.hooks?.[event] || [];
   return hooks.some(entry =>
@@ -624,30 +968,50 @@ function hasOacbHook(settings, event, hookFile) {
 
 // ─── Hook installation ────────────────────────────────────────────────────────
 
-async function installHooks(localDir = null) {
-  await fs.mkdir(HOOKS_DIR, { recursive: true });
+async function installHooks(localDir, agent = 'claude-code') {
+  const hooksDir = agent === 'codex' ? CODEX_HOOKS_DIR : CLAUDE_HOOKS_DIR;
+  await fs.mkdir(hooksDir, { 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}`;
+        const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/baseline/${agent}/hooks/${name}`;
         content = await api.getRaw(url);
       }
-      await fs.writeFile(path.join(HOOKS_DIR, name), content, { mode: 0o755 });
+      await fs.writeFile(path.join(hooksDir, name), content, { mode: 0o755 });
     })
   );
+
+  // Codex hooks source a shared core that is not bundled per-agent.
+  // Install it alongside the agent hooks so OACB_SHARED_DIR can resolve locally.
+  if (agent === 'codex') {
+    let coreContent;
+    if (localDir) {
+      const sharedDir = process.env.OACB_SHARED_DIR
+        || path.resolve(localDir, '..', '..', 'shared');
+      coreContent = await fs.readFile(path.join(sharedDir, 'oacb-enforce-core.sh'), 'utf8');
+    } else {
+      const url = `${OACB_RAW_BASE}/${OACB_PINNED_REF}/baseline/shared/oacb-enforce-core.sh`;
+      coreContent = await api.getRaw(url);
+    }
+    await fs.writeFile(path.join(hooksDir, 'oacb-enforce-core.sh'), coreContent, { mode: 0o755 });
+  }
 }
 
-// Build the OACB hook entries with ~/.claude/hooks/ paths (not the MDM paths)
-function buildOacbHookEntries(baseline) {
+// Build the OACB hook entries with agent-specific local paths.
+// extraEnv: optional object merged into each hook command's env (e.g. { OACB_EXPIRES: '2026-06-12' })
+function buildOacbHookEntries(baseline, extraEnv) {
   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));
+          h.command = path.join(CLAUDE_HOOKS_DIR, path.basename(h.command));
+        }
+        if (extraEnv && Object.keys(extraEnv).length > 0) {
+          h.env = Object.assign({}, h.env || {}, extraEnv);
         }
       }
     }
@@ -655,18 +1019,116 @@ function buildOacbHookEntries(baseline) {
   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.
+// ─── Codex config read/write ──────────────────────────────────────────────────
+
+// Pure: merge OACB hook entries and policy scalars into an existing parsed TOML config.
+// Expands ~ in hook command paths to os.homedir().
+// Existing non-OACB hook entries are preserved.
+// extraEnv: optional object merged into each hook command's env (e.g. { OACB_EXPIRES: '2026-06-12' })
+function mergeCodexConfig(existing, oacbConfig, extraEnv) {
+  const result = Object.assign({}, existing);
+
+  if (oacbConfig.approval_policy !== undefined) result.approval_policy = oacbConfig.approval_policy;
+  if (oacbConfig.sandbox_mode !== undefined) result.sandbox_mode = oacbConfig.sandbox_mode;
+
+  if (oacbConfig.shell_environment_policy) {
+    result.shell_environment_policy = Object.assign(
+      {}, result.shell_environment_policy || {}, oacbConfig.shell_environment_policy
+    );
+  }
+
+  const oacbHookRe = /oacb-[^/\\]+\.sh/;
+  result.hooks = Object.assign({}, result.hooks);
+
+  for (const [event, entries] of Object.entries(oacbConfig.hooks || {})) {
+    // Strip any previously installed OACB entries for this event
+    const userEntries = (result.hooks[event] || []).filter(e =>
+      !(e.hooks || []).some(h => oacbHookRe.test(h.command || ''))
+    );
+    // Expand ~ in command paths and inject extraEnv
+    const oacbEntries = entries.map(e => ({
+      ...e,
+      hooks: (e.hooks || []).map(h => {
+        // eslint-disable-next-line no-unused-vars
+        const { async: _async, ...rest } = h;  // strip unsupported async field
+        return {
+          ...rest,
+          command: typeof rest.command === 'string'
+            ? rest.command.replace(/^~(?=\/|$)/, os.homedir())
+            : rest.command,
+          ...(extraEnv && Object.keys(extraEnv).length > 0
+            ? { env: Object.assign({}, rest.env || {}, extraEnv) }
+            : {}),
+        };
+      }),
+    }));
+    result.hooks[event] = [...userEntries, ...oacbEntries];
+  }
+
+  return result;
+}
+
+// Pure: strip OACB hook entries from a parsed Codex TOML config.
+// Policy scalars (approval_policy, sandbox_mode) are left in place —
+// they may have been set by the user independently.
+function stripOacbFromCodexConfig(existing) {
+  const result = Object.assign({}, existing);
+  const oacbHookRe = /oacb-[^/\\]+\.sh/;
+
+  if (result.hooks) {
+    result.hooks = Object.assign({}, result.hooks);
+    for (const event of Object.keys(result.hooks)) {
+      if (!Array.isArray(result.hooks[event])) continue;  // e.g. hooks.state
+      result.hooks[event] = result.hooks[event].filter(e =>
+        !(e.hooks || []).some(h => oacbHookRe.test(h.command || ''))
+      );
+      if (!result.hooks[event].length) delete result.hooks[event];
+    }
+    if (!Object.keys(result.hooks).length) delete result.hooks;
+  }
+
+  return result;
+}
+
+async function writeCodexConfig(oacbConfig, tier) {
+  await fs.mkdir(path.dirname(CODEX_CONFIG_PATH), { recursive: true });
+
+  let existing = {};
+  try {
+    existing = TOML.parse(await fs.readFile(CODEX_CONFIG_PATH, 'utf8'));
+  } catch (_) {}
+
+  const extraEnv = {
+    OACB_SHARED_DIR: CODEX_HOOKS_DIR,
+    ...(tier === 'receipts' ? { OACB_EXPIRES: computeExpiryDate(30) } : {}),
+  };
+  const merged = mergeCodexConfig(existing, oacbConfig, extraEnv);
+  await fs.writeFile(CODEX_CONFIG_PATH, TOML.stringify(merged), { mode: 0o600 });
+
+  // Sidecar provenance — Codex ignores this file; OACB uses it for clean removal
+  await fs.writeFile(CODEX_META_PATH, JSON.stringify({
+    tier,
+    appliedAt: new Date().toISOString(),
+    ref: OACB_PINNED_REF,
+    // Fields read by handleStatus (mirrors writeConsentReceipt schema)
+    ts: new Date().toISOString(),
+    oacb_version: PKG_VERSION,
+    agent: 'codex',
+    ...(tier === 'receipts' ? { expires: computeExpiryDate(30) } : {}),
+  }, null, 2) + '\n', { mode: 0o600 });
+
+  return merged;
+}
+
+// ─── Settings helpers (Claude Code) ──────────────────────────────────────────
+
 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'));
+      return JSON.parse(await fs.readFile(CLAUDE_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) {
@@ -687,7 +1149,6 @@ async function stripOacbFromSettings(settings) {
 
   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] || []);
@@ -705,7 +1166,6 @@ async function stripOacbFromSettings(settings) {
     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)) {
@@ -720,7 +1180,6 @@ async function stripOacbFromSettings(settings) {
     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])) {
@@ -734,27 +1193,20 @@ async function stripOacbFromSettings(settings) {
   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 });
+async function writeSettingsOverlay(baseline, tier, extraEnv) {
+  await fs.mkdir(path.dirname(CLAUDE_SETTINGS_PATH), { recursive: true });
 
   let existing = {};
-  try { existing = JSON.parse(await fs.readFile(SETTINGS_PATH, 'utf8')); } catch (_) {}
+  try { existing = JSON.parse(await fs.readFile(CLAUDE_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 });
+    await fs.writeFile(CLAUDE_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']) {
@@ -768,19 +1220,16 @@ async function writeSettingsOverlay(baseline, tier) {
     if (perm[scalarKey] !== undefined) merged.permissions[scalarKey] = perm[scalarKey];
   }
 
-  // hooks: add OACB hook entries alongside existing entries (don't replace)
-  const oacbHooks = buildOacbHookEntries(baseline);
+  const oacbHooks = buildOacbHookEntries(baseline, extraEnv);
   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(),
@@ -791,30 +1240,10 @@ async function writeSettingsOverlay(baseline, tier) {
     },
   };
 
-  await fs.writeFile(SETTINGS_PATH, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+  await fs.writeFile(CLAUDE_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) {
@@ -879,10 +1308,21 @@ function computeDeepDiff(a, b) {
 
 // ─── Pure utilities ───────────────────────────────────────────────────────────
 
+// Returns a YYYY-MM-DD string for today + daysOffset days (UTC).
+function computeExpiryDate(daysOffset) {
+  const d = new Date();
+  d.setUTCDate(d.getUTCDate() + daysOffset);
+  return d.toISOString().slice(0, 10);
+}
+
 function validateTier(t) {
   if (!TIERS.includes(t)) throw new Error(`Invalid tier '${t}'. Expected one of: ${TIERS.join(', ')}`);
 }
 
+function validateAgent(a) {
+  if (!AGENTS.includes(a)) throw new Error(`Invalid agent '${a}'. Expected one of: ${AGENTS.join(', ')}`);
+}
+
 function mergeOverrides(base, overrides) {
   const result = deepClone(base);
   for (const [k, v] of Object.entries(overrides)) {
@@ -913,13 +1353,416 @@ function isVersionSupported(v) {
   return true;
 }
 
+// ─── Rule registry ────────────────────────────────────────────────────────────
+
+const RULE_REGISTRY = [
+  { id: 'OACB-OBF-001', risk: 'critical', description: 'Backslash-escaped binary (deny-evasion pattern)', mitre: 'T1027' },
+  { id: 'OACB-OBF-002', risk: 'critical', description: 'base64-decode piped to shell (exfil / RCE pattern)', mitre: 'T1059' },
+  { id: 'OACB-OBF-003', risk: 'critical', description: 'Process-substitution exec of remote content', mitre: 'T1059.004' },
+  { id: 'OACB-OBF-004', risk: 'critical', description: '/proc/self/root path traversal (sandbox-bypass)', mitre: 'T1055' },
+  { id: 'OACB-OBF-005', risk: 'critical', description: 'command-substitution resolves to dangerous binary (Flatt-class)', mitre: 'T1027' },
+  { id: 'OACB-OBF-006', risk: 'critical', description: 'Variable-substitution default resolves to dangerous binary', mitre: 'T1027' },
+  { id: 'OACB-COMPOUND-001', risk: 'medium', description: 'Compound command exceeds 10 separators (Adversa CVE class)', mitre: 'T1036' },
+  { id: 'OACB-RM-001', risk: 'critical', description: 'Destructive rm against home/root/system path', mitre: 'T1485' },
+  { id: 'OACB-RM-002', risk: 'critical', description: 'Destructive rm with glob against home/root wildcard', mitre: 'T1485' },
+  { id: 'OACB-RM-003', risk: 'critical', description: 'find -delete against home/root', mitre: 'T1485' },
+  { id: 'OACB-RM-004', risk: 'critical', description: 'find -exec rm against home/root', mitre: 'T1485' },
+  { id: 'OACB-RM-005', risk: 'critical', description: 'dd to block device (disk-wipe class)', mitre: 'T1485' },
+  { id: 'OACB-RM-006', risk: 'critical', description: 'mkfs against block device (disk-format class)', mitre: 'T1485' },
+  { id: 'OACB-GIT-001', risk: 'critical', description: 'Force-push to main/master/release/prod branch', mitre: 'T1565' },
+  { id: 'OACB-TF-001', risk: 'critical', description: 'terraform destroy (irreversible operation)', mitre: 'T1485' },
+  { id: 'OACB-TF-002', risk: 'high', description: 'terraform apply --auto-approve in autonomous mode', mitre: 'T1072' },
+  { id: 'OACB-TF-003', risk: 'high', description: 'terraform state rm (silent state divergence risk)', mitre: 'T1565' },
+  { id: 'OACB-DB-001', risk: 'high', description: 'drizzle-kit push --force against any database', mitre: 'T1485' },
+  { id: 'OACB-DB-002', risk: 'critical', description: 'prisma migrate reset drops all tables', mitre: 'T1485' },
+  { id: 'OACB-DB-003', risk: 'high', description: 'alembic downgrade without human approval', mitre: 'T1485' },
+  { id: 'OACB-NET-001', risk: 'critical', description: 'Remote-to-shell pipe (RCE vector)', mitre: 'T1059' },
+  { id: 'OACB-NET-002', risk: 'high', description: 'netcat/socat/telnet invocation (network egress / reverse-shell)', mitre: 'T1095' },
+  { id: 'OACB-NET-003', risk: 'critical', description: 'bash /dev/tcp reverse-shell pattern', mitre: 'T1059.004' },
+  { id: 'OACB-HIST-001', risk: 'critical', description: 'history -s/-a manipulation (denylist-bypass primitive)', mitre: 'T1562' },
+  { id: 'OACB-EVAL-001', risk: 'critical', description: 'eval prohibited at OACB baseline', mitre: 'T1059' },
+  { id: 'OACB-EXFIL-001', risk: 'high', description: 'Environment enumeration for credentials', mitre: 'T1552' },
+];
+
+// Static MITRE lookup by rule prefix
+const MITRE_MAP = {
+  'OACB-OBF': { id: 'T1027', name: 'Obfuscated Files or Information' },
+  'OACB-RM':  { id: 'T1485', name: 'Data Destruction' },
+  'OACB-GIT': { id: 'T1565', name: 'Data Manipulation' },
+  'OACB-TF':  { id: 'T1072', name: 'Software Deployment Tools / T1485 Data Destruction' },
+  'OACB-DB':  { id: 'T1485', name: 'Data Destruction' },
+  'OACB-NET': { id: 'T1059', name: 'Command and Scripting Interpreter' },
+  'OACB-HIST':{ id: 'T1562', name: 'Impair Defenses' },
+  'OACB-EVAL':{ id: 'T1059', name: 'Command and Scripting Interpreter' },
+  'OACB-EXFIL':{ id: 'T1552', name: 'Unsecured Credentials' },
+  'OACB-COMPOUND':{ id: 'T1036', name: 'Masquerading' },
+};
+
+function mitreForRule(ruleId) {
+  for (const [prefix, info] of Object.entries(MITRE_MAP)) {
+    if (ruleId.startsWith(prefix)) return info;
+  }
+  return { id: 'unknown', name: 'unknown' };
+}
+
+// ─── printTierMatrix ─────────────────────────────────────────────────────────
+
+function printTierMatrix(selectedTier) {
+  const tiers = ['shadow', 'receipts', 'baseline', 'strict', 'paranoid'];
+  const risks = ['low', 'medium', 'high', 'critical'];
+  const actionLabel = { allow: 'AUDIT', warn: 'WARN ', ask: 'ASK  ', block: 'BLOCK' };
+  const col = 9;
+  const lines = [
+    '',
+    '  Policy matrix for this tier (> = selected):',
+    `  ${''.padEnd(14)}${risks.map(r => r.toUpperCase().padEnd(col)).join('')}`,
+    `  ${''.padEnd(14)}${risks.map(() => '─'.repeat(col - 1).padEnd(col)).join('')}`,
+  ];
+  for (const tier of tiers) {
+    const marker = tier === selectedTier ? '> ' : '  ';
+    const row = risks.map(risk => actionLabel[_simulateTierMatrix(tier, risk)].padEnd(col)).join('');
+    lines.push(`${marker}${tier.padEnd(12)}  ${row}`);
+  }
+  lines.push('');
+  process.stderr.write(lines.join('\n') + '\n');
+}
+
+// ─── historyDryRun ───────────────────────────────────────────────────────────
+
+async function historyDryRun(tier, agent) {
+  const commands = [];
+
+  // Try Claude Code session logs first (most accurate for auto-mode context)
+  const ccProjectsDir = path.join(os.homedir(), '.claude', 'projects');
+  try {
+    const projectDirs = await fs.readdir(ccProjectsDir);
+    for (const proj of projectDirs.slice(-5)) {  // last 5 projects to bound cost
+      const sessDir = path.join(ccProjectsDir, proj, 'sessions');
+      let sessFiles;
+      try { sessFiles = await fs.readdir(sessDir); } catch (_) { continue; }
+      for (const f of sessFiles.slice(-3)) {  // last 3 sessions per project
+        try {
+          const filePath = path.join(sessDir, f);
+          const stat = await fs.stat(filePath);
+          if (stat.size > 10 * 1024 * 1024) continue;  // skip files > 10MB
+          const content = await fs.readFile(filePath, 'utf8');
+          for (const line of content.trim().split('\n')) {
+            try {
+              const entry = JSON.parse(line);
+              const cmd = entry?.tool_input?.command || entry?.content?.[0]?.input?.command;
+              if (cmd && typeof cmd === 'string') commands.push(cmd.trim());
+            } catch (_) { /* skip malformed lines */ }
+          }
+        } catch (_) { /* skip unreadable files */ }
+      }
+    }
+  } catch (_) { /* no CC session logs — fall through */ }
+
+  // Fallback: shell history (last 30 days by line, capped at 500)
+  if (commands.length === 0) {
+    const histFile = process.env.HISTFILE ||
+      path.join(os.homedir(), process.env.SHELL?.includes('zsh') ? '.zsh_history' : '.bash_history');
+    try {
+      const histStat = await fs.stat(histFile);
+      if (histStat.size > 10 * 1024 * 1024) {
+        output.info('  History dry-run: shell history file exceeds 10MB — skipping.');
+        return;
+      }
+      const raw = await fs.readFile(histFile, 'utf8');
+      for (const line of raw.split('\n')) {
+        // Strip zsh extended-history prefix: ": <ts>:<elapsed>;<cmd>"
+        const stripped = line.replace(/^: \d+:\d+;/, '').trim();
+        if (stripped && !stripped.startsWith('#')) commands.push(stripped);
+      }
+    } catch (_) { /* no shell history available */ }
+  }
+
+  if (commands.length === 0) {
+    output.info('  History dry-run: no command history found — skipping.');
+    return;
+  }
+
+  const sample = commands.slice(-500);  // cap at 500 most recent
+  const results = { block: [], warn: [], ask: [], allow: [] };
+  for (const cmd of sample) {
+    const action = simulateTierAction(cmd, tier);
+    results[action].push(cmd);
+  }
+
+  output.info(`\n  History dry-run: ${sample.length} commands sampled (agent=${agent}, tier=${tier})`);
+  output.info(`    allow ${results.allow.length}  warn ${results.warn.length}  ask ${results.ask.length}  block ${results.block.length}`);
+
+  const notable = [...results.block.slice(0, 3), ...results.warn.slice(0, 2)];
+  if (notable.length > 0) {
+    output.info('  Commands that would be affected:');
+    for (const cmd of notable) {
+      const action = simulateTierAction(cmd, tier);
+      output.info(`    [${action.toUpperCase().padEnd(5)}] ${cmd.slice(0, 80)}`);
+    }
+  }
+  output.info('');
+}
+
+// ─── simulateTierAction ───────────────────────────────────────────────────────
+// JS reimplementation of the tier matrix for common rule patterns.
+// Exported for unit testing and history dry-run.
+
+function simulateTierAction(cmd, tier) {
+  const risk = _simulateClassifyRisk(cmd);
+  return _simulateTierMatrix(tier, risk);
+}
+
+function _simulateClassifyRisk(cmd) {
+  const c = cmd.trim();
+  // Critical patterns
+  if (/\brm\s+(-[rRfF]*[rR][rRfF]*|-r\s+-f|-f\s+-r|--recursive.*--force|--force.*--recursive)\b/.test(c) &&
+      /\s(\/|~|\$HOME|\$\{HOME\}|\/etc\/|\/var\/|\/usr\/)/.test(c)) return 'critical';
+  if (/\bterraform\s+destroy\b/.test(c)) return 'critical';
+  if (/\bgit\s+push\s+.*(--force|-f)\b.*\b(main|master|release|prod)/.test(c)) return 'critical';
+  if (/\bprisma\s+migrate\s+reset\b/.test(c)) return 'critical';
+  if (/\beval\s+/.test(c)) return 'critical';
+  if (/\b(bash|sh|zsh)\b.*\/dev\/tcp\//.test(c)) return 'critical';
+  if (/\bbase64\b.*\|\s*(bash|sh|zsh)\b/.test(c)) return 'critical';
+  if (/(curl|wget)\s+.*\|\s*(bash|sh|zsh)\b/.test(c)) return 'critical';
+  // High patterns
+  if (/\bterraform\s+apply\b.*--auto-approve\b/.test(c)) return 'high';
+  if (/\bterraform\s+state\s+rm\b/.test(c)) return 'high';
+  if (/\bdrizzle-kit\s+push\b.*--force\b/.test(c)) return 'high';
+  if (/\balembic\s+downgrade\b/.test(c)) return 'high';
+  if (/\b(nc|ncat|socat)\s+/.test(c)) return 'high';
+  // Medium patterns
+  const sepCount = (c.match(/(&&|\|\||;)/g) || []).length;
+  if (sepCount > 10) return 'medium';
+  // Default: low
+  return 'low';
+}
+
+function _simulateTierMatrix(tier, risk) {
+  const key = `${tier}:${risk}`;
+  const matrix = {
+    'shadow:low': 'allow', 'shadow:medium': 'allow', 'shadow:high': 'allow', 'shadow:critical': 'allow',
+    'receipts:low': 'allow', 'receipts:medium': 'warn', 'receipts:high': 'warn', 'receipts:critical': 'warn',
+    'baseline:low': 'allow', 'baseline:medium': 'allow', 'baseline:high': 'block', 'baseline:critical': 'block',
+    'strict:low': 'allow', 'strict:medium': 'warn', 'strict:high': 'block', 'strict:critical': 'block',
+    'paranoid:low': 'allow', 'paranoid:medium': 'block', 'paranoid:high': 'block', 'paranoid:critical': 'block',
+  };
+  return matrix[key] || 'block';
+}
+
+// ─── Consent receipt ──────────────────────────────────────────────────────────
+
+async function writeConsentReceipt(tier, agent) {
+  const userInfo = os.userInfo();
+  const hostname = os.hostname();
+  const machineId = crypto
+    .createHash('sha256')
+    .update(`${hostname}:${userInfo.username}`)
+    .digest('hex')
+    .slice(0, 16);
+
+  const receipt = {
+    ts: new Date().toISOString(),
+    username: userInfo.username,
+    hostname,
+    tier,
+    agent,
+    oacb_version: PKG_VERSION,
+    machine_id: machineId,
+    ...(tier === 'receipts' ? { expires: computeExpiryDate(30) } : {}),
+  };
+
+  const receiptPath = agent === 'codex' ? CODEX_CONSENT_RECEIPT_PATH : CONSENT_RECEIPT_PATH;
+  await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+  await fs.writeFile(receiptPath, JSON.stringify(receipt, null, 2) + '\n', { mode: 0o600 });
+
+  // Fire-and-forget POST to gateway if OACB_GATEWAY_URL is set.
+  // globalThis.fetch is available on Node 18+; no import needed.
+  if (process.env.OACB_GATEWAY_URL && typeof globalThis.fetch === 'function') {
+    globalThis.fetch(process.env.OACB_GATEWAY_URL + '/consent', {
+      method: 'POST',
+      body: JSON.stringify(receipt),
+      headers: { 'Content-Type': 'application/json' },
+    }).catch(() => {});
+  }
+
+  return receipt;
+}
+
+async function readConsentReceipt() {
+  try {
+    return JSON.parse(await fs.readFile(CONSENT_RECEIPT_PATH, 'utf8'));
+  } catch (_) {
+    return null;
+  }
+}
+
+// ─── handleWhy ───────────────────────────────────────────────────────────────
+
+async function handleWhy({ agent }) {
+  const logPath = agent === 'codex'
+    ? path.join(os.homedir(), '.codex', 'hooks', 'oacb-audit.log')
+    : path.join(os.homedir(), '.claude', 'hooks', 'oacb-audit.log');
+
+  let entry = null;
+  try {
+    const content = await fs.readFile(logPath, 'utf8');
+    const lines = content.trim().split('\n').filter(Boolean);
+    // Scan backwards: skip abort-only entries (engineer_aborted=true with no cmd)
+    // so we land on the meaningful warn/block that preceded it.
+    for (let i = lines.length - 1; i >= 0; i--) {
+      try {
+        const candidate = JSON.parse(lines[i]);
+        if (candidate.engineer_aborted && !candidate.cmd) continue;
+        entry = candidate;
+        break;
+      } catch (_) { /* skip malformed lines */ }
+    }
+  } catch (_) { /* file not found or unreadable */ }
+
+  if (!entry) {
+    output.info('No recent events found.');
+    return;
+  }
+
+  const mitre = mitreForRule(entry.rule || '');
+  const decisionLabel = (entry.decision || 'allow').toUpperCase();
+
+  process.stdout.write([
+    `Last event: ${decisionLabel} (${entry.ts || 'unknown'})`,
+    `Rule:       ${entry.rule || 'unknown'}`,
+    `Risk:       ${entry.risk || 'unknown'}`,
+    `Command:    ${(entry.cmd || '').slice(0, 80)}`,
+    `Reason:     ${entry.reason || 'unknown'}`,
+    '',
+    `MITRE: ${mitre.id} — ${mitre.name}`,
+    '',
+    (entry.decision === 'deny' || entry.decision === 'block')
+      ? 'This command was blocked by OACB enforcement. To allow it, remove OACB or escalate to a human approver.'
+      : entry.decision === 'warn'
+        ? 'This command was allowed with a warning. Engineer was notified.'
+        : 'This command was allowed.',
+    '',
+  ].join('\n'));
+}
+
+// ─── handleRules ─────────────────────────────────────────────────────────────
+
+async function handleRules({ risk, search }) {
+  let rules = RULE_REGISTRY;
+
+  if (risk) {
+    rules = rules.filter(r => r.risk === risk);
+  }
+  if (search) {
+    const term = search.toLowerCase();
+    rules = rules.filter(r =>
+      r.id.toLowerCase().includes(term) ||
+      r.description.toLowerCase().includes(term)
+    );
+  }
+
+  if (rules.length === 0) {
+    output.info('No rules match the given filters.');
+    return;
+  }
+
+  output.table(
+    rules.map(r => ({ id: r.id, risk: r.risk, mitre: r.mitre, desc: r.description })),
+    [
+      { key: 'id', header: 'Rule ID' },
+      { key: 'risk', header: 'Risk' },
+      { key: 'mitre', header: 'MITRE' },
+      { key: 'desc', header: 'Description' },
+    ]
+  );
+}
+
+// ─── handleStatus ─────────────────────────────────────────────────────────────
+
+async function handleStatus({ agent }) {
+  let receipt;
+  if (agent === 'codex') {
+    try { receipt = JSON.parse(await fs.readFile(CODEX_CONSENT_RECEIPT_PATH, 'utf8')); } catch (_) { receipt = null; }
+  } else {
+    receipt = await readConsentReceipt();
+  }
+
+  if (!receipt) {
+    output.warn('OACB does not appear to be installed — run `unbound oacb apply`');
+    return;
+  }
+
+  const logPath = agent === 'codex'
+    ? path.join(os.homedir(), '.codex', 'hooks', 'oacb-audit.log')
+    : path.join(os.homedir(), '.claude', 'hooks', 'oacb-audit.log');
+
+  // Expiry countdown
+  let expiryNote = '';
+  if (receipt.tier === 'receipts' && receipt.expires) {
+    const exp = new Date(receipt.expires);
+    const now = new Date();
+    const daysLeft = Math.ceil((exp - now) / (1000 * 60 * 60 * 24));
+    expiryNote = daysLeft > 0
+      ? ` (expires ${receipt.expires} — ${daysLeft} days remaining)`
+      : ` (EXPIRED ${receipt.expires} — run \`unbound oacb apply\` to renew)`;
+  }
+
+  // Audit log stats — last 7 days
+  const counts = { allow: 0, warn: 0, block: 0, deny: 0, aborted: 0 };
+  const ruleHits = {};
+  const sevenDaysAgo = new Date(Date.now() - 7 * 24 * 60 * 60 * 1000);
+  let logSize = 'not found';
+  let mostHitRule = 'none';
+
+  try {
+    const stat = await fs.stat(logPath);
+    logSize = `${(stat.size / 1024).toFixed(1)} KB`;
+    const content = await fs.readFile(logPath, 'utf8');
+    for (const line of content.trim().split('\n').filter(Boolean)) {
+      try {
+        const e = JSON.parse(line);
+        const entryTime = new Date(e.ts);
+        if (entryTime < sevenDaysAgo) continue;
+        const dec = e.engineer_aborted ? 'aborted' : (e.decision || 'allow');
+        counts[dec] = (counts[dec] || 0) + 1;
+        if (e.rule && e.rule !== 'OACB-DEFAULT-ALLOW' && e.rule !== 'OACB-SHADOW') {
+          ruleHits[e.rule] = (ruleHits[e.rule] || 0) + 1;
+        }
+      } catch (_) {}
+    }
+    // Find most hit rule
+    const topEntry = Object.entries(ruleHits).sort((a, b) => b[1] - a[1])[0];
+    if (topEntry) {
+      const ruleInfo = RULE_REGISTRY.find(r => r.id === topEntry[0]);
+      mostHitRule = ruleInfo
+        ? `${topEntry[0]} (${topEntry[1]}x) — ${ruleInfo.description}`
+        : `${topEntry[0]} (${topEntry[1]}x)`;
+    }
+  } catch (_) {}
+
+  output.keyValue([
+    ['Tier', `${receipt.tier}${expiryNote}`],
+    ['Agent', receipt.agent || agent],
+    ['Installed', receipt.ts || 'unknown'],
+    ['OACB version', receipt.oacb_version || 'unknown'],
+    ['Audit log', `${logPath} (${logSize})`],
+    ['─── Last 7 days ───', ''],
+    ['allow', String(counts.allow)],
+    ['warn', String(counts.warn)],
+    ['block/deny', String((counts.block || 0) + (counts.deny || 0))],
+    ['aborted', String(counts.aborted)],
+    ['Most hit rule', mostHitRule],
+  ]);
+}
+
 module.exports = {
   register,
-  // exported for unit tests only — not part of the public API
   __test__: {
     validateTier,
+    validateAgent,
     isVersionSupported,
     computeGaps,
+    computeCodexGaps,
     mergeOverrides,
     computeDeepDiff,
     buildOacbHookEntries,
@@ -927,5 +1770,14 @@ module.exports = {
     classifyRule,
     hasOacbHook,
     runConformanceCase,
+    mergeCodexConfig,
+    stripOacbFromCodexConfig,
+    simulateTierAction,
+    historyDryRun,
+    printTierMatrix,
+    writeConsentReceipt,
+    handleWhy,
+    handleStatus,
+    RULE_REGISTRY,
   },
 };