cc-viewer 1.2.1 → 1.2.2

package/concepts/ja/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（リクエストボディの差分比較）
+
+## 背景
+
+Claude Code の MainAgent はフルコンテキスト送信方式を採用しており、リクエストごとに完全な会話履歴、system prompt、ツール定義などを含みます。つまり会話が進むにつれてリクエストボディはどんどん大きくなり、生の Body を直接見ても「今回実際に何が追加されたのか」を素早く特定するのは困難です。
+
+Body Diff JSON はまさにこの問題を解決するためのものです。前後2つの MainAgent リクエストの body を自動比較し、差分部分を抽出することで、今回のリクエストで実際に追加された内容を一目で把握できます。
+
+## 動作原理
+
+1. **連続する MainAgent リクエストの識別**：現在のリクエストが MainAgent タイプであり、かつ前の MainAgent リクエストが存在すること
+2. **フィールドごとの比較**：リクエストボディのすべてのトップレベルフィールドを走査し、`_` プレフィックスの内部属性はスキップ
+3. **スマートな差分抽出**：
+   - 追加されたフィールド：そのまま表示
+   - 削除されたフィールド：非表示（通常、理解に影響しない）
+   - 変更されたフィールド：現在の値を表示
+   - `messages` 配列は特別処理：追加されたメッセージのみ表示（通常の会話は追記モードで、プレフィックスメッセージは不変のため）
+4. **リクエストボディの縮小検出**：現在のリクエストボディが前回より小さい場合、コンテキストの切り詰めやセッションリセットが発生したことを意味し、diff ではなく通知メッセージを表示
+
+## 典型的なシナリオ
+
+通常の会話ラウンドでは、Body Diff JSON には以下のみが含まれます：
+- `messages`：追加された1〜2件のメッセージ（ユーザーの入力 + 前回のアシスタントの応答）
+
+diff に `system`、`tools`、`model` などのフィールドの変更が表示された場合、今回のリクエストで設定変更が発生したことを意味し、これはキャッシュ再構築の原因でもあることが多いです。
+
+## 使い方
+
+- Body Diff JSON は MainAgent リクエストの詳細パネルに表示されます
+- タイトルをクリックで展開/折りたたみ
+- JSON と Text の2つの表示モードに対応し、ワンクリックコピーも可能
+- 左上の **CC-Viewer → グローバル設定** で「Body Diff JSON をデフォルトで展開」を設定できます

