@heretyc/subagent-mcp 2.12.1 → 2.12.3

package/dist/routing.js

@@ -12,7 +12,7 @@
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 /** Launch model enum accepted by buildCommand. */
-export const LAUNCH_MODELS = ["haiku", "sonnet", "opus", "opus-4-8", "gpt-5.5"];
+export const LAUNCH_MODELS = ["haiku", "sonnet", "opus", "opus-4-8", "fable", "gpt-5.5"];
 /** Launch effort enum accepted by buildCommand/resolveEffort. */
 export const LAUNCH_EFFORTS = ["medium", "high", "xhigh", "max", "ultracode"];
 /** Sentinel reported (and passed-through harmlessly) for haiku, whose effort is ignored. */
@@ -28,12 +28,14 @@ const FULL_TO_SHORT = {
     "claude-opus-4-8": new Set(["opus", "opus-4-8"]),
     "claude-sonnet-4-6": "sonnet",
     "claude-haiku-4-5": "haiku",
+    "claude-fable-5": "fable",
     "gpt-5.5": "gpt-5.5",
     // Short ids may already appear in a hand-authored table; map them through.
     haiku: "haiku",
     sonnet: "sonnet",
     opus: "opus",
     "opus-4-8": "opus-4-8",
+    fable: "fable",
 };
 export const DEFAULT_BRANCH = "cost_efficiency";
 /** Resolve dist/routing-table.json relative to this module at runtime. */
@@ -76,6 +78,7 @@ export function mapModelToProvider(model) {
         model === "sonnet" ||
         model === "opus" ||
         model === "opus-4-8" ||
+        model === "fable" ||
         model.startsWith("claude-")) {
         return "claude";
     }
