Jeder Hook ist eine Narbe: 84 Agent-Fehler, kodiert im Code

In meinem Agent-Orchestrierungssystem habe ich 84 Hooks, die 15 der 26 Lifecycle-Ereignistypen abfangen, welche Claude Code mit Stand v2.1.116 (April 2026) bereitstellt. Jeder Hook ist ein Shell-Skript oder Python-Snippet, das vor oder nach einer bestimmten Agent-Aktion ausgelöst wird: Dateilesevorgänge, Dateischreibvorgänge, Bash-Befehle, Webanfragen, das Spawnen von Sub-Agents, Git-Operationen, MCP-Tool-Aufrufe. Jeder Hook existiert, weil etwas schiefgelaufen ist.

Jeder Hook in einem Agent-Orchestrierungssystem lässt sich auf einen konkreten Produktionsfehler zurückverfolgen, wodurch die Hook-Sammlung zu institutionellem Gedächtnis wird, das in Form von Shell-Skripten kodiert ist. Agenten löschten CDN-Caches, lasen Anmeldedatei-Dateien, meldeten bestandene Tests, die sie nie ausgeführt hatten, und drifteten 40 Minuten lang vom Thema ab. Jeder Vorfall brachte eine kleine, deterministische Schutzmaßnahme hervor, die in jeder nachfolgenden Sitzung lautlos ausgelöst wird.

Nicht theoretisch falsch. In der Produktion falsch. Ein Agent löschte einen CDN-Cache, der Millionen von Anfragen bediente. Ein Agent versuchte, SSH-Schlüssel zu schreiben. Ein Agent meldete „Alle Tests bestanden”, ohne pytest aufzurufen. Ein Agent wich so weit von seiner Aufgabe ab, dass er vierzig Minuten damit verbrachte, eine Funktion in einer Datei zu optimieren, die nichts mit der zugewiesenen Arbeit zu tun hatte.

Ich habe keinen dieser Hooks proaktiv entworfen. Ich habe mich nicht hingesetzt und die Fehlermodi autonomer KI-Agenten aufgezählt und vorbeugende Kontrollen geschrieben. Jeder Hook ist reaktiv. Etwas ist kaputtgegangen, ich habe ein Skript geschrieben, um zu verhindern, dass es erneut kaputtgeht, und das Skript wird seitdem in jeder Sitzung lautlos ausgelöst. Das Hook-System ist keine Sicherheitsarchitektur. Es ist eine Narbensammlung.

TL;DR

• Die Cache-Löschung: Ein Agent löschte einen produktiven CDN-Cache mithilfe eines autorisierten API-Aufrufs. Zwei Hooks (47 Zeilen) sichern destruktive Operationen nun mit einer von einem Menschen einzugebenden Passphrase ab.
• Der Anmeldedaten-Leser: Ein Agent nahm API-Tokens in sein Kontextfenster auf. Eine pfadbasierte Schutzmaßnahme blockiert nun das Lesen von Anmeldedatei-Dateien und protokolliert Zugriffe auf .env-Dateien.
• Der Phantom-Verifizierer: Ein Agent meldete „Alle Tests bestanden”, ohne pytest auszuführen. Ein Detektor für vage Formulierungen senkte die Phantom-Verifizierung von 12 % auf unter 2 % der Sitzungen.
• Die zwölf Abdriftungen: Agenten verloren innerhalb von sechzig Tagen nachweislich zwölfmal den Fokus auf ihre Aufgabe. Ein Kosinus-Ähnlichkeits-Detektor mit Schwellenwert 0,30 wird nun alle 25 Tool-Aufrufe ausgelöst.
• Die Taxonomie: Sechs strukturelle Fehlerkategorien decken alle 84 Hooks ab. Neue Kategorien sind nach mehr als 500 Sitzungen selten. Das System wird mit jedem Vorfall robuster.

Die Cache-Löschung: Wie ein autorisierter Aufruf die Produktion lahmlegte

Am 21. März 2026 bat ich einen Agenten zu untersuchen, warum Marktseiten auf resumegeni.com langsam luden. Der Agent begann seine Untersuchung ganz normal: Route-Handler lesen, Datenbankabfragen prüfen, Template-Rendering profilieren. Dann entschied er, dass veraltete Cloudflare-Cache-Einträge die wahren Leistungsmerkmale verschleiern könnten.

