# 機能設計書 3-General サブエージェント

## 概要

本ドキュメントは、OpenCodeシステムにおけるGeneral サブエージェントの機能設計を記述する。General サブエージェントは、複雑な検索やマルチステップタスクを実行する汎用エージェントであり、並列で複数の作業単位を実行可能である。

### 本機能の処理概要

General サブエージェントは、Task ツールを通じてメインエージェント（Build/Plan）から呼び出され、複雑なタスクを独立したコンテキストで実行する。子セッションを作成して特定のタスクを遂行し、結果を親セッションに返却する。

**業務上の目的・背景**：大規模なタスクを効率的に処理するため、複数の独立したサブタスクに分割し、並列実行することで処理時間を短縮する。また、複雑な調査タスクをサブエージェントに委譲することで、メインエージェントのコンテキストを汚染せずにタスクを実行できる。

**機能の利用シーン**：複数ファイルの同時調査、マルチステップの変更タスク、複雑なリサーチクエリの実行など。例えば「複数のモジュールを並列で調査して結果をまとめて」「それぞれのテストファイルを個別に実行して」などの指示で利用される。

**主要な処理内容**：
1. 親セッションからのタスク委譲受信
2. 子セッションの作成
3. 独立したコンテキストでのタスク実行
4. 複数のサブタスクの並列実行（可能な場合）
5. 結果の集約と親セッションへの返却

**関連システム・外部連携**：メインエージェントとはTask ツールを介して連携。LSPやその他のツール群へのアクセスは親エージェントの権限を継承。

**権限による制御**：General サブエージェントは、デフォルト権限を継承しつつ、todoread/todowrite権限がdenyに設定されている。これは、サブエージェントがメインセッションのTodoリストを操作することを防止するためである。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | セッション | 補助画面 | Taskコンポーネントによるサブエージェントタスク表示 |

## 機能種別

タスク委譲 / 並列処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| name | string | Yes | エージェント名（"general"固定） | 文字列型 |
| description | string | Yes | エージェントの説明 | 任意の文字列 |
| mode | "subagent" \| "primary" \| "all" | Yes | エージェントのモード（"subagent"） | enum値 |
| native | boolean | No | ネイティブエージェントかどうか（true） | boolean型 |
| permission | PermissionNext.Ruleset | Yes | 権限ルールセット | 有効なルールセット配列 |
| options | Record<string, any> | No | 追加オプション | オブジェクト型 |

### 入力データソース

- Task ツールからのタスク指示
- 親セッションのコンテキスト情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| output | string | タスク実行結果のテキスト |
| metadata | object | 実行メタデータ |
| sessionID | string | 子セッションのID |

### 出力先

- 親セッションへの結果返却
- 子セッションデータベース

## 処理フロー

### 処理シーケンス

```
1. Task ツールからの呼び出し
   └─ タスク内容と使用エージェントの指定受信
2. 子セッション作成
   └─ Session.create()で独立したセッションを作成
3. タスク実行
   └─ 指定されたタスクを実行（ツール呼び出し含む）
4. 結果の生成
   └─ テキスト応答と実行結果のメタデータ作成
5. 親セッションへの返却
   └─ Task ツール結果として結果を返却
```

### フローチャート

