cc-viewer 1.2.0 → 1.2.2

package/concepts/es/Tool-TaskOutput.md

@@ -0,0 +1,34 @@
+# TaskOutput
+
+## Definición
+
+Obtiene la salida de tareas en segundo plano en ejecución o completadas. Aplicable a shells en segundo plano, agents asíncronos y sesiones remotas.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `task_id` | string | Sí | ID de la tarea |
+| `block` | boolean | Sí | Si se bloquea esperando que la tarea termine, por defecto `true` |
+| `timeout` | number | Sí | Tiempo máximo de espera (milisegundos), por defecto 30000, máximo 600000 |
+
+## Casos de uso
+
+**Adecuado para:**
+- Verificar el progreso de agents en segundo plano iniciados mediante Task (`run_in_background: true`)
+- Obtener los resultados de ejecución de comandos Bash en segundo plano
+- Esperar a que una tarea asíncrona termine y obtener su salida
+
+**No adecuado para:**
+- Tareas en primer plano — las tareas en primer plano devuelven resultados directamente, no se necesita esta herramienta
+
+## Notas
+
+- `block: true` bloquea hasta que la tarea termine o se agote el tiempo
+- `block: false` se usa para verificación no bloqueante del estado actual
+- El ID de la tarea se puede encontrar mediante el comando `/tasks`
+- Aplicable a todos los tipos de tareas: shells en segundo plano, agents asíncronos, sesiones remotas
+
+## Significado en cc-viewer
+
+Las llamadas a TaskOutput no producen solicitudes API por sí mismas, es una operación interna de gestión de tareas de Claude Code y no aparece en el registro de solicitudes.

package/concepts/es/Tool-TaskStop.md

@@ -0,0 +1,27 @@
+# TaskStop
+
+## Definición
+
+Detiene una tarea en segundo plano en ejecución.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `task_id` | string | No | ID de la tarea en segundo plano a detener |
+| `shell_id` | string | No | Obsoleto, usar `task_id` en su lugar |
+
+## Casos de uso
+
+**Adecuado para:**
+- Terminar tareas de larga duración que ya no son necesarias
+- Cancelar tareas en segundo plano iniciadas por error
+
+## Notas
+
+- Devuelve estado de éxito o fallo
+- El parámetro `shell_id` está obsoleto, se debe usar `task_id`
+
+## Significado en cc-viewer
+
+Las llamadas a TaskStop no producen solicitudes API por sí mismas, pertenecen a las operaciones internas de gestión de tareas de Claude Code.

package/concepts/es/Tool-TaskUpdate.md

@@ -0,0 +1,49 @@
+# TaskUpdate
+
+## Definición
+
+Actualiza el estado, contenido o relaciones de dependencia de una tarea en la lista de tareas.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `taskId` | string | Sí | ID de la tarea a actualizar |
+| `status` | enum | No | Nuevo estado: `pending` / `in_progress` / `completed` / `deleted` |
+| `subject` | string | No | Nuevo título |
+| `description` | string | No | Nueva descripción |
+| `activeForm` | string | No | Texto en gerundio mostrado cuando está en progreso |
+| `owner` | string | No | Nuevo responsable de la tarea (nombre del agent) |
+| `metadata` | object | No | Metadatos a fusionar (establecer como null para eliminar una clave) |
+| `addBlocks` | string[] | No | Lista de IDs de tareas bloqueadas por esta tarea |
+| `addBlockedBy` | string[] | No | Lista de IDs de tareas previas que bloquean esta tarea |
+
+## Flujo de estados
+
+```
+pending → in_progress → completed
+```
+
+`deleted` puede ser alcanzado desde cualquier estado, elimina permanentemente la tarea.
+
+## Casos de uso
+
+**Adecuado para:**
+- Marcar una tarea como `in_progress` al comenzar a trabajar
+- Marcar una tarea como `completed` al terminar el trabajo
+- Establecer relaciones de dependencia entre tareas
+- Actualizar el contenido de la tarea cuando cambian los requisitos
+
+**Reglas importantes:**
+- Solo marcar como `completed` cuando la tarea está completamente terminada
+- Mantener como `in_progress` cuando se encuentran errores o bloqueos
+- No marcar como `completed` cuando las pruebas fallan, la implementación es parcial o hay errores sin resolver
+
+## Notas
+
+- Antes de actualizar, se debe obtener el estado más reciente de la tarea mediante TaskGet para evitar datos obsoletos
+- Después de completar una tarea, llamar a TaskList para encontrar la siguiente tarea disponible
+
+## Significado en cc-viewer
+
+TaskUpdate es una operación interna de gestión de tareas, no produce solicitudes API independientes.

