cc-viewer 1.6.182 → 1.6.183

package/concepts/pl/Tool-executeCode.md

@@ -1,41 +1,47 @@
-# executeCode (mcp__ide__executeCode)
+# executeCode
 
-## Definicja
+Wykonuje fragment kodu wewnątrz żywego jądra lub sandboxa dostarczonego przez integrację IDE (na przykład jądro Jupyter powiązane z obecnie otwartym notatnikiem). Narzędzie jest dostępne tylko wtedy, gdy Claude Code działa obok kompatybilnego mostu IDE, takiego jak rozszerzenie VS Code z wybranym jądrem Jupyter.
 
-Wykonuje kod Python w jądrze Jupyter bieżącego pliku notebook.
+## Kiedy używać
+
+- Uruchamianie szybkich obliczeń, inspekcji danych lub wykresu względem stanu już załadowanego w aktywnym jądrze Jupyter.
+- Walidowanie fragmentu kodu przed wklejeniem go do komórki notatnika.
+- Eksplorowanie dataframe'a w pamięci, zmiennej lub modelu, który istnieje w jądrze, ale nie jest serializowany na dysk.
+- Produkowanie wykresu lub wyniku liczbowego, który użytkownik chce mieć renderowany inline w IDE.
+
+NIE używaj dla samodzielnych skryptów, którym lepiej odpowiadałby `Bash` uruchamiający `python script.py`, ani dla kodu, który musi trwać przez świeże jądro.
 
 ## Parametry
 
-| Parametr | Typ | Wymagany | Opis |
-|------|------|------|------|
-| `code` | string | Tak | Kod Python do wykonania |
+- `code` (string, wymagany): Kod do wykonania w bieżącym jądrze. Uruchamia się tak, jakby został wklejony do komórki notatnika — zdefiniowane zmienne utrzymują się w jądrze, aż zostanie zrestartowane.
+- `language` (string, opcjonalny): Język fragmentu, gdy most IDE obsługuje wiele jąder. Najczęściej pomijany; domyślnie język aktywnego jądra (zwykle Python).
+
+## Przykłady
+
+### Przykład 1: Inspekcja dataframe'a w pamięci
+
+```
+executeCode(
+  code="df.head()\nprint(df.shape)\nprint(df.dtypes)"
+)
+```
+
+Zwraca pierwsze wiersze, kształt i typy kolumn dataframe'a już załadowanego w jądrze.
 
-## Scenariusze użycia
+### Przykład 2: Szybkie sprawdzenie liczbowe
 
-**Odpowiednie zastosowanie:**
-- Wykonywanie kodu w środowisku Jupyter notebook
-- Testowanie fragmentów kodu
-- Analiza danych i obliczenia
+```
+executeCode(
+  code="import numpy as np\nnp.mean([1, 2, 3, 4, 5])"
+)
+```
 
-**Nieodpowiednie zastosowanie:**
-- Wykonywanie kodu poza środowiskiem Jupyter — należy użyć Bash
-- Modyfikacja plików — należy użyć Edit lub Write
+Wykonuje jednorazowe obliczenie bez tworzenia komórki notatnika.
 
 ## Uwagi
 
-- To jest narzędzie MCP (Model Context Protocol), dostarczane przez integrację z IDE
-- Kod jest wykonywany w bieżącym jądrze Jupyter, stan jest zachowywany między wywołaniami
-- O ile użytkownik wyraźnie nie poprosi, należy unikać deklarowania zmiennych lub modyfikowania stanu jądra
-- Po restarcie jądra stan zostaje utracony
-
-## Tekst oryginalny
-
-<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>
+- `executeCode` to narzędzie mostu IDE. Jest niedostępne w zwykłych sesjach terminalowych Claude Code; pojawia się tylko, gdy sesja jest podłączona do IDE udostępniającego jądro (na przykład rozszerzenia Jupyter w VS Code).
+- Stan utrzymuje się w jądrze. Zmienne zdefiniowane jednym wywołaniem `executeCode` pozostają widoczne dla późniejszych wywołań, komórek notatnika i użytkownika — uważaj na efekty uboczne.
+- Długo działający lub blokujący kod zablokuje jądro. Utrzymuj fragmenty krótkie; dla wielominutowej pracy napisz właściwy skrypt i uruchom go przez `Bash`.
+- Wyjście (stdout, wartości zwracane, obrazy) jest zwracane do sesji. Bardzo duże wyjścia mogą być obcinane przez most IDE.
+- Do edycji plików preferuj `Edit`, `Write` lub `NotebookEdit` — `executeCode` nie jest substytutem autoringu plików źródłowych.

