第3章ツール実行エンジン

はじめに

モデルが「ファイルを読みたい」「コマンドを実行したい」と判断したとき、それを実際に実行するのがハーネスの ツール実行エンジン です。

本章では、主要な組み込みツールの役割と、ツール呼び出しがどう処理されるかを解説します。

3.1 ツール呼び出しの流れ

モデルとハーネスの間では、次のようなやり取りが行われています。

sequenceDiagram
    participant M as モデル
    participant H as ハーネス
    participant OS as OS / ファイルシステム
    M->>H: tool_use: Bash { command: "pnpm test" }
    H->>H: パーミッション確認（第4章）
    H->>H: PreToolUse フック実行（第5章）
    H->>OS: コマンド実行
    OS-->>H: 標準出力 / 終了コード
    H->>H: PostToolUse フック実行
    H-->>M: tool_result: テスト結果
    M->>M: 結果を踏まえて次の行動を推論

モデルはツールの 名前とパラメータを JSON で宣言するだけ です。
実行・検証・結果の整形はすべてハーネスが担い、その過程でパーミッション確認とフックが挟まります。

3.2 主要な組み込みツール

ファイル操作

ツール	役割	特徴
Read	ファイルの読み取り	行番号付きで返す。画像・PDF・Jupyter Notebook も読める
Write	ファイルの新規作成・全体上書き	既存ファイルは事前に Read していないと上書きできない
Edit	文字列の完全一致置換	`old_string` が一意に一致しないと失敗する（安全装置）

検索

ツール	役割	使い分け
Glob	ファイル名パターンで検索	`src/*/.ts` のようなパスの当たり付け
Grep	ファイル内容を正規表現検索	ripgrep ベースで高速。コード検索の主力

実行

ツール	役割	特徴
Bash	シェルコマンド実行	作業ディレクトリは引き継がれる。タイムアウト指定・バックグラウンド実行が可能

Web・その他

ツール	役割
WebFetch	URL の内容を取得して読む
WebSearch	Web 検索
Task (Agent)	サブエージェントの起動（第7章）
TodoWrite	タスクリストの管理・進捗の可視化

3.3 ハーネスによるツールの「しつけ」

ハーネスは、ツールを安全かつ効率的に使わせるための制約をモデルに課しています。
代表的なものを知っておくと、Claude Code の挙動が理解しやすくなります。

Read してから Write / Edit — 読んでいないファイルの上書き・編集は失敗します。
実際の内容を確認せずに変更することを防ぎます。
専用ツール優先 — cat や grep を Bash で実行するのではなく、Read / Grep ツールを使うよう誘導されます。
専用ツールの方が結果の整形・権限管理・UI 表示に適しているためです。
出力の切り詰め — 巨大な出力はコンテキスト保護のため自動的に切り詰められます。
並列実行 — 依存関係のない複数のツール呼び出し（例：3つのファイルを同時に Read）は、1回の応答でまとめて発行され並列実行されます。

3.4 バックグラウンド実行

長時間かかるコマンド（開発サーバー、ビルド、テストスイート）は、バックグラウンドで実行できます。

Bash ツールの run_in_background オプションで起動
実行中も会話を継続でき、完了時にハーネスがモデルへ通知
ユーザー側からは Ctrl+B などで手動でバックグラウンド化することも可能

例: 「開発サーバーをバックグラウンドで起動して、
     トップページのHTMLを確認して」
→ Bash(run_in_background) で pnpm dev を起動
→ 別の Bash で curl localhost:4321 を実行して確認

3.5 ツールの無効化・制限

利用できるツールは設定やCLIオプションで制御できます。

# WebSearch を無効化して起動
claude --disallowedTools "WebSearch"

# 読み取り系ツールのみ許可
claude --allowedTools "Read" "Glob" "Grep"

CI やレビュー用途で「読み取り専用の Claude」を作る、といった使い方ができます。
恒久的な設定は settings.json の permissions（第4章・第8章）で行います。

まとめ

モデルはツールを「宣言」するだけで、実行はハーネスのツール実行エンジンが担う
ファイル操作（Read / Write / Edit）、検索（Glob / Grep）、実行（Bash）が中核ツール
「Read してから Edit」などの制約は、誤操作を防ぐハーネスの安全設計
ツールの許可・禁止は CLI オプションや settings.json で制御できる