npm - @heretyc/subagent-mcp - Versions diffs - 2.9.0 → 2.10.0 - Mend

@heretyc/subagent-mcp 2.9.0 → 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md +121 -57
package/directives/carryover-claude.md +2 -2
package/directives/carryover-codex.md +2 -4
package/dist/concurrency.js +96 -0
package/dist/config-scaffold.js +2 -0
package/dist/global-concurrency.jsonc +29 -0
package/dist/index.js +159 -69
package/dist/init.js +1 -1
package/dist/orchestration/hook-core.js +3 -1
package/dist/orchestration/marker.js +99 -26
package/dist/routing.js +10 -11
package/dist/setup.js +1 -0
package/package.json +18 -3

package/README.md CHANGED Viewed

@@ -1,70 +1,115 @@
 # subagent-mcp
-MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions. Runs on **macOS, Linux, and Windows**.
+[![npm version](https://img.shields.io/npm/v/@heretyc/subagent-mcp?label=npm)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
+[![license](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![node](https://img.shields.io/node/v/@heretyc/subagent-mcp)](https://www.npmjs.com/package/@heretyc/subagent-mcp)
+[![CI](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml/badge.svg)](https://github.com/Heretyc/subagent-mcp/actions/workflows/claude-routine.yml)
-**No direct API calls.** subagent-mcp does NOT use the Anthropic or OpenAI HTTP APIs and has no plans to. Claude sessions use the Claude Agent SDK against your local Claude Code executable; Codex sessions use your local `codex app-server`. No API keys.
-**License:** Apache-2.0 | **Author:** Lexi Blackburn | **Repo:** https://github.com/Heretyc/subagent-mcp
+MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions — on macOS, Linux, and Windows. No direct API calls. No API keys.
 ---
-## Features
+## Install
-- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
-- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
-- Concurrency caps: 5 concurrent Claude agents + 5 concurrent Codex agents (counts only actively-streaming `processing` agents, to limit API rate-limit pressure; quiet `stalled` agents don't reserve a slot)
-- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet -- thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
-- Ultracode mode for Opus 4.8 -- headless activation via `--settings {"ultracode":true}` (see [docs/usage.md](docs/usage.md))
-- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
-- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
-- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate (Desktop hosts toggle but do not inject); see [docs/spec/orchestration-mode/_INDEX.md](docs/spec/orchestration-mode/_INDEX.md)
+### Prerequisites (runtime)
----
+To run the published CLI you need:
-## Quick Start
+- Node.js >= 18  (`node --version`)
+- `claude` CLI — globally installed and authenticated  (`claude --version`)
+- `codex` CLI — globally installed and authenticated  (`codex --version`; optional if you only use Claude paths)
-**Prerequisites:** Node.js >= 18, plus the `claude` and/or `codex` CLIs installed globally and authenticated.
+Building from source needs additional developer tooling — see [CONTRIBUTING.md § Prerequisites](CONTRIBUTING.md#prerequisites).
-Installed via [GitHub Packages](https://github.com/Heretyc/subagent-mcp/pkgs/npm/subagent-mcp). One-time `.npmrc` setup required (GitHub Packages requires auth even for public packages):
+### npmjs (default)
+No authentication, no `.npmrc` configuration, and no PAT required. The package is publicly available on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
 ```bash
-# 1. Configure registry for @heretyc scope (once per machine)
-echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
+npm install -g @heretyc/subagent-mcp
+```
-# 2. Authenticate — use a classic PAT with read:packages scope
+**Use this path for all standard installs.**
+### GitHub Packages (org-internal pin / supply-chain auditing)
+Use this path when your organization's `.npmrc` already routes the `@heretyc` scope through GitHub Packages, when you need supply-chain audit tracing against the org-internal artifact, or when you run inside a GitHub Actions workflow whose `GITHUB_TOKEN` carries `read:packages`. Otherwise prefer npmjs above — it is simpler and needs no credentials.
+```bash
+# One-time machine setup
+echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
 echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
+# PAT must be a classic PAT with the read:packages scope
-# 3. Install and wire
 npm install -g @heretyc/subagent-mcp
+```
+> **Note:** GitHub Packages requires authentication even for public packages. If you see `401 Unauthorized`, verify your PAT has the `read:packages` scope and has not expired. GitHub Packages does not render a README page — the live documentation appears on [npmjs.com](https://www.npmjs.com/package/@heretyc/subagent-mcp).
+---
+## Quick Start
+**1. Install** (see [Install](#install) above):
+```bash
+npm install -g @heretyc/subagent-mcp
+```
+**2. Register the MCP server + orchestration hooks:**
+```bash
 subagent-mcp setup
 ```
-`setup` detects which vendors are present, registers the MCP server, and writes orchestration-mode hooks. Idempotent — safe to re-run after updates. Pass `--dry-run` to preview.
+Installing the package only ships the binary — it does **not** auto-wire anything. `subagent-mcp setup` auto-detects Claude Code / Codex and registers the MCP server plus the per-turn orchestration-mode hooks. Preview with `subagent-mcp setup --dry-run`.
-For consumer projects, run `subagent-mcp init --root /path/to/project` to upsert
-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.
+**3. Restart your host.**
-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).
+Restart your Claude Code or Codex session so it picks up the new binary. On Codex, run `/hooks` and trust the new hook.
-After setup, restart your Claude Code or Codex session. On Codex, run `/hooks` and trust the new hook.
+**4. Initialize the orchestration invariant (recommended):**
-**Updating:** `subagent-mcp update && subagent-mcp setup`
+```bash
+subagent-mcp init --global
+```
+`init --global` writes the managed invariant block into the providers' official global user-config files — `~/.claude/CLAUDE.md`, `~/.codex/AGENTS.md`, `~/.gemini/GEMINI.md` — set up once, works across every project. For a single project instead, use `subagent-mcp init --root /path/to/project` to write into that project's instruction files. `--global` and `--root` are mutually exclusive.
+For manual wiring, Gemini CLI, Claude Desktop, and developer install from source, see [docs/registration.md](docs/registration.md).
+---
+## Features
+- Start Claude or Codex interactive sessions as managed sub-agents from any MCP host
+- Poll status, stream stdout/stderr tails, and enqueue follow-up messages to live sessions
+- Concurrency caps: 5 concurrent Claude + 5 concurrent Codex agents (only `processing` agents count toward the cap; `stalled` agents do not hold a slot)
+- Liveness tracking via the visible provider stream (Claude SDK events, Codex app-server JSONL): agents with no parsed visible provider stream item for 10 minutes enter `stalled` state (still alive, just quiet — thinking or awaiting a temp-file handoff), and recover to `processing` if the visible stream resumes
+- Ultracode mode for Opus 4.8 via `--settings {"ultracode":true}` — see [docs/usage.md](docs/usage.md)
+- Cross-platform exe resolution (Windows: npm-prefix .exe paths; macOS/Linux: PATH + Homebrew/usr-local fallbacks); immediate `taskkill /t /f` (Windows) / `SIGKILL` (POSIX) force-kill; no graceful shutdown period
+- stdio MCP transport; built with `@modelcontextprotocol/sdk` + `zod`
+- `orchestration-mode` tool — toggles orchestrator directives injected by bundled Claude Code / Codex hooks; Claude also gets a deterministic `PreToolUse` gate
+---
-For manual wiring, developer install from source, Gemini CLI, and Claude Desktop, see [docs/registration.md](docs/registration.md).
+## Orchestration Mode
+**ON:** the agent operates as an orchestrator — hook injection governs each session turn, preventing inline reads or writes, and all work is delegated through sub-agent tools.
+**OFF:** the agent operates normally, with no orchestration constraints.
+Toggle with the `orchestration-mode` tool. Desktop hosts toggle the mode but receive no hook injection. See [docs/spec/dev-loop/orchestration-directive-architecture.md](docs/spec/dev-loop/orchestration-directive-architecture.md) for full semantics.
 ---
 ## Auto Mode
+Pass `task_category` to `launch_agent` and the server picks the best provider, model, and effort for that category, with automatic fallback.
 `launch_agent` supports **auto mode**: pass `prompt` + `task_category` and the server picks the best provider/model/effort for that category from its routing table, silently falling back to the next-best candidate on any launch-time failure.
-`provider`, `model`, and `effort` are optional overrides — omit them to get auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
+`provider`, `model`, and `effort` are optional overrides — omit them to get the auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
 **task_category** (required) — pick one:
@@ -92,20 +137,36 @@ The last four are **composite-inferred**: they carry no dedicated benchmark and
 ---
+## Configuration
+### Global concurrent-subagent cap
+subagent-mcp enforces a machine-global cap on the number of **live concurrent subagents** across all agentic sessions and MCP server processes on the machine. The count includes agents started by other active sessions and the whole recursive descendant tree; slots free as agents finish or are killed.
+The cap is configured in `global-concurrency.jsonc`, a dedicated dist-sibling file in the install directory. It is separate from the advanced routing directives file, ships as a commented template, and is retained across installs and updates by the same preserve-user-edits mechanism as the advanced routing directives.
+Set `globalConcurrentSubagents` in that file. The default is `20`; the minimum valid value is `10`. Validation is forced: `0`, unset, missing, or invalid values reset to `20`, and values `1` through `9` are pinned up to `10`. There is no environment-variable override; the file is the sole source of truth. The file is re-read on every `launch_agent` call, so edits take effect on the next launch with no server restart.
+When the cap is reached, `launch_agent` is rejected immediately; it never queues. Because the count includes other active sessions and the entire descendant tree, free slots manually with `list_agents` and `kill_agent` before retrying. There is no automatic cleanup or zombie reaping.
+---
 ## Tools
-Six tools are exposed over the stdio MCP transport:
+Eight tools are exposed over the stdio MCP transport.
-| Tool | Purpose |
-|------|---------|
-| `launch_agent` | Start a new `claude`/`codex` sub-agent session |
-| `poll_agent` | Get status + output tail of one agent |
-| `kill_agent` | Immediately force-kill any live agent |
-| `send_message` | Enqueue a user message on a live session |
-| `list_agents` | List all agents with token-efficient core metrics |
-| `wait` | Block until one or more agents finish, or 15-minute timeout |
+| Tool | Description |
+|---|---|
+| `launch_agent` | Start a new sub-agent session with a prompt and optional task category / overrides |
+| `poll_agent` | Check status and stream tail output for a running agent |
+| `kill_agent` | Terminate a running or stalled agent |
+| `send_message` | Enqueue a message into a running agent's stdin |
+| `list_agents` | List all tracked agents and their current status |
+| `wait` | Block until a specific agent reaches a terminal state |
+| `orchestration-mode` | Toggle orchestration-mode ON/OFF; controls whether hook directives are injected into agent sessions |
+| `model-selection-mode` | Control model selection: `smart` (auto-pick) or `user-approved-overrides` (30-min override window) |
-Full parameters, return shapes, the `alive` / `idle_seconds` / `hint` / `recent_stream` fields, and `poll_agent`'s last-3 visible-stream items are in [docs/tools.md](docs/tools.md).
+Full parameters, return shapes, and the `alive` / `idle_seconds` / `hint` / `recent_stream` fields are in [docs/tools.md](docs/tools.md).
 ---
@@ -114,30 +175,33 @@ Full parameters, return shapes, the `alive` / `idle_seconds` / `hint` / `recent_
 Each agent transitions through these states:
 | Status | Meaning |
-|--------|---------|
-| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes -- actively working. Launch time counts as the initial heartbeat |
-| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes -- working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
+|---|---|
+| `processing` | Driver alive with a visible provider-stream heartbeat in the last 10 minutes — actively working. Launch time counts as the initial heartbeat |
+| `stalled` | Driver STILL ALIVE but no parsed visible provider stream item for >= 10 minutes — working, thinking, or awaiting a temp-file handoff (not a failure). Recovers to `processing` if the visible stream resumes |
 | `finished` | Current turn completed, or driver exited with code 0 |
 | `errored` | Process exited with non-zero code |
 | `stopped` | Terminated by `kill_agent` |
-`processing` and `stalled` are live. `finished` is reportable for `wait`; if `alive` is still true, `send_message` can start the next turn on the same session. A health monitor runs every 10 seconds, and `poll_agent`/`list_agents` additionally reconcile driver exit synchronously. `wait` does not return just because an agent is `stalled`. `stalled` agents recover to `processing` if the visible stream resumes and are never auto-killed -- prefer `wait`/re-poll over `kill_agent`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
+`processing` and `stalled` are live. `stalled` means the driver is alive but quiet (>= 10 min no visible stream); it recovers automatically and is never auto-killed — do not `kill_agent` a stalled agent. `wait` does not return on `stalled`. Full semantics: [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md).
 ---
 ## Documentation
-- [docs/registration.md](docs/registration.md) -- per-platform registration (Claude Code, Codex, Gemini), prerequisites, install, config paths.
-- [docs/tools.md](docs/tools.md) -- full Tool Reference for all six tools, including `alive` / `idle_seconds` / `hint` fields.
-- [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**).
+| Document | Contents |
+|---|---|
+| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop; manual wiring; developer install from source |
+| [docs/tools.md](docs/tools.md) | Full tool reference — all eight tools, parameters, return shapes |
+| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, 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 |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contributor guide — dev environment, build, test, publish |
 ---
 ## License
-Apache-2.0 -- Copyright 2026 Lexi Blackburn
+Apache-2.0 — Copyright 2026 Lexi Blackburn
-See [docs/SPEC.md](docs/SPEC.md) for the full technical specification.
+See [LICENSE](LICENSE).

package/directives/carryover-claude.md CHANGED Viewed

@@ -2,9 +2,9 @@
 <subagent-mcp state="on" kind="carryover">
 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.
-Orchestration ON carried over from a PRIOR session for this project (persists until disabled with user permission). Not enabled THIS session.
+Orchestration ON carried over from a PRIOR session for this project (per-session disable; next session resumes ON, or after a 2h backstop). Not enabled THIS session.
-THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to keep it ON; (3) ADVISE fit — long-horizon / context-filling → keep ON; bounded / interactive → propose OFF. Decline → orchestration-mode enabled:false. NEVER disable on your own initiative. After the answer the handshake is done; do not re-raise.
+THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via AskUserQuestion whether to REMAIN enabled; (3) ADVISE fit — long-horizon → remain enabled; bounded/interactive → disable this session. Decline → orchestration-mode enabled:false this session only; no mid-session re-enable. NEVER disable on your own initiative. After answer handshake done; do not re-raise.
 While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
 </subagent-mcp>

package/directives/carryover-codex.md CHANGED Viewed

@@ -2,9 +2,7 @@
 <subagent-mcp state="on" kind="carryover">
 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.
-Orchestration ON carried over from a PRIOR session for this project (persists until disabled with user permission). Not enabled THIS session.
+Orchestration ON carried over from a PRIOR session for this project (per-session disable only; the next new session resumes ON automatically or after a 2h backstop). Not enabled THIS session.
-THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to keep it ON; (3) ADVISE fit — long-horizon / context-filling → keep ON; bounded / interactive → propose OFF. Decline → orchestration-mode enabled:false. NEVER disable on your own initiative. After the answer the handshake is done; do not re-raise.
-While ON, follow the MOST RECENT <subagent-mcp state="on"> tag in context (directive or reminder/carrier); if none is in the current window, the CLAUDE/AGENTS/GEMINI INIT_BLOCK governs. This tag is co-supreme with safety-scope; conflict → ask the user.
+THIS turn, ONCE: (1) NOTIFY the user it carried over; (2) ASK via request-user-input whether to REMAIN enabled; (3) ADVISE fit — long-horizon / context-filling → remain enabled; bounded / interactive → propose OFF. Decline → orchestration-mode enabled:false for this session only; no mid-session re-enable. NEVER disable on your own initiative. After the answer the handshake is done; do not re-raise.
 </subagent-mcp>

package/dist/concurrency.js ADDED Viewed

@@ -0,0 +1,96 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import { platform } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONCURRENCY_SCAFFOLD } from "./config-scaffold.js";
+export const DEFAULT_CAP = 20;
+export const MIN_CAP = 10;
+export const CONFIG_FILENAME = "global-concurrency.jsonc";
+export function clampCap(raw) {
+    if (!Number.isInteger(raw))
+        return DEFAULT_CAP;
+    const v = raw;
+    if (v <= 0)
+        return DEFAULT_CAP;
+    if (v < MIN_CAP)
+        return MIN_CAP;
+    return v;
+}
+export function stripJsoncComments(text) {
+    return text.replace(/^\s*\/\/.*$/gm, "");
+}
+export function parseConcurrencyConfig(text) {
+    let raw;
+    try {
+        raw = JSON.parse(stripJsoncComments(text))?.globalConcurrentSubagents;
+    }
+    catch {
+        raw = undefined;
+    }
+    return clampCap(raw);
+}
+export function defaultConfigPath() {
+    return fileURLToPath(new URL("./" + CONFIG_FILENAME, import.meta.url));
+}
+export function ensureConcurrencyConfig(path = defaultConfigPath()) {
+    try {
+        if (existsSync(path))
+            return;
+        writeFileSync(path, CONCURRENCY_SCAFFOLD);
+    }
+    catch { }
+}
+export function readGlobalCap(path = defaultConfigPath()) {
+    try {
+        ensureConcurrencyConfig(path);
+        return parseConcurrencyConfig(readFileSync(path, "utf8"));
+    }
+    catch {
+        return DEFAULT_CAP;
+    }
+}
+export function slotDir() {
+    if (platform() === "win32") {
+        return join(process.env.ProgramData || process.env.ALLUSERSPROFILE || "C:\\ProgramData", "subagent-mcp", "slots");
+    }
+    return "/tmp/subagent-mcp/slots";
+}
+export function countSlots(dir = slotDir()) {
+    try {
+        return readdirSync(dir).filter((f) => f.startsWith("slot-")).length;
+    }
+    catch {
+        return 0;
+    }
+}
+export function reserveSlot(agentId, max, dir = slotDir()) {
+    try {
+        mkdirSync(dir, { recursive: true, mode: 0o1777 });
+        const slotPath = join(dir, `slot-${agentId}.json`);
+        writeFileSync(slotPath, JSON.stringify({ pid: process.pid, cwd: process.cwd(), startedAt: new Date().toISOString() }), { mode: 0o600 });
+        const n = countSlots(dir);
+        if (n > max) {
+            try {
+                unlinkSync(slotPath);
+            }
+            catch { }
+            return { ok: false, current: n - 1, max };
+        }
+        return { ok: true, slotPath, current: n, max };
+    }
+    catch (e) {
+        console.error(`[concurrency] reserve failed, failing open: ${e instanceof Error ? e.message : String(e)}`);
+        return { ok: true, current: 0, max, slotPath: null };
+    }
+}
+export function releaseSlot(slotPath) {
+    if (!slotPath)
+        return;
+    try {
+        unlinkSync(slotPath);
+    }
+    catch { }
+}
+export function globalCapMessage(current, max, configPath = defaultConfigPath()) {
+    return `Global concurrent-subagent limit reached: ${current} of ${max} live subagents are already running across all sessions on this machine. This global count includes agents started by OTHER active agentic sessions and the ENTIRE recursive descendant tree, not just this session's direct children. launch_agent was REJECTED — this cap never queues or blocks; no slot frees itself by waiting. Free a slot manually first: call list_agents to see live agents, then kill_agent to terminate ones you no longer need, and retry. The limit is "globalConcurrentSubagents" in ${configPath} (default 20, minimum 10).`;
+}

package/dist/config-scaffold.js ADDED Viewed

	@@ -0,0 +1,2 @@
1	+ // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-concurrency.jsonc — DO NOT EDIT.
2	+ export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\r\n// ------------------------------------------------------------------\r\n// SOLE source of truth for the machine-wide limit on how many subagents\r\n// may be ALIVE AT ONCE across EVERY session, process, and user on this\r\n// machine. There is NO environment-variable override.\r\n//\r\n// The whole recursive descendant tree counts toward this ONE number: a\r\n// subagent that itself launches subagents adds to the same machine-wide\r\n// total, and OTHER active agentic sessions count too.\r\n//\r\n// RE-READ on every launch_agent call — edits take effect immediately, no\r\n// server restart required.\r\n//\r\n// Value rules (forcibly applied to the number below):\r\n// - missing / unset / non-integer / 0 / negative -> reset to default 20\r\n// - 1 through 9 -> forced UP to minimum 10\r\n// - 10 or greater -> used as-is\r\n//\r\n// When the cap is reached, launch_agent is REJECTED (never queued). Free a\r\n// slot with list_agents + kill_agent, then retry.\r\n//\r\n// Slots free automatically as agents finish or are killed. There is NO\r\n// zombie reaping. If a server process CRASHES, its slots stay counted until\r\n// you delete the stale slot files by hand:\r\n// Windows: %ProgramData%\\subagent-mcp\\slots\r\n// macOS/Linux: /tmp/subagent-mcp/slots\r\n{\r\n \"globalConcurrentSubagents\": 20\r\n}\r\n";

package/dist/global-concurrency.jsonc ADDED Viewed

@@ -0,0 +1,29 @@
+// subagent-mcp — Global Concurrent Subagent Cap
+// ------------------------------------------------------------------
+// SOLE source of truth for the machine-wide limit on how many subagents
+// may be ALIVE AT ONCE across EVERY session, process, and user on this
+// machine. There is NO environment-variable override.
+//
+// The whole recursive descendant tree counts toward this ONE number: a
+// subagent that itself launches subagents adds to the same machine-wide
+// total, and OTHER active agentic sessions count too.
+//
+// RE-READ on every launch_agent call — edits take effect immediately, no
+// server restart required.
+//
+// Value rules (forcibly applied to the number below):
+//   - missing / unset / non-integer / 0 / negative  -> reset to default 20
+//   - 1 through 9                                    -> forced UP to minimum 10
+//   - 10 or greater                                 -> used as-is
+//
+// When the cap is reached, launch_agent is REJECTED (never queued). Free a
+// slot with list_agents + kill_agent, then retry.
+//
+// Slots free automatically as agents finish or are killed. There is NO
+// zombie reaping. If a server process CRASHES, its slots stay counted until
+// you delete the stale slot files by hand:
+//   Windows:      %ProgramData%\subagent-mcp\slots
+//   macOS/Linux:  /tmp/subagent-mcp/slots
+{
+  "globalConcurrentSubagents": 20
+}

package/dist/index.js CHANGED Viewed

@@ -18,6 +18,7 @@ import { consumeStreamChunk, flushStream, isTurnCompletedLine, retainLastN, } fr
 import { loadRoutingTable, buildCandidates, validatePresence, TASK_CATEGORIES, AUTO_HINT, SPLIT_HINT, } from "./routing.js";
 import { createDeadlockWindow } from "./deadlock.js";
 import { createRulesetGate, RULESET_HARD_FAIL_MSG, } from "./ruleset.js";
+import { CONFIG_FILENAME, defaultConfigPath, globalCapMessage, readGlobalCap, releaseSlot, reserveSlot, } from "./concurrency.js";
 import * as orchestrationMarker from "./orchestration/marker.js";
 import * as modelMode from "./orchestration/model-mode.js";
 import { startLivenessHeartbeat } from "./orchestration/liveness.js";
@@ -139,11 +140,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), 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 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 remain enabled; 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.9.0",
+    version: "2.10.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"
@@ -359,6 +360,8 @@ async function tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rule
         }
         // Always clean up ultracode settings file on close
         cleanupUcSettings(agentState);
+        releaseSlot(agentState.slotPath ?? null);
+        agentState.slotPath = null;
         // Always record actual close time (unless already finalized)
         if (agentState.exitedAt === null)
             agentState.exitedAt = Date.now();
@@ -599,69 +602,94 @@ server.tool("launch_agent", "Spawn a sub-agent session. AUTO MODE (mandatory fir
     }
     // 6. Attempt loop: best→worst. Register on first successful driver start; silently
     //    advance on launch-time failure. Sub-agent task outcome is NEVER a trigger.
+    const cap = readGlobalCap();
+    const reservationId = randomUUID();
+    const reservation = reserveSlot(reservationId, cap);
+    if (!reservation.ok) {
+        return errorResult(globalCapMessage(reservation.current, cap, defaultConfigPath()));
+    }
     const skipped = [];
-    for (const candidate of candidates) {
-        const outcome = await tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetApplied && rulesetOriginalSelection !== undefined
-            ? { applied: true, originalSelection: rulesetOriginalSelection }
-            : undefined);
-        if ("agentId" in outcome) {
-            if (branch === "performance") {
-                deadlockWindow.consume();
-            }
-            if (skipped.length > 0) {
+    let launched = false;
+    try {
+        for (const candidate of candidates) {
+            const outcome = await tryLaunchCandidate(candidate, prompt, agentCwd, routingTier, rulesetApplied && rulesetOriginalSelection !== undefined
+                ? { applied: true, originalSelection: rulesetOriginalSelection }
+                : undefined);
+            if ("agentId" in outcome) {
+                if (branch === "performance") {
+                    deadlockWindow.consume();
+                }
                 const registeredAgent = agents.get(outcome.agentId);
                 if (registeredAgent) {
-                    registeredAgent.failoverFrom = skipped.map((s) => ({
-                        provider: s.provider,
-                        model: s.model,
-                        effort: s.effort,
-                        failure_type: s.failure_type,
-                    }));
+                    registeredAgent.slotPath = reservation.slotPath;
+                    // The child can reach a terminal state DURING tryLaunchCandidate's
+                    // awaits — before slotPath was set — so its close handler ran
+                    // releaseSlot(undefined) (a no-op) and left the slot leaked. Detect
+                    // that here and release now. slotPath is unique per reservation, so
+                    // this never frees another agent's slot.
+                    if (registeredAgent.exitCode !== null) {
+                        releaseSlot(registeredAgent.slotPath);
+                        registeredAgent.slotPath = null;
+                    }
+                    if (skipped.length > 0) {
+                        registeredAgent.failoverFrom = skipped.map((s) => ({
+                            provider: s.provider,
+                            model: s.model,
+                            effort: s.effort,
+                            failure_type: s.failure_type,
+                        }));
+                    }
                 }
+                launched = true;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                agent_id: outcome.agentId,
+                                status: "processing",
+                                provider: candidate.provider,
+                                model: candidate.model,
+                                effort: candidate.effort,
+                                task_category,
+                                ...(rulesetApplied
+                                    ? {
+                                        ruleset_applied: true,
+                                        ruleset_original_selection: rulesetOriginalSelection,
+                                    }
+                                    : {}),
+                                ...(skipped.length > 0
+                                    ? {
+                                        failover_occurred: true,
+                                        failover_from: skipped.map((s) => ({
+                                            provider: s.provider,
+                                            model: s.model,
+                                            effort: s.effort,
+                                            failure_type: s.failure_type,
+                                        })),
+                                        failover_note: buildFailoverNote(skipped, candidate),
+                                    }
+                                    : {}),
+                            }),
+                        },
+                    ],
+                };
+            }
+            skipped.push({
+                model: candidate.model,
+                effort: candidate.effort,
+                provider: candidate.provider,
+                reason: outcome.reason,
+                failure_type: outcome.failure_type,
+            });
+            if (!pureAuto) {
+                break;
             }
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({
-                            agent_id: outcome.agentId,
-                            status: "processing",
-                            provider: candidate.provider,
-                            model: candidate.model,
-                            effort: candidate.effort,
-                            task_category,
-                            ...(rulesetApplied
-                                ? {
-                                    ruleset_applied: true,
-                                    ruleset_original_selection: rulesetOriginalSelection,
-                                }
-                                : {}),
-                            ...(skipped.length > 0
-                                ? {
-                                    failover_occurred: true,
-                                    failover_from: skipped.map((s) => ({
-                                        provider: s.provider,
-                                        model: s.model,
-                                        effort: s.effort,
-                                        failure_type: s.failure_type,
-                                    })),
-                                    failover_note: buildFailoverNote(skipped, candidate),
-                                }
-                                : {}),
-                        }),
-                    },
-                ],
-            };
         }
-        skipped.push({
-            model: candidate.model,
-            effort: candidate.effort,
-            provider: candidate.provider,
-            reason: outcome.reason,
-            failure_type: outcome.failure_type,
-        });
-        if (!pureAuto) {
-            break;
+    }
+    finally {
+        if (!launched) {
+            releaseSlot(reservation.slotPath);
         }
     }
     // 7. All candidates failed. Override selector modes are single-attempt hard
@@ -790,6 +818,8 @@ server.tool("kill_agent", "Terminate a live agent/session (status `processing`,
         // POSIX, SIGKILL the process (close handler records the real exit code).
         agent.status = "stopped";
         agent.driver.kill();
+        releaseSlot(agent.slotPath ?? null);
+        agent.slotPath = null;
         if (isWindows && agent.process.pid) {
             spawn("taskkill", ["/pid", String(agent.process.pid), "/t", "/f"], {
                 windowsHide: true,
@@ -1004,24 +1034,52 @@ 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 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).", {
+server.tool("orchestration-mode", "Toggle or query per-project ORCHESTRATION MODE. `enabled`: true = ON, false = OFF for THIS session only, 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 remain enabled (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 default-ON orchestration mode 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: orchestration is DEFAULT ON; a permitted disable applies to THIS session only, resumes ON next new session (or after the 2h backstop), and cannot be re-enabled mid-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();
+    const key = orchestrationMarker.readCurrentSession(cwd);
     if (params.enabled === true) {
-        orchestrationMarker.enable(cwd);
+        if (!orchestrationMarker.isActive(cwd, key)) {
+            return errorResult("orchestration already disabled for this session, cannot re-enable mid-session; resumes ON automatically next new session (or after the 2h backstop).");
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        orchestration_mode: "ON",
+                        message: "orchestration is ON by default.",
+                    }),
+                },
+            ],
+        };
     }
     else if (params.enabled === false) {
-        orchestrationMarker.disable(cwd);
+        if (key)
+            orchestrationMarker.writeDisable(key);
+        else
+            orchestrationMarker.writeDisableCwd(cwd);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        orchestration_mode: "disabled-this-session",
+                        message: "orchestration disabled for THIS session only; the next new session resumes ON automatically (or after the 2h backstop); no mid-session re-enable.",
+                    }),
+                },
+            ],
+        };
     }
     // enabled === undefined -> query only; no marker mutation.