package/concepts/ja/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild（キャッシュ再構築）
+
+## 背景
+
+Anthropic の prompt caching メカニズムは、リクエスト内の system → tools → messages（キャッシュブレークポイントまで）を順番に連結してキャッシュキーを生成します。キャッシュキーが前回のリクエストと完全に一致する場合、API は `cache_read_input_tokens`（キャッシュヒット）を返します。キャッシュキーが変更された場合、API はキャッシュを再作成し、大量の `cache_creation_input_tokens` を返します。これがキャッシュ再構築です。
+
+キャッシュ再構築は追加のトークン課金を意味します（cache creation の価格は cache read より高い）。そのため、再構築の原因を特定することはコスト最適化に直接的な価値があります。
+
+## キャッシュ再構築の原因分類
+
+cc-viewer は前後2つの MainAgent リクエストの body を比較し、キャッシュ再構築の原因を正確に判定します：
+
+| reason | 意味 | 判定方法 |
+|--------|------|----------|
+| `ttl` | キャッシュ期限切れ | 前の MainAgent リクエストから5分以上経過 |
+| `system_change` | system prompt の変更 | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | ツール定義の変更 | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | モデル切り替え | `prev.model !== curr.model` |
+| `msg_truncated` | メッセージスタックの切り詰め | 現在のリクエストの messages 数が前回より少ない。通常コンテキストウィンドウのオーバーフローによる切り詰めで発生 |
+| `msg_modified` | 履歴メッセージの変更 | プレフィックスメッセージの内容が不一致（通常の追記時はプレフィックスが完全に同一であるべき） |
+| `key_change` | 不明なキー変更 | 上記のいずれにも該当しない場合のフォールバック |
+
+## 判定優先順位
+
+1. まず時間間隔を確認——5分を超えた場合は直接 `ttl` と判定し、body 比較は行わない
+2. 次に model、system、tools、messages を順に確認
+3. 1つのリクエストが複数の原因に同時に該当する場合がある（例：モデル切り替え + system prompt 変更）。この場合 `reasons` 配列にすべての該当項目が含まれ、tooltip では改行表示される
+
+## よくあるシナリオ
+
+- **`ttl`**：ユーザーが5分以上操作を中断した後に再開し、キャッシュが自然に期限切れ
+- **`system_change`**：Claude Code が system prompt を更新（新しい CLAUDE.md の読み込み、project instructions の変更など）
+- **`tools_change`**：MCP server の接続/切断により利用可能なツールリストが変化
+- **`model_change`**：ユーザーが `/model` コマンドでモデルを切り替え
+- **`msg_truncated`**：会話が長くなりコンテキストウィンドウ管理が発動、Claude Code が初期のメッセージを切り詰め
+- **`msg_modified`**：Claude Code が履歴メッセージを編集（例：`/compact` で圧縮サマリーが元のメッセージを置換）
+
+## cc-viewer での表示
+
+リクエストリストでは、キャッシュ再構築が発生したリクエストの cache 行に赤い丸のインジケーターが表示されます。マウスホバーで tooltip が表示され、具体的な再構築理由の説明が含まれます（18言語対応）。

package/concepts/ja/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## 定義
+
+MainAgent は、Claude Code が非 agent team 状態における主幹リクエストチェーンです。ユーザーと Claude Code のやり取りのたびに一連の API リクエストが生成され、その中で MainAgent リクエストがコア会話チェーンを構成します。これらは完全な system prompt、ツール定義、メッセージ履歴を含みます。
+
+## 識別方法
+
+cc-viewer では、MainAgent は `req.mainAgent === true` で識別され、`interceptor.js` がリクエストキャプチャ時に自動的にマーキングします。
+
+判定条件（すべて満たす）：
+- リクエストボディに `system` フィールド（system prompt）が含まれる
+- リクエストボディに `tools` 配列（ツール定義）が含まれる
+- system prompt に "Claude Code" の特徴テキストが含まれる
+
+## SubAgent との違い
+
+| 特徴 | MainAgent | SubAgent |
+|------|-----------|----------|
+| system prompt | 完全な Claude Code メインプロンプト | 簡潔なタスク専用プロンプト |
+| tools 配列 | 利用可能なすべてのツールを含む | 通常タスクに必要な少数のツールのみ |
+| メッセージ履歴 | 完全な会話コンテキストを蓄積 | サブタスク関連のメッセージのみ |
+| キャッシュ動作 | prompt caching あり（5分 TTL） | 通常キャッシュなし、またはキャッシュが小さい |
+
+## cc-viewer での意義
+
+- **キャッシュ追跡**：MainAgent リクエストの prompt caching 状態はコストに直接影響します。`cache_creation_input_tokens` と `cache_read_input_tokens` の比率を監視することで、キャッシュヒット率を判断できます
+- **キャッシュロス分析**：MainAgent リクエストで大量の cache creation（cache read ではなく）が発生した場合、キャッシュロスと再構築を意味し、cc-viewer は赤い丸のインジケーターでこれらのリクエストをマーキングします
+- **メインチェーン分析**：MainAgent リクエストシーケンスはユーザーと Claude Code の完全なインタラクションプロセスを反映し、セッション行動分析のコアデータです
+- **セッション再構築**：cc-viewer は MainAgent リクエストのメッセージ履歴を通じて会話ビュー（Chat Mode）を再構築します

