Eingebaute Agenten-Tools

Das sind die servergebundenen Tools, die die eingebaute Agentenlaufzeit direkt registriert — Sprachserver, strukturelle Suche, Debugger, Kernel, Fragen und Worker-Steuerung — im Unterschied zu den MCP-Tools, die sie überbrückt, und den generischen Datei-, Such- und Shell-Tools aus der Laufzeit des Harness. Sie stehen nicht in der MCP-Registrierung: Ein externer MCP-Client sieht sie nicht, weil jedes an eine laufende serverseitige Ressource gebunden ist, die zu einem Lauf gehört — einen Sprachserver-Prozess, einen Debug-Adapter, einen Interpreter.

Jedes Tool hier wird nur registriert, wenn die Ressource dahinter für den Lauf angeschlossen ist — ein Supervisor für Sprachserver oder Debugger, ein tree-sitter-Parser, eine Kernel-Fabrik, ein Frage-Port, ein Vibe-Roster. Ob ein Sprachserver oder Debug-Adapter für diesen Checkout da ist, ist eine eigene, spätere Prüfung (status / adapters): Diese Tools bleiben an der Oberfläche, damit der Agent fragen kann, warum nichts brauchbar ist, statt zu raten.

Freigabestufen

Jedes Tool deklariert eine Stufe, und die Stufe entscheidet, welche Oberflächen es sehen — nicht bloß, ob es eine Freigabe verlangt. Planmodus und schreibgeschützte Subagenten sind auf read begrenzt, deshalb fehlt ein Tool der Stufe write oder exec in ihrem Schema vollständig.

Stufe	Bedeutung	Tools hier
read	Keine Seiteneffekte	lsp, ast_grep, ask_user, die fünf vibe_*
write	Ändert Dateien	lsp_rename, ast_edit, resolve
exec	Startet oder steuert einen Prozess	debug, eval

---

lsp — Sprachserver-Abfragen

Registriert, wenn der Lauf einen Sprachserver-Supervisor und ein Arbeitsverzeichnis hat. Ob ein Server wirklich antworten kann, wird beim Aufruf erkannt, als Schnittmenge: Ein Wurzelmarker muss existieren, und die Binärdatei des Servers muss sich auflösen lassen. Liegt nur eines von beiden vor, startet kein Server — status sagt das — statt einer stillen Vermutung.

Positionen werden über line plus eine Teilzeichenkette symbol adressiert, nie über die Spalte. Fragt man ein Modell nach einer Spalte, rät es, und ein falscher Tipp trifft ein anderes Symbol in derselben Zeile — eine Antwort, die richtig aussieht und von etwas anderem handelt. symbol bei einer Navigationsaktion wegzulassen ist ein Fehler, keine Vermutung auf die erste Spalte.

Aktion	Argumente	Liefert
diagnostics	file (oder "*")	Fehler und Warnungen; "*" führt stattdessen die Projektprüfung aus
definition	file, line, symbol	Wo das Symbol deklariert ist
type_definition	file, line, symbol	Wo sein Typ deklariert ist
implementation	file, line, symbol	Konkrete Implementierungen
references	file, line, symbol	Jede Verwendung, höchstens 50
hover	file, line, symbol	Signatur und Doc-Kommentar
symbols	query oder file	Suche im Arbeitsbereich mit query (höchstens 100); Dokumentsymbole mit file (höchstens 200)
code_actions	file, line, symbol	Schnellkorrekturen, die der Server anbietet
status	—	Welche Server laufen, und für welche Wurzeln
reload	—	Startet den Server für diese Wurzel neu

Diagnosen beim Schreiben

Der Gewinn ist nicht das Tool. write, edit und apply_patch sind umhüllt: Nach dem Schreiben wird die Datei über den Sprachserver synchronisiert und gespeichert, und nur neu hinzugekommene Diagnosen fließen ins Tool-Ergebnis ein. Der Agent erfährt in dem Moment, in dem er den Build bricht, dass er ihn gebrochen hat, ohne nachfragen zu müssen.

Schon gemeldete Diagnosen unterdrückt ein Protokoll je Lauf, geschlüsselt nach Schweregrad, Code und Meldung — die Position bleibt absichtlich außen vor, damit eine Diagnose, die bloß vier Zeilen nach unten gerutscht ist, nicht noch einmal als neu gemeldet wird.

lsp_rename — projektweites Umbenennen

Ein eigenes Tool der Stufe write, aus genau einem Grund: Die Stufe entscheidet die Sichtbarkeit. Nähme man das Umbenennen in lsp auf, bekäme ein schreibgeschützter Explorer die Möglichkeit, das Repo umzuschreiben, oder jedes hover stünde hinter einer Freigabeaufforderung.

