@heretyc/subagent-mcp 2.10.4 → 2.12.2

package/README.md

@@ -5,180 +5,156 @@
 [![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)
 
-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.
+Turn any AI coding assistant into a **manager of other AI agents**. subagent-mcp
+lets your Claude Code or Codex session start, watch, message, and stop a whole
+team of AI sub-agents — on macOS, Linux, and Windows. **No direct API calls. No
+API keys.** It drives the `claude` and `codex` command-line tools you already
+signed into.
+
+## What it does
+
+Normally one AI assistant does all the work in one conversation. That
+conversation fills up, slows down, and eventually forgets its early context. As
+of a certain size it "compacts" — summarizing and dropping detail.
+
+subagent-mcp changes the shape of the work. Your assistant becomes an
+**orchestrator**: it hands each task to a fresh sub-agent, watches the results,
+and moves on — without ever doing the reading or writing itself.
+
+## Why it works this way
+
+Four bets drive the whole design. The full reasoning lives in
+[docs/spec/arch-rationale.md](docs/spec/arch-rationale.md); the short version:
+
+- **The effective memory grows geometrically.** Because the orchestrator only
+  ever holds *summaries* of what its sub-agents did — never the raw files — its
+  own memory fills up far more slowly. That means **very long tasks with little
+  or no compaction**.
+- **Mixed providers avoid blind spots.** Using Claude *and* Codex together means
+  one vendor's weak spot or outage doesn't blind or block the whole job — and
+  you're never locked in to a single vendor.
+- **Ruthless token efficiency.** Every hand-off is compressed and every read is
+  kept small, so the system stays fast and cheap even on marathon tasks.
+- **Durable, authoritative reminders.** The operating rules are re-injected every
+  turn through official host hooks, so the assistant doesn't drift off-task or
+  start making things up over a long run.
 
 ## Install
 
-### Prerequisites (runtime)
+### What you need first
 
-To run the published CLI you need:
+- Node.js 18 or newer  (`node --version`)
+- `claude` CLI — installed and signed in  (`claude --version`)
+- `codex` CLI — installed and signed in  (`codex --version`; optional if you
+  only use Claude)
 
-- 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)
+Building from source needs extra developer tools — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
 
