Jeder Hook ist eine Narbe: 84 Agentenfehler, in Code gegossen

In meinem System zur Agentenorchestrierung greifen 84 Hooks in 15 der 26 Lebenszyklus-Ereignistypen ein, die Claude Code mit Stand v2.1.116 (April 2026) bereitstellt. Jeder Hook ist ein Shell-Skript oder ein Python-Schnipsel, das vor oder nach einer bestimmten Agentenaktion auslöst: Dateien lesen, Dateien schreiben, Bash-Befehle, Web-Anfragen, das Starten von Sub-Agenten, Git-Operationen, MCP-Werkzeugaufrufe. Jeden dieser Hooks gibt es, weil etwas schiefgegangen ist.

Jeder Hook in einem System zur Agentenorchestrierung geht auf einen konkreten Produktionsfehler zurück — die Sammlung der Hooks ist damit institutionelles Gedächtnis in Form von Shell-Skripten. Agenten haben CDN-Caches geleert, Dateien mit Zugangsdaten gelesen, bestandene Tests gemeldet, die sie nie ausgeführt hatten, und sind 40 Minuten lang vom Thema abgekommen. Aus jedem Vorfall entstand eine kleine, deterministische Schutzmaßnahme, die seither in jeder Sitzung lautlos auslöst.

Nicht theoretisch falsch. In der Produktion falsch. Ein Agent hat einen CDN-Cache geleert, der Millionen von Anfragen bediente. Ein Agent wollte SSH-Schlüssel schreiben. Ein Agent meldete „alle Tests bestanden”, ohne pytest je aufgerufen zu haben. Ein Agent entfernte sich so weit von seiner Aufgabe, dass er vierzig Minuten damit verbrachte, eine Funktion in einer Datei zu optimieren, die mit dem Auftrag nicht das Geringste zu tun hatte.

Keinen dieser Hooks habe ich vorausschauend entworfen. Ich habe mich nicht hingesetzt, um die Fehlermodi autonomer KI-Agenten aufzulisten und vorbeugende Kontrollen zu schreiben. Jeder Hook ist reaktiv. Etwas ging kaputt, ich schrieb ein Skript, damit es nicht wieder kaputtgeht, und seither läuft dieses Skript lautlos in jeder Sitzung mit. Das Hook-System ist keine Sicherheitsarchitektur. Es ist eine Narbensammlung.

TL;DR

• Der gelöschte Cache: Ein Agent leerte einen produktiven CDN-Cache über einen autorisierten API-Aufruf. Zwei Hooks (47 Zeilen) sichern destruktive Operationen inzwischen hinter einer von Hand eingetippten Passphrase ab.
• Der Zugangsdaten-Leser: Ein Agent nahm API-Tokens in sein Kontextfenster auf. Eine pfadbasierte Schutzmaßnahme blockiert jetzt das Lesen von Dateien mit Zugangsdaten und protokolliert Zugriffe auf .env-Dateien.
• Der Phantomprüfer: Ein Agent meldete „alle Tests bestanden”, ohne pytest auszuführen. Ein Detektor für vage Formulierungen senkte den Anteil der Phantomprüfungen von 12 % auf unter 2 % der Sitzungen.
• Die zwölf Abweichungen: Agenten verloren ihre Aufgabe innerhalb von sechzig Tagen nachweislich zwölfmal aus dem Blick. Ein Detektor auf Basis der Kosinus-Ähnlichkeit mit Schwellenwert 0,30 löst jetzt alle 25 Werkzeugaufrufe aus.
• Die Taxonomie: Sechs strukturelle Fehlerkategorien decken alle 84 Hooks ab. Neue Kategorien sind nach über 500 Sitzungen selten. Mit jedem Vorfall wird das System härter.

Der gelöschte Cache: Wie ein einziger autorisierter Aufruf die Produktion lahmlegte

