Outils d’agent intégrés

Voici les outils liés au serveur que le harnais intégré enregistre directement — serveur de langage, recherche structurelle, débogueur, noyaux, questions et pilotage des workers — par opposition aux outils MCP qu’il relie et aux outils génériques de fichiers, de recherche et de shell du harnais. Ils ne figurent pas au registre MCP : un client MCP externe ne les verra pas, parce que chacun est lié à une ressource vive côté serveur — un processus de serveur de langage, un adaptateur de débogage, un interpréteur — qui appartient à une seule exécution.

Chaque outil ici n’est enregistré que lorsque la ressource qui le soutient est raccordée pour l’exécution — un superviseur de serveur de langage ou de débogage, un analyseur tree-sitter, une fabrique de noyaux, un port de question, une liste de workers vibe. La détection d’un serveur de langage ou d’un adaptateur de débogage pour ce checkout est une vérification distincte et ultérieure (status / adapters) : ces outils restent dans la surface afin que l’agent puisse demander pourquoi rien n’est utilisable, plutôt que de deviner.

Niveaux d’approbation

Chaque outil déclare un niveau, et le niveau détermine quelles surfaces le voient — pas seulement s’il demande une approbation. Le mode plan et les sous-agents en lecture seule sont plafonnés à read, de sorte qu’un outil de niveau write ou exec est entièrement absent de leur schéma.

Niveau	Signification	Outils ici
read	Aucun effet de bord	lsp, ast_grep, ask_user, les cinq vibe_*
write	Modifie des fichiers	lsp_rename, ast_edit, resolve
exec	Démarre ou pilote un processus	debug, eval

---

lsp — requêtes au serveur de langage

Enregistré lorsque l’exécution dispose d’un superviseur de serveur de langage et d’un répertoire de travail. La capacité réelle d’un serveur à répondre est détectée au moment de l’appel, comme une intersection : un marqueur racine doit exister et le binaire du serveur doit se résoudre. L’un sans l’autre signifie qu’aucun serveur ne démarre — status le dit — plutôt qu’une supposition silencieuse.

Les positions sont désignées par line et une sous-chaîne symbol, jamais par colonne. Un modèle à qui l’on demande une colonne devine, et une mauvaise supposition se résout en un autre symbole de la même ligne — une réponse qui a l’air juste et qui parle d’autre chose. Omettre symbol dans une action de navigation est une erreur, et non une supposition de première colonne.

Action	Arguments	Retourne
diagnostics	file (ou "*")	Erreurs et avertissements ; "*" lance plutôt le vérificateur du projet
definition	file, line, symbol	Où le symbole est déclaré
type_definition	file, line, symbol	Où son type est déclaré
implementation	file, line, symbol	Les implémentations concrètes
references	file, line, symbol	Chaque utilisation, plafonnée à 50
hover	file, line, symbol	Signature et commentaire de documentation
symbols	query ou file	Recherche dans l’espace de travail avec query (plafonnée à 100) ; symboles du document avec file (plafonnés à 200)
code_actions	file, line, symbol	Corrections rapides offertes par le serveur
status	—	Quels serveurs sont en cours d’exécution, et pour quelles racines
reload	—	Redémarre le serveur pour cette racine

Diagnostics à l’écriture

Le gain n’est pas l’outil. write, edit et apply_patch sont enveloppés : après l’écriture, le fichier est synchronisé et enregistré par le serveur de langage, et seuls les diagnostics nouvellement introduits sont intégrés au résultat de l’outil. Un agent apprend qu’il a cassé la compilation au moment même où il l’a cassée, sans avoir à penser à le demander.

Les diagnostics déjà signalés sont supprimés par un registre par exécution indexé sur la gravité, le code et le message — la position étant délibérément exclue, de sorte qu’un diagnostic simplement descendu de quatre lignes n’est pas signalé de nouveau.

lsp_rename — renommage à l’échelle du projet

Un outil distinct, de niveau write, pour une seule raison : le niveau décide de la visibilité. Fusionner le renommage dans lsp donnerait soit à un explorateur en lecture seule la capacité de réécrire le dépôt, soit placerait chaque hover derrière une demande d’approbation.

