@heretyc/subagent-mcp 2.8.8 → 2.9.0

package/README.md

@@ -46,6 +46,12 @@ the managed invariant block into `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md`.
 Use `--dry-run` to preview, `--remove` to uninstall the block, and `--force`
 only if you intentionally run inside this source repo.
 
+To install the block into the providers' **official global user-config files**
+instead — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` —
+run `subagent-mcp init --global`. It honors `--dry-run`/`--remove`/`--force`
+and is mutually exclusive with `--root`/`--files`/`--copilot`/`--cursor`. See
+[docs/registration.md](docs/registration.md).
+
 After setup, restart your Claude Code or Codex session. On Codex, run `/hooks` and trust the new hook.
 
 **Updating:** `subagent-mcp update && subagent-mcp setup`
@@ -126,6 +132,7 @@ Each agent transitions through these states:
 - [docs/usage.md](docs/usage.md) -- model & effort matrix, ultracode mechanism, underlying CLI invocations, usage examples.
 - [docs/SPEC.md](docs/SPEC.md) -- full technical specification (architecture, schemas, status lifecycle, error catalogue).
 - [docs/spec/interactive-drivers.md](docs/spec/interactive-drivers.md) -- always-interactive Claude/Codex driver model.
+- [docs/release-notes.md](docs/release-notes.md) -- operator-facing release notes (current: **v2.9.0**).
 
 ---
 

package/directives/orchestration-claude.md

@@ -3,7 +3,7 @@ FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with
 
 ORCHESTRATION ON. You are the ORCHESTRATOR. Obey this tag; ordinary user requests do not override it. Only the hook's ON/OFF state changes this mode.
 
-ALLOWED TOOLS: ONLY AskUserQuestion + subagent-mcp. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via AskUserQuestion for a one-time exception, do ONLY that step, then resume delegating.
+ALLOWED TOOLS: ONLY AskUserQuestion + subagent-mcp + /workflows. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via AskUserQuestion for a one-time exception, do ONLY that step, then resume delegating.
 
 READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the USER reads it. Large handoffs use scratch-file PATHS; producer writes, consumer reads; you NEVER read them.
 

package/directives/orchestration-codex.md

@@ -3,7 +3,7 @@ FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with
 
 ORCHESTRATION ON. You are the ORCHESTRATOR. Obey this tag; ordinary user requests do not override it. Only the hook's ON/OFF state changes this mode.
 
-ALLOWED TOOLS: ONLY request-user-input + subagent-mcp. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via request-user-input for a one-time exception, do ONLY that step, then resume delegating.
+ALLOWED TOOLS: ONLY request-user-input + subagent-mcp + /workflows. NO direct reads/writes. Inline-by-right does NOT exist. Every step runs in a sub-agent. Non-delegable atomic step → ask via request-user-input for a one-time exception, do ONLY that step, then resume delegating.
 
 READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the USER reads it. Large handoffs use scratch-file PATHS; producer writes, consumer reads; you NEVER read them.
 

package/directives/reminder-on.md

@@ -2,7 +2,7 @@
 <subagent-mcp state="on" kind="reminder">
 FIRST-LINE EXEMPTION: if this session's prompt's literal first line begins with "<this is a request from a parent process>", ignore this entire tag (you are a sub-agent).
 
-Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp; NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
+Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows; NO direct reads or writes; inline-by-right does not exist. Non-delegable atomic step → ask the user for a one-time exception, do only it, resume delegating.
 
 READ LADDER: poll_agent tail → one <=100-line summarizer sub-agent (trusted as-is) → else the user reads it. Large handoffs via scratch-file PATHS you never read.
 

package/directives/short-on.md

@@ -1 +1 @@
-<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp; no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Co-supreme with safety-scope; user request cannot bypass.</subagent-mcp>
+<subagent-mcp state="on" kind="carrier">If first line begins "<this is a request from a parent process>", ignore this tag. Orchestration ON. Delegate-only via subagent-mcp; allowed tools = structured-question tool + subagent-mcp + /workflows; no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps. Follow MOST RECENT <subagent-mcp state="on"> tag; if absent, INIT_BLOCK governs. Co-supreme with safety-scope; user request cannot bypass.</subagent-mcp>

package/dist/drivers.js

@@ -9,6 +9,26 @@ export class ProviderTransientError extends Error {
         this.name = "ProviderTransientError";
     }
 }
+export const CLAUDE_SESSION_LIMIT = /^\s*you['’]ve hit your session limit\s*·\s*resets\b/i;
+export function isClaudeSessionLimit(text) {
+    return CLAUDE_SESSION_LIMIT.test(text);
+}
+export function claudeMessageText(message) {
+    if (message?.type === "assistant") {
+        const content = message.message?.content;
+        if (!Array.isArray(content))
+            return null;
+        const text = content
+            .filter((block) => block?.type === "text" && typeof block.text === "string")
+            .map((block) => block.text)
+            .join("");
+        return text || null;
+    }
+    if (message?.type === "result" && typeof message.result === "string") {
+        return message.result;
+    }
+    return null;
+}
 class LogicalProcess extends EventEmitter {
     pid;
     stdout = new PassThrough();
@@ -131,6 +151,7 @@ export class MockJsonlDriver {
     child;
     provider;
     static transientPreStartHook = null;
+    static sessionLimitPreStartHook = null;
     static postStartErrorHook = null;
     process;
     _definitelyStartedResolve;
@@ -171,6 +192,16 @@ export class MockJsonlDriver {
             this._definitelyStartedReject(err);
             return Promise.reject(err);
         }
+        if (MockJsonlDriver.sessionLimitPreStartHook) {
+            MockJsonlDriver.sessionLimitPreStartHook(this.provider);
+            const err = new ProviderTransientError("You've hit your session limit · resets 7:10pm (America/Los_Angeles)");
+            setTimeout(() => {
+                this._definitelyStartedReject(err);
+                this.process.stderr.write(err.message);
+                this.process.close(1);
+            }, 0);
+            return Promise.resolve();
+        }
         if (MockJsonlDriver.postStartErrorHook) {
             this._definitelyStartedResolve();
             MockJsonlDriver.postStartErrorHook(this.provider);
@@ -472,11 +503,21 @@ export class ClaudeSdkDriver {
         let started = false;
         try {
             for await (const message of query) {
-                if (!started) {
+                const text = claudeMessageText(message);
+                if (!started && text && isClaudeSessionLimit(text)) {
+                    // Launch-time failover only applies before startup resolves/spawn grace ends;
+                    // post-registration session-limit rerouting is intentionally out of scope.
+                    this._definitelyStartedReject(new ProviderTransientError(text));
+                    this.closedFlag = true;
+                    this.process.stderr.write(text);
+                    this.process.close(1);
+                    return;
+                }
+                this.process.stdout.write(`${JSON.stringify(message)}\n`);
+                if (!started && message?.type !== "system") {
                     started = true;
                     this._definitelyStartedResolve();
                 }
-                this.process.stdout.write(`${JSON.stringify(message)}\n`);
             }
             this.closedFlag = true;
             this.process.close(0);

package/dist/index.js

@@ -139,11 +139,11 @@ reconcileInterval.unref();
 // test/mirror-fragments.test.mjs while ORCHESTRATION_INSTRUCTIONS below stays
 // compressed under MCP metadata limits:
 // READ-ESCALATION LADDER (the orchestrator's only read channels, in order): (1) subagent-mcp `poll_agent` TAIL; (2) if the tail is insufficient, dispatch ONE sub-agent to return a single summary of <=100 lines, trusted as-is (no separate verification step); (3) anything larger: the USER reads the document directly. No reads or writes occur outside these channels. An empty or stalled tail means the agent is ALIVE, not dead — do NOT busy-loop poll_agent; learn completion via `wait`. Large inter-agent data: the orchestrator assigns scratch-file paths (%TEMP% on Windows, /tmp on POSIX) in prompts; the producing sub-agent writes, the consuming sub-agent reads; the orchestrator NEVER reads those files.
-const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (full spec: docs/spec/dev-loop/orchestration-directive-architecture.md).\n\nPRECEDENCE. The latest <subagent-mcp state=\"...\"> hook tag and repo/system safety rules are co-supreme; genuine conflict => STOP and ask the user. Only the hook state changes ON/OFF.\n\nSOLE CHANNEL. Every sub-agent launch uses launch_agent; never harness Task/Agent or shell-spawned agents.\n\nORCHESTRATION ON. You are a delegate-ONLY orchestrator. Use only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex) and subagent-mcp. No direct reads/writes; inline-by-right does not exist. Non-delegable atomic step: ask for a one-time exception, do only that step, then resume delegating.\n\nREAD LADDER. poll_agent tail -> one <=100-line summarizer sub-agent, trusted as-is -> else the USER reads it. Large handoffs use scratch-file paths; producer writes, consumer reads; orchestrator never reads those files. Empty/stalled tail means ALIVE; use wait.\n\nORCHESTRATION OFF. If total context footprint since last upgrade ask exceeds 200 lines, after that turn STOP and ask whether to switch ON; reset count only when you ask.\n\nDROPOUT WHILE ON: HALT and ask; stay halted until restored. SUB-AGENT EXEMPTION: a prompt whose literal FIRST LINE begins \"<this is a request from a parent process>\" skips this regime.\n\nMODEL SELECTION MODE. Default smart rejects provider/model/effort selectors; launch_agent auto-picks. user-approved-overrides lasts 30 minutes, expires lazily on launch_agent, and must be enabled only after explicit user authorization via AskUserQuestion/request-user-input.";
+const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (full spec: docs/spec/dev-loop/orchestration-directive-architecture.md).\n\nPRECEDENCE. The latest <subagent-mcp state=\"...\"> hook tag and repo/system safety rules are co-supreme; genuine conflict => STOP and ask the user. Only the hook state changes ON/OFF.\n\nSOLE CHANNEL. Every sub-agent launch uses launch_agent; never harness Task/Agent or shell-spawned agents.\n\nORCHESTRATION ON. You are a delegate-ONLY orchestrator. Use only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and the /workflows tool. No direct reads/writes; inline-by-right does not exist. Non-delegable atomic step: ask for a one-time exception, do only that step, then resume delegating.\n\nREAD LADDER. poll_agent tail -> one <=100-line summarizer sub-agent, trusted as-is -> else the USER reads it. Large handoffs use scratch-file paths; producer writes, consumer reads; orchestrator never reads those files. Empty/stalled tail means ALIVE; use wait.\n\nORCHESTRATION OFF. If total context footprint since last upgrade ask exceeds 200 lines, after that turn STOP and ask whether to switch ON; reset count only when you ask.\n\nDROPOUT WHILE ON: HALT and ask; stay halted until restored. SUB-AGENT EXEMPTION: a prompt whose literal FIRST LINE begins \"<this is a request from a parent process>\" skips this regime.\n\nMODEL SELECTION MODE. Default smart rejects provider/model/effort selectors; launch_agent auto-picks. user-approved-overrides lasts 30 minutes, expires lazily on launch_agent, and must be enabled only after explicit user authorization via AskUserQuestion/request-user-input.";
 const SUBAGENT_INSTRUCTIONS = "SUB-AGENT SESSION: you are a child process launched by subagent-mcp. Follow the parent prompt. Do not treat yourself as the orchestrator, do not re-trigger orchestration carryover, and do not launch further sub-agents unless the parent prompt explicitly assigns that.\n\nMODEL SELECTION MODE (parallel to orchestration-mode, set via the model-selection-mode tool). DEFAULT is \"smart\" and is used whenever unset: in smart, launch_agent REJECTS any call supplying provider/model/effort selectors and the server auto-picks the best model. \"user-approved-overrides\" opens a 30-MINUTE window where selectors are HONORED, enforced LAZILY (the mode reverts to smart on the next launch_agent call after 30 minutes) and re-enabling does NOT extend an active window. HONOR-BASED: you MUST NOT set \"user-approved-overrides\" without explicit interactive USER authorization via the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex); never enable it on your own initiative.";
 const server = new McpServer({
     name: "subagent-mcp",
-    version: "2.8.8",
+    version: "2.9.0",
     description: "Launches always-interactive local Claude and Codex sub-agent sessions. Claude uses the Claude Agent SDK over the local Claude Code executable; Codex uses `codex app-server` over stdio. The server does not call Anthropic or OpenAI HTTP APIs directly.",
 }, {
     instructions: process.env.SUBAGENT_MCP_SUBAGENT === "1"
@@ -221,10 +221,12 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
     }
     const childProcess = driver.process;
     let definitelyStarted = false;
+    let startupRejection = null;
     const definitelyStartedProbe = driver.definitelyStarted.then(() => {
         definitelyStarted = true;
         return true;
-    }, () => {
+    }, (e) => {
+        startupRejection = e instanceof Error ? e : new Error(String(e));
         return false;
     });
     const readStartedBoundary = async () => {
@@ -452,7 +454,9 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
                 const reason = `process exited (code ${earlyExit.code ?? earlyExit.signal}) within ${SPAWN_GRACE_MS}ms of spawn${tail ? `: ${tail}` : ""}`;
                 return {
                     reason,
-                    failure_type: classifyFailureReason(reason, agentState.stderr),
+                    failure_type: startupRejection
+                        ? failureTypeForError(startupRejection, agentState.stderr)
+                        : classifyFailureReason(reason, agentState.stderr),
                 };
             }
         }
@@ -1000,7 +1004,7 @@ server.tool("wait", "Blocks until one or more sub-agents reach a reportable stat
     };
 });
 // Tool 7: orchestration-mode
-server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF, omit = query current state. SOLE CHANNEL: the subagent MCP is the ONLY sanctioned channel for launching sub-agents whether this mode is ON or OFF — toggling OFF does not lift that obligation. When OFF, run the per-turn upgrade check: a long-horizon task = any whose TOTAL context footprint (input read + output produced) exceeds 200 lines, measured CUMULATIVELY since your last upgrade ask; after EVERY user turn, if it qualifies, STOP and ask the user whether to switch ON (ask every qualifying turn; a decline does not latch; reset the count only when you actually ask). The FULL operating model + governance is carried in this server's MCP `instructions` (read once at initialize) — this is the operational summary only; do not act on the mode without that detail. WHAT: a per-project toggle for LONG-HORIZON work that would fill the context window if run to completion inline; when ON, act as an orchestrator with delegate-default, but steps bound to main-session-only capability stay INLINE BY RIGHT (state which + why). PERSISTENCE: a per-project marker keyed by cwd; absence of the marker = OFF = no injection; once ON it persists across restarts/sessions until a permitted disable (it does NOT reset on a new session). CARRYOVER: if ON was inherited from a PRIOR session (provenance = carried-over, not user-enabled this session), the bundled hook prepends a ONE-TIME notice (once per marker, never per turn) — you MUST then notify the user it auto-activated and confirm whether to keep it ON. DISABLE: never on your own initiative; you MAY PROPOSE turning it OFF on task-fit mismatch, but only EXPLICIT user permission (AskUserQuestion on Claude, request-user-input on Codex) may set enabled:false. Per-turn injection fires only in CLI hosts that load the bundled hook; desktop hosts toggle the marker but inject nothing (documented degradation).", {
+server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF, omit = query current state. SOLE CHANNEL: the subagent MCP is the ONLY sanctioned channel for launching sub-agents whether this mode is ON or OFF — toggling OFF does not lift that obligation. When OFF, run the per-turn upgrade check: a long-horizon task = any whose TOTAL context footprint (input read + output produced) exceeds 200 lines, measured CUMULATIVELY since your last upgrade ask; after EVERY user turn, if it qualifies, STOP and ask the user whether to switch ON (ask every qualifying turn; a decline does not latch; reset the count only when you actually ask). The FULL operating model + governance is carried in this server's MCP `instructions` (read once at initialize) — this is the operational summary only; do not act on the mode without that detail. WHAT: a per-project toggle for LONG-HORIZON work that would fill the context window if run to completion inline; when ON, act as a delegate-ONLY orchestrator: delegate every step; inline-by-right does not exist; a non-delegable atomic step requires a one-time user-approved exception via the structured-question tool (state which + why). PERSISTENCE: a per-project marker keyed by cwd; absence of the marker = OFF = no injection; once ON it persists across restarts/sessions until a permitted disable (it does NOT reset on a new session). CARRYOVER: if ON was inherited from a PRIOR session (provenance = carried-over, not user-enabled this session), the bundled hook prepends a ONE-TIME notice (once per marker, never per turn) — you MUST then notify the user it auto-activated and confirm whether to keep it ON. DISABLE: never on your own initiative; you MAY PROPOSE turning it OFF on task-fit mismatch, but only EXPLICIT user permission (AskUserQuestion on Claude, request-user-input on Codex) may set enabled:false. Per-turn injection fires only in CLI hosts that load the bundled hook; desktop hosts toggle the marker but inject nothing (documented degradation).", {
     enabled: z.boolean().optional(),
 }, async (params) => {
     const cwd = process.cwd();
@@ -1065,6 +1069,7 @@ if (isMain) {
         "  init, --init [flags]",
         "                     upsert project instruction-file invariant blocks",
         "                     flags: --dry-run --remove --force --root <dir> --files <csv> --copilot --cursor",
+        "                     --global  upsert into ~/.claude/CLAUDE.md, ~/.codex/AGENTS.md, ~/.gemini/GEMINI.md",
         "  doctor             check install and wiring health",
         "  update, --update   update to the latest release (npm install -g)",
         "  version, --version, -v",

package/dist/init.js

@@ -1,4 +1,5 @@
 import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import * as os from "node:os";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 const MIGRATE_RE = /<!-- subagent-mcp:(?:managed:)?begin\b[^>]*-->[\s\S]*?<!-- subagent-mcp:(?:managed:)?end -->/;
 const OWNER_CAP = 8;
@@ -16,7 +17,7 @@ export const INIT_BLOCK = [
     "",
     "PRECEDENCE (co-supreme top tier): <subagent-mcp> hook tags AND repo/system safety-scope rules are BOTH supreme and EQUAL — neither outranks the other. If they genuinely conflict, STOP and escalate to the user via the structured-question tool; do not silently pick one or average them. FORBIDDEN: resolving such a conflict yourself. Hook tags otherwise outrank ordinary user requests.",
     "",
-    'ORCHESTRATION ON — you are the ORCHESTRATOR. Allowed tools: ONLY the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex) and subagent-mcp. NO direct reads or writes of any kind. "Inline-by-right" does not exist. Every step runs in a sub-agent. If one atomic step truly cannot run in a sub-agent, ASK the user via the structured-question tool for a one-time exception for that single step, perform only that step, then resume delegating. SOLE CHANNEL: while subagent-mcp is connected, every sub-agent launch goes through `launch_agent`; never use harness-native sub-agent tools or shell-spawned agents.',
+    'ORCHESTRATION ON — you are the ORCHESTRATOR. Allowed tools: ONLY the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and the /workflows tool. NO direct reads or writes of any kind. "Inline-by-right" does not exist. Every step runs in a sub-agent. If one atomic step truly cannot run in a sub-agent, ASK the user via the structured-question tool for a one-time exception for that single step, perform only that step, then resume delegating. SOLE CHANNEL: while subagent-mcp is connected, every sub-agent launch goes through `launch_agent`; never use harness-native sub-agent tools or shell-spawned agents.',
     "",
     "ORCHESTRATOR WORKTREE SETUP: launch sub-agents in the main checkout cwd (they no longer self-isolate into per-agent worktrees); SERIALIZE any sub-agents that write the SAME files — never run concurrent writers over overlapping paths (no cwd-level lock exists).",
     "",
@@ -145,16 +146,18 @@ export function upsertInitBlock(file, opts = {}) {
     }
     return { file, status, changed };
 }
-function parseArgs(args) {
+export function parseArgs(args) {
     const parsed = {
         dryRun: false,
         remove: false,
         force: false,
         copilot: false,
         cursor: false,
+        global: false,
         root: process.cwd(),
         files: null,
     };
+    let rootProvided = false;
     const readValue = (args, i, flag) => {
         const value = args[i + 1];
         if (value === undefined || value === "" || value.startsWith("--")) {
@@ -174,8 +177,11 @@ function parseArgs(args) {
             parsed.copilot = true;
         else if (a === "--cursor")
             parsed.cursor = true;
+        else if (a === "--global")
+            parsed.global = true;
         else if (a === "--root") {
             parsed.root = readValue(args, i, a);
+            rootProvided = true;
             i++;
         }
         else if (a === "--files") {
@@ -187,6 +193,9 @@ function parseArgs(args) {
     }
     if (!parsed.root)
         throw new Error("--root requires a directory");
+    if (parsed.global && (rootProvided || parsed.files || parsed.copilot || parsed.cursor)) {
+        throw new Error("--global cannot be combined with --root/--files/--copilot/--cursor");
+    }
     return parsed;
 }
 function isSelfRepo(root) {
@@ -198,6 +207,13 @@ function isSelfRepo(root) {
         return false;
     }
 }
+export function globalTargetFiles(home = os.homedir()) {
+    return [
+        join(home, ".claude", "CLAUDE.md"),
+        join(home, ".codex", "AGENTS.md"),
+        join(home, ".gemini", "GEMINI.md"),
+    ];
+}
 function targetFiles(root, opts) {
     const resolveTarget = (f) => {
         const target = isAbsolute(f) ? resolve(f) : resolve(root, f);
@@ -225,19 +241,24 @@ export async function runInit(args = process.argv.slice(3)) {
         console.error(e instanceof Error ? e.message : String(e));
         return 1;
     }
-    const root = resolve(opts.root);
-    if (isSelfRepo(root) && !opts.force) {
-        console.error("Refusing to run init inside the subagent-mcp source repo without --force.");
-        console.error("This repo keeps CLAUDE.md/GEMINI.md as thin redirects; use --root for a consumer repo.");
-        return 1;
-    }
     let files;
-    try {
-        files = targetFiles(root, opts);
+    if (opts.global) {
+        files = globalTargetFiles();
     }
-    catch (e) {
-        console.error(e instanceof Error ? e.message : String(e));
-        return 1;
+    else {
+        const root = resolve(opts.root);
+        if (isSelfRepo(root) && !opts.force) {
+            console.error("Refusing to run init inside the subagent-mcp source repo without --force.");
+            console.error("This repo keeps CLAUDE.md/GEMINI.md as thin redirects; use --root for a consumer repo.");
+            return 1;
+        }
+        try {
+            files = targetFiles(root, opts);
+        }
+        catch (e) {
+            console.error(e instanceof Error ? e.message : String(e));
+            return 1;
+        }
     }
     const issues = [];
     const results = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.8.8",
+  "version": "2.9.0",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "type": "module",
   "main": "dist/index.js",
@@ -22,7 +22,7 @@
     "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/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/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/init-migration.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 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"
+    "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/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/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 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",