Ferramentas de agente integradas

Estas são as ferramentas vinculadas ao servidor que o runtime de agente integrado registra diretamente — servidor de linguagem, busca estrutural, depurador, kernels, perguntas e controle de workers —, em oposição às ferramentas MCP que ele conecta por ponte e às ferramentas genéricas de arquivo, busca e shell do runtime do harness. Elas não estão no registro MCP: um cliente MCP externo não as verá, porque cada uma está vinculada a um recurso vivo do lado do servidor — um processo de servidor de linguagem, um adaptador de depuração, um interpretador — que pertence a uma execução.

Toda ferramenta aqui só é registrada quando o recurso que a sustenta está conectado para a execução — um supervisor de servidor de linguagem ou de depuração, um analisador tree-sitter, uma fábrica de kernels, uma porta de perguntas, uma lista de workers de vibe. A detecção de um servidor de linguagem ou de um adaptador de depuração para este checkout é uma verificação separada e posterior (status / adapters): essas ferramentas permanecem na superfície para que o agente possa perguntar por que nada está utilizável, em vez de adivinhar.

Níveis de aprovação

Cada ferramenta declara um nível, e o nível decide quais superfícies a veem — não apenas se ela pede aprovação. O modo plano e os subagentes somente leitura têm como teto o read, então uma ferramenta de nível write ou exec está totalmente ausente do esquema deles.

Nível	Significado	Ferramentas aqui
read	Sem efeitos colaterais	lsp, ast_grep, ask_user, as cinco vibe_*
write	Altera arquivos	lsp_rename, ast_edit, resolve
exec	Inicia ou controla um processo	debug, eval

---

lsp — consultas ao servidor de linguagem

Registrada quando a execução tem um supervisor de servidor de linguagem e um diretório de trabalho. Se um servidor consegue de fato responder é detectado no momento da chamada, como uma interseção: um marcador de raiz precisa existir e o binário do servidor precisa resolver. Qualquer um dos dois sozinho significa que nenhum servidor inicia — o status diz isso —, em vez de um chute silencioso.

As posições são endereçadas por line mais uma substring symbol, nunca por coluna. Um modelo a quem se pede uma coluna chuta, e um chute errado resolve para outro símbolo na mesma linha — uma resposta que parece certa e trata de outra coisa. Omitir symbol em uma ação de navegação é um erro, não um chute para a primeira coluna.

Ação	Argumentos	Retorna
diagnostics	file (ou "*")	Erros e avisos; "*" executa o verificador do projeto em vez disso
definition	file, line, symbol	Onde o símbolo é declarado
type_definition	file, line, symbol	Onde o tipo dele é declarado
implementation	file, line, symbol	Implementações concretas
references	file, line, symbol	Todos os usos, limitados a 50
hover	file, line, symbol	Assinatura e comentário de documentação
symbols	query ou file	Busca no espaço de trabalho com query (limitada a 100); símbolos do documento com file (limitados a 200)
code_actions	file, line, symbol	Correções rápidas que o servidor oferece
status	—	Quais servidores estão rodando, e para quais raízes
reload	—	Reinicia o servidor para esta raiz

Diagnósticos ao escrever

O ganho não está na ferramenta. write, edit e apply_patch são envolvidos: depois da escrita, o arquivo é sincronizado e salvo pelo servidor de linguagem, e apenas os diagnósticos introduzidos recentemente são incorporados ao resultado da ferramenta. O agente descobre que quebrou a build no momento em que a quebrou, sem precisar lembrar de perguntar.

Os diagnósticos já reportados são suprimidos por um registro por execução com chave em gravidade, código e mensagem — posição deliberadamente excluída, de modo que um diagnóstico que apenas desceu quatro linhas não é reportado de novo como novo.

lsp_rename — renomeação em todo o projeto

Uma ferramenta separada, de nível write, por exatamente um motivo: o nível decide a visibilidade. Juntar a renomeação ao lsp ou daria a um explorador somente leitura a capacidade de reescrever o repo, ou colocaria todo hover atrás de uma solicitação de aprovação.