package/concepts/pl/Tool-getDiagnostics.md

@@ -1,32 +1,44 @@
-# getDiagnostics (mcp__ide__getDiagnostics)
+# getDiagnostics
 
-## Definicja
+Pobiera diagnostykę serwera języka (błędy, ostrzeżenia, wskazówki) z podłączonego IDE dla konkretnego pliku lub dla każdego pliku, który IDE ma obecnie otwarty. Używane do weryfikowania, że zmiany kodu kompilują się czysto, przed ogłoszeniem zadania za zakończone.
 
-Pobiera informacje diagnostyczne języka z VS Code, w tym błędy składni, błędy typów, ostrzeżenia lint itp.
+## Kiedy używać
+
+- Po `Edit` lub `Write`, aby potwierdzić, że zmiana nie wprowadziła błędu typu, błędu składni ani ostrzeżenia lintera.
+- Przed zakończeniem zadania, aby przejść przez każdy otwarty plik w poszukiwaniu nierozwiązanych problemów.
+- Gdy diagnozujesz błąd zgłoszony przez użytkownika — wyciągnięcie dokładnego komunikatu kompilatora lub type-checkera z IDE pozwala uniknąć zgadywania.
+- Jako lekkiej alternatywy dla uruchomienia pełnej kompilacji lub polecenia testowego, gdy chcesz sprawdzić tylko statyczną poprawność.
+
+NIE polegaj na `getDiagnostics` jako substytucie zestawu testów. Raportuje to, co widzi serwer języka, a nie to, co działa w czasie testów lub produkcji.
 
 ## Parametry
 
-| Parametr | Typ | Wymagany | Opis |
-|------|------|------|------|
-| `uri` | string | Nie | URI pliku. Jeśli nie podano, pobiera diagnostykę wszystkich plików |
+- `uri` (string, opcjonalny): URI pliku (zwykle `file:///absolute/path`), dla którego pobrać diagnostykę. Gdy pominięty, narzędzie zwraca diagnostykę dla każdego pliku obecnie otwartego w IDE.
 
-## Scenariusze użycia
+## Przykłady
 
-**Odpowiednie zastosowanie:**
-- Sprawdzanie problemów semantycznych kodu: składnia, typy, lint itp.
-- Weryfikacja po edycji kodu, czy nie wprowadzono nowych błędów
-- Zastępowanie poleceń Bash do sprawdzania jakości kodu
+### Przykład 1: Sprawdź pojedynczy plik po edycji
 
-**Nieodpowiednie zastosowanie:**
-- Uruchamianie testów — należy użyć Bash
-- Sprawdzanie błędów runtime — należy użyć Bash do wykonania kodu
+```
+getDiagnostics(
+  uri="file:///Users/sky/project/src/auth.ts"
+)
+```
 
-## Uwagi
+Zwraca wszelkie błędy TypeScript, ostrzeżenia ESLint lub inne komunikaty serwera języka dla `src/auth.ts`.
 
-- To jest narzędzie MCP (Model Context Protocol), dostarczane przez integrację z IDE
-- Dostępne tylko w środowisku VS Code / IDE
-- Preferuj użycie tego narzędzia zamiast poleceń Bash do sprawdzania problemów z kodem
+### Przykład 2: Przeszukaj wszystkie otwarte pliki
 
-## Tekst oryginalny
+```
+getDiagnostics()
+```
+
+Zwraca diagnostykę we wszystkich obecnie otwartych edytorach. Przydatne na końcu wieloplikowego refaktoringu, aby upewnić się, że nic nie zregresowało gdzie indziej.
+
+## Uwagi
 
-<textarea readonly>Get language diagnostics from VS Code</textarea>
+- `getDiagnostics` to narzędzie mostu IDE. Jest dostępne tylko wtedy, gdy Claude Code jest podłączony do wspierającej integracji IDE (na przykład rozszerzenia VS Code). W zwykłej sesji terminalowej narzędzie się nie pojawi.
+- Wyniki odzwierciedlają dowolne serwery języków, które IDE załadowało — TypeScript, Pyright, ESLint, rust-analyzer itd. Jakość i pokrycie zależą od konfiguracji IDE użytkownika, a nie od Claude Code.
+- Diagnostyka jest żywa. Po edycji daj serwerowi języka chwilę na ponowną analizę przed zinterpretowaniem pustego wyniku jako sukcesu — uruchom ponownie, jeśli plik został właśnie zapisany.
+- Poziomy ważności zwykle obejmują `error`, `warning`, `information` oraz `hint`. Skoncentruj się najpierw na `error`; ostrzeżenia mogą być intencjonalnym stylem projektu.
+- Dla plików obecnie nieotwartych w IDE serwer języka może nie mieć żadnej diagnostyki do zgłoszenia, nawet jeśli plik zawiera rzeczywiste problemy. Otwórz plik lub uruchom kompilację dla miarodajnego pokrycia.

