Herramientas de agente integradas

Estas son las herramientas vinculadas al servidor que el tiempo de ejecución del agente integrado registra directamente —servidor de lenguaje, búsqueda estructural, depurador, kernels, preguntas y control de workers—, a diferencia de las herramientas MCP que puentea y de las herramientas genéricas de archivo, búsqueda y shell del tiempo de ejecución del arnés. No están en el registro MCP: un cliente MCP externo no las verá, porque cada una está vinculada a un recurso vivo del lado del servidor —un proceso de servidor de lenguaje, un adaptador de depuración, un intérprete— que pertenece a una sola ejecución.

Todas las herramientas de esta página se registran solo cuando su recurso de respaldo está conectado para la ejecución —un supervisor de servidor de lenguaje o de depuración, un analizador de tree-sitter, una fábrica de kernels, un puerto de preguntas, un listado de workers de vibe. La detección de un servidor de lenguaje o de un adaptador de depuración para este checkout es una comprobación aparte y posterior (status / adapters): esas herramientas siguen en la superficie para que el agente pueda preguntar por qué no hay nada utilizable, en lugar de adivinar.

Niveles de aprobación

Cada herramienta declara un nivel, y el nivel decide qué superficies la ven, y no solo si pide aprobación. El modo plan y los subagentes de solo lectura están limitados a read, así que una herramienta de nivel write o exec está ausente por completo de su esquema.

Nivel	Significado	Herramientas aquí
read	Sin efectos secundarios	lsp, ast_grep, ask_user, las cinco vibe_*
write	Modifica archivos	lsp_rename, ast_edit, resolve
exec	Inicia o controla un proceso	debug, eval

---

lsp — consultas al servidor de lenguaje

Se registra cuando la ejecución tiene un supervisor de servidor de lenguaje y un directorio de trabajo. Que un servidor pueda responder de verdad se detecta en el momento de la llamada, como una intersección: debe existir un marcador de raíz y el binario del servidor debe poder resolverse. Cualquiera de los dos por sí solo significa que no arranca ningún servidor —status lo dice—, en lugar de una suposición silenciosa.

Las posiciones se direccionan con line más una subcadena symbol, nunca por columna. Un modelo al que se le pide una columna adivina, y una suposición equivocada se resuelve en otro símbolo de la misma línea: una respuesta que parece correcta y que trata de otra cosa. Omitir symbol en una acción de navegación es un error, no una suposición de primera columna.

Acción	Argumentos	Devuelve
diagnostics	file (o "*")	Errores y advertencias; "*" ejecuta en su lugar el comprobador del proyecto
definition	file, line, symbol	Dónde se declara el símbolo
type_definition	file, line, symbol	Dónde se declara su tipo
implementation	file, line, symbol	Implementaciones concretas
references	file, line, symbol	Todos los usos, limitados a 50
hover	file, line, symbol	Firma y comentario de documentación
symbols	query o file	Búsqueda en el espacio de trabajo con query (limitada a 100); símbolos del documento con file (limitados a 200)
code_actions	file, line, symbol	Correcciones rápidas que ofrece el servidor
status	—	Qué servidores están en ejecución y para qué raíces
reload	—	Reinicia el servidor de esta raíz

Diagnósticos al escribir

El beneficio no es la herramienta. write, edit y apply_patch están envueltas: tras la escritura, el archivo se sincroniza y se guarda a través del servidor de lenguaje, y solo los diagnósticos recién introducidos se incorporan al resultado de la herramienta. Un agente se entera de que ha roto la compilación en el mismo momento en que la rompe, sin tener que acordarse de preguntar.

Los diagnósticos ya notificados se suprimen mediante un registro por ejecución con la clave puesta en la severidad, el código y el mensaje —la posición se excluye a propósito—, de modo que un diagnóstico que solo ha bajado cuatro líneas no se vuelve a notificar como nuevo.

lsp_rename — renombrado en todo el proyecto

