# 機能設計書 18-TodoRead ツール

## 概要

本ドキュメントは、OpenCodeのTodoRead ツール機能の設計仕様を定義する。TodoRead ツールは、セッション内のタスクリスト（Todo）を読み取り、現在のタスク状態を確認する機能を担う。

### 本機能の処理概要

TodoRead ツールは、現在のセッションに関連付けられたTodo情報を取得し、その内容をJSON形式で返却する機能である。タスクの進捗確認や状態把握に使用される。

**業務上の目的・背景**：エージェントが現在のタスク状況を把握し、次に実行すべき作業を判断するために、Todoリストの読み取り機能が必要である。本ツールにより、エージェントは自身が管理しているタスクの状態を確認できる。

**機能の利用シーン**：
- 現在のタスク進捗状況の確認
- 次に実行すべきタスクの特定
- 完了済みタスクの確認
- タスクリストの整合性チェック

**主要な処理内容**：
1. 読み取り権限の確認
2. Todoデータの取得
3. 結果の返却

**関連システム・外部連携**：
- Todo：Todoデータ管理

**権限による制御**：
- `todoread`権限が必要

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | 直接的な画面関連なし |

## 機能種別

データ読み取り / 状態確認

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| - | - | - | パラメータなし | - |

### 入力データソース

- 実行コンテキスト（セッションID）

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| title | string | "{未完了タスク数} todos" |
| output | string | タスクリストのJSON文字列 |
| metadata.todos | array | 取得されたタスクリスト |

### 出力先

- エージェントへのレスポンス（ツール実行結果）

## 処理フロー

### 処理シーケンス

```
1. 読み取り権限確認
   └─ ctx.askでtodoread権限を要求

2. Todoデータ取得
   └─ Todo.getでデータベースから取得

3. 結果返却
   └─ 未完了タスク数とJSON出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[読み取り権限確認]
    B --> C[Todoデータ取得]
    C --> D[未完了タスク数計算]
    D --> E[結果返却]
    E --> OUTPUT[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | セッション単位 | Todoはセッション単位で管理される | 常時 |
| BR-02 | 順序保持 | Todoはposition順にソートされて返却 | 常時 |

### 計算ロジック

**未完了タスク数の計算**：
```javascript
todos.filter((x) => x.status !== "completed").length
```

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Todo取得 | TodoTable | SELECT | セッションIDでTodoを取得 |

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

#### TodoTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | session_id | 対象セッションID | - |
| ORDER BY | position | ASC | 順序保持 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | PermissionError | todoread権限がない | 適切な権限を付与 |

### リトライ仕様

本機能はリトライ処理を行わない。エラー発生時は即座にエラーを返却する。

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

読み取りのみのためトランザクション管理は不要。

## パフォーマンス要件

- 特に制限なし

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

- todoread権限による実行制御
- 子セッションではデフォルトで禁止（Task ツールの仕様）

## 備考

- Todoが存在しない場合は空配列が返却される
- TodoWriteツールと組み合わせて使用することが想定される

---

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

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

### 推奨読解順序

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

Todo情報のスキーマを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | todo.ts | `packages/opencode/src/session/todo.ts` | Todo.Infoスキーマ（8-14行目）を確認 |

**読解のコツ**: TodoWriteツールと同じデータ構造を使用。

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

TodoRead ツールの本体実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | todo.ts | `packages/opencode/src/tool/todo.ts` | TodoReadTool定義（33-53行目） |

**主要処理フロー**:
1. **34行目**: ツール説明
2. **35行目**: 空のパラメータスキーマ
3. **37-42行目**: 権限確認
4. **44行目**: Todo.getによるデータ取得
5. **45-50行目**: 結果フォーマット

#### Step 3: Todoデータ取得を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | session/todo.ts | `packages/opencode/src/session/todo.ts` | Todo.get関数（46-55行目） |

**主要処理フロー**:
- **47-48行目**: Database.useでSELECT実行
- **48行目**: position順でソート
- **50-54行目**: 結果のマッピング

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

```
TodoReadTool.execute
    │
    ├─ ctx.ask (todoread権限要求)
    │
    └─ Todo.get
           │
           └─ Database.use
                  └─ SELECT from TodoTable
```

### データフロー図

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

ctx.sessionID ────────────▶ 権限確認
                                │
                                ▼
                           データベース検索
                           (session_id, position順)
                                │
                                ▼
                           結果マッピング
                                │
                                ▼
                           結果返却 ─────────▶ title
                                              output
                                              metadata.todos
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| todo.ts | `packages/opencode/src/tool/todo.ts` | ソース | TodoWrite/TodoRead ツール本体 |
| tool.ts | `packages/opencode/src/tool/tool.ts` | ソース | ツール基盤定義 |
| session/todo.ts | `packages/opencode/src/session/todo.ts` | ソース | Todoデータ管理 |
| session.sql.ts | `packages/opencode/src/session/session.sql.ts` | ソース | TodoTableスキーマ定義 |