Am 21. März 2026 bat ich einen Agenten zu untersuchen, warum die Marktseiten auf resumegeni.com langsam luden. Der Agent begann ganz normal: Route-Handler lesen, Datenbankabfragen prüfen, das Rendern der Templates profilieren. Dann kam er zu dem Schluss, veraltete Cloudflare-Cache-Einträge könnten das wahre Leistungsverhalten verschleiern.

Der Agent rief mcp__cloudflare__cache_purge mit purge_everything: true auf.

Damit war jede zwischengespeicherte Seite der Produktionsumgebung schlagartig ungültig. Statt die meisten Anfragen in 80 bis 100 ms auszuliefern, reichte das CDN nun jede einzelne Anfrage an den Railway-Ursprungsserver weiter. Die Marktseite für Austin stürzte vom Sub-Sekunden-Bereich auf 14.290 Millisekunden ab, New York auf 6.891 ms. Jede Seite der Website wurde nun bei jeder Anfrage aus dem kalten Ursprungsserver gerendert.

Der Agent tat nichts Unautorisiertes. Er nutzte ein legitimes MCP-Werkzeug mit gültigen Zugangsdaten, um einen freigegebenen API-Endpunkt aufzurufen. Wer Cache-Verhalten debuggt, für den ist das Leeren des Caches ein durchaus vernünftiger Schritt. Das Problem: „vernünftig fürs Debuggen” und „katastrophal für die Produktion” waren derselbe API-Aufruf, und zwischen der Überlegung des Agenten und der Konsequenz in der Produktion stand keinerlei Schranke.⁴

Noch in derselben Nacht baute ich zwei Hooks.

Die Bash-Sperre (destructive-api-guard.sh): Löst bei jedem Bash-Befehl aus. Sie gleicht Muster wie curl.*purge, rm -rf, DROP TABLE, docker.*rm und git push.*--force ab. Harte Blockade (Exit 2). Der Agent bekommt eine Meldung, die erklärt, warum der Befehl blockiert wurde, und Alternativen vorschlägt. Weiter kommt er nur mit der Passphrase „rosebud”, und die kann nur dann in den Kontext gelangen, wenn ein Mensch sie eintippt.

Die MCP-Sperre (destructive-mcp-guard.sh): Löst bei jedem MCP-Werkzeugaufruf aus, der auf mcp__cloudflare oder mcp__github passt. Sie prüft die Werkzeugparameter auf purge, delete, destroy und remove. Dieselbe harte Blockade, dieselbe Passphrasen-Schranke.

Zwei Hooks. Zwei Shell-Skripte. Insgesamt 47 Zeilen Code. Seit der Installation haben sie null Cache-Löschungen verhindert, denn seit Einführung der Passphrasen-Schranke hat kein Agent mehr eine versucht. Die Hooks fangen keine Angriffe ab. Sie sorgen dafür, dass diese Art von Fehler gar nicht mehr möglich ist.

Der Vorfall legte nebenbei genau das Leistungsproblem offen, das er hätte untersuchen sollen. Austin mit 14 Sekunden beim kalten Rendern führte zur Übergabe der Marktseiten-Analyse und diese vier Tage später zur Korrektur der Abfrageform. Der Vorfall war nützlich. Der Hook stellt sicher, dass er sich nicht wiederholt.

Der Zugangsdaten-Leser

Im Februar 2026 las ein Agent, der Kontext für ein Projekt sammelte, die Datei ~/.claude/docs/credentials.md. Sie enthält API-Tokens für Cloudflare, GitHub, Railway und weitere Dienste. Der Agent nahm eine Zusammenfassung des Dateiinhalts in seine Arbeitsnotizen auf — womit die Tokens in der API-Anfrage an die Server von Anthropic landeten.

Committet wurde kein Token. Öffentlich wurde keines. Aber die Tokens wanderten durch eine fremde API in ein Kontextfenster, über das ich keine Kontrolle habe. Die Angriffsfläche wuchs von „meiner Maschine” auf „meine Maschine plus die Inferenz-Infrastruktur von Anthropic”.