package/concepts/es/Tool-WebFetch.md

@@ -0,0 +1,36 @@
+# WebFetch
+
+## Definición
+
+Obtiene el contenido de una página web de una URL especificada, convierte el HTML a markdown y procesa el contenido con un modelo de IA según el prompt.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `url` | string (URI) | Sí | URL completa a obtener |
+| `prompt` | string | Sí | Describe qué información extraer de la página |
+
+## Casos de uso
+
+**Adecuado para:**
+- Obtener contenido de páginas web públicas
+- Consultar documentación en línea
+- Extraer información específica de páginas web
+
+**No adecuado para:**
+- URLs que requieren autenticación (Google Docs, Confluence, Jira, GitHub, etc.) — buscar primero herramientas MCP dedicadas
+- URLs de GitHub — preferir usar el CLI `gh`
+
+## Notas
+
+- La URL debe ser una URL válida completa
+- HTTP se actualiza automáticamente a HTTPS
+- Los resultados pueden ser resumidos si el contenido es demasiado grande
+- Incluye caché con auto-limpieza de 15 minutos
+- Cuando la URL redirige a un host diferente, la herramienta devuelve la URL de redirección y se necesita hacer una nueva solicitud con la nueva URL
+- Si hay una herramienta web fetch proporcionada por MCP disponible, preferir usar esa
+
+## Significado en cc-viewer
+
+Las llamadas a WebFetch aparecen en el registro de solicitudes como pares de content blocks `tool_use` / `tool_result`. El `tool_result` contiene el resumen del contenido web procesado por IA.

package/concepts/es/Tool-WebSearch.md

@@ -0,0 +1,32 @@
+# WebSearch
+
+## Definición
+
+Ejecuta consultas en motores de búsqueda y devuelve resultados de búsqueda para obtener información actualizada.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `query` | string | Sí | Consulta de búsqueda (mínimo 2 caracteres) |
+| `allowed_domains` | string[] | No | Solo incluir resultados de estos dominios |
+| `blocked_domains` | string[] | No | Excluir resultados de estos dominios |
+
+## Casos de uso
+
+**Adecuado para:**
+- Obtener información actualizada más allá de la fecha de corte del conocimiento del modelo
+- Buscar eventos actuales y datos recientes
+- Buscar la documentación técnica más reciente
+
+## Notas
+
+- Los resultados de búsqueda se devuelven en formato de hipervínculos markdown
+- Después de usar, se debe incluir una sección "Sources:" al final de la respuesta, listando las URLs relevantes
+- Soporta filtrado de dominios (incluir/excluir)
+- Se debe usar el año actual en las consultas de búsqueda
+- Solo disponible en Estados Unidos
+
+## Significado en cc-viewer
+
+Las llamadas a WebSearch aparecen en el registro de solicitudes como pares de content blocks `tool_use` / `tool_result`. El `tool_result` contiene la lista de resultados de búsqueda.

package/concepts/es/Tool-Write.md

@@ -0,0 +1,32 @@
+# Write
+
+## Definición
+
+Escribe contenido en el sistema de archivos local. Si el archivo ya existe, lo sobrescribe.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `file_path` | string | Sí | Ruta absoluta del archivo (debe ser ruta absoluta) |
+| `content` | string | Sí | Contenido a escribir |
+
+## Casos de uso
+
+**Adecuado para:**
+- Crear archivos nuevos
+- Cuando se necesita reescribir completamente el contenido de un archivo
+
+**No adecuado para:**
+- Modificar contenido parcial de un archivo — usar Edit
+- No se deben crear proactivamente archivos de documentación (*.md) o README, a menos que el usuario lo solicite explícitamente
+
+## Notas
+
+- Si el archivo de destino ya existe, se debe leer primero con Read, de lo contrario fallará
+- Sobrescribe todo el contenido del archivo existente
+- Preferir usar Edit para editar archivos existentes, Write solo para crear archivos nuevos o reescrituras completas
+
+## Significado en cc-viewer
+
+Las llamadas a Write aparecen en el registro de solicitudes como content blocks `tool_use`, cuyo `input.content` contiene el contenido completo escrito.