Argumento	Significado
file	Onde o símbolo está
line	Linha indexada a partir de 1
symbol	Substring que o identifica naquela linha
new_name	Como chamá-lo

---

ast_grep — busca estrutural

Encontra código por forma, e não por texto. $NAME casa qualquer nó, $$$NAME casa uma sequência de irmãos, e $_ é um curinga que não captura nada.

A propriedade que faz dele um comparador, e não uma regex com etapas extras: uma metavariável repetida em um mesmo padrão precisa capturar o mesmo texto.

ast_grep(pattern: "if ($X != null) $X.dispose()", language: "dart")

casa com uma guarda que descarta o que ela testou e não casa com uma que descarta outra coisa.

Argumento	Significado
pattern	Um fragmento de código com metavariáveis
path	Arquivo ou diretório a pesquisar; o padrão é todo o espaço de trabalho
language	Um id de gramática distribuído (dart, python, rust, c, …). Inferido quando path nomeia um arquivo
max_results	Padrão 50

O padrão é analisado pela mesma gramática do arquivo

Então dispose(x) casa com a chamada de qualquer jeito que esteja espaçada, quebrada em várias linhas ou comentada — e nunca casa os mesmos caracteres dentro de um literal de string ou de um comentário.

Um fragmento é analisado em um andaime, e não isolado

Analisado no nível superior do Dart, dispose(x) é uma assinatura de função válida. O compilador de padrões tenta uma escada de contextos (instrução, expressão, membro de classe, declaração) e usa o primeiro que aceita o fragmento. Um padrão que nenhum contexto aceita é reportado como não analisável, em vez de ser procurado e silenciosamente não encontrado.

ast_edit — reescrita estrutural, preparada

A mesma correspondência, mais um modelo rewrite com as metavariáveis substituídas de volta. Nada é escrito. A alteração é preparada e o resultado nomeia um edit_id.

ast_edit(pattern: "dispose($X)", rewrite: "$X.dispose()", language: "dart")
→ (proposed) 12 replacements in 4 files … call resolve with edit_id "edit_1"

Argumento	Significado
pattern	O que casar
rewrite	O que colocar no lugar, com $NAME substituído
path	Escopo; o padrão é todo o espaço de trabalho
language	Id da linguagem

resolve — confirmar ou descartar uma alteração preparada

Argumento	Significado
edit_id	Do resultado (proposed)
action	accept ou discard

Cada arquivo é comparado com o conteúdo capturado no momento da preparação, e qualquer divergência recusa a alteração inteira. Uma reescrita estrutural aplicada em parte deixa uma árvore que não compila na forma antiga nem na nova.

---

debug — conduzir um depurador

Registrada quando a execução tem um supervisor de sessão de depuração, um diretório de trabalho e um id de conversa. Se um adaptador consegue de fato iniciar é detectado no momento da chamada, pela mesma regra de interseção do servidor de linguagem (marcador de raiz e binário). Nível exec; não é segura para paralelismo (uma sessão é estado entre chamadas, então um continue que ultrapassasse o stack leria um frame que já se moveu).

Uma sessão por conversa, com um TTL rígido (30 minutos). Um segundo launch é recusado em vez de substituir silenciosamente o primeiro.

Operação	Argumentos	Observações
adapters	—	Quais adaptadores são utilizáveis aqui, e por que não
status	—	Se uma sessão está em execução, e onde ela parou
breakpoints	file, lines[]	lines vazio limpa o arquivo. Podem ser definidos antes de iniciar
launch	program, args[]	Inicia o programa parado nos seus pontos de interrupção
attach	port	Conecta-se a um processo já em execução
continue	thread_id?	Roda até a próxima parada
pause	thread_id?	Para onde ele estiver
step_over / step_in / step_out	thread_id?	Avança um passo
threads	—	Ids e nomes das threads
stack	thread_id?	Frames, limitados a 30
scopes	frame_id	Escopos de um frame, cada um com um reference
variables	reference	Filhos, limitados a 50; valores, limitados a 400 caracteres
evaluate	expression, frame_id?	Avaliada no próprio escopo do frame
output	—	O stdout/stderr do processo depurado, com limite
terminate	—	Encerra a sessão e mata o adaptador