package/concepts/ja/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## 定義
+
+実行中にユーザーに質問し、確認の取得、仮説の検証、または判断の要求に使用します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `questions` | array | はい | 質問リスト（1〜4個の質問） |
+| `answers` | object | いいえ | ユーザーから収集した回答 |
+| `annotations` | object | いいえ | 各質問の注釈（プレビュー選択の備考など） |
+| `metadata` | object | いいえ | トラッキングと分析用のメタデータ |
+
+各 `question` オブジェクト：
+
+| フィールド | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `question` | string | はい | 完全な質問テキスト。疑問符で終わること |
+| `header` | string | はい | 短いラベル（最大12文字）、ラベルチップとして表示 |
+| `options` | array | はい | 2〜4個の選択肢 |
+| `multiSelect` | boolean | はい | 複数選択を許可するかどうか |
+
+各 `option` オブジェクト：
+
+| フィールド | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `label` | string | はい | 選択肢の表示テキスト（1〜5語） |
+| `description` | string | はい | 選択肢の説明 |
+| `markdown` | string | いいえ | プレビューコンテンツ（ASCII レイアウト、コードスニペットなどの視覚的比較用） |
+
+## 使用シナリオ
+
+**適している場合：**
+- ユーザーの好みや要件を収集
+- 曖昧な指示を明確化
+- 実装中に判断を取得
+- ユーザーに方向性の選択を提供
+
+**適していない場合：**
+- 「方針でよろしいですか？」と聞く場合——ExitPlanMode を使用すべき
+
+## 注意事項
+
+- ユーザーは常に "Other" を選択してカスタム入力を提供できる
+- 推奨選択肢は最初に配置し、label の末尾に "(Recommended)" を追加
+- `markdown` プレビューは単一選択の質問のみ対応
+- `markdown` がある選択肢は左右並列レイアウトに切り替わる
+- 計画モードでは、方針確定前の要件明確化に使用
+
+## cc-viewer での意義
+
+AskUserQuestion 呼び出しはリクエストログで `tool_use` content block として表示され、質問と選択肢の定義が含まれます。ユーザーの回答は後続リクエストのメッセージ履歴に表示されます。

package/concepts/ja/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## 定義
+
+シェルコマンドを実行します。オプションのタイムアウト設定に対応。作業ディレクトリはコマンド間で永続化されますが、シェル状態（環境変数など）は永続化されません。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `command` | string | はい | 実行する bash コマンド |
+| `description` | string | いいえ | コマンドの簡単な説明 |
+| `timeout` | number | いいえ | タイムアウト（ミリ秒）、最大 600000、デフォルト 120000 |
+| `run_in_background` | boolean | いいえ | バックグラウンドで実行するかどうか |
+
+## 使用シナリオ
+
+**適している場合：**
+- git 操作（commit、push、branch など）
+- npm/yarn などのパッケージ管理コマンド
+- docker 操作
+- コンパイル、ビルドコマンド
+- ディレクトリ内容の一覧表示（`ls`）
+- その他シェル実行が必要なシステムコマンド
+
+**適していない場合：**
+- ファイルの読み取り——Read を使用すべき
+- ファイル名の検索——Glob を使用すべき
+- ファイル内容の検索——Grep を使用すべき
+- ファイルの編集——Edit を使用すべき
+- ファイルの書き込み——Write を使用すべき
+- ユーザーへの情報出力——レスポンステキストに直接出力
+- 長時間実行プロセス（dev server、watch モード）——ユーザーに手動実行を推奨
+
+## 注意事項
+
+- スペースを含むパスはダブルクォートで囲む必要がある
+- 出力が 30000 文字を超えると切り詰められる
+- バックグラウンド実行のコマンドは TaskOutput で結果を取得
+- できるだけ絶対パスを使用し、`cd` を避ける
+- 独立したコマンドは複数の Bash を並列呼び出し可能
+- 依存関係のあるコマンドは `&&` で連結
+- シェル環境はユーザーの profile（bash または zsh）から初期化
+
+## cc-viewer での意義
+
+Bash 呼び出しはリクエストログで `tool_use`（コマンドを含む）と `tool_result`（出力を含む）の content block ペアとして表示されます。コマンド実行の出力はモデルの操作行動の分析に使用できます。