@@ -252,8 +255,8 @@ export function validatePresence(p) {
     }
     // provider+model must satisfy the existing match rule.
     if (provider && model) {
-        if (provider === "claude" && !["haiku", "sonnet", "opus", "opus-4-8"].includes(model)) {
-            return `Error: Claude provider only supports haiku, sonnet, opus, or opus-4-8. Got: ${model}`;
+        if (provider === "claude" && !["haiku", "sonnet", "opus", "opus-4-8", "fable"].includes(model)) {
+            return `Error: Claude provider only supports haiku, sonnet, opus, opus-4-8, or fable. Got: ${model}`;
         }
         if (provider === "codex" && model !== "gpt-5.5") {
             return `Error: Codex provider only supports gpt-5.5. Got: ${model}`;

package/dist/ruleset-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/advanced-ruleset.py — DO NOT EDIT.
-export const RULESET_SCAFFOLD = "#!/usr/bin/env python3\n\"\"\"advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.\n\n(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent\n    call. Slow rules slow every agent launch. Keep rules lean and low-latency —\n    no network calls, no heavy imports at module top. This is YOUR responsibility;\n    you have been warned.\n\n(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified\n    candidate list (reorder / filter / replace allowed). Template:\n    [\n      {\"provider\": \"claude\", \"model\": \"sonnet\",  \"effort\": \"high\",  \"rank\": 1},\n      {\"provider\": \"codex\",  \"model\": \"gpt-5.5\", \"effort\": \"xhigh\", \"rank\": 2}\n    ]\n    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8 (claude);\n    gpt-5.5 (codex). Valid efforts: haiku -> \"none\" only; sonnet -> medium|high|xhigh|max;\n    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.\n    \"rank\" on output is ignored. An EMPTY array vetoes the launch. Anything else\n    invalid fails the launch hard — the server validates strictly.\n\n(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):\n    stdin receives one JSON object:\n    { \"candidates\": [ {\"provider\",\"model\",\"effort\",\"rank\"} ... ],   # rank 1..N best->worst\n      \"context\": { \"task_category\": str, \"cwd\": str,\n                   \"selection_mode\": \"auto\"|\"provider\"|\"provider_model\"|\"explicit\",\n                   \"provider\": str|None, \"model\": str|None, \"effort\": str|None } }\n    OS environment variables are visible natively (os.environ).\n\nENV-CHECK MODE (no arguments): prints {\"ready\": true|false, \"load-rules\": true|false}.\nRuns once per MCP server process. load-rules false => ruleset silently disabled\nfor the rest of the process. Set LOAD_RULES = True below to activate.\n\"\"\"\nimport json\nimport sys\n\nLOAD_RULES = False\n\n# --- Requirements stub (scaffold itself is stdlib-only) ----------------------\n# List third-party distributions your rules import, e.g.:\n# REQUIREMENTS = [\"requests\", \"pyyaml\"]\n# Install with:  <python> -m pip install <name> ...\nREQUIREMENTS = []\n\ndef missing_requirements():\n    \"\"\"pip-check helper: returns the REQUIREMENTS entries not importable here.\"\"\"\n    import importlib.util\n    return [r for r in REQUIREMENTS\n            if importlib.util.find_spec(r.replace(\"-\", \"_\")) is None]\n\ndef env_check():\n    missing = missing_requirements()\n    json.dump({\"ready\": not missing, \"load-rules\": bool(LOAD_RULES)}, sys.stdout)\n\ndef apply_rules(candidates, context):\n    \"\"\"YOUR RULES HERE. Default: passthrough (returns the list unchanged).\"\"\"\n    return candidates\n\ndef route():\n    payload = json.load(sys.stdin)\n    out = apply_rules(payload.get(\"candidates\", []), payload.get(\"context\", {}))\n    json.dump(out, sys.stdout)\n\nif __name__ == \"__main__\":\n    if len(sys.argv) > 1 and sys.argv[1] == \"route\":\n        route()\n    else:\n        env_check()\n";
+export const RULESET_SCAFFOLD = "#!/usr/bin/env python3\r\n\"\"\"advanced-ruleset.py — final-authority model-routing override hook for subagent-mcp.\r\n\r\n(a) PERFORMANCE WARNING: this script runs synchronously inside EVERY launch_agent\r\n    call. Slow rules slow every agent launch. Keep rules lean and low-latency —\r\n    no network calls, no heavy imports at module top. This is YOUR responsibility;\r\n    you have been warned.\r\n\r\n(b) OUTPUT CONTRACT (routing mode): print to stdout ONE JSON array — the modified\r\n    candidate list (reorder / filter / replace allowed). Template:\r\n    [\r\n      {\"provider\": \"claude\", \"model\": \"sonnet\",  \"effort\": \"high\",  \"rank\": 1},\r\n      {\"provider\": \"codex\",  \"model\": \"gpt-5.5\", \"effort\": \"xhigh\", \"rank\": 2}\r\n    ]\r\n    Valid providers: claude, codex. Valid models: haiku, sonnet, opus, opus-4-8, fable (claude);\r\n    gpt-5.5 (codex). Valid efforts: haiku -> \"none\" only; sonnet -> medium|high|xhigh|max;\r\n    fable -> medium|high|xhigh|max; opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> medium|high|xhigh.\r\n    \"rank\" on output is ignored. An EMPTY array vetoes the launch. Anything else\r\n    invalid fails the launch hard — the server validates strictly.\r\n\r\n(c) INPUT CONTRACT (routing mode, invoked as: <python> advanced-ruleset.py route):\r\n    stdin receives one JSON object:\r\n    { \"candidates\": [ {\"provider\",\"model\",\"effort\",\"rank\"} ... ],   # rank 1..N best->worst\r\n      \"context\": { \"task_category\": str, \"cwd\": str,\r\n                   \"selection_mode\": \"auto\"|\"provider\"|\"provider_model\"|\"explicit\",\r\n                   \"provider\": str|None, \"model\": str|None, \"effort\": str|None } }\r\n    OS environment variables are visible natively (os.environ).\r\n\r\nENV-CHECK MODE (no arguments): prints {\"ready\": true|false, \"load-rules\": true|false}.\r\nRuns once per MCP server process. load-rules false => ruleset silently disabled\r\nfor the rest of the process. Set LOAD_RULES = True below to activate.\r\n\"\"\"\r\nimport json\r\nimport sys\r\n\r\nLOAD_RULES = False\r\n\r\n# --- Requirements stub (scaffold itself is stdlib-only) ----------------------\r\n# List third-party distributions your rules import, e.g.:\r\n# REQUIREMENTS = [\"requests\", \"pyyaml\"]\r\n# Install with:  <python> -m pip install <name> ...\r\nREQUIREMENTS = []\r\n\r\ndef missing_requirements():\r\n    \"\"\"pip-check helper: returns the REQUIREMENTS entries not importable here.\"\"\"\r\n    import importlib.util\r\n    return [r for r in REQUIREMENTS\r\n            if importlib.util.find_spec(r.replace(\"-\", \"_\")) is None]\r\n\r\ndef env_check():\r\n    missing = missing_requirements()\r\n    json.dump({\"ready\": not missing, \"load-rules\": bool(LOAD_RULES)}, sys.stdout)\r\n\r\ndef apply_rules(candidates, context):\r\n    \"\"\"YOUR RULES HERE. Default: passthrough (returns the list unchanged).\"\"\"\r\n    return candidates\r\n\r\ndef route():\r\n    payload = json.load(sys.stdin)\r\n    out = apply_rules(payload.get(\"candidates\", []), payload.get(\"context\", {}))\r\n    json.dump(out, sys.stdout)\r\n\r\nif __name__ == \"__main__\":\r\n    if len(sys.argv) > 1 and sys.argv[1] == \"route\":\r\n        route()\r\n    else:\r\n        env_check()\r\n";

package/dist/ruleset.js

@@ -169,7 +169,7 @@ const CODEX_EFFORTS = LAUNCH_EFFORTS.filter((e) => e !== "ultracode" && e !== "m
 function effortAllowed(model, effort) {
     if (model === "haiku")
         return effort === HAIKU_EFFORT;
-    if (model === "sonnet")
+    if (model === "sonnet" || model === "fable")
         return SONNET_EFFORTS.includes(effort);
     if (model === "opus" || model === "opus-4-8") {
         return LAUNCH_EFFORTS.includes(effort);
@@ -185,7 +185,7 @@ function effortAllowed(model, effort) {
  *
  * Per element: string provider/model/effort; provider ∈ {claude, codex};
  * model ∈ launch enum; provider↔model legality (claude↔{haiku,sonnet,opus,
- * opus-4-8}, codex↔gpt-5.5); per-model effort legality incl. haiku→"none".
+ * opus-4-8,fable}, codex↔gpt-5.5); per-model effort legality incl. haiku→"none".
  * Extra keys (incl. rank) are ignored on output; duplicates are allowed (the
  * attempt loop just tries them in order). An EMPTY array is VALID — it is the
  * limit case of the allowed filter operation and means "veto the launch"

package/package.json

@@ -1,69 +1,69 @@
-{
-  "name": "@heretyc/subagent-mcp",
-  "version": "2.12.1",
-  "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
-  "keywords": [
-    "mcp",
-    "model-context-protocol",
-    "mcp-server",
-    "claude",
-    "claude-code",
-    "codex",
-    "orchestration",
-    "subagent",
-    "sub-agent",
-    "multi-agent",
-    "ai-agents",
-    "anthropic",
-    "openai"
-  ],
-  "type": "module",
-  "main": "dist/index.js",
-  "bin": {
-    "subagent-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist",
-    "directives",
-    "scripts/postinstall.mjs",
-    "LICENSE",
-    "NOTICE",
-    "README.md"
-  ],
-  "scripts": {
-    "check:versions": "node scripts/check_version_sync.mjs",
-    "build": "npm run check:versions && node scripts/gen-ruleset-scaffold.mjs && tsc && node scripts/copy-provider.mjs",
-    "verify:npmjs-release": "node scripts/verify_npmjs_release.mjs",
-    "start": "node dist/index.js",
-    "postinstall": "node scripts/postinstall.mjs",
-    "prepare": "npm run build",
-    "prepublishOnly": "npm test",
-    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/zombie.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
-  },
-  "author": "Lexi Blackburn",
-  "license": "Apache-2.0",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Heretyc/subagent-mcp.git"
-  },
-  "homepage": "https://github.com/Heretyc/subagent-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/Heretyc/subagent-mcp/issues"
-  },
-  "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.177",
-    "@modelcontextprotocol/sdk": "^1.0.0",
-    "zod": "^4.4.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0"
-  },
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "registry": "https://registry.npmjs.org",
-    "access": "public"
-  }
-}
+{
+  "name": "@heretyc/subagent-mcp",
+  "version": "2.12.3",
+  "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "mcp-server",
+    "claude",
+    "claude-code",
+    "codex",
+    "orchestration",
+    "subagent",
+    "sub-agent",
+    "multi-agent",
+    "ai-agents",
+    "anthropic",
+    "openai"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "subagent-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "directives",
+    "scripts/postinstall.mjs",
+    "LICENSE",
+    "NOTICE",
+    "README.md"
+  ],
+  "scripts": {
+    "check:versions": "node scripts/check_version_sync.mjs",
+    "build": "npm run check:versions && node scripts/gen-ruleset-scaffold.mjs && tsc && node scripts/copy-provider.mjs",
+    "verify:npmjs-release": "node scripts/verify_npmjs_release.mjs",
+    "start": "node dist/index.js",
+    "postinstall": "node scripts/postinstall.mjs",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test",
+    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/update-check.test.mjs && node test/zombie.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
+  },
+  "author": "Lexi Blackburn",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Heretyc/subagent-mcp.git"
+  },
+  "homepage": "https://github.com/Heretyc/subagent-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/Heretyc/subagent-mcp/issues"
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.177",
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/scripts/postinstall.mjs