Adaptadores

Id	Comando	Marcadores de raiz
dart	dart debug_adapter	pubspec.yaml
debugpy	python3 -m debugpy.adapter	pyproject.toml, setup.py, requirements.txt
lldb	lldb-dap	Cargo.toml, CMakeLists.txt
delve	dlv dap	go.mod

O debugpy prefere um .venv/bin ou venv/bin local do projeto ao $PATH: um python do $PATH é outro ambiente, e anexar a partir do errado falha de um jeito que se lê como código quebrado.

---

eval — interpretadores persistentes

Uma célula de Python ou JavaScript cujas variáveis, importações e dados carregados sobrevivem entre chamadas. Nível exec; não é segura para paralelismo.

Argumento	Significado
code	A célula
description	Obrigatório. 5–10 palavras para o rótulo da transcrição
language	python (padrão) ou javascript
reset	Descarta o interpretador e começa do zero

• A última expressão é ecoada como um notebook faz.
• display() funciona, um frame do pandas é renderizado como tabela e uma figura do matplotlib volta como uma imagem que a transcrição mostra.
• As expressões idiomáticas do IPython que as pessoas digitam por reflexo — %pip, %cd, !cmd, %%bash, %%timeit — são reescritas como código comum. O %pip também esvazia o sys.modules, então o próximo import vê o que acabou de ser instalado.

Chamar suas próprias ferramentas de dentro de uma célula

contents = tool("read", {"path": "lib/auth.dart"})

A ponte entra novamente no registro de ferramentas do harness, então os guardrails, a aprovação e todos os wrappers se aplicam exatamente como em uma chamada emitida pelo modelo. Ela trafega pelo próprio pipe do kernel, e não por um socket de loopback: sem porta, sem segredo, sem regra de saída.

O timeout da célula é um orçamento de inatividade (padrão de 5 minutos) e fica suspenso enquanto há uma chamada via ponte pendente, então uma célula que se distribui para subagentes não é morta no meio da distribuição.

Onde o kernel roda

No recinto da conversa quando ela tem um; caso contrário, no host. Ele não inicializa um recinto para chegar até lá — a mesma regra que impede uma aba de rig de iniciar automaticamente.

---

ask_user — fazer uma pergunta ao humano

Nível read. A única forma de uma execução perguntar algo ao operador. Ela renderiza um cartão numerado na conversa e bloqueia até que alguém responda, pule ou a pergunta expire. Nunca escreva a pergunta como mensagem de chat — isso encerra o turno.

Argumento	Significado
question	O que perguntar
context	Opcional: por que você está perguntando e o que depende da resposta
options[]	Escolhas, cada uma {label, description?}
allow_free_text	Se uma resposta digitada é aceita
multi_select	Se várias opções podem ser escolhidas

Pular é sucesso: prossiga com uma suposição declarada e não pergunte de novo. Um tempo esgotado é um erro com a mesma instrução. As solicitações de permissão (“posso fazer isso?”) são um portão separado e são renderizadas como o mesmo cartão na conversa.

Registrada apenas quando existem tanto uma porta de perguntas quanto um espaço de destino. Sem um humano conectado, a chamada falha em vez de bloquear para sempre — a mesma postura de falha fechada que um prompt de guardrail adota quando não há aprovador conectado.

---

vibe_* — dirigir workers em segundo plano

Registradas apenas enquanto o modo vibe está ligado. As cinco são de nível read: o portão pertence às ferramentas do worker, onde a edição de fato acontece.

Ferramenta	Argumentos	Observações
vibe_spawn	brief, label, tier?	Retorna imediatamente; o worker segue rodando
vibe_send	worker_id, message	Anexa ao briefing e executa de novo
vibe_wait	worker_id, timeout_seconds?	Bloqueia até que ele termine
vibe_kill	worker_id	Para ele
vibe_list	—	Nível, status, tempo decorrido e último resultado

O tier é fast (trabalho mecânico com especificação clara) ou good (design, julgamento ou revisão do que um worker fast produziu).