package/concepts/es/Tool-executeCode.md

@@ -0,0 +1,33 @@
+# executeCode (mcp__ide__executeCode)
+
+## Definición
+
+Ejecuta código Python en el kernel de Jupyter del archivo notebook actual.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `code` | string | Sí | Código Python a ejecutar |
+
+## Casos de uso
+
+**Adecuado para:**
+- Ejecutar código en un entorno Jupyter notebook
+- Probar fragmentos de código
+- Análisis de datos y cálculos
+
+**No adecuado para:**
+- Ejecución de código fuera del entorno Jupyter — usar Bash
+- Modificar archivos — usar Edit o Write
+
+## Notas
+
+- Esta es una herramienta MCP (Model Context Protocol), proporcionada por la integración con el IDE
+- El código se ejecuta en el kernel de Jupyter actual, el estado persiste entre llamadas
+- A menos que el usuario lo solicite explícitamente, se debe evitar declarar variables o modificar el estado del kernel
+- El estado se pierde al reiniciar el kernel
+
+## Significado en cc-viewer
+
+executeCode es una herramienta MCP que aparece en el array `tools` del registro de solicitudes con el nombre `mcp__ide__executeCode`. Sus llamadas y retornos siguen el patrón estándar `tool_use` / `tool_result`. La adición/eliminación de herramientas MCP causa cambios en el array tools, lo que puede activar la reconstrucción de caché.

package/concepts/es/Tool-getDiagnostics.md

@@ -0,0 +1,32 @@
+# getDiagnostics (mcp__ide__getDiagnostics)
+
+## Definición
+
+Obtiene información de diagnóstico del lenguaje de VS Code, incluyendo errores de sintaxis, errores de tipo, advertencias de lint, etc.
+
+## Parámetros
+
+| Parámetro | Tipo | Requerido | Descripción |
+|-----------|------|-----------|-------------|
+| `uri` | string | No | URI del archivo. Si no se proporciona, obtiene la información de diagnóstico de todos los archivos |
+
+## Casos de uso
+
+**Adecuado para:**
+- Verificar problemas semánticos de sintaxis, tipos, lint, etc. del código
+- Verificar si se introdujeron nuevos errores después de editar código
+- Reemplazar comandos Bash para verificar la calidad del código
+
+**No adecuado para:**
+- Ejecutar pruebas — usar Bash
+- Verificar errores en tiempo de ejecución — usar Bash para ejecutar el código
+
+## Notas
+
+- Esta es una herramienta MCP (Model Context Protocol), proporcionada por la integración con el IDE
+- Solo disponible en entornos VS Code / IDE
+- Preferir usar esta herramienta en lugar de comandos Bash para verificar problemas de código
+
+## Significado en cc-viewer
+
+getDiagnostics es una herramienta MCP que aparece en el array `tools` del registro de solicitudes con el nombre `mcp__ide__getDiagnostics`. Sus llamadas y retornos siguen el patrón estándar `tool_use` / `tool_result`. La adición/eliminación de herramientas MCP causa cambios en el array tools, lo que puede activar la reconstrucción de caché.

package/concepts/es/Tools.md