@@ -1,102 +1,102 @@
-#!/usr/bin/env node
-// Postinstall banner for subagent-mcp.
-//
-// `npm install -g @heretyc/subagent-mcp` ships only the MCP server + hook
-// assets; it does NOT wire them into Claude Code / Codex. Without feedback the
-// user has no idea an addon landed, let alone that a second step is required.
-// This prints a clear "what installed / what to run next / how to verify"
-// banner so the install is self-explanatory.
-//
-// Rules:
-//   - NEVER fail the install. Any error is swallowed; always exit 0.
-//   - Only speak for a real end-user install. In the dev checkout (src/ present)
-//     stay silent so `npm install` during development isn't noisy.
-//   - Print only — do not mutate vendor config. Wiring is the explicit,
-//     reversible `subagent-mcp setup` step.
-
-import { existsSync, readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join, dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { execSync } from "node:child_process";
-
-try {
-  // Install root: scripts/postinstall.mjs -> scripts/ -> <root>
-  const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-
-  // Dev checkout? (src/ only exists in the repo, never in the shipped tarball.)
-  // Stay silent there — the maintainer doesn't need the end-user banner.
-  if (existsSync(join(ROOT, "src"))) process.exit(0);
-
-  let version = "";
-  try {
-    version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version || "";
-  } catch { /* version is cosmetic */ }
-
-  // Best-effort vendor detection so the banner can say what WILL be wired.
-  // Pure read-only; failures just fall back to "not detected".
-  function has(cmd) {
-    try {
-      execSync(process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`, {
-        stdio: "ignore",
-      });
-      return true;
-    } catch {
-      return false;
-    }
-  }
-  const hasClaude = has("claude");
-  const hasCodex = has("codex") || existsSync(join(homedir(), ".codex"));
-
-  const L = [];
-  const line = (s = "") => L.push(s);
-  const bar = "============================================================";
-
-  line();
-  line(bar);
-  line(`  subagent-mcp installed${version ? `  (v${version})` : ""}`);
-  line(bar);
-  line();
-  line("  This is an MCP ADDON for Claude Code CLI and Codex CLI.");
-  line("  It is NOT active yet — one command wires it in.");
-  line();
-  line("  FINISH SETUP  (auto-detects vendors, wires all present):");
-  line();
-  line("      subagent-mcp setup");
-  line();
-  line("  That registers the MCP server AND installs the per-turn");
-  line("  orchestration-mode hooks for every vendor it finds.");
-  line();
-
-  // Detected vendors — concrete, so the user knows what setup will touch.
-  if (hasClaude || hasCodex) {
-    line("  Detected on this machine:");
-    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit/PreToolUse hooks)");
-    if (hasCodex) line("    - Codex CLI        (will get MCP server + SessionStart/UserPromptSubmit hooks)");
-  } else {
-    line("  No Claude Code or Codex CLI detected yet. Install one,");
-    line("  then run:  subagent-mcp setup");
-  }
-  line();
-
-  line("  AFTER setup — confirm it took effect:");
-  if (hasClaude || !hasCodex) {
-    line("    - Claude Code: restart the session, run /mcp");
-    line("        -> 'subagent-mcp' shows Connected.");
-  }
-  if (hasCodex || !hasClaude) {
-    line("    - Codex CLI:   restart the session, run /hooks");
-    line("        -> TRUST the new subagent-mcp hook.");
-  }
-  line();
-  line("  Preview without changes:   subagent-mcp setup --dry-run");
-  line("  Health check any time:     subagent-mcp doctor");
-  line("  Docs:  https://github.com/Heretyc/subagent-mcp#readme");
-  line(bar);
-  line();
-
-  process.stdout.write(L.join("\n") + "\n");
-} catch {
-  // Never let a banner failure break the install.
-}
-process.exit(0);
+#!/usr/bin/env node
+// Postinstall banner for subagent-mcp.
+//
+// `npm install -g @heretyc/subagent-mcp` ships only the MCP server + hook
+// assets; it does NOT wire them into Claude Code / Codex. Without feedback the
+// user has no idea an addon landed, let alone that a second step is required.
+// This prints a clear "what installed / what to run next / how to verify"
+// banner so the install is self-explanatory.
+//
+// Rules:
+//   - NEVER fail the install. Any error is swallowed; always exit 0.
+//   - Only speak for a real end-user install. In the dev checkout (src/ present)
+//     stay silent so `npm install` during development isn't noisy.
+//   - Print only — do not mutate vendor config. Wiring is the explicit,
+//     reversible `subagent-mcp setup` step.
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execSync } from "node:child_process";
+
+try {
+  // Install root: scripts/postinstall.mjs -> scripts/ -> <root>
+  const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+  // Dev checkout? (src/ only exists in the repo, never in the shipped tarball.)
+  // Stay silent there — the maintainer doesn't need the end-user banner.
+  if (existsSync(join(ROOT, "src"))) process.exit(0);
+
+  let version = "";
+  try {
+    version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version || "";
+  } catch { /* version is cosmetic */ }
+
+  // Best-effort vendor detection so the banner can say what WILL be wired.
+  // Pure read-only; failures just fall back to "not detected".
+  function has(cmd) {
+    try {
+      execSync(process.platform === "win32" ? `where ${cmd}` : `command -v ${cmd}`, {
+        stdio: "ignore",
+      });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  const hasClaude = has("claude");
+  const hasCodex = has("codex") || existsSync(join(homedir(), ".codex"));
+
+  const L = [];
+  const line = (s = "") => L.push(s);
+  const bar = "============================================================";
+
+  line();
+  line(bar);
+  line(`  subagent-mcp installed${version ? `  (v${version})` : ""}`);
+  line(bar);
+  line();
+  line("  This is an MCP ADDON for Claude Code CLI and Codex CLI.");
+  line("  It is NOT active yet — one command wires it in.");
+  line();
+  line("  FINISH SETUP  (auto-detects vendors, wires all present):");
+  line();
+  line("      subagent-mcp setup");
+  line();
+  line("  That registers the MCP server AND installs the per-turn");
+  line("  orchestration-mode hooks for every vendor it finds.");
+  line();
+
+  // Detected vendors — concrete, so the user knows what setup will touch.
+  if (hasClaude || hasCodex) {
+    line("  Detected on this machine:");
+    if (hasClaude) line("    - Claude Code CLI  (will get MCP server + UserPromptSubmit/PreToolUse hooks)");
+    if (hasCodex) line("    - Codex CLI        (will get MCP server + SessionStart/UserPromptSubmit hooks)");
+  } else {
+    line("  No Claude Code or Codex CLI detected yet. Install one,");
+    line("  then run:  subagent-mcp setup");
+  }
+  line();
+
+  line("  AFTER setup — confirm it took effect:");
+  if (hasClaude || !hasCodex) {
+    line("    - Claude Code: restart the session, run /mcp");
+    line("        -> 'subagent-mcp' shows Connected.");
+  }
+  if (hasCodex || !hasClaude) {
+    line("    - Codex CLI:   restart the session, run /hooks");
+    line("        -> TRUST the new subagent-mcp hook.");
+  }
+  line();
+  line("  Preview without changes:   subagent-mcp setup --dry-run");
+  line("  Health check any time:     subagent-mcp doctor");
+  line("  Docs:  https://github.com/Heretyc/subagent-mcp#readme");
+  line(bar);
+  line();
+
+  process.stdout.write(L.join("\n") + "\n");
+} catch {
+  // Never let a banner failure break the install.
+}
+process.exit(0);