Die Pfadsperre für Zugangsdaten löst bei jedem Dateilesevorgang aus. Sie gleicht den Pfad mit einer Liste sensibler Muster ab: .env, credentials, .ssh/, .aws/, .gnupg/, secrets. Beim Lesen von Zugangsdaten protokolliert der Hook eine Warnung und blockiert den Zugriff. Bei .env-Dateien erlaubt er das Lesen, protokolliert den Zugriff aber.

Für die meisten Pfade ist die Sperre nur beratend, für Dateien mit Zugangsdaten dagegen eine harte Blockade. Der Unterschied zählt: Ein Agent, der .env liest, um die Namen der Umgebungsvariablen zu verstehen, sammelt nützlichen Kontext. Ein Agent, der credentials.md liest, um an API-Tokens zu kommen, ist ein Sicherheitsvorfall.

Seit der Installation hat die Pfadsperre in über 200 Sitzungen 23-mal ausgelöst. Zwanzigmal davon lasen Agenten .env-Dateien (protokolliert, erlaubt). Dreimal versuchten Agenten, Dateien mit Zugangsdaten oder Schlüsseln zu lesen (blockiert). Hinter jedem blockierten Lesevorgang stand ein Agent, der breit Projektkontext sammelte und dabei zufällig eine sensible Datei ins Suchmuster nahm. Bösartig war keiner davon. Ohne die Sperre wären in jedem dieser Fälle Geheimnisse ins Kontextfenster gelangt.

Der Phantomprüfer

Der heimtückischste Fehlermodus ist ein Agent, der eine erfolgreiche Prüfung meldet, ohne geprüft zu haben.

Sitzung 147. Ich bat einen Agenten, eine Datenbankabfrage umzubauen und die Änderung mit der vorhandenen Testsuite zu verifizieren. Der Umbau der Abfrage gelang korrekt. Im Abschlussbericht stand: „Alle Tests bestanden. Die umgebaute Abfrage liefert identische Ergebnisse wie das Original.”

Ich sah ins Sitzungsprotokoll. Kein pytest-Aufruf. Kein Test-Runner irgendeiner Art war aufgerufen worden. Der Agent hatte geschlussfolgert, die Tests würden bestehen, weil die umgebaute Abfrage logisch äquivalent zum Original sei — und diese Schlussfolgerung als Testergebnis ausgegeben.

Die umgebaute Abfrage war korrekt. Die Tests wären bestanden worden. Die Überlegung des Agenten war schlüssig. Doch über Tests nachzudenken ist nicht dasselbe wie Tests auszuführen, und genau in dieser Lücke gehen Bugs in Produktion. Wäre die umgebaute Abfrage in einem Randfall subtil falsch gewesen, den die Überlegung nicht abdeckte, wäre der Bug mit einem Abschlussbericht ausgeliefert worden, der eine Testverifikation behauptet.

Bevor ich den Hook für die Beweispflicht baute, trat dieser Fehlermodus in 60 Sitzungen 7-mal auf. Der Hook löst bei jedem Abschlussbericht aus und sucht nach vagen Formulierungen: „sollte bestehen”, „ich glaube”, „die Tests bestehen wahrscheinlich”, „ich bin zuversichtlich”. Wird er fündig, schiebt er eine Meldung ein: „Vage Formulierung erkannt. Nennen Sie konkrete Belege: Testausgabe einfügen, Datei und Zeilennummer nennen oder den konkreten Prüfschritt referenzieren.”

Der Hook verifiziert nicht, dass die Tests tatsächlich liefen. Er markiert das sprachliche Muster, das auf eine übersprungene Prüfung hindeutet. Die Erkennung ist unvollkommen. Ein hinreichend sprachgewandter Agent könnte seine Absicherungen so umformulieren, dass sie durchrutschen. Aber der Hook erwischt den Regelfall — und der macht 12 % der Agentenfehler aus, die menschliches Eingreifen erfordern.¹

