cx-viewer 1.0.0

package/concepts/ja/Tool-TaskStop.md

@@ -0,0 +1,32 @@
+# TaskStop
+
+## 定義
+
+実行中のバックグラウンドタスクを停止します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `task_id` | string | いいえ | 停止するバックグラウンドタスクの ID |
+| `shell_id` | string | いいえ | 非推奨、`task_id` を代わりに使用 |
+
+## 使用シナリオ
+
+**適している場合：**
+- 不要になった長時間実行タスクの終了
+- 誤って起動したバックグラウンドタスクのキャンセル
+
+## 注意事項
+
+- 成功または失敗のステータスを返す
+- `shell_id` パラメータは非推奨、`task_id` を使用すべき
+
+## 原文
+
+<textarea readonly>
+- Stops a running background task by its ID
+- Takes a task_id parameter identifying the task to stop
+- Returns a success or failure status
+- Use this tool when you need to terminate a long-running task
+</textarea>

package/concepts/ja/Tool-TaskUpdate.md

@@ -0,0 +1,123 @@
+# 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 を呼び出して次の利用可能なタスクを検索
+
+## 原文
+
+<textarea readonly>Use this tool to update a task in the task list.
+
+## When to Use This Tool
+
+**Mark tasks as resolved:**
+- When you have completed the work described in a task
+- When a task is no longer needed or has been superseded
+- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
+- After resolving, call TaskList to find your next task
+
+- ONLY mark a task as completed when you have FULLY accomplished it
+- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
+- When blocked, create a new task describing what needs to be resolved
+- Never mark a task as completed if:
+  - Tests are failing
+  - Implementation is partial
+  - You encountered unresolved errors
+  - You couldn't find necessary files or dependencies
+
+**Delete tasks:**
+- When a task is no longer relevant or was created in error
+- Setting status to `deleted` permanently removes the task
+
+**Update task details:**
+- When requirements change or become clearer
+- When establishing dependencies between tasks
+
+## Fields You Can Update
+
+- **status**: The task status (see Status Workflow below)
+- **subject**: Change the task title (imperative form, e.g., "Run tests")
+- **description**: Change the task description
+- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
+- **owner**: Change the task owner (agent name)
+- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
+- **addBlocks**: Mark tasks that cannot start until this one completes
+- **addBlockedBy**: Mark tasks that must complete before this one can start
+
+## Status Workflow
+
+Status progresses: `pending` → `in_progress` → `completed`
+
+Use `deleted` to permanently remove a task.
+
+## Staleness
+
+Make sure to read a task's latest state using `TaskGet` before updating it.
+
+## Examples
+
+Mark task as in progress when starting work:
+```json
+{"taskId": "1", "status": "in_progress"}
+```
+
+Mark task as completed after finishing work:
+```json
+{"taskId": "1", "status": "completed"}
+```
+
+Delete a task:
+```json
+{"taskId": "1", "status": "deleted"}
+```
+
+Claim a task by setting owner:
+```json
+{"taskId": "1", "owner": "my-name"}
+```
+
+Set up task dependencies:
+```json
+{"taskId": "2", "addBlockedBy": ["1"]}
+```
+</textarea>

package/concepts/ja/Tool-TeamCreate.md

