yoi/docs/ref/reference-tool-spec.md

リファレンス: ローカルファイル操作ツール仕様

Claude Code がエージェントとして使うファイル操作ツールの仕様。 Pod のツール設計の参考資料。

Read

ファイルを読む。画像・PDF・Jupyter notebook にも対応。

パラメータ	型	必須	説明
file_path	string	必須	絶対パス
offset	integer	任意	読み開始行番号（0始まり）
limit	integer	任意	読み取り行数（offset と併用）
pages	string	任意	PDF用ページ範囲 (例: "1-5")。最大20ページ/回

• デフォルトで先頭から最大2000行
• 出力は行番号付き（1始まり）
• ディレクトリは読めない

Write

ファイルを新規作成、または全体上書き。

パラメータ	型	必須	説明
file_path	string	必須	絶対パス
content	string	必須	書き込む内容全体

• 既存ファイルは上書き
• 既存ファイルを Write する前に Read が必要（未読だとエラー）

Edit

既存ファイルの部分的な文字列置換。

パラメータ	型	必須	説明
file_path	string	必須	絶対パス
old_string	string	必須	置換対象（ファイル内で一意であること）
new_string	string	必須	置換後（old_string と異なること）
replace_all	boolean	任意	true で全出現箇所を置換。デフォルト false

• 事前に Read が必要（未読だとエラー）
• old_string がファイル内で一意でないとエラー（replace_all: true 除く）

Glob

ファイルパターン検索。

パラメータ	型	必須	説明
pattern	string	必須	glob パターン (例: "**/*.rs")
path	string	任意	検索ディレクトリ。省略時はカレント

• 結果は更新日時順ソート

Grep

ファイル内容の正規表現検索（ripgrep ベース）。

パラメータ	型	必須	説明
pattern	string	必須	正規表現パターン
path	string	任意	検索対象。省略時はカレント
glob	string	任意	ファイルフィルタ (例: "*.rs")
type	string	任意	ファイル種別 (例: "rust", "py")
output_mode	enum	任意	"files_with_matches" (デフォルト) / "content" / "count"
-n	boolean	任意	行番号表示 (content モード、デフォルト true)
-i	boolean	任意	大文字小文字無視
-A	number	任意	マッチ後の行数
-B	number	任意	マッチ前の行数
-C	number	任意	マッチ前後の行数
multiline	boolean	任意	複数行マッチ。デフォルト false
head_limit	number	任意	出力件数制限。デフォルト 250
offset	number	任意	先頭N件スキップ

Bash

シェルコマンド実行。

パラメータ	型	必須	説明
command	string	必須	実行するコマンド
description	string	任意	コマンドの説明
timeout	number	任意	タイムアウト ms (最大 600000、デフォルト 120000)
run_in_background	boolean	任意	バックグラウンド実行

• 作業ディレクトリはコマンド間で永続
• シェル状態（変数・エイリアス）は永続しない

設計上の特徴

• パスは全て絶対パス
• Read → Edit/Write の順序制約: 未読ファイルの編集を防ぐ安全弁
• 専用ツール優先: cat/grep/find/sed の代わりに専用ツールを使う
• 冪等性: Edit は差分ベース、Write は全体上書き
• ワークフロー: Glob/Grep で探索 → Read で確認 → Edit で変更