package/concepts/pl/Tools.md

@@ -8,7 +8,7 @@ Poniżej znajduje się kategoryzowany indeks wszystkich narzędzi.
 
 | Narzędzie | Przeznaczenie |
 |------|------|
-| [Task](Tool-Task.md) | Uruchomienie sub-agenta (SubAgent) do obsługi złożonych wieloetapowych zadań |
+| [Agent](Tool-Agent.md) | Uruchomienie sub-agenta (SubAgent) do obsługi złożonych wieloetapowych zadań |
 | [TaskOutput](Tool-TaskOutput.md) | Pobranie wyniku zadania w tle |
 | [TaskStop](Tool-TaskStop.md) | Zatrzymanie działającego zadania w tle |
 | [TaskCreate](Tool-TaskCreate.md) | Utworzenie wpisu na strukturalnej liście zadań |

package/concepts/pt-BR/SubAgent-Search.md

@@ -1,20 +1,52 @@
 # SubAgent: Search
 
-## Definição
+## Propósito
 
-Search é um tipo de sub-agent gerado pelo agente principal do Claude Code para realizar buscas na base de código. Ele executa buscas direcionadas de arquivos e conteúdo usando ferramentas como Glob, Grep e Read, e então retorna os resultados ao agente pai.
+O subagente Search é um agente de exploração leve e somente leitura. Despache-o quando precisar entender um codebase — encontrar onde algo vive, aprender como componentes se encaixam ou responder perguntas estruturais — sem alterar nenhum arquivo. Ele é otimizado para muitas leituras pequenas em muitos arquivos, retornando um resumo conciso em vez de saída bruta de busca.
 
-## Comportamento
+Search não é um assistente de propósito geral. Ele não pode editar código, rodar builds, commitar mudanças ou abrir conexões de rede além de fetches somente leitura. Seu valor é que pode queimar um grande orçamento de exploração em paralelo sem consumir o contexto do agente principal, e então devolver uma resposta compacta.
 
-- Gerado automaticamente quando o agente principal precisa buscar ou explorar a base de código
-- Executa em um contexto isolado com acesso somente leitura
-- Usa Glob para correspondência de padrões de arquivos, Grep para busca de conteúdo e Read para inspeção de arquivos
-- Retorna resultados de busca ao agente pai para processamento adicional
+## Quando usar
 
-## Quando aparece
+- Você precisa responder a uma pergunta que requer três ou mais buscas ou leituras distintas. Exemplo: "Como a autenticação está conectada desde a rota de login até o armazenamento de sessão?"
+- O alvo é desconhecido — você ainda não sabe qual arquivo, módulo ou símbolo olhar.
+- Você precisa de uma visão estrutural de uma área desconhecida do repositório antes de fazer mudanças.
+- Você quer cruzar múltiplos candidatos (por exemplo, qual dentre vários helpers com nomes similares é de fato chamado em produção).
+- Você precisa de um resumo em estilo de revisão de literatura: "liste todo lugar que importa X e categorize por ponto de chamada."
 
-Sub-agents Search tipicamente aparecem quando:
+Não use Search quando:
 