@@ -0,0 +1,73 @@
+# Resumen de herramientas de Claude Code
+
+Claude Code proporciona al modelo un conjunto de herramientas integradas a través del mecanismo tool_use de la API de Anthropic. Cada solicitud MainAgent incluye las definiciones completas en JSON Schema de estas herramientas en el array `tools`, y el modelo las invoca mediante content blocks `tool_use` en la respuesta.
+
+A continuación se presenta el índice clasificado de todas las herramientas.
+
+## Sistema de Agents
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Task](Tool-Task.md) | Iniciar un sub-agent (SubAgent) para manejar tareas complejas de múltiples pasos |
+| [TaskOutput](Tool-TaskOutput.md) | Obtener la salida de tareas en segundo plano |
+| [TaskStop](Tool-TaskStop.md) | Detener una tarea en segundo plano en ejecución |
+| [TaskCreate](Tool-TaskCreate.md) | Crear una entrada en la lista de tareas estructurada |
+| [TaskGet](Tool-TaskGet.md) | Obtener detalles de una tarea |
+| [TaskUpdate](Tool-TaskUpdate.md) | Actualizar el estado, dependencias, etc. de una tarea |
+| [TaskList](Tool-TaskList.md) | Listar todas las tareas |
+
+## Operaciones de archivos
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Read](Tool-Read.md) | Leer contenido de archivos (soporta texto, imágenes, PDF, Jupyter notebook) |
+| [Edit](Tool-Edit.md) | Editar archivos mediante reemplazo exacto de cadenas |
+| [Write](Tool-Write.md) | Escribir o sobrescribir archivos |
+| [NotebookEdit](Tool-NotebookEdit.md) | Editar celdas de Jupyter notebook |
+
+## Búsqueda
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Glob](Tool-Glob.md) | Buscar archivos por coincidencia de patrones de nombre |
+| [Grep](Tool-Grep.md) | Búsqueda de contenido de archivos basada en ripgrep |
+
+## Terminal
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Bash](Tool-Bash.md) | Ejecutar comandos shell |
+
+## Web
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [WebFetch](Tool-WebFetch.md) | Obtener contenido web y procesarlo con IA |
+| [WebSearch](Tool-WebSearch.md) | Consultas en motores de búsqueda |
+
+## Planificación e interacción
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [EnterPlanMode](Tool-EnterPlanMode.md) | Entrar en modo de planificación para diseñar un plan de implementación |
+| [ExitPlanMode](Tool-ExitPlanMode.md) | Salir del modo de planificación y enviar el plan para aprobación del usuario |
+| [AskUserQuestion](Tool-AskUserQuestion.md) | Hacer preguntas al usuario para obtener aclaraciones o decisiones |
+
+## Extensiones
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [Skill](Tool-Skill.md) | Ejecutar una habilidad (slash command) |
+
+## Integración con IDE
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| [getDiagnostics](Tool-getDiagnostics.md) | Obtener información de diagnóstico del lenguaje de VS Code |
+| [executeCode](Tool-executeCode.md) | Ejecutar código en el kernel de Jupyter |
+
+## Significado en cc-viewer
+
+Las llamadas a herramientas son uno de los datos observables más importantes en los registros de solicitudes de Claude Code. El array `tools` de cada solicitud MainAgent define el conjunto de herramientas disponibles para el modelo, mientras que los content blocks `tool_use` / `tool_result` en la respuesta registran las llamadas reales a herramientas y sus retornos. cc-viewer analiza estos datos para reconstruir la cadena completa de llamadas a herramientas en el Chat Mode.
+
+Los cambios en las definiciones de herramientas (como la adición/eliminación de herramientas por conexión/desconexión de MCP server) activan la reconstrucción de caché, ver [CacheRebuild](CacheRebuild.md).

package/concepts/es/TranslateContextPollution.md