Argument	Bedeutung
file	Wo das Symbol steht
line	1-indizierte Zeile
symbol	Teilzeichenkette, die es in dieser Zeile kennzeichnet
new_name	Wie es heißen soll

---

ast_grep — strukturelle Suche

Findet Code nach der Form statt nach dem Text. $NAME trifft jeden Knoten, $$$NAME eine Folge von Geschwistern, und $_ ist ein Platzhalter, der nichts bindet.

Die Eigenschaft, die daraus einen Matcher macht und nicht einen Regex mit Extra-Schritten: Eine Metavariable, die in einem Muster wiederholt wird, muss denselben Text erfassen.

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

trifft eine Absicherung, die dispose auf genau dem aufruft, was sie geprüft hat, und nicht eine, die dispose auf etwas anderem aufruft.

Argument	Bedeutung
pattern	Ein Codefragment mit Metavariablen
path	Datei oder Verzeichnis für die Suche; Standard ist der ganze Arbeitsbereich
language	Eine mitgelieferte Grammatik-Id (dart, python, rust, c, …). Wird erschlossen, wenn path eine Datei nennt
max_results	Standard 50

Das Muster wird mit derselben Grammatik geparst wie die Datei

Deshalb trifft dispose(x) den Aufruf, egal wie er gesetzt, umbrochen oder kommentiert ist — und dieselben Zeichen nie in einem Zeichenkettenliteral oder einem Kommentar.

Ein Fragment wird in einem Gerüst geparst, nicht nackt

dispose(x) auf Darts oberster Ebene geparst ist eine gültige Funktionssignatur. Der Muster-Compiler probiert eine Leiter von Kontexten (Anweisung, Ausdruck, Klassenmember, Deklaration) und nimmt den ersten, der das Fragment annimmt. Ein Muster, das kein Kontext annimmt, wird als nicht parsebar gemeldet, statt gesucht und stillschweigend nicht gefunden zu werden.

ast_edit — strukturelle Umschreibung, im Staging

Dieselbe Suche, plus eine rewrite-Vorlage, in die die Metavariablen wieder eingesetzt werden. Es wird nichts geschrieben. Die Änderung geht ins Staging, und das Ergebnis nennt eine 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	Bedeutung
pattern	Was getroffen werden soll
rewrite	Was dort stehen soll, mit eingesetztem $NAME
path	Umfang; Standard ist der ganze Arbeitsbereich
language	Sprach-Id

resolve — eine Änderung im Staging übernehmen oder verwerfen

Argument	Bedeutung
edit_id	Aus dem Ergebnis (proposed)
action	accept oder discard

Jede Datei wird mit dem Inhalt verglichen, der beim Staging festgehalten wurde, und jede Abweichung lehnt die ganze Änderung ab. Eine nur teilweise angewendete strukturelle Umschreibung hinterlässt einen Baum, der weder unter der alten noch unter der neuen Form kompiliert.

---

debug — einen Debugger steuern

Registriert, wenn der Lauf einen Supervisor für die Debug-Sitzung, ein Arbeitsverzeichnis und eine Unterhaltungs-Id hat. Ob ein Adapter wirklich starten kann, wird beim Aufruf erkannt, nach derselben Schnittmengenregel wie beim Sprachserver (Wurzelmarker und Binärdatei). Stufe exec; nicht parallel-sicher (eine Sitzung ist Zustand über die Aufrufe hinweg, deshalb läse ein continue, das stack überholt, einen Frame, der sich schon bewegt hat).

Eine Sitzung pro Unterhaltung, mit einer harten TTL (30 Minuten). Ein zweites launch wird abgelehnt, statt das erste stillschweigend zu ersetzen.

Operation	Argumente	Hinweise
adapters	—	Welche Adapter hier brauchbar sind, und warum nicht
status	—	Ob eine Sitzung läuft, und wo sie angehalten hat
breakpoints	file, lines[]	Leeres lines leert die Datei. Darf vor dem Start gesetzt werden
launch	program, args[]	Startet das Programm, angehalten an deinen Haltepunkten
attach	port	Verbindet sich mit einem schon laufenden Debuggee
continue	thread_id?	Läuft bis zum nächsten Halt
pause	thread_id?	Hält es an, wo es gerade steht
step_over / step_in / step_out	thread_id?	Geht einen Schritt
threads	—	Thread-Ids und Namen
stack	thread_id?	Frames, höchstens 30
scopes	frame_id	Scopes eines Frames, jeder mit einer reference
variables	reference	Kinder, höchstens 50, Werte höchstens 400 Zeichen
evaluate	expression, frame_id?	Ausgewertet im eigenen Scope des Frames
output	—	stdout/stderr des Debuggee, begrenzt
terminate	—	Beendet die Sitzung und killt den Adapter