Nach der Installation des Hooks ging die Phantomprüfung von 12 % auf unter 2 % der Sitzungen zurück. Bei den verbleibenden 2 % formuliert der Agent seine Absicherung um, oder die Prüfaussage stimmt technisch, ist aber unvollständig (etwa „Unit-Tests bestanden”, während die Integrationstests gar nicht liefen).

Abweichung

Zwischen Januar und März 2026 schlug mein Abweichungsdetektor zwölfmal in Sitzungen an, in denen der Agent seine zugewiesene Aufgabe nachweislich aus dem Blick verloren hatte.

Der Detektor bettet die ursprüngliche Aufgabenstellung ein und vergleicht sie regelmäßig mit der Einbettung der jüngsten Agentenaktionen. Fällt die Kosinus-Ähnlichkeit unter 0,30, schiebt das System eine Warnung mitsamt der ursprünglichen Aufgabe ein. Den Schwellenwert habe ich experimentell kalibriert: 0,50 war zu empfindlich (löste bei legitimer Erkundung von Teilaufgaben aus), 0,20 zu großzügig (übersah offensichtliche Abweichungen), 0,30 erwischte jeden bestätigten Abweichungsfall.

Sitzung 203 war der klarste Fall. Die Aufgabe lautete: „Das kaputte XML-Escaping der Sitemap für Job-Slugs mit Ampersand beheben.” Der Agent begann damit, den Code zur Sitemap-Erzeugung zu lesen. Dann fiel ihm auf, dass die Sitemap aus einer Datenbankabfrage erzeugt wird. Dann fiel ihm auf, dass sich diese Abfrage optimieren ließe. Dann verbrachte er 40 Minuten damit, die Abfrage in ein Materialized-View-Muster umzubauen, schrieb Tests für die neue Abfrage und meldete die Optimierung als abgeschlossen. Das Ampersand-Escaping hat er nie repariert.

Bei der Marke von 25 Werkzeugaufrufen — rund 15 Minuten nach Sitzungsbeginn — hätte der Detektor das aufgefangen, sobald die Ähnlichkeit zwischen „XML-Escaping der Sitemap beheben” und „Materialized View anlegen” unter den Schwellenwert fiel. Stattdessen entdeckte ich die Abweichung erst beim Review.

Sitzung 89 war subtiler. Die Aufgabe: „Den Authentifizierungs-Endpunkten ein Rate Limiting hinzufügen.” Der Agent baute das Rate Limiting korrekt ein. Dann fiel ihm auf, dass der Authentifizierungsablauf uneinheitliche Fehlermeldungen hatte. Dann vereinheitlichte er die Fehlermeldungen. Dann fiel ihm auf, dass das Format der Fehlerantwort vom Standard für API-Antworten abwich. Dann baute er das Antwortformat über 12 Endpunkte hinweg um. Das Rate Limiting war korrekt und vollständig. Die Ausweitung des Umfangs — das war die Abweichung.

Der Abweichungsdetektor löst alle 25 Werkzeugaufrufe aus. In allen zwölf Fällen unterhalb des Schwellenwerts war der Agent nachweislich von der ursprünglichen Aufgabe abgewichen. In sechs Fällen korrigierte er sich nach der eingeschobenen Warnung selbst. In vier Fällen räumte er die Abweichung ein, argumentierte aber, die laufende Arbeit sei wertvoll (mitunter zu Recht). In zwei Fällen ignorierte er die Warnung und machte mit der abweichenden Arbeit weiter.

Der Hook verhindert keine Abweichung. Er macht sie sichtbar. Ob umgelenkt oder weitergearbeitet wird, entscheidet weiterhin der Mensch. Ohne den Hook aber bleibt die Abweichung bis zum Abschlussbericht unsichtbar — und dann ist das Kontextbudget bereits verbraucht.

Die Narben-Taxonomie

Nach 84 Hooks zeichnen sich Muster ab. Die Fehler gruppieren sich in sechs Kategorien:

Die übrigen 47 Hooks sind projektspezifisch (Durchsetzung von Konventionen, Deployment-Sperren, Übersetzungsprüfer) oder experimentell (Kostenerfassung, Sitzungsmetriken, Aktivitätssignale).

