pi-subagent

Pi CLI（@earendil-works/pi-coding-agent）をプログラム可能なコーディングサブエージェントに変えます。あらゆるMCPホスト（ZCode、Claude Code、Cursorなど）がタスクを委任し、セッションを追跡し、プロセスを強制終了できるようにします。

pi-subagent は、pi -p --mode json を7つの構造化ツールにラップする軽量なMCPサーバーです。タスクの委任、結果の収集、スケジューリング判断、名前付きセッションの管理、実行の中断を行います。プロセス分離、完全セッションベース、同期/非同期のデュアルモードを備えています。

なぜ

Pi は最小限のターミナルコーディングエージェントです。Pi に方法論を教えるのではなく、このプロジェクトは Pi を委任可能なワーカーとして扱います。ホストエージェント（ZCode / Claude Code）がいつ委任するかを決定し、自己完結型のタスクを発火し、結果を収穫します。1つのPiプロセス = 1つの分離されたサブエージェント実行です。

• プロセス分離 — 各委任は1つの pi -p 子プロセスを生成します。Pi がクラッシュしても、その実行のみに影響します。

• 完全セッションベース — すべてのタスクは名前付きセッション（例: feat-auth）にバインドされ、後続の呼び出しは自動的に継続されます。

• 同期 / 非同期 — デフォルトは async（ホストのツール呼び出しタイムアウトを回避）。pi_status のロングポーリングで収穫します。

• スケジュール可能 — pi_plan は純粋な5段階の決定関数（reject / capacity / reuse / modify / mode）で、完全にユニットテストされています。

• ユニバーサルMCP — 標準的なMCPクライアントならどれでも読み込めます。

Related MCP server: cursor-agent-bridge

アーキテクチャ

