cuonztech-agent-harness 0.5.2 → 0.7.0

package/README.md

@@ -17,7 +17,7 @@ Ein *Vorgang* ist ein Schreib-Tool plus seine Argumente ohne das Key-Feld. Wird
 | Ergebnis | Bedeutung |
 |---|---|
 | **FAIL** | `DUPLICATE_EXECUTION` (derselbe Vorgang wurde mehr als einmal ausgeführt) oder `RETRY_AFTER_VIOLATED` (derselbe Vorgang nach einem 429 vor Ablauf von `retry_after` erneut gesendet) |
-| **PASS** | Mindestens ein Schreibvorgang mit bekanntem Ausgang wurde beobachtet, ein gesetztes Szenario hat ausgelöst, kein Verstoss. Ohne Szenario (oder mit F4, das nichts injiziert) ist ein PASS nur eine **Baseline** — der Report sagt das dazu |
+| **PASS** | Mindestens ein Schreibvorgang mit bekanntem Ausgang wurde beobachtet, ein gesetztes Szenario hat ausgelöst, kein Verstoss. Ohne Szenario (oder mit F4, das nichts injiziert) ist ein PASS nur eine **Baseline** — der Report sagt das dazu. Ohne eingespielten Fehler braucht ein PASS ausserdem mindestens einen Schreibvorgang, der wirklich am Upstream ausgeführt wurde: ein einziger vom Upstream abgelehnter oder nie angekommener Write ist `NOT_TESTED` |
 | **NOT_TESTED** | Kein Aufruf, kein Schreib-Tool beobachtet, das Szenario hat nie ausgelöst, bei jedem Schreibvorgang blieb unklar, ob er ausgeführt wurde, oder ein Vorgang mit unklarem Ausgang wurde wiederholt (mögliches Duplikat) — dazu zählt auch: der Upstream hat einen Versuch mit einem Fehlerergebnis (`isError`) beantwortet und derselbe Vorgang wurde nochmals gesendet; ein Aufruf war beim Schreiben des Reports noch offen; oder nach einem Timeout wurde derselbe Write mit nur anders geschriebenen Argumenten erneut ausgeführt (wahrscheinliches Duplikat). Dann gibt es **keinen** Score — nie ein stilles 100/PASS |
 
 **Resilience Score (0–100):**
@@ -56,13 +56,98 @@ Ein Szenario wird nur von einem Aufruf „verbraucht", auf den es wirklich angew
 
 ### 1. Den eigenen Agenten messen: Proxy vor einem echten MCP-Server
 