-1. O agente principal precisa encontrar arquivos, funções ou padrões de código específicos
-2. Uma exploração ampla da base de código é solicitada pelo usuário
-3. O agente está investigando dependências, referências ou padrões de uso
+- Você já sabe o arquivo e a linha exatos. Chame `Read` diretamente.
+- Um único `Grep` ou `Glob` responderá à pergunta. Rode diretamente; despachar um subagente adiciona overhead.
+- A tarefa requer editar, rodar comandos ou qualquer efeito colateral. Search é somente leitura por design.
+- Você precisa da saída exata literal de uma chamada de ferramenta. Subagentes resumem; não atuam como proxy de resultados brutos.
+
+## Níveis de minúcia
+
+Escolha o nível que corresponde ao peso da pergunta.
+
+- `quick` — algumas buscas direcionadas, resposta de melhor esforço. Use quando precisar de uma pista rápida (por exemplo, "onde está a lógica de parsing de variáveis de ambiente?") e estiver confortável em iterar se a resposta for incompleta.
+- `medium` — o padrão. Várias rodadas de busca, cross-check de candidatos e leitura dos arquivos mais relevantes por completo. Use para perguntas típicas do tipo "me ajude a entender esta área".
+- `very thorough` — exploração exaustiva. O subagente perseguirá toda pista plausível, lerá contexto ao redor e reverificará achados antes de resumir. Use quando a correção importa (por exemplo, revisão de segurança, planejamento de migração) ou quando uma resposta incompleta causará retrabalho.
+
+Minúcia mais alta custa mais tempo e tokens dentro do subagente, mas esses tokens ficam dentro do subagente — apenas o resumo final retorna ao agente principal.
+
+## Ferramentas disponíveis
+
+O Search tem acesso a todas as ferramentas somente leitura que o agente principal usa, e nada mais:
+
+- `Read` — para ler arquivos específicos, incluindo intervalos parciais.
+- `Grep` — para buscas de conteúdo na árvore.
+- `Glob` — para localizar arquivos por padrão de nome.
+- `Bash` em modo somente leitura — para comandos que inspecionam estado sem mutá-lo (por exemplo `git log`, `git show`, `ls`, `wc`).
+- `WebFetch` e `WebSearch` — para ler documentação externa quando esse contexto for necessário.
+
+Ferramentas de edição (`Write`, `Edit`, `NotebookEdit`), comandos de shell que modificam estado e ferramentas do grafo de tarefas (`TaskCreate`, `TaskUpdate` e assim por diante) estão deliberadamente indisponíveis.
+
+## Observações
+
+- Dê ao subagente Search uma pergunta específica, não um tópico. "Liste todo caller de `renderMessage` e anote quais passam um tema customizado" retorna uma resposta útil; "me conte sobre renderização" não.
+- O subagente retorna um resumo. Se você precisa de caminhos de arquivo exatos, peça-os explicitamente em seu prompt.
+- Múltiplas perguntas independentes são melhor despachadas como subagentes Search paralelos em vez de um prompt longo, para que cada um possa focar.
+- Como Search não pode editar, emparelhe-o com um passo de edição subsequente no agente principal uma vez que você saiba o que mudar.
+- Trate a saída do Search como evidência, não como verdade absoluta. Para qualquer coisa crítica, abra os arquivos citados você mesmo antes de agir.

package/concepts/pt-BR/Tool-Agent.md

@@ -1,125 +1,60 @@
 # Agent
 
-## Definição
+Inicia um subagente autônomo do Claude Code com sua própria janela de contexto para lidar com uma tarefa focada e retornar um único resultado consolidado. Este é o mecanismo canônico para delegar pesquisas abertas, trabalho paralelo ou colaboração em equipe.
 
-Inicia um sub-agent (SubAgent) para processar autonomamente tarefas complexas de múltiplas etapas. Sub-agents são subprocessos independentes, cada um com seu próprio conjunto de ferramentas e contexto dedicados. Agent é a versão renomeada da ferramenta Task nas versões mais recentes do Claude Code.
+## Quando usar
 
-## Parâmetros
-
-| Parâmetro | Tipo | Obrigatório | Descrição |
-|------|------|------|------|
-| `prompt` | string | Sim | Descrição da tarefa a ser executada pelo sub-agent |
-| `description` | string | Sim | Resumo curto de 3-5 palavras |
-| `subagent_type` | string | Sim | Tipo do sub-agent, determina o conjunto de ferramentas disponíveis |
-| `model` | enum | Não | Modelo especificado (sonnet / opus / haiku), herda do pai por padrão |
-| `max_turns` | integer | Não | Número máximo de turnos agênticos |
-| `run_in_background` | boolean | Não | Se deve executar em segundo plano; tarefas em segundo plano retornam caminho do output_file |
-| `resume` | string | Não | ID do agent a retomar, continua da última execução. Útil para retomar um sub-agent anterior sem perder o contexto |
-| `isolation` | enum | Não | Modo de isolamento, `worktree` cria um git worktree temporário |
-
-## Tipos de Sub-agent
-
-| Tipo | Finalidade | Ferramentas Disponíveis |
-|------|------|----------|
-| `Bash` | Execução de comandos, operações git | Bash |
-| `general-purpose` | Tarefas genéricas de múltiplas etapas | Todas as ferramentas |
-| `Explore` | Exploração rápida da base de código | Todas exceto Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `Plan` | Projetar plano de implementação | Todas exceto Agent/Edit/Write/NotebookEdit/ExitPlanMode |
-| `claude-code-guide` | Q&A sobre guia de uso do Claude Code | Glob, Grep, Read, WebFetch, WebSearch |
-| `statusline-setup` | Configurar barra de status | Read, Edit |
-
-## Cenários de Uso
-
-**Adequado para:**
-- Tarefas complexas que requerem múltiplas etapas autônomas
-- Exploração e pesquisa aprofundada da base de código (usando tipo Explore)
-- Trabalho paralelo que requer ambiente isolado
-- Tarefas de longa duração que precisam executar em segundo plano
+- Pesquisas abertas em que você ainda não sabe quais arquivos são relevantes e espera várias rodadas de `Glob`, `Grep` e `Read`.
+- Trabalho independente paralelo — dispare vários agentes em uma única mensagem para investigar áreas distintas simultaneamente.
+- Isolar exploração ruidosa da conversa principal para que o contexto do agente pai permaneça compacto.
+- Delegar para um tipo de subagente especializado como `Explore`, `Plan`, `claude-code-guide` ou `statusline-setup`.
+- Inserir um colega de equipe nomeado em uma equipe ativa para trabalho multiagente coordenado.
 
