Subagent MCP

Subagent MCP

独立したハーネス。1 つの Codex オーケストレーター。

1 つのモデルが変更を計画し、実装し、レビューすると、レビュアーは作者と同じコンテキストや盲点を共有します。その結果、計画を検証するのではなく、自らの計画を追認してしまうことがあります。

Subagent MCP は Codex をメインエージェント兼最終決定者としながら、範囲を限定した作業を外部のエージェントランタイムに委任します。各ランタイムはモデルとそのネイティブハーネスを組み合わせたもので、Codex は異なるコンテキストや前提を持つ独立したモデルから、実装やレビューを受けられます。

これにより、Codex が実質的に利用できるサブエージェントの選択肢が広がり、すでに利用しているプロバイダーの利用枠も活用できます。Subagent MCP が利用クレジットや有料超過利用を有効化、購入、自動チャージしたり、ユーザーの知らないうちに利用に同意したりすることはありません。

アダプターは、各ネイティブハーネスを、委任、状況確認、指示、終了という共通のライフサイクルに変換します。コアには、プロバイダーの役割やモデル名がハードコードされていません。

安定版： 1.0.31 は Windows を対象としています。MCP、パッケージ、localhost UI、および Claude Code と DeepSeek のネイティブハーネス連携が利用可能です。

ランタイムのステータス

• Claude Code — 利用可能。 ネイティブの Claude Code ハーネス、プロバイダー標準のモデルと推論設定、サブスクリプションの OAuth ID、および出力を受け入れる前のリアルタイムな超過課金なしの証拠を使用します。プロジェクト／ローカルコンテキストと、正確な自動圧縮トリガーの証明は、明示的な機能上のギャップとして残っています。
• DeepSeek Harness — 利用可能。 範囲を限定したタスクに、ネイティブの ACP トランスポートとハーネスが公開するモデルカタログを使用します。MCP 再起動後の再開、正確なプロバイダー利用枠の証拠、対話的な入力、および宣言された MCP は、明示的な機能上のギャップとして残っています。プロバイダーが廃止したモデルのルートは終端エラーとなり、ユーザーが明示的に選択しない限り置き換えられません。
• Grok Build — 読み取り専用レビューで利用可能。 Windows アダプターはキャッシュ済みのネイティブログインのみを使用し、クレジット、有料超過利用、モデルのフォールバックは許可しません。バージョン 1.0.31 が提示し、受け入れるのは repo_read のみです。範囲を限定した書き込み機能は引き続き開発中であり、workspace_write リクエストはネイティブプロセスの起動前に失敗します。その他の明示的なギャップは、ターミナル／テスト／Git の実行、ネットワーク／ウェブ／ブラウザー、MCP／プラグイン／フック、ネストされたエージェント、ネイティブワークツリー、再起動後の復旧、macOS／Linux のサポート、およびリクエスト前の正確な利用枠です。

ランタイムの動作は、コア内のプロバイダー固有の分岐ではなく、アダプターによって決まります。

クイックスタート

1. インストール

必要に応じて uv をインストールし、正確に分離されたリリースを登録して、バックグラウンド UI を起動します。

winget install --id=astral-sh.uv -e
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp ui --background

登録後、新しい Codex タスクを開始します。

2. ランタイムを設定

ブラウザーで http://127.0.0.1:8765 を開きます。バックグラウンド UI が停止している場合は、同じ正確なリリースをもう一度起動します。

uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp ui --background

設定画面と読み取り専用のアクティビティ UI は固定のループバックポートで動作し、アクティブな MCP 接続には依存しません。

ランタイムに Sign in required と表示された場合は、Sign in をクリックします。ネイティブハーネスがオペレーティングシステムの既定のブラウザーを開きます。Subagent MCP が認証情報を要求または保存することはありません。ブラウザーでログインを完了してから、Refresh をクリックします。ステータス確認によってブラウザーが自動的に開くことはありません。

現在および最近のアクティビティは、外部エージェントごとに一覧表示されます。行を選択すると、モデル、ネイティブハーネス、ワークスペース、権限、書き込み対象、現在の段階、ライフサイクル、経過時間、そして機密情報を除去したターミナル結果を確認できます。プロンプト、トランスクリプト、非公開の思考内容、生のプロバイダーイベントが表示されることはありません。

3. 委任する

平易な言葉で Codex に依頼します。