@@ -0,0 +1,46 @@
+# Contaminación de contexto de la API de traducción
+
+## Contexto
+
+CC-Viewer incluye una función de traducción integrada (`POST /api/translate`) impulsada por la API de mensajes de Anthropic. En la implementación inicial, las solicitudes de traducción reutilizaban las credenciales de autenticación almacenadas en caché de la sesión de Claude Code, incluyendo tanto los encabezados `x-api-key` como `authorization`. Esto provocó un problema sutil pero grave: los resultados de traducción devolvían con frecuencia contenido irrelevante.
+
+## Causa raíz
+
+### Diferencia fundamental entre los dos métodos de autenticación
+
+La API de Anthropic admite dos métodos de autenticación:
+
+| Método | Encabezado | Origen típico | Características |
+|--------|------------|---------------|-----------------|
+| Clave API | `x-api-key: sk-ant-...` | Variable de entorno / Console | Sin estado, cada solicitud es independiente |
+| Token OAuth | `authorization: Bearer sessionToken` | Inicio de sesión con suscripción de Claude Code | Vinculado a la sesión, el servidor mantiene la asociación de contexto |
+
+La diferencia clave: **las claves API son sin estado** — cada solicitud es completamente independiente; mientras que **los tokens de sesión OAuth son con estado** — el servidor de Anthropic asocia las solicitudes que usan el mismo token al mismo contexto de sesión.
+
+### Cadena de contaminación
+
+Cuando Claude Code utiliza el inicio de sesión OAuth por suscripción, el flujo de autenticación es el siguiente:
+
+```
+Conversación principal de Claude Code ──(authorization: Bearer sessionToken)──→ Anthropic API
+                                                                                  ↑
+Solicitud de traducción de CC-Viewer ──(authorization: Bearer sessionToken)──→ Anthropic API
+```
+
+Dado que las solicitudes de traducción reutilizaban el mismo token de sesión, el servidor de Anthropic podía asociar las solicitudes de traducción con el contexto de la conversación principal de Claude Code. Esto provoca:
+
+1. **Los resultados de traducción se ven influenciados por el contexto de la conversación principal**: El prompt del sistema de la solicitud de traducción es "eres un traductor", pero el contexto del servidor aún contiene el historial de conversación de Claude Code, lo que puede interferir con el modelo
+2. **La conversación principal se ve perturbada por las solicitudes de traducción**: El contenido de las solicitudes de traducción (fragmentos de texto de la interfaz) puede inyectarse en el contexto de la conversación principal, causando que las respuestas de Claude Code se desvíen
+3. **Comportamiento impredecible**: Dado que la contaminación de contexto es un comportamiento del lado del servidor, el cliente no puede detectarlo ni controlarlo
+
+## Lecciones aprendidas
+
+- **Los tokens de sesión OAuth no son "simplemente otra clave API"** — llevan estado del lado del servidor, reutilizarlos significa compartir contexto
+- **Las llamadas internas de servicio deben usar autenticación independiente y sin estado** para evitar la asociación con sesiones de usuario
+
+## Referencias
+
+- [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/fr/BodyDiffJSON.md

@@ -0,0 +1,32 @@
+# Body Diff JSON (Comparaison incrémentale du corps de la requête)
+
+## Contexte
+
+Le MainAgent de Claude Code utilise un mécanisme d'envoi de contexte complet — chaque requête inclut l'historique complet de la conversation, le system prompt, les définitions d'outils, etc. Cela signifie qu'au fur et à mesure que la conversation progresse, le corps de la requête devient de plus en plus volumineux, et il est difficile d'identifier rapidement « ce qui a été ajouté dans ce tour » en regardant le Body brut.
+
+Body Diff JSON résout exactement ce problème : il compare automatiquement les corps de deux requêtes MainAgent consécutives, extrait la partie incrémentale et vous permet de voir d'un coup d'œil le contenu réellement nouveau dans cette requête.
+
+## Fonctionnement
+
+1. **Identifier les requêtes MainAgent consécutives** : La requête actuelle doit être de type MainAgent et une requête MainAgent précédente doit exister
+2. **Comparaison champ par champ** : Parcourt tous les champs de niveau supérieur du corps de la requête, en ignorant les propriétés internes préfixées par `_`
+3. **Extraction intelligente des différences** :
+   - Champs ajoutés : Affichés directement
+   - Champs supprimés : Non affichés (n'affectent généralement pas la compréhension)
+   - Champs modifiés : La valeur actuelle est affichée
+   - Traitement spécial du tableau `messages` : Seuls les nouveaux messages sont affichés (car en conversation normale, le mode est l'ajout, les messages précédents ne changent pas)
+4. **Détection de réduction du corps** : Si le corps actuel est plus petit que le précédent, cela indique une troncature de contexte ou une réinitialisation de session, et un message informatif est affiché au lieu du diff
+
+## Scénarios typiques
+
+Dans un tour de conversation normal, le Body Diff JSON ne contient généralement que :
+- `messages` : 1~2 nouveaux messages (l'entrée de l'utilisateur + la réponse de l'assistant du tour précédent)
+
+Si vous voyez des changements dans `system`, `tools`, `model` ou d'autres champs dans le diff, cela signifie qu'un changement de configuration a eu lieu dans ce tour, ce qui est souvent aussi la cause de la reconstruction du cache.
+
+## Utilisation
+
+- Le Body Diff JSON est affiché dans le panneau de détails de la requête MainAgent
+- Cliquez sur le titre pour développer/réduire
+- Prend en charge deux modes de visualisation : JSON et Text, ainsi que la copie en un clic
+- Dans **CC-Viewer → Paramètres globaux** (coin supérieur gauche), vous pouvez configurer « Développer le Body Diff JSON par défaut »

package/concepts/fr/CacheRebuild.md

@@ -0,0 +1,40 @@
+# Cache Rebuild (Reconstruction du cache)
+
+## Contexte
+
+Le mécanisme de prompt caching d'Anthropic concatène séquentiellement system → tools → messages (jusqu'au cache breakpoint) de la requête pour former la clé de cache. Lorsque la clé de cache correspond exactement à la requête précédente, l'API renvoie `cache_read_input_tokens` (hit de cache) ; lorsque la clé de cache change, l'API recrée le cache et renvoie une grande quantité de `cache_creation_input_tokens`, c'est-à-dire une reconstruction du cache.
+
+La reconstruction du cache implique une facturation supplémentaire de tokens (le prix du cache creation est supérieur à celui du cache read), donc identifier la cause de la reconstruction a une valeur directe pour l'optimisation des coûts.
+
+## Classification des causes de reconstruction du cache
+
+cc-viewer compare les corps de deux requêtes MainAgent consécutives pour déterminer précisément la cause de la reconstruction du cache :
+
+| reason | Signification | Méthode de détermination |
+|--------|---------------|--------------------------|
+| `ttl` | Cache expiré | Plus de 5 minutes depuis la dernière requête MainAgent |
+| `system_change` | Changement du system prompt | `JSON.stringify(prev.system) !== JSON.stringify(curr.system)` |
+| `tools_change` | Changement des définitions d'outils | `JSON.stringify(prev.tools) !== JSON.stringify(curr.tools)` |
+| `model_change` | Changement de modèle | `prev.model !== curr.model` |
+| `msg_truncated` | Pile de messages tronquée | La requête actuelle a moins de messages que la précédente, généralement dû à une troncature lors du dépassement de la fenêtre de contexte |
+| `msg_modified` | Messages historiques modifiés | Le contenu des messages préfixe ne correspond pas (en ajout normal, le préfixe devrait être identique) |
+| `key_change` | Changement de clé inconnu | Fallback lorsqu'aucune des conditions ci-dessus ne correspond |
+
+## Priorité de détermination
+
+1. On vérifie d'abord l'intervalle de temps — s'il dépasse 5 minutes, on détermine directement `ttl`, sans comparer le body
+2. Ensuite on vérifie séquentiellement model, system, tools, messages
+3. Une requête peut correspondre à plusieurs causes simultanément (par exemple, changement de modèle + changement de system prompt), auquel cas le tableau `reasons` contient tous les éléments correspondants et le tooltip les affiche sur des lignes séparées
+
+## Scénarios courants
+
+- **`ttl`** : L'utilisateur a mis en pause l'opération pendant plus de 5 minutes puis a continué, le cache a expiré naturellement
+- **`system_change`** : Claude Code a mis à jour le system prompt (par exemple, chargement d'un nouveau CLAUDE.md, changements dans les project instructions)
+- **`tools_change`** : La connexion/déconnexion d'un MCP server a causé des changements dans la liste des outils disponibles
+- **`model_change`** : L'utilisateur a changé de modèle via la commande `/model`
+- **`msg_truncated`** : Une conversation longue a déclenché la gestion de la fenêtre de contexte, Claude Code a tronqué les messages antérieurs
+- **`msg_modified`** : Claude Code a édité des messages historiques (par exemple, `/compact` a remplacé les messages originaux par des résumés compressés)
+
+## Affichage dans cc-viewer
+
+Dans la liste des requêtes, les requêtes avec reconstruction du cache affichent un indicateur de point rouge sur la ligne de cache. Au survol de la souris, un tooltip s'affiche avec la description spécifique de la cause de reconstruction (supporte 18 langues).

package/concepts/fr/MainAgent.md

@@ -0,0 +1,30 @@
+# MainAgent
+
+## Définition
+
+MainAgent est la chaîne de requêtes principale de Claude Code en état non agent team. Chaque interaction de l'utilisateur avec Claude Code produit une série de requêtes API, où les requêtes MainAgent constituent la chaîne de conversation centrale — elles portent le system prompt complet, les définitions d'outils et l'historique des messages.
+
+## Méthode d'identification
+
+Dans cc-viewer, MainAgent est identifié par `req.mainAgent === true`, marqué automatiquement par `interceptor.js` lors de la capture de la requête.
+
+Conditions de détermination (toutes doivent être remplies) :
+- Le corps de la requête contient le champ `system` (system prompt)
+- Le corps de la requête contient le tableau `tools` (définitions d'outils)
+- Le system prompt contient le texte caractéristique « Claude Code »
+
+## Différences avec SubAgent
+
+| Caractéristique | MainAgent | SubAgent |
+|-----------------|-----------|----------|
+| system prompt | Prompt principal complet de Claude Code | Prompt simplifié spécifique à la tâche |
+| Tableau tools | Contient tous les outils disponibles | Ne contient généralement que les quelques outils nécessaires à la tâche |
+| Historique des messages | Accumule le contexte complet de la conversation | Ne contient que les messages liés à la sous-tâche |
+| Comportement de cache | A le prompt caching (TTL de 5 minutes) | Généralement sans cache ou avec un cache réduit |
+
+## Signification dans cc-viewer
+
+- **Suivi du cache** : L'état du prompt caching des requêtes MainAgent affecte directement les coûts. En surveillant la proportion entre `cache_creation_input_tokens` et `cache_read_input_tokens`, on peut déterminer le taux de hits du cache
+- **Analyse de perte de cache** : Lorsque les requêtes MainAgent montrent une grande quantité de cache creation (au lieu de cache read), cela indique que le cache a été perdu et reconstruit ; cc-viewer marque ces requêtes avec un indicateur de point rouge
+- **Analyse de la chaîne principale** : La séquence de requêtes MainAgent reflète le processus complet d'interaction de l'utilisateur avec Claude Code, constituant les données centrales pour l'analyse du comportement de la session
+- **Reconstruction de session** : cc-viewer reconstruit la vue de conversation (Chat Mode) à travers l'historique des messages des requêtes MainAgent

package/concepts/fr/Tool-AskUserQuestion.md

@@ -0,0 +1,54 @@
+# AskUserQuestion
+
+## Définition
+
+Pose des questions à l'utilisateur pendant l'exécution pour obtenir des clarifications, vérifier des hypothèses ou demander des décisions.
+
+## Paramètres
+
+| Paramètre | Type | Requis | Description |
+|-----------|------|--------|-------------|
+| `questions` | array | Oui | Liste de questions (1-4 questions) |
+| `answers` | object | Non | Réponses collectées auprès de l'utilisateur |
+| `annotations` | object | Non | Annotations pour chaque question (comme les notes de prévisualisation de sélection) |
+| `metadata` | object | Non | Métadonnées pour le suivi et l'analyse |
+
+Chaque objet `question` :
+
+| Champ | Type | Requis | Description |
+|-------|------|--------|-------------|
+| `question` | string | Oui | Texte complet de la question, doit se terminer par un point d'interrogation |
+| `header` | string | Oui | Étiquette courte (maximum 12 caractères), affichée comme chip d'étiquette |
+| `options` | array | Oui | 2-4 options |
+| `multiSelect` | boolean | Oui | Si la sélection multiple est autorisée |
+
+Chaque objet `option` :
+
+| Champ | Type | Requis | Description |
+|-------|------|--------|-------------|
+| `label` | string | Oui | Texte d'affichage de l'option (1-5 mots) |
+| `description` | string | Oui | Description de l'option |
+| `markdown` | string | Non | Contenu de prévisualisation (pour la comparaison visuelle de mises en page ASCII, extraits de code, etc.) |
+
+## Cas d'utilisation
+
+**Adapté pour :**
+- Collecter les préférences ou exigences de l'utilisateur
+- Clarifier des instructions ambiguës
+- Obtenir des décisions pendant l'implémentation
+- Offrir des choix de direction à l'utilisateur
+
+**Non adapté pour :**
+- Demander « le plan est-il correct ? » — utiliser ExitPlanMode
+
+## Notes
+
+- L'utilisateur peut toujours sélectionner « Other » pour fournir une entrée personnalisée
+- L'option recommandée est placée en premier, avec « (Recommended) » à la fin du label
+- La prévisualisation `markdown` n'est compatible qu'avec les questions à sélection unique
+- Les options avec `markdown` passent à une disposition côte à côte
+- En mode planification, utilisé pour clarifier les exigences avant de définir le plan
+
+## Signification dans cc-viewer
+
+Les appels à AskUserQuestion apparaissent dans le journal des requêtes comme des content blocks `tool_use`, contenant les définitions de questions et d'options. Les réponses de l'utilisateur apparaissent dans l'historique des messages des requêtes suivantes.

package/concepts/fr/Tool-Bash.md

@@ -0,0 +1,47 @@
+# Bash
+
+## Définition
+
+Exécute des commandes shell avec une configuration de délai d'attente optionnelle. Le répertoire de travail persiste entre les commandes, mais l'état du shell (variables d'environnement, etc.) ne persiste pas.
+
+## Paramètres
+
+| Paramètre | Type | Requis | Description |
+|-----------|------|--------|-------------|
+| `command` | string | Oui | Commande bash à exécuter |
+| `description` | string | Non | Description brève de la commande |
+| `timeout` | number | Non | Délai d'attente (millisecondes), maximum 600000, par défaut 120000 |
+| `run_in_background` | boolean | Non | Si la commande s'exécute en arrière-plan |
+
+## Cas d'utilisation
+
+**Adapté pour :**
+- Opérations git (commit, push, branch, etc.)
+- Commandes de gestion de paquets npm/yarn
+- Opérations docker
+- Commandes de compilation et de build
+- Lister le contenu des répertoires (`ls`)
+- Autres commandes système nécessitant une exécution shell
+
+**Non adapté pour :**
+- Lire des fichiers — utiliser Read
+- Rechercher des noms de fichiers — utiliser Glob
+- Rechercher du contenu de fichiers — utiliser Grep
+- Éditer des fichiers — utiliser Edit
+- Écrire des fichiers — utiliser Write
+- Afficher des informations à l'utilisateur — afficher directement dans le texte de réponse
+- Processus de longue durée (dev server, mode watch) — recommander à l'utilisateur d'exécuter manuellement
+
+## Notes
+
+- Les chemins contenant des espaces doivent être entre guillemets doubles
+- La sortie dépassant 30000 caractères sera tronquée
+- Les commandes en arrière-plan obtiennent leurs résultats via TaskOutput
+- Utiliser de préférence des chemins absolus, éviter `cd`
+- Les commandes indépendantes peuvent exécuter plusieurs Bash en parallèle
+- Les commandes avec des dépendances sont chaînées avec `&&`
+- L'environnement shell est initialisé à partir du profile de l'utilisateur (bash ou zsh)
+
+## Signification dans cc-viewer
+
+Les appels Bash apparaissent dans le journal des requêtes comme des paires de content blocks `tool_use` (contenant la commande) et `tool_result` (contenant la sortie). La sortie de l'exécution de la commande peut être utilisée pour analyser le comportement opérationnel du modèle.

package/concepts/fr/Tool-Edit.md

@@ -0,0 +1,38 @@
+# Edit
+
+## Définition
+
+Édite des fichiers par remplacement exact de chaînes. Remplace `old_string` par `new_string` dans le fichier.
+
+## Paramètres
+
+| Paramètre | Type | Requis | Description |
+|-----------|------|--------|-------------|
+| `file_path` | string | Oui | Chemin absolu du fichier à modifier |
+| `old_string` | string | Oui | Texte original à remplacer |
+| `new_string` | string | Oui | Nouveau texte de remplacement (doit être différent de old_string) |
+| `replace_all` | boolean | Non | Si toutes les occurrences sont remplacées, par défaut `false` |
+
+## Cas d'utilisation
+
+**Adapté pour :**
+- Modifier des segments de code spécifiques dans des fichiers existants
+- Corriger des bugs, mettre à jour la logique
+- Renommer des variables (avec `replace_all: true`)
+- Tout scénario nécessitant une modification précise du contenu d'un fichier
+
+**Non adapté pour :**
+- Créer de nouveaux fichiers — utiliser Write
+- Réécritures à grande échelle — peut nécessiter Write pour écraser le fichier entier
+
+## Notes
+
+- Le fichier doit avoir été lu préalablement avec Read, sinon une erreur sera retournée
+- `old_string` doit être unique dans le fichier, sinon l'édition échoue. S'il n'est pas unique, fournir plus de contexte pour le rendre unique, ou utiliser `replace_all`
+- Lors de l'édition du texte, l'indentation originale (tab/espaces) doit être conservée, ne pas inclure le préfixe de numéro de ligne de la sortie de Read
+- Préférer l'édition de fichiers existants plutôt que la création de nouveaux
+- `new_string` doit être différent de `old_string`
+
+## Signification dans cc-viewer
+
+Les appels Edit apparaissent dans le journal des requêtes comme des content blocks `tool_use`, dont l'`input` contient `old_string` et `new_string`, permettant de suivre les modifications apportées par le modèle aux fichiers.