+    const active = orchestrationMarker.isActive(cwd, key);
     return {
         content: [
             {
                 type: "text",
                 text: JSON.stringify({
-                    orchestration_mode: orchestrationMarker.isActive(cwd),
-                    marker_path: orchestrationMarker.markerPath(cwd),
+                    orchestration_mode: active ? "ON" : "disabled-this-session",
                 }),
             },
         ],
@@ -1126,7 +1184,9 @@ if (isMain) {
         }
         const installRoot = join(npmRoot.stdout.toString().trim(), ...pkg.name.split("/"));
         const rulesetPath = join(installRoot, "dist", "advanced-ruleset.py");
+        const cfgPath = join(installRoot, "dist", CONFIG_FILENAME);
         let previousRuleset = null;
+        let previousCfg = null;
         if (existsSync(rulesetPath)) {
             previousRuleset = readFileSync(rulesetPath);
             const backupPath = join(tmpdir(), `advanced-ruleset.py.bak-update-${Date.now()}`);
@@ -1139,6 +1199,18 @@ if (isMain) {
                 process.exit(1);
             }
         }
+        if (existsSync(cfgPath)) {
+            previousCfg = readFileSync(cfgPath);
+            const backupPath = join(tmpdir(), `${CONFIG_FILENAME}.bak-update-${Date.now()}`);
+            try {
+                writeFileSync(backupPath, previousCfg);
+                console.log(`backed up user ${CONFIG_FILENAME} to ${backupPath}`);
+            }
+            catch (e) {
+                console.error(`update refused before install: failed to back up ${CONFIG_FILENAME}: ${e instanceof Error ? e.message : String(e)}`);
+                process.exit(1);
+            }
+        }
         const r = spawnNpm(npmArgs, "inherit");
         if (r.error) {
             console.error(`update failed to start npm: ${r.error.message}`);
@@ -1161,6 +1233,21 @@ if (isMain) {
                     process.exit(1);
                 }
             }
+            if (previousCfg !== null) {
+                try {
+                    const freshCfg = existsSync(cfgPath)
+                        ? readFileSync(cfgPath)
+                        : null;
+                    if (freshCfg === null || !previousCfg.equals(freshCfg)) {
+                        writeFileSync(cfgPath, previousCfg);
+                        console.log(`restored user ${CONFIG_FILENAME} (package update never overwrites user edits)`);
+                    }
+                }
+                catch (e) {
+                    console.error(`update failed to restore ${CONFIG_FILENAME}: ${e instanceof Error ? e.message : String(e)}`);
+                    process.exit(1);
+                }
+            }
             console.log("Update complete. Restart your CLI sessions so the MCP server picks up the new build.");
         }
         process.exit(code);