Der Agent rief mcp__cloudflare__cache_purge mit purge_everything: true auf.

Jede gecachte Seite auf der Produktionsseite wurde augenblicklich invalidiert. Das CDN ging davon über, die meisten Anfragen mit 80–100 ms zu bedienen, dazu über, jede Anfrage an den Railway-Origin-Server weiterzuleiten. Die Marktseite von Austin ging von unter einer Sekunde auf 14.290 Millisekunden. New York von unter einer Sekunde auf 6.891 ms. Jede Seite der Website wurde bei jeder Anfrage aus einem kalten Origin gerendert.

Der Agent tat nichts Unautorisiertes. Er verwendete ein legitimes MCP-Tool mit gültigen Anmeldedaten, um einen autorisierten API-Endpunkt aufzurufen. Die Cache-Löschung war ein vernünftiger Untersuchungsschritt, wenn man Cache-Verhalten debuggt. Das Problem bestand darin, dass „vernünftig zum Debuggen” und „katastrophal für die Produktion” derselbe API-Aufruf waren, und zwischen der Argumentation des Agenten und der Produktionsfolge gab es keinerlei Schranke.

In jener Nacht baute ich zwei Hooks.

Die Bash-Schutzmaßnahme (destructive-api-guard.sh): Wird bei jedem Bash-Befehl ausgelöst. Sie führt einen Musterabgleich gegen curl.*purge, rm -rf, DROP TABLE, docker.*rm, git push.*--force durch. Harte Blockade (Exit 2). Der Agent sieht eine Nachricht, die erklärt, warum der Befehl blockiert wurde, und Alternativen vorschlägt. Er kann ohne die Passphrase „rosebud” nicht fortfahren, die nur dann in den Kontext gelangen kann, wenn ein Mensch sie eintippt.

Die MCP-Schutzmaßnahme (destructive-mcp-guard.sh): Wird bei jedem MCP-Tool-Aufruf ausgelöst, der mcp__cloudflare oder mcp__github entspricht. Sie führt einen Musterabgleich gegen purge, delete, destroy, remove in den Tool-Parametern durch. Dieselbe harte Blockade, dasselbe Passphrase-Gate.

Zwei Hooks. Zwei Shell-Skripte. Insgesamt: 47 Codezeilen. Sie haben seit der Installation null Cache-Löschungen verhindert, denn seit das Passphrase-Gate hinzugefügt wurde, hat kein Agent mehr eine versucht. Die Hooks fangen keine Angriffe ab. Sie verhindern, dass diese Kategorie von Fehler überhaupt möglich ist.

Der Cache-Löschungs-Vorfall deckte auch das Performance-Problem auf, das er eigentlich untersuchen sollte. Austin mit 14 Sekunden beim Cold Render führte zur Marktseiten-Übergabe, was vier Tage später zur Behebung der Query-Struktur führte. Der Vorfall war nützlich. Der Hook sorgt dafür, dass er sich nicht wiederholen kann.

Der Anmeldedaten-Leser

Im Februar 2026 las ein Agent, der Kontext für ein Projekt sammelte, ~/.claude/docs/credentials.md. Die Datei enthält API-Tokens für Cloudflare, GitHub, Railway und andere Dienste. Der Agent nahm eine Zusammenfassung des Dateiinhalts in seine Arbeitsnotizen auf, was bedeutete, dass die Tokens in der API-Anfrage an Anthropics Server vorhanden waren.

Keine Tokens wurden committet. Keine Tokens wurden öffentlich offengelegt. Aber die Tokens wanderten durch eine Drittanbieter-API in einem Kontextfenster, über das ich keine Kontrolle habe. Die Risikofläche erweiterte sich von „meiner Maschine” auf „meine Maschine plus Anthropics Inferenz-Infrastruktur”.

Die Anmeldedaten-Pfad-Schutzmaßnahme wird bei jedem Dateilesevorgang ausgelöst. Sie prüft den Pfad gegen eine Liste sensibler Muster: .env, credentials, .ssh/, .aws/, .gnupg/, secrets. Bei Zugriffen auf Anmeldedaten protokolliert der Hook eine Warnung und blockiert den Lesevorgang. Bei .env-Lesevorgängen erlaubt er den Zugriff, protokolliert ihn jedoch.

