# 機能設計書 17-TodoWrite ツール

## 概要

本ドキュメントは、OpenCodeのTodoWrite ツール機能の設計仕様を定義する。TodoWrite ツールは、セッション内のタスクリスト（Todo）を更新し、タスクの進捗管理を行う機能を担う。

### 本機能の処理概要

TodoWrite ツールは、指定されたタスクリストでセッションのTodo情報を更新する機能である。タスクの追加、ステータス変更、優先度設定などを行い、エージェントの作業進捗を可視化する。

**業務上の目的・背景**：複雑なマルチステップタスクを処理する際、進捗状況を明確に追跡することで、エージェントの作業効率と透明性を向上させる。本ツールにより、ユーザーは現在の作業状況を把握でき、エージェントは体系的にタスクを管理できる。

**機能の利用シーン**：
- 複数ステップを含むタスクの管理
- 実装作業の進捗追跡
- ユーザーから指示された複数タスクの整理
- 作業完了状況の報告

**主要な処理内容**：
1. 書き込み権限の確認
2. Todoデータの更新
3. イベントの発行
4. 結果の返却

**関連システム・外部連携**：
- Todo：Todoデータ管理
- Bus：イベント発行

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

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | セッション | 補助機能 | TodoWriteコンポーネントによるタスクリスト表示 |

## 機能種別

データ更新 / 状態管理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| todos | array | Yes | 更新するタスクリスト | Todo.Info配列 |
| todos[].content | string | Yes | タスクの内容（簡潔な説明） | 空文字列不可 |
| todos[].status | string | Yes | タスクのステータス: pending, in_progress, completed, cancelled | 有効なステータス値 |
| todos[].priority | string | Yes | タスクの優先度: high, medium, low | 有効な優先度値 |

### 入力データソース

- エージェントによるタスク分析結果
- 実行コンテキスト（セッションID、メッセージID等）

## 出力仕様

### 出力データ

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

### 出力先

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

## 処理フロー

### 処理シーケンス

```
1. 書き込み権限確認
   └─ ctx.askでtodowrite権限を要求

2. Todoデータ更新
   └─ Todo.updateでデータベースを更新

3. イベント発行
   └─ Todo.Event.Updatedを発行

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

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[書き込み権限確認]
    B --> C[Todoデータ更新]
    C --> D[イベント発行]
    D --> E[未完了タスク数計算]
    E --> F[結果返却]
    F --> OUTPUT[結果返却]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | 全件更新 | Todoリストは毎回全件更新（差分更新ではない） | 常時 |
| BR-02 | タスク数制限 | 同時進行タスクは1つに制限することが推奨 | 運用ガイドライン |
| BR-03 | ステータス遷移 | pending → in_progress → completed/cancelled | 推奨フロー |
| BR-04 | 位置保持 | タスクは配列内の位置（position）で順序付け | 常時 |

### 計算ロジック

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

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| Todo更新 | TodoTable | DELETE + INSERT | 既存レコードを削除後、新規レコードを挿入 |

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

#### TodoTable

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| DELETE | session_id | 対象セッションID | 既存Todo全削除 |
| INSERT | session_id | セッションID | - |
| INSERT | content | タスク内容 | - |
| INSERT | status | ステータス | pending/in_progress/completed/cancelled |
| INSERT | priority | 優先度 | high/medium/low |
| INSERT | position | 配列インデックス | 順序保持用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | PermissionError | todowrite権限がない | 適切な権限を付与 |
| - | ValidationError | todosの形式が不正 | 正しい形式で指定 |

### リトライ仕様

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

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

DELETE + INSERT は同一トランザクション内で実行される。

## パフォーマンス要件

- 特に制限なし

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

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

## 備考

- タスクリストは毎回全件更新されるため、既存のタスクを保持する場合は全て含める必要がある
- ステータスは pending（未着手）、in_progress（作業中）、completed（完了）、cancelled（キャンセル）の4種類
- 優先度は high（高）、medium（中）、low（低）の3段階

---

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

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

### 推奨読解順序

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

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

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

**読解のコツ**: content, status, priorityの3フィールドがTodoの基本構造。

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

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

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

**主要処理フロー**:
1. **8-9行目**: パラメータスキーマ（todos配列）
2. **12-17行目**: 権限確認
3. **19-22行目**: Todo.updateによるデータ更新
4. **23-29行目**: 結果フォーマット

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

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

**主要処理フロー**:
- **28行目**: Database.transactionでトランザクション開始
- **29行目**: 既存Todoを全削除
- **31-40行目**: 新規Todoを挿入
- **43行目**: イベント発行

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

```
TodoWriteTool.execute
    │
    ├─ ctx.ask (todowrite権限要求)
    │
    └─ Todo.update
           │
           ├─ Database.transaction
           │      ├─ DELETE (既存Todo削除)
           │      └─ INSERT (新規Todo挿入)
           │
           └─ Bus.publish (Todo.Event.Updated)
```

### データフロー図

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

todos[] ──────────────────▶ 権限確認
                                │
                                ▼
                           トランザクション開始
                                │
                                ▼
                           既存Todo削除
                                │
                                ▼
                           新規Todo挿入
                                │
                                ▼
                           イベント発行
                                │
                                ▼
                           結果返却 ─────────▶ title
                                              output
                                              metadata.todos
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| todo.ts | `packages/opencode/src/tool/todo.ts` | ソース | TodoWrite/TodoRead ツール本体 |
| todowrite.txt | `packages/opencode/src/tool/todowrite.txt` | テンプレート | ツール説明文 |
| 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スキーマ定義 |