package/concepts/ja/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## 定義
+
+精確な文字列置換によるファイル編集。ファイル内の `old_string` を `new_string` に置換します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `file_path` | string | はい | 変更するファイルの絶対パス |
+| `old_string` | string | はい | 置換する元のテキスト |
+| `new_string` | string | はい | 置換後の新しいテキスト（old_string と異なる必要がある） |
+| `replace_all` | boolean | いいえ | すべてのマッチを置換するかどうか、デフォルト `false` |
+
+## 使用シナリオ
+
+**適している場合：**
+- 既存ファイル内の特定のコードセクションを変更
+- バグ修正、ロジックの更新
+- 変数のリネーム（`replace_all: true` と併用）
+- ファイル内容を精確に変更する必要があるすべてのシナリオ
+
+**適していない場合：**
+- 新規ファイルの作成——Write を使用すべき
+- 大規模な書き換え——Write でファイル全体を上書きする必要がある場合
+
+## 注意事項
+
+- 使用前に必ず Read でそのファイルを読み取っておく必要がある。そうでないとエラーになる
+- `old_string` はファイル内で一意でなければならない。一意でない場合は、より多くのコンテキストを含めて一意にするか、`replace_all` を使用する
+- テキスト編集時は元のインデント（tab/スペース）を維持する必要がある。Read 出力の行番号プレフィックスを含めないこと
+- 新規ファイル作成よりも既存ファイルの編集を優先
+- `new_string` は `old_string` と異なる必要がある
+
+## cc-viewer での意義
+
+Edit 呼び出しはリクエストログで `tool_use` content block として表示され、その `input` に `old_string` と `new_string` が含まれます。モデルがファイルに対して行った変更を追跡するのに使用できます。

package/concepts/ja/Tool-EnterPlanMode.md

@@ -0,0 +1,43 @@
+# EnterPlanMode
+
+## 定義
+
+Claude Code を計画モードに切り替え、実装前にコードベースを探索し方針を設計するために使用します。
+
+## パラメータ
+
+パラメータなし。
+
+## 使用シナリオ
+
+**適している場合：**
+- 新機能の実装——アーキテクチャの判断が必要
+- 複数の実行可能な方針がある——ユーザーの選択が必要
+- コード変更が既存の動作や構造に影響する
+- 複数ファイルの変更——2〜3ファイル以上に及ぶ可能性
+- 要件が不明確——まず探索して範囲を理解する必要がある
+- ユーザーの好みが重要——実装に複数の合理的な方向性がある
+
+**適していない場合：**
+- 1行または少数行の修正（タイプミス、明らかなバグ）
+- ユーザーが非常に具体的な指示を出している
+- 純粋な調査/探索タスク——Task（Explore タイプ）を使用すべき
+
+## 計画モードでの動作
+
+計画モードに入ると、Claude Code は：
+1. Glob、Grep、Read ツールを使用してコードベースを深く探索
+2. 既存のパターンとアーキテクチャを理解
+3. 実装方針を設計
+4. 方針をユーザー承認に提出
+5. 必要に応じて AskUserQuestion で確認
+6. 方針が準備できたら ExitPlanMode で終了
+
+## 注意事項
+
+- このツールは計画モードに入るためにユーザーの同意が必要
+- 計画が必要かどうか不確かな場合は、計画する方に傾ける——事前の擦り合わせは手戻りよりも良い
+
+## cc-viewer での意義
+
+EnterPlanMode 呼び出しはリクエストログで `tool_use` content block として表示されます。計画モードに入った後のリクエストシーケンスは通常、探索的なツール呼び出し（Glob、Grep、Read）が中心となり、ExitPlanMode が呼び出されるまで続きます。