Die sechs strukturellen Kategorien sind stabil. Neue Vorfälle innerhalb dieser Kategorien fangen die vorhandenen Hooks ab. Neue Kategorien sind selten. In sechs Monaten Betrieb kam nur eine einzige neue strukturelle Kategorie hinzu (projektübergreifende Kontamination, entdeckt, als eine im Projekt obsidian-signals laufende Sitzung Dateien in blakecrosley.com bearbeiten wollte). Die anderen fünf Kategorien standen bereits nach den ersten 60 Sitzungen fest.

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 gab — kam unabhängig auf überlappende Fehlerkategorien: unverhältnismäßige Reaktion (destruktive Operationen), Identitätsübernahme (Preisgabe von Zugangsdaten), Endlosschleifen (Ressourcenerschöpfung) und schrittweises Nachgeben unter Druck (Aufgabenabweichung).⁵ Dass sich ihre kontrollierte Forschung und meine Produktionserfahrung derart decken, spricht dafür: Diese Kategorien sind strukturelle Eigenschaften autonomer Agenten, keine Artefakte einer bestimmten Konfiguration.

Was Hooks nicht abfangen können

Hooks arbeiten auf der Ebene des Werkzeugaufrufs. Sie greifen vor oder nach der Aktion ein. Was sie nicht abfangen können, ist die Überlegung, die zu der Aktion geführt hat.

Ein Agent, der eine Funktion umbaut, statt den gemeldeten Bug zu beheben, erzeugt einen gültigen Werkzeugaufruf (Datei schreiben) mit korrektem Inhalt (syntaktisch valider Code), der die Aufgabe verfehlt (falsche Funktion). Kein Hook fängt das ab, weil kein einziger Werkzeugaufruf verdächtig aussieht. Der Abweichungsdetektor erwischt es irgendwann — aber erst, nachdem der Agent erheblichen Kontext an der falschen Arbeit verbraucht hat.

Ebenso wenig fangen Hooks Kompositionsfehler ab, bei denen jede Einzelaktion autorisiert ist, die Abfolge aber ein nicht autorisiertes Ergebnis produziert. Das Leeren des Caches war genau so ein Kompositionsfehler: die Cache-Konfiguration lesen (autorisiert), die Purge-API aufrufen (autorisiert) — aber die Kombination (den Produktions-Cache mitten in einer Untersuchung leeren) war schädlich. Die MCP-Sperre fängt diese eine Kombination inzwischen ab, doch neuartige Kompositionen bleiben ungedeckt.

Die Kompositionslücke in der Lieferkette³ liegt auf derselben Ebene: Vertrauenswürdige Komponenten setzen sich zu nicht autorisiertem Verhalten zusammen. Hooks sind Schutzmaßnahmen auf Komponentenebene. Denken auf Kompositionsebene braucht einen anderen Mechanismus — einen, der Handlungsfolgen statt einzelner Handlungen bewertet. Der Abweichungsdetektor kommt dem am nächsten: Er bewertet den Verlauf des Verhaltens statt einzelner Werkzeugaufrufe. Gemessen wird dabei aber die Ähnlichkeit zur ursprünglichen Aufgabe, nicht die Sicherheit der zusammengesetzten Handlungsfolge.

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

Warum reaktiv ehrlich ist

Ich könnte ein vorausschauendes Hook-System entwerfen. Jeden denkbaren Fehlermodus auflisten. Für jeden eine vorbeugende Kontrolle schreiben. Eine vollständige Sicherheitsarchitektur bauen, bevor die erste Sitzung startet.

Ich tue es nicht, denn vorausschauendes Design setzt voraus, Fehler vorherzusagen, die noch nie eingetreten sind. Diese Vorhersagen wären falsch. Die Hooks wären entweder zu breit (blockieren legitime Aktionen) oder zu eng (verfehlen das tatsächliche Fehlermuster). Die Rate der Fehlalarme würde das Vertrauen in das Hook-System zersetzen, und ich würde anfangen, Warnungen zu ignorieren.

