cc-viewer 1.2.1 → 1.2.2

package/concepts/ja/Tool-TaskGet.md

@@ -0,0 +1,35 @@
+# TaskGet
+
+## 定義
+
+タスク ID でタスクの完全な詳細を取得します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `taskId` | string | はい | 取得するタスクの ID |
+
+## 返却内容
+
+- `subject` — タスクタイトル
+- `description` — 詳細な要件とコンテキスト
+- `status` — ステータス：`pending`、`in_progress` または `completed`
+- `blocks` — このタスクによってブロックされているタスクのリスト
+- `blockedBy` — このタスクをブロックしている前提タスクのリスト
+
+## 使用シナリオ
+
+**適している場合：**
+- 作業開始前にタスクの完全な説明とコンテキストを取得
+- タスクの依存関係を理解
+- タスクを割り当てられた後に完全な要件を取得
+
+## 注意事項
+
+- タスク取得後、作業開始前に `blockedBy` リストが空であることを確認すべき
+- TaskList ですべてのタスクの要約情報を確認
+
+## cc-viewer での意義
+
+TaskGet は内部タスク管理操作であり、独立した API リクエストは生成しません。

package/concepts/ja/Tool-TaskList.md

@@ -0,0 +1,36 @@
+# TaskList
+
+## 定義
+
+タスクリスト内のすべてのタスクを一覧表示し、全体の進捗と利用可能な作業を確認します。
+
+## パラメータ
+
+パラメータなし。
+
+## 返却内容
+
+各タスクの要約情報：
+- `id` — タスク識別子
+- `subject` — 短い説明
+- `status` — ステータス：`pending`、`in_progress` または `completed`
+- `owner` — 担当者（agent ID）、空は未割り当て
+- `blockedBy` — このタスクをブロックしている未完了タスク ID のリスト
+
+## 使用シナリオ
+
+**適している場合：**
+- 利用可能なタスクの確認（ステータスが pending、owner なし、ブロックされていない）
+- プロジェクト全体の進捗確認
+- ブロックされているタスクの検索
+- タスク完了後に次のタスクを検索
+
+## 注意事項
+
+- ID 順にタスクを処理することを優先（最小 ID 優先）。早期のタスクは通常、後続タスクにコンテキストを提供するため
+- `blockedBy` があるタスクは依存が解除されるまで認領できない
+- TaskGet で特定タスクの完全な詳細を取得
+
+## cc-viewer での意義
+
+TaskList は内部タスク管理操作であり、独立した API リクエストは生成しません。

package/concepts/ja/Tool-TaskOutput.md

@@ -0,0 +1,34 @@
+# TaskOutput
+
+## 定義
+
+実行中または完了したバックグラウンドタスクの出力を取得します。バックグラウンドシェル、非同期 agent、リモートセッションに適用。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `task_id` | string | はい | タスク ID |
+| `block` | boolean | はい | タスク完了までブロック待機するかどうか、デフォルト `true` |
+| `timeout` | number | はい | 最大待機時間（ミリ秒）、デフォルト 30000、最大 600000 |
+
+## 使用シナリオ
+
+**適している場合：**
+- Task（`run_in_background: true`）で起動したバックグラウンド agent の進捗確認
+- バックグラウンド Bash コマンドの実行結果を取得
+- 非同期タスクの完了を待って出力を取得
+
+**適していない場合：**
+- フォアグラウンドタスク——フォアグラウンドタスクは直接結果を返すため、このツールは不要
+
+## 注意事項
+
+- `block: true` はタスク完了またはタイムアウトまでブロック
+- `block: false` はノンブロッキングで現在の状態を確認
+- タスク ID は `/tasks` コマンドで検索可能
+- すべてのタスクタイプに適用：バックグラウンドシェル、非同期 agent、リモートセッション
+
+## cc-viewer での意義
+
+TaskOutput 呼び出し自体は API リクエストを生成しません。Claude Code 内部のタスク管理操作であり、リクエストログには表示されません。

package/concepts/ja/Tool-TaskStop.md