package/concepts/ja/Tool-ExitPlanMode.md

@@ -0,0 +1,39 @@
+# ExitPlanMode
+
+## 定義
+
+計画モードを終了し、方針をユーザー承認に提出します。方針の内容は以前書き込まれた計画ファイルから読み取られます。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `allowedPrompts` | array | いいえ | 実装方針に必要な権限の説明リスト |
+
+`allowedPrompts` 配列の各要素：
+
+| フィールド | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `tool` | enum | はい | 適用するツール、現在は `Bash` のみサポート |
+| `prompt` | string | はい | 操作のセマンティック説明（例："run tests"、"install dependencies"） |
+
+## 使用シナリオ
+
+**適している場合：**
+- 計画モードで方針が完成し、ユーザー承認に提出する準備ができた
+- コードを書く必要がある実装タスクにのみ使用
+
+**適していない場合：**
+- 純粋な調査/探索タスク——計画モードを終了する必要はない
+- ユーザーに「方針でよろしいですか？」と聞きたい場合——これがまさにこのツールの機能であり、AskUserQuestion で聞かないこと
+
+## 注意事項
+
+- このツールは方針の内容をパラメータとして受け取らない——以前書き込まれた計画ファイルから読み取る
+- ユーザーは計画ファイルの内容を見て承認する
+- このツールを呼び出す前に AskUserQuestion で「方針は大丈夫ですか」と聞かないこと。重複になる
+- 質問の中で「計画」に言及しないこと。ユーザーは ExitPlanMode の前に計画の内容を見ることができないため
+
+## cc-viewer での意義
+
+ExitPlanMode 呼び出しは計画フェーズの終了を示します。リクエストログでは、この呼び出し以降のリクエストは通常、実装的な操作（Edit、Write、Bash など）に移行します。

package/concepts/ja/Tool-Glob.md

@@ -0,0 +1,34 @@
+# Glob
+
+## 定義
+
+高速なファイル名パターンマッチングツール。任意の規模のコードベースに対応。修正時間順にソートされたマッチするファイルパスを返します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `pattern` | string | はい | glob パターン（例：`**/*.js`、`src/**/*.ts`） |
+| `path` | string | いいえ | 検索ディレクトリ、デフォルトは現在の作業ディレクトリ。"undefined" や "null" を渡さないこと |
+
+## 使用シナリオ
+
+**適している場合：**
+- ファイル名パターンでファイルを検索
+- 特定タイプのすべてのファイルを検索（例：すべての `.tsx` ファイル）
+- 特定のクラス定義（例：`class Foo`）を探す際にまずファイルを特定
+- 単一メッセージ内で複数の Glob 呼び出しを並列実行可能
+
+**適していない場合：**
+- ファイル内容の検索——Grep を使用すべき
+- 複数ラウンドの検索が必要なオープンエンドな探索——Task（Explore タイプ）を使用すべき
+
+## 注意事項
+
+- 標準 glob 構文をサポート：`*` は単一階層、`**` は複数階層、`{}` は複数選択にマッチ
+- 結果は修正時間順にソート
+- Bash の `find` コマンドよりも推奨
+
+## cc-viewer での意義
+
+Glob 呼び出しはリクエストログで `tool_use` / `tool_result` content block ペアとして表示されます。`tool_result` にはマッチしたファイルパスのリストが含まれます。

package/concepts/ja/Tool-Grep.md

