{
  "markdown": "# Subagent MCP\n\n<!-- mcp-name: io.github.Thang1710/subagent-mcp -->\n\n**Independent harnesses. One Codex orchestrator.**\n\nWhen one model plans a change, implements it, and reviews it, the reviewer shares\nthe author's context and blind spots. It can end up confirming its own plan\ninstead of testing it.\n\nSubagent MCP keeps Codex as the main agent and final decision-maker while\ndelegating bounded work to external agent runtimes. Each runtime is a model\npaired with its native harness, so Codex can get implementation or review from\nan independent model with different context and assumptions.\n\nThat expands Codex's effective sub-agent pool and can use provider quota you\nalready have. Subagent MCP never enables, purchases, auto-reloads, or silently\nopts into usage credits or paid overage.\n\nAdapters translate every native harness into the same lifecycle: delegate,\nobserve, steer, and close. The core hard-codes no provider role or model name.\n\n> **Stable:** `1.0.29` targets Windows. The MCP, package, localhost UI, and\n> Claude Code and DeepSeek native-harness integrations are ready.\n\n## Runtime status\n\n- **Claude Code — Ready.** Uses the native Claude Code harness, provider-native\n  model and reasoning settings, subscription OAuth identity, and live\n  no-overage evidence before accepting its output. Project/local context and\n  exact auto-compaction-trigger attestation remain explicit capability gaps.\n- **DeepSeek Harness — Ready.** Uses its native ACP transport and\n  harness-published model catalog for bounded tasks. Resume after an MCP restart,\n  exact provider quota evidence, interactive input, and declared MCP remain\n  explicit capability gaps. A provider-retired model route fails terminally and\n  is never replaced without the user's explicit selection.\n- **Grok Build — Ready for read-only review.** The Windows adapter uses cached\n  native login only and allows no credits, paid overage, or model fallback.\n  Version 1.0.29 advertises and accepts `repo_read` only. Bounded writing remains\n  **In development** and `workspace_write` requests fail before a native process\n  starts. Other explicit gaps are terminal/test/Git execution,\n  network/web/browser, MCP/plugins/hooks, nested agents, native worktrees,\n  restart recovery, macOS/Linux support, and exact pre-request quota.\n\nRuntime behavior comes from adapters rather than provider-specific branches in\nthe core.\n\n## Quick start\n\n### 1. Install\n\nInstall [uv](https://docs.astral.sh/uv/getting-started/installation/) if needed,\nthen register the exact isolated release and start its background UI:\n\n```powershell\nwinget install --id=astral-sh.uv -e\ncodex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.29 subagent-harness-mcp serve\nuvx --isolated --from subagent-harness-mcp==1.0.29 subagent-harness-mcp ui --background\n```\n\nStart a new Codex task after registration.\n\n### 2. Configure runtimes\n\nOpen `http://127.0.0.1:8765` in a browser. If the background UI was stopped,\nstart the same exact release again:\n\n```powershell\nuvx --isolated --from subagent-harness-mcp==1.0.29 subagent-harness-mcp ui --background\n```\n\nThe settings and read-only activity UI stays on the fixed loopback port and\ndoes not depend on an active MCP connection.\n\nIf a runtime shows **Sign in required**, click **Sign in**. Its native harness\nopens the operating system's default browser; Subagent MCP never asks for or\nstores credentials. Complete login there, then click **Refresh**. A status\ncheck never opens a browser by itself.\n\nCurrent and recent activity is listed by external agent. Select a row to inspect\nits model, native harness, workspace, permissions, write set, current stage,\nlifecycle, elapsed time, and redacted terminal result. Prompts, transcripts,\nhidden thinking, and raw provider events are never displayed.\n\n### 3. Delegate\n\nAsk Codex in plain language:\n\n> Use Subagent MCP to ask an external agent to review this change, then\n> evaluate its findings independently.\n\nCodex chooses what to delegate, observes the result, and keeps the final\njudgment. Lifecycle responses are compact by default; full redacted reports\nremain in local product state and can be read or relayed later by hash-bound\nreference.\n\nFor an approval tied to an exact file, pass `inputs` on `agent_spawn` (inside\n`task`) or `agent_send`:\n\n```json\n[{\"path\":\"docs/specs/review.md\",\"expected_sha256\":\"<lowercase SHA-256>\"}]\n```\n\nThe MCP hashes each repository-relative file read-only immediately before the\nnative turn. Status returns the verified hash and configured reasoning\nattestation; a changed file fails before the external agent runs.\n\n## Models and fallback order\n\nEach native harness publishes its own model choices. The UI shows friendly names\nand an ordered priority stack; exact provider IDs remain available for advanced\nroutes.\n\nWhen a provider explicitly reports exhausted quota or credit\n(`QUOTA_PAUSED`), Subagent MCP moves that exact model to the bottom for future\ntasks. It does not retry the failed task. Ambiguous failures, crashes, and\ntimeouts do not reorder models or trigger another paid request.\n\nThat failed task stays terminal, but the next explicit delegation checks the\nprovider again live; no cached reset clock or wait-until checkpoint substitutes\nfor that check. When the native harness exposes no safe pre-request quota\nendpoint, status stays unknown rather than inferred exhausted.\n\nOperational recovery is capped at three actions. Local state work and explicit\npre-provider failures may be retried. DeepSeek also retries an explicit\ntemporary upstream HTTP 429 at most three total attempts. A generic provider\nfailure is never replayed automatically: a read-only task returns bounded\nguidance for a new explicit attempt, while a write task remains non-retryable\nuntil its write set and possible effects are reconciled. Quota, credit, billing,\ntimeout, and ambiguous lifecycle failures never trigger another provider call.\nNative ACP failures include bounded redacted RPC/provider details when the\nharness exposes them; unknown quota remains a provider error, not exhaustion.\n\nDeepSeek routes may use an existing subscription, unlimited offer, or funded\nbalance that the user authorizes. Subagent MCP never purchases, reloads, or\nincreases that balance.\n\n## Long-running work\n\n`agent_wait` is a bounded local observation, not a model deadline. If it returns\n`running` with `wait_policy=continue_while_running`, the external agent may still\nbe working or thinking. Keep observing the same conversation; elapsed time alone\nnever triggers retry, fallback, interruption, or another provider request.\n\n## Concurrent writers\n\nA write task can declare up to 32 repository-relative file or directory roots\nin `write_set`. External writers may run concurrently when their canonical\nabsolute sets are disjoint. Equal paths and parent/child paths conflict; task\nand lane names do not affect locking.\n\nOmitting `write_set` gives the execution the whole workspace for backwards\ncompatibility. Each adapter also enforces the normalized paths at its native\nharness boundary. Inspect `runtime_list` before creating a write request:\n`write_root_mode=path-prefix` supports exact file or directory prefixes, while\n`existing-directory` requires an existing directory. The current DeepSeek\nHarness native session advertises `existing-directory` and one writable root.\nSubagent MCP never widens an exact-file scope to its parent directory; use that\nbroader directory only when it is explicitly acceptable, otherwise choose a\nruntime that enforces `path-prefix`. Multiple valid directory roots are split\ninto disjoint writer calls. These leases coordinate Subagent MCP executions;\nthey are not an operating-system sandbox for unrelated local processes.\n\nOn the current Windows public slice, set `cwd` to the checkout root and use\n`workspace=\"current\"`. For a DeepSeek write, pass `workspace_write` and exactly\none existing directory relative to `cwd`, for example\n`write_set=[\"Assets/_Project/Core/Scripts/GameSettings\"]`. An absolute path,\nmissing path, or exact file is not a valid `existing-directory` root.\n\nOn Windows, the DeepSeek native sandbox must materialize a restricted-token ACE,\nso the current user also needs `WRITE_DAC` on the selected directory. Subagent\nMCP checks that capability read-only before ACP or provider work. It does not\nchange ownership or ACLs. A failed check stays `CAPABILITY_MISSING`; it never\nfalls back to `danger-full-access`.\n\n## How it fits together\n\n```mermaid\nflowchart LR\n    C[\"Codex<br/>Main agent & orchestrator\"]\n    M[\"Subagent MCP<br/>Gateway\"]\n    UI[\"Localhost UI<br/>Settings & activity\"]\n\n    C -->|\"delegate · steer · observe\"| M\n    UI --> M\n\n    subgraph E[\"External agent runtimes — adapter-driven\"]\n        R1[\"Model<br/>+<br/>native harness\"]\n        R2[\"Model<br/>+<br/>native harness\"]\n        RN[\"Future runtimes<br/>via adapters\"]\n    end\n\n    M -->|\"normalized lifecycle\"| R1\n    M -->|\"normalized lifecycle\"| R2\n    M -->|\"normalized lifecycle\"| RN\n```\n\nSubagent MCP owns lifecycle normalization, status, redaction, leases, and\ncircuits. Each adapter translates that contract to its native harness. See\n[Architecture](docs/architecture.md) for the full contract.\n\n## Update or roll back on Windows\n\nSwitch versions without reinstalling an environment that may still be running.\nThe first command uses the source version; the add/start commands use the target\nversion. This example upgrades 1.0.28 to 1.0.29:\n\n```powershell\nuvx --isolated --from subagent-harness-mcp==1.0.28 subagent-harness-mcp ui --stop\ncodex mcp remove subagent-mcp\ncodex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.29 subagent-harness-mcp serve\nuvx --isolated --from subagent-harness-mcp==1.0.29 subagent-harness-mcp ui --background\n```\n\nStart a fresh Codex task after changing the entry. Existing tasks keep their old\nruntime until they end. Use the same sequence with the exact versions reversed\nto roll back.\n\nAn already-running MCP that reports `UPDATE_QUARANTINED` cannot hot-load the\nreplacement safely. Do not retry that resident; finish with native fallback and\nuse the new exact registration from a fresh task.\n\nFor a one-time migration from a direct `subagent-harness-mcp serve` entry,\nreplace the registration first and let the legacy task end naturally. After\nreplacing it, close every Codex window once before optionally removing the\nnow-unused persistent tool. Leaving it installed is safe because every new\ncommand above uses `uvx --isolated`.\n\nSubagent MCP does not edit Codex configuration, kill Codex/provider processes,\nor clear uv caches on its own.\n\n## Safety and billing\n\n- Subagent MCP never enables usage credits or changes billing settings.\n- Claude tasks can consume included subscription quota. Each task validates the\n  bound CLI, subscription authentication, credential precedence, and control\n  connection, then requires safe rate evidence from the same response before\n  accepting its output.\n- Provider Refresh sends no model prompt. If the native harness cannot expose\n  exact rate evidence before a response, status remains unknown rather than\n  inventing a quota result or using a reset clock.\n- Fallback occurs only after explicit quota exhaustion. Unsafe or ambiguous\n  evidence never triggers another paid request.\n- Native transcripts remain owned by the native harness. Product state stays in\n  explicit local roots, and agent output must be treated as untrusted advice.\n\nRead [Security](SECURITY.md) and the\n[Threat model](docs/threat-model.md) before enabling write access.\n\n## Project\n\n- [Architecture](docs/architecture.md)\n- [Adapter authoring](docs/adapter-authoring.md)\n- [Contributing](CONTRIBUTING.md)\n- [Changelog](CHANGELOG.md)\n- [MIT License](LICENSE)\n",
  "bytes": 11750,
  "sha": "625df7a2ba12eeed683696a3d4c8ca9aa8f1331e4c55b904f584e202567d62ab",
  "repo_slug": "thang1710/subagent-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_thang1710_subagent_mcp_b2c56552/readme"
}