# 機能設計書 8-Bash ツール

## 概要

本ドキュメントは、OpenCodeシステムにおけるBash ツールの機能設計を記述する。Bash ツールは、シェルコマンドを実行する機能を提供し、タイムアウト設定、作業ディレクトリ指定、外部ディレクトリアクセスの権限管理に対応している。

### 本機能の処理概要

Bash ツールは、エージェントがシステムコマンドを実行するための基盤機能を提供する。git、npm、docker等のターミナル操作が可能であり、コマンドのパース、権限チェック、プロセス管理、出力のストリーミングを行う。

**業務上の目的・背景**：開発作業において、ビルド、テスト、バージョン管理、パッケージ管理などのコマンドライン操作は不可欠である。Bash ツールは、これらの操作をエージェントが安全に実行できるようにし、開発者の作業を自動化する。

**機能の利用シーン**：gitコマンドの実行（git status, git commit等）、npmコマンドの実行（npm install, npm test等）、ビルドコマンドの実行、ファイル操作コマンドの実行など。

**主要な処理内容**：
1. コマンド文字列のパース（tree-sitter-bashによる構文解析）
2. 外部ディレクトリアクセスの検出と権限チェック
3. コマンドパターンに基づく権限チェック
4. シェルプロセスの起動と実行
5. 出力のリアルタイムストリーミング
6. タイムアウト処理とプロセス終了

**関連システム・外部連携**：Shell.acceptable()でシステムのシェル（bash/zsh等）を自動検出。Plugin.trigger("shell.env")でプラグインによる環境変数のカスタマイズが可能。

**権限による制御**：bash権限でコマンドパターンをチェック。外部ディレクトリへのアクセスはexternal_directory権限で制御。プロジェクト外へのファイル操作は明示的な許可が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 26 | セッション | 補助機能 | Bashコンポーネントによるシェルコマンド実行結果表示 |

## 機能種別

コマンド実行 / シェル操作

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| command | string | Yes | 実行するコマンド | 文字列型 |
| timeout | number | No | タイムアウト（ミリ秒） | 正の数値、デフォルト120000ms |
| workdir | string | No | 作業ディレクトリ | 有効なディレクトリパス |
| description | string | Yes | コマンドの説明（5-10語） | 文字列型 |

### 入力データソース

- エージェントからのツール呼び出し

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| output | string | コマンドの標準出力と標準エラー出力 |
| exit | number | 終了コード |
| description | string | コマンドの説明 |

### 出力先

- ツール結果としてエージェントに返却
- メタデータとしてUIにストリーミング

## 処理フロー

### 処理シーケンス

```
1. コマンド受信
   └─ command、timeout、workdirパラメータの取得
2. コマンドパース
   └─ tree-sitter-bashで構文解析
3. ディレクトリ権限チェック
   └─ プロジェクト外のディレクトリアクセスをチェック
4. コマンド権限チェック
   └─ bashパーミッションでコマンドパターンをチェック
5. プロセス起動
   └─ spawn()でシェルプロセスを起動
6. 出力ストリーミング
   └─ stdout/stderrをリアルタイムで収集
7. プロセス終了待機
   └─ タイムアウトまたは正常終了を待機
8. 結果返却
   └─ 出力とメタデータを返却
```

### フローチャート

