unbound-cli 1.4.0 → 1.6.2

package/README.md

@@ -195,6 +195,8 @@ unbound policy security create --name "429 Fallback" --sub-type error-code-routi
 
 Tool policy examples:
 
+> **BREAKING CHANGE in 1.5.0:** `create-terminal` and `create-mcp` now require either `--prompt` (AI-assisted creation) or an explicit `--no-ai` opt-out. Invocations with raw classification flags but no `--no-ai` exit with code 2 and a remediation message. Under Claude Code (`CLAUDECODE=1`), even `--no-ai` is rejected unless you also set `UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1` — this is intended for interactive humans, not agents.
+
 ```bash
 # AI-assisted (preferred): describe the policy in natural language.
 unbound policy tool create-terminal --prompt "block rm -rf"
@@ -207,11 +209,11 @@ unbound policy tool families
 unbound policy tool mcp-servers
 
 # Flag-based fallback: block destructive shell commands explicitly
-unbound policy tool create-terminal --name "Block rm -rf" --command-family filesystem \
+unbound policy tool create-terminal --no-ai --name "Block rm -rf" --command-family filesystem \
     --field command='rm -rf*' --action BLOCK --custom-message "Destructive command blocked."
 
 # Flag-based MCP fallback: audit Linear write operations
-unbound policy tool create-mcp --name "Audit Linear writes" --mcp-server Linear \
+unbound policy tool create-mcp --no-ai --name "Audit Linear writes" --mcp-server Linear \
     --mcp-action-type write --action AUDIT
 
 # List, get, delete

package/package.json

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

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/policy.js

@@ -2,6 +2,7 @@ const config = require('../config');
 const api = require('../api');
 const output = require('../output');
 const { formatDate, confirm, parseCommaSeparated } = require('../utils');
+const { assertSteering, helpBannerFor } = require('../lib/no-ai-guard');
 
 // ============================================================================
 // Constants and docs URLs
@@ -1430,6 +1431,7 @@ Subcommands:
     .command('create-terminal')
     .description('Create a TERMINAL_COMMAND policy: monitor or block shell commands run by AI coding tools.')
     .option('--prompt <text>', 'Natural-language description; routes through Unbound AI assist. Mutually exclusive with --command-family/--field/--config. Compatible with --name/--description/--action overrides.')
+    .option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')
     .option('--name <name>', 'Policy name (required unless --prompt is used)')
     .option('--command-family <family>', 'Command family (e.g. git, filesystem, network). See `policy tool families`.')
     .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable — multiple --field are ANDed (all must match), one per field, for a more specific policy. At least one required unless --config is used.', (val, prev = []) => [...prev, val])
@@ -1441,6 +1443,7 @@ Subcommands:
     .option('--config <json>', 'Advanced: raw config JSON (skips --field builder)')
     .option('--yes', 'Skip the confirmation prompt for --prompt flows (preview is still printed)')
     .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('before', helpBannerFor('create-terminal'))
     .addHelpText('after', `
 Examples:
   # AI-assisted (preferred): describe the policy in natural language.
@@ -1450,15 +1453,15 @@ Examples:
   $ unbound policy tool create-terminal --prompt "block rm -rf" \\
       --name "Block recursive deletes" --action WARN
 
-  $ unbound policy tool create-terminal --name "Block rm -rf" \\
+  $ unbound policy tool create-terminal --no-ai --name "Block rm -rf" \\
       --command-family filesystem --field command='rm -rf*' --action BLOCK \\
       --custom-message "Destructive commands are blocked."
 
-  $ unbound policy tool create-terminal --name "Audit git push" \\
+  $ unbound policy tool create-terminal --no-ai --name "Audit git push" \\
       --command-family git --field command='git push*' --action AUDIT
 
   # Multiple --field are ANDed — this fires only on a push to main on origin:
-  $ unbound policy tool create-terminal --name "Block push to main on origin" \\
+  $ unbound policy tool create-terminal --no-ai --name "Block push to main on origin" \\
       --command-family git_action \\
       --field operation=push --field branch=main --field remote='*origin*' \\
       --action BLOCK --custom-message "Pushing to main on origin is blocked."