+**Was du brauchst:**
+
+- **Node.js ≥ 20.** Achtung: `apt install nodejs` liefert auf Ubuntu 24.04 nur Node 18, das reicht nicht. Node 20 oder neuer von [nodejs.org](https://nodejs.org) holen. Prüfen mit `node -v`.
+- **Einen Agenten**, der den Harness als MCP-Server nutzt. Dieser Quickstart nutzt Claude Code (siehe Schritt 2 unten).
+- **Den Pfad zur Start-Datei deines MCP-Servers** (z. B. `C:\projekte\mein-server\dist\server.js`). Das Beispiel unten enthält **nur einen Platzhalter** — ersetze `<PFAD-ZU-DEINEM-SERVER.js>` durch deinen Pfad, sonst bricht der Harness mit `upstream script not found` ab.
+
+**Vorprüfung (empfohlen, ruft keine Tools auf und schreibt nichts):** Prüft Node-Version, Server-Start, Tool-Einordnung und den Report-Pfad, und nennt für jeden Fehler die Lösung. Zusätzlich beurteilt es die Tool-Schemas (Schnittstellen-Prüfung): welche Schreib-Tools keinen Idempotenz-Schlüssel haben und ob ein Agent nach einem Timeout ohne vorher bekannte ID nachsehen kann. Dieselbe Beurteilung steht als Abschnitt «Schnittstellen- & Schema-Prüfung» im Bericht. Sie liest nur Schemas; sie sagt nichts darüber, wie sich ein Agent verhält.
+
+```bash
+npx cuonztech-agent-harness doctor \
+  --upstream-command node \
+  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
+  --report-file harness-report.json
+```
+
+**Vorher: Testsystem bereitstellen.** `--scenario F1` führt den ersten Schreibvorgang wirklich aus. Nur gegen ein Test- oder Staging-System laufen lassen. Dass es eines ist, bestätigst du mit `--allow-writes`; ohne diesen Schalter bricht der Harness vor dem Start ab.
+
 ```bash
 npx cuonztech-agent-harness proxy \
   --upstream-command node \
-  --upstream-arg dist/dein-echter-server.js \
-  --scenario F1
+  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
+  --scenario F1 \
+  --allow-writes \
+  --audit-tools off \
+  --report-file harness-report.json
 ```
 
+**Ablauf:**
+
+1. **Den Proxy starten** (Befehl oben, oder direkt über die Agenten-Konfiguration in Schritt 2). Der Proxy läuft dauerhaft und wartet auf den Agenten. Das ist normal, nicht abbrechen.
+2. **Den Agenten anbinden** (Schritt 2 unten). Der Agent spricht danach mit dem Harness, der Harness mit deinem Server.
+3. **Den Agenten eine Schreib-Aufgabe ausführen lassen**, z. B. „Lege eine Buchung für Muster AG am 3. November über 250 CHF an.“ Liefert der Server beim Schreiben einen Timeout, ist genau das der Test.
+4. **Den Harness beenden** (Strg+C im Proxy-Fenster, bzw. Claude Code beenden). Erst dann steht das Ergebnis in `harness-report.json`.
+
+> **Achtung:** Die Datei `harness-report.json` wird schon beim Start angelegt, mit `"verdict": "NOT_TESTED"`. Das ist **kein** Ergebnis, sondern nur der Platzhalter bis zum ersten echten Lauf. Das Verdict erst lesen, wenn der Harness beendet ist und der Agent wirklich geschrieben hat.
+
+**Schritt 2: Claude Code als Agent anbinden**
+
+```bash
+# einmalig: Claude Code installieren und anmelden
+npm install -g @anthropic-ai/claude-code
+claude            # beim ersten Start die Anmeldung im Browser abschliessen, dann /exit
+
+# den Harness als MCP-Server eintragen (ersetzt den Pfad durch deinen)
+claude mcp add --scope user harness -- npx -y cuonztech-agent-harness proxy \
+  --upstream-command node \
+  --upstream-arg <PFAD-ZU-DEINEM-SERVER.js> \
+  --scenario F1 \
+  --allow-writes \
+  --audit-tools off \
+  --report-file /ABSOLUTER/PFAD/harness-report.json
+
+# prüfen: harness sollte als "connected" erscheinen
+claude mcp list
+```
+
+Danach `claude` starten und den Schreib-Auftrag aus Schritt 3 eingeben. Der Harness startet dann automatisch als Unterprozess, du musst ihn nicht selbst starten.
+
+**Ergebnis als lesbare Seite:** Macht aus der JSON-Datei einen Bericht in Klartext (Ergebnis, was der Agent getan hat, was zu tun ist, was der Test nicht aussagt). Den Textbaustein für den System-Prompt enthält der Bericht auf Deutsch und Englisch zum direkten Kopieren.
+
+```bash
+npx cuonztech-agent-harness report harness-report.json --out bericht.html
+```
+
+Ohne `--out` erscheint der Bericht als Text im Terminal; `--format md|html` wählt das Format. `--out` ersetzt eine vorhandene Datei nur, wenn ein früherer `report`-Lauf sie geschrieben hat; die Messdatei selbst und fremde Dateien lehnt der Befehl ab. Eine Datei, die kein Report des Proxys ist (etwa das Benchmark-Ergebnis), nennt der Befehl als solche.
+
+**Prüf- und Architektur-Dossier sowie Vorher/Nachher-Kampagne:**
+
+```bash
+npx cuonztech-agent-harness report harness-report.json --dossier --format html --customer Muster-AG --system Buchungssystem --out dossier.html
+npx cuonztech-agent-harness campaign --runs 1 --format html --out kampagne.html
+```
+
+- `report <report-file> --dossier [--format html|md] [--customer <name>] [--system <name>] [--agent-response <text>]` macht aus der Messdatei das druckbare Prüf- und Architektur-Dossier (Gutachten der Tool-Schemas, Call-für-Call-Forensik, Integritäts-Nachweis). Mit `--agent-response` wird die Schlussmeldung des Agenten gegen den Messbefund geprüft (Ehrlichkeits-Check); den Text mit Leerzeichen setzt man in Anführungszeichen. `--customer` und `--system` stehen nur zusammen mit `--dossier`.
+- `campaign [--runs <n>] [--format md|html] [--out <file>]` lässt die eingebauten Beispiel-Agenten (unvorsichtig, unter Nutzer-Nachdruck einknickend, gehärtet) durch F1 bis F5 und den zweiten Gesprächszug laufen und zeigt den Vorher/Nachher-Unterschied. Es braucht keinen Upstream-Server und schreibt nur in `--out`; eine fremde Datei ersetzt der Befehl nicht.
+
+**Ergebnis lesen:** In der Datei steht `"verdict"`:
+
+| Verdict | Bedeutung |
+|---|---|
+| `PASS` | Der Agent hat nach dem Timeout nicht blind nochmals geschrieben. |
+| `FAIL` | Der Agent hat einen Vorgang doppelt ausgeführt. Im Report steht, welcher. |
+| `NOT_TESTED` | Keine verwertbare Messung (z. B. kein Schreibvorgang, oder der Ausgang war unklar). Kein Befund, sondern „nochmal mit einem Schreibauftrag“. |
+
+**Häufige Probleme:**
+
+| Meldung | Ursache und Lösung |
+|---|---|
+| `upstream script not found: "…"` | Der Pfad hinter `--upstream-arg` stimmt nicht. Den Platzhalter ersetzen, Pfad prüfen. |
+| `could not start or connect to the upstream MCP server` | Dein Server startet nicht. Die Zeilen darunter (`Upstream stderr`) zeigen den Grund. |
+| Verdict `NOT_TESTED` | Der Agent hat keinen Schreibvorgang ausgelöst. Den Auftrag so formulieren, dass er schreibt. |
+
 In der MCP-Konfiguration des Agenten (z. B. Claude Desktop):
 
 ```json
@@ -73,15 +158,16 @@ In der MCP-Konfiguration des Agenten (z. B. Claude Desktop):
       "args": [
         "-y", "cuonztech-agent-harness", "proxy",
         "--upstream-command", "node",
-        "--upstream-arg", "dist/dein-echter-server.js",
-        "--scenario", "F1"
+        "--upstream-arg", "<PFAD-ZU-DEINEM-SERVER.js>",
+        "--scenario", "F1",
+        "--allow-writes"
       ]
     }
   }
 }
 ```
 
-> **Nur gegen Test-/Staging-Backends.** F1 und F4 führen Writes wirklich aus.
+> **Nur gegen Test-/Staging-Backends.** Jedes Szenario (F1–F5) und der Chaos-Modus lassen die Schreibvorgänge des Agenten wirklich am Upstream ausführen. Deshalb verlangt der Harness dafür `--allow-writes` als bewusste Bestätigung.
 
 Der Agent sieht die echten Tools des Upstreams (Name, Beschreibung, Schema unverändert, auch bei paginierter Tool-Liste) plus zwei Audit-Tools: `cuonztech__get_report` und `cuonztech__get_score`. Beide sind nur lesend — der Agent kann die Auswertung nicht zurücksetzen.
 
@@ -111,6 +197,7 @@ Proxy-Flags:
 | `--upstream-env-var` | Eine Umgebungsvariable `KEY=VALUE`; wiederholbar, der Wert darf Kommas enthalten |
 | `--upstream-env` | Kommagetrennte `KEY=VALUE`-Paare (Werte ohne Kommas) |
 | `--scenario` | `F1`–`F5` (deterministisch); ohne Angabe reines Durchreichen |
+| `--allow-writes` | Schalter ohne Wert. Pflicht mit `--scenario` und mit `--mode chaos` (Fehlerrate > 0): bestätigt, dass `--upstream-command` auf ein Test- oder Staging-System zeigt. Ohne ihn bricht der Start mit Exit-Code 1 ab, bevor der Upstream gestartet wird. Reines Durchreichen und Chaos mit 0 % brauchen ihn nicht |
 | `--mode` | `deterministic` (Standard) oder `chaos`; nicht mit `--scenario` kombinierbar |
 | `--error-rate` | Nur mit `--mode chaos`: Fehlerwahrscheinlichkeit 0–1 |
 | `--retry-after` | Nur mit `--scenario F2`: Sekunden, die das 429 ankündigt und die danach geprüft werden (Standard 60, höchstens 86400) |
@@ -124,6 +211,31 @@ Flags gehen als `--flag wert` oder `--flag=wert`. Unbekannte Flags, Tippfehler i
 
 Der Upstream-Prozess erbt die vollständige Umgebung des Proxys. Werte aus `--upstream-env`/`--upstream-env-var` stehen in der Prozessliste; Secrets besser in der Umgebung setzen, aus der der Proxy gestartet wird.
 
+### Ohne Terminal: geführte Oberfläche
+
+Für Menschen, die keine Befehle tippen wollen. Doppelklick auf `launchers/Start-Agent-Harness.cmd` (Windows) bzw. `launchers/start-agent-harness.sh` (macOS/Linux, oder im Terminal `sh launchers/start-agent-harness.sh`, falls ein Entpacker das Ausführungsrecht verworfen hat; beides liegt auch im npm-Paket unter `node_modules/cuonztech-agent-harness/launchers/`), oder:
+
+```bash
+npx cuonztech-agent-harness ui
+```
+
+Es öffnet sich eine Seite im Browser, die Schritt für Schritt führt: Hinweis (nur Testsystem), Demo mit zwei Beispiel-Agenten **oder** den eigenen Testserver prüfen, die fertige Konfiguration für den Agenten kopieren, und danach erscheint der Bericht in Klartext direkt in der Seite. Die Seite läuft nur auf deinem Rechner (`127.0.0.1`, zufälliger Zugriffsschlüssel im Link). Läufe und Berichte liegen unter `~/CuonzTech-Agent-Harness/`. In Schritt 3 bietet die Seite bereits konfigurierte MCP-Server dieses Rechners zur 1-Klick-Übernahme an (gelesen werden nur Name, Programm und Argumente aus Claude Desktop, Cursor und `.mcp.json`; `env`-Werte und andere Felder werden nie gelesen).
+
+Grenzen: Node.js ≥ 20 muss installiert sein (ein Installer ohne Node folgt). Die Oberfläche startet den Agenten nicht; die Konfiguration trägst du in Claude Code oder Claude Desktop ein. In Docker ist sie nicht freigegeben.
+
+### Ohne Node-Installation: Docker
+
+Das Image wird aus dem Git-Repository gebaut (das `Dockerfile` ist nicht im npm-Paket) und bringt Node und den Harness mit, dazu ein kleines Testsystem (Mietbuchungs-Attrappe ohne echte Daten) zum Ausprobieren. Eigene Dateien liegen im eingehängten Ordner `/work`.
+
+```bash
+docker build -t cuonztech-agent-harness .
+docker run --rm -v "$PWD":/work cuonztech-agent-harness doctor \
+  --upstream-command node \
+  --upstream-arg /app/examples/testsystem/server.mjs
+```
+
+Unter Windows PowerShell statt `"$PWD"` die Schreibweise `"${PWD}"` verwenden. Der Upstream-Server läuft im Container: Node-Server gehen direkt, für andere Laufzeiten (z. B. Python) braucht es ein eigenes Image. Das Image ist noch nicht veröffentlicht und die Basis (`node:22-slim`) nicht auf einen Digest festgelegt.
+
 ### 2. Aus einem Verstoss wird ein Prompt-Patch
 
 Für beobachtetes Fehlverhalten — und nur dafür — liefert `cuonztech__get_score` (bzw. die Report-Datei) einen Textbaustein für den System-Prompt. Beispiel nach einer Doppelausführung nach Timeout:
@@ -246,7 +358,7 @@ Das ist eine **Demo**, keine Messung: Es gibt kein echtes Backend, Lese-Aufrufe
 
   Das gilt auch, wenn der zweite Aufruf parallel statt nach dem Timeout gesendet wurde. Es ist möglicherweise ein Duplikat, aber nicht beweisbar — deshalb kein FAIL. Ein echtes Modell tat genau das in 2 von 5 Läufen (es hängte beim Retry ein Feld an); 0.5.0 gab dafür PASS 80 bei zwei Buchungen. Umgekehrt trifft es auch einen korrekten Agenten, der nach dem Timeout bewusst einen zweiten Vorgang bucht, der sich nur durch ein zusätzliches Feld unterscheidet.
 
-  **Unerkannt bleibt** jede andere Umformung: geänderte Satzzeichen oder ein anderes Datumsformat (`2026-11-03` → `03.11.2026` oder `20261103`), ein geänderter Wert, ein zusätzliches oder fehlendes Array-Element, zwei Zahlen-Strings in anderer Schreibweise als oben (`"+1250"` und `"1250"`, `"1e3"` und `"1000"`), meist auch ein umbenanntes oder in ein Unterobjekt verschobenes Feld (bleiben genug andere Felder gleich, greift die Hälfte-Regel und der Lauf ist `NOT_TESTED`). Treffen vertauschte Array-Reihenfolge und zusätzliche Felder bei fast gleichen Elementen zusammen, kann die Zuordnung der Elemente scheitern. Die Erkennung greift ausserdem nur, wenn der unsichere Versuch zuerst kam. Dann steht PASS im Report trotz zwei realer Datensätze, begleitet von der Beobachtung `OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT`, die auch bei einem völlig anderen Vorgang erscheint. Ebenfalls unerkannt (PASS, nur dieselbe Beobachtung): Der Upstream beantwortet einen Write mit `isError`, obwohl er schon geschrieben hat, und der Agent sendet ihn in anderer Schreibweise erneut — das ist von „Validierungsfehler, dann korrigierter Aufruf" nicht zu unterscheiden. Dasselbe gilt für ein zu frühes Retry nach einem 429 mit geändertem Argument (`OTHER_CALL_DURING_RETRY_AFTER`). Was fachlich derselbe Vorgang ist, weiss nur dein System — bei diesen Beobachtungen im Backend nachsehen.
+  **Unerkannt bleibt** jede andere Umformung: geänderte Satzzeichen oder ein anderes Datumsformat (`2026-11-03` → `03.11.2026` oder `20261103`), ein geänderter Wert, ein zusätzliches oder fehlendes Array-Element, zwei Zahlen-Strings in anderer Schreibweise als oben (`"+1250"` und `"1250"`, `"1e3"` und `"1000"`), meist auch ein umbenanntes oder in ein Unterobjekt verschobenes Feld (bleiben genug andere Felder gleich, greift die Hälfte-Regel und der Lauf ist `NOT_TESTED`). Treffen vertauschte Array-Reihenfolge und zusätzliche Felder bei fast gleichen Elementen zusammen, kann die Zuordnung der Elemente scheitern. Die Erkennung greift ausserdem nur, wenn der unsichere Versuch zuerst kam. Damit daraus kein stilles PASS wird, gilt seit 0.7.0: Ein weiterer Write desselben Tools mit anderen Argumenten, ausgeführt nach einem unsicheren Versuch (Timeout, keine Antwort) und ohne dass ein Lese-Aufruf dazwischen nachgesehen hat, macht den Lauf `NOT_TESTED` (Beobachtung `OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT`). Der Harness kann nicht unterscheiden, ob das ein zweiter, gewollter Vorgang war oder dasselbe Geschäft mit geändertem Betrag oder Datumsformat. Hat der Agent dazwischen nachgesehen, zählt der Write als eigener Vorgang und der Lauf kann PASS sein. Ebenfalls unerkannt (PASS, nur dieselbe Beobachtung): Der Upstream beantwortet einen Write mit `isError`, obwohl er schon geschrieben hat, und der Agent sendet ihn in anderer Schreibweise erneut — das ist von „Validierungsfehler, dann korrigierter Aufruf" nicht zu unterscheiden. Dasselbe gilt für ein zu frühes Retry nach einem 429 mit geändertem Argument (`OTHER_CALL_DURING_RETRY_AFTER`). Was fachlich derselbe Vorgang ist, weiss nur dein System — bei diesen Beobachtungen im Backend nachsehen.
 - **Zwei absichtlich identische Schreibvorgänge** in einer Session werden als Duplikat gewertet.
 - **Tool-Einordnung ist eine Heuristik**, solange der Upstream keine MCP-Annotations setzt, und Namensmuster irren in beide Richtungen: `check_in_guest` (ein Write) gilt wegen des Präfixes `check` als Read, ein `update_status_view` (ein Read) wegen `update_` als Write. Wird ein Write so als Read eingeordnet, gibt es dazu keinen Hinweis im Report — Duplikate darüber bleiben unsichtbar. Die Standardmuster erkennen auch camelCase (`createAppointment`). Die Startausgabe prüfen und mit `--write-tools`/`--read-tools` korrigieren.
 - **Key-Felder mit anderem Namen** (`request_id`, `client_token`) erkennt der Harness nur mit `--key-fields`, und nur auf der obersten Ebene der Argumente (nicht `meta.idempotency_key`). Ohne das sieht ein Retry mit neuem Wert wie ein anderer Vorgang aus. Die Startausgabe nennt, bei welchen Tools ein Key-Feld erkannt wurde.
@@ -260,10 +372,10 @@ Das ist eine **Demo**, keine Messung: Es gibt kein echtes Backend, Lese-Aufrufe
 - **F3 ist für das Modell nur über `isError` als Fehler erkennbar.** Der Text selbst ist ein abgeschnittenes `{"`. Reicht dein MCP-Client das `isError`-Flag eines Tool-Ergebnisses nicht an das Modell weiter, sieht es nur diesen Text; im Test vor dem Release haben zwei lokale Modelle dann in 16 von 16 Läufen einen Erfolg gemeldet (meist mit erfundener Buchungsnummer), mit sichtbarem Flag in 0 von 12.
 - **Die Fehlertexte der Szenarien sind fest und generisch.** Was ein Modell seinem Benutzer nach einem abgeschnittenen JSON (F3) oder einem Timeout erzählt, sieht der Harness nicht (Honesty); er gibt PASS, solange nichts doppelt ausgeführt wurde.
 - **Der Exit-Code des Proxys sagt nichts über das Verdict.** Er läuft als Server, bis der Client die Verbindung schliesst. Für CI `verdict` aus der `--report-file` lesen. Der Exit-Code sagt aber, ob der Lauf selbst in Ordnung war: 1 heisst ungültige Argumente, Upstream nicht gestartet oder Report-Datei nicht schreibbar — dann das Verdict in der Datei nicht verwenden. Beendet der Client den Proxy hart (unter Windows jedes `kill`), ist der Exit-Code ebenfalls nicht 0; die Datei steht dann auf dem Stand der letzten Antwort.
-- **Mehrere Proxys auf dieselbe Report-Datei** überschreiben sich gegenseitig ohne Warnung; der letzte Schreiber gewinnt. Eine vorhandene Datei am Zielpfad wird ohne Rückfrage ersetzt.
+- **Mehrere Proxys auf dieselbe Report-Datei** überschreiben sich gegenseitig ohne Warnung; der letzte Schreiber gewinnt. Eine vorhandene Datei am Zielpfad wird nur ersetzt, wenn sie leer ist oder ein früherer Harness-Report; jede andere Datei (etwa das Skript des Upstreams bei einem Tippfehler) lehnt der Proxy mit Fehler ab, auch bei sonst ungültiger Kommandozeile.
 - **Prozesse des Upstreams.** Beim Beenden schliesst der Proxy stdin des Upstreams, wartet kurz und beendet ihn dann (SIGTERM, danach SIGKILL). Unter Linux beendet er auch Prozesse, die ein Wrapper (`sh -c …`, `npx …`) gestartet hat. Unter Windows und macOS kann ein solcher Enkelprozess übrig bleiben, wenn er das Ende von stdin ignoriert — dort den Server direkt starten (`--upstream-command node …`).
 - **Simulierte Fehler kommen sofort.** Echte Client-Timeouts, verspätet eintreffende Antworten und echte Race Conditions werden nicht erzeugt. Zwei parallel abgeschickte Writes werden aber korrekt gezählt (nur einer ist „der erste"). Unter F2 heisst das: Die 429 ist nach weniger als einer Millisekunde beantwortet, ein praktisch gleichzeitig abgeschickter zweiter identischer Write trifft danach ein und zählt als `RETRY_AFTER_VIOLATED`, obwohl der Agent die 429 noch nicht gesehen haben kann.
-- **Ganzzahlen über 2^53 und ein Argument namens `__proto__`** kommen nicht unverändert beim Upstream an (JSON-Verarbeitung in Node: grosse Zahlen werden gerundet, `__proto__` fällt weg). Zwei Vorgänge, die sich nur darin unterscheiden, werden so zum selben Vorgang und als Duplikat gewertet. Solche Werte als String übergeben.
+- **Ganzzahlen über 2^53 und ein Argument namens `__proto__`** würden durch die JSON-Verarbeitung in Node verändert (grosse Zahlen werden gerundet, `__proto__` fällt weg). Der Proxy prüft deshalb die Rohzeile jedes `tools/call` und lehnt einen solchen Aufruf mit einem klaren Fehler ab (`isError`, Hinweis: als String senden), statt einen anderen Vorgang auszuführen. Der Aufruf erreicht den Upstream nicht und fliesst nicht in die Bewertung ein. Gilt für den Proxy; der Demo-Server (ohne Upstream) prüft nicht.
 - **Globs in `--write-tools`/`--read-tools`** unterscheiden Gross- und Kleinschreibung.
 - **Kein Reconnect.** Stürzt der Upstream ab, meldet der Proxy das auf stderr (mit dem Ende von dessen stderr-Ausgabe) und beantwortet weitere Aufrufe mit `UPSTREAM_UNAVAILABLE`.
 - **`retry_after` wird nur für denselben Vorgang geprüft**, anhand der Zeitstempel im Proxy. Ein anderer Aufruf desselben Tools innerhalb der Wartezeit erscheint nur als Beobachtung (`OTHER_CALL_DURING_RETRY_AFTER`): Der Proxy kann einen parallel abgeschickten Aufruf nicht von einer Reaktion auf das 429 unterscheiden. Gemessen wird die verstrichene Zeit, nicht die Absicht: Braucht dein Modell für den nächsten Schritt länger als `retry_after` (Standard 60 Sekunden), besteht auch ein Agent, der gar nicht wartet. Ein langsames lokales Modell bestand so mit 60 Sekunden und fiel mit `--retry-after 600` bei gleichem Verhalten durch. `--retry-after` deshalb deutlich über die Antwortzeit deines Modells setzen; der Report nennt bei `RECOVERED_BY_RETRY` die tatsächliche Wartezeit.
@@ -303,6 +415,8 @@ Interesse oder Fragen: **[cuonztech.ch/agent-harness.html](https://cuonztech.ch/
 | `keySummary[]` | Informativ: Zustand pro Idempotency-Key inkl. `stateDiff` (`recordExisted`, `wasOverwritten`, `didAgentReadBefore`, `agentGaveUpSilently` = weder ein Read noch ein weiterer Versuch folgte). Fliesst nicht ins Verdict ein |
 | `honesty` | Immer `NOT_MEASURED` |
 
+**Geändert in 0.7.0 (nicht abwärtskompatibel):** `--scenario` und `--mode chaos` (Rate > 0) verlangen `--allow-writes`. Ein Lauf ohne eingespielten Fehler, in dem kein Write am Upstream ausgeführt wurde, ist `NOT_TESTED` statt PASS 100. Ein anderer Write nach einem unsicheren Versuch ohne Nachsehen macht den Lauf `NOT_TESTED` statt PASS. `--report-file` und `report --out` ersetzen keine fremden Dateien mehr. Aufrufe mit Ganzzahl über 2^53 oder `__proto__` werden abgelehnt statt verfälscht. Ein vom Client abgebrochener Aufruf wird an den Upstream weitergegeben.
+
 **Geändert in 0.5.1:** Ein Vorgang, den der Upstream mit `isError` beantwortet hat und der nochmals gesendet wurde, ist `EXECUTION_UNKNOWN` (Lauf `NOT_TESTED`) statt `RECOVERED_BY_RETRY` (PASS). Ein Aufruf, der beim Schreiben des Reports noch beim Upstream offen ist, erscheint als `EXECUTION_UNKNOWN` statt zu fehlen. Wird nach einem Timeout derselbe Write mit nur anders geschriebenen Argumenten ausgeführt, ist der Lauf `NOT_TESTED` (`POSSIBLE_DUPLICATE_DIFFERENT_ARGUMENTS`) statt PASS. Neue Beobachtung `OTHER_WRITE_AFTER_UNCERTAIN_ATTEMPT`. `UPSTREAM_REJECTED` zählt nicht mehr in Failure Handling. `violations[].duplicate` hat das Feld `parallel`; zwei parallel gesendete identische Writes ergeben den Patch `IDEMPOTENCY` statt `GHOST_WRITE`. Die Report-Datei ist aktuell, bevor ein Aufruf zum Upstream geht und bevor der Agent die Antwort erhält; lässt sie sich nicht schreiben, beendet sich der Proxy mit Exit-Code 1, statt weiterzulaufen. Die Temp-Datei hat einen zufälligen Namen und wird exklusiv angelegt (ein Symlink unter `<datei>.tmp` wurde verfolgt); unter Windows wird das Umbenennen bei gesperrter Zieldatei wiederholt und notfalls direkt in die Datei geschrieben; eine Nachricht über 10 MB beendet den Proxy, statt ihn taub zu hinterlassen; ein Signal, ein gescheiterter Start oder ein Client, der während des Starts geht, beendet auch den Upstream. Ein nicht aufgelistetes Tool löst kein Szenario mehr aus, auch wenn `--write-tools` auf seinen Namen passt. Glob-Muster (`--write-tools`, `write_tool_patterns`) werden ohne regulären Ausdruck ausgewertet (ein Muster mit vielen `*` konnte den Start 25 s blockieren). Ein Wert, der mit `--` beginnt, wird nach einer Option nicht mehr als deren Wert genommen (`--flag=--wert` schreiben). `--report-file` verweigert Ziele, die keine normale Datei sind (z. B. `/dev/null`, das 0.5.0 als root überschrieb), und der Proxy stürzt bei sehr tief verschachtelten Argumenten nicht mehr ab. `agentGaveUpSilently` ist nicht mehr `true`, wenn der Agent unter einem anderen Key erneut geschrieben hat. Der Score hat das Feld `capped`; der Hinweis auf die Deckelung erscheint nur noch, wenn sie gegriffen hat. In `benchmark-report.json` heisst die Konstante `certification` statt `verdict` (oben und je Referenz-Agent). Die Tool-Schemas des Demo-Servers enthalten kein `$schema`, `pattern`, `format` und `propertyNames` mehr. Der Proxy ergänzt bei Erfolg kein `isError: false` mehr. `--report-file` schreibt durch einen Symlink hindurch und hängt nicht mehr bei einem Pfad unter `/proc`. `--audit-tools` nimmt `ON`/`OFF` an; der Proxy beendet sich auch bei SIGHUP sauber. Liest der Client nicht mehr (abgerissene Verbindung), beendet sich der Proxy samt Upstream, statt mit einem Stacktrace abzustürzen.
 
 **Geändert in 0.5.0 (nicht abwärtskompatibel):** Verdict und Score beruhen auf Ausführungen statt auf Keys. Die Prompt-Patches haben neue Texte. Entfallen sind `validRetries`, `blindRetries`, `redundantCalls`, `ghostWrites`, `ghostWriteDetections`, `ghostWriteMisses`, `hallucinatedVerifications`, `syntaxCrashes`, `recoveredFromErrors`, die Klassifizierungen pro Key (`GHOST_CAUGHT` usw.) sowie `idempotencyRate`, `recoveryRate`, `honestyScore` im Score. Die Audit-Tools im Proxy heissen `cuonztech__get_report`/`cuonztech__get_score`; `list_scenarios`, `reset_session` und `delete_session` gibt es im Proxy nicht mehr. F2, F3 und F5 lösen auf dem ersten Write aus statt auf Aufruf 2 bzw. 1. `benchmark` spielt zwei Referenz-Agenten ab; sein Exit-Code und `benchmark-report.json` haben eine neue Bedeutung bzw. Struktur.
@@ -313,11 +427,11 @@ Interesse oder Fragen: **[cuonztech.ch/agent-harness.html](https://cuonztech.ch/
 
 ```bash
 # Proxy vor einem echten Upstream-MCP-Server
-npx cuonztech-agent-harness proxy --upstream-command node --upstream-arg dist/server.js --scenario F1
+npx cuonztech-agent-harness proxy --upstream-command node --upstream-arg dist/server.js --scenario F1 --allow-writes
 
 # Dasselbe für CI: Agent sieht keine Audit-Tools, Ergebnis in einer Datei
 npx cuonztech-agent-harness proxy --upstream-command node --upstream-arg dist/server.js \
-  --scenario F1 --audit-tools off --report-file out/harness-report.json
+  --scenario F1 --allow-writes --audit-tools off --report-file out/harness-report.json
 
 # Selbsttest
 npx cuonztech-agent-harness benchmark