Una herramienta aparte, de nivel write, por una única razón: el nivel decide la visibilidad. Integrar el renombrado en lsp o bien daría a un explorador de solo lectura la capacidad de reescribir el repositorio, o bien pondría cada hover detrás de una solicitud de aprobación.

Argumento	Significado
file	Dónde está el símbolo
line	Línea indexada desde 1
symbol	Subcadena que lo identifica en esa línea
new_name	Cómo llamarlo

---

ast_grep — búsqueda estructural

Encuentra código por su forma en lugar de por su texto. $NAME coincide con cualquier nodo, $$$NAME coincide con una serie de hermanos y $_ es un comodín que no captura nada.

La propiedad que lo convierte en un buscador y no en una regex con pasos extra: una metavariable repetida en un patrón debe capturar el mismo texto.

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

coincide con una guarda que libera lo que comprobó y no coincide con una que libera otra cosa.

Argumento	Significado
pattern	Un fragmento de código con metavariables
path	Archivo o directorio donde buscar; de forma predeterminada, todo el espacio de trabajo
language	Un id de gramática incluida (dart, python, rust, c, …). Se infiere cuando path nombra un archivo
max_results	50 de forma predeterminada

El patrón se analiza con la misma gramática que el archivo

Así que dispose(x) coincide con la llamada sin importar cómo esté espaciada, envuelta o comentada, y nunca coincide con los mismos caracteres dentro de un literal de cadena o un comentario.

Un fragmento se analiza dentro de un andamiaje, no en crudo

dispose(x) analizado en el nivel superior de Dart es una firma de función válida. El compilador de patrones prueba una escalera de contextos (sentencia, expresión, miembro de clase, declaración) y usa el primero que acepta el fragmento. Un patrón que ningún contexto acepta se notifica como no analizable en lugar de buscarse y no encontrarse en silencio.

ast_edit — reescritura estructural, preparada

El mismo emparejamiento, más una plantilla rewrite con las metavariables sustituidas de vuelta. No se escribe nada. El cambio se prepara y el resultado nombra un 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	Qué buscar
rewrite	Qué poner en su lugar, con $NAME sustituido
path	Alcance; de forma predeterminada, todo el espacio de trabajo
language	Id del lenguaje

resolve — confirmar o descartar un cambio preparado

Argumento	Significado
edit_id	Del resultado (proposed)
action	accept o discard

Cada archivo se compara con el contenido capturado en el momento de la preparación, y cualquier discrepancia rechaza todo el cambio. Una reescritura estructural aplicada a medias deja un árbol que no compila con la forma antigua ni con la nueva.

---

debug — controlar un depurador

Se registra cuando la ejecución tiene un supervisor de sesión de depuración, un directorio de trabajo y un id de conversación. Que un adaptador pueda arrancar de verdad se detecta en el momento de la llamada, con la misma regla de intersección que el servidor de lenguaje (marcador de raíz y binario). Nivel exec; no es seguro en paralelo (una sesión es estado entre llamadas, así que un continue que adelantara a stack leería un frame que ya se ha movido).

Una sesión por conversación, con un TTL estricto (30 minutos). Un segundo launch se rechaza en lugar de reemplazar silenciosamente al primero.

Op	Argumentos	Notas
adapters	—	Qué adaptadores se pueden usar aquí y por qué no
status	—	Si hay una sesión en ejecución y dónde se detuvo
breakpoints	file, lines[]	Un lines vacío limpia el archivo. Se pueden establecer antes de lanzar
launch	program, args[]	Inicia el programa detenido en tus puntos de interrupción
attach	port	Se conecta a un proceso ya en ejecución bajo depuración
continue	thread_id?	Se ejecuta hasta la siguiente parada
pause	thread_id?	Lo detiene donde está
step_over / step_in / step_out	thread_id?	Avanza un paso
threads	—	Ids y nombres de los hilos
stack	thread_id?	Frames, limitados a 30
scopes	frame_id	Ámbitos de un frame, cada uno con una reference
variables	reference	Hijos, limitados a 50, valores limitados a 400 caracteres
evaluate	expression, frame_id?	Se evalúa en el propio ámbito del frame
output	—	La stdout/stderr del proceso depurado, acotada
terminate	—	Termina la sesión y mata al adaptador