@@ -0,0 +1,47 @@
+# Grep
+
+## 定義
+
+ripgrep ベースの強力なコンテンツ検索ツール。正規表現、ファイルタイプフィルタリング、複数の出力モードに対応。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `pattern` | string | はい | 正規表現検索パターン |
+| `path` | string | いいえ | 検索パス（ファイルまたはディレクトリ）、デフォルトは現在の作業ディレクトリ |
+| `glob` | string | いいえ | ファイル名フィルタ（例：`*.js`、`*.{ts,tsx}`） |
+| `type` | string | いいえ | ファイルタイプフィルタ（例：`js`、`py`、`rust`）、glob より効率的 |
+| `output_mode` | enum | いいえ | 出力モード：`files_with_matches`（デフォルト）、`content`、`count` |
+| `-i` | boolean | いいえ | 大文字小文字を区別しない検索 |
+| `-n` | boolean | いいえ | 行番号を表示（content モードのみ）、デフォルト true |
+| `-A` | number | いいえ | マッチ後に表示する行数 |
+| `-B` | number | いいえ | マッチ前に表示する行数 |
+| `-C` / `context` | number | いいえ | マッチ前後に表示する行数 |
+| `head_limit` | number | いいえ | 出力エントリ数の制限、デフォルト 0（無制限） |
+| `offset` | number | いいえ | 最初の N 件の結果をスキップ |
+| `multiline` | boolean | いいえ | 複数行マッチモードを有効化、デフォルト false |
+
+## 使用シナリオ
+
+**適している場合：**
+- コードベース内で特定の文字列やパターンを検索
+- 関数/変数の使用箇所を検索
+- ファイルタイプで検索結果をフィルタリング
+- マッチ数のカウント
+
+**適していない場合：**
+- ファイル名でファイルを検索——Glob を使用すべき
+- 複数ラウンドの検索が必要なオープンエンドな探索——Task（Explore タイプ）を使用すべき
+
+## 注意事項
+
+- ripgrep 構文を使用（grep ではない）、波括弧などの特殊文字はエスケープが必要
+- `files_with_matches` モードはファイルパスのみを返し、最も効率的
+- `content` モードはマッチ行の内容を返し、コンテキスト行に対応
+- 複数行マッチには `multiline: true` の設定が必要
+- Bash 内の `grep` や `rg` コマンドよりも常に Grep ツールを優先使用
+
+## cc-viewer での意義
+
+Grep 呼び出しはリクエストログで `tool_use` / `tool_result` content block ペアとして表示されます。`tool_result` には検索結果が含まれます。

package/concepts/ja/Tool-NotebookEdit.md

@@ -0,0 +1,33 @@
+# NotebookEdit
+
+## 定義
+
+Jupyter notebook（.ipynb ファイル）内の特定のセルを置換、挿入、または削除します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `notebook_path` | string | はい | notebook ファイルの絶対パス |
+| `new_source` | string | はい | セルの新しい内容 |
+| `cell_id` | string | いいえ | 編集するセルの ID。挿入モードでは新しいセルがこの ID の後に挿入される |
+| `cell_type` | enum | いいえ | セルタイプ：`code` または `markdown`。挿入モードでは必須 |
+| `edit_mode` | enum | いいえ | 編集モード：`replace`（デフォルト）、`insert`、`delete` |
+
+## 使用シナリオ
+
+**適している場合：**
+- Jupyter notebook 内のコードまたは markdown セルを変更
+- notebook に新しいセルを追加
+- notebook 内のセルを削除
+
+## 注意事項
+
+- `cell_number` は 0 インデックス
+- `insert` モードは指定位置に新しいセルを挿入
+- `delete` モードは指定位置のセルを削除
+- パスは絶対パスでなければならない
+
+## cc-viewer での意義
+
+NotebookEdit 呼び出しはリクエストログで `tool_use` content block として表示され、notebook に対する具体的な変更操作が記録されます。

package/concepts/ja/Tool-Read.md