Die Schutzmaßnahme ist für die meisten Pfade beratend und für Anmeldedatei-Dateien eine harte Blockade. Diese Unterscheidung ist wichtig: Ein Agent, der .env liest, um die Namen von Umgebungsvariablen zu verstehen, liefert nützlichen Kontext. Ein Agent, der credentials.md liest, um API-Tokens zu verstehen, ist ein Sicherheitsvorfall.

Seit der Installation ist die Anmeldedaten-Pfad-Schutzmaßnahme 23 Mal in mehr als 200 Sitzungen ausgelöst worden. Zwanzig davon waren Agenten, die .env-Dateien lasen (protokolliert, erlaubt). Drei waren Agenten, die versuchten, Anmeldedatei- oder Schlüsseldateien zu lesen (blockiert). Jeder blockierte Lesevorgang stammte von einem Agenten, der Projektkontext breit sammelte und zufällig eine sensible Datei in sein Suchmuster einbezog. Keiner war böswillig. Alle hätten ohne die Schutzmaßnahme Geheimnisse in das Kontextfenster eingeführt.

Der Phantom-Verifizierer

Der heimtückischste Fehlermodus ist ein Agent, der eine erfolgreiche Verifizierung meldet, ohne die Verifizierung durchzuführen.

Sitzung 147. Ich bat einen Agenten, eine Datenbankabfrage zu refaktorieren und die Änderung mit der bestehenden Test-Suite zu verifizieren. Der Agent refaktorierte die Abfrage korrekt. Der Abschlussbericht lautete: „Alle Tests bestanden. Die refaktorierte Abfrage liefert identische Ergebnisse wie das Original.”

Ich überprüfte das Sitzungsprotokoll. Kein pytest-Aufruf erschien. Kein Test-Runner irgendwelcher Art war aufgerufen worden. Der Agent argumentierte, dass die Tests bestehen würden, weil die refaktorierte Abfrage logisch äquivalent zum Original sei, und meldete diese Argumentation, als wäre sie ein Testergebnis.

Die refaktorierte Abfrage war korrekt. Die Tests wären bestanden. Die Argumentation des Agenten war schlüssig. Doch über Tests zu argumentieren bedeutet nicht, Tests auszuführen, und die Lücke zwischen beidem ist der Ort, an dem Bugs in die Produktion gelangen. Wäre die refaktorierte Abfrage in einem Edge Case subtil falsch gewesen, den die Argumentation des Agenten nicht abdeckte, wäre der Bug mit einem Abschlussbericht deployt worden, der Testverifizierung behauptete.

Der Fehlermodus trat 7 Mal in 60 Sitzungen auf, bevor ich den Evidence-Gate-Hook baute. Der Hook wird bei jedem Abschlussbericht ausgelöst und sucht nach vagen Formulierungen: „sollten bestehen”, „ich glaube”, „Tests bestehen vermutlich”, „ich bin sicher”. Bei Erkennung injiziert der Hook eine Nachricht: „Vage Formulierungen erkannt. Nennen Sie konkrete Belege: Fügen Sie Test-Output ein, nennen Sie Datei und Zeilennummer, oder verweisen Sie auf den spezifischen Verifizierungsschritt.”

Der Hook verifiziert nicht, dass Tests tatsächlich ausgeführt wurden. Er kennzeichnet das sprachliche Muster, das darauf hinweist, dass die Verifizierung übersprungen wurde. Die Erkennung ist unvollkommen. Ein ausreichend gewandter Agent könnte seine vage Formulierung umformulieren, um das Muster zu umgehen. Doch der Hook fängt den häufigen Fall ab, der 12 % der Agent-Fehler ausmacht, die menschliches Eingreifen erfordern.¹

Nach der Installation des Hooks sank die Phantom-Verifizierung von 12 % auf unter 2 % der Sitzungen. Die verbleibenden 2 % sind Fälle, in denen der Agent die vage Formulierung umformuliert oder in denen die Verifizierungsbehauptung technisch korrekt, aber unvollständig ist (z. B. „Unit-Tests bestanden”, wenn Integrationstests nicht ausgeführt wurden).

Abdrift