@@ -0,0 +1,38 @@
+# TeamCreate
+
+## 定義
+
+プロジェクトに取り組む複数の agent を調整するための新しいチームを作成します。チームは共有タスクリストと agent 間のメッセージングを通じて並列タスク実行を可能にします。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `team_name` | string | はい | 新しいチームの名前 |
+| `description` | string | いいえ | チームの説明 / 目的 |
+| `agent_type` | string | いいえ | チームリーダーのタイプ / ロール |
+
+## 作成されるもの
+
+- **チーム設定ファイル**: `~/.claude/teams/{team-name}/config.json` — メンバーリストとメタデータを保存
+- **タスクリストディレクトリ**: `~/.claude/tasks/{team-name}/` — すべてのチームメンバーが共有するタスクリスト
+
+チームとタスクリストは 1:1 の対応関係にあります。
+
+## チームワークフロー
+
+1. **TeamCreate** — チームとそのタスクリストを作成
+2. **TaskCreate** — チームのタスクを定義
+3. **Agent**（`team_name` + `name` を指定）— チームに参加するチームメンバーを起動
+4. **TaskUpdate** — `owner` を通じてチ��ムメンバーにタスクを割り当て
+5. チームメンバーがタスクに���り組み、**SendMessage** を通じて通信
+6. 完了後チームメンバーをシャットダウン、その後 **TeamDelete** でクリーンアップ
+
+## 関連ツール
+
+| ツール | 目的 |
+|--------|------|
+| `TeamDelete` | チームとタスクディレクトリを削除 |
+| `SendMessage` | チーム内の agent 間通信 |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 共有タスクリストの管理 |
+| `Agent` | チームに参加するチームメンバーを起動 |

package/concepts/ja/Tool-TeamDelete.md

@@ -0,0 +1,30 @@
+# TeamDelete
+
+## 定義
+
+マルチ agent コラボレーション作業が完了した際に、チームと関連するタスクディレクトリを削除します。TeamCreate のクリーンアップ対応操作です。
+
+## 動作
+
+- チームディレクトリを削除: `~/.claude/teams/{team-name}/`
+- タスクディレクトリを削除: `~/.claude/tasks/{team-name}/`
+- 現在のセッションからチームコンテキストをクリア
+
+**重要**: チームにまだアクティブなメンバーがいる場合、TeamDelete は失敗します。SendMessage のシャットダウンリクエストを通じて、先にすべてのチームメンバーを適切にシャットダウンする必要があります。
+
+## 典型的な使用方法
+
+TeamDelete はチームワークフローの終了時に呼び出されます:
+
+1. すべてのタスクが完了
+2. `SendMessage` で `shutdown_request` を送信してチームメンバーをシャットダウン
+3. **TeamDelete** がチームとタスクディレクトリを削除
+
+## 関連ツール
+
+| ツール | 目的 |
+|--------|------|
+| `TeamCreate` | 新しいチームとそのタスクリストを作成 |
+| `SendMessage` | チームメンバーとの通信 / シャットダウンリクエストの送信 |
+| `TaskCreate` / `TaskUpdate` / `TaskList` / `TaskGet` | 共有タスクリストの管理 |
+| `Agent` | チームに参加するチームメンバーを起動 |

package/concepts/ja/Tool-WebFetch.md

@@ -0,0 +1,55 @@
+# 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 ツールが利用可能な場合、そちらを優先使用
+
+## 原文
+
+<textarea readonly>IMPORTANT: WebFetch WILL FAIL for authenticated or private URLs. Before using this tool, check if the URL points to an authenticated service (e.g. Google Docs, Confluence, Jira, GitHub). If so, you MUST use ToolSearch first to find a specialized tool that provides authenticated access.
+
+- Fetches content from a specified URL and processes it using an AI model
+- Takes a URL and a prompt as input
+- Fetches the URL content, converts HTML to markdown
+- Processes the content with the prompt using a small, fast model
+- Returns the model's response about the content
+- Use this tool when you need to retrieve and analyze web content
+
+Usage notes:
+  - IMPORTANT: If an MCP-provided web fetch tool is available, prefer using that tool instead of this one, as it may have fewer restrictions.
+  - The URL must be a fully-formed valid URL
+  - HTTP URLs will be automatically upgraded to HTTPS
+  - The prompt should describe what information you want to extract from the page
+  - This tool is read-only and does not modify any files
+  - Results may be summarized if the content is very large
+  - Includes a self-cleaning 15-minute cache for faster responses when repeatedly accessing the same URL
+  - When a URL redirects to a different host, the tool will inform you and provide the redirect URL in a special format. You should then make a new WebFetch request with the redirect URL to fetch the content.
+  - For GitHub URLs, prefer using the gh CLI via Bash instead (e.g., gh pr view, gh issue view, gh api).
+</textarea>