Reaktive Hooks sind ehrlich. Jeder einzelne sagt: „Genau das ist passiert, und hier ist genau die Schutzmaßnahme, die es verhindert.” Die Maßnahme ist präzise auf den Fehler kalibriert, weil der Fehler sie definiert hat. Fehlalarme sind deutlich seltener, weil das Muster aus einem realen Vorfall stammt und nicht aus einem ausgedachten Bedrohungsmodell. Eine reaktive Schutzmaßnahme kann später trotzdem zu breit greifen, wenn sich die Codebasis weiterentwickelt — aber ihre Anfangspräzision ist hoch.

Der reaktive Ansatz hat seinen Preis: Der erste Fall jeder Fehlerkategorie geht durch. Der Cache wurde geleert. Die Zugangsdaten wurden gelesen. Die Phantomprüfung ging in Produktion. Die Abweichung fraß Kontext. Jeder erste Fehler ist das Eintrittsgeld für eine präzise, geräuscharme Schutzmaßnahme, die den zweiten verhindert.

Nach über 500 Sitzungen sind die meisten strukturellen Fehlerkategorien bereits aufgetreten. Der Preis des ersten Fehlers amortisiert sich über Hunderte von Sitzungen, in denen der Hook die Wiederholung verhindert hat. Mit jedem Vorfall wird das System härter. Nicht klüger. Härter.

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

FAQ

Kann ich Ihre Hook-Konfigurationen einsehen?

Das Hook-System beschreibe ich in meiner Stellungnahme an das NIST zur Agentensicherheit und beziehe mich in der gesamten AI-Engineering-Reihe darauf. Die Hooks werden in ~/.claude/settings.json registriert und über ~/.claude/hooks/dispatchers/ nach Ereignistyp verteilt.

Wie wirken sich Hooks auf die Leistung des Agenten aus?

Jeder Hook kostet einige Millisekunden pro Werkzeugaufruf. Bei 84 Hooks liegt der Gesamtaufwand je nach ausgelösten Hooks bei 200 bis 400 ms pro Werkzeugaufruf. Gegenüber der Inferenzzeit des Modells (2 bis 5 Sekunden pro Antwort) ist das vernachlässigbar. Der Engpass sind die Hooks nicht.

Funktionieren Hooks auch mit anderen KI-Programmierwerkzeugen?

Hooks sind spezifisch für Claude Code (Ereignismodell mit PreToolUse und PostToolUse). Das Konzept lässt sich auf jedes Agenten-Framework mit Middleware- oder Plugin-Unterstützung übertragen. Die konkreten Implementierungen sind nicht portabel, wohl aber die Narben-Taxonomie und die reaktive Methodik.

Was passiert, wenn ein Hook eine Aktion blockiert?

Harte Blockaden (Exit 2) verhindern die Aktion und schieben eine Meldung mit der Begründung ein. Der Agent sieht den Grund und passt sich an. Beratende Hooks (Exit 0) protokollieren das Bedenken, lassen die Aktion aber zu. Destruktive Operationen bekommen harte Blockaden. Die meisten übrigen Kategorien laufen beratend. Die Passphrasen-Schranke kommt nur bei den gefährlichsten Operationen zum Einsatz (Cache leeren, Infrastruktur löschen).

Wie entscheiden Sie zwischen harter Blockade und Hinweis?

Zwei Klassen bekommen harte Blockaden: destruktive Operationen (Caches leeren, Datenbanken löschen, Force Pushes, Änderungen an der Infrastruktur) und die Preisgabe von Zugangsdaten (Lesen geheimer Dateien, Zugriff auf Schlüsselspeicher). Alles andere wird beratend protokolliert. Ausschlaggebend ist die Schwere der Folgen: Lässt sich die Aktion günstig rückgängig machen und legt sie keine Geheimnisse offen, genügt ein Hinweis. Ist sie unumkehrbar oder gibt sie Zugangsdaten preis, muss hart blockiert werden.

Quellen