unbound-cli 1.5.0 → 1.6.3

package/package.json

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

package/src/commands/discover.js

@@ -16,7 +16,7 @@ const DISCOVERY_EXIT_UNSUPPORTED_OS = 3;
 // indefinitely. Discovery enforces this itself — on expiry it releases its lock,
 // reports the run as failed, and exits non-zero. Kept in sync with
 // setup/mdm/onboard.py's DISCOVERY_TIMEOUT_SECONDS.
-const DISCOVERY_TIMEOUT_SECONDS = 5400;
+const DISCOVERY_TIMEOUT_SECONDS = 9000;
 
 // Classifies a discovery subprocess exit code:
 // 'success' (scan ran), 'unsupported' (skipped on this OS), or 'failure'.

package/src/commands/doctor.js

@@ -90,7 +90,7 @@ Examples:
         }
 
         const C = output.colors;
-        const labelOf = (t) => t.label + (t.mode ? ` (${t.mode})` : '');
+        const labelOf = (t) => t.label + (t.mode && t.mode !== 'subscription' ? ` (${t.mode})` : '');
         const W = Math.max(7, ...tools.map((t) => labelOf(t).length)); // 7 = "API key"
 
         console.log('');
@@ -150,7 +150,8 @@ Examples:
             return;
           }
           const fixNow = root ? allFix : userFix;
-          output.info(`Reinstalling: ${fixNow.join(', ')}${root ? ' (org-wide, all users)' : ''}`);
+          const fixDisplay = (root ? tampered : userTampered).map(labelOf).join(', ');
+          output.info(`Reinstalling: ${fixDisplay}${root ? ' (org-wide, all users)' : ''}`);
           console.log('');
           const r = spawnSync(process.argv[0], [process.argv[1], 'setup', ...fixNow], { stdio: 'inherit' });
           if (!root && mdmFix.length) console.error(`  ${mdmNames} ${mdmFix.length === 1 ? 'is' : 'are'} set up by your organization — run ${C.bold('sudo unbound doctor --fix')} to repair ${mdmFix.length === 1 ? 'it' : 'them'}.`);

package/src/commands/setup.js

@@ -35,14 +35,16 @@ const SETUP_TOOLS = [
   { label: 'Codex \u2014 gateway (gateway)', value: 'codex-gw', script: 'codex/gateway/setup.py', group: 'codex' },
 ];
 
+// Labels drop the `(subscription)` suffix on the default mode and keep
+// `(gateway)` as the differentiator — matches what doctor/status render.
 const MDM_TOOLS = {
-  'cursor':                   { label: 'Cursor',                    script: 'cursor/mdm/setup.py' },
-  'copilot':                  { label: 'GitHub Copilot',            script: 'copilot/hooks/mdm/setup.py' },
-  'claude-code-subscription': { label: 'Claude Code (subscription)', script: 'claude-code/hooks/mdm/setup.py' },
-  'claude-code-gateway':      { label: 'Claude Code (gateway)',      script: 'claude-code/gateway/mdm/setup.py' },
-  'gemini-cli':               { label: 'Gemini CLI',                 script: 'gemini-cli/gateway/mdm/setup.py' },
-  'codex-subscription':       { label: 'Codex (subscription)',       script: 'codex/hooks/mdm/setup.py' },
-  'codex-gateway':            { label: 'Codex (gateway)',            script: 'codex/gateway/mdm/setup.py' },
+  'cursor':                   { label: 'Cursor',                script: 'cursor/mdm/setup.py' },
+  'copilot':                  { label: 'GitHub Copilot',        script: 'copilot/hooks/mdm/setup.py' },
+  'claude-code-subscription': { label: 'Claude Code',           script: 'claude-code/hooks/mdm/setup.py' },
+  'claude-code-gateway':      { label: 'Claude Code (gateway)', script: 'claude-code/gateway/mdm/setup.py' },
+  'gemini-cli':               { label: 'Gemini CLI',            script: 'gemini-cli/gateway/mdm/setup.py' },
+  'codex-subscription':       { label: 'Codex',                 script: 'codex/hooks/mdm/setup.py' },
+  'codex-gateway':            { label: 'Codex (gateway)',       script: 'codex/gateway/mdm/setup.py' },
 };
 
 // Default MDM tools for `sudo unbound onboard` (subscription mode for Claude Code/Codex since only one can be active)