package/concepts/ja/Tool-WebSearch.md

@@ -0,0 +1,58 @@
+# WebSearch
+
+## 定義
+
+検索エンジンクエリを実行し、最新情報を取得するための検索結果を返します。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `query` | string | はい | 検索クエリ（最低2文字） |
+| `allowed_domains` | string[] | いいえ | これらのドメインの結果のみを含む |
+| `blocked_domains` | string[] | いいえ | これらのドメインの結果を除外 |
+
+## 使用シナリオ
+
+**適している場合：**
+- モデルの知識カットオフ日を超えた最新情報の取得
+- 現在のイベントや最新データの検索
+- 最新の技術ドキュメントの検索
+
+## 注意事項
+
+- 検索結果は markdown ハイパーリンク形式で返される
+- 使用後はレスポンスの末尾に "Sources:" セクションを付け、関連 URL を列挙する必要がある
+- ドメインフィルタリング（包含/除外）に対応
+- 検索クエリには現在の年を使用すべき
+- 米国でのみ利用可能
+
+## 原文
+
+<textarea readonly>
+- Allows Claude to search the web and use the results to inform responses
+- Provides up-to-date information for current events and recent data
+- Returns search result information formatted as search result blocks, including links as markdown hyperlinks
+- Use this tool for accessing information beyond Claude's knowledge cutoff
+- Searches are performed automatically within a single API call
+
+CRITICAL REQUIREMENT - You MUST follow this:
+  - After answering the user's question, you MUST include a "Sources:" section at the end of your response
+  - In the Sources section, list all relevant URLs from the search results as markdown hyperlinks: [Title](URL)
+  - This is MANDATORY - never skip including sources in your response
+  - Example format:
+
+    [Your answer here]
+
+    Sources:
+    - [Source Title 1](https://example.com/1)
+    - [Source Title 2](https://example.com/2)
+
+Usage notes:
+  - Domain filtering is supported to include or block specific websites
+  - Web search is only available in the US
+
+IMPORTANT - Use the correct year in search queries:
+  - The current month is March 2026. You MUST use this year when searching for recent information, documentation, or current events.
+  - Example: If the user asks for "latest React docs", search for "React documentation" with the current year, NOT last year
+</textarea>

package/concepts/ja/Tool-Write.md

@@ -0,0 +1,39 @@
+# Write
+
+## 定義
+
+ローカルファイルシステムにコンテンツを書き込みます。ファイルが既に存在する場合は上書きします。
+
+## パラメータ
+
+| パラメータ | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `file_path` | string | はい | ファイルの絶対パス（絶対パスでなければならない） |
+| `content` | string | はい | 書き込む内容 |
+
+## 使用シナリオ
+
+**適している場合：**
+- 新規ファイルの作成
+- ファイル内容を完全に書き換える必要がある場合
+
+**適していない場合：**
+- ファイル内の部分的な内容の変更——Edit を使用すべき
+- ドキュメントファイル（*.md）や README を自発的に作成すべきではない。ユーザーが明示的に要求した場合を除く
+
+## 注意事項
+
+- 対象ファイルが既に存在する場合、先に Read で読み取る必要がある。そうでないと失敗する
+- 既存ファイルの全内容を上書きする
+- 既存ファイルの編集には Edit を優先使用し、Write は新規ファイル作成または完全な書き換えにのみ使用
+
+## 原文
+
+<textarea readonly>Writes a file to the local filesystem.
+
+Usage:
+- This tool will overwrite the existing file if there is one at the provided path.
+- If this is an existing file, you MUST use the Read tool first to read the file's contents. This tool will fail if you did not read the file first.
+- Prefer the Edit tool for modifying existing files — it only sends the diff. Only use this tool to create new files or for complete rewrites.
+- NEVER create documentation files (*.md) or README files unless explicitly requested by the User.
+- Only use emojis if the user explicitly requests it. Avoid writing emojis to files unless asked.</textarea>

package/concepts/ja/Tool-executeCode.md

@@ -0,0 +1,41 @@
+# 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 再起動後は状態が失われる
+
+## 原文
+
+<textarea readonly>Execute python code in the Jupyter kernel for the current notebook file.
+    
+    All code will be executed in the current Jupyter kernel.
+    
+    Avoid declaring variables or modifying the state of the kernel unless the user
+    explicitly asks for it.
+    
+    Any code executed will persist across calls to this tool, unless the kernel
+    has been restarted.</textarea>

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 コマンドよりもこのツールを優先使用
+
+## 原文
+
+<textarea readonly>Get language diagnostics from VS Code</textarea>

package/concepts/ja/Tools.md

@@ -0,0 +1,67 @@
+# 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 でコードを実行 |

package/concepts/ja/ToolsFirst.md

@@ -0,0 +1,77 @@
+# なぜToolsが最初に表示されるのか？
+
+cc-viewerのContextパネルでは、**ToolsはSystem PromptとMessagesより前に表示されます**。この順序は、**Anthropic APIのKV-Cacheプレフィックスシーケンス**を正確に反映しています。
+
+## KV-Cacheプレフィックスシーケンス
+
+Anthropic のAPIがKV-Cacheを構築する際、コンテキストを以下の**固定された順序**でプレフィックスとして連結します：
+
+```
+┌─────────────────────────────────────────────────┐
+│ 1. Tools (JSON Schema definitions)               │  ← Start of cache prefix
+│ 2. System Prompt                                 │
+│ 3. Messages (conversation history + current turn)│  ← End of cache prefix
+└─────────────────────────────────────────────────┘
+```
+
+つまり、**ToolsはSystem Promptより前、キャッシュプレフィックスの最先頭に位置します**。
+
+## なぜToolsはSystemよりキャッシュの重みが大きいのか？
+
+KV-Cacheのプレフィックスマッチングでは、**前方のコンテンツほど重要**です — 変更が発生すると、それ以降のすべてが無効化されます：
+
+1. **プレフィックスマッチングは先頭から開始される**：KV-Cacheは現在のリクエストをキャッシュされたプレフィックスと先頭からtoken単位で比較します。不一致が見つかった瞬間、それ以降のコンテンツはすべて無効化されます。
+
+2. **Toolsの変更 = キャッシュ全体が無効化**：Toolsは最前列にあるため、tool定義の変更（MCP toolの追加・削除1つでも）は**プレフィックスを最先頭から破壊し**、キャッシュされたSystem PromptとMessagesすべてを無効化します。
+
+3. **Systemの変更 = Messagesキャッシュが無効化**：System Promptは中間に位置するため、その変更は後続のMessages部分のみを無効化します。
+
+4. **Messagesの変更 = 末尾部分のみ影響**：Messagesは末尾にあるため、新しいmessageの追加は小さな末尾セグメントのみを無効化します — ToolsとSystemのキャッシュはそのまま保持されます。
+
+## 実際の影響
+
+| 変更の種類 | キャッシュへの影響 | 典型的なシナリオ |
+|-------------|-------------|-----------------|
+| Tool追加/削除 | **完全無効化** | MCPサーバーの接続/切断、IDEプラグインの切り替え |
+| System Promptの変更 | Messagesキャッシュが失われる | CLAUDE.mdの編集、system reminderの挿入 |
+| 新しいmessageの追加 | 末尾の増分のみ | 通常の会話フロー（最も一般的、最もコストが低い） |
+
+これが、[CacheRebuild](CacheRebuild.md)における`tools_change`が最もコストの高いリビルド理由になりやすい理由です — プレフィックスチェーンを最前部から破壊するからです。
+
+## なぜツール定義が「脳」より先に配置されるのか？
+
+キャッシュの仕組みから言えば、Toolsが最前列に位置するのは技術的な事実です。しかし認知設計の観点からも、この順序は理にかなっています —— **Toolsは手足であり、System Promptは脳です**。
+
+人は行動する前に、自分がどんな手足や道具を使えるかを感知する必要があります。赤ちゃんは最初に世界のルール（System）を理解してから手を伸ばすのではなく、まず自分に手や足があることを感知し、環境との相互作用を通じて徐々にルールを理解していきます。同様に、LLMはタスク指示（System Prompt）を受け取る前に、どんなツールを呼び出せるか（ファイル読み取り、コード記述、検索、コマンド実行）を知っておく必要があります。そうすることで、指示を処理する際に「何ができるか」「どうすべきか」を正確に判断できるのです。
+
+もし逆だったら —— まずモデルに「このモジュールをリファクタリングせよ」と伝え、次に「Read、Edit、Bashなどのツールがある」と伝える —— モデルはタスクを理解する際に重要な能力境界の情報が欠けてしまい、非現実的な計画を立てたり、利用可能な手段を見落としたりする可能性があります。
+
+**手持ちのカードを知ってから、どう切るかを決める。** これがToolsがSystemより先に来る認知的論理です。
+
+## なぜMCPツールもこの位置にあるのか？
+
+MCP（Model Context Protocol）ツールは、組み込みツールと同様にTools領域の最前列に配置されます。MCPのコンテキスト内での位置を理解することは、その実際のメリットとコストを評価するのに役立ちます。
+
+### MCPの利点
+
+- **能力拡張**：MCPにより、モデルは外部サービス（データベースクエリ、API呼び出し、IDE操作、ブラウザ制御など）にアクセスでき、組み込みツールの境界を超えることができます
+- **オープンエコシステム**：誰でもMCPサーバーを実装でき、モデルは再トレーニングなしで新しい能力を獲得できます
+- **オンデマンド読み込み**：タスクのシナリオに応じてMCPサーバーを選択的に接続/切断でき、ツールセットを柔軟に構成できます
+
+### MCPのコスト
+
+- **キャッシュキラー**：各MCPツールのJSON Schema定義はKV-Cacheプレフィックスの最前列に連結されます。MCPツールを1つ追加/削除するだけで = **キャッシュ全体が最初から無効化**されます。MCPサーバーの接続/切断を頻繁に行うと、キャッシュヒット率が大幅に低下します
+- **プレフィックスの肥大化**：MCPツールのSchemaは通常、組み込みツールより大きくなります（詳細なパラメータ説明、列挙値などを含む）。多数のMCPツールはTools領域のトークン数を大幅に増加させ、Messagesに使えるコンテキスト空間を圧迫します
+- **レイテンシオーバーヘッド**：MCPツール呼び出しにはプロセス間通信（JSON-RPC over stdio/SSE）が必要で、組み込み関数呼び出しより1桁遅くなります
+- **安定性リスク**：MCPサーバーは外部プロセスであり、クラッシュ、タイムアウト、予期しないフォーマットの返却が起こりうるため、追加のエラーハンドリングが必要です
+
+### 実践的な推奨事項
+
+| シナリオ | 推奨 |
+|----------|------|
+| 長い会話、高頻度のやり取り | MCPツールの数を最小限にし、キャッシュプレフィックスの安定性を保護 |
+| 短いタスク、一回限りの操作 | MCPツールを自由に使用可能；キャッシュへの影響は限定的 |
+| MCPサーバーの頻繁な追加/削除 | 変更のたびにキャッシュが全面再構築される；ツールセットの固定を検討 |
+| 過大なTool Schema | descriptionとenumを削減し、プレフィックスのトークン消費を削減 |
+
+cc-viewerのContextパネルでは、MCPツールは組み込みツールと並んでTools領域に表示され、各ツールのSchemaサイズとキャッシュプレフィックスへの寄与を直感的に確認できます。

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/)