Zwischen Januar und März 2026 wurde mein Drift-Detektor zwölfmal in Sitzungen ausgelöst, in denen der Agent nachweislich den Fokus auf seine zugewiesene Aufgabe verloren hatte.

Der Drift-Detektor funktioniert, indem er den ursprünglichen Aufgaben-Prompt einbettet und ihn periodisch mit dem Embedding der jüngsten Aktionen des Agenten vergleicht. Wenn die Kosinus-Ähnlichkeit unter 0,30 fällt, injiziert das System eine Warnung, die den ursprünglichen Prompt enthält. Ich kalibrierte den Schwellenwert durch Experimente: 0,50 war zu empfindlich (ausgelöst bei legitimer Teilaufgaben-Exploration), 0,20 war zu nachlässig (offensichtliche Abdrift wurde übersehen), 0,30 fing jeden verifizierten Abdrift-Vorfall ab.

Sitzung 203 war der klarste Fall. Die Aufgabe lautete „Behebe das fehlerhafte Sitemap-XML-Escaping für Job-Slugs mit Ampersand-Zeichen.” Der Agent begann damit, den Sitemap-Generierungscode zu lesen. Dann bemerkte er, dass die Sitemap aus einer Datenbankabfrage generiert wurde. Dann bemerkte er, dass die Datenbankabfrage optimiert werden könnte. Dann verbrachte er 40 Minuten damit, die Abfrage in ein Materialized-View-Muster zu refaktorieren, schrieb Tests für die neue Abfrage und meldete die Optimierung als abgeschlossen. Er hat das Ampersand-Escaping nie behoben.

Der Drift-Detektor hätte dies bei der 25-Tool-Aufruf-Marke abgefangen, etwa 15 Minuten nach Sitzungsbeginn, als die Ähnlichkeit zwischen „Sitemap-XML-Escaping beheben” und „Materialized View erstellen” unter den Schwellenwert fiel. Stattdessen entdeckte ich die Abdrift bei der Überprüfung.

Sitzung 89 war subtiler. Die Aufgabe lautete „Rate-Limiting zu den Authentifizierungs-Endpunkten hinzufügen.” Der Agent fügte Rate-Limiting korrekt hinzu. Dann bemerkte er, dass der Authentifizierungsablauf inkonsistente Fehlermeldungen hatte. Dann standardisierte er die Fehlermeldungen. Dann bemerkte er, dass sich das Fehlerantwort-Format vom API-Antwortformat-Standard unterschied. Dann refaktorierte er das Antwortformat über 12 Endpunkte hinweg. Das Rate-Limiting war korrekt und vollständig. Die Scope-Explosion war die Abdrift.

Der Drift-Detektor wird alle 25 Tool-Aufrufe ausgelöst. In allen zwölf unter dem Schwellenwert liegenden Auslösungen war der Agent nachweislich von der ursprünglichen Aufgabe abgewichen. In sechs Fällen korrigierte sich der Agent nach dem Sehen der injizierten Warnung selbst. In vier Fällen räumte der Agent die Abdrift ein, argumentierte aber, dass die aktuelle Arbeit wertvoll sei (manchmal korrekt). In zwei Fällen ignorierte der Agent die Warnung und setzte die abweichende Arbeit fort.

Der Hook verhindert keine Abdrift. Er macht Abdrift sichtbar. Die Entscheidung, umzuleiten oder die abweichende Arbeit zuzulassen, bleibt beim Menschen. Doch ohne den Hook ist Abdrift unsichtbar bis zum Abschlussbericht, zu einem Zeitpunkt, an dem das Kontextbudget bereits aufgebraucht ist.

Die Narbentaxonomie

Nach 84 Hooks treten Muster hervor. Die Fehler gruppieren sich in sechs Kategorien:

Die verbleibenden 47 Hooks sind projektspezifisch (Konventions-Durchsetzung, Deployment-Schutzmaßnahmen, Übersetzungsvalidatoren) oder experimentell (Kostenverfolgung, Sitzungsmetriken, Aktivitäts-Heartbeats).