```mermaid
flowchart TD
    A[Task ツール呼び出し] --> B[Generalサブエージェント選択]
    B --> C[子セッション作成]
    C --> D[タスク実行開始]
    D --> E{ツール呼び出し?}
    E -->|Yes| F[権限チェック]
    F --> G[ツール実行]
    G --> H[結果処理]
    H --> E
    E -->|No| I[テキスト応答生成]
    I --> J[結果集約]
    J --> K[親セッションへ返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | サブエージェントモード | modeが"subagent"として定義され、直接選択不可 | 常時 |
| BR-02 | Todo操作禁止 | todoread/todowrite権限がdenyでTodoリスト操作不可 | 常時 |
| BR-03 | 独立コンテキスト | 子セッションは親セッションとは独立したコンテキストを持つ | タスク実行時 |
| BR-04 | 権限継承 | デフォルト権限は親エージェントから継承 | タスク実行時 |

### 計算ロジック

特になし

## データベース操作仕様

### 操作別データベース影響一覧

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 子セッション作成 | session | INSERT | 子セッションレコードの作成 |
| メッセージ保存 | message | INSERT/UPDATE | サブタスク実行結果の保存 |

### テーブル別操作詳細

#### session

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | parent_id | 親セッションID | 子セッション関係 |
| INSERT | agent | "general" | サブエージェント名 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | RejectedError | ユーザーがツール実行を拒否 | 親セッションにエラー返却 |
| - | タイムアウト | タスク実行時間超過 | タイムアウトエラー返却 |

### リトライ仕様

サブエージェント内でのリトライは通常のエージェントと同様。

## トランザクション仕様

子セッションの操作は独立したトランザクションで実行。

## パフォーマンス要件

- 並列タスク実行により処理時間を短縮
- 子セッションのオーバーヘッドを最小化

## セキュリティ考慮事項

- Todo操作の禁止によりメインセッション状態の保護
- 権限継承により親エージェントと同等のセキュリティレベル維持

## 備考

General サブエージェントは、Task ツールの`agent`パラメータで"general"を指定することで呼び出される。複数のGeneralサブエージェントを並列で起動することも可能。

---

## コードリーディングガイド

本機能を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

Generalサブエージェントの設定とTask ツールの関係を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | agent.ts | `packages/opencode/src/agent/agent.ts` | generalエージェント定義（115-129行目） |
| 1-2 | task.ts | `packages/opencode/src/tool/task.ts` | Task ツールの実装でサブエージェント呼び出し方法を理解 |

**読解のコツ**: mode: "subagent"が設定されていることで、直接選択ではなくTask ツール経由でのみ利用可能であることを把握。

#### Step 2: エントリーポイントを理解する

Task ツールからの呼び出しフローを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | task.ts | `packages/opencode/src/tool/task.ts` | Task ツールのexecute関数で子セッション作成を理解 |

**主要処理フロー**:
1. **Task ツール呼び出し**: agent: "general"パラメータでGeneralサブエージェントを指定
2. **子セッション作成**: Session.create()で独立したセッションを作成
3. **タスク実行**: 子セッション内でLLMストリーミング処理
4. **結果返却**: Task ツール結果として親セッションに返却

#### Step 3: 権限設定を理解する

Todo操作禁止の設定を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | agent.ts | `packages/opencode/src/agent/agent.ts` | generalエージェントの権限設定（118-124行目） |

**主要処理フロー**:
- **118-124行目**: permission設定でtodoread: deny、todowrite: denyを確認

### プログラム呼び出し階層図

```
Task ツール呼び出し [task.ts]
    │
    ├─ Agent.get("general") [agent.ts]
    │      └─ Generalサブエージェント設定取得
    │
    ├─ Session.create() [session/index.ts]
    │      └─ 子セッション作成（parent_id設定）
    │
    └─ Session.chat() [session/index.ts]
           │
           ├─ LLM.stream() [llm.ts]
           │
           └─ processor.process() [processor.ts]
                  │
                  └─ 結果返却 → Task ツール結果
```

### データフロー図

```
[入力]                    [処理]                         [出力]

親セッション
    │
    └──▶ Task ツール
              │
              ├──▶ agent: "general"
              │
              └──▶ 子セッション作成
                        │
                        ├──▶ Generalサブエージェント
                        │         │
                        │         ├──▶ ツール実行
                        │         │
                        │         └──▶ テキスト応答
                        │
                        └──▶ 結果集約
                                  │
                                  └──▶ 親セッションへ返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| agent.ts | `packages/opencode/src/agent/agent.ts` | ソース | Generalサブエージェント定義（115-129行目） |
| task.ts | `packages/opencode/src/tool/task.ts` | ソース | Task ツール（サブエージェント呼び出し） |
| index.ts | `packages/opencode/src/session/index.ts` | ソース | セッション作成・管理 |
| llm.ts | `packages/opencode/src/session/llm.ts` | ソース | LLMストリーミング処理 |
| processor.ts | `packages/opencode/src/session/processor.ts` | ソース | ストリームイベント処理 |
