@heretyc/subagent-mcp 2.6.0

package/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction,
+and distribution as defined in Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by
+the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all
+other entities that control, are controlled by, or are under common
+control with that entity. For the purposes of this definition,
+"control" means (i) the power, direct or indirect, to cause the
+direction or management of such entity, whether by contract or
+otherwise, or (ii) ownership of fifty percent (50%) or more of the
+outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising
+permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications,
+including but not limited to software source code, documentation
+source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical
+transformation or translation of a Source form, including but
+not limited to compiled object code, generated documentation,
+and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object
+form, made available under the License, as indicated by a copyright
+notice that is included in or attached to the work (an example is
+provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object
+form, that is based on (or derived from) the Work and for which the
+editorial revisions, annotations, elaborations, or other modifications
+represent, as a whole, an original work of authorship. For the purposes
+of this License, Derivative Works shall not include works that remain
+separable from, or merely link (or bind by name) to the interfaces of,
+the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including
+the original Work and any Derivative Works thereof, and any modifications
+and enhancements to those works or Derivative Works thereof, that is
+intentionally submitted to Licensor for inclusion in the Work by the
+copyright owner or by an individual or Legal Entity authorized to submit
+on behalf of the copyright owner. For the purposes of this definition,
+"submitted" means any form of electronic, verbal, or written communication
+sent to the Licensor or its representatives, including but not limited to
+communication on electronic mailing lists, source code control systems,
+and issue tracking systems that are managed by, or on behalf of, the
+Licensor for the purpose of discussing and improving the Work, but
+excluding communication that is conspicuously marked or otherwise
+designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any Legal Entity on behalf of
+whom a Contribution has been received by Licensor and subsequently
+incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+copyright license to reproduce, prepare Derivative Works of,
+publicly display, publicly perform, sublicense, and distribute the
+Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+this License, each Contributor hereby grants to You a perpetual,
+worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+(except as stated in this section) patent license to make, have made,
+use, offer to sell, sell, import, and otherwise transfer the Work,
+where such license applies only to those patent claims licensable
+by such Contributor that are necessarily infringed by their
+Contribution(s) alone or by combination of their Contribution(s)
+with the Work to which such Contribution(s) was submitted. If You
+institute patent litigation against any entity (including a
+cross-claim or counterclaim in a lawsuit) alleging that the Work
+or a Contribution incorporated within the Work constitutes direct
+or contributory patent infringement, then any patent licenses
+granted to You under this License for that Work shall terminate
+as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+Work or Derivative Works thereof in any medium, with or without
+modifications, and in Source or Object form, provided that You
+meet the following conditions:
+
+(a) You must give any other recipients of the Work or
+Derivative Works a copy of this License; and
+
+(b) You must cause any modified files to carry prominent notices
+stating that You changed the files; and
+
+(c) You must retain, in the Source form of any Derivative Works
+that You distribute, all copyright, patent, trademark, and
+attribution notices from the Source form of the Work,
+excluding those notices that do not pertain to any part of
+the Derivative Works; and
+
+(d) If the Work includes a "NOTICE" text file, then any
+Derivative Works that You distribute must include a readable
+copy of the attribution notices contained within such NOTICE
+file, excluding those notices that do not pertain to any part
+of the Derivative Works, in at least one of the following
+places: within a NOTICE text file distributed as part of the
+Derivative Works; within the Source form or documentation,
+if provided along with the Derivative Works; or, within a
+display generated by the Derivative Works, if and
+wherever such third-party notices normally appear. The contents
+of the NOTICE file are for informational purposes only and
+do not modify the License. You may add Your own attribution
+notices within Derivative Works that You distribute, alongside
+or as an addendum to the NOTICE from the Work, provided that
+such additional attribution notices cannot be construed as
+modifying the License.
+
+You may add Your own copyright statement to Your modifications and
+may provide additional or different license terms and conditions
+for use, reproduction, or distribution of Your modifications, or
+for any such Derivative Works as a whole, provided Your use,
+reproduction, and distribution of the Work otherwise complies with
+the conditions of this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+any Contribution intentionally submitted for inclusion in the Work by
+You to Licensor shall be under the terms and conditions of this License,
+without any additional terms or conditions. Notwithstanding the above,
+nothing herein shall supersede or modify the terms of any separate
+license agreement you may have executed with Licensor regarding such
+Contribution.
+
+6. Trademarks. This License does not grant permission to use the trade
+names, trademarks, service marks, or product names of the Licensor,
+except as required for reasonable and customary use in describing the
+origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+agreed to in writing, Licensor provides the Work (and each
+Contributor provides its Contributions) on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied, including, without limitation, any warranties or conditions
+of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+PARTICULAR PURPOSE. You are solely responsible for determining the
+appropriateness of using or redistributing the Work and assume any
+risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+whether in tort (including negligence), contract, or otherwise,
+unless required by applicable law (such as deliberate and grossly
+negligent acts) or agreed to in writing, shall any Contributor be
+liable to You for damages, including any direct, indirect, special,
+incidental, or consequential damages of any character arising as a
+result of this License or out of the use or inability to use the
+Work (including but not limited to damages for loss of goodwill,
+work stoppage, computer failure or malfunction, or any and all
+other commercial damages or losses), even if such Contributor
+has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+the Work or Derivative Works thereof, You may choose to offer,
+and charge a fee for, acceptance of support, warranty, indemnity,
+or other liability obligations and/or rights consistent with this
+License. However, in accepting such obligations, You may act only
+on Your own behalf and on Your sole responsibility, not on behalf
+of any other Contributor, and only if You agree to indemnify,
+defend, and hold each Contributor harmless for any liability
+incurred by, or claims asserted against, such Contributor by reason
+of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+APPENDIX: How to apply the Apache License to your work.
+
+To apply the Apache License to your work, attach the following
+boilerplate notice, with the fields enclosed by brackets "{}"
+replaced with your own identifying information. (Don't include
+the brackets!) The text should be enclosed in the appropriate
+comment syntax for the file type. You may also add a brief
+description of what the file does on the same "printed page" as
+the copyright notice for easier identification within third-party
+archives.
+
+Copyright 2026 Lexi Blackburn
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/NOTICE

@@ -0,0 +1,5 @@
+subagent-mcp
+Copyright 2026 Lexi Blackburn
+
+Licensed under the Apache License, Version 2.0.
+This product includes software developed by Lexi Blackburn.

package/README.md

@@ -0,0 +1,124 @@
+# subagent-mcp
+
+MCP server that launches and manages locally installed `claude` and `codex` CLI binaries as child sub-agent processes. Runs on **macOS, Linux, and Windows**.
+
+**No direct API calls.** subagent-mcp does NOT use the Anthropic or OpenAI HTTP APIs and has no plans to. It invokes your locally installed and authenticated `claude` (Claude Code) and `codex` CLIs. No API keys, no SDKs beyond the CLIs themselves.
+
+**License:** Apache-2.0 | **Author:** Lexi Blackburn | **Repo:** https://github.com/Heretyc/subagent-mcp
+
+---
+
+## Features
+
+- Spawn `claude` or `codex` CLI processes as managed sub-agents from any MCP host
+- Poll status, stream stdout/stderr tails, and send stdin messages to live agents
+- 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 `stream-json`, Codex `--json` 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 an orchestrator-only directive that the bundled Claude Code / Codex plugin injects every turn via its `UserPromptSubmit` hook (Desktop hosts toggle but do not inject); see [docs/spec/orchestration-mode/_INDEX.md](docs/spec/orchestration-mode/_INDEX.md)
+
+---
+
+## Quick Start
+
+**Prerequisites:** Node.js >= 18, plus the `claude` and/or `codex` CLIs installed globally and authenticated.
+
+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):
+
+```bash
+# 1. Configure registry for @heretyc scope (once per machine)
+echo "@heretyc:registry=https://npm.pkg.github.com" >> ~/.npmrc
+
+# 2. Authenticate — use a classic PAT with read:packages scope
+echo "//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT" >> ~/.npmrc
+
+# 3. Install and wire
+npm install -g @heretyc/subagent-mcp
+subagent-mcp setup
+```
+
+`setup` detects which vendors are present, registers the MCP server, and writes the `UserPromptSubmit` hook for orchestration-mode injection. Idempotent — safe to re-run after updates. Pass `--dry-run` to preview.
+
+After setup, restart your Claude Code or Codex session. On Codex, run `/hooks` and trust the new hook.
+
+**Updating:** `npm install -g @heretyc/subagent-mcp && subagent-mcp setup`
+
+For manual wiring, developer install from source, Gemini CLI, and Claude Desktop, see [docs/registration.md](docs/registration.md).
+
+---
+
+## Auto Mode
+
+`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`.
+
+**task_category** (required) — pick one:
+
+| Category | What it is |
+|---|---|
+| `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) |
+| `fallback_default` | no category matches with confidence; prefer splitting work instead |
+
+**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.
+
+---
+
+## Tools
+
+Six tools are exposed over the stdio MCP transport:
+
+| Tool | Purpose |
+|------|---------|
+| `launch_agent` | Spawn a new `claude`/`codex` sub-agent process |
+| `poll_agent` | Get status + output tail of one agent |
+| `kill_agent` | Immediately force-kill any live agent |
+| `send_message` | Write to a live agent's stdin |
+| `list_agents` | List all agents with token-efficient core metrics |
+| `wait` | Block until one or more agents finish, or 15-minute timeout |
+
+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).
+
+---
+
+## Agent Lifecycle
+
+Each agent transitions through these states:
+
+| Status | Meaning |
+|--------|---------|
+| `processing` | Process alive with a visible provider-stream heartbeat in the last 10 minutes -- actively working. Launch time counts as the initial heartbeat |
+| `stalled` | Process 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` | Process exited with code 0, or Codex emitted `turn.completed` event |
+| `errored` | Process exited with non-zero code |
+| `stopped` | Terminated by `kill_agent` |
+
+Only `finished`, `errored`, and `stopped` are terminal; `processing` and `stalled` are live. A health monitor runs every 10 seconds, and `poll_agent`/`list_agents` additionally reconcile exit synchronously so an exited process is reported immediately. `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 (or checking the agent's temp output) over `kill_agent`. 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).
+
+---
+
+## License
+
+Apache-2.0 -- Copyright 2026 Lexi Blackburn
+
+See [docs/SPEC.md](docs/SPEC.md) for the full technical specification.

package/directives/carryover-claude.md

@@ -0,0 +1,17 @@
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-CARRYOVER priority="CRITICAL" override="NONE">
+
+ORCHESTRATION MODE was ON at session start — carried over from a PRIOR session
+for this project (persists until disabled with permission). Not enabled in THIS
+session.
+
+THIS turn, ONCE:
+1. NOTIFY user it carried over.
+2. ASK keep ON? via AskUserQuestion.
+3. ADVISE fit: long-horizon context-filling → keep ON; bounded, interactive, or
+   core-bound to main-session-only MCP → propose OFF.
+
+Declines → orchestration-mode enabled:false. NEVER disable on own initiative.
+After answer: handshake done — do not re-raise.
+
+</ORCHESTRATION-CARRYOVER>

package/directives/carryover-codex.md

@@ -0,0 +1,17 @@
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<ORCHESTRATION-CARRYOVER priority="CRITICAL" override="NONE">
+
+ORCHESTRATION MODE was ON at session start — carried over from a PRIOR session
+for this project (persists until disabled with permission). Not enabled in THIS
+session.
+
+THIS turn, ONCE:
+1. NOTIFY user it carried over.
+2. ASK keep ON? via request-user-input.
+3. ADVISE fit: long-horizon context-filling → keep ON; bounded, interactive, or
+   core-bound to main-session-only MCP → propose OFF.
+
+Declines → orchestration-mode enabled:false. NEVER disable on own initiative.
+After answer: handshake done — do not re-raise.
+
+</ORCHESTRATION-CARRYOVER>

package/directives/off-turn-reminder.md

@@ -0,0 +1 @@
+Reminder: <SUB-AGENT-INVARIANT> and <sanity-rules> apply. HALT if unknown.

package/directives/orchestration-claude.md

@@ -0,0 +1,21 @@
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<SUB-AGENT-INVARIANT priority="CRITICAL" override="NONE">
+
+ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+
+INLINE BY RIGHT (no violation): steps bound to main-session-only capability —
+MCP tools sub-agents can't inherit, interactive/consent tools, tight verify
+loops. State which + why, one line.
+
+MUST DELEGATE/OFFLOAD (breach if not): pure compute (parse/aggregate/transform);
+any payload >50KB or >200 lines → scratch file, hand off the PATH.
+Mixed task = SPLIT. One MCP-bound step never makes the whole task inline.
+
+CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
+User tool-pin re-partitions work; does not suspend mode.
+
+IPC = temp scratch files ONLY. Windows: %TEMP%. POSIX: /tmp.
+Full model + governance: server MCP instructions.
+DISABLE: never on own initiative. Propose via AskUserQuestion only.
+
+</SUB-AGENT-INVARIANT>

package/directives/orchestration-codex.md

@@ -0,0 +1,22 @@
+<!-- INJECTED PRE-PROMPT DIRECTIVE — BINDING, NON-NEGOTIABLE -->
+<SUB-AGENT-INVARIANT priority="CRITICAL" override="NONE">
+SCOPE: If this session's prompt begins with "<this is a request from a parent process>", SUB-AGENT-INVARIANT does NOT apply to this session, SKIP the remainder of this directive.
+
+ORCHESTRATION MODE ON. You = ORCHESTRATOR. DEFAULT = DELEGATE.
+
+INLINE BY RIGHT (no violation): steps bound to main-session-only capability —
+MCP tools sub-agents can't inherit, interactive/consent tools, tight verify
+loops. State which + why, one line.
+
+MUST DELEGATE/OFFLOAD (breach if not): pure compute (parse/aggregate/transform);
+any payload >50KB or >200 lines → scratch file, hand off the PATH.
+Mixed task = SPLIT. One MCP-bound step never makes the whole task inline.
+
+CONFLICT ORDER: safety-scope > user instruction this turn > delegate-default.
+User tool-pin re-partitions work; does not suspend mode.
+
+IPC = temp scratch files ONLY. Windows: %TEMP%. POSIX: /tmp.
+Full model + governance: server MCP instructions.
+DISABLE: never on own initiative. Propose via request-user-input only.
+
+</SUB-AGENT-INVARIANT>

package/dist/advanced-ruleset.py

@@ -0,0 +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 -> low|medium|high|xhigh|max;
+    opus/opus-4-8 -> those plus ultracode; gpt-5.5 -> low|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/deadlock.js

@@ -0,0 +1,8 @@
+export function createDeadlockWindow(size = 3) {
+    let counter = 0;
+    return {
+        arm() { counter = size; },
+        active() { return counter > 0; },
+        consume() { counter = Math.max(0, counter - 1); },
+    };
+}

package/dist/doctor.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// `subagent-mcp doctor` — read-only health check for the installed addon.
+//
+// Diagnoses without touching any file: install completeness, vendor presence,
+// and whether each vendor's wiring (MCP server + hooks) points at THIS install.
+// The fixer is always `subagent-mcp setup` (idempotent, self-repairing); doctor
+// just tells you whether you need it and what exactly is wrong.
+//
+// Exit code: 0 = everything healthy, 1 = at least one check failed.
+import { verifyWiring } from "./setup.js";
+export async function runDoctor() {
+    console.log("subagent-mcp doctor (read-only — changes nothing)\n");
+    const major = Number(process.versions.node.split(".")[0]);
+    console.log(`  ${major >= 18 ? "PASS" : "FAIL"}  node version — ${process.versions.node}` +
+        (major >= 18 ? "" : " (Node >= 18 required)"));
+    let failed = major < 18 ? 1 : 0;
+    for (const r of verifyWiring()) {
+        console.log(`  ${r.ok ? "PASS" : "FAIL"}  ${r.label} — ${r.detail}`);
+        if (!r.ok)
+            failed++;
+    }
+    if (failed === 0) {
+        console.log("\nAll checks passed. If tools still don't appear in a session:\n" +
+            "  - Claude Code: restart the session, run /mcp\n" +
+            "  - Codex CLI:   restart the session, run /hooks (the hook must be TRUSTED)");
+        return 0;
+    }
+    console.log(`\n${failed} check(s) failed. Fix automatically with:  subagent-mcp setup\n` +
+        "(setup is idempotent: it repairs stale paths and re-adds missing wiring,\n" +
+        " backing up each config file before its first edit.)");
+    return 1;
+}

package/dist/effort.js

@@ -0,0 +1,78 @@
+import { writeFileSync } from "fs";
+import { join } from "path";
+import { tmpdir } from "os";
+import { randomUUID } from "crypto";
+export function mapModel(provider, model) {
+    if (provider === "claude") {
+        if (model === "opus" || model === "opus-4-8")
+            return "claude-opus-4-8";
+        return model; // haiku, sonnet as-is
+    }
+    else {
+        return model; // gpt-5.5
+    }
+}
+export function resolveEffort(provider, model, effort) {
+    const isOpus48 = provider === "claude" && (model === "opus" || model === "opus-4-8");
+    if (effort === "ultracode") {
+        if (!isOpus48) {
+            throw new Error(`ultracode effort is only available on Opus 4.8+ (got ${provider}/${model}). Use xhigh for other models.`);
+        }
+        return { kind: "settings" };
+    }
+    if (provider === "claude" && model === "haiku") {
+        return { kind: "none" };
+    }
+    if (provider === "claude" && ["sonnet", "opus", "opus-4-8"].includes(model)) {
+        if (["low", "medium", "high", "xhigh", "max"].includes(effort)) {
+            return { kind: "flag", value: effort };
+        }
+    }
+    if (provider === "codex") {
+        if (effort === "max") {
+            throw new Error(`max effort is not valid for gpt-5.5 (Codex). Valid: low, medium, high, xhigh.`);
+        }
+        if (["low", "medium", "high", "xhigh"].includes(effort)) {
+            return { kind: "flag", value: effort };
+        }
+    }
+    return { kind: "flag", value: "high" };
+}
+export function buildCommand(provider, model, effort, prompt, cwd) {
+    const mapped = mapModel(provider, model);
+    const er = resolveEffort(provider, model, effort);
+    if (provider === "claude") {
+        const args = ["-p", "--model", mapped];
+        if (er.kind === "flag") {
+            args.push("--effort", er.value);
+        }
+        else if (er.kind === "settings") {
+            const ucSettingsPath = join(tmpdir(), `subagent-uc-${randomUUID()}.json`);
+            writeFileSync(ucSettingsPath, '{"ultracode":true}');
+            args.push("--settings", ucSettingsPath);
+            args.push("--permission-mode", "bypassPermissions", "--tools", "default", "--max-turns", "50", "--output-format", "stream-json", "--verbose");
+            return { args, ucSettingsPath };
+        }
+        args.push("--permission-mode", "bypassPermissions", "--tools", "default", "--max-turns", "50", "--output-format", "stream-json", "--verbose");
+        return { args };
+    }
+    else {
+        // codex
+        const effortValue = er.value;
+        return {
+            args: [
+                "exec",
+                "-C",
+                cwd,
+                "-m",
+                "gpt-5.5",
+                "-c",
+                `model_reasoning_effort="${effortValue}"`,
+                "--dangerously-bypass-approvals-and-sandbox",
+                "--skip-git-repo-check",
+                "--json",
+                prompt,
+            ],
+        };
+    }
+}