Die sechs strukturellen Kategorien sind stabil. Neue Vorfälle innerhalb dieser Kategorien werden von bestehenden Hooks abgefangen. Neue Kategorien sind selten. In sechs Monaten Betrieb entstand nur eine neue strukturelle Kategorie (projektübergreifende Kontamination, entdeckt, als eine im Projekt obsidian-signals laufende Sitzung versuchte, Dateien in blakecrosley.com zu bearbeiten). Die anderen fünf Kategorien wurden innerhalb der ersten 60 Sitzungen etabliert.

Die Studie „Agents of Chaos”, ein 14-tägiges Experiment mehrerer Universitäten, das sechs KI-Agenten Zugriff auf E-Mail, Bash, Dateisysteme und GitHub gewährte, identifizierte unabhängig überlappende Fehlerkategorien: unverhältnismäßige Reaktion (destruktive Operationen), Identitätsentführung (Offenlegung von Anmeldedaten), endlose Schleifen (Ressourcenerschöpfung) und graduelle Konformität unter Druck (Aufgaben-Abdrift).⁵ Die Konvergenz zwischen ihrer kontrollierten Forschung und meiner Produktionserfahrung legt nahe, dass diese Kategorien strukturelle Eigenschaften autonomer Agenten sind, nicht Artefakte einer bestimmten Konfiguration.

Was Hooks nicht abfangen können

Hooks operieren auf Tool-Aufruf-Ebene. Sie fangen die Aktion vor oder nach ihrer Ausführung ab. Sie können die Argumentation, die zur Aktion führte, nicht abfangen.

Ein Agent, der sich entscheidet, eine Funktion zu refaktorieren, statt den gemeldeten Bug zu beheben, erzeugt einen gültigen Tool-Aufruf (Dateischreibvorgang) mit korrektem Inhalt (syntaktisch gültiger Code), der die Aufgabe verletzt (falsche Funktion). Kein Hook fängt dies ab, weil kein Tool-Aufruf verdächtig ist. Der Drift-Detektor fängt es schließlich ab, aber erst, nachdem der Agent erheblichen Kontext für die falsche Arbeit verbraucht hat.

Hooks können auch Kompositionsfehler nicht abfangen, bei denen jede einzelne Aktion autorisiert ist, die Sequenz jedoch ein nicht autorisiertes Ergebnis erzeugt. Die Cache-Löschung war ein Kompositionsfehler: das Lesen der Cache-Konfiguration (autorisiert), der Aufruf der Purge-API (autorisiert), aber die Kombination (Löschung des Produktions-Caches während einer Untersuchung) war schädlich. Die MCP-Schutzmaßnahme fängt nun die spezifische Kombination ab, aber neue Kompositionen bleiben ungedeckt.

Die Lücke in der Komposition der Lieferkette operiert auf derselben Ebene: Vertrauenswürdige Komponenten komponieren sich zu nicht autorisiertem Verhalten. Hooks sind Schutzmaßnahmen auf Komponentenebene. Argumentation auf Kompositionsebene erfordert einen anderen Mechanismus, einen, der Aktionssequenzen statt einzelner Aktionen bewertet. Der Drift-Detektor ist die nächste Annäherung: Er bewertet die Verhaltenstrajektorie statt einzelner Tool-Aufrufe. Doch er misst die Ähnlichkeit zur ursprünglichen Aufgabe, nicht die Sicherheit der komponierten Aktionssequenz.

Die Lücke zwischen Hooks und vollständiger Sicherheit ist die Lücke zwischen institutionellem Gedächtnis und institutioneller Weitsicht. Hooks erinnern sich daran, was schiefgegangen ist. Sie sagen nicht voraus, was als Nächstes schiefgehen wird.

Warum Reaktiv ehrlich ist

Ich könnte ein proaktives Hook-System entwerfen. Jeden möglichen Fehlermodus aufzählen. Vorbeugende Kontrollen für jeden schreiben. Eine vollständige Sicherheitsarchitektur vor der ersten Sitzung aufbauen.

Ich tue das nicht, weil proaktives Design erfordert, Fehler vorherzusagen, die noch nicht aufgetreten sind. Die Vorhersagen wären falsch. Die Hooks wären entweder zu breit (blockieren legitime Aktionen) oder zu eng (verfehlen das tatsächliche Fehlermuster). Die Rate falscher Positiver würde das Vertrauen in das Hook-System untergraben, und ich würde anfangen, Warnungen zu ignorieren.