@@ -1184,11 +1271,14 @@ if (isMain) {
         process.exit(1);
     }
     // ORCHESTRATION MODE PERSISTS across restarts/sessions: the server does NOT
-    // clear the marker on startup. DEFAULT OFF now means ABSENCE of a marker — a
-    // project never enabled stays OFF; a project explicitly enabled persists ON
-    // until disabled with explicit user permission. On a new session the bundled
-    // hook detects the carried-over marker and prompts the user to confirm.
-    // (orchestrationMarker.disable is still used by the tool's enabled:false.)
+    // clear the marker on startup. DEFAULT ON now means ABSENCE of a disable
+    // record — a project stays ON with no marker write needed; OFF is only a
+    // per-session disable record that holds while it is active, cleared with
+    // explicit user permission. On a new session a carried-over legacy ON marker
+    // (if any) triggers a one-time prompt asking whether to remain enabled; under
+    // default-ON this rarely fires.
+    // (the tool's enabled:false writes a disable record via writeDisable /
+    // writeDisableCwd; it does not call disable().)
     startLivenessHeartbeat();
     const transport = new StdioServerTransport();
     await server.connect(transport);

package/dist/init.js CHANGED Viewed

@@ -29,7 +29,7 @@ export const INIT_BLOCK = [
     "",
     'NO-HOOK / UNKNOWN STATE: if no harness-hook injection bearing a <subagent-mcp state="..."> tag is present this session (e.g. Gemini, desktop apps, or any host that fires no hook), the state is UNKNOWN — represented by the ABSENCE of any tag, never by a tag value. Emit this UNKNOWN-STATE WARNING to the user: "subagent-mcp: no hook injection detected — orchestration state unknown; defaulting to ON". Briefly explain WHY: no hook injection detected — cannot verify orchestration state; defaulting to ON to prevent uncontrolled inline execution. Then DEFAULT TO ORCHESTRATION ON (fail-safe). One-time opt-out: if you are not currently running an orchestration workflow, you may explicitly opt out of ON for this session by saying so now; this opt-out does not persist and is not recorded. The sub-agent first-line exemption is the ONLY automatic suppressor of this default.',
     "",
-    "DISABLE: never on your own initiative; you MAY propose OFF on task-fit mismatch via the structured-question tool, and only explicit user approval may call orchestration-mode enabled:false.",
+    "DISABLE: never on your own initiative; you MAY propose OFF on task-fit mismatch via the structured-question tool, and only explicit user approval may set enabled:false — per-session only; the next new session resumes ON; no mid-session re-enable.",
     "<!-- subagent-mcp:managed:end -->",
 ].join("\n");
 function detectEol(s) {

package/dist/orchestration/hook-core.js CHANGED Viewed

@@ -234,7 +234,9 @@ export function runHook(payload, env, adapter) {
         }
         const cwd = payload.cwd || process.cwd();
         const current = sessionKey(payload);
-        if (!marker.isActive(cwd)) {
+        if (current)
+            marker.writeCurrentSession(cwd, current);
+        if (!marker.isActive(cwd, current)) {
             // OFF: no claim machinery — just the per-prompt reminder cadence.
             const r = reminder.advance(cwd, current);
             return cadenceEmit(env, adapter, adapter.reminderOffFile, adapter.shortOffFile, r.count, r.persisted);

package/dist/orchestration/marker.js CHANGED Viewed

@@ -3,6 +3,7 @@ import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync, } from
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
 const markerDir = join(tmpdir(), "subagent-mcp");
+export const ORCH_DISABLE_TTL_MS = 2 * 60 * 60 * 1000; // 2h GC backstop ONLY (independent of model-mode WINDOW_MS)
 /**
  * Shared per-project state dir for ALL hook state files (marker + reminder
  * counter). Exported so sibling state modules key off the SAME location — a
@@ -33,15 +34,27 @@ export function normalizeCwd(cwd) {
     }
     return p;
 }
-export function cwdHash(cwd) {
+function hashKey(key) {
     return createHash("sha256")
-        .update(normalizeCwd(cwd), "utf8")
+        .update(key, "utf8")
         .digest("hex")
         .slice(0, 16);
 }
+export function cwdHash(cwd) {
+    return hashKey(normalizeCwd(cwd));
+}
 export function markerPath(cwd) {
     return join(markerDir, "orch-" + cwdHash(cwd) + ".flag");
 }
+export function disablePath(sessionKey) {
+    return join(stateDir, `orch-disable-${hashKey(sessionKey)}.json`);
+}
+function cwdDisablePath(cwd) {
+    return join(stateDir, `orch-disable-${cwdHash(cwd)}.json`);
+}
+export function sessionPointerPath(cwd) {
+    return join(stateDir, `orch-session-${cwdHash(cwd)}.json`);
+}
 /**
  * Enable orchestration for cwd. ALWAYS overwrites — re-enabling re-baselines by
  * clearing owner_session/baseline_turn back to null so the next hook turn
@@ -62,44 +75,105 @@ export function enable(cwd) {
             carryover_ack: false,
         };
         writeFileSync(markerPath(cwd), JSON.stringify(state), { encoding: "utf8", mode: 0o600 });
+        try {
+            unlinkSync(cwdDisablePath(cwd));
+        }
+        catch (e) {
+            if (e?.code !== "ENOENT") {
+                // Fail-safe: enable still succeeds if stale disable cleanup fails.
+            }
+        }
     }
     catch {
         // Fail-safe: never throw to the caller.
     }
 }
 /**
- * Disable orchestration for cwd by removing the marker.
- *
- * No existsSync() guard: that only opens a TOCTOU window where a concurrent
- * clearForCwd/disable for the same cwd removes the file between the check and
- * the unlink. We just unlink and swallow ENOENT (already-gone is success).
- *
- * KNOWN LIMITATION: the marker is keyed by cwd, NOT by session. Two CLI
- * sessions in the same project share one marker, so their enable/disable
- * interleave and the last writer wins. Per-session isolation would require
- * keying the marker by cwd+session_id; not done here because LOCKED DECISION 1
- * keys the marker by working directory alone. (The hook tracks the owning
- * session via owner_session so a carried-over marker is re-claimed, but the
- * marker file itself is still shared per cwd.)
+ * Disable orchestration for cwd using cwd-keyed shared fallback state. The
+ * hook's session-keyed path uses writeDisable(sessionKey) instead.
  */
 export function disable(cwd) {
     try {
-        unlinkSync(markerPath(cwd));
+        mkdirSync(markerDir, { recursive: true, mode: 0o700 });
+        writeFileSync(cwdDisablePath(cwd), JSON.stringify({ disabled_at: Date.now() }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
     }
-    catch (e) {
-        if (e?.code !== "ENOENT") {
-            // Any non-ENOENT failure is still swallowed (fail-safe); ENOENT means the
-            // marker was already gone, which is the desired end state anyway.
-        }
+    catch {
+        // Fail-safe: never throw to the caller.
+    }
+}
+export function writeDisable(sessionKey) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(disablePath(sessionKey), JSON.stringify({ disabled_at: Date.now() }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Fail-safe: never throw to the caller.
     }
 }
-export function isActive(cwd) {
+export function writeDisableCwd(cwd) {
     try {
-        return existsSync(markerPath(cwd));
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(cwdDisablePath(cwd), JSON.stringify({ disabled_at: Date.now() }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
     }
     catch {
+        // Fail-safe: never throw to the caller.
+    }
+}
+export function writeCurrentSession(cwd, sessionKey) {
+    try {
+        mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(sessionPointerPath(cwd), JSON.stringify({ session_key: sessionKey }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        // Fail-safe: never throw to the caller.
+    }
+}
+export function readCurrentSession(cwd) {
+    try {
+        const raw = readFileSync(sessionPointerPath(cwd), "utf8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.session_key === "string" ? parsed.session_key : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isDisableActive(path, now) {
+    if (!existsSync(path)) {
         return false;
     }
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.disabled_at !== "number") {
+        return false;
+    }
+    if (now - parsed.disabled_at <= ORCH_DISABLE_TTL_MS) {
+        return true;
+    }
+    // Lazy GC side-effect: the disable has expired, so remove it.
+    unlinkSync(path);
+    return false;
+}
+export function isActive(cwd, sessionKey) {
+    try {
+        const path = sessionKey === undefined ? cwdDisablePath(cwd) : disablePath(sessionKey);
+        return !isDisableActive(path, Date.now());
+    }
+    catch {
+        return true;
+    }
 }
 export function readMarker(cwd) {
     try {
@@ -136,9 +210,8 @@ export function writeMarker(cwd, obj) {
     }
 }
 /**
- * Marker removal alias, identical to disable. RETAINED for callers that clear a
- * marker explicitly (e.g. the tool's enabled:false path). NOTE: the server no
- * longer calls this on startup — orchestration mode now PERSISTS across sessions.
+ * Cwd-keyed disable alias, identical to disable. RETAINED for callers that
+ * clear legacy marker state explicitly (e.g. the tool's enabled:false path).
  */
 export function clearForCwd(cwd) {
     disable(cwd);

package/dist/routing.js CHANGED Viewed

@@ -120,10 +120,10 @@ export function normalizeEffort(provider, model, effort) {
  * explicit (provider+model+effort all present): one candidate from the user's
  * triple; the table is NOT read (works with a null table).
  *
- * auto/provider/provider_model: read performance.<task_category> as the pairings
- * array directly (defensive .pairings unwrap), sort by rank asc, map each model
- * to a launch id, normalize effort, and drop non-launchable / unknown-effort
- * pairings. An empty result sets noCandidates:true.
+ * auto/provider/provider_model: read <branch>.<task_category> as the pairings
+ * array directly, sort by rank asc, map each model to a launch id, normalize
+ * effort, and drop non-launchable / unknown-effort pairings. An empty result
+ * sets noCandidates:true.
  */
 export function buildCandidates(table, taskCategory, overrides, branch = DEFAULT_BRANCH) {
     const { provider, model, effort } = overrides;
@@ -188,12 +188,7 @@ function readPairings(table, taskCategory, branch = DEFAULT_BRANCH) {
     const perf = table[branch];
     if (!perf || typeof perf !== "object")
         return [];
-    let raw = perf[taskCategory];
-    // Defensive: tolerate a {pairings:[...]} wrapper even though the contract
-    // says the value IS the array directly.
-    if (raw && !Array.isArray(raw) && typeof raw === "object" && "pairings" in raw) {
-        raw = raw.pairings;
-    }
+    const raw = perf[taskCategory];
     if (!Array.isArray(raw))
         return [];
     const entries = raw.filter((e) => !!e && typeof e === "object" && typeof e.model === "string");
@@ -251,7 +246,11 @@ export function validatePresence(p) {
     if (model && !provider) {
         return `Error: provider is required when model is given. You passed model=${model} without provider. Either also pass provider, or omit both.\n${AUTO_HINT}`;
     }
-    // 5. explicit mode only: provider+model must satisfy the existing match rule.
+    // fallback_default is valid only for fully explicit launches.
+    if (task_category === "fallback_default" && !(provider && model && effort)) {
+        return `Error: fallback_default is a split hint sentinel, not a launchable routing-table category.\n${SPLIT_HINT}\n${AUTO_HINT}`;
+    }
+    // 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}`;

package/dist/setup.js CHANGED Viewed

@@ -227,6 +227,7 @@ export function verifyInstall(root = INSTALL_ROOT) {
     const required = [
         "dist/index.js",
         "dist/advanced-ruleset.py",
+        "dist/global-concurrency.jsonc",
         "dist/hooks/orchestration-claude.js",
         "dist/hooks/orchestration-claude-pretool.js",
         "dist/hooks/orchestration-codex.js",

package/package.json CHANGED Viewed

@@ -1,7 +1,22 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.9.0",
+  "version": "2.10.0",
   "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": {
@@ -22,7 +37,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/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"
+    "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/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",
@@ -47,7 +62,7 @@
     "node": ">=18"
   },
   "publishConfig": {
-    "registry": "https://npm.pkg.github.com",
+    "registry": "https://registry.npmjs.org",
     "access": "public"
   }
 }