@@ -1469,6 +1472,7 @@ Learn more: ${DOCS_TOOL}
     .action(async (opts) => {
       try {
         requireLogin();
+        assertSteering(opts, { subcommandName: 'create-terminal' });
 
         if (opts.prompt !== undefined) {
           if (typeof opts.prompt !== 'string' || opts.prompt.trim() === '') {
@@ -1594,7 +1598,7 @@ Learn more: ${DOCS_TOOL}
         displayToolPolicy(unwrapToolPolicy(data));
       } catch (err) {
         output.error(err.message);
-        process.exitCode = 1;
+        process.exitCode = err.exitCode || 1;
       }
     });
 
@@ -1602,6 +1606,7 @@ Learn more: ${DOCS_TOOL}
     .command('create-mcp')
     .description('Create an MCP_TOOL policy: monitor or block MCP server tool calls.')
     .option('--prompt <text>', 'Natural-language description; routes through Unbound AI assist. Mutually exclusive with --mcp-server/--mcp-tool/--mcp-action-type/--config. Compatible with --name/--description/--action overrides.')
+    .option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')
     .option('--name <name>', 'Policy name (required unless --prompt is used). Override AI suggestion when used with --prompt.')
     .option('--mcp-server <server>', 'MCP server name as shown by `policy tool mcp-servers` (e.g. linear, github). Resolved to its canonical group automatically.')
     .option('--mcp-tool <tool>', 'Specific tool name on the MCP server (e.g. create_issue). Mutually exclusive with --mcp-action-type.')
@@ -1614,6 +1619,7 @@ Learn more: ${DOCS_TOOL}
     .option('--config <json>', 'Advanced: raw config JSON')
     .option('--yes', 'Skip the confirmation prompt for --prompt flows (preview is still printed)')
     .option('--json', 'Output raw JSON of the created policy')
+    .addHelpText('before', helpBannerFor('create-mcp'))
     .addHelpText('after', `
 Examples:
   # AI-assisted (preferred): describe the policy in natural language.
@@ -1625,12 +1631,12 @@ Examples:
       --custom-message "Linear writes are monitored."
 
   # Match a specific tool on a server (flag-based fallback):
-  $ unbound policy tool create-mcp --name "Block Linear writes" \\
+  $ unbound policy tool create-mcp --no-ai --name "Block Linear writes" \\
       --mcp-server linear --mcp-tool create_issue --action BLOCK \\
       --custom-message "Issue creation is blocked. Contact admin."
 
   # Match all destructive tools on a server:
-  $ unbound policy tool create-mcp --name "Audit all destructive Slack" \\
+  $ unbound policy tool create-mcp --no-ai --name "Audit all destructive Slack" \\
       --mcp-server slack --mcp-action-type destructive --action AUDIT
 
 The server name is resolved to its canonical group automatically, so pass the
@@ -1642,6 +1648,7 @@ Learn more: ${DOCS_TOOL}
     .action(async (opts) => {
       try {
         requireLogin();
+        assertSteering(opts, { subcommandName: 'create-mcp' });
 
         if (opts.prompt !== undefined) {
           if (typeof opts.prompt !== 'string' || opts.prompt.trim() === '') {
@@ -1766,7 +1773,7 @@ Learn more: ${DOCS_TOOL}
         displayToolPolicy(unwrapToolPolicy(data));
       } catch (err) {
         output.error(err.message);
-        process.exitCode = 1;
+        process.exitCode = err.exitCode || 1;
       }
     });
 

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/lib/no-ai-guard.js

@@ -0,0 +1,77 @@
+// Steering guard for `policy tool create-terminal` / `create-mcp`.
+//
+// Three layers, evaluated in order. Routing happens BEFORE src/lib/policy-ai-assist.js
+// is reached — this module never touches the network and has no external deps.
+//
+//   Layer 1 (assertSteering): require either --prompt or an explicit --no-ai opt-out.
+//                             Reject --prompt + --no-ai (mutex).
+//   Layer 2 (assertSteering): under CLAUDECODE=1, reject --no-ai unless the env-gated
+//                             escape hatch UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1 is set.
+//   Layer 3 (helpBannerFor):  banner-first --help so the AI-assisted form is the
+//                             one a reader sees first.
+//
+// Errors carry `err.exitCode = 2` so the .action() catch block in src/commands/policy.js
+// can propagate via `process.exitCode = err.exitCode || 1`.
+
+function makeGuardError(message) {
+  const err = new Error(message);
+  err.exitCode = 2;
+  return err;
+}
+
+// Layer 1 + Layer 2. Throws a guard error (exitCode 2) on rejection.
+// `opts` is the parsed commander options object; `--no-ai` arrives as `opts.ai === false`.
+// "prompt provided" means `--prompt` appeared on the command line at all (even
+// empty-string) — the empty-prompt case is validated by the existing
+// `opts.prompt.trim() === ''` check in the prompt branch so that callers see the
+// dedicated "--prompt cannot be empty." error rather than the steering message.
+function assertSteering(opts, { subcommandName, env = process.env } = {}) {
+  const hasPrompt = opts.prompt !== undefined;
+  const noAi = opts.ai === false;
+
+  // Mutex (layer 1): --prompt + --no-ai is incoherent — pick one.
+  if (hasPrompt && noAi) {
+    throw makeGuardError(
+      'Pass --prompt for AI-assisted creation or --no-ai for raw flags, not both.'
+    );
+  }
+
+  // Layer 1: neither --prompt nor --no-ai → steer to the AI-assisted form.
+  if (!hasPrompt && !noAi) {
+    throw makeGuardError(
+      `${subcommandName} requires AI-assisted creation. Retry with --prompt "<natural language description>". To use raw classification flags instead, opt out explicitly with --no-ai.`
+    );
+  }
+
+  // Layer 2: under Claude Code, even --no-ai is rejected unless the human-only
+  // escape hatch is set. This is steering, not security — the env var is in
+  // plain sight in the error message. See PLAN risk R2.
+  if (noAi && env.CLAUDECODE === '1' && env.UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE !== '1') {
+    throw makeGuardError(
+      `--no-ai is disabled under CLAUDECODE=1. This is intended for interactive humans, not for agents. Retry with --prompt "<natural language description>", or set UNBOUND_ALLOW_NO_AI_UNDER_CLAUDE=1 if you are an interactive human.`
+    );
+  }
+}
+
+// Layer 3: banner rendered above commander's auto-generated `Usage:` line by
+// `.addHelpText('before', helpBannerFor(...))`. Keep it short so the help screen
+// is still scannable.
+function helpBannerFor(subcommandName) {
+  const examples = {
+    'create-terminal': 'unbound policy tool create-terminal --prompt "block rm -rf"',
+    'create-mcp': 'unbound policy tool create-mcp --prompt "audit all Linear writes"',
+  };
+  if (!Object.prototype.hasOwnProperty.call(examples, subcommandName)) {
+    throw new Error(`helpBannerFor: unknown subcommand "${subcommandName}"`);
+  }
+  const promptExample = examples[subcommandName];
+  return [
+    'AI-ASSISTED (preferred):',
+    `  $ ${promptExample}`,
+    '',
+    'To use raw classification flags instead, opt out explicitly with --no-ai.',
+    '',
+  ].join('\n');
+}
+
+module.exports = { assertSteering, helpBannerFor };

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') {