@@ -0,0 +1,41 @@
+# Read
+
+## 定義
+
+ローカルファイルシステムからファイル内容を読み取ります。テキストファイル、画像、PDF、Jupyter notebook に対応。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `file_path` | string | はい | ファイルの絶対パス |
+| `offset` | number | いいえ | 開始行番号（大きなファイルの分割読み取り用） |
+| `limit` | number | いいえ | 読み取り行数（大きなファイルの分割読み取り用） |
+| `pages` | string | いいえ | PDF ページ範囲（例："1-5"、"3"、"10-20"）、PDF のみ適用 |
+
+## 使用シナリオ
+
+**適している場合：**
+- コードファイル、設定ファイルなどのテキストファイルを読み取り
+- 画像ファイルの表示（Claude はマルチモーダルモデル）
+- PDF ドキュメントの読み取り
+- Jupyter notebook の読み取り（すべてのセルと出力を返す）
+- 複数ファイルを並列読み取りしてコンテキストを取得
+
+**適していない場合：**
+- ディレクトリの読み取り——Bash の `ls` コマンドを使用すべき
+- オープンエンドなコードベース探索——Task（Explore タイプ）を使用すべき
+
+## 注意事項
+
+- パスは絶対パスでなければならず、相対パスは不可
+- デフォルトでファイルの最初の 2000 行を読み取り
+- 2000 文字を超える行は切り詰められる
+- 出力は `cat -n` 形式で、行番号は 1 から開始
+- 大きな PDF（10 ページ超）は `pages` パラメータの指定が必須、1回最大 20 ページ
+- 存在しないファイルの読み取りはエラーを返す（クラッシュしない）
+- 単一メッセージ内で複数の Read を並列呼び出し可能
+
+## cc-viewer での意義
+
+Read 呼び出しはリクエストログで `tool_use`（呼び出し）と `tool_result`（返却内容）の content block ペアとして表示されます。`tool_result` にはファイルの実際の内容が含まれ、モデルがどのファイルを読み取ったかの分析に使用できます。

package/concepts/ja/Tool-Skill.md

@@ -0,0 +1,35 @@
+# Skill
+
+## 定義
+
+メイン会話内でスキル（skill）を実行します。スキルはユーザーが slash command（例：`/commit`、`/review-pr`）で呼び出せる専用機能です。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `skill` | string | はい | スキル名（例："commit"、"review-pr"、"pdf"） |
+| `args` | string | いいえ | スキルの引数 |
+
+## 使用シナリオ
+
+**適している場合：**
+- ユーザーが `/<skill-name>` 形式の slash command を入力した
+- ユーザーのリクエストが登録済みスキルの機能にマッチする
+
+**適していない場合：**
+- 組み込み CLI コマンド（例：`/help`、`/clear`）
+- 既に実行中のスキル
+- 利用可能なスキルリストにないスキル名
+
+## 注意事項
+
+- スキルが呼び出されると完全なプロンプトに展開される
+- 完全修飾名をサポート（例：`ms-office-suite:pdf`）
+- 利用可能なスキルリストは system-reminder メッセージで提供される
+- `<command-name>` タグが見えた場合はスキルが既にロード済みであり、このツールを再度呼び出さずに直接実行すべき
+- 実際にツールを呼び出さずにスキルに言及しないこと
+
+## cc-viewer での意義
+
+Skill 呼び出しはリクエストログで `tool_use` content block として表示されます。スキル展開後のプロンプトは後続リクエストの system prompt やメッセージ内容に影響します。

package/concepts/ja/Tool-Task.md

