@heretyc/subagent-mcp 2.12.5 → 2.12.8

package/README.md

@@ -5,39 +5,56 @@
 [![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)
 
-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.
+## Core premise
+
+subagent-mcp is an MCP (stdio) server that turns any AI coding assistant
+(Claude Code, Codex, Gemini CLI) into a **manager/orchestrator of a team of
+AI sub-agents** running on macOS, Linux, and Windows. It drives the locally
+authenticated `claude` and `codex` CLIs you already signed into — **no direct
+HTTP API calls and no API keys, ever** (an explicit, permanent non-goal). It
+serves developers running big, long-horizon coding jobs who want to escape a
+single conversation's context limits and vendor lock-in.
+
+Its central promise: the orchestrator **monitors but never reads or writes
+files itself** — every step is delegated to a fresh sub-agent, so the
+orchestrator's context fills only with ≤100-line summaries. This extends
+effective context "geometrically" instead of linearly, enabling marathon tasks
+with little or no compaction. Guarantees/invariants it promises: a single
+machine-global, provider-agnostic concurrency cap (default 20, min 10; rejects
+at cap, never queues); fail-safe **ON** on hosts lacking hooks (unknown
+orchestration state defaults to ON); orchestration state is authoritative only
+via harness-verified `<subagent-mcp state="...">` hook tags, never inferred from
+prose (guards against directive drift/hallucination); sub-agents run **gated by
+default** (permission ceiling `auto`); and automatic model/provider/effort
+routing per task category so the user never picks a model.
+
+## Key problems it solves
+
+- **Context exhaustion / compaction on long tasks** — delegate-only
+  orchestration keeps the manager's context holding summaries, not raw files,
+  so long jobs run with minimal compaction.
+- **Single-vendor blind spots and lock-in** — mixed Claude + Codex (provider-
+  agnostic) operation means one vendor's weakness or outage doesn't blind or
+  block the whole job.
+- **No API keys / no direct API calls** — drives locally signed-in vendor CLIs
+  instead of the Anthropic/OpenAI HTTP APIs, avoiding key management and cost of
+  a gateway.
+- **Directive drift & hallucination over long runs** — operating rules are
+  re-injected redundantly (MCP `instructions`, INIT_BLOCK, per-turn hooks,
+  managed AGENTS.md/CLAUDE.md/GEMINI.md blocks) and made authoritative via
+  harness-verified state tags.
+- **Model-selection burden** — a benchmark-derived routing table auto-picks
+  provider/model/effort from a plain-English prompt + task category.
+- **Uncontrolled/unsafe sub-agent actions** — a shared permission engine gates
+  sub-agent operations (SAFE→allow, DANGER→deny, NEUTRAL→park for a decision)
+  with `auto`/`manual`/`yolo` ceilings and one-time `respond_permission`.
+- **Runaway fan-out / resource contention** — one machine-wide concurrency cap
+  and worktree isolation (branch-per-task) with a first-line sub-agent
+  carve-out to prevent fork-bomb recursion.
+- **Orchestrator observability** — a fixed set of tools (launch/poll/kill/
+  send_message/list/wait/respond_permission + orchestration & model modes) plus
+  a status lifecycle (processing/stalled/finished/errored/stopped/
+  zombie_killed/permission_requested) so a quiet agent isn't mistaken for dead.
 
 ## Install
 
@@ -167,7 +184,7 @@ keeps running either way. Full spec: [docs/spec/permissions.md](docs/spec/permis
 - **"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.
+  `global-subagent-mcp-config.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
@@ -179,7 +196,7 @@ keeps running either way. Full spec: [docs/spec/permissions.md](docs/spec/permis
 |---|---|
 | [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/tools.md](docs/tools.md) | Full tool reference — all nine tools, parameters, return shapes |
 | [docs/usage.md](docs/usage.md) | Model & effort matrix, ultracode mode, usage examples |
 | [docs/SPEC.md](docs/SPEC.md) | Full technical specification |
 | [docs/spec/permissions.md](docs/spec/permissions.md) | Permission system — ceiling modes, shared engine, threat model |

package/dist/concurrency.js

@@ -25,7 +25,7 @@ export function clampCap(raw) {
     return v;
 }
 export function stripJsoncComments(text) {
-    return text.replace(/^\s*\/\/.*$/gm, "");
+    return text.replace(/^\uFEFF/, "").replace(/^\s*\/\/.*$/gm, "");
 }
 function parseJsonObject(text) {
     const parsed = JSON.parse(stripJsoncComments(text));

package/dist/index.js

@@ -441,8 +441,7 @@ function handleCompletedStdoutLines(agent, lines, at) {
             agent.status = "finished";
             if (agent.exitedAt === null)
                 agent.exitedAt = at;
-            releaseSlot(agent.slotPath ?? null);
-            agent.slotPath = null;
+            updateSlotMetadata(agent, at);
         }
     }
 }
@@ -516,7 +515,7 @@ const ORCHESTRATION_INSTRUCTIONS = "subagent-mcp - CANONICAL OPERATING MODEL (fu
 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.12.5",
+    version: "2.12.8",
     description: "Launches always-interactive local Claude and Codex sub-agent sessions and is the orchestrator's sole launch channel. Claude runs via the Claude Agent SDK over the local Claude Code executable; Codex via `codex app-server` over stdio. The server never calls Anthropic or OpenAI HTTP APIs directly.",
 }, {
     instructions: process.env.SUBAGENT_MCP_SUBAGENT === "1"

package/dist/init.js

@@ -21,7 +21,7 @@ export const INIT_BLOCK = [
     "",
     "ORCHESTRATION ON — you are the ORCHESTRATOR. Allowed tools: only the structured-question tool (AskUserQuestion on Claude / request-user-input on Codex), subagent-mcp, and the /workflows tool. There is no inline-by-right; every step runs in a sub-agent. If one atomic step truly cannot run in a sub-agent, ask the user via the structured-question tool for a one-time exception for that single step, perform only that step, then resume delegating. Sole channel: while subagent-mcp is connected, every sub-agent launch goes through `launch_agent`; never use harness-native sub-agent tools or shell-spawned agents.",
     "",
-    "ORCHESTRATOR WORKTREE SETUP: launch sub-agents in the main checkout cwd (they no longer self-isolate into per-agent worktrees); serialize any sub-agents that write the same files — never run concurrent writers over overlapping paths (no cwd-level lock exists).",
+    "ORCHESTRATOR WORKTREE SETUP: for mutating work, first place sub-agents in a compliant linked worktree/work branch; the main checkout cwd applies only to read-only work or already-isolated target-tree contexts (sub-agents no longer self-isolate into per-agent worktrees). Serialize any sub-agents that write the same files — never run concurrent writers over overlapping paths (no cwd-level lock exists).",
     "",
     "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.",
     "",

package/dist/orchestration/marker.js

@@ -55,6 +55,9 @@ function cwdDisablePath(cwd) {
 export function sessionPointerPath(cwd) {
     return join(stateDir, `orch-session-${cwdHash(cwd)}.json`);
 }
+export function serverSessionPointerPath(cwd, serverKey = process.ppid) {
+    return join(stateDir, `orch-session-${cwdHash(cwd)}-${hashKey(String(serverKey))}.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
@@ -128,9 +131,15 @@ export function writeDisableCwd(cwd) {
         // Fail-safe: never throw to the caller.
     }
 }
-export function writeCurrentSession(cwd, sessionKey) {
+export function writeCurrentSession(cwd, sessionKey, serverKey = process.ppid) {
     try {
         mkdirSync(stateDir, { recursive: true, mode: 0o700 });
+        writeFileSync(serverSessionPointerPath(cwd, serverKey), JSON.stringify({ session_key: sessionKey }), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        // Back-compat only: older consumers may still read the cwd-keyed pointer.
+        // New disable/query paths must read the server-scoped pointer instead.
         writeFileSync(sessionPointerPath(cwd), JSON.stringify({ session_key: sessionKey }), {
             encoding: "utf8",
             mode: 0o600,
@@ -140,9 +149,9 @@ export function writeCurrentSession(cwd, sessionKey) {
         // Fail-safe: never throw to the caller.
     }
 }
-export function readCurrentSession(cwd) {
+export function readCurrentSession(cwd, serverKey = process.ppid) {
     try {
-        const raw = readFileSync(sessionPointerPath(cwd), "utf8");
+        const raw = readFileSync(serverSessionPointerPath(cwd, serverKey), "utf8");
         const parsed = JSON.parse(raw);
         return typeof parsed.session_key === "string" ? parsed.session_key : undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretyc/subagent-mcp",
-  "version": "2.12.5",
+  "version": "2.12.8",
   "description": "MCP server that launches and manages always-interactive Claude Code and Codex sub-agent sessions (no direct Anthropic/OpenAI API).",
   "keywords": [
     "mcp",
@@ -38,7 +38,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/global-concurrency-cap.test.mjs && node test/update-check.test.mjs && node test/zombie.test.mjs && node test/zombie-reap-idle.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/mcp-compliance.test.mjs"
+    "test": "npm run check:versions && node test/effort.test.mjs && node test/drivers.test.mjs && node test/platform.test.mjs && node test/wait.test.mjs && node test/status.test.mjs && node test/output.test.mjs && node test/stream.test.mjs && node test/routing.test.mjs && node test/deadlock.test.mjs && node test/handler-validation.test.mjs && node test/index-handler.test.mjs && node test/ruleset.test.mjs && node test/ruleset-exec.test.mjs && node test/ruleset-handler.test.mjs && node test/failover.test.mjs && node test/global-concurrency-cap.test.mjs && node test/update-check.test.mjs && node test/zombie.test.mjs && node test/zombie-reap-idle.test.mjs && node test/orchestration-marker.test.mjs && node test/orchestration-hook-core.test.mjs && node test/orchestration-adapters.test.mjs && node test/orchestration-pretool.test.mjs && node test/orchestration-directives.test.mjs && node test/no-five-call.test.mjs && node test/no-per-provider-cap.test.mjs && node test/rag-pointers.test.mjs && node test/check-worktree-subagent.test.mjs && node test/launch-agent-upsert.test.mjs && node test/claude-session-limit.test.mjs && node test/init-migration.test.mjs && node test/init-global.test.mjs && node test/mirror-fragments.test.mjs && node test/performance-tier-effort.test.mjs && node test/setup-repair.test.mjs && node test/setup-quoting.test.mjs && node test/setup-wire.test.mjs && node test/setup-cli-integration.test.mjs && node test/init.test.mjs && node test/model-selection-mode.test.mjs && node test/cli-args.test.mjs && node test/index-guard.test.mjs && node test/drivers-guard.test.mjs && node test/audit-next13-lb3.test.mjs && node test/zombie-guard.test.mjs && node test/concurrency-guard.test.mjs && node test/hook-core-guard.test.mjs && node scripts/validate_provider.mjs && node scripts/validate_seed_sites.mjs && node scripts/validate_routing_audit.mjs && node test/seed-sites.test.mjs && node test/config-bom.test.mjs && node test/permission-system.test.mjs && node test/lifecycle-matrix.test.mjs && node test/output-hook-registration.test.mjs && node test/mcp-compliance.test.mjs"
   },
   "author": "Lexi Blackburn",
   "license": "Apache-2.0",