```mermaid
flowchart TD
    A[コマンド受信] --> B[tree-sitter-bashでパース]
    B --> C{外部ディレクトリ?}
    C -->|Yes| D[external_directory権限チェック]
    C -->|No| E[コマンド権限チェック]
    D -->|許可| E
    D -->|拒否| F[エラー返却]
    E -->|許可| G[プロセス起動]
    E -->|要確認| H[ユーザー確認]
    H -->|許可| G
    H -->|拒否| F
    G --> I[出力ストリーミング]
    I --> J{タイムアウト?}
    J -->|No| K{プロセス終了?}
    J -->|Yes| L[プロセス強制終了]
    K -->|No| I
    K -->|Yes| M[結果返却]
    L --> M
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-01 | デフォルトタイムアウト | 指定なしの場合120000ms（2分） | timeout未指定時 |
| BR-02 | 作業ディレクトリ | デフォルトはInstance.directory | workdir未指定時 |
| BR-03 | 外部ディレクトリ検出 | cd, rm, cp, mv, mkdir, touch, chmod, chown, catコマンドのパスを解析 | ファイル操作コマンド |
| BR-04 | 出力截断 | MAX_LINESまたはMAX_BYTES超過時に截断 | 大量出力時 |
| BR-05 | メタデータ制限 | メタデータは30,000文字まで | 出力ストリーミング時 |
| BR-06 | cdの代替 | "cd && command"パターンの代わりにworkdirパラメータ使用を推奨 | 常時 |

### 計算ロジック

- タイムアウト: DEFAULT_TIMEOUT = 2 * 60 * 1000 (120000ms)
- MAX_METADATA_LENGTH = 30,000

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ツール結果保存 | message_part | UPDATE | 実行結果のメタデータ保存 |

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

#### message_part

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| UPDATE | state.output | コマンド出力 | リアルタイム更新 |
| UPDATE | state.metadata.exit | 終了コード | プロセス終了時 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | パースエラー | コマンド構文エラー | エラーメッセージ返却 |
| - | DeniedError | 権限ルールによる拒否 | エラーメッセージ返却 |
| - | RejectedError | ユーザーによる拒否 | エラーメッセージ返却 |
| - | タイムアウト | 実行時間超過 | プロセス終了、メタデータに記録 |
| - | アボート | ユーザーによる中断 | プロセス終了、メタデータに記録 |

### リトライ仕様

コマンド実行はリトライなし。失敗時はエラー状態を返却。

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

ファイル操作コマンドの実行は、コマンド自体のアトミック性に依存。

## パフォーマンス要件

- 出力のリアルタイムストリーミング
- 大量出力時の自動截断
- タイムアウトによるハングアップ防止

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

- 外部ディレクトリアクセスの権限チェック
- コマンドパターンに基づく権限制御
- 環境変数の管理（プラグインによるカスタマイズ可能）

## 備考

Bash ツールは、ファイル操作にはRead/Edit/Writeツールの使用を推奨している。grep、cat、head、tail、sed、awk、echoなどは専用ツールの使用が推奨される。

---

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

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

### 推奨読解順序

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

Bashツールのパラメータスキーマと出力構造を理解。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | bash.ts | `packages/opencode/src/tool/bash.ts` | BashTool定義とパラメータスキーマ（55-77行目） |
| 1-2 | tool.ts | `packages/opencode/src/tool/tool.ts` | Tool.define()の基盤構造 |

**読解のコツ**: zodスキーマでパラメータを定義し、execute関数で実行処理を行う構造を理解する。

#### Step 2: コマンドパースを理解する

tree-sitter-bashによるコマンド解析を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | bash.ts | `packages/opencode/src/tool/bash.ts` | parser()関数（33-52行目）でtree-sitterセットアップ |

**主要処理フロー**:
1. **33-52行目**: tree-sitter-bashのWASM初期化
2. **84行目**: parser().then((p) => p.parse(params.command))でコマンドパース
3. **93-141行目**: コマンドノードを走査してディレクトリとパターンを抽出

#### Step 3: 権限チェックを理解する

外部ディレクトリとコマンドパターンの権限チェックを把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | bash.ts | `packages/opencode/src/tool/bash.ts` | 権限チェック処理（144-165行目） |

**主要処理フロー**:
- **144-156行目**: external_directory権限チェック
- **158-165行目**: bash権限チェック（コマンドパターン）

#### Step 4: プロセス実行を理解する

シェルプロセスの起動と出力管理を把握。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | bash.ts | `packages/opencode/src/tool/bash.ts` | プロセス起動と出力処理（167-272行目） |

**主要処理フロー**:
- **167-170行目**: Plugin.trigger("shell.env")で環境変数取得
- **172-181行目**: spawn()でプロセス起動
- **193-201行目**: 出力のストリーミングとメタデータ更新
- **225-247行目**: タイムアウトとプロセス終了待機

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

```
BashTool.execute() [bash.ts]
    │
    ├─ parser() → tree-sitter-bash
    │      └─ コマンド構文解析
    │
    ├─ ctx.ask({permission: "external_directory"})
    │      └─ 外部ディレクトリ権限チェック
    │
    ├─ ctx.ask({permission: "bash"})
    │      └─ コマンドパターン権限チェック
    │
    ├─ Plugin.trigger("shell.env")
    │      └─ 環境変数カスタマイズ
    │
    ├─ spawn(command, {shell, cwd, env})
    │      └─ シェルプロセス起動
    │
    └─ 出力ストリーミング
           │
           ├─ stdout.on("data")
           │
           ├─ stderr.on("data")
           │
           └─ ctx.metadata() → UI更新
```

### データフロー図

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

command ───▶ tree-sitter-bash
    │               │
    │               ├──▶ ディレクトリ抽出
    │               │
    │               └──▶ コマンドパターン抽出
    │                         │
timeout ───▶                  ├──▶ 権限チェック
    │                         │
workdir ───▶                  └──▶ プロセス起動
                                      │
                              ┌───────┴───────┐
                              ▼               ▼
                           stdout          stderr
                              │               │
                              └───────┬───────┘
                                      ▼
                              出力ストリーミング
                                      │
                                      ▼
                              ツール結果返却
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| bash.ts | `packages/opencode/src/tool/bash.ts` | ソース | Bashツール実装 |
| bash.txt | `packages/opencode/src/tool/bash.txt` | テンプレート | ツール説明文 |
| tool.ts | `packages/opencode/src/tool/tool.ts` | ソース | ツール基盤定義 |
| shell.ts | `packages/opencode/src/shell/shell.ts` | ソース | シェル検出とプロセス管理 |
| arity.ts | `packages/opencode/src/permission/arity.ts` | ソース | コマンドプレフィックス抽出（BashArity） |
| truncation.ts | `packages/opencode/src/tool/truncation.ts` | ソース | 出力截断処理 |