-Building from source needs additional developer tooling — see [CONTRIBUTING.md § Prerequisites](CONTRIBUTING.md#prerequisites).
-
-### 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).
+### Install the package
 
 ```bash
 npm install -g @heretyc/subagent-mcp
 ```
 
-**Use this path for all standard installs.**
-
-`subagent-mcp update` always refreshes from npmjs, even on machines whose `.npmrc` routes `@heretyc` packages through GitHub Packages.
+This is the standard install for everyone. (Organizations pinning the package
+through GitHub Packages should see [docs/registration.md](docs/registration.md).)
 
-### 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
-
-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:**
+### Wire it into your assistant
 
 ```bash
 subagent-mcp setup
 ```
 
-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`.
-
-**3. Restart your host.**
+Installing the package only ships the program — it does **not** connect anything
+on its own. `subagent-mcp setup` finds your Claude Code / Codex install and
+registers both the server and the per-turn orchestration hooks. Preview first
+with `subagent-mcp setup --dry-run`.
 
-Restart your Claude Code or Codex session so it picks up the new binary. On Codex, run `/hooks` and trust the new hook.
+### Restart, then turn on the invariant
 
-**4. Initialize the orchestration invariant (recommended):**
+Restart your Claude Code or Codex session so it picks up the new tools. On Codex,
+run `/hooks` and trust the new hook. Then (recommended):
 
 ```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
+This writes a small managed "always delegate" rule block into your global
+assistant config once, so it works across every project. For a single project
+instead, use `subagent-mcp init --root /path/to/project`. Full per-platform
+wiring (Gemini CLI, Claude Desktop, manual setup) is in
+[docs/registration.md](docs/registration.md).
 
-## Orchestration Mode
+## How to operate it
 
-**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.
+### Orchestration mode: ON vs OFF
 
-**OFF:** the agent operates normally, with no orchestration constraints.
+- **ON** — your assistant acts as a pure manager. It never reads or writes files
+  directly; it delegates every step to sub-agents. Best for big, long-running
+  jobs.
+- **OFF** — your assistant works normally, on its own, with no delegation rules.
 
-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.
+Flip it with the `orchestration-mode` tool. (Desktop apps can toggle the mode
+but don't receive the per-turn hook reminders.)
 
-## Auto Mode
+### The 8 tools at a glance
 
-`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 the auto-selected best combination. Rules: passing `model` requires `provider`; passing `effort` requires both `provider` and `model`.
-
-**task_category** (required) — pick one:
-
-| Category | What it is |
+| Tool | What it does |
 |---|---|
-| `math_proof` | deliverable is a proof/derivation/formally-checkable result |
-| `security_review` | security verdict, threat assessment, or demonstrated exploit |
-| `debugging` | verified fix/root-cause; requires an observed failure as precondition |
-| `quality_review` | evaluative verdict on existing artifact (review, A-vs-B, validate-vs-spec) |
-| `architecture` | cross-module design/plan, no code, no execution loop |
-| `agentic_execution` | end-state via act/observe/adapt loop (run/deploy/provision/browse) |
-| `data_analysis` | empirical finding about structured dataset (query, stat, model) |
-| `coding` | bounded runnable code artifact, one-pass (implement, test, refactor) |
-| `knowledge_synthesis` | novel integrated prose over sources (synthesize, summarize, draft) |
-| `mechanical` | deterministic single-pass transform, exact-match checkable (grep, rename, reformat) |
-| `prompt_engineering` | designed/optimized prompt or prompt-system steering an LLM/agent (composite-inferred) |
-| `vulnerability_research` | discovery + PoC of a novel vulnerability (composite-inferred) |
-| `molecular_biology` | reasoned molecular/computational-biology result over sequences, structures, or -omics data (composite-inferred) |
-| `ml_accelerator_design` | hardware/software design for ML acceleration — dataflow, kernel, roofline (composite-inferred) |
-| `fallback_default` | no category matches with confidence; prefer splitting work instead |
-
-The last four are **composite-inferred**: they carry no dedicated benchmark and their routing competency is composed from parent categories rather than measured directly.
-
-**Atomic-split guidance:** if you are unsure which category fits, do NOT submit one large amorphous task. Break the work into smaller atomic steps each mapping to a single category and launch one agent per step.
-
-## 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. Before cap checks, hooks and tool calls run default zombie culling with no config knob: stale slots whose owner server is gone may terminate their managed child process-tree, while live owned slots are heartbeated and preserved; terminal-but-alive agents idle for more than 30 seconds are force-killed. Reports include `zombies`, and `poll_agent` keeps the tail with `zombie_killed` when culling terminates an agent.
-
-## Tools
-
-Eight tools are exposed over the stdio MCP transport.
-
-| 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, and the `alive` / `idle_seconds` / `hint` / `recent_stream` fields are in [docs/tools.md](docs/tools.md).
-
-## Agent Lifecycle
-
-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 |
-| `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. `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).
+| `launch_agent` | Start a sub-agent on a task (just give a prompt + a task category) |
+| `poll_agent` | Check how an agent is doing and read its latest output |
+| `kill_agent` | Stop a running or quiet agent |
+| `send_message` | Send a follow-up message to a live agent |
+| `list_agents` | See every agent and its current status |
+| `wait` | Pause until a specific agent finishes |
+| `orchestration-mode` | Turn manager-mode ON or OFF |
+| `model-selection-mode` | Let the server auto-pick the model, or allow manual overrides |
+
+You never have to choose a model. Give `launch_agent` a plain-English prompt and
+a **task category** (e.g. "coding", "debugging", "security_review") and the
+server picks the best provider, model, and effort for that kind of work.
+
+### How many run at once
+
+There is a single machine-wide limit on how many sub-agents run at the same time
+across everything on your computer. The **default is 20**. When the limit is
+reached, a new `launch_agent` is turned down right away — it does not wait in a
+queue. You change the number in the `global-concurrency.jsonc` file in the
+install folder (minimum 10); the file is re-read on every launch, so no restart
+is needed.
+
+The same settings file includes `checkForUpdates` (default `true`). When a newer
+npm version exists, the per-turn hook can show a throttled notice to run
+`subagent-mcp update` and then `subagent-mcp setup`. Set `checkForUpdates` to
+`false`, or run with `SUBAGENT_UPDATE_CHECK=0` / `false`, to disable that check.
+
+## Basic debugging
+
+- **"An agent looks stuck."** A quiet agent is usually **still alive**, not
+  dead. After ~10 minutes with no output an agent is marked `stalled` — it's
+  thinking or waiting on a hand-off. It recovers on its own. **Do not kill a
+  stalled agent**, and `wait` will not return on one.
+- **"It won't start a new agent (cap reached)."** You've hit the concurrent
+  limit. Use `list_agents` to see what's running and `kill_agent` on anything
+  you no longer need — that frees a slot immediately. Raising the number in
+  `global-concurrency.jsonc` also works.
+- **"Where are the logs?"** Each agent's recent output is available any time via
+  `poll_agent`. The server's own diagnostics go to your host's normal MCP
+  server log (your Claude Code or Codex session logs) — all server logging goes
+  to stderr, never mixed into results.
 
 ## Documentation
 
 | 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/spec/arch-rationale.md](docs/spec/arch-rationale.md) | Why it's built this way — the full design rationale |
+| [docs/registration.md](docs/registration.md) | Per-platform setup: Claude Code, Codex, Gemini CLI, Claude Desktop |
 | [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 |
+| [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, usage examples |
+| [docs/SPEC.md](docs/SPEC.md) | Full technical specification |
+| [docs/reference/status-lifecycle.md](docs/reference/status-lifecycle.md) | Agent status meanings (processing / stalled / finished / errored / stopped) |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Developer guide — build, test, publish, contribution workflow |
 
 ## License
 

package/directives/carryover-codex.md

@@ -2,7 +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 (per-session disable only; the next new session resumes ON automatically or after a 2h backstop). 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 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.
+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 → 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/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 (leading blank lines don't count; 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 + /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.
+Orchestration ON. You are the orchestrator: delegate EVERY step. Allowed tools = ONLY the structured-question tool (AskUserQuestion / request-user-input) + subagent-mcp + /workflows (Claude Code CLI only); 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.
 
 Each launched prompt carries objective + output format + tools/sources + boundaries; scale agent count to complexity; subdivide to the smallest auditable step; verify code steps with an independent sub-agent.
 

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 + /workflows; no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. 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 (Claude Code CLI only); no direct reads/writes; inline-by-right does not exist. Subdivide small; verify code steps; never 1-shot multi-phase. 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/advanced-ruleset.py

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

package/dist/concurrency.js

@@ -6,6 +6,7 @@ import { CONCURRENCY_SCAFFOLD } from "./config-scaffold.js";
 import { cullStaleSlots, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, parseSlotMetadata, readSlotMetadata, slotPathForAgent, writeSlotMetadata, } from "./zombie.js";
 export const DEFAULT_CAP = 20;
 export const MIN_CAP = 10;
+export const DEFAULT_CHECK_FOR_UPDATES = true;
 export const CONFIG_FILENAME = "global-concurrency.jsonc";
 export { cullStaleSlots, ZOMBIE_FORCE_GRACE_MS, ZOMBIE_LIVE_IDLE_MS, ZOMBIE_TERMINAL_IDLE_MS, buildProcessTreeKillCommands, drainZombieIntents, drainZombieReports, parseSlotMetadata, readSlotMetadata, slotPathForAgent, writeSlotMetadata, };
 export function clampCap(raw) {
@@ -31,6 +32,16 @@ export function parseConcurrencyConfig(text) {
     }
     return clampCap(raw);
 }
+export function parseCheckForUpdatesConfig(text) {
+    try {
+        const raw = JSON.parse(stripJsoncComments(text))
+            ?.checkForUpdates;
+        return typeof raw === "boolean" ? raw : DEFAULT_CHECK_FOR_UPDATES;
+    }
+    catch {
+        return DEFAULT_CHECK_FOR_UPDATES;
+    }
+}
 export function defaultConfigPath() {
     return fileURLToPath(new URL("./" + CONFIG_FILENAME, import.meta.url));
 }
@@ -51,6 +62,15 @@ export function readGlobalCap(path = defaultConfigPath()) {
         return DEFAULT_CAP;
     }
 }
+export function readCheckForUpdates(path = defaultConfigPath()) {
+    try {
+        ensureConcurrencyConfig(path);
+        return parseCheckForUpdatesConfig(readFileSync(path, "utf8"));
+    }
+    catch {
+        return DEFAULT_CHECK_FOR_UPDATES;
+    }
+}
 export function slotDir() {
     if (process.env.SUBAGENT_SLOT_DIR)
         return process.env.SUBAGENT_SLOT_DIR;
@@ -79,20 +99,26 @@ export function reserveSlot(agentId, max, dir = slotDir(), cullDeps) {
         mkdirSync(dir, { recursive: true, mode: 0o1777 });
         cullStaleSlots(dir, cullDeps);
         const slotPath = slotPathForAgent(dir, agentId);
+        const before = countSlots(dir);
+        if (before >= max) {
+            return { ok: false, current: before, max };
+        }
+        // ponytail: count->write->recount narrows the TOCTOU; a cross-process lock would close it fully.
         writeSlotMetadata(slotPath, { agent_id: agentId });
-        const n = countSlots(dir);
-        if (n > max) {
+        const after = countSlots(dir);
+        if (after > max) {
             try {
                 unlinkSync(slotPath);
             }
             catch { }
-            return { ok: false, current: n - 1, max };
+            return { ok: false, current: countSlots(dir), max };
         }
-        return { ok: true, slotPath, current: n, max };
+        return { ok: true, slotPath, current: after, 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 };
+        const error = e instanceof Error ? e.message : String(e);
+        console.error(`[concurrency] reserve failed, rejecting launch: ${error}`);
+        return { ok: false, current: -1, max, error };
     }
 }
 export function releaseSlot(slotPath) {

package/dist/config-scaffold.js

@@ -1,2 +1,2 @@
 // GENERATED by scripts/gen-ruleset-scaffold.mjs from src/global-concurrency.jsonc — DO NOT EDIT.
-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// Zombie culling is always enabled. There is no config knob. Before cap\n// rejection, launch/tool/hook paths refresh live owned slots, preserve stale\n// slots whose owner server is still alive, and cull stale slots whose owner is\n// gone. Managed stale slots terminate the child process tree, then force-kill\n// after 20s when needed; unmanaged stale slots are only unlinked.\n//\r\n// When the cap is reached after culling, launch_agent is REJECTED (never\r\n// queued). Free a slot with list_agents + kill_agent, then retry.\r\n{\r\n  \"globalConcurrentSubagents\": 20\r\n}\r\n";
+export const CONCURRENCY_SCAFFOLD = "// subagent-mcp — Global Concurrent Subagent Cap\n// ------------------------------------------------------------------\n// SOLE source of truth for the machine-wide limit on how many subagents\n// may be ALIVE AT ONCE across EVERY session, process, and user on this\n// machine. There is NO environment-variable override for the cap.\n//\n// The whole recursive descendant tree counts toward this ONE number: a\n// subagent that itself launches subagents adds to the same machine-wide\n// total, and OTHER active agentic sessions count too.\n//\n// RE-READ on every launch_agent call — edits take effect immediately, no\n// server restart required.\n//\n// Value rules (forcibly applied to the number below):\n//   - missing / unset / non-integer / 0 / negative  -> reset to default 20\n//   - 1 through 9                                    -> forced UP to minimum 10\n//   - 10 or greater                                 -> used as-is\n//\n// Zombie culling is always enabled. There is no config knob. Before cap\n// rejection, launch/tool/hook paths refresh live owned slots, preserve stale\n// slots whose owner server is still alive, and cull stale slots whose owner is\n// gone. Managed stale slots terminate the child process tree, then force-kill\n// after 20s when needed; unmanaged stale slots are only unlinked.\n//\n// When the cap is reached after culling, launch_agent is REJECTED (never\n// queued). Free a slot with list_agents + kill_agent, then retry.\n//\n// checkForUpdates controls the silent npmjs update check started when the MCP\n// server connects. Default true. Set to false to skip the registry fetch and\n// suppress hook notices. SUBAGENT_UPDATE_CHECK=0 or false also disables it.\n{\n  \"globalConcurrentSubagents\": 20,\n  \"checkForUpdates\": true\n}\n";