-**Não adequado para:**
-- Ler um caminho de arquivo específico — usar Read ou Glob diretamente
-- Buscar em 2-3 arquivos conhecidos — usar Read diretamente
-- Buscar definição de classe específica — usar Glob diretamente
+NÃO use quando o arquivo ou símbolo-alvo já é conhecido — use `Read`, `Grep` ou `Glob` diretamente. Uma consulta de passo único via `Agent` desperdiça uma janela de contexto inteira e adiciona latência.
 
-## Observações
-
-- Após conclusão, o sub-agent retorna uma única mensagem; seus resultados não são visíveis ao usuário, o agent principal precisa retransmitir
-- Pode iniciar múltiplas chamadas Agent em paralelo em uma única mensagem para maior eficiência
-- Tarefas em segundo plano verificam progresso via ferramenta TaskOutput
-- O tipo Explore é mais lento que chamar Glob/Grep diretamente, use apenas quando buscas simples não são suficientes
-- Use `run_in_background: true` para tarefas de longa duração que não precisam de resultados imediatos; use o modo em primeiro plano (padrão) quando o resultado é necessário antes de prosseguir
-- O parâmetro `resume` permite continuar uma sessão de sub-agent iniciada anteriormente, preservando o contexto acumulado
-
-## Texto original
+## Parâmetros
 
-<textarea readonly>Launch a new agent to handle complex, multi-step tasks autonomously.
+- `description` (string, obrigatório): Rótulo curto de 3–5 palavras descrevendo a tarefa; exibido na interface e nos logs.
+- `prompt` (string, obrigatório): O briefing completo e autossuficiente que o agente executará. Deve incluir todo o contexto necessário, restrições e o formato de retorno esperado.
+- `subagent_type` (string, opcional): Persona predefinida como `general-purpose`, `Explore`, `Plan`, `claude-code-guide` ou `statusline-setup`. O padrão é `general-purpose`.
+- `run_in_background` (boolean, opcional): Se `true`, o agente executa de forma assíncrona e o agente pai pode continuar trabalhando; os resultados são recuperados depois.
+- `model` (string, opcional): Substitui o modelo para este agente — `opus`, `sonnet` ou `haiku`. O padrão é o modelo da sessão pai.
+- `isolation` (string, opcional): Defina como `worktree` para rodar o agente dentro de um worktree git isolado para que suas gravações no sistema de arquivos não colidam com o pai.
+- `team_name` (string, opcional): Ao inserir em uma equipe existente, o identificador da equipe que o agente entrará.
+- `name` (string, opcional): Nome endereçável do colega de equipe, usado como alvo `to` em `SendMessage`.
 
-The Agent tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+## Exemplos
 
-Available agent types and the tools they have access to:
-- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. (Tools: *)
-- statusline-setup: Use this agent to configure the user's Claude Code status line setting. (Tools: Read, Edit)
-- Explore: Fast agent specialized for exploring codebases. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?"). When calling this agent, specify the desired thoroughness level: "quick" for basic searches, "medium" for moderate exploration, or "very thorough" for comprehensive analysis across multiple locations and naming conventions. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- Plan: Software architect agent for designing implementation plans. Use this when you need to plan the implementation strategy for a task. Returns step-by-step plans, identifies critical files, and considers architectural trade-offs. (Tools: All tools except Agent, ExitPlanMode, Edit, Write, NotebookEdit)
-- claude-code-guide: Use this agent when the user asks questions ("Can Claude...", "Does Claude...", "How do I...") about: (1) Claude Code (the CLI tool) - features, hooks, slash commands, MCP servers, settings, IDE integrations, keyboard shortcuts; (2) Claude Agent SDK - building custom agents; (3) Claude API (formerly Anthropic API) - API usage, tool use, Anthropic SDK usage. **IMPORTANT:** Before spawning a new agent, check if there is already a running or recently completed claude-code-guide agent that you can resume using the "resume" parameter. (Tools: Glob, Grep, Read, WebFetch, WebSearch)
+### Exemplo 1: Busca aberta de código
 