@@ -0,0 +1,27 @@
+# TaskStop
+
+## 定義
+
+実行中のバックグラウンドタスクを停止します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `task_id` | string | いいえ | 停止するバックグラウンドタスクの ID |
+| `shell_id` | string | いいえ | 非推奨、`task_id` を代わりに使用 |
+
+## 使用シナリオ
+
+**適している場合：**
+- 不要になった長時間実行タスクの終了
+- 誤って起動したバックグラウンドタスクのキャンセル
+
+## 注意事項
+
+- 成功または失敗のステータスを返す
+- `shell_id` パラメータは非推奨、`task_id` を使用すべき
+
+## cc-viewer での意義
+
+TaskStop 呼び出し自体は API リクエストを生成しません。Claude Code 内部のタスク管理操作です。

package/concepts/ja/Tool-TaskUpdate.md

@@ -0,0 +1,49 @@
+# TaskUpdate
+
+## 定義
+
+タスクリスト内の特定タスクのステータス、内容、または依存関係を更新します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `taskId` | string | はい | 更新するタスクの ID |
+| `status` | enum | いいえ | 新しいステータス：`pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | いいえ | 新しいタイトル |
+| `description` | string | いいえ | 新しい説明 |
+| `activeForm` | string | いいえ | 進行中に表示する現在進行形テキスト |
+| `owner` | string | いいえ | 新しいタスク担当者（agent 名） |
+| `metadata` | object | いいえ | マージするメタデータ（null に設定するとキーを削除） |
+| `addBlocks` | string[] | いいえ | このタスクによってブロックされるタスク ID のリスト |
+| `addBlockedBy` | string[] | いいえ | このタスクをブロックする前提タスク ID のリスト |
+
+## ステータス遷移
+
+```
+pending → in_progress → completed
+```
+
+`deleted` は任意のステータスから遷移可能で、タスクを永久に削除します。
+
+## 使用シナリオ
+
+**適している場合：**
+- 作業開始時にタスクを `in_progress` にマーク
+- 作業完了後にタスクを `completed` にマーク
+- タスク間の依存関係を設定
+- 要件変更時にタスク内容を更新
+
+**重要なルール：**
+- タスクを完全に完了した場合のみ `completed` にマーク
+- エラーやブロックに遭遇した場合は `in_progress` を維持
+- テスト失敗、実装不完全、未解決エラーがある場合は `completed` にマークしてはならない
+
+## 注意事項
+
+- 更新前に TaskGet でタスクの最新ステータスを取得し、古いデータを避ける
+- タスク完了後に TaskList を呼び出して次の利用可能なタスクを検索
+
+## cc-viewer での意義
+
+TaskUpdate は内部タスク管理操作であり、独立した API リクエストは生成しません。

package/concepts/ja/Tool-WebFetch.md

@@ -0,0 +1,36 @@
+# WebFetch
+
+## 定義
+
+指定 URL のウェブページ内容を取得し、HTML を markdown に変換し、AI モデルで prompt に基づいて内容を処理します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `url` | string (URI) | はい | 取得する完全な URL |
+| `prompt` | string | はい | ページからどの情報を抽出するかの説明 |
+
+## 使用シナリオ
+
+**適している場合：**
+- 公開ウェブページの内容を取得
+- オンラインドキュメントの参照
+- ウェブページから特定の情報を抽出
+
+**適していない場合：**
+- 認証が必要な URL（Google Docs、Confluence、Jira、GitHub など）——まず専用の MCP ツールを探すべき
+- GitHub URL——`gh` CLI を優先使用
+
+## 注意事項
+
+- URL は完全な有効 URL でなければならない
+- HTTP は自動的に HTTPS にアップグレード
+- 内容が大きすぎる場合、結果が要約される可能性がある
+- 15分の自動クリーニングキャッシュを含む
+- URL が異なるホストにリダイレクトされた場合、ツールはリダイレクト URL を返し、新しい URL で再リクエストが必要
+- MCP 提供の web fetch ツールが利用可能な場合、そちらを優先使用
+
+## cc-viewer での意義
+
+WebFetch 呼び出しはリクエストログで `tool_use` / `tool_result` content block ペアとして表示されます。`tool_result` には AI 処理後のウェブページ内容の要約が含まれます。

package/concepts/ja/Tool-WebSearch.md

@@ -0,0 +1,32 @@
+# WebSearch
+
+## 定義
+
+検索エンジンクエリを実行し、最新情報を取得するための検索結果を返します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `query` | string | はい | 検索クエリ（最低2文字） |
+| `allowed_domains` | string[] | いいえ | これらのドメインの結果のみを含む |
+| `blocked_domains` | string[] | いいえ | これらのドメインの結果を除外 |
+
+## 使用シナリオ
+
+**適している場合：**
+- モデルの知識カットオフ日を超えた最新情報の取得
+- 現在のイベントや最新データの検索
+- 最新の技術ドキュメントの検索
+
+## 注意事項
+
+- 検索結果は markdown ハイパーリンク形式で返される
+- 使用後はレスポンスの末尾に "Sources:" セクションを付け、関連 URL を列挙する必要がある
+- ドメインフィルタリング（包含/除外）に対応
+- 検索クエリには現在の年を使用すべき
+- 米国でのみ利用可能
+
+## cc-viewer での意義
+
+WebSearch 呼び出しはリクエストログで `tool_use` / `tool_result` content block ペアとして表示されます。`tool_result` には検索結果リストが含まれます。

package/concepts/ja/Tool-Write.md

@@ -0,0 +1,32 @@
+# Write
+
+## 定義
+
+ローカルファイルシステムにコンテンツを書き込みます。ファイルが既に存在する場合は上書きします。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `file_path` | string | はい | ファイルの絶対パス（絶対パスでなければならない） |
+| `content` | string | はい | 書き込む内容 |
+
+## 使用シナリオ
+
+**適している場合：**
+- 新規ファイルの作成
+- ファイル内容を完全に書き換える必要がある場合
+
+**適していない場合：**
+- ファイル内の部分的な内容の変更——Edit を使用すべき
+- ドキュメントファイル（*.md）や README を自発的に作成すべきではない。ユーザーが明示的に要求した場合を除く
+
+## 注意事項
+
+- 対象ファイルが既に存在する場合、先に Read で読み取る必要がある。そうでないと失敗する
+- 既存ファイルの全内容を上書きする
+- 既存ファイルの編集には Edit を優先使用し、Write は新規ファイル作成または完全な書き換えにのみ使用
+
+## cc-viewer での意義
+
+Write 呼び出しはリクエストログで `tool_use` content block として表示され、その `input.content` に書き込まれた完全な内容が含まれます。

package/concepts/ja/Tool-executeCode.md

@@ -0,0 +1,33 @@
+# executeCode (mcp__ide__executeCode)
+
+## 定義
+
+現在の notebook ファイルの Jupyter kernel で Python コードを実行します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `code` | string | はい | 実行する Python コード |
+
+## 使用シナリオ
+
+**適している場合：**
+- Jupyter notebook 環境でコードを実行
+- コードスニペットのテスト
+- データ分析と計算
+
+**適していない場合：**
+- 非 Jupyter 環境でのコード実行——Bash を使用すべき
+- ファイルの変更——Edit または Write を使用すべき
+
+## 注意事項
+
+- これは MCP（Model Context Protocol）ツールで、IDE 統合により提供
+- コードは現在の Jupyter kernel で実行され、状態は呼び出し間で永続化
+- ユーザーが明示的に要求しない限り、変数の宣言や kernel 状態の変更を避けるべき
+- kernel 再起動後は状態が失われる
+
+## cc-viewer での意義
+
+executeCode は MCP ツールで、リクエストログの `tools` 配列に `mcp__ide__executeCode` の名前で表示されます。その呼び出しと返却は標準の `tool_use` / `tool_result` パターンに従います。MCP ツールの増減は tools 配列の変化を引き起こし、キャッシュ再構築をトリガーする可能性があります。

package/concepts/ja/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## 定義
+
+VS Code から言語診断情報を取得します。構文エラー、型エラー、lint 警告などを含みます。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `uri` | string | いいえ | ファイル URI。指定しない場合はすべてのファイルの診断情報を取得 |
+
+## 使用シナリオ
+
+**適している場合：**
+- コードの構文、型、lint などのセマンティック問題をチェック
+- コード編集後に新しいエラーが導入されていないか検証
+- Bash コマンドの代わりにコード品質をチェック
+
+**適していない場合：**
+- テストの実行——Bash を使用すべき
+- ランタイムエラーのチェック——Bash でコードを実行すべき
+
+## 注意事項
+
+- これは MCP（Model Context Protocol）ツールで、IDE 統合により提供
+- VS Code / IDE 環境でのみ利用可能
+- コード問題のチェックには Bash コマンドよりもこのツールを優先使用
+
+## cc-viewer での意義
+
+getDiagnostics は MCP ツールで、リクエストログの `tools` 配列に `mcp__ide__getDiagnostics` の名前で表示されます。その呼び出しと返却は標準の `tool_use` / `tool_result` パターンに従います。MCP ツールの増減は tools 配列の変化を引き起こし、キャッシュ再構築をトリガーする可能性があります。

package/concepts/ja/Tools.md

@@ -0,0 +1,73 @@
+# Claude Code ツール一覧
+
+Claude Code は Anthropic API の tool_use メカニズムを通じてモデルに一連の組み込みツールを提供します。各 MainAgent リクエストの `tools` 配列にこれらのツールの完全な JSON Schema 定義が含まれ、モデルはレスポンス内の `tool_use` content block でそれらを呼び出します。
+
+以下はすべてのツールのカテゴリ別インデックスです。
+
+## Agent システム
+
+| ツール | 用途 |
+|--------|------|
+| [Task](Tool-Task.md) | サブ agent（SubAgent）を起動して複雑なマルチステップタスクを処理 |
+| [TaskOutput](Tool-TaskOutput.md) | バックグラウンドタスクの出力を取得 |
+| [TaskStop](Tool-TaskStop.md) | 実行中のバックグラウンドタスクを停止 |
+| [TaskCreate](Tool-TaskCreate.md) | 構造化タスクリストエントリを作成 |
+| [TaskGet](Tool-TaskGet.md) | タスクの詳細を取得 |
+| [TaskUpdate](Tool-TaskUpdate.md) | タスクのステータス、依存関係などを更新 |
+| [TaskList](Tool-TaskList.md) | すべてのタスクを一覧表示 |
+
+## ファイル操作
+
+| ツール | 用途 |
+|--------|------|
+| [Read](Tool-Read.md) | ファイル内容を読み取り（テキスト、画像、PDF、Jupyter notebook 対応） |
+| [Edit](Tool-Edit.md) | 精確な文字列置換でファイルを編集 |
+| [Write](Tool-Write.md) | ファイルの書き込みまたは上書き |
+| [NotebookEdit](Tool-NotebookEdit.md) | Jupyter notebook セルの編集 |
+
+## 検索
+
+| ツール | 用途 |
+|--------|------|
+| [Glob](Tool-Glob.md) | ファイル名パターンマッチングでファイルを検索 |
+| [Grep](Tool-Grep.md) | ripgrep ベースのファイル内容検索 |
+
+## ターミナル
+
+| ツール | 用途 |
+|--------|------|
+| [Bash](Tool-Bash.md) | シェルコマンドの実行 |
+
+## Web
+
+| ツール | 用途 |
+|--------|------|
+| [WebFetch](Tool-WebFetch.md) | ウェブページの内容を取得し AI で処理 |
+| [WebSearch](Tool-WebSearch.md) | 検索エンジンクエリ |
+
+## 計画とインタラクション
+
+| ツール | 用途 |
+|--------|------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | 計画モードに入り、実装方針を設計 |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | 計画モードを終了し、方針をユーザー承認に提出 |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | ユーザーに質問して確認や判断を取得 |
+
+## 拡張
+
+| ツール | 用途 |
+|--------|------|
+| [Skill](Tool-Skill.md) | スキル（slash command）の実行 |
+
+## IDE 統合
+
+| ツール | 用途 |
+|--------|------|
+| [getDiagnostics](Tool-getDiagnostics.md) | VS Code 言語診断情報の取得 |
+| [executeCode](Tool-executeCode.md) | Jupyter kernel でコードを実行 |
+
+## cc-viewer での意義
+
+ツール呼び出しは Claude Code リクエストログにおける最も重要な観測可能データの一つです。各 MainAgent リクエストの `tools` 配列はモデルが利用可能なツールセットを定義し、レスポンス内の `tool_use` / `tool_result` content block は実際のツール呼び出しと返却を記録します。cc-viewer はこれらのデータを解析し、Chat Mode で完全なツール呼び出しチェーンを再現します。
+
+ツール定義の変化（MCP server の接続/切断によるツールの増減など）はキャッシュ再構築をトリガーします。詳細は [CacheRebuild](CacheRebuild.md) を参照してください。

package/concepts/ja/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# 翻訳APIのコンテキスト汚染
+
+## 背景
+
+CC-Viewerには、Anthropic Messages APIを利用した組み込み翻訳機能（`POST /api/translate`）が含まれています。初期の実装では、翻訳リクエストがClaude Codeセッションからキャッシュされた認証情報（`x-api-key`と`authorization`ヘッダーの両方）を再利用していました。これにより、微妙ながら深刻な問題が発生しました：翻訳結果に無関係なコンテンツが頻繁に返されるようになったのです。
+
+## 根本原因
+
+### 2つの認証方式の本質的な違い
+
+Anthropic APIは2つの認証方式をサポートしています：
+
+| 方式 | ヘッダー | 典型的なソース | 特徴 |
+|------|----------|----------------|------|
+| APIキー | `x-api-key: sk-ant-...` | 環境変数 / Console | ステートレス、各リクエストが独立 |
+| OAuthトークン | `authorization: Bearer sessionToken` | Claude Codeサブスクリプションログイン | セッションに紐づき、サーバーがコンテキストの関連付けを維持 |
+
+重要な違い：**APIキーはステートレス**であり、各リクエストは完全に独立しています。一方、**OAuthセッショントークンはステートフル**であり、Anthropicサーバーは同じトークンを使用するリクエストを同一のセッションコンテキストに関連付けます。
+
+### 汚染の連鎖
+
+Claude Codeがサブスクリプション型OAuthログインを使用する場合、認証フローは以下のようになります：
+
+```
+Claude Code メイン会話 ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                    ↑
+CC-Viewer 翻訳リクエスト ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+翻訳リクエストが同じセッショントークンを再利用していたため、Anthropicサーバーは翻訳リクエストをClaude Codeのメイン会話コンテキストに関連付ける可能性がありました。これにより以下の問題が発生します：
+
+1. **翻訳結果がメイン会話のコンテキストに影響される**：翻訳リクエストのシステムプロンプトは「あなたは翻訳者です」ですが、サーバーコンテキストにはClaude Codeの会話履歴が残っており、モデルに干渉する可能性があります
+2. **メイン会話が翻訳リクエストによって乱される**：翻訳リクエストの内容（UIテキストの断片）がメイン会話のコンテキストに注入され、Claude Codeの応答がずれる可能性があります
+3. **予測不能な動作**：コンテキスト汚染はサーバー側の動作であるため、クライアント側では検出も制御もできません
+
+## 教訓
+
+- **OAuthセッショントークンは「単なる別のAPIキー」ではない** — サーバー側の状態を持っており、再利用はコンテキストの共有を意味します
+- **内部サービス呼び出しには独立したステートレスな認証を使用すべき**であり、ユーザーセッションとの関連付けを避ける必要があります
+
+## 参考資料
+
+- [Anthropic API Authentication Docs](https://docs.anthropic.com/en/api/getting-started)
+- [Claude Code Authentication](https://support.claude.com/en/articles/12304248-managing-api-key-environment-variables-in-claude-code)
+- [Anthropic Bans Subscription OAuth in Third-Party Apps](https://winbuzzer.com/2026/02/19/anthropic-bans-claude-subscription-oauth-in-third-party-apps-xcxwbn/)
+- [Claude Code Authentication: API Keys, Subscriptions, and SSO](https://developertoolkit.ai/en/claude-code/quick-start/authentication/)

package/concepts/ko/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON（요청 본문 증분 비교）
+
+## 배경
+
+Claude Code의 MainAgent는 전체 컨텍스트 전송 방식을 채택하고 있어, 매 요청마다 완전한 대화 이력, system prompt, 도구 정의 등의 내용을 포함합니다. 이는 대화가 진행될수록 요청 본문이 점점 커진다는 것을 의미하며, 원시 Body를 직접 확인해서는 "이번에 실제로 무엇이 추가되었는지"를 빠르게 파악하기 어렵습니다.
+
+Body Diff JSON은 바로 이 문제를 해결하기 위한 것입니다. 전후 두 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 두 가지 보기 모드를 지원하며, 원클릭 복사 가능
+- 좌측 상단 **CC-Viewer → 전역 설정**에서 "Body Diff JSON 기본 펼치기"를 설정할 수 있습니다

package/concepts/ko/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는 전후 두 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. 하나의 요청이 여러 원인에 동시에 해당할 수 있음 (예: 모델 전환 + 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/ko/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/ko/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으로 나타나며, 질문과 선택지 정의가 포함됩니다. 사용자의 답변은 후속 요청의 메시지 이력에 표시됩니다.