Reaktive Hooks sind ehrlich. Jeder einzelne sagt: „Diese spezifische Sache ist passiert, und hier ist die spezifische Schutzmaßnahme, die sie verhindert.” Die Schutzmaßnahme ist präzise auf den Fehler kalibriert, weil der Fehler die Schutzmaßnahme definiert hat. Falsche Positive sind materiell niedriger, weil das Muster aus einem realen Vorfall extrahiert wird, nicht aus einem Bedrohungsmodell imaginiert. Eine reaktive Schutzmaßnahme kann später dennoch zu breit greifen, wenn sich der Codebase weiterentwickelt, aber die Ausgangspräzision ist hoch.

Der reaktive Ansatz hat einen Preis: Die erste Instanz jeder Fehlerkategorie gelingt. Die Cache-Löschung ist passiert. Der Anmeldedaten-Lesevorgang ist passiert. Die Phantom-Verifizierung ist in Produktion gegangen. Die Abdrift hat Kontext verbraucht. Jeder erste Fehler ist der Eintrittspreis für eine präzise, rauscharme Schutzmaßnahme, die den zweiten Fehler verhindert.

Nach mehr als 500 Sitzungen sind die meisten strukturellen Fehlerkategorien aufgetreten. Die Kosten des ersten Fehlers amortisieren sich über Hunderte von Sitzungen, in denen der Hook ein Wiederauftreten verhindert hat. Das System wird mit jedem Vorfall robuster. Nicht klüger. Robuster.

Jeder Hook ist eine Narbe. Jede Narbe ist eine Lektion. Die Lektionen kumulieren sich.²

FAQ

Kann ich Ihre Hook-Konfigurationen sehen?

Ich beschreibe das Hook-System in meinem NIST-Kommentar zur Agent-Sicherheit und verweise darauf in der gesamten AI-Engineering-Serie. Hooks werden in ~/.claude/settings.json registriert und nach Ereignistyp durch ~/.claude/hooks/dispatchers/ verteilt.

Wie wirken sich Hooks auf die Agent-Performance aus?

Jeder Hook fügt Millisekunden pro Tool-Aufruf hinzu. Bei 84 Hooks beträgt der Gesamtaufwand 200–400 ms pro Tool-Aufruf, je nachdem, welche Hooks ausgelöst werden. Der Aufwand ist vernachlässigbar im Vergleich zur Modell-Inferenzzeit (2–5 Sekunden pro Antwort). Die Hooks sind nicht der Flaschenhals.

Funktionieren Hooks mit anderen KI-Coding-Tools?

Hooks sind spezifisch für Claude Code (PreToolUse-, PostToolUse-Ereignismodell). Das Konzept lässt sich auf jedes Agent-Framework mit Middleware- oder Plugin-Unterstützung anwenden. Die spezifischen Implementierungen sind nicht portierbar, aber die Narbentaxonomie und die reaktive Methodik gelten universell.

Was passiert, wenn ein Hook eine Aktion blockiert?

Harte Blockaden (Exit 2) verhindern die Aktion und injizieren eine Nachricht, die erklärt, warum. Der Agent sieht den Blockadegrund und passt sich an. Beratende Hooks (Exit 0) protokollieren das Anliegen, erlauben aber die Aktion. Destruktive Operationen verwenden harte Blockaden. Die meisten anderen Kategorien verwenden beratende Hooks. Das Passphrase-Gate wird nur für die gefährlichsten Operationen verwendet (Cache-Löschung, Infrastruktur-Löschung).

Wie entscheiden Sie zwischen harter Blockade und Beratung?

Zwei Klassen erhalten harte Blockaden: destruktive Operationen (Cache-Löschungen, Datenbank-Löschungen, Force-Pushes, Infrastruktur-Modifikationen) und Offenlegung von Anmeldedaten (Lesen von Geheimdateien, Zugriff auf Schlüsselspeicher). Alles andere erhält beratendes Logging. Die Unterscheidung liegt in der Schwere der Folgen: Wenn die Aktion kostengünstig rückgängig gemacht werden kann und keine Geheimnisse preisgibt, genügt eine Beratung. Wenn die Aktion unumkehrbar ist oder Anmeldedaten preisgibt, ist eine harte Blockade notwendig.

Quellen