# Bash ツール

シェルコマンド実行ツール。**用途は限定されている**。

## 許可される用途

- ファイル操作: `cp`, `mv`, `rm`, `mkdir`, `ls`, `find`
- テキスト処理: `cat`, `grep`, `sed`, `awk`, `head`, `tail`, `sort`, `uniq`, `wc`
- Python スクリプト実行: `python3 script.py`、`python3 -c "..."` （データ処理・グラフ生成等）
- Git の参照系: `git log`, `git diff`, `git status` （履歴・差分の確認）
- アーカイブ: `tar`, `zip`, `unzip`

## 禁止される用途

❌ **パッケージ・ソフトウェアのインストール一切**
- `apt install`, `apt-get install`
- `pip install`, `pip3 install`
- `npm install`, `yarn add`
- `curl ... | sh`, `wget ... | bash`
- `cargo install`, `go install`

❌ **永続的システム変更**
- `systemctl`, `service` の操作
- `crontab`, `at` の登録
- `chmod` で権限を緩和する操作

❌ **ネットワーク経由のダウンロード（コードや実行可能物）**
- `curl https://.../install.sh` 系
- 必要なら DownloadFile ツールを使う

## なぜインストールが禁止か

- ジョブ実行環境はサンドボックス化されており、永続化されない
- 必要な機能は専用ツール（`allowed_tools` に列挙されたもの）で提供される
- インストールが必要 = ツールの設計が足りないので、ユーザーに報告して機能追加を依頼する

## 代替

「○○ をインストールしたい」と思ったときの代替策:

| やりたいこと | 専用ツールで代替 |
|-------------|------------------|
| HTTP リクエスト | WebFetch / DownloadFile |
| HTML パース | BrowseWeb |
| 画像加工 | AnnotateImage / ReadImage |
| OCR | OCRTool / BatchOCRTool |
| Office ファイル読み込み | ReadPdf / ReadExcel / ReadDocx / ReadPPTX |
| 音声書き起こし | TranscribeAudio |
| データベース | SQLite |
| 検索 | WebSearch / SearchKnowledge |

## サンドボックス機構 (`safety.bash_sandbox`)

Bash 実行の隔離方式を選ぶ。**2 つの設定は直交する**:

- `safety.bash_sandbox`: 隔離機構を選ぶ — `auto`（既定）/ `always` / `off`
- `safety.bash_unrestricted`: コマンドホワイトリストを適用するか否か（`true` で撤廃）。**bwrap が走るかどうかは制御しない**（それは `bash_sandbox` の役割）

| `bash_sandbox` | 挙動 |
|----------------|------|
| `auto`（既定） | bwrap があれば bwrap サンドボックス、無ければ hardened（whitelist + パススコープ + env スクラブ）にフォールバック |
| `always` | bwrap を強制。bwrap 不在なら**起動失敗**（本番推奨） |
| `off` | bwrap を使わず exec（**env スクラブと、unrestricted でなければ whitelist + パススコープは維持**）。デバッグ用・非推奨 |

### bwrap サンドボックスの構成

| マウント | 種別 |
|---------|------|
| タスクの workspace (`{worktreeDir}/local/{taskId}/`) | read-write bind |
| `/usr`, `/bin`, `/sbin`, `/lib`, `/etc` | read-only bind |
| `/lib64` (存在する場合) | read-only bind |
| `/tmp` | private tmpfs |
| `/proc`, `/dev` | proc / dev |

**マウントされないもの**: `/home`, 他タスクの workspace、ホストの `/tmp` など。他ユーザーの workspace にはファイルシステムレベルでアクセス不可。

**環境変数**: `--clearenv` で全消去後、`PATH`/`HOME`/`LANG`/`LC_ALL`/`TZ`/`TERM`/`TMPDIR` の最小 allowlist のみ注入する。`MCP_ENCRYPTION_KEY` 等のシークレットはサンドボックス内から見えない。hardened フォールバック経路も同じ allowlist で exec する。

**ネットワーク**: `--unshare-net` で隔離（ループバックのみ）。bash からの外向き通信は不可 — Web 取得は SSRF ガード付きの WebFetch / DownloadFile / MCP 経由に一本化されている。

**パッケージ**: 各 Bash コールは独立した bwrap サンドボックスで実行され（揮発 `/tmp`・毎回新しい名前空間）、`/usr` は read-only。よって `pip install` / `npm install` は永続せず、全モードで明示的に拒否される。必要な Python パッケージは `runtime/python-requirements.txt` にプリベイクされ、システム python（read-only bind）から import できる。

### 前提条件 (`always` / bwrap 経路)

- コンテナ/ホストで **user namespace** が有効であること (PVE: `features: nesting=1`)
- `bwrap` バイナリがインストール済みであること
- `bash_sandbox: always`（または `bash_unrestricted: true`）では起動時に bwrap の動作確認を行い、失敗時はエラー終了する。`auto` では失敗時に警告ログを出し hardened へフォールバック