@@ -0,0 +1,53 @@
+# Task
+
+## 定義
+
+サブ agent（SubAgent）を起動して、複雑なマルチステップタスクを自律的に処理します。サブ agent は独立したサブプロセスで、それぞれ専用のツールセットとコンテキストを持ちます。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `prompt` | string | はい | サブ agent が実行するタスクの説明 |
+| `description` | string | はい | 3〜5語の短い要約 |
+| `subagent_type` | string | はい | サブ agent タイプ、利用可能なツールセットを決定 |
+| `model` | enum | いいえ | モデルを指定（sonnet / opus / haiku）、デフォルトは親から継承 |
+| `max_turns` | integer | いいえ | 最大 agentic ターン数 |
+| `run_in_background` | boolean | いいえ | バックグラウンドで実行するかどうか。バックグラウンドタスクは output_file パスを返す |
+| `resume` | string | いいえ | 再開する agent ID、前回の実行から続行 |
+| `isolation` | enum | いいえ | 隔離モード、`worktree` で一時的な git worktree を作成 |
+
+## サブ agent タイプ
+
+| タイプ | 用途 | 利用可能なツール |
+|--------|------|------------------|
+| `Bash` | コマンド実行、git 操作 | Bash |
+| `general-purpose` | 汎用マルチステップタスク | 全ツール |
+| `Explore` | コードベースの高速探索 | Task/Edit/Write/NotebookEdit/ExitPlanMode 以外のすべて |
+| `Plan` | 実装方針の設計 | Task/Edit/Write/NotebookEdit/ExitPlanMode 以外のすべて |
+| `claude-code-guide` | Claude Code 使用ガイド Q&A | Glob, Grep, Read, WebFetch, WebSearch |
+| `statusline-setup` | ステータスバーの設定 | Read, Edit |
+
+## 使用シナリオ
+
+**適している場合：**
+- マルチステップで自律的に完了する必要がある複雑なタスク
+- コードベースの探索と深い調査（Explore タイプを使用）
+- 隔離環境が必要な並列作業
+- バックグラウンドで実行する必要がある長時間タスク
+
+**適していない場合：**
+- 特定のファイルパスの読み取り——直接 Read または Glob を使用
+- 2〜3個の既知ファイル内の検索——直接 Read を使用
+- 特定のクラス定義の検索——直接 Glob を使用
+
+## 注意事項
+
+- サブ agent は完了後に単一メッセージを返し、その結果はユーザーには見えないため、メイン agent が伝達する必要がある
+- 単一メッセージ内で複数の並列 Task 呼び出しを発行して効率を向上できる
+- バックグラウンドタスクは TaskOutput ツールで進捗を確認
+- Explore タイプは直接 Glob/Grep を呼び出すより遅いため、単純な検索では不十分な場合にのみ使用
+
+## cc-viewer での意義
+
+Task 呼び出しは SubAgent リクエストチェーンを生成し、リクエストリストで MainAgent とは独立したサブリクエストシーケンスとして確認できます。SubAgent リクエストは通常、簡潔な system prompt と少ないツール定義を持ち、MainAgent と明確な対比を形成します。

package/concepts/ja/Tool-TaskCreate.md

@@ -0,0 +1,38 @@
+# TaskCreate
+
+## 定義
+
+構造化されたタスクリストエントリを作成し、進捗の追跡、複雑なタスクの整理、ユーザーへの作業進捗の表示に使用します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `subject` | string | はい | 短いタスクタイトル、命令形を使用（例："Fix authentication bug"） |
+| `description` | string | はい | 詳細な説明、コンテキストと受け入れ基準を含む |
+| `activeForm` | string | いいえ | 進行中に表示する現在進行形テキスト（例："Fixing authentication bug"） |
+| `metadata` | object | いいえ | タスクに付加する任意のメタデータ |
+
+## 使用シナリオ
+
+**適している場合：**
+- 複雑なマルチステップタスク（3ステップ以上）
+- ユーザーが複数の TODO 項目を提供した
+- 計画モードで作業を追跡
+- ユーザーが明示的に todo リストの使用を要求
+
+**適していない場合：**
+- 単一の簡単なタスク
+- 3ステップ以内の簡単な操作
+- 純粋な会話や情報照会
+
+## 注意事項
+
+- すべての新規タスクの初期ステータスは `pending`
+- `subject` は命令形（"Run tests"）、`activeForm` は現在進行形（"Running tests"）を使用
+- 作成後に TaskUpdate で依存関係（blocks/blockedBy）を設定可能
+- 作成前に TaskList を呼び出して重複タスクがないか確認すべき
+
+## cc-viewer での意義
+
+TaskCreate は Claude Code 内部のタスク管理操作であり、独立した API リクエストは生成しません。ただし Chat Mode ではモデルがこのツールを呼び出した tool_use block を確認できます。