Subagent MCP を使用して、外部エージェントにこの変更をレビューするよう依頼し、その結果を独自に評価してください。

Codex は委任する内容を選び、結果を確認して、最終判断を行います。ライフサイクルの応答はデフォルトで簡潔です。完全なレポートは機密情報を伏せたうえでローカルの製品状態に保持され、後からハッシュに紐付いた参照を使って読み取ったり、伝達したりできます。

特定のファイルに紐付いた承認を求める場合は、agent_spawn（task 内）または agent_send で inputs を渡します。

[{"path":"docs/specs/review.md","expected_sha256":"<lowercase SHA-256>"}]

MCP はネイティブのターンを実行する直前に、リポジトリ相対パスの各ファイルを読み取り専用でハッシュ化します。ステータスには検証済みのハッシュと設定済みの推論アテステーションが返されます。ファイルが変更されている場合、外部エージェントの実行前に失敗します。

モデルとフォールバック順序

各ネイティブハーネスでは、それぞれのモデル選択肢が公開されています。UI にはわかりやすい名前と優先順位が表示され、詳細なルートでは正確なプロバイダー ID も引き続き利用できます。

Claude の選択肢は、公開 Agent SDK を通じてインストール済みのスタンドアロン CLI から取得されます。検出ではプロンプトを送信せずにネイティブのエイリアスを正確なモデル ID に解決し、得られたメタデータを最長 60 秒間キャッシュします。CLI の ID が変更されるとキャッシュは無効になります。認証情報がない場合や検出が利用できない場合も、カスタムの正確な ID を入力できます。保存済みのモデル選択が変更されることはありません。新しいモデル名の利用に新しい MCP リリースは不要ですが、モデルによっては、より新しいネイティブ CLI が必要になる場合があります。通常の互換性カナリアは引き続き独立しています。

モデルピッカーでモデルを追加または削除できるのは、明示的な操作を行った場合のみです。開いて適用するだけでは、編集しない限り既存の順序は変更されません。

runtime_list には config_revision が含まれます。ユーザーの承認後、そのリビジョンと新しいリクエスト ID を使用して runtime_configure でランタイムを設定します。

{
  "request_id": "choose-claude-model-1",
  "expected_revision": 7,
  "patch": {
    "runtimes": {
      "claude-code": {
        "options": {
          "variant.0.model": "claude-opus-5-5",
          "variant.0.reasoning.effort": "max"
        }
      }
    }
  }
}

この例では、既存のバリアントを変更します。新しいランタイムの場合は、enabled: true と、選択した ID および必要な推論オプションを含む options.model_priority を指定してください。設定画面と MCP は、同じ検証とリビジョンチェックを使用します。同一のリクエストを再度送ると、保存済みのレシートが返されます。入力が異なる場合は、新しいリクエスト ID が必要です。レシートがないまま変更が中断された場合は、次の変更を行う前に現在の状態を確認してください。このツールでプロジェクトの信頼設定を変更することはできず、認証、ライブカナリア、プロバイダータスクを自動的に開始することもありません。

プロバイダーがクォータまたはクレジットの枯渇を明示的に報告した場合（QUOTA_PAUSED）、Subagent MCP は今後のタスクで、該当するモデルを最下位に移動します。失敗したタスクは再試行しません。あいまいな失敗、クラッシュ、タイムアウトによってモデルの順序が変更されたり、別の有料リクエストが発生したりすることはありません。

失敗したタスクはそのまま終了しますが、次の明示的な委任ではプロバイダーを再度ライブで確認します。キャッシュ済みのリセット時刻や待機チェックポイントで、その確認を代替することはありません。ネイティブハーネスが安全なリクエスト前クォータエンドポイントを公開していない場合、クォータ状態は枯渇と推定せず、不明のままにします。

運用上の復旧は最大 3 アクションです。ローカル状態の操作と、プロバイダー呼び出し前に明示的に発生した失敗は再試行できます。DeepSeek では、一時的な上流 HTTP 429 が明示的に返された場合も、合計 3 回まで再試行します。一般的なプロバイダーの失敗が自動的に再実行されることはありません。読み取り専用タスクでは、新たに明示的な試行を行うための範囲を限定したガイダンスが返されます。一方、書き込みタスクでは、書き込み対象と想定される影響を照合するまで再試行できません。クォータ、クレジット、請求、タイムアウト、あいまいなライフサイクルの失敗によって、別のプロバイダー呼び出しが発生することはありません。ネイティブ ACP の失敗では、ハーネスが詳細を公開している場合、範囲を限定して機密情報を伏せた RPC／プロバイダー情報が含まれます。クォータが不明の場合はプロバイダーエラーであり、枯渇ではありません。