-When using the Agent tool, you must specify a subagent_type parameter to select which agent type to use.
+```
+Agent(
+  description="Find auth middleware",
+  subagent_type="Explore",
+  prompt="Locate every place in this repo where JWT verification is performed. Return a bulleted list of absolute file paths with a one-line note about each site's role. Do not modify any files."
+)
+```
 
-When NOT to use the Agent tool:
-- If you want to read a specific file path, use the Read or Glob tool instead of the Agent tool, to find the match more quickly
-- If you are searching for a specific class definition like "class Foo", use the Glob tool instead, to find the match more quickly
-- If you are searching for code within a specific file or set of 2-3 files, use the Read tool instead of the Agent tool, to find the match more quickly
-- Other tasks that are not related to the agent descriptions above
+### Exemplo 2: Investigações independentes paralelas
 
-Usage notes:
-- Always include a short description (3-5 words) summarizing what the agent will do
-- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
-- You can optionally run agents in the background using the run_in_background parameter. When an agent runs in the background, you will be automatically notified when it completes — do NOT sleep, poll, or proactively check on its progress. Continue with other work or respond to the user instead.
-- **Foreground vs background**: Use foreground (default) when you need the agent's results before you can proceed — e.g., research agents whose findings inform your next steps. Use background when you have genuinely independent work to do in parallel.
-- Agents can be resumed using the `resume` parameter by passing the agent ID from a previous invocation. When resumed, the agent continues with its full previous context preserved. When NOT resuming, each invocation starts fresh and you should provide a detailed task description with all necessary context.
-- When the agent is done, it will return a single message back to you along with its agent ID. You can use this ID to resume the agent later if needed for follow-up work.
-- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
-- Agents with "access to current context" can see the full conversation history before the tool call. When using these agents, you can write concise prompts that reference earlier context (e.g., "investigate the error discussed above") instead of repeating information. The agent will receive all prior messages and understand the context.
-- The agent's outputs should generally be trusted
-- Clearly tell the agent whether you expect it to write code or just to do research (search, file reads, web fetches, etc.), since it is not aware of the user's intent
-- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.
-- If the user specifies that they want you to run agents "in parallel", you MUST send a single message with multiple Agent tool use content blocks. For example, if you need to launch both a build-validator agent and a test-runner agent in parallel, send a single message with both tool calls.
-- You can optionally set `isolation: "worktree"` to run the agent in a temporary git worktree, giving it an isolated copy of the repository. The worktree is automatically cleaned up if the agent makes no changes; if changes are made, the worktree path and branch are returned in the result.
+Dispare dois agentes na mesma mensagem — um inspecionando o pipeline de build, outro revisando o harness de testes. Cada um recebe sua própria janela de contexto e retorna um resumo. Agrupá-los em um único bloco de chamadas de ferramenta os executa simultaneamente.
 
-Example usage:
+### Exemplo 3: Inserir um colega de equipe em uma equipe em execução
 
-<example_agent_descriptions>
-"test-runner": use this agent after you are done writing code to run tests
-"greeting-responder": use this agent to respond to user greetings with a friendly joke
-</example_agent_descriptions>
+```
+Agent(
+  description="Data layer specialist",
+  team_name="refactor-crew",
+  name="db-lead",
+  prompt="You are db-lead on team refactor-crew. Audit all Prisma schema files and propose a migration plan. Use SendMessage to report findings to the team leader."
+)
+```
 
-<example>
-user: "Please write a function that checks if a number is prime"
-assistant: Sure let me write a function that checks if a number is prime
-assistant: First let me use the Write tool to write a function that checks if a number is prime
-assistant: I'm going to use the Write tool to write the following code:
-<code>
-function isPrime(n) {
-  if (n <= 1) return false
-  for (let i = 2; i * i <= n; i++) {
-    if (n % i === 0) return false
-  }
-  return true
-}
-</code>
-<commentary>
-Since a significant piece of code was written and the task was completed, now use the test-runner agent to run the tests
-</commentary>
-assistant: Now let me use the test-runner agent to run the tests
-assistant: Uses the Agent tool to launch the test-runner agent
-</example>
+## Observações
 