Argument	Signification
file	Où se trouve le symbole
line	Ligne indexée à 1
symbol	Sous-chaîne qui l’identifie sur cette ligne
new_name	Le nouveau nom à lui donner

---

ast_grep — recherche structurelle

Trouve du code par sa forme plutôt que par son texte. $NAME correspond à n’importe quel nœud, $$$NAME correspond à une suite d’éléments frères, et $_ est un joker qui ne lie rien.

La propriété qui en fait un moteur de correspondance plutôt qu’une expression régulière avec des étapes en plus : une métavariable répétée dans un même motif doit capturer le même texte.

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

correspond à une garde qui dispose ce qu’elle a testé, et ne correspond pas à une garde qui dispose autre chose.

Argument	Signification
pattern	Un fragment de code avec des métavariables
path	Fichier ou répertoire à explorer ; par défaut, tout l’espace de travail
language	Un identifiant de grammaire livrée (dart, python, rust, c, …). Déduit lorsque path désigne un fichier
max_results	50 par défaut

Le motif est analysé par la même grammaire que le fichier

Ainsi, dispose(x) correspond à l’appel quelle que soit sa disposition, son découpage ou ses commentaires — et ne correspond jamais aux mêmes caractères à l’intérieur d’un littéral de chaîne ou d’un commentaire.

Un fragment est analysé dans un échafaudage, jamais à nu

Analysé tel quel au niveau supérieur de Dart, dispose(x) est une signature de fonction parfaitement valide. Le compilateur de motifs essaie une échelle de contextes (instruction, expression, membre de classe, déclaration) et utilise le premier qui accepte le fragment. Un motif qu’aucun contexte n’accepte est signalé comme non analysable plutôt que recherché puis discrètement introuvable.

ast_edit — réécriture structurelle, préparée

La même correspondance, plus un gabarit rewrite où les métavariables sont substituées de nouveau. Rien n’est écrit. Le changement est préparé et le résultat nomme 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"

Argument	Signification
pattern	Ce qu’il faut mettre en correspondance
rewrite	Ce qu’il faut mettre à la place, avec $NAME substitué
path	Portée ; par défaut, tout l’espace de travail
language	Identifiant de langage

resolve — valider ou écarter un changement préparé

Argument	Signification
edit_id	Provenant du résultat (proposed)
action	accept ou discard

Chaque fichier est comparé au contenu capturé au moment de la préparation, et tout écart fait refuser l’ensemble du changement. Une réécriture structurelle partiellement appliquée laisse un arbre qui ne compile ni sous l’ancienne forme ni sous la nouvelle.

---

debug — piloter un débogueur

Enregistré lorsque l’exécution dispose d’un superviseur de session de débogage, d’un répertoire de travail et d’un identifiant de conversation. La capacité réelle d’un adaptateur à démarrer est détectée au moment de l’appel, par la même règle d’intersection que le serveur de langage (marqueur racine et binaire). Niveau exec ; ne supporte pas le parallélisme (une session est un état qui persiste entre les appels, de sorte qu’un continue qui dépasse stack lirait une trame déjà déplacée).

Une session par conversation, avec un TTL strict (30 minutes). Un second launch est refusé plutôt que de remplacer silencieusement le premier.

Opération	Arguments	Notes
adapters	—	Quels adaptateurs sont utilisables ici, et pourquoi pas
status	—	Si une session est en cours d’exécution, et où elle s’est arrêtée
breakpoints	file, lines[]	Un lines vide efface le fichier. Peut être posé avant le lancement
launch	program, args[]	Démarre le programme arrêté à vos points d’arrêt
attach	port	Se connecte à un programme débogué déjà en cours d’exécution
continue	thread_id?	S’exécute jusqu’au prochain arrêt
pause	thread_id?	L’arrête là où il se trouve
step_over / step_in / step_out	thread_id?	Avance d’un pas
threads	—	Identifiants et noms des fils
stack	thread_id?	Trames, plafonnées à 30
scopes	frame_id	Portées sur une trame, chacune avec une reference
variables	reference	Enfants, plafonnés à 50, valeurs plafonnées à 400 caractères
evaluate	expression, frame_id?	Évaluée dans la portée propre à la trame
output	—	La sortie standard/erreur du programme débogué, délimitée
terminate	—	Met fin à la session et tue l’adaptateur