DeepSeek のルートでは、ユーザーが許可した既存のサブスクリプション、無制限プラン、またはチャージ済み残高を使用できます。Subagent MCP が残高を購入、チャージ、または増額することはありません。

レビュー権限とソースへの同意

agent_spawn は、タスクとネイティブハーネスが読み取ったソースを、選択された外部プロバイダーに送信します。required_capabilities が省略されているか null の場合、既定値は ["repo_read"] です。[] を含む明示的なリストはそのまま保持され、書き込み権限が推測されることはありません。runtime_list は各マニフェストの required_semantic_permissions を通知します。Claude と Grok には repo_read が必要です。

必須権限が不足している場合、ランタイムのプローブ、タスク入力の読み取り、実行の確定、プロバイダーの起動より前に、ローカルで REQUEST_INVALID が返されます。応答には recovery.action="repair"、reason="declare_required_permissions"、max_attempts=1 が含まれます。next_action に従ってください。必要なプロバイダーやソースへのアクセスがすでに許可されている場合に限り、新しい request_id を使ってペイロードを修正します。明示された制限を黙って置き換えてはいけません。この修正は、失敗したネイティブ実行の再生や、クォータ、認証、アクセス、ポリシー、起動状態が曖昧な場合の再試行を許可するものではありません。

コントローラーは、指定されたプロバイダーとソースの範囲に対する既存の許可を再利用してください。仕様のみのレビューで追加の非公開ソースが必要な場合は、ディスパッチする前に確認してください。たとえば、「読み取り専用レビューのため、選択したプロバイダーがこの仕様と指定されたソースフォルダーを読み取ることを許可しますか？」と尋ねます。ホストがサポートする承認ツールまたはユーザーへの質問ツールを使用し、ホストによる拒否の理由を説明し、質問を保留したままにして、回答を尊重してください。必要な承認なしに、拒否された呼び出しを繰り返してはいけません。task.inputs はファイルの識別情報を検証するものであり、読み取り用のサンドボックスでも同意の記録でもありません。ホストが MCP サーバーへの到達前に呼び出しを拒否した場合、MCP サーバーは質問を表示できません。また、チャットでの同意は OS／OAuth へのアクセスを許可するものではありません。

長時間実行される作業

agent_wait は範囲が限定されたローカルの状況確認であり、モデルの期限ではありません。wait_policy=continue_while_running とともに running が返された場合、外部エージェントは引き続き作業中、または思考中である可能性があります。同じ会話の状況確認を続けてください。経過時間だけを理由に、再試行、フォールバック、中断、または別のプロバイダーへのリクエストが実行されることはありません。

並行する書き込み元

書き込みタスクでは、リポジトリを基準とするファイルまたはディレクトリのルートを write_set に最大 32 個指定できます。正規化された絶対パスの集合が互いに重複しない場合、外部の書き込み元は並行して実行できます。同一のパスや親子関係にあるパスは競合します。タスク名とレーン名はロックに影響しません。

後方互換性のため、write_set を省略すると、実行はワークスペース全体を対象にします。各アダプターも、ネイティブハーネスの境界で正規化されたパスを適用します。書き込みリクエストを作成する前に runtime_list を確認してください。write_root_mode=path-prefix はファイルまたはディレクトリの正確なプレフィックスに対応し、existing-directory は既存のディレクトリを必要とします。現在の DeepSeek Harness のネイティブセッションが通知するモードは existing-directory で、書き込み可能なルートは 1 つです。Subagent MCP は、ファイルの正確なスコープを親ディレクトリに広げることはありません。より広いディレクトリを使うのは、それが明示的に許容される場合に限ります。それ以外の場合は、path-prefix を適用するランタイムを選択してください。複数の有効なディレクトリルートは、重複しない書き込み呼び出しに分割されます。これらのリースが調整するのは Subagent MCP の実行であり、無関係なローカルプロセスに対する OS サンドボックスではありません。

現在の Windows 公開スライスでは、cwd にチェックアウトルートを設定し、workspace="current" を使用してください。DeepSeek への書き込みでは workspace_write と、cwd を基準とする既存ディレクトリをちょうど 1 つ渡します。たとえば、write_set=["Assets/_Project/Core/Scripts/GameSettings"] のように指定します。絶対パス、存在しないパス、または正確なファイルは、有効な existing-directory ルートではありません。

Windows では、DeepSeek のネイティブサンドボックスで制限付きトークンの ACE を作成する必要があるため、現在のユーザーにも選択したディレクトリへの WRITE_DAC が必要です。Subagent MCP は、ACP やプロバイダー処理を開始する前に、この機能を読み取り専用で確認します。所有者や ACL は変更しません。確認に失敗すると CAPABILITY_MISSING のままとなり、danger-full-access にフォールバックすることはありません。

連携の仕組み

flowchart LR
    C["Codex<br/>Main agent & orchestrator"]
    M["Subagent MCP<br/>Gateway"]
    UI["Localhost UI<br/>Settings & activity"]

    C -->|"delegate · steer · observe"| M
    UI --> M

    subgraph E["External agent runtimes — adapter-driven"]
        R1["Model<br/>+<br/>native harness"]
        R2["Model<br/>+<br/>native harness"]
        RN["Future runtimes<br/>via adapters"]
    end

    M -->|"normalized lifecycle"| R1
    M -->|"normalized lifecycle"| R2
    M -->|"normalized lifecycle"| RN

Subagent MCP は、ライフサイクルの正規化、ステータス、秘匿化、リース、サーキットを管理します。各アダプターは、その契約をネイティブハーネス向けに変換します。契約の全容については、アーキテクチャを参照してください。

Windows での更新またはロールバック

実行中の可能性がある環境を再インストールせずに、バージョンを切り替えます。最初のコマンドでは切り替え元のバージョンを、追加／起動コマンドでは切り替え先のバージョンを使用します。次の例では、1.0.30 から 1.0.31 にアップグレードします。

uvx --isolated --from subagent-harness-mcp==1.0.30 subagent-harness-mcp ui --stop
codex mcp remove subagent-mcp
codex mcp add subagent-mcp -- uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp serve
uvx --isolated --from subagent-harness-mcp==1.0.31 subagent-harness-mcp ui --background

エントリーを変更した後、新しい Codex タスクを開始してください。既存のタスクは終了するまで、古いランタイムを使い続けます。ロールバックする場合は、バージョンを正確に逆にして同じ手順を使用してください。

すでに実行中の MCP が UPDATE_QUARANTINED を返している場合、置き換えを安全にホットロードすることはできません。その常駐プロセスを再試行しないでください。ネイティブのフォールバックで処理を完了し、新しい正確な登録は新しいタスクから使用してください。

subagent-harness-mcp serve を直接指定するエントリーから一度だけ移行する場合は、まず登録を置き換え、レガシータスクが自然に終了するのを待ってください。置き換えた後、使用されなくなった永続ツールを任意で削除する前に、Codex のウィンドウをすべて一度閉じてください。インストールしたままでも問題ありません。上記の新しいコマンドはすべて uvx --isolated を使用するためです。

Subagent MCP は、Codex の設定を編集したり、Codex／プロバイダーのプロセスを強制終了したり、uv キャッシュを独自に消去したりすることはありません。

安全性と課金

• Subagent MCP は、利用クレジットを有効にしたり、課金設定を変更したりすることはありません。
• Claude のタスクでは、サブスクリプションに含まれる利用枠を消費する場合があります。各タスクでは、出力を受け入れる前に、バインドされた CLI、サブスクリプション認証、認証情報の優先順位、制御接続を検証し、同じ応答から安全なレートの証拠を確認します。
• Provider Refresh はモデルプロンプトを送信しません。ネイティブハーネスが応答前に正確なレートの証拠を提示できない場合、クォータの結果を捏造したりリセット時刻を使用したりせず、ステータスは不明のままになります。
• フォールバックは、クォータの枯渇が明示された場合にのみ発生します。安全でない、または曖昧な証拠によって、有料リクエストが再度行われることはありません。
• ネイティブのトランスクリプトは、ネイティブハーネスが所有します。製品の状態は明示的に指定されたローカルルート内に保持され、エージェントの出力は信頼できない助言として扱う必要があります。

書き込みアクセスを有効にする前に、セキュリティと脅威モデルをお読みください。

プロジェクト

• アーキテクチャ
• アダプターの作成
• コントリビューション
• 変更履歴
• MIT ライセンス