Adaptadores

Id	Comando	Marcadores de raíz
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

debugpy prefiere un .venv/bin o un venv/bin locales del proyecto antes que $PATH: un python de $PATH es un entorno distinto, y conectarse desde el equivocado falla de una forma que parece código roto.

---

eval — intérpretes persistentes

Una celda de Python o JavaScript cuyas variables, importaciones y datos cargados sobreviven entre llamadas. Nivel exec; no es seguro en paralelo.

Argumento	Significado
code	La celda
description	Obligatorio. De 5 a 10 palabras para la etiqueta de la transcripción
language	python (predeterminado) o javascript
reset	Descarta el intérprete y empieza limpio primero

• La última expresión se devuelve igual que en un notebook.
• display() funciona, un frame de pandas se representa como una tabla y una figura de matplotlib vuelve como una imagen que la transcripción muestra.
• Los modismos de IPython que la gente escribe por reflejo —%pip, %cd, !cmd, %%bash, %%timeit— se reescriben a código normal. %pip además vacía sys.modules, así que la siguiente import ve lo que se acaba de instalar.

Llamar a tus propias herramientas desde dentro de una celda

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

El puente vuelve a entrar en el registro de herramientas del arnés, así que las barandillas, la aprobación y todos los envoltorios se aplican exactamente igual que a una llamada emitida por el modelo. Viaja por la propia tubería del kernel en lugar de por un socket de bucle local: sin puerto, sin secreto, sin regla de salida.

El tiempo de espera de la celda es un presupuesto de inactividad (5 minutos de forma predeterminada) y se suspende mientras hay una llamada puenteada pendiente, así que una celda que se reparte entre subagentes no se mata a mitad del reparto.

Dónde se ejecuta el kernel

En el recinto de la conversación cuando lo tiene, y en el host en caso contrario. No arranca un recinto para conseguirlo —la misma regla que impide que una pestaña de rig se arranque sola.

---

ask_user — preguntar algo a la persona

De nivel read. La única forma en que una ejecución pregunta algo al operador. Representa una tarjeta numerada en la conversación y se bloquea hasta que alguien responde, la omite o la pregunta agota su tiempo de espera. Nunca escribas la pregunta como un mensaje de chat: eso termina el turno.

Argumento	Significado
question	Qué preguntar
context	Opcional: por qué preguntas y de qué depende la respuesta
options[]	Opciones, cada una {label, description?}
allow_free_text	Si se acepta una respuesta escrita
multi_select	Si se pueden elegir varias opciones

Omitirla es un éxito: continúa sobre una suposición declarada y no vuelvas a preguntar. Un tiempo de espera agotado es un error con la misma instrucción. Las solicitudes de permiso («¿puedo hacer esto?») son una puerta aparte y se representan como la misma tarjeta en la conversación.

Se registra solo cuando existen tanto un puerto de preguntas como un espacio de destino. Sin una persona conectada, la llamada falla en lugar de bloquearse para siempre: la misma postura de cierre de seguridad que adopta un prompt de barandilla cuando no hay ningún aprobador conectado.

---

vibe_* — dirigir workers en segundo plano

Se registran solo mientras el modo vibe está activado. Las cinco son de nivel read: la puerta corresponde a las herramientas del worker, que es donde ocurre de verdad la edición.

Herramienta	Argumentos	Notas
vibe_spawn	brief, label, tier?	Devuelve el control de inmediato; el worker sigue ejecutándose
vibe_send	worker_id, message	Añade al encargo y vuelve a ejecutar
vibe_wait	worker_id, timeout_seconds?	Se bloquea hasta que finaliza
vibe_kill	worker_id	Lo detiene
vibe_list	—	Nivel, estado, tiempo transcurrido y último resultado

tier es fast (trabajo mecánico con una especificación clara) o good (diseño, criterio o revisión de lo que ha producido un worker fast).