Adapter

Id	Befehl	Wurzelmarker
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 bevorzugt ein projektlokales .venv/bin oder venv/bin gegenüber $PATH: Ein Python aus $PATH ist eine andere Umgebung, und ein Attach aus der falschen scheitert so, dass es wie kaputter Code wirkt.

---

eval — persistente Interpreter

Eine Python- oder JavaScript-Zelle, deren Variablen, Importe und geladene Daten zwischen den Aufrufen erhalten bleiben. Stufe exec; nicht parallel-sicher.

Argument	Bedeutung
code	Die Zelle
description	Pflicht. 5–10 Wörter für die Beschriftung im Transkript
language	python (Standard) oder javascript
reset	Verwirft den Interpreter und startet zuerst sauber

• Der letzte Ausdruck wird wie in einem Notebook zurückgegeben.
• display() funktioniert, ein pandas-Frame wird als Tabelle dargestellt, und eine matplotlib-Figure kommt als Bild zurück, das das Transkript anzeigt.
• Die IPython-Idiome, die du reflexartig tippst — %pip, %cd, !cmd, %%bash, %%timeit — werden in gewöhnlichen Code umgeschrieben. %pip leert außerdem sys.modules, damit der nächste import sieht, was gerade installiert wurde.

Eigene Tools aus einer Zelle heraus aufrufen

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

Die Brücke steigt wieder in die Tool-Registrierung des Harness ein, deshalb gelten Schutzregeln, Freigabe und jeder Wrapper genau wie bei einem vom Modell ausgelösten Aufruf. Sie läuft über die eigene Pipe des Kernels statt über einen Loopback-Socket: kein Port, kein Geheimnis, keine Ausgangsregel.

Das Timeout der Zelle ist ein Budget für Untätigkeit (Standard 5 Minuten), und es wird ausgesetzt, solange ein überbrückter Aufruf aussteht, damit eine Zelle, die sich auf Subagenten auffächert, nicht mitten in der Auffächerung abgebrochen wird.

Wo der Kernel läuft

In der Kapsel der Unterhaltung, wenn sie eine hat, sonst auf dem Host. Er bootet dafür keine Kapsel — dieselbe Regel, die einen Rig-Tab am automatischen Start hindert.

---

ask_user — dem Menschen eine Frage stellen

Stufe read. Der einzige Weg, auf dem ein Lauf den Betreiber etwas fragt. Es zeichnet eine nummerierte Karte in die Unterhaltung und blockiert, bis jemand antwortet, überspringt oder die Frage ins Timeout läuft. Schreib die Frage nie als Chat-Nachricht — das beendet den Zug.

Argument	Bedeutung
question	Was gefragt werden soll
context	Optional: warum du fragst und was an der Antwort hängt
options[]	Auswahlmöglichkeiten, jede {label, description?}
allow_free_text	Ob eine getippte Antwort angenommen wird
multi_select	Ob mehrere Optionen gewählt werden dürfen

Ein Überspringen ist Erfolg: Mach auf einer genannten Annahme weiter und frag nicht noch einmal. Ein Timeout ist ein Fehler mit derselben Anweisung. Freigabeaufforderungen („darf ich das tun?“) sind ein eigenes Tor und erscheinen als dieselbe Karte in der Unterhaltung.

Registriert nur, wenn ein Frage-Port und ein Zielbereich beide da sind. Ohne angeschlossenen Menschen schlägt der Aufruf fehl, statt für immer zu blockieren — dieselbe fail-closed-Haltung, die ein Schutzregel-prompt ohne verbundene zuständige Person einnimmt.

---

vibe_* — Hintergrund-Worker steuern

Registriert nur, solange der Vibe-Modus an ist. Alle fünf liegen auf der Stufe read: Das Tor gehört auf die Tools des Workers, dort, wo die Bearbeitung wirklich geschieht.

Tool	Argumente	Hinweise
vibe_spawn	brief, label, tier?	Kehrt sofort zurück; der Worker läuft weiter
vibe_send	worker_id, message	Hängt an das Briefing an und startet erneut
vibe_wait	worker_id, timeout_seconds?	Blockiert, bis er zur Ruhe kommt
vibe_kill	worker_id	Stoppt ihn
vibe_list	—	Stufe, Status, verstrichene Zeit und letztes Ergebnis

tier ist fast (mechanische Arbeit mit klarer Vorgabe) oder good (Entwurf, Einschätzung oder die Prüfung dessen, was ein fast-Worker erzeugt hat).