-<example>
-user: "Hello"
-<commentary>
-Since the user is greeting, use the greeting-responder agent to respond with a friendly joke
-</commentary>
-assistant: "I'm going to use the Agent tool to launch the greeting-responder agent"
-</example>
-</textarea>
+- Agentes não têm memória de execuções anteriores. Cada invocação começa do zero, portanto o `prompt` deve ser totalmente autossuficiente — inclua caminhos de arquivos, convenções, a pergunta e o formato exato da resposta desejada.
+- O agente retorna exatamente uma mensagem final. Ele não pode fazer perguntas de esclarecimento durante a execução, então ambiguidade no prompt vira suposição no resultado.
+- Executar múltiplos agentes em paralelo é significativamente mais rápido do que chamadas sequenciais quando as subtarefas são independentes. Agrupe-os em um único bloco de chamadas de ferramenta.
+- Use `isolation: "worktree"` sempre que um agente for gravar arquivos e você quiser revisar as mudanças antes de integrar na árvore de trabalho principal.
+- Prefira `subagent_type: "Explore"` para reconhecimento somente leitura e `Plan` para trabalho de design; `general-purpose` é o padrão para tarefas mistas de leitura/escrita.
+- Agentes em segundo plano (`run_in_background: true`) são adequados para trabalhos longos; evite polling em loop com `sleep` — o pai é notificado na conclusão.

package/concepts/pt-BR/Tool-AskUserQuestion.md

@@ -1,75 +1,60 @@
 # AskUserQuestion
 
-## Definição
+Apresenta ao usuário uma ou mais perguntas de múltipla escolha estruturadas dentro da interface do chat, coleta suas seleções e as devolve ao assistente — útil para desambiguar a intenção sem uma troca de mensagens em texto livre.
 
-Faz perguntas ao usuário durante a execução, para obter esclarecimentos, validar suposições ou solicitar decisões.
+## Quando usar
 
-## Parâmetros
-
-| Parâmetro | Tipo | Obrigatório | Descrição |
-|------|------|------|------|
-| `questions` | array | Sim | Lista de perguntas (1-4 perguntas) |
-| `answers` | object | Não | Respostas coletadas do usuário |
-| `annotations` | object | Não | Anotações para cada pergunta (ex: notas de pré-visualização de seleção) |
-| `metadata` | object | Não | Metadados para rastreamento e análise |
-
-Cada objeto `question`:
-
-| Campo | Tipo | Obrigatório | Descrição |
-|------|------|------|------|
-| `question` | string | Sim | Texto completo da pergunta, deve terminar com ponto de interrogação |
-| `header` | string | Sim | Rótulo curto (máximo 12 caracteres), exibido como chip de tag |
-| `options` | array | Sim | 2-4 opções |
-| `multiSelect` | boolean | Sim | Se permite seleção múltipla |
-
-Cada objeto `option`:
-
-| Campo | Tipo | Obrigatório | Descrição |
-|------|------|------|------|
-| `label` | string | Sim | Texto de exibição da opção (1-5 palavras) |
-| `description` | string | Sim | Descrição da opção |
-| `markdown` | string | Não | Conteúdo de pré-visualização (para comparação visual de layouts ASCII, trechos de código, etc.) |
-
-## Cenários de Uso
+- Um pedido tem múltiplas interpretações razoáveis e o assistente precisa que o usuário escolha uma antes de prosseguir.
+- O usuário precisa escolher entre opções concretas (framework, biblioteca, caminho de arquivo, estratégia) onde respostas em texto livre seriam propensas a erro.
+- Você quer comparar alternativas lado a lado usando o painel de pré-visualização.
+- Várias decisões relacionadas podem ser agrupadas em um único prompt para reduzir idas e vindas.
+- Um plano ou chamada de ferramenta depende de configuração que o usuário ainda não especificou.
 
-**Adequado para:**
-- Coletar preferências ou requisitos do usuário
-- Esclarecer instruções ambíguas
-- Obter decisões durante a implementação
-- Oferecer opções de direção ao usuário
+## Parâmetros
 