@@ -59,13 +61,13 @@ const SETUP_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'codex-subscripti
 
 // Tool name → script mapping for automated tools
 const SETUP_TOOL_MAP = {
-  'cursor':                   { label: 'Cursor',                     script: 'cursor/setup.py' },
-  'copilot':                  { label: 'GitHub Copilot',             script: 'copilot/hooks/setup.py' },
-  'claude-code-subscription': { label: 'Claude Code (subscription)', script: 'claude-code/hooks/setup.py' },
-  'claude-code-gateway':      { label: 'Claude Code (gateway)',      script: 'claude-code/gateway/setup.py' },
-  'gemini-cli':               { label: 'Gemini CLI',                 script: 'gemini-cli/gateway/setup.py' },
-  'codex-subscription':       { label: 'Codex (subscription)',       script: 'codex/hooks/setup.py' },
-  'codex-gateway':            { label: 'Codex (gateway)',            script: 'codex/gateway/setup.py' },
+  'cursor':                   { label: 'Cursor',                script: 'cursor/setup.py' },
+  'copilot':                  { label: 'GitHub Copilot',        script: 'copilot/hooks/setup.py' },
+  'claude-code-subscription': { label: 'Claude Code',           script: 'claude-code/hooks/setup.py' },
+  'claude-code-gateway':      { label: 'Claude Code (gateway)', script: 'claude-code/gateway/setup.py' },
+  'gemini-cli':               { label: 'Gemini CLI',            script: 'gemini-cli/gateway/setup.py' },
+  'codex-subscription':       { label: 'Codex',                 script: 'codex/hooks/setup.py' },
+  'codex-gateway':            { label: 'Codex (gateway)',       script: 'codex/gateway/setup.py' },
 };
 
 /**
@@ -338,6 +340,56 @@ function runScriptPiped(scriptPath, args) {
   });
 }
 
+// Env vars Unbound writes during setup. The python `--clear` scripts strip
+// these from ONE rc file (the current shell's), so a user who installed under
+// zsh and runs nuke under bash leaves a stale `export …` in the other rc and
+// then `status` reports tampered. Sweep every candidate rc to close that gap.
+// Conservative: only UNBOUND_* names + ANTHROPIC_BASE_URL. Skip OPENAI_API_KEY
+// — it's a generic user-owned var that can have non-Unbound uses.
+const NUKE_ENV_VARS = [
+  'UNBOUND_API_KEY',
+  'UNBOUND_CLAUDE_API_KEY',
+  'UNBOUND_CODEX_API_KEY',
+  'UNBOUND_COPILOT_API_KEY',
+  'UNBOUND_CURSOR_API_KEY',
+  'ANTHROPIC_BASE_URL',
+];
+
+function nukeRcFiles() {
+  if (process.platform === 'win32') return [];
+  if (process.platform === 'darwin') return ['~/.zprofile', '~/.bash_profile', '~/.zshrc', '~/.bashrc'];
+  return ['~/.zshrc', '~/.bashrc', '~/.profile'];
+}
+
+// Removes `export NAME=...` lines for NUKE_ENV_VARS from every candidate rc.
+// On Windows, best-effort `reg delete` for each name. Returns a summary of
+// what changed so the nuke command can surface it.
+function clearUnboundEnvsEverywhere() {
+  const cleared = [];
+  if (process.platform === 'win32') {
+    for (const name of NUKE_ENV_VARS) {
+      const r = spawnSync('reg', ['delete', 'HKCU\\Environment', '/F', '/V', name],
+        { stdio: 'ignore', windowsHide: true });
+      if (r.status === 0) cleared.push(`${name} (registry)`);
+    }
+    return cleared;
+  }
+  const home = os.homedir();
+  const exportRe = new RegExp(`^\\s*export\\s+(${NUKE_ENV_VARS.join('|')})=`);
+  for (const rc of nukeRcFiles()) {
+    const rcPath = rc.replace(/^~/, home);
+    let text;
+    try { text = fs.readFileSync(rcPath, 'utf8'); } catch { continue; }
+    const lines = text.split('\n');
+    const kept = lines.filter((line) => !exportRe.test(line));
+    if (kept.length !== lines.length) {
+      fs.writeFileSync(rcPath, kept.join('\n'));
+      cleared.push(`${lines.length - kept.length} line(s) from ${path.basename(rcPath)}`);
+    }
+  }
+  return cleared;
+}
+
 /**
  * Returns true when the process has the privileges needed to touch system-level
  * (MDM) configuration. On Windows, `net session` succeeds only when elevated, so
@@ -911,6 +963,13 @@ Examples:
           output.info('Skipped MDM (system-level) config — that needs root. Re-run with sudo to remove it too.');
         }
 
+        // Sweep stale `export UNBOUND_*` / `ANTHROPIC_BASE_URL` lines from EVERY
+        // candidate rc file (the per-tool python clears only touch the current
+        // shell's rc, so a stale entry in another rc would survive and re-trip
+        // `unbound status` as tampered on the next run).
+        const envCleared = clearUnboundEnvsEverywhere();
+        if (envCleared.length) output.info(`Removed Unbound env: ${envCleared.join(', ')}.`);
+
         // Wipe credentials + settings last, regardless of tool-clear outcomes.
         config.clearConfig();
         output.success('Stored credentials and settings removed.');
@@ -988,4 +1047,6 @@ module.exports = {
   buildScriptArgs,
   scriptSupportsBackfill,
   resolveSetupAllTools,
+  clearUnboundEnvsEverywhere,
+  NUKE_ENV_VARS,
 };

package/src/commands/status.js

@@ -105,7 +105,7 @@ Examples:
           console.log(`  ${C.dim('None set up yet.')} Run ${C.bold('unbound setup')} to wire a tool.`);
         } else {
           for (const t of connected) {
-            const mode = t.mode ? C.dim(` (${t.mode})`) : '';
+            const mode = t.mode && t.mode !== 'subscription' ? C.dim(` (${t.mode})`) : '';
             let mark = C.green('✓');
             let note = '';
             if (t.status === 'tampered') { mark = C.red('✗'); note = C.dim(' — run `unbound doctor`'); }

package/src/toolHealth.js

@@ -20,6 +20,11 @@ const { spawnSync } = require('child_process');
 
 const HOME = os.homedir();
 const GATEWAY_DEFAULT = 'https://api.getunbound.ai';
+// Anchored to the install root + binary name so a hypothetical neighbor
+// (e.g. `unbound-hooks-v2`) can't accidentally satisfy the substring.
+const BINARY_MARKER = 'unbound-hook/unbound-hook';
+// Hard-coded by the ai.getunbound.runtime pkg (binary/src/unbound_hook/_resources.py).
+const BINARY_PATH = '/opt/unbound/current/unbound-hook/unbound-hook';
 
 function expand(p) {
   return p.startsWith('~') ? path.join(HOME, p.slice(1)) : p;
@@ -129,6 +134,22 @@ function envCheck(label, name, expected, kind = 'aux') {
   // A value that doesn't match what setup wrote (stale key, wrong gateway URL) is a
   // real misconfiguration: mark it not-ok so the tool reports tampered, not healthy.
   if (expected && r.value !== expected) {
+    // process.env can be a stale snapshot from a shell loaded before setup re-wrote
+    // the rc, so consult the rc files as a fallback before declaring a mismatch.
+    if (r.source === 'process env' && process.platform !== 'win32') {
+      const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, 'm');
+      for (const rc of rcFiles()) {
+        const text = readText(rc);
+        if (!text) continue;
+        const m = text.match(re);
+        if (!m) continue;
+        const rcVal = m[1].trim().replace(/^["']|["']$/g, '');
+        if (rcVal === expected) {
+          const rcSource = path.basename(expand(rc));
+          return { name: label, ok: true, kind, detail: `${name} set (${rcSource})`, summary: `${base} set` };
+        }
+      }
+    }
     return { name: label, ok: false, kind, warn: true, summary: `${base} differs from setup`, detail: `${name} set (${r.source}) but differs from what setup configured` };
   }
   return { name: label, ok: true, kind, detail: `${name} set (${r.source})`, summary: `${base} set` };
@@ -139,7 +160,7 @@ function envCheck(label, name, expected, kind = 'aux') {
 // A plain managed-settings.json (Claude Enterprise / generic MDM) does NOT count,
 // and a managed config that points at a missing hook script is a broken (tampered)
 // MDM install, not a healthy one. Returns { status: 'healthy'|'tampered'|null, checks }.
-function mdmDetect(family, dirOverride) {
+function mdmDetect(family, dirOverride, binaryPath) {
   // Only Cursor / Claude Code / Codex have a managed (MDM) directory. Copilot and
   // Gemini have none — their org install writes the same per-user config into
   // every profile, so they're checked exactly like a user-level tool.
@@ -158,7 +179,28 @@ function mdmDetect(family, dirOverride) {
   const scriptPath = path.join(dir, 'hooks', 'unbound.py');
 
   const cfgText = readText(configPath);
-  if (cfgText == null || !cfgText.includes('unbound.py')) return { status: null, checks: [] };
+  if (cfgText == null) return { status: null, checks: [] };
+  const hasBinary = cfgText.includes(BINARY_MARKER);
+  const hasPython = cfgText.includes('unbound.py');
+  if (!hasBinary && !hasPython) return { status: null, checks: [] };
+
+  // Binary install wins even when an `unbound.py` substring lingers (e.g.
+  // mid-migration the config can mention both; the per-MDM unbound.py script
+  // is no longer expected once binary is in play). Mirror the python branch's
+  // existence guard so a missing binary surfaces as tampered, not healthy.
+  if (hasBinary) {
+    const bp = binaryPath || BINARY_PATH;
+    const binaryOk = fileExists(bp);
+    return {
+      status: binaryOk ? 'healthy' : 'tampered',
+      checks: [
+        { name: 'MDM config', ok: true, kind: 'structural', detail: configPath, summary: 'managed config (binary)' },
+        { name: 'Hook binary', ok: binaryOk, kind: 'structural',
+          summary: binaryOk ? 'hook binary installed' : 'hook binary missing',
+          detail: binaryOk ? bp : `managed config references the hook binary but it isn't installed (${bp})` },
+      ],
+    };
+  }
 
   const scriptOk = fileExists(scriptPath);
   const checks = [
@@ -170,12 +212,13 @@ function mdmDetect(family, dirOverride) {
 
 // Marker that a claude/codex/cursor hooks block references unbound.py.
 function refsUnbound(obj) {
-  return JSON.stringify(obj || {}).includes('unbound.py');
+  const s = JSON.stringify(obj || {});
+  return s.includes('unbound.py') || s.includes(BINARY_MARKER);
 }
 
 // One descriptor per (tool, mode). `family` groups the two-mode tools so the
 // collapsed view shows a single line per product.
-function buildVariants(gatewayUrl, apiKey) {
+function buildVariants(gatewayUrl, apiKey, binaryPath) {
   const gw = (gatewayUrl || GATEWAY_DEFAULT).replace(/\/+$/, ''); // setup rstrips too
   return [
     {
@@ -221,14 +264,21 @@ function buildVariants(gatewayUrl, apiKey) {
     },
     {
       key: 'copilot', label: 'GitHub Copilot', family: 'copilot', mode: null,
-      checks: () => [
+      checks: () => {
         // Copilot has no managed (MDM) directory: the org install writes the same
         // ~/.copilot config into every user profile, so it's checked like a
         // user-level tool and never reports "managed by MDM".
-        configCheck('Config', '~/.copilot/hooks/unbound.json', { json: true, test: refsUnbound }),
-        scriptCheck('Hook script', '~/.copilot/hooks/unbound.py'),
-        envCheck('API key env', 'UNBOUND_COPILOT_API_KEY', apiKey),
-      ],
+        // Binary install of Copilot replaces the per-user `unbound.py` script with
+        // a config that points straight at the binary; skip the script check in
+        // that case so a clean binary install doesn't read as tampered.
+        const cfgText = readText('~/.copilot/hooks/unbound.json');
+        const hasBinary = cfgText != null && cfgText.includes(BINARY_MARKER);
+        const checks = [configCheck('Config', '~/.copilot/hooks/unbound.json', { json: true, test: refsUnbound })];
+        if (hasBinary) checks.push(scriptCheck('Hook binary', binaryPath || BINARY_PATH));
+        else checks.push(scriptCheck('Hook script', '~/.copilot/hooks/unbound.py'));
+        checks.push(envCheck('API key env', 'UNBOUND_COPILOT_API_KEY', apiKey));
+        return checks;
+      },
     },
     // Gemini CLI is intentionally omitted here — it isn't part of `setup --all`
     // and has no managed directory. Add it back when its scope is settled.
@@ -253,8 +303,10 @@ function detectVariant(variant) {
 // not-installed. This is what both `doctor` and `status` render.
 // `_mdmDirs` (test-only) overrides the system MDM directories per family so the
 // org-managed scenarios can be exercised without writing under /Library or /etc.
-function detectTools({ gatewayUrl, apiKey, _mdmDirs } = {}) {
-  const variants = buildVariants(gatewayUrl, apiKey).map(detectVariant);
+// `_binaryPath` (test-only) overrides the system hook-binary path so binary-mode
+// scenarios can be exercised without writing under /opt.
+function detectTools({ gatewayUrl, apiKey, _mdmDirs, _binaryPath } = {}) {
+  const variants = buildVariants(gatewayUrl, apiKey, _binaryPath).map(detectVariant);
   const families = [];
   const seen = new Set();
   for (const v of variants) {
@@ -272,7 +324,7 @@ function detectTools({ gatewayUrl, apiKey, _mdmDirs } = {}) {
     } else {
       const family = v.family;
       const label = v.label.replace(/ \(.*\)$/, '');
-      const mdm = mdmDetect(family, _mdmDirs && _mdmDirs[family]);
+      const mdm = mdmDetect(family, _mdmDirs && _mdmDirs[family], _binaryPath);
       if (mdm.status === 'healthy') {
         families.push({ key: family, label, family, mode: null, status: 'managed-by-mdm', checks: mdm.checks, scope: 'mdm' });
       } else if (mdm.status === 'tampered') {

package/test/setup-args.test.js

@@ -1,6 +1,9 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
-const { buildScriptArgs, scriptSupportsBackfill, resolveSetupAllTools } = require('../src/commands/setup');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { buildScriptArgs, scriptSupportsBackfill, resolveSetupAllTools, clearUnboundEnvsEverywhere, NUKE_ENV_VARS } = require('../src/commands/setup');
 
 // shellEscape single-quotes every value, so a real key surfaces as
 // --api-key '<key>' at the head of the argv tail.
@@ -147,3 +150,72 @@ test('resolveSetupAllTools(true): clear-all covers every tool incl. gateway mode
     assert.ok(tools.includes(t), `clear-all missing install-bundle tool ${t}`);
   }
 });
+
+// WEB-4886: nuke must strip stale UNBOUND_* / ANTHROPIC_BASE_URL lines from
+// EVERY candidate rc file, not just the one the python --clear script reaches.
+// Skip on Windows (rc-file sweep is POSIX-only; the registry path runs `reg`).
+if (process.platform !== 'win32') {
+  test('clearUnboundEnvsEverywhere: removes Unbound exports from every candidate rc, preserves other lines', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-nuke-'));
+    const origHome = process.env.HOME;
+    process.env.HOME = tmp;
+    try {
+      // .bashrc and .zshrc are in the candidate list on both darwin and linux,
+      // so the test is hermetic across CI (linux) and dev (darwin).
+      const bashrc = path.join(tmp, '.bashrc');
+      const zshrc = path.join(tmp, '.zshrc');
+      fs.writeFileSync(bashrc, [
+        '# user content',
+        'export UNBOUND_CURSOR_API_KEY="old"',
+        'export PATH=/usr/local/bin:$PATH',
+        'export UNBOUND_CLAUDE_API_KEY=abc',
+        '',
+      ].join('\n'));
+      fs.writeFileSync(zshrc, [
+        'export ANTHROPIC_BASE_URL="https://gateway.example"',
+        'alias ll="ls -la"',
+        '',
+      ].join('\n'));
+
+      const cleared = clearUnboundEnvsEverywhere();
+      assert.ok(cleared.length > 0, `expected something cleared, got ${JSON.stringify(cleared)}`);
+
+      const bNow = fs.readFileSync(bashrc, 'utf8');
+      assert.ok(!bNow.includes('UNBOUND_CURSOR_API_KEY'), bNow);
+      assert.ok(!bNow.includes('UNBOUND_CLAUDE_API_KEY'), bNow);
+      assert.ok(bNow.includes('# user content'), bNow);
+      assert.ok(bNow.includes('export PATH=/usr/local/bin:$PATH'), bNow);
+
+      const zNow = fs.readFileSync(zshrc, 'utf8');
+      assert.ok(!zNow.includes('ANTHROPIC_BASE_URL'), zNow);
+      assert.ok(zNow.includes('alias ll="ls -la"'), zNow);
+    } finally {
+      if (origHome === undefined) delete process.env.HOME;
+      else process.env.HOME = origHome;
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('clearUnboundEnvsEverywhere: leaves OPENAI_API_KEY alone (out of sweep scope)', () => {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-nuke-'));
+    const origHome = process.env.HOME;
+    process.env.HOME = tmp;
+    try {
+      const rc = path.join(tmp, '.zshrc');
+      fs.writeFileSync(rc, 'export OPENAI_API_KEY="user-owned"\n');
+      clearUnboundEnvsEverywhere();
+      assert.ok(fs.readFileSync(rc, 'utf8').includes('OPENAI_API_KEY'));
+    } finally {
+      if (origHome === undefined) delete process.env.HOME;
+      else process.env.HOME = origHome;
+      fs.rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+
+  test('NUKE_ENV_VARS covers every UNBOUND_* env var named in the variant set + ANTHROPIC_BASE_URL', () => {
+    for (const name of ['UNBOUND_API_KEY', 'UNBOUND_CLAUDE_API_KEY', 'UNBOUND_CODEX_API_KEY',
+                        'UNBOUND_COPILOT_API_KEY', 'UNBOUND_CURSOR_API_KEY', 'ANTHROPIC_BASE_URL']) {
+      assert.ok(NUKE_ENV_VARS.includes(name), `missing: ${name}`);
+    }
+  });
+}

package/test/tool-health.test.js

@@ -208,3 +208,114 @@ test('only four tools are reported (Gemini CLI is omitted)', () => {
     assert.deepEqual(new Set(keys), new Set(['cursor', 'claude-code', 'codex', 'copilot']));
   });
 });
+
+test('detectTools: cursor MDM binary (unbound-hook in hooks.json, binary installed) → managed-by-mdm', () => {
+  withHome((tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'Cursor');
+    const fakeBin = path.join(tmp, 'opt', 'unbound-hook');
+    writeFile(path.join(mdmDir, 'hooks.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: '/opt/unbound/current/unbound-hook/unbound-hook hook cursor PreToolUse' }] },
+    }));
+    writeFile(fakeBin, '');
+    const t = th.detectTools({ apiKey: 'k', _mdmDirs: { cursor: mdmDir }, _binaryPath: fakeBin }).find((x) => x.family === 'cursor');
+    assert.equal(t.status, 'managed-by-mdm');
+    assert.equal(t.scope, 'mdm');
+  });
+});
+
+test('detectTools: cursor MDM binary (unbound-hook in hooks.json, binary MISSING) → tampered', () => {
+  withHome((tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'Cursor');
+    writeFile(path.join(mdmDir, 'hooks.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: '/opt/unbound/current/unbound-hook/unbound-hook hook cursor PreToolUse' }] },
+    }));
+    const t = th.detectTools({
+      apiKey: 'k', _mdmDirs: { cursor: mdmDir },
+      _binaryPath: path.join(tmp, 'no-such-binary'),
+    }).find((x) => x.family === 'cursor');
+    assert.equal(t.status, 'tampered');
+    assert.equal(t.scope, 'mdm');
+  });
+});
+
+test('detectTools: claude-code MDM binary (unbound-hook in managed-settings.json, binary installed) → managed-by-mdm', () => {
+  withHome((tmp, th) => {
+    const mdmDir = path.join(tmp, 'mdm', 'ClaudeCode');
+    const fakeBin = path.join(tmp, 'opt', 'unbound-hook');
+    writeFile(path.join(mdmDir, 'managed-settings.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: '/opt/unbound/current/unbound-hook/unbound-hook hook claude-code PreToolUse' }] },
+    }));
+    writeFile(fakeBin, '');
+    const t = th.detectTools({ apiKey: 'k', _mdmDirs: { 'claude-code': mdmDir }, _binaryPath: fakeBin }).find((x) => x.family === 'claude-code');
+    assert.equal(t.status, 'managed-by-mdm');
+    assert.equal(t.scope, 'mdm');
+  });
+});
+
+test('detectTools: copilot user binary (unbound-hook in ~/.copilot/hooks/unbound.json, binary installed) → healthy', () => {
+  withHome((tmp, th) => {
+    const fakeBin = path.join(tmp, 'opt', 'unbound-hook');
+    writeFile(path.join(tmp, '.copilot', 'hooks', 'unbound.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: '/opt/unbound/current/unbound-hook/unbound-hook hook copilot PreToolUse' }] },
+    }));
+    writeFile(fakeBin, '');
+    process.env.UNBOUND_COPILOT_API_KEY = 'k';
+    try {
+      const t = th.detectTools({ apiKey: 'k', _binaryPath: fakeBin }).find((x) => x.family === 'copilot');
+      assert.equal(t.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_COPILOT_API_KEY;
+    }
+  });
+});
+
+test('detectTools: copilot user binary (unbound-hook in unbound.json, binary MISSING) → tampered', () => {
+  withHome((tmp, th) => {
+    writeFile(path.join(tmp, '.copilot', 'hooks', 'unbound.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: '/opt/unbound/current/unbound-hook/unbound-hook hook copilot PreToolUse' }] },
+    }));
+    process.env.UNBOUND_COPILOT_API_KEY = 'k';
+    try {
+      const t = th.detectTools({ apiKey: 'k', _binaryPath: path.join(tmp, 'no-such-binary') }).find((x) => x.family === 'copilot');
+      assert.equal(t.status, 'tampered');
+    } finally {
+      delete process.env.UNBOUND_COPILOT_API_KEY;
+    }
+  });
+});
+
+test('detectTools: codex binary regression (wrapper at ~/.codex/hooks/unbound.py, hooks.json refs wrapper, config.toml flag, env) → healthy', () => {
+  withHome((tmp, th) => {
+    const wrapper = path.join(tmp, '.codex', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.codex', 'hooks.json'), JSON.stringify({
+      hooks: { PreToolUse: [{ command: wrapper }] },
+    }));
+    writeFile(wrapper, '#!/bin/sh\nexec /opt/unbound/current/unbound-hook/unbound-hook hook codex "$@"\n');
+    writeFile(path.join(tmp, '.codex', 'config.toml'), 'codex_hooks = true\n');
+    process.env.UNBOUND_CODEX_API_KEY = 'k';
+    try {
+      const t = th.detectTools({ apiKey: 'k' }).find((x) => x.family === 'codex');
+      assert.equal(t.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_CODEX_API_KEY;
+    }
+  });
+});
+
+test('detectTools: envCheck rc-file fallback (process.env stale, shell rc holds expected value) → healthy', () => {
+  withHome((tmp, th) => {
+    const script = path.join(tmp, '.cursor', 'hooks', 'unbound.py');
+    writeFile(path.join(tmp, '.cursor', 'hooks.json'), JSON.stringify({ hooks: { PreToolUse: [{ command: script }] } }));
+    writeFile(script, '# unbound');
+    // rcFiles() lists different files per platform (zprofile on darwin,
+    // zshrc/bashrc/profile on linux). Write to .bashrc — both lists include it.
+    writeFile(path.join(tmp, '.bashrc'), 'export UNBOUND_CURSOR_API_KEY="fresh-key"\n');
+    process.env.UNBOUND_CURSOR_API_KEY = 'stale-key';
+    try {
+      const t = th.detectTools({ apiKey: 'fresh-key' }).find((x) => x.key === 'cursor');
+      assert.equal(t.status, 'healthy');
+    } finally {
+      delete process.env.UNBOUND_CURSOR_API_KEY;
+    }
+  });
+});

package/PLAN-web-4887.md

@@ -1,515 +0,0 @@
-# WEB-4887 — AI-Assisted Tool Policy Creation in `unbound` CLI
-
-**Linear:** https://linear.app/unboundsec/issue/WEB-4887
-**Status:** Spec / implementation plan
-**Owner:** Dinesh Veluswamy
-**Last updated:** 2026-06-18
-
----
-
-## 1. Background
-
-The web UI's tool-policy creation flow has an AI-assist input that hits a server-side endpoint tuned with our policy schema and is materially better than Claude hand-authoring policy JSON. Today, when a Claude Code user asks `unbound` to create a tool policy, Claude reaches for the flag-based `unbound policy tool create-terminal` / `create-mcp` commands and constructs the arguments itself. That works but underperforms the in-product AI-assist for the same reason the ticket describes — Claude does not have our system prompt, our command-family inventory, or our MCP catalog in context.
-
-This plan exposes the existing AI-assist endpoints to the CLI and ships a Claude Code skill that steers Claude to use them.
-
-Endpoints already in production (see `ai-gateway-data/webapp/api/v1/command_policy_handlers.py`):
-
-| Policy kind | Endpoint | Model | Backend fallback if LLM fails |
-|---|---|---|---|
-| Terminal command | `POST /api/v1/command-policies/assist/` | Cerebras → Groq via ai-gateway classifier | Deterministic family/field extraction |
-| MCP tool | `POST /api/v1/command-policies/assist-mcp/` | Claude Haiku 4.5 (`temp=0.1`, `max_tokens=900`) | None — returns `success: false` |
-
-Both are admin-only (`@require_admin`), enforce a hard 2000-character input cap (HTTP 200 + `success: false`), and collapse runs of newlines/strip non-printable control chars as prompt-injection defense.
-
----
-
-## 2. Goals
-
-1. Add an AI-assist code path to `unbound policy tool create-terminal` and `create-mcp` so Claude (and humans) can create policies from a natural-language description.
-2. Ship a Claude Code skill bundled with the CLI install so Claude reliably picks the AI-assist path over hand-authored arguments.
-3. Detect and clearly reject prompts that ask for fields the AI-assist endpoint cannot fill (env scoping, exception clauses, user-group conditions, etc.).
-4. Surface backend errors — especially the 2000-char rejection and the LLM-could-not-determine cases — with actionable CLI messages.
-5. Provide an eval harness that measures the acceptance criterion: "Claude Code should always pick our AI-assist endpoint over creating policies on its own."
-
-## 3. Non-goals
-
-- **LLM quality improvements.** The Cerebras terminal classifier and Haiku MCP classifier are out of scope. The user has explicitly flagged this as non-functional for this ticket. We will work around flakiness via UX, not by changing the model.
-- **Cost / Model / Security policy types.** Only tool policies have AI-assist endpoints today. Adding AI-assist to the other three is a separate ticket.
-- **Multi-turn refinement loops** with the user inside the CLI. The endpoints are one-shot; we keep that contract.
-- **Authoring new backend fields.** The CLI must work strictly within the existing form schema and AI-assist response schema.
-
----
-
-## 4. Field whitelist — what AI-assist actually fills
-
-This is the boundary the skill must teach Claude to respect. Fields outside this set must be passed via existing flags, or the prompt must be rejected with a clear message.
-
-### 4.1 Terminal command AI-assist (`assist/`)
-
-**Fills** (from `form_updates` in the response — `command_policy_handlers.py:1340-1393`):
-
-| Field | Type | Notes |
-|---|---|---|
-| `command_family` | string | Must match a known family (e.g. `filesystem`, `git`, `package_manager`). |
-| `selected_field` | string | One of the family's fields, or the literal `ANY` wildcard. |
-| `field_value` | string | Pattern — auto-detected as EXACT / GLOB / REGEX. `*` for "match everything". |
-| `action` | enum | `audit` \| `block` \| `warn` \| `require_slack_approval`. Omitted if user didn't specify. |
-| `name` | string ≤ 200 | Suggested policy name. Optional. |
-| `description` | string ≤ 500 | Suggested description. Optional. |
-
-**Does NOT fill** (form fields the user / Claude must set via flags or accept defaults):
-
-| Form field | Source | CLI handling |
-|---|---|---|
-| `enabled` | `useCreatePolicyForm.ts:21` | Default `true`. Expose `--disabled` flag. |
-| `custom_message` | `useCreatePolicyForm.ts:18` | Only relevant for `BLOCK`/`WARN`. Expose `--custom-message` flag; do not parse from prompt. |
-| `scope_user_group_ids` | `useCreatePolicyForm.ts:39` | Expose `--group` / `--scope-group` flag; do not parse group names from prompt. |
-| `suggestion_id` | UI-only, coverage-gap link | Not relevant to CLI. |
-
-### 4.2 MCP tool AI-assist (`assist-mcp/`)
-
-**Fills** (from `mcp_policy_assist_service.py:36-86`):
-
-| Field | Type | Notes |
-|---|---|---|
-| `mcp_canonical_group_id` | int | Must match an entry in the org's MCP catalog. |
-| `mcp_tools` | string[] | Tool names, post-validated against the group's actual tool list — invented names are dropped. |
-| `name` | string ≤ 80 | Short policy name. |
-| `description` | string | One sentence. |
-| `action` | enum | `AUDIT` \| `BLOCK` \| `WARN` \| `REQUIRE_SLACK_APPROVAL`. Defaults to `AUDIT` if not in prompt. |
-| `custom_message` | string | Only when action is `BLOCK`/`WARN`. |
-
-**Does NOT fill** (same boundary as terminal):
-
-- `enabled` — default true, `--disabled` flag.
-- `scope_user_group_ids` — `--group` flag.
-- `suggested_tools` — UI-only, captured from a separate `/resolve-tools/` call.
-
-### 4.3 Out-of-scope constructs (the "env, archived projects, nuance" cases)
-
-These are things users will naturally try to express. None of them are representable in the current form schema, and the LLM will either silently drop them or hallucinate. The CLI must detect them in the prompt and warn before sending.
-
-| Construct | Example phrasing | Why it can't work | CLI response |
-|---|---|---|---|
-| Environment scope | "in staging", "on prod", "only in dev" | No env field on policies. | Warn + ask user to remove or proceed knowing it's ignored. |
-| Repo / project filter | "for the web repo", "except archived projects" | No project field. | Warn. |
-| User-role conditions | "for non-admins", "when the user is on call" | Closest is `scope_user_group_ids`, settable via `--group` only. | Suggest `--group <name>`. |
-| Time conditions | "after 6pm", "outside business hours" | Not representable. | Reject. |
-| Exception clauses | "block all writes EXCEPT to docs" | Single-policy schema is allow-or-deny on one pattern. | Suggest creating two policies. |
-| Compound asks | "block X and audit Y" | One policy per call. | Suggest splitting into N invocations. |
-
----
-
-## 5. Architecture decision
-
-### 5.1 Add `--prompt` to existing subcommands rather than introduce parallel `-ai` variants
-
-The existing CLI surface is:
-
-```
-unbound policy tool create-terminal --name "..." --command-family ... --field K=V --action ... [flags]
-unbound policy tool create-mcp      --name "..." --mcp-server ... --mcp-action-type ... --action ... [flags]
-```
-
-We add a single `--prompt "<natural language>"` flag to each. When `--prompt` is present:
-
-1. The CLI calls the corresponding AI-assist endpoint.
-2. The response's `form_updates` are merged with any flags the user also passed (flags take precedence — they're explicit overrides).
-3. The CLI shows the resolved policy to the user (or to Claude, who will surface it to the user) and asks for confirmation before calling the real create endpoint.
-
-Rejected alternatives:
-
-- **Parallel `create-terminal-ai` / `create-mcp-ai` subcommands.** Doubles the command surface; gives Claude two near-identical commands to pick between; complicates the skill.
-- **Unified `unbound policy tool assist` that infers terminal vs MCP.** Inference itself is another LLM call. Cleaner UX, but adds a third moving part. Defer to a later ticket.
-
-### 5.2 Two-phase delivery
-
-| Phase | Scope | Why this order |
-|---|---|---|
-| **Phase 1** | `create-terminal --prompt` + skill v1 (terminal only) | Terminal endpoint has a deterministic fallback when the LLM fails. Lower-risk path to validate the surface. |
-| **Phase 2** | `create-mcp --prompt` + skill v2 (covers both) | MCP endpoint has no fallback. Ship after Phase 1 has shaken out the error-handling patterns. |
-
-In Phase 1, the skill explicitly tells Claude: "For MCP policies, use the existing flag-based `create-mcp` — AI-assist for MCP is coming in Phase 2."
-
----
-
-## 6. Phase 1 — Terminal command AI-assist
-
-### 6.1 CLI surface
-
-```bash
-unbound policy tool create-terminal \
-  --prompt "block rm -rf in the filesystem family" \
-  [--group <name>] \
-  [--disabled] \
-  [--custom-message "..."] \
-  [--yes] \
-  [--json]
-```
-
-Behavior:
-
-- `--prompt` is mutually exclusive with the existing field-specifying flags (`--command-family`, `--field`, `--action`, `--name`, `--description`). If both are passed, error out: "Pass `--prompt` for AI-assist or the field flags for explicit creation, not both."
-- `--group`, `--disabled`, `--custom-message` remain valid alongside `--prompt` because they're out-of-AI-scope (see §4.1).
-- `--yes` skips the confirmation prompt (needed for Claude's non-interactive flows).
-- `--json` emits the resolved policy and the create response as JSON, no TTY formatting.
-
-### 6.2 Pre-flight checks (CLI side, before any network call)
-
-In order, fail fast on the first hit:
-
-1. **Auth present.** Refuse if `unbound login` has not been run.
-2. **Admin role.** Hit `whoami` cache or pre-flight `/me`; if not admin, error: "Tool policy creation requires admin role; current role: <role>."
-3. **Prompt length.** If trimmed length > 1800 characters, reject locally with the same wording the backend uses: "Input is too long (max 2000 characters)." Reject at 1800 to leave headroom for backend normalization.
-4. **Out-of-scope keyword scan.** Lower-cased substring match against this list (kept small and explicit, not a regex puzzle):
-   - `staging`, `production`, `prod`, `dev`, `qa`, `testing`
-   - `archived`, `archive`
-   - `business hour`, `after hour`, `outside hour`, `weekend`
-   - `except`, `unless`, `but not`
-   - `private repo`, `public repo`, `private project`, `public project`
-   On match, warn and confirm: "Your prompt mentions `<token>`. Tool policies cannot scope by environment / project / time / exception clauses. Continue anyway? The endpoint will ignore those parts. [y/N]". Under `--yes`, log the warning but proceed.
-5. **Newline normalization.** Collapse runs of ≥2 newlines to one. (Mirror backend defense — gives us identical sanitization regardless of which side rejects.)
-
-### 6.3 Network call
-
-```
-POST {API_BASE}/api/v1/command-policies/assist/
-Authorization: Bearer <token>
-Content-Type: application/json
-
-{
-  "user_input": "<sanitized prompt>",
-  "current_form_state": {
-    "command_family": "",
-    "selected_field": "",
-    "field_value": "",
-    "action": "",
-    "name": "",
-    "description": ""
-  }
-}
-```
-
-Timeout: 20 seconds (backend timeout to the gateway is 15s; we add 5s for routing).
-
-### 6.4 Response handling
-
-| HTTP | Body | CLI behavior |
-|---|---|---|
-| 200 | `success: true`, `form_updates: {...}`, `explanation` | Merge `form_updates` ← user-passed flags, render preview, confirm. |
-| 200 | `success: false`, `error: "Input is too long..."` | Print verbatim error + suggestion: "Try shortening to under 1800 characters." Exit 2. |
-| 200 | `success: false`, `error: "Could not determine command family..."` | Print verbatim error + suggestion: "Try naming the command type explicitly (e.g. `block git pushes`, `audit npm installs`). Or use `unbound policy tool families` to see available families and pass `--command-family` directly." Exit 2. |
-| 200 | `success: false`, `error: <other>` | Print verbatim error. Exit 2. |
-| 401 / 403 | any | "Authentication failed / not authorized. Tool policies require admin. Run `unbound whoami` to check role." Exit 3. |
-| 400 / 422 | any | "Request validation failed: `<body>`." Exit 2. |
-| 5xx | any | "Server error. Try again, or fall back to flag-based creation: `unbound policy tool create-terminal --command-family ... --field ... --action ...`." Exit 4. |
-| timeout / network | — | "Network error reaching `<host>`. Check connectivity. Falling back to flag-based creation is not blocked." Exit 4. |
-
-**No automatic retries.** Re-sending the same prompt to the same flaky LLM endpoint won't change the answer in any meaningful way, and silent retries hide latency. If the user explicitly asks Claude to retry, that's a separate invocation.
-
-### 6.5 Merging AI output with user-passed flags
-
-Order of precedence (highest first):
-
-1. Explicit flags on the command line (`--group`, `--custom-message`, `--disabled`).
-2. AI response `form_updates` fields.
-3. Defaults (`enabled: true`, `action: audit` if AI omitted it).
-
-The merge happens before the confirmation step so the user sees the final shape.
-
-### 6.6 Confirmation step
-
-Default behavior — show the resolved policy, ask `Create policy? [Y/n]`. The
-preview reuses the CLI's standard `output.keyValue` rendering (dimmed keys,
-auto-padded columns) for visual consistency with `displayToolPolicy` and the
-other policy-display surfaces.
-
-Concept-order of rows (rows MAY be skipped when their value is empty — e.g.
-Description and Custom message are dropped rather than printed as `(none)`):
-
-- Name, Description, Type, Command family, Field, Pattern, Action,
-  Custom message, Scope (groups), Enabled.
-
-Action is colored — `BLOCK` red, `WARN`/`REQUIRE_SLACK_APPROVAL` yellow,
-`AUDIT` dimmed (low-emphasis default). The AI explanation prints below the
-table in dim text and is omitted entirely when the backend returns an empty
-explanation.
-
-Exact column widths and labels are not pinned — tests assert on meaningful
-tokens (Name value, Action enum, explanation body), not on column-aligned
-strings.
-
-Under `--yes`, skip the prompt but always print the resolved policy (Claude will surface it to the user in chat).
-
-### 6.7 Create call
-
-On confirmation, call the existing create endpoint exactly as the flag-based path does today (`POST /api/v1/command-policies/`) with the merged payload. No new backend code on the create side.
-
-### 6.8 Backend change (optional, recommended)
-
-Add a `source` field to both AI-assist endpoints (`"web"` | `"cli"`, defaulting to `"web"` for backward compat). Lets us measure CLI adoption and the AC pick-rate without parsing user-agent headers. One-line wire change, two-line server change, no behavioral impact.
-
-### 6.9 Tests
-
-- **Unit (CLI):**
-  - Prompt length pre-flight at 1799 / 1800 / 1801 chars.
-  - Out-of-scope keyword detection for each token in §6.2.
-  - Flag/prompt mutual exclusion error path.
-  - Merge precedence: flag wins over AI value.
-  - Each HTTP status path in §6.4 routes to the right CLI message.
-- **Integration (against staging):**
-  - 10 representative single-intent prompts → expect `success: true` and a valid policy.
-  - 3 oversize prompts → expect length error, no policy created.
-  - 3 nonsense prompts → expect "could not determine" error.
-- **Eval harness (see §8):**
-  - Pick-rate test: spawn Claude Code with the skill installed, give it 10 natural-language asks ("create a policy that…"), measure whether it invokes `create-terminal --prompt` vs hand-rolls `--command-family ...`.
-
----
-
-## 7. Phase 2 — MCP tool AI-assist — **DELIVERED**
-
-Phase 2 ships on the same branch (`web-4887-cli-ai-assist-policy`, PR #54) as
-Phase 1. New exports in `src/lib/policy-ai-assist.js`: `runMcpPromptCreate`,
-`mergeAiAndFlagsMcp`, `renderMcpPreview`. The `create-mcp` subcommand now
-accepts `--prompt <text>` as a first-class alternative to the flag-based path.
-
-### 7.1 CLI surface
-
-```bash
-unbound policy tool create-mcp \
-  --prompt "audit all Linear writes" \
-  [--group <name>] \
-  [--disabled] \
-  [--custom-message "..."] \
-  [--yes] \
-  [--json]
-```
-
-Same flag rules as Phase 1.
-
-### 7.2 Pre-flight additions on top of §6.2
-
-- **Catalog awareness.** If the prompt names a service that isn't in the org's MCP catalog (fetched via the existing `unbound policy tool mcp-servers` call, cached for the session), warn before sending: "Your prompt mentions `<service>`, which isn't in this org's MCP catalog. The endpoint will likely return an error. Available services: `<list>`. Continue? [y/N]". Optional optimization; skip in v1 if scope creeps.
-
-### 7.3 Network call
-
-`POST {API_BASE}/api/v1/command-policies/assist-mcp/` — identical envelope shape to Phase 1, with the MCP-specific `current_form_state` keys.
-
-### 7.4 Response handling — same matrix as §6.4, with one addition
-
-| HTTP | Body | CLI behavior |
-|---|---|---|
-| 200 | `success: true`, `mcp_tools: []` (empty array after backend post-validation drops hallucinated names) | Treat as a soft failure: "AI assist could not match any tools in `<group>` for your description. Try naming the tools more directly, or use `unbound policy tool create-mcp --mcp-server ... --mcp-tools tool1,tool2`." Do NOT auto-create a policy with no tools. Exit 2. |
-
-The MCP endpoint has no backend deterministic fallback, so flakiness surfaces as either `success: false` or `mcp_tools: []`. The CLI handles both as "couldn't figure it out; here's the manual escape hatch."
-
-Note: the `assist-mcp/` response has no `explanation` field (asymmetric with the
-terminal `assist/` endpoint). `renderMcpPreview` is passed `undefined` for the
-explanation and skips the trailing dim line entirely. The render code is
-forward-compatible: if the backend later adds `explanation`, the existing
-`if (explanation)` guard picks it up with zero CLI change.
-
-### 7.5 Tests — extend §6.9 with MCP-specific cases
-
-- Empty `mcp_tools` response routes to the "couldn't match any tools" message.
-- Out-of-catalog service mention warns before sending.
-- Integration: 10 single-service prompts + 3 multi-service prompts (latter should warn or split).
-
----
-
-## 8. Claude Code skill — distribution and content
-
-> ~~DEPRECATED — replaced by CLI-side guards in §14~~. The external Claude Code skill described below was never shipped; setup-repo PR #163 was closed unmerged. CLI-side deterministic enforcement (layers 1+2+3) supersedes this approach. See §14 for the shipped design.
-
-The CLI cannot edit Claude's system prompt, but it can drop a skill file. Skills are the closest analog to a CLAUDE.md hook that we can install programmatically.
-
-### 8.1 Where it lives
-
-`~/.claude/skills/unbound-tool-policy/SKILL.md` at runtime.
-
-Source-of-truth lives in the **`setup` repo** at `claude-code/skills/unbound-tool-policy/SKILL.md`, NOT in unbound-cli. The `claude-code/hooks/setup.py` and `claude-code/gateway/setup.py` scripts (which `unbound setup claude-code` and `unbound onboard` download and run) copy it from the setup repo's main branch on every install. This co-locates the skill with the rest of the claude-code per-tool install artifacts (`unbound.py`, `anthropic_key.sh`, etc.) and lets skill content updates ship the moment they merge to setup-repo main — no unbound-cli release required.
-
-Installed by `unbound setup claude-code` (both subscription and gateway modes) and by `unbound onboard`. Idempotent: overwritten on each install so content updates propagate.
-
-### 8.2 Phase 1 skill content (terminal only)
-
-The SKILL.md frontmatter is what Claude reads to decide whether to invoke. Keep the description imperative and specific:
-
-```markdown
----
-name: unbound-tool-policy
-description: |
-  Use when the user asks to create a terminal command tool policy in Unbound
-  (e.g. "block rm -rf", "audit git pushes to main"). ALWAYS prefer
-  `unbound policy tool create-terminal --prompt "<NL>"` over hand-authoring
-  the --command-family / --field / --action flags. The CLI calls a
-  server-side AI-assist endpoint tuned on Unbound's policy schema; it
-  outperforms hand-authoring.
-
-  For MCP tool policies (Linear, GitHub, etc.), AI-assist is not available
-  yet — fall back to flag-based `unbound policy tool create-mcp` for those.
----
-
-# Creating an Unbound terminal command policy
-
-When the user asks for a tool policy targeting terminal commands, invoke:
-
-    unbound policy tool create-terminal --prompt "<natural language>" [--group <name>] [--yes]
-
-## Rules for the --prompt string
-
-1. **One policy per invocation.** If the user wants two things, run the
-   command twice.
-2. **Single-intent, imperative.** Phrase it as "block git pushes to main",
-   "audit npm installs", "warn on rm -rf". Avoid multi-paragraph briefs.
-3. **Stay under 1500 characters.** The endpoint caps at 2000; the CLI
-   pre-trims at 1800. Long prompts get rejected.
-4. **Do NOT include** these — the endpoint cannot represent them and the
-   CLI will warn about them:
-   - environment scope (staging, prod, dev)
-   - project / repo filters
-   - time-based conditions
-   - exception clauses ("except for X")
-   - user-role conditions
-5. **Group scoping** goes on the `--group` flag, not in the prompt.
-6. **Custom block messages** go on `--custom-message`, not in the prompt.
-
-## When AI-assist fails
-
-If the CLI returns "Could not determine command family", try one of:
-
-- Re-phrase the user's intent to name the command type explicitly.
-- Fall back to flag-based: `unbound policy tool families` to list families,
-  then `unbound policy tool create-terminal --command-family ... --field ...`.
-
-## What success looks like
-
-The CLI prints a resolved policy preview and asks for confirmation.
-Pass `--yes` to skip the confirm; the preview still prints so the user
-can sanity-check.
-
-## MCP policies (not this skill, for now)
-
-For MCP tool policies, use the flag-based form:
-
-    unbound policy tool create-mcp --name "..." --mcp-server <server> \
-      --mcp-action-type <read|write|destructive> --action AUDIT|BLOCK|WARN
-```
-
-### 8.3 Phase 2 skill content updates
-
-When Phase 2 ships, replace the "MCP policies (not this skill, for now)" section with the MCP variant of the same rules, and update the frontmatter description to drop the "MCP not available yet" caveat.
-
-### 8.4 Belt-and-suspenders: README and `--help`
-
-- Update `unbound policy tool create-terminal --help` so the imperative language is also in the help output. Claude reads `--help` when uncertain.
-- Update `README.md` "Tool policy examples" section so the first example uses `--prompt`. Manual flag examples remain below as a fallback.
-
----
-
-## 9. Acceptance criterion — testable definition
-
-The Linear ticket says "Claude code should always pick our AI assist endpoint over creating policies on its own." Rewritten as testable:
-
-1. **Pick-rate ≥ 90%** on the eval set below.
-2. **Success-rate ≥ 80%** of in-scope eval prompts that reach the endpoint return `success: true`.
-3. **Zero hand-authored YAML / JSON files** in the eval transcript. Claude should never write a policy file to disk and then upload — the CLI is the only path.
-
-### 9.1 Eval set
-
-`tests/eval/policy-prompts.json` in this repo. ~20 prompts across:
-
-- 6 single-intent in-scope ("block rm -rf", "audit git pushes to main", …)
-- 4 detailed in-scope (300–800 chars, single intent, more context)
-- 4 out-of-scope (env, exception, time, compound) — expected outcome: skill steers Claude to warn the user or split
-- 3 oversize (> 2000 chars) — expected outcome: pre-flight rejects
-- 3 nonsense — expected outcome: `success: false`, surfaced
-
-Eval harness: a script that spawns Claude Code in a clean workspace with the skill installed, feeds each prompt as a user message, and records: which command Claude invoked, whether `--prompt` was used, the endpoint response, the final state. Aggregate into a pick-rate / success-rate report.
-
-This eval is the artifact that closes the ticket. Without it, "always picks" is unverifiable.
-
----
-
-## 10. Implementation order
-
-### Phase 1 (1–2 dev-days)
-
-1. `src/commands/policy.js` — add `--prompt` flag and AI path to `create-terminal`. Branch on `--prompt` presence; preserve all existing flag paths.
-2. New module `src/lib/policy-ai-assist.js` — HTTP client, pre-flight checks, response routing, preview rendering.
-3. Skill file at `skills/unbound-tool-policy/SKILL.md` in the repo; build step copies to `~/.claude/skills/` during `setup claude-code` and `onboard`.
-4. Update `--help` text and `README.md` policy examples.
-5. Unit tests (§6.9).
-6. Eval harness skeleton + the in-scope prompts (§9.1).
-7. Integration sanity check against staging.
-
-### Phase 2 (1 dev-day, after Phase 1 lands)
-
-1. Extend `create-mcp` with `--prompt`.
-2. Reuse `src/lib/policy-ai-assist.js`; add MCP-specific pre-flight and response routing.
-3. Update skill file and `--help`.
-4. Extend eval harness with MCP prompts.
-
-### Backend (optional, parallel to Phase 1)
-
-Add the `source: "cli" | "web"` field to both AI-assist request handlers and log it. PR in `ai-gateway-data`.
-
----
-
-## 11. Open questions / risks
-
-1. **Catalog awareness in MCP pre-flight.** The `mcp-servers` list is org-specific and changes. Caching policy: per-session in memory, or persist to `~/.unbound/cache/`? Defer to Phase 2 review.
-2. **Admin-key blast radius.** AI-assist is admin-only. End-user Claude Code sessions running under a non-admin key will get 403s. The skill should detect that on first use and tell Claude to advise the user to ask their admin, instead of looping on retries.
-3. **Eval cost.** Running the eval against real Claude Code instances burns tokens. Cap the eval to one run per CI build, gated on changes to `src/commands/policy.js` or the skill file.
-
-## 12. Deferred to follow-up tickets
-
-These are intentionally out of scope for WEB-4887 to keep the surface narrow. Spin off tickets when these become live:
-
-1. **MCP catalog cache for pre-flight.** Phase 2 pre-flight could check the prompted service against the org's MCP catalog before sending. Cache location (`~/.unbound/cache/`?) and invalidation policy need design. Defer until we see whether the bare endpoint surfaces "no matching service" errors well enough on its own.
-2. **`source: "cli" | "web"` request field on both AI-assist endpoints.** Lets us distinguish CLI usage from web usage in production logs, which is the only way to measure the AC pick-rate at scale without parsing user-agents. Punt to a post-Phase-2 ticket so backend work doesn't gate the CLI rollout.
-3. **AI-assist for Cost / Model / Security policy types.** Today only tool policies have AI-assist endpoints. If pick-rate data shows users want NL creation for the other three, design endpoints and extend the skill.
-~~4. **Per-user skill install for MDM deployments.**~~ — DELIVERED in setup PR #163. Both MDM setup scripts now enumerate device users via `get_all_user_homes()` and install the skill into each user's `~/.claude/skills/` under `_run_as_user(username, _do)` (the existing security-critical privilege-drop primitive). Best-effort per user; one locked-down home does not abort the device rollout. See `claude-code/{hooks,gateway}/mdm/setup.py:setup_tool_policy_skill_for_user` and the README updates in each `mdm/` directory.
-
-## 13. Skill reinstall policy
-
-Each `unbound setup claude-code` and `unbound onboard` run **overwrites** `~/.claude/skills/unbound-tool-policy/SKILL.md` with the version fetched from the `setup` repo's main branch at install time. No checksum gating, no diff-and-prompt. Rationale: the skill is a derived artifact of whatever's in the setup repo's main; treating it as an install-time output (not user state) keeps the mental model simple and ensures Claude is always steered with the current rules.
-
-(The skill source-of-truth was originally bundled in unbound-cli during initial implementation; relocated to the setup repo to follow the existing per-tool-artifact convention. See companion PR https://github.com/websentry-ai/setup/pull/163.)
-
----
-
-## 14. Steering enforcement (post-skill-kill)
-
-§8 (external Claude Code skill) is deprecated. Setup-repo PR #163 was closed unmerged, and the install-side artifact path was abandoned in favor of CLI-side deterministic enforcement that ships in the same binary as the commands it protects. Three layers, evaluated in order, implemented in `src/lib/no-ai-guard.js` and wired into the `.action()` handlers of `create-terminal` (line 1430) and `create-mcp` (line 1602) immediately after `requireLogin()`.
-
-### 14.1 Layer 1 — hard guard at the action boundary
-
-`unbound policy tool create-terminal` and `create-mcp` reject invocations that pass neither `--prompt` nor an explicit `--no-ai` opt-out. The error message names the AI-assist form, instructs the caller to retry with `--prompt "<text>"`, and surfaces `--no-ai` as the documented opt-out for raw classification flags. Exit code is `2` (invalid usage), routed through `err.exitCode = 2` and propagated by the `process.exitCode = err.exitCode || 1` catch block.
-
-`--prompt` and `--no-ai` are also declared mutex: passing both exits 2 with a "not both" message. This avoids ambiguity about which path the caller intended.
-
-Why an action-time guard and not a commander.js parse-time validator: commander has no first-class mutex API for "exactly one of A, B" that also accommodates a default-to-A steering nudge, and threading the AI-assist routing through commander's option parsing would complicate the existing `--prompt` branch in `policy.js`. Throwing from `.action()` keeps the guard local to the two subcommands it protects.
-
-### 14.2 Layer 2 — Claude Code detection + env-gated escape hatch
-
-When `process.env.CLAUDECODE === '1'`, `--no-ai` is additionally rejected unless `process.env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE === '1'` is also set. The rejection message explicitly says "intended for interactive humans, not for agents." This is steering, not security: the env var is in plain sight in the error message, and an adversarial agent that reads the message could set it itself. Accepted residual risk per the original principal-architect review. Server-side detection (deferred ticket) if pick-rate telemetry later shows leakage.
-
-`CLAUDECODE=1` is set by current Claude Code variants. If future variants do not set it, layer 1 still steers to `--prompt`, and the layer-2 nudge silently no-ops — an acceptable degradation. Future Claude Code variants can match `CLAUDECODE` to remain steered by this layer.
-
-### 14.3 Layer 3 — banner-first `--help`
-
-`unbound policy tool create-terminal --help` (and `create-mcp --help`) opens with a short banner that names the AI-assisted form before commander's auto-generated `Usage:` line. This is the first text a reader (human or agent) sees on `--help`, so it leads the eye to `--prompt`. Implementation: `.addHelpText('before', helpBannerFor(subcommandName))`. The existing `addHelpText('after', ...)` examples are updated so every manual-flag example prepends `--no-ai`, making the documented opt-out form unambiguous.
-
-### 14.4 Why the external skill was killed
-
-The original §8 plan installed `~/.claude/skills/unbound-tool-policy/SKILL.md` via `unbound setup claude-code` and `unbound onboard`, with per-user MDM rollout in setup-repo PR #163. Three problems killed it:
-
-1. **Install-time artifact, runtime enforcement.** A skill file in `~/.claude/` is a soft nudge — Claude reads it, but nothing in the CLI enforces what the skill recommends. CLI-side guards close the loop: the binary that creates the policy is also the binary that decides which path to route through.
-2. **Distribution sprawl.** Skill content lived in the setup repo to follow the per-tool-artifact convention. Updating steering rules meant a setup-repo PR, an MDM rollout, and a CLI release on different cadences. Folding the rules into the CLI collapses that to one release surface.
-3. **MDM rollout complexity.** Per-user install across `get_all_user_homes()` under `_run_as_user(username, ...)` was correct but added scope to a security-critical primitive for a feature that the CLI can enforce on its own.
-
-### 14.5 Versioning
-
-Minor bump: `1.4.0` → `1.5.0`. The breaking surface is two subcommands and the migration is a one-flag (`--no-ai`) prepend. Major bump would over-signal. README ships a `BREAKING CHANGE in 1.5.0` callout at the top of the Tool policy section; PR description names both subcommands and shows the migration.

package/PLAN.md

@@ -1,106 +0,0 @@
-# Implementation Plan: WEB-4887 CLI `--no-ai` steering guard (layers 1+2+3)
-
-> Generated by /implementation-plan on 2026-06-19. Source: principal-architect.
->
-> Successor to PR #54 (`web-4887-cli-ai-assist-policy`) which shipped `--prompt`-based AI-assist for `create-terminal` / `create-mcp`. This plan replaces the killed external Claude Code skill (`unbound-tool-policy`, setup repo PR #163 closed unmerged) with CLI-side deterministic enforcement.
-
-## Goal
-`unbound policy tool create-terminal` and `unbound policy tool create-mcp` deterministically route Claude Code agents through the AI-assist `--prompt` path: invocations without `--prompt` and without an explicit `--no-ai` opt-out exit with code 2 and a copy-paste-ready remediation message; under `CLAUDECODE=1` even `--no-ai` is rejected unless an env-gated escape hatch is set; `--help` leads with the AI-assisted form.
-
-## Established Context (do not override)
-- Repo `/Users/dinesh/Code/unbound-cli` — Node.js CLI on commander.js `^12.1.0`, tests via `node --test`.
-- Active branch `web-4887-cli-noai-guard`, stacked on `web-4887-cli-ai-assist-policy` (PR #54). The eventual PR base = `web-4887-cli-ai-assist-policy`; GitHub auto-retargets to `main` after #54 merges.
-- `src/commands/policy.js` — `create-terminal` at line 1430, `create-mcp` at line 1602. Both have an existing `opts.prompt`-presence branch (lines 1473 / 1646) with an empty-`--prompt` guard that exits 2 (lines 1475 / 1648). Flag-path required-field errors at lines 1539–1547 (terminal) / 1708–1715 (MCP), thrown into the handler `catch` which sets `process.exitCode = 1` (lines 1595–1598 / 1767–1770).
-- `src/lib/policy-ai-assist.js` owns the AI-assist `--prompt` path and **MUST NOT be modified** by this work — the new layers route BEFORE that module is reached.
-- Test convention: integration tests at the `commander.parseAsync` layer. Fresh `new Command()` per test, `src/api.js` `.get`/`.post` and `src/config.js` `isLoggedIn`/`getApiKey`/`getBaseUrl` stubbed, `require.cache` invalidated to reset module-level caches. Pattern established in `test/policy-ai-assist.test.js` (`loadFreshModules`, `buildHarness`, `runCreate`).
-- Exit-code convention: `output.error(msg)` + `process.exitCode = N` (no `process.exit`). Exit 2 is already used for invalid-flag failures (line 1476). Exit 1 is reserved for runtime/operational failures.
-- This is a **breaking change** for any caller of `create-terminal` / `create-mcp` with raw flags (no `--prompt`). Clean break recommended over deprecation window; breaking surface is exactly two subcommands.
-- Version bump: `package.json` `1.4.0` → `1.5.0` (minor; team versions liberally; breaking surface is narrow).
-- Do NOT bundle a Claude Code skill or anything that writes to `~/.claude/` — the whole point of this work is to eliminate that external artifact.
-- The original spec doc `PLAN-web-4887.md` is the source of truth for §1–§13 (Phase 1 and Phase 2 AI-assist scope) and must not be overwritten — only extended with a new §14 and a deprecation marker on §8.
-
-## Out of Scope
-- Modifying `src/lib/policy-ai-assist.js`. Routing decisions in this work happen BEFORE the AI-assist module is reached.
-- Any Claude Code skill, hook, or `~/.claude/` artifact. The point of this work is to remove that external steering layer.
-- Changes to `create-terminal`/`create-mcp` AI-assist behavior, prompt handling, preview rendering, merge precedence, BLOCK/WARN custom-message guard, or response routing.
-- Changes to `update`, `delete`, `get`, `list` tool-policy subcommands. The guard does NOT extend to those (no AI-assist exists for them).
-- Changes to non-tool policy subcommands (cost, model, security).
-- Eval harness updates (`test/eval/`).
-- Telemetry on guard fires (deferred until adoption data demands it).
-- Deprecation-window plumbing (one-release-with-warning option (b)). Clean break (option (a)) is committed.
-- Server-side detection of agents bypassing the guard (deferred — separate ticket if pick-rate telemetry shows leakage).
-- Major-version bump to `2.0.0` (architect endorses minor `1.5.0` per team versioning practice).
-
-## Files to Change
-| Path | Change | Acceptance criterion |
-|------|--------|----------------------|
-| `src/commands/policy.js` | (a) On both `create-terminal` (line 1430) and `create-mcp` (line 1602), add `.option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')`. (b) Insert `.addHelpText('before', helpBannerFor('create-terminal'))` (resp. `'create-mcp'`) above the existing `.action(...)`. (c) Update the existing `.addHelpText('after', ...)` examples (lines 1444–1468 and 1617–1641) so every manual-flag example prepends `--no-ai`; AI-assisted (`--prompt`) examples unchanged. (d) At the top of each `.action()` handler — inside the existing `try`, immediately after `requireLogin()` (lines 1471 / 1644) — call `assertSteering(opts, { subcommandName: 'create-terminal' })` (resp. `'create-mcp'`). (e) Change the outer handler `catch` (lines 1596–1598 and 1768–1770) from `process.exitCode = 1` to `process.exitCode = err.exitCode || 1` so the guard's `err.exitCode = 2` propagates (mirrors the already-existing pattern on the AI-assist branch at line 1512). | #1, #2, #3, #4, #5, #6 |
-| `package.json` | Bump `"version"` from `"1.4.0"` to `"1.5.0"`. | #7 |
-| `README.md` | In the "Tool policy" examples section, update every manual-flag example for `create-terminal` and `create-mcp` to prepend `--no-ai`. AI-assisted (`--prompt`) examples unchanged. Add a one-paragraph note under the section header documenting (i) the guard, (ii) the `--no-ai` opt-out, (iii) the `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1` env-var escape hatch for Claude Code interactive humans. Add a top-of-section `BREAKING CHANGE in 1.5.0:` callout. | #9 |
-| `PLAN-web-4887.md` | Append §14 "Steering enforcement (post-skill-kill)" documenting (i) layer 1 hard guard, (ii) layer 2 `CLAUDECODE=1` detection + `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1` escape hatch, (iii) layer 3 banner-first `--help`, (iv) why the external skill (PR #163) was killed. Mark §8 "Claude Code skill — distribution and content" as `~~DEPRECATED — replaced by CLI-side guards in §14~~` with a forward pointer to §14. Do NOT alter §1–§7 or §9–§13. | #10 |
-
-## Files to Create
-| Path | Purpose | Acceptance criterion |
-|------|---------|----------------------|
-| `src/lib/no-ai-guard.js` | New module, ~80 LOC, no external dependencies. Exports two pure functions: `assertSteering(opts, { subcommandName, env = process.env })` (runs layers 1 + 2; throws an `Error` with `err.exitCode = 2` and the appropriate stderr message — see AD-8 wording in the source plan) and `helpBannerFor(subcommandName)` (returns the multi-line banner string for `.addHelpText('before', ...)`). The `env` parameter is dependency-injected (defaults to `process.env`) so tests can exercise the production codepath without touching global env. | #1, #3, #4 |
-| `test/no-ai-guard.test.js` | New integration test file at `commander.parseAsync` layer. Uses `node:test` + `node:assert/strict`. Reuses the harness pattern from `test/policy-ai-assist.test.js` (`loadFreshModules`, fresh `new Command()`, stubbed `api.get`/`api.post`, captured `output.error`/`output.success`/`output.warn`, `program.exitOverride()`). Adds a local `withEnv(overrides, fn)` helper that saves+restores `process.env.CLAUDECODE` and `process.env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE` per test. Defines 11 `test(...)` cases (T1–T11) covering every acceptance criterion below; `beforeEach`/`after` hooks reset `process.exitCode = 0` (same convention as `test/policy-ai-assist.test.js` lines 97–106). | #1, #2, #3, #4, #5, #6, #8 |
-
-## Test Surface
-- **Layer:** CLI command — `commander.parseAsync(['node','unbound','policy','tool','create-terminal'|'create-mcp', ...argv])` against a fresh `new Command()` with `src/commands/policy.js`'s `register` invoked per test. `src/api.js` `.get`/`.post` and `src/config.js` `isLoggedIn`/`getApiKey`/`getBaseUrl` are stubbed. `process.env.CLAUDECODE` and `process.env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE` are set per-test via a save+restore helper. NO unit tests on `assertSteering` or `helpBannerFor` directly — coverage is end-to-end through `parseAsync`.
-- **Tests to add or extend:**
-  - `test/no-ai-guard.test.js` — covers acceptance criteria #1, #2, #3, #4, #5, #6, #8. Test cases:
-    1. **T1** — `create-terminal` with no `--prompt` and no `--no-ai`, no `CLAUDECODE` → `process.exitCode === 2` AND captured `output.error` contains `"AI-assisted"`, `"Retry with"`, AND `"--prompt"`. No `api.post` calls observed. (#1)
-    2. **T2** — `create-mcp` with no `--prompt` and no `--no-ai`, no `CLAUDECODE` → same shape as T1, scoped to `create-mcp`. (#1)
-    3. **T3** — `create-terminal --no-ai --name X --command-family git --field command='git push*' --action AUDIT` with no `CLAUDECODE` → `api.post('/api/v1/command-policies/', ...)` fires (observed in stub). `process.exitCode === 0`. (#2)
-    4. **T4** — `create-mcp --no-ai --name X --mcp-server linear --mcp-action-type read --action AUDIT` with no `CLAUDECODE` → `api.post('/api/v1/command-policies/', ...)` fires. `process.exitCode === 0`. (#2)
-    5. **T5** — `create-terminal --prompt "block rm -rf" --no-ai` → `process.exitCode === 2` AND captured `output.error` contains `"not both"`. No `api.post` calls. (#3)
-    6. **T6** — `create-terminal --no-ai` under `CLAUDECODE=1`, `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE` unset → `process.exitCode === 2` AND captured `output.error` contains `"CLAUDECODE=1"` AND `"intended for interactive humans"`. No `api.post` calls. (#4)
-    7. **T7** — `create-terminal --no-ai` under `CLAUDECODE=1` AND `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1` → layer 2 bypassed, falls into existing flag-path, which then exits 1 with `"--name is required"` error (asserting the env-escape hatch worked end-to-end). (#4)
-    8. **T8** — `create-terminal --prompt "block rm -rf"` under `CLAUDECODE=1` → assist endpoint stub observes `api.post('/api/v1/command-policies/assist/', ...)`. Layer 2 does not interfere. (#5)
-    9. **T9** — `create-terminal --help` (collected via `program.outputHelp()` redirected stdout or `--help` triggering commander's help output capture) → stdout contains the AI-assisted banner block AND `idx(banner) < idx("Usage:")` (banner appears before commander's auto-generated Usage line). (#6)
-    10. **T10** — same as T9 for `create-mcp --help`. (#6)
-    11. **T11** (regression smoke) — `create-terminal --prompt "audit npm installs"` with no `CLAUDECODE`, no `--no-ai` → assist endpoint stub observes the assist POST. Confirms the existing Phase-1 happy-path is unaffected by the new guard. (#8)
-
-## Acceptance Criteria
-1. Given `unbound policy tool create-terminal` (resp. `create-mcp`) invoked with neither `--prompt` nor `--no-ai`, when the command runs, then `process.exitCode === 2`, `output.error` is called with a message containing the substrings `"AI-assisted"`, `"Retry with"`, and `"--prompt"`, and no network call to `api.post` is made.
-2. Given `unbound policy tool create-terminal --no-ai --name X --command-family git --field command='git push*' --action AUDIT` (resp. `create-mcp --no-ai --name X --mcp-server linear --mcp-action-type read --action AUDIT`) with `process.env.CLAUDECODE` unset, when the command runs, then `api.post` is called with path `/api/v1/command-policies/` and `process.exitCode === 0`.
-3. Given `unbound policy tool create-terminal --prompt "X" --no-ai`, when the command runs, then `process.exitCode === 2`, `output.error` is called with a message containing the substring `"not both"`, and no network call is made.
-4. Given `unbound policy tool create-terminal --no-ai` under `process.env.CLAUDECODE === '1'` and `process.env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE` unset, when the command runs, then `process.exitCode === 2` AND `output.error` is called with a message containing `"CLAUDECODE=1"` AND `"intended for interactive humans"`. Given the same invocation but with `process.env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE === '1'`, layer 2 is bypassed and the existing flag-path errors out on `"--name is required"` (with `process.exitCode === 1`).
-5. Given `unbound policy tool create-terminal --prompt "block rm -rf"` under `process.env.CLAUDECODE === '1'`, when the command runs, then `api.post('/api/v1/command-policies/assist/', ...)` is invoked (assist endpoint is reached; layer 2 does not interfere).
-6. Given `unbound policy tool create-terminal --help` (resp. `create-mcp --help`), when the command runs, then the help output (captured stdout) contains the AI-assisted banner block (substring `"AI-ASSISTED (preferred):"`) AND the index of that banner is strictly less than the index of `"Usage:"`.
-7. `package.json` `version` is `"1.5.0"`.
-8. `npm test` exits 0 with all existing tests in `test/*.test.js` (including `test/policy-ai-assist.test.js` and `test/policy-ai-assist-mcp.test.js`) passing unmodified.
-9. `README.md` Tool policy section contains: (i) every manual-flag example using `--no-ai`, (ii) a paragraph documenting the guard + `--no-ai` + `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE` env var, (iii) a `BREAKING CHANGE in 1.5.0:` callout at the top of the section.
-10. `PLAN-web-4887.md` has a new §14 "Steering enforcement (post-skill-kill)" documenting the three layers and the env var, AND §8 begins with `~~DEPRECATED — replaced by CLI-side guards in §14~~` and a forward pointer to §14.
-
-## Risks & Mitigations
-- **Risk R1: BREAKING CHANGE breaks existing scripts.** Any CI / shell script today running `unbound policy tool create-terminal --name X --command-family git --field K=V --action AUDIT` starts exiting 2 immediately on upgrade.
-  - **Mitigation:** PR description includes a `BREAKING CHANGE:` callout naming both subcommands and showing the one-flag (`--no-ai`) migration. README breaking-change banner. Team automation audited in PR review. Breaking surface is narrow (two subcommands).
-- **Risk R2: Claude reads layer-2 stderr and sets `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1` itself.** The env var is in plain sight in the error message; an adversarial reading would lead the agent to set the var and bypass.
-  - **Mitigation:** Message wording explicitly says `"This is intended for interactive humans, not for agents."` Accepted residual risk — this is steering, not security. Server-side detection (deferred ticket) if pick-rate telemetry later shows leakage.
-- **Risk R3: `addHelpText('before', ...)` placement varies across commander.js versions.** Could cause the banner to render in the wrong slot.
-  - **Mitigation:** Project pins `commander ^12.1.0`. T9/T10 assert `idx(banner) < idx("Usage:")` and fail loudly on drift. Smoke-verify locally before commit.
-- **Risk R4: `process.env.CLAUDECODE` may not be `'1'` in every Claude Code variant.** Worst case: layer 2 silently no-ops.
-  - **Mitigation:** Layer 1 still steers in the absence of layer 2. Acceptable degradation; document the env var the CLI checks for in `PLAN-web-4887.md` §14 so future Claude Code variants can match.
-- **Risk R5: Test brittleness around `process.exitCode`.** The runner conflates a leftover non-zero `process.exitCode` with a test-file failure.
-  - **Mitigation:** Reuse `beforeEach(() => { process.exitCode = 0; })` and `after(() => { process.exitCode = 0; })` pattern verbatim from `test/policy-ai-assist.test.js` lines 97–106. Do not invent a new convention.
-- **Risk R6: `catch`-block change (`process.exitCode = err.exitCode || 1`) subtly alters exit codes for existing thrown `Error`s that lack `.exitCode`.**
-  - **Mitigation:** Today's behavior for such errors is `process.exitCode = 1`; the `|| 1` fallback preserves that exactly. Change is purely additive for errors that DO carry `.exitCode`. Existing `test/policy-ai-assist.test.js` and `test/policy-ai-assist-mcp.test.js` confirm regression-free behavior.
-- **Risk R7: Test harness module-cache bleed between `test/no-ai-guard.test.js` and the existing assist tests.** Module-level caches (e.g. `_privilegesCache` in `src/lib/policy-ai-assist.js`) could leak state.
-  - **Mitigation:** Copy the `loadFreshModules` pattern from `test/policy-ai-assist.test.js` lines 9–25 verbatim — it already invalidates `require.cache` for the relevant modules.
-
-## Sequencing
-1. Create `src/lib/no-ai-guard.js` with `assertSteering` and `helpBannerFor`. No call sites yet. Verify the module loads cleanly: `node -e "require('./src/lib/no-ai-guard')"`.
-2. In `src/commands/policy.js`, add `.option('--no-ai', ...)` to both `create-terminal` (line 1430 block) and `create-mcp` (line 1602 block).
-3. In `src/commands/policy.js`, wire `assertSteering(opts, { subcommandName: ... })` into both `.action()` handlers immediately after `requireLogin()` (lines 1471 / 1644).
-4. In `src/commands/policy.js`, change the outer handler `catch` blocks (lines 1596–1598 and 1768–1770) to use `process.exitCode = err.exitCode || 1`.
-5. In `src/commands/policy.js`, add `.addHelpText('before', helpBannerFor('create-terminal'))` / `'create-mcp'` and update the manual examples in the existing `.addHelpText('after', ...)` blocks (lines 1444–1468 and 1617–1641) to prepend `--no-ai`.
-6. Bump `package.json` `version` to `1.5.0`.
-7. Write `test/no-ai-guard.test.js` (T1–T11). Run `npm test`. Iterate stderr wording in `src/lib/no-ai-guard.js` until tests pass and copy remains human-readable.
-8. Update `README.md` Tool policy section per the table above.
-9. Update `PLAN-web-4887.md` — append §14, mark §8 deprecated.
-10. Run `npm test` once more for full regression confirmation.
-11. Self-review the diff. Commit. Open PR with base `web-4887-cli-ai-assist-policy`; PR description includes the `BREAKING CHANGE:` callout and the `--no-ai` migration example.
-
-## Open Questions
-- None.