Adaptateurs

Id	Commande	Marqueurs racines
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 préfère un .venv/bin ou un venv/bin propre au projet plutôt que $PATH : un python trouvé dans le $PATH appartient à un autre environnement, et s’attacher depuis le mauvais échoue d’une manière qui se lit comme du code défectueux.

---

eval — interpréteurs persistants

Une cellule Python ou JavaScript dont les variables, les imports et les données chargées survivent entre les appels. Niveau exec ; ne supporte pas le parallélisme.

Argument	Signification
code	La cellule
description	Obligatoire. 5 à 10 mots pour l’étiquette de la transcription
language	python (par défaut) ou javascript
reset	Abandonne l’interpréteur et repart proprement d’abord

• La dernière expression est renvoyée comme le ferait un carnet de notes.
• display() fonctionne, un cadre de données pandas s’affiche sous forme de tableau, et une figure matplotlib revient sous forme d’image que la transcription affiche.
• Les idiomes IPython que les gens tapent par réflexe — %pip, %cd, !cmd, %%bash, %%timeit — sont réécrits en code ordinaire. %pip vide aussi sys.modules, de sorte que le prochain import voit ce qui vient d’être installé.

Appeler vos propres outils depuis l’intérieur d’une cellule

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

Le pont revient dans le registre d’outils du harnais, de sorte que les garde-fous, l’approbation et chaque enveloppe s’appliquent exactement comme pour un appel émis par le modèle. Il passe par le propre tuyau du noyau plutôt que par une socket de bouclage : aucun port, aucun secret, aucune règle de sortie réseau.

Le délai d’expiration de la cellule est un budget d’inactivité (5 minutes par défaut) et il est suspendu tant qu’un appel relayé est en cours, de sorte qu’une cellule qui se ramifie vers des sous-agents n’est pas tuée en pleine ramification.

Où s’exécute le noyau

Dans l’enceinte de la conversation lorsqu’elle en a une, sur l’hôte autrement. Il ne démarre pas d’enceinte pour y arriver — la même règle qui empêche l’onglet d’un rig de démarrer automatiquement.

---

ask_user — poser une question à un humain

Niveau read. La seule façon pour une exécution de demander quoi que ce soit à l’exploitant. Il affiche une carte numérotée dans la conversation et bloque jusqu’à ce que quelqu’un réponde, passe ou que la question expire. N’écrivez jamais la question comme un message de clavardage — cela met fin au tour.

Argument	Signification
question	Ce qu’il faut demander
context	Facultatif : pourquoi vous posez la question et ce qui dépend de la réponse
options[]	Choix, chacun {label, description?}
allow_free_text	Indique si une réponse tapée est acceptée
multi_select	Indique si plusieurs options peuvent être choisies

Un passage est un succès : poursuivez sur une hypothèse énoncée et ne demandez pas de nouveau. Une expiration est une erreur avec la même consigne. Les invites de permission (« puis-je faire ceci ? ») forment une barrière distincte et s’affichent comme la même carte dans la conversation.

Enregistré seulement lorsqu’un port de question et un espace cible existent tous les deux. Sans humain rattaché, l’appel échoue plutôt que de bloquer indéfiniment — la même posture à refus par défaut qu’adopte un prompt de garde-fou sans approbateur connecté.

---

vibe_* — diriger des workers en arrière-plan

Enregistrés seulement pendant que le mode vibe est activé. Les cinq sont de niveau read : la barrière appartient aux outils du worker, là où la modification se produit réellement.

Outil	Arguments	Notes
vibe_spawn	brief, label, tier?	Renvoie immédiatement ; le worker continue de s’exécuter
vibe_send	worker_id, message	Ajoute à la consigne et relance
vibe_wait	worker_id, timeout_seconds?	Bloque jusqu’à ce qu’il se termine
vibe_kill	worker_id	L’arrête
vibe_list	—	Niveau, statut, temps écoulé et dernier résultat

tier vaut fast (travail mécanique avec une spécification claire) ou good (conception, jugement ou révision de la sortie d’un worker fast).