-**Não adequado para:**
-- Perguntar "o plano está ok?" — deve usar ExitPlanMode
+- `questions` (array, obrigatório): De uma a quatro perguntas exibidas juntas em um único prompt. Cada objeto de pergunta contém:
+  - `question` (string, obrigatório): O texto completo da pergunta, terminando com ponto de interrogação.
+  - `header` (string, obrigatório): Um rótulo curto (no máximo 12 caracteres) renderizado como um chip acima da pergunta.
+  - `options` (array, obrigatório): De duas a quatro opções. Cada opção tem um `label` (1–5 palavras), uma `description` e um `markdown` opcional para pré-visualização.
+  - `multiSelect` (boolean, obrigatório): Quando `true`, o usuário pode escolher mais de uma opção.
+
+## Exemplos
+
+### Exemplo 1: Escolher um único framework
+
+```
+AskUserQuestion(questions=[{
+  "header": "Test runner",
+  "question": "Which test runner should I configure?",
+  "multiSelect": false,
+  "options": [
+    {"label": "Vitest (Recommended)", "description": "Fast, Vite-native, Jest-compatible API"},
+    {"label": "Jest",                  "description": "Mature, broadest plugin ecosystem"},
+    {"label": "Node --test",           "description": "Zero dependencies, built in"}
+  ]
+}])
+```
+
+### Exemplo 2: Pré-visualização lado a lado de dois layouts
+
+```
+AskUserQuestion(questions=[{
+  "header": "Layout",
+  "question": "Which dashboard layout do you prefer?",
+  "multiSelect": false,
+  "options": [
+    {"label": "Sidebar",  "description": "Nav on the left", "markdown": "```\n+------+---------+\n| NAV  | CONTENT |\n+------+---------+\n```"},
+    {"label": "Top bar",  "description": "Nav across top",  "markdown": "```\n+-----------------+\n|       NAV       |\n+-----------------+\n|     CONTENT     |\n+-----------------+\n```"}
+  ]
+}])
+```
 
 ## Observações
 
-- O usuário sempre pode escolher "Other" para fornecer entrada personalizada
-- A opção recomendada deve ser colocada em primeiro lugar, com "(Recommended)" no final do label
-- A pré-visualização `markdown` é suportada apenas para perguntas de seleção única
-- Opções com `markdown` alternam para layout lado a lado
-- No modo de planejamento, usado para esclarecer requisitos antes de definir o plano
-
-## Texto original
-
-<textarea readonly>Use this tool when you need to ask the user questions during execution. This allows you to:
-1. Gather user preferences or requirements
-2. Clarify ambiguous instructions
-3. Get decisions on implementation choices as you work
-4. Offer choices to the user about what direction to take.
-
-Usage notes:
-- Users will always be able to select "Other" to provide custom text input
-- Use multiSelect: true to allow multiple answers to be selected for a question
-- If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
-
-Plan mode note: In plan mode, use this tool to clarify requirements or choose between approaches BEFORE finalizing your plan. Do NOT use this tool to ask "Is my plan ready?" or "Should I proceed?" - use ExitPlanMode for plan approval. IMPORTANT: Do not reference "the plan" in your questions (e.g., "Do you have feedback about the plan?", "Does the plan look good?") because the user cannot see the plan in the UI until you call ExitPlanMode. If you need plan approval, use ExitPlanMode instead.
-
-Preview feature:
-Use the optional `markdown` field on options when presenting concrete artifacts that users need to visually compare:
-- ASCII mockups of UI layouts or components
-- Code snippets showing different implementations
-- Diagram variations
-- Configuration examples
-
-When any option has a markdown, the UI switches to a side-by-side layout with a vertical option list on the left and preview on the right. Do not use previews for simple preference questions where labels and descriptions suffice. Note: previews are only supported for single-select questions (not multiSelect).
-</textarea>
+- A interface adiciona automaticamente uma opção "Other" de texto livre a cada pergunta. Não adicione sua própria entrada "Other", "None" ou "Custom" — ela duplicará a válvula de escape embutida.
+- Limite cada chamada a entre uma e quatro perguntas e cada pergunta a entre duas e quatro opções. Exceder esses limites é rejeitado pelo harness.
+- Se você recomendar uma opção específica, coloque-a em primeiro lugar e anexe "(Recommended)" ao seu label para que a interface destaque o caminho preferido.
+- Pré-visualizações via o campo `markdown` só são suportadas em perguntas de seleção única. Use-as para artefatos visuais como layouts em ASCII, trechos de código ou diffs de configuração — não para perguntas simples de preferência onde label mais descrição bastam.
+- Quando qualquer opção em uma pergunta tem um valor `markdown`, a interface muda para um layout lado a lado com a lista de opções à esquerda e a pré-visualização à direita.
+- Não use `AskUserQuestion` para perguntar "este plano parece bom?" — chame `ExitPlanMode` em vez disso, que existe precisamente para aprovação de planos. No modo de plano, evite também mencionar "o plano" no texto da pergunta, pois o plano não é visível para o usuário até que `ExitPlanMode` seja executado.
+- Não use esta ferramenta para solicitar entrada sensível ou de texto livre, como chaves de API ou senhas. Pergunte no chat em vez disso.