┌─────────────────────────────────────────────────────────────┐
│  MCP Host (ZCode / Claude Code / Pi / Cursor …)              │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP (JSON-RPC over stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│  pi-subagent-server  (Node/TS)                                │
│  ┌────────────┐  ┌──────────────┐  ┌────────────────────┐   │
│  │ Tool layer │  │ Session      │  │ Pi runner          │   │
│  │ (7 tools)  │─▶│ registry     │─▶│ (spawn pi -p)      │   │
│  │ + plan()   │  │ + persist    │  │ parse agent_end    │   │
│  └─────┬──────┘  │ + _snapshot  │  │ + tool_execution   │   │
│        │         └──────────────┘  └─────────┬──────────┘   │
│        │                           ┌────────▼─────────┐     │
│        └───────────────────────────│ Run registry     │     │
│           (kill)                   │ + process-table  │     │
│                                   └──────────────────┘     │
└─────────────────────────────────────────────────────────────┘
                            │ child_process.spawn({ cwd })
                            ▼
                   ┌─────────────────────┐
                   │  pi CLI (0.77+)     │
                   └─────────────────────┘

明確な境界を持つ3つのレイヤー: ツールレイヤー（MCPスキーマ + plan() 純粋関数） / セッションレジストリ（状態 + 永続化 + 編集） / ランナー（pi の生成、NDJSONの解析、プロセステーブル）。

ツール

レビューループ: pi_task_plan の後、pi_status(runId) で収穫します。実行が完了すると、サーバーはそれがレビュー実行であることを検出し、_plan-reviewed.md を解析して、planVerdict / planReviewedPath をタスクに保存します。ステージのプロンプトには、レビュー済みプランと、合格した依存ステージの出力ファイルが自動的に含まれます。

非同期ステージ: pi_task_stage_run に mode: "async" を渡すと、実行全体でツール呼び出しをブロックしません（MCPホストが短いツールタイムアウトを強制する場合に推奨）。pi_task_stage_collect(taskId, stageId) で収穫します。失敗した試行は、履歴の汚染を避けるために新しいセッション名で再ディスパッチされます。3回失敗すると、ステージは manual になり、決定パネルが表示されます（retry_with_new_hint は promptHintOverride でサポート）。

再起動リカバリ: 同じ taskId で pi_task_create を再実行すると、競合せずにマージされます。出力ファイルがすでに存在し検証に合格したステージは自動的に passed とマークされるため、中断されたタスクは tasks.json を手動編集せずに再開できます。

セッションモデル

• 各セッションには、人間が読める名前 + Pi の UUID + cwd + goal があります。

• 最初の pi_delegate がセッションを作成します（goal 必須）。以降の呼び出しは自動的に継続されます。

• レジストリは ~/.pi-subagent/registry.json に永続化されます（アトミック書き込み。再起動時、中断された running レコードは error に修正されます）。

• 同時実行上限: 4 つの実行中。単一セッションが同時に実行されることはありません。

• タスクは ~/.pi-subagent/tasks.json に永続化されます（アトミック書き込み。再起動時、実行中のステージは failed(interrupted_by_restart) に修正されます）。

インストール

git clone <this-repo> && cd pi-subagent
npm install

前提条件: pi CLI がインストールされ（npm i -g @earendil-works/pi-coding-agent）、PATH に含まれていること。

MCPホストの設定

MCPクライアント設定に追加:

{
  "mcpServers": {
    "pi-subagent": {
      "command": "npx",
      "args": ["tsx", "/abs/path/to/pi-subagent/src/server.ts"]
    }
  }
}

オプションの環境変数:

• PI_SUBAGENT_REGISTRY — レジストリパス（デフォルト ~/.pi-subagent/registry.json）

• PI_BIN — pi 実行可能ファイルを上書き（テストで使用）

テスト

npm test           # full suite (140 tests)
npm run test:fast  # dot reporter

テストは偽の pi（test/fixtures/fake-pi.sh）を使用し、以下をカバー: 非同期/同期、タイムアウト、強制終了、セッション作成失敗、複数待機者、進捗上限、スケジューリングルール（テーブル駆動 + 100回反復のプロパティテスト）、レジストリ永続化、編集など。

プロジェクトレイアウト

src/
├── types.ts                 # all shared types + error codes
├── errors.ts                # ToolError helpers
├── runner/                  # parse.ts, argv.ts, spawn.ts, process-table.ts
├── registry/                # session.ts, run.ts, persist.ts, redact.ts
├── scheduler/               # keywords.ts, plan.ts (5-stage pure function)
├── tools/                   # delegate, status, plan-tool, session, kill
└── server.ts                # MCP entry (stdio)
skills/pi-subagent/          # SKILL.md + delegation-patterns (strategy layer)
test/                        # fixtures/ + *.test.ts
docs/                        # design.md (spec) + implementation-plan.md

設計とプロセス

このプロジェクトは、実装前に共同設計と4回の外部レビューを経ています。仕様と計画は docs/ にコミットされています:

• docs/design.md — 完全な設計仕様（アーキテクチャ、ツール契約、エラーハンドリング、スケジューラールール、テスト戦略）。すべての契約はレビューノート（R1–R4）にトレース可能です。

• docs/implementation-plan.md — 19のTDDタスク（失敗するテストを書く → 実装 → 合格 → コミット）。

主要な設計決定は、すべて pi -p 出力の実際の調査と外部レビューに裏付けられています:

• cwd ≠ セッションストレージ — spawn({ cwd }) は作業ディレクトリを制御します。Pi のセッションファイルはデフォルトの場所を使用します（プロジェクトを汚染しません）。

• 非同期デフォルト + ハンドシェイク — 新しいセッションは、戻る前に Pi の session イベントを待ちます（sessionStartTimeoutMs 付き）。これにより、ホストは常に実際の piSessionId を取得します。

• マルチステージスケジューラ — plan() は reject → capacity → reuse → modify → mode の順で、修飾子は最初に一致するのではなく積み重なります（レビューラウンド1からの教訓）。

• 進捗の編集 — ツール結果は、保存前にトークン/キーが切り詰められ、スクラブされます。

ステータス

実装済み、140のテストが合格。まだ npm に公開されていません — tsx でソースから実行します。

ライセンス

MIT