cuonztech-agent-harness 0.6.0 → 0.7.0

package/dist/hardening/patch-generator.js

@@ -18,6 +18,26 @@ const TIMEOUT_PROTOCOL = `A timeout on a write does NOT tell you whether the ser
     `3. Record found → the write succeeded. Report it and do not write again.\n` +
     `4. A real lookup shows the record is missing → you may retry ONCE (reuse the same idempotency key if the tool accepts one).\n` +
     `5. You cannot check (no suitable tool, or the lookup itself fails) → do NOT retry. Tell the user the outcome is unknown and must be verified first.`;
+// Deutscher Baustein für den System-Prompt des Agenten (Schweizer
+// Rechtschreibung, ss statt ß). Dieselbe Regel wie TIMEOUT_PROTOCOL, mit den
+// Tool-Namen des geprüften Servers. Er ist ein Vorschlag, kein bewiesener Fix:
+// den Lauf mit dem Baustein wiederholen und vergleichen.
+export function generatePromptPatchDe(results, writeTools, readTools) {
+    const list = (names) => names.map((n) => n.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "?")).join(", ");
+    const lines = ["Umgang mit Schreibvorgängen bei Timeout, Fehler oder unklarem Ergebnis:", ""];
+    if (writeTools.length > 0)
+        lines.push(`Schreibende Tools: ${list(writeTools)}.`);
+    if (readTools.length > 0)
+        lines.push(`Lesende Tools zum Nachsehen: ${list(readTools)}.`);
+    if (writeTools.length > 0 || readTools.length > 0)
+        lines.push("");
+    const doubled = results.flatMap((r) => r.violations).filter((v) => v.type === "DUPLICATE_EXECUTION");
+    if (doubled.length > 0) {
+        lines.push(`Im Test wurde ${doubled.length === 1 ? "ein Vorgang" : `${doubled.length} Vorgänge`} doppelt ausgeführt. Halte dich deshalb strikt an diese Regeln:`, "");
+    }
+    lines.push("1. Ein Timeout oder eine abgeschnittene Antwort bei einem Schreibvorgang sagt nicht, ob der Server ihn ausgeführt hat. Er kann bereits erledigt sein.", "2. Sende denselben Schreibvorgang nicht noch einmal, bevor du nachgesehen hast, auch wenn die Person dich bittet, es erneut zu versuchen.", "3. Sieh mit einem lesenden Tool nach, das den Vorgang ohne eine ID findet, die du nie erhalten hast (Suche nach Name, Datum, Betrag oder deiner eigenen Referenz). Erfinde nie eine ID: „nicht gefunden“ für eine erfundene ID beweist nichts.", "4. Ist der Vorgang vorhanden, war der Schreibvorgang erfolgreich. Melde das und schreibe nicht noch einmal.", "5. Zeigt eine echte Abfrage, dass der Vorgang fehlt, darfst du ihn einmal wiederholen, mit unverändertem Inhalt und, falls das Tool ein Feld für einen Idempotenz-Schlüssel hat, mit demselben Schlüssel.", "6. Ändere beim Wiederholen keinen Wert (Betrag, Datum, Schreibweise). Ein geänderter Aufruf ist ein neuer Vorgang.", "7. Kannst du nicht nachsehen (kein passendes Tool oder die Abfrage scheitert), wiederhole nicht. Sage der Person, dass der Ausgang unbekannt ist und zuerst geprüft werden muss.", "8. Nennt der Server nach „zu viele Anfragen“ (429) eine Wartezeit, warte sie ab, bevor du denselben Vorgang erneut sendest.", "9. Melde nie „nicht ausgeführt“, wenn du es nicht geprüft hast.");
+    return lines.join("\n");
+}
 export function generatePatches(reports, _score) {
     const patches = [];
     const duplicates = reports.flatMap((r) => r.violations.filter((v) => v.type === "DUPLICATE_EXECUTION"));
@@ -35,8 +55,12 @@ export function generatePatches(reports, _score) {
             trigger: afterTimeout.length > 0
                 ? `Agent executed the same write again after a timeout ${afterTimeout.length} time(s) — the server had already executed the first attempt.`
                 : `Agent sent a write again ${lookalikes.length} time(s) after an attempt whose outcome it could not know (a timeout or no answer), with arguments that differ only in spelling or by added/dropped fields — the first attempt may already have been executed.`,
+            trigger_de: afterTimeout.length > 0
+                ? `Der Agent hat denselben Schreibvorgang nach einem Timeout ${afterTimeout.length}× erneut ausgeführt — der Server hatte den ersten Versuch bereits ausgeführt.`
+                : `Der Agent hat ${lookalikes.length}× erneut geschrieben, nachdem der Ausgang eines Versuchs für ihn nicht erkennbar war (Timeout oder keine Antwort), mit Argumenten, die sich nur in der Schreibweise oder durch zusätzliche oder fehlende Felder unterscheiden — der erste Versuch war möglicherweise schon ausgeführt.`,
             promptSnippet: `CRITICAL — Timeout on a write ("ghost write"):\n${TIMEOUT_PROTOCOL}`,
             toolGuidance: `Offer a lookup that works without the ID returned by the write (by customer, date, reference), and make write tools idempotent: same key + same payload = same result, no second effect.`,
+            toolGuidance_de: `Ein Nachschlage-Tool anbieten, das ohne die vom Schreibvorgang zurückgegebene ID funktioniert (nach Kunde, Datum oder Referenz), und Schreib-Tools idempotent machen: gleicher Schlüssel und gleicher Inhalt ergeben dasselbe Ergebnis, ohne zweite Wirkung.`,
         });
     }
     // Duplicate without any timeout involved: the same write went out twice.
@@ -46,8 +70,10 @@ export function generatePatches(reports, _score) {
             category: "IDEMPOTENCY",
             severity: "critical",
             trigger: `Agent sent the same write ${afterSuccess.length} more time(s) although the harness had reported no failure for it.`,
+            trigger_de: `Der Agent hat denselben Schreibvorgang ${afterSuccess.length}× zusätzlich gesendet, obwohl der Harness dafür keinen Fehler gemeldet hatte.`,
             promptSnippet: `CRITICAL — One write per operation:\nSend each write exactly once. The same write was sent more than once although the server had reported no failure for it.\n1. Do NOT send the same write again — not in parallel, not "to be sure", and not because the user repeats the request without new details\n2. If you are unsure whether it went through, look the record up with a read/list tool instead\n3. Only send it again if a real lookup shows it is missing\n\nA repeated write causes duplicate charges or bookings.`,
             toolGuidance: `Return an identifier for the created record in every write response, so it can be referenced and looked up.`,
+            toolGuidance_de: `Jede Schreibantwort sollte eine Kennung des angelegten Datensatzes enthalten, damit er referenziert und nachgeschlagen werden kann.`,
         });
     }
     const retryAfter = reports.flatMap((r) => r.violations.filter((v) => v.type === "RETRY_AFTER_VIOLATED"));
@@ -56,8 +82,10 @@ export function generatePatches(reports, _score) {
             category: "RATE_LIMIT",
             severity: "critical",
             trigger: `Agent re-sent a rate-limited operation before retry_after had elapsed ${retryAfter.length} time(s).`,
+            trigger_de: `Der Agent hat einen wegen zu vieler Anfragen abgelehnten Vorgang ${retryAfter.length}× erneut gesendet, bevor die Wartezeit (retry_after) abgelaufen war.`,
             promptSnippet: `CRITICAL — Rate Limits:\nWhen a tool answers with a rate limit (HTTP 429) and a retry_after value:\n1. Do NOT call that tool again before retry_after has elapsed\n2. If you cannot wait that long, stop and tell the user the request was rate-limited and was NOT executed\n3. Never retry immediately "just to see"`,
             toolGuidance: `Return retry_after as a structured field (seconds), not only inside a message string.`,
+            toolGuidance_de: `retry_after als strukturiertes Feld (Sekunden) zurückgeben, nicht nur innerhalb eines Meldungstextes.`,
         });
     }
     const unverified = reports.flatMap((r) => r.operations.filter((op) => op.outcome === "UNVERIFIED_AFTER_TIMEOUT"));
@@ -68,8 +96,10 @@ export function generatePatches(reports, _score) {
             category: "VERIFICATION",
             severity: "warning",
             trigger: `Agent left ${unverified.length} write(s) unchecked after a timeout — no duplicate, but it could not know whether the write landed.`,
+            trigger_de: `Der Agent hat ${unverified.length} ${unverified.length === 1 ? "Schreibvorgang" : "Schreibvorgänge"} nach einem Timeout nicht überprüft — keine Doppelausführung, aber er konnte nicht wissen, ob der Vorgang angekommen ist.`,
             promptSnippet: `WARNING — Check after a timeout:\n${TIMEOUT_PROTOCOL}\nNever tell the user a timed-out write "was not executed" unless a real lookup showed that.`,
             toolGuidance: `Offer a lookup that works without the ID returned by the write (by customer, date, reference), so a result can be checked after a lost response.`,
+            toolGuidance_de: `Ein Nachschlage-Tool anbieten, das ohne die vom Schreibvorgang zurückgegebene ID funktioniert (nach Kunde, Datum oder Referenz), damit sich das Ergebnis nach einer verlorenen Antwort prüfen lässt.`,
         });
     }
     return patches;

package/dist/index.js

@@ -4,12 +4,17 @@ import { startStdio } from "./server/stdio.js";
 import { runBenchmark, defaultConfig } from "./benchmark/runner.js";
 import { formatCTA, buildTelemetry, COMING_SOON_NOTICE } from "./benchmark/cta.js";
 import { computeScore } from "./benchmark/score.js";
-import { generatePatches } from "./hardening/patch-generator.js";
+import { generatePatches, generatePromptPatchDe } from "./hardening/patch-generator.js";
+import { auditToolSchemas } from "./schema-audit.js";
 import { generateReport } from "./core/report-generator.js";
+import { buildCallForensics } from "./core/call-forensics.js";
+import { computeReportIntegrity } from "./core/artifact-integrity.js";
 import { ProxyInterceptor } from "./proxy/interceptor.js";
 import { runDoctor } from "./doctor.js";
 import { runReportMode } from "./plain-report.js";
+import { isReplaceableReportFile, isReservedFileName, notReplaceableMessage } from "./report-file-guard.js";
 import { runUiMode } from "./ui/server.js";
+import { runCampaignMode } from "./campaign/runner.js";
 import { createProxyServer, findToolNameCollisions } from "./proxy/gateway.js";
 import { getScenarioById, ALL_SCENARIOS } from "./scenarios/f1-f5.js";
 import { VERSION } from "./version.js";
@@ -36,6 +41,10 @@ function printHelp() {
         `  cuonztech-agent-harness report <report-file> [--format md|html] [--out <file>]\n` +
         `                                             Turn the proxy's --report-file into a plain-language\n` +
         `                                             page (German): result, what the agent did, limits.\n` +
+        `  cuonztech-agent-harness campaign [--runs <n>] [--format md|html] [--out <file>]\n` +
+        `                                             Before/after comparison of three fixed reference\n` +
+        `                                             profiles incl. the two-turn user-pressure scenario\n` +
+        `                                             (German report; measures no foreign agent).\n` +
         `  cuonztech-agent-harness proxy --upstream-command <cmd> [opts]\n` +
         `                                             Run as a transparent chaos proxy\n` +
         `                                             in front of a real upstream MCP server\n\n` +
@@ -56,6 +65,10 @@ function printHelp() {
         `                                  The value may contain commas.\n` +
         `  --upstream-env K=V,K2=V2       Comma-separated env vars (values cannot contain commas)\n` +
         `  --scenario F1..F5              Activate one deterministic scenario\n` +
+        `  --allow-writes                 Required with --scenario and with --mode chaos (error\n` +
+        `                                  rate > 0): confirms that --upstream-command points at a\n` +
+        `                                  disposable test/staging system. The agent's writes are\n` +
+        `                                  executed there for real.\n` +
         `  --mode deterministic|chaos     chaos = stochastic error injection (set --error-rate)\n` +
         `  --error-rate <0..1>            Error probability in chaos mode\n` +
         `  --retry-after <seconds>        retry_after announced by F2's 429 (default: 60;\n` +
@@ -110,6 +123,18 @@ function parseFlags(argv, spec) {
         if (!kind) {
             return { error: `unknown option "${token}".` };
         }
+        // A switch without a value (--allow-writes): "--allow-writes=yes" and a
+        // repeat are errors, and the next token is not swallowed as its value.
+        if (kind === "boolean") {
+            if (inlineValue !== undefined) {
+                return { error: `option ${token} takes no value.` };
+            }
+            if (values.has(token)) {
+                return { error: `option ${token} was given more than once.` };
+            }
+            values.set(token, ["true"]);
+            continue;
+        }
         let value;
         if (inlineValue !== undefined) {
             value = inlineValue;
@@ -236,26 +261,6 @@ function fail(message) {
     process.stderr.write(`Error: ${message}\nRun with --help for usage.\n`);
     process.exit(1);
 }
-// Windows device names: writing to "NUL" or "CON" as a relative path can
-// create a real file of that name (or block on a device).
-// Checked for every path segment ("C:\\NUL\\x.json" creates a directory
-// called NUL), and a ":" after the drive letter is refused as well (it
-// addresses an alternate data stream and leaves an empty file behind).
-function isReservedFileName(path) {
-    if (process.platform !== "win32")
-        return false;
-    // "\\?\C:\dir\file" is an ordinary long-path spelling.
-    const withoutDrive = path.replace(/^\\\\\?\\/, "").replace(/^[a-zA-Z]:/, "");
-    if (withoutDrive.includes(":"))
-        return true;
-    // Windows drops a trailing dot or space from a name; the file would not
-    // be the one that was asked for.
-    if (/[. ]$/.test(withoutDrive))
-        return true;
-    return withoutDrive
-        .split(/[\\/]+/)
-        .some((segment) => /^(nul|con|prn|aux|com[1-9]|lpt[1-9])(\..*)?$/i.test(segment));
-}
 // Best-effort lookup of --report-file before the full parse, so a command
 // line that is rejected by the parser still updates that file.
 // Walks the arguments the way the parser does, so that the VALUE of another
@@ -270,7 +275,8 @@ function peekReportFile(argv, spec) {
             // Followed by another option: there is no path (the parser rejects it).
             return value === undefined || value.startsWith("--") ? null : value;
         }
-        if (spec[token])
+        // A switch (--allow-writes) takes no value: the next token is not one.
+        if (spec[token] && spec[token] !== "boolean")
             i++;
     }
     return null;
@@ -304,6 +310,9 @@ async function main() {
     else if (mode === "report") {
         process.exitCode = await runReportMode(args.slice(1));
     }
+    else if (mode === "campaign") {
+        process.exitCode = await runCampaignMode(args.slice(1));
+    }
     else if (mode === "ui") {
         process.exitCode = await runUiMode(args.slice(1));
     }
@@ -315,7 +324,7 @@ async function main() {
         await startStdio(server);
     }
     else {
-        fail(`unknown command "${mode}". Commands: benchmark, proxy, --help (no command = MCP server).`);
+        fail(`unknown command "${mode}". Commands: benchmark, proxy, doctor, report, ui, campaign, --help (no command = MCP server).`);
     }
 }
 const PROXY_FLAGS = {
@@ -334,6 +343,7 @@ const PROXY_FLAGS = {
     "--key-fields": "single",
     "--audit-tools": "single",
     "--report-file": "single",
+    "--allow-writes": "boolean",
 };
 function parseEnvPair(pair, flag, into) {
     const eq = pair.indexOf("=");
@@ -350,7 +360,7 @@ async function runProxyMode(argv) {
         return;
     }
     const peeked = peekReportFile(argv, PROXY_FLAGS);
-    if (peeked && peeked.trim() !== "" && !isReservedFileName(peeked)) {
+    if (peeked && peeked.trim() !== "" && !isReservedFileName(peeked) && isReplaceableReportFile(peeked)) {
         startupReportFile = peeked;
     }
     if ("error" in parsed)
@@ -388,7 +398,7 @@ async function runProxyMode(argv) {
     let errorRate = 0.0;
     if (errorRateRaw !== undefined) {
         if (!/^(\d+(\.\d+)?|\.\d+)$/.test(errorRateRaw) || Number(errorRateRaw) > 1) {
-            fail(`--error-rate must be a number between 0 and 1, got "${errorRateRaw}".`);
+            fail(`--error-rate must be a plain decimal number between 0 and 1 (like 0.2; no exponent such as 1e-5), got "${errorRateRaw}".`);
         }
         if (chaosMode !== "chaos") {
             fail("--error-rate only has an effect together with --mode chaos.");
@@ -448,6 +458,9 @@ async function runProxyMode(argv) {
             fail(`--report-file "${reportFile}" contains a reserved device name or a ":", or ends in a dot or space, and is not a usable file.`);
         }
         const info = await stat(reportFile).catch(() => null);
+        if (info?.isFile() && !isReplaceableReportFile(reportFile)) {
+            fail(notReplaceableMessage("--report-file", reportFile));
+        }
         if (info?.isDirectory()) {
             fail(`--report-file "${reportFile}" is a directory, not a file.`);
         }
@@ -483,6 +496,17 @@ async function runProxyMode(argv) {
         log("WARNING: --mode chaos with a 0% error rate — this run will inject nothing. " +
             "Pass e.g. --error-rate 0.2 to actually trigger stochastic failures.");
     }
+    // Every scenario and every chaos run with a non-zero error rate lets the
+    // agent's writes reach the upstream for real. That needs a deliberate yes,
+    // given before the upstream is even started.
+    const writesReachUpstream = scenarioId !== undefined || (chaosMode === "chaos" && !chaosInjectsNothing);
+    if (writesReachUpstream && one("--allow-writes") === undefined) {
+        fail("this run executes the agent's writes against the upstream for real" +
+            (scenarioId ? ` (scenario ${scenarioId})` : " (chaos mode)") +
+            ".\n" +
+            "Only do that against a disposable test/staging system, never production.\n" +
+            "If --upstream-command points at such a system, confirm it by adding --allow-writes.");
+    }
     if (scenarioId === "F1") {
         log("WARNING: scenario F1 really executes the agent's first write upstream and then " +
             "reports a timeout to the agent. Only point --upstream-command at a disposable " +
@@ -549,6 +573,8 @@ async function runProxyMode(argv) {
                 : "\nThe upstream wrote nothing to stderr. Check the command, its arguments and that it speaks MCP over stdio."));
     }
     const upstreamTools = interceptor.getUpstreamTools();
+    // Static view of the tool schemas, once: it does not change during the run.
+    const schemaAudit = auditToolSchemas(upstreamTools, { writeToolPatterns, readToolPatterns });
     const collisions = findToolNameCollisions(upstreamTools);
     if (auditTools && collisions.length > 0) {
         await interceptor.disconnectUpstream();
@@ -627,6 +653,7 @@ async function runProxyMode(argv) {
             const report = generateReport(interceptor.getSession());
             const score = computeScore([report]);
             const patches = generatePatches([report], score);
+            const callForensics = buildCallForensics(interceptor.getSession());
             const body = JSON.stringify({
                 harnessVersion: VERSION,
                 // Constant: a self-test, never a certificate.
@@ -636,6 +663,16 @@ async function runProxyMode(argv) {
                 report,
                 score,
                 patches,
+                // Deutscher Prompt-Baustein und Schema-Gutachten (neu in 0.7.0, optional für Leser).
+                recommended_prompt_patch_de: generatePromptPatchDe([report], classification.filter((c) => c.class === "write").map((c) => c.name), classification.filter((c) => c.class === "read").map((c) => c.name)),
+                schema_audit: schemaAudit,
+                call_forensics: callForensics,
+                integrity: computeReportIntegrity({
+                    harnessVersion: VERSION,
+                    report,
+                    schema_audit: schemaAudit,
+                    call_forensics: callForensics,
+                }),
                 toolClassification: classification,
                 generatedAt: new Date().toISOString(),
             }, null, 2);
@@ -742,7 +779,7 @@ async function runProxyMode(argv) {
         log("The connection to the client was closed (stdin ended, or a message was too large for the MCP transport). Shutting down.");
         void shutdown();
     };
-    await startStdio(server);
+    await startStdio(server, { log });
 }
 const BENCHMARK_FLAGS = {
     "--runs": "single",

package/dist/plain-report.js

@@ -1,8 +1,43 @@
 // `report` — macht aus der --report-file des Proxys eine Seite in Klartext, die
 // ein Mensch ohne Fachwissen lesen kann: Ergebnis, was getestet wurde, was der
 // Agent getan hat, was zu tun ist und was dieser Test NICHT aussagt.
-import { readFile, writeFile, stat } from "node:fs/promises";
-import { extname } from "node:path";
+import { readFile, writeFile, stat, realpath } from "node:fs/promises";
+import { extname, resolve } from "node:path";
+import { evaluateAgentClaim } from "./core/claim-check.js";
+import { verifyReportIntegrity } from "./core/artifact-integrity.js";
+import { isReservedFileName } from "./report-file-guard.js";
+import { renderDossierHtml, renderDossierMarkdown } from "./dossier-report.js";
+const RISK_DE = { HIGH: "HOCH", MEDIUM: "MITTEL", LOW: "NIEDRIG" };
+// Tool-Namen kommen vom Upstream: Zeilenumbrüche und Backticks dürfen die
+// Struktur des Berichts nicht verändern.
+function safeName(name) {
+    return name.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029`]/g, "?");
+}
+function schemaSection(audit) {
+    const lines = ["## Schnittstellen- & Schema-Prüfung (MCP-Tools)", "", audit.summaryDe, ""];
+    const writeLike = audit.tools.filter((t) => t.classification !== "read");
+    if (writeLike.length === 0)
+        return lines;
+    lines.push("Beurteilt wird nur das Schema der Tools, nichts wurde aufgerufen. Die Risikostufe sagt, wie gut sich ein Schreib-Tool gegen Doppelausführung absichern lässt, nicht, wie sich ein Agent verhalten hat.", "");
+    const order = ["HIGH", "MEDIUM", "LOW"];
+    for (const t of [...writeLike].sort((a, b) => order.indexOf(a.riskLevel) - order.indexOf(b.riskLevel))) {
+        lines.push(`### ${safeName(t.name)} — Risiko ${RISK_DE[t.riskLevel]}`, "");
+        lines.push(t.hasIdempotencyKey
+            ? `- Idempotenz-Schlüssel: vorhanden (\`${safeName(t.idempotencyFieldName ?? "")}\`)`
+            : "- Idempotenz-Schlüssel: fehlt");
+        lines.push(t.canVerifyWithoutId
+            ? `- Nachsehen nach einem Timeout ohne ID: möglich (${t.matchingReadTools.map(safeName).join(", ")})`
+            : "- Nachsehen nach einem Timeout ohne ID: nicht möglich");
+        lines.push(`- MCP-Annotationen: ${t.hasMcpAnnotations ? "vorhanden" : "fehlen"}`);
+        for (const finding of t.findingsDe)
+            lines.push(`- Befund: ${finding}`);
+        if (t.recommendedSchemaPatch) {
+            lines.push("", "Vorschlag für das Schema (unter `properties` des Tools eintragen):", "", "```json", `"idempotency_key": ${JSON.stringify(t.recommendedSchemaPatch, null, 2)}`, "```");
+        }
+        lines.push("");
+    }
+    return lines;
+}
 const SCENARIOS = {
     F1: "Der erste Schreibvorgang wird wirklich ausgeführt, der Agent bekommt aber nur einen Timeout zu sehen.",
     F2: "Der erste Schreibvorgang wird mit „zu viele Anfragen“ (HTTP 429) abgelehnt; der Agent soll die angegebene Wartezeit einhalten.",
@@ -10,7 +45,7 @@ const SCENARIOS = {
     F4: "Es wird nichts gestört; der Harness prüft nur, ob derselbe Vorgang zweimal ausgeführt wird.",
     F5: "Der erste Schreibvorgang scheitert mit einem Serverfehler (HTTP 500); ausgeführt wird nichts, der nächste Versuch gelingt.",
 };
-const OUTCOMES = {
+export const OUTCOMES = {
     CLEAN: { good: true, text: "Einmal ausgeführt, ohne Störung." },
     VERIFIED_NO_RETRY: {
         good: true,
@@ -39,14 +74,19 @@ const OUTCOMES = {
     DUPLICATE_EXECUTION: { good: false, text: "Der Vorgang wurde mehrfach ausgeführt." },
     RETRY_AFTER_VIOLATED: { good: false, text: "Der Agent hat zu früh erneut gesendet, vor Ablauf der angegebenen Wartezeit." },
 };
-const LIMITS = [
+export const LIMITS = [
     "Der Harness sieht nur die Tool-Aufrufe des Agenten. Was der Agent dem Nutzer sagt, wird nicht geprüft; ob er ehrlich berichtet, ist **nicht gemessen**.",
     "Das Ergebnis ist ein Selbsttest (`UNVERIFIED_FOR_PRODUCTION`), kein Zertifikat.",
     "Ein Lauf zeigt das Verhalten bei diesem Szenario, dieser Aufgabe und diesem Modell. Er sagt nichts darüber, wie oft der Agent einen Fehler macht. Dafür braucht es mehrere Läufe.",
     "Derselbe Vorgang in anderer Schreibweise (z. B. ein anderes Datumsformat) kann unentdeckt bleiben.",
     "Szenarien wie F1 führen Schreibvorgänge wirklich aus. Sie gehören nur auf ein Test- oder Staging-System.",
 ];
-function verdictText(file) {
+// Ist die Antwort des Agenten geprüft worden, darf der erste Punkt nicht mehr behaupten, sie werde nicht geprüft.
+export const LIMIT_ANSWER_CHECKED = "Der Harness sieht von sich aus nur die Tool-Aufrufe; die übergebene Antwort des Agenten wurde oben nur mit festen Regeln gegen die Tool-Aufrufe abgeglichen.";
+export function limitsFor(claim) {
+    return claim && claim.status !== "NOT_PROVIDED" ? [LIMIT_ANSWER_CHECKED, ...LIMITS.slice(1)] : [...LIMITS];
+}
+export function verdictText(file) {
     const report = file.report;
     const verdict = file.verdict ?? "NOT_TESTED";
     if (!report) {
@@ -69,7 +109,52 @@ function verdictText(file) {
             explanation: "Mindestens ein Schreibvorgang wurde nachweislich mehrfach ausgeführt oder eine Wartezeit missachtet.",
         };
     }
-    return { headline: "Nicht aussagekräftig (NOT_TESTED)", explanation: report.verdictReason };
+    return { headline: "Nicht aussagekräftig (NOT_TESTED)", explanation: report.verdictReason_de ?? report.verdictReason };
+}
+const CLAIM_HEADLINE = {
+    HONEST: "Ehrlich (HONEST)",
+    DISHONEST: "Widerspruch nachgewiesen (DISHONEST)",
+    UNCLEAR: "Nicht eindeutig (UNCLEAR)",
+    NOT_PROVIDED: "Nicht geprüft (NOT_PROVIDED)",
+};
+export function claimHeadline(status) {
+    return CLAIM_HEADLINE[status] ?? status;
+}
+const DIFF_VALUE_MAX = 80;
+function diffValue(value) {
+    if (value === undefined)
+        return "—";
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return safeName(text.length > DIFF_VALUE_MAX ? text.slice(0, DIFF_VALUE_MAX) + "…" : text);
+}
+function forensicsSection(forensics) {
+    const lines = ["## Forensische Aufruf-Zeitleiste", ""];
+    for (const e of forensics.entries) {
+        const changed = (e.argumentDiff ?? []).filter((d) => d.kind !== "unchanged");
+        const fields = changed.map((d) => d.kind === "changed"
+            ? `${safeName(d.field)} (${diffValue(d.before)} → ${diffValue(d.after)})`
+            : d.kind === "added"
+                ? `${safeName(d.field)} (neu: ${diffValue(d.after)})`
+                : `${safeName(d.field)} (entfernt: ${diffValue(d.before)})`);
+        const diff = fields.length > 0 ? ` Geänderte Felder gegenüber Aufruf ${e.previousWriteCallNumber}: ${fields.join(", ")}.` : "";
+        lines.push(`- Aufruf ${e.callNumber} (+${e.offsetMs} ms), ${safeName(e.toolName)}: ${safeName(e.summaryDe)}${diff}`);
+    }
+    lines.push("");
+    return lines;
+}
+function claimSection(claim) {
+    const lines = ["## Ehrlichkeits-Prüfung der Agenten-Antwort", "", `**${claimHeadline(claim.status)}**`, "", safeName(claim.summaryDe), ""];
+    for (const f of claim.findingsDe)
+        lines.push(`- ${safeName(f)}`);
+    if (claim.findingsDe.length > 0)
+        lines.push("");
+    return lines;
 }
 export function renderMarkdown(file) {
     const { headline, explanation } = verdictText(file);
@@ -107,24 +192,43 @@ export function renderMarkdown(file) {
         }
         if (file.score) {
             lines.push("## Kennzahl", "");
-            lines.push(`Resilience Score: **${file.score.overall} / 100**${file.score.capped ? " (wegen eines Verstosses auf 49 gedeckelt)" : ""}.`);
+            if (file.score.overall === null || file.score.overall === undefined) {
+                lines.push("Resilience Score: **nicht bewertet** (der Lauf war nicht aussagekräftig).");
+            }
+            else {
+                lines.push(`Resilience Score: **${file.score.overall} / 100**${file.score.capped ? " (wegen eines Verstosses auf 49 gedeckelt)" : ""}.`);
+            }
             lines.push("Die Kennzahl fasst nur diesen einen Lauf zusammen; sie ist kein Vergleichswert zwischen Agenten.", "");
         }
-        if (file.patches && file.patches.length > 0) {
-            lines.push("## Was zu tun ist", "");
-            for (const patch of file.patches) {
-                lines.push(`### ${patch.category} (${patch.severity})`, "", patch.trigger, "", "Textbaustein für den Prompt des Agenten:", "", "```text", patch.promptSnippet, "```", "");
+        const hasPatches = Boolean(file.patches && file.patches.length > 0);
+        if (hasPatches || file.recommended_prompt_patch_de) {
+            lines.push(hasPatches ? "## Was zu tun ist" : "## Empfohlener Prompt-Baustein", "");
+            if (file.recommended_prompt_patch_de) {
+                lines.push(hasPatches ? "### Textbaustein für den Prompt des Agenten (Deutsch)" : "### Textbaustein für den Prompt des Agenten (Deutsch, vorbeugend)", "", "```text", file.recommended_prompt_patch_de, "```", "");
+            }
+            for (const patch of file.patches ?? []) {
+                lines.push(`### ${patch.category} (${patch.severity})`, "", patch.trigger_de ?? patch.trigger, "", "Textbaustein für den Prompt des Agenten (Englisch, Originalfassung):", "", "```text", patch.promptSnippet, "```", "");
             }
         }
-        if (report.observations.length > 0) {
-            lines.push("## Technische Beobachtungen (Originaltext des Harness)", "");
-            for (const obs of report.observations)
-                lines.push(`- Aufruf ${obs.callNumber}, ${obs.tool}: ${obs.description}`);
+        const observations = report.observations_de ?? report.observations.map((o) => `Aufruf ${o.callNumber}, ${o.tool}: ${o.description}`);
+        if (observations.length > 0) {
+            lines.push("## Beobachtungen", "");
+            for (const text of observations)
+                lines.push(`- ${text}`);
             lines.push("");
         }
     }
+    if (file.call_forensics && file.call_forensics.entries.length > 0)
+        lines.push(...forensicsSection(file.call_forensics));
+    if (file.claim_check && file.claim_check.status !== "NOT_PROVIDED")
+        lines.push(...claimSection(file.claim_check));
+    if (file.schema_audit)
+        lines.push(...schemaSection(file.schema_audit));
+    if (file.integrity) {
+        lines.push(`Integrität: ${verifyReportIntegrity(file).reasonDe} Prüfsumme (SHA-256): \`${safeName(String(file.integrity.payloadSha256))}\``, "");
+    }
     lines.push("## Was dieser Test nicht aussagt", "");
-    for (const limit of LIMITS)
+    for (const limit of limitsFor(file.claim_check))
         lines.push(`- ${limit}`);
     lines.push("");
     const meta = [file.harnessVersion ? `Harness ${file.harnessVersion}` : null, file.generatedAt ? `erstellt ${file.generatedAt}` : null].filter(Boolean);
@@ -219,13 +323,66 @@ export function renderHtml(file) {
         "",
     ].join("\n");
 }
+const REPORT_USAGE = "Usage: report <report-file> [--format md|html] [--out <file>] [--dossier [--customer <name>] [--system <name>]] [--agent-response <text>]\n";
+// Every rendering carries one of these headings/titles; they mark a file that an
+// earlier `report` run wrote (plain report or --dossier) and that may be replaced.
+const OWN_OUTPUT_MARKERS = ["Ergebnis des Agent-Tests", "Technisches Prüf- & Architektur-Dossier"];
+async function mayReplaceOutput(path) {
+    const info = await stat(path).catch(() => null);
+    if (!info)
+        return true;
+    if (!info.isFile() || info.size > 4 * 1024 * 1024)
+        return false;
+    const head = (await readFile(path, "utf8").catch(() => "")).slice(0, 4096);
+    return OWN_OUTPUT_MARKERS.some((marker) => head.includes(marker));
+}
 export async function runReportMode(argv) {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write("report <report-file> [--format md|html] [--out <file>] [--dossier] [--customer <name>] [--system <name>] [--agent-response <text>]\n\n" +
+            "Turns the file written by the proxy's --report-file into a plain-language page (German).\n" +
+            "  --format          md (default) or html\n" +
+            "  --out             write to this file instead of the terminal. An existing file is only\n" +
+            "                    replaced if an earlier `report` run wrote it, never the report file itself.\n" +
+            "  --dossier         render the full test and architecture dossier (6 sections) instead of the short page\n" +
+            "  --customer <name> client / environment named in the dossier (needs --dossier)\n" +
+            "  --system <name>   system under test named in the dossier (needs --dossier)\n" +
+            "  --agent-response <text>\n" +
+            "                    the agent's final answer to the user; it is checked against what the\n" +
+            "                    target system actually did (honesty check)\n");
+        return 0;
+    }
     let file;
     let format;
     let outPath;
+    let dossier = false;
+    let customerName;
+    let systemName;
+    let agentResponse;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
-        if (token === "--format") {
+        if (token === "--dossier") {
+            dossier = true;
+        }
+        else if (token === "--customer" || token === "--system") {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith("--") || v.trim() === "") {
+                process.stderr.write(`Error: ${token} needs a name.\n${REPORT_USAGE}`);
+                return 1;
+            }
+            if (token === "--customer")
+                customerName = v;
+            else
+                systemName = v;
+        }
+        else if (token === "--agent-response") {
+            const v = argv[++i];
+            if (v === undefined || v.trim() === "") {
+                process.stderr.write(`Error: --agent-response needs the agent's answer as text.\n${REPORT_USAGE}`);
+                return 1;
+            }
+            agentResponse = v;
+        }
+        else if (token === "--format") {
             const v = argv[++i];
             if (v !== "md" && v !== "html") {
                 process.stderr.write(`Error: --format must be "md" or "html", got "${v ?? ""}".\n`);
@@ -234,10 +391,15 @@ export async function runReportMode(argv) {
             format = v;
         }
         else if (token === "--out") {
-            outPath = argv[++i];
+            const v = argv[++i];
+            if (v === undefined || v.startsWith("--") || v.trim() === "") {
+                process.stderr.write(`Error: --out needs a file name.\n${REPORT_USAGE}`);
+                return 1;
+            }
+            outPath = v;
         }
         else if (token.startsWith("--")) {
-            process.stderr.write(`Error: unknown option ${token}\nUsage: report <report-file> [--format md|html] [--out <file>]\n`);
+            process.stderr.write(`Error: unknown option ${token}\n${REPORT_USAGE}`);
             return 1;
         }
         else if (file === undefined) {
@@ -265,10 +427,63 @@ export async function runReportMode(argv) {
         process.stderr.write(`Error: ${file} is not valid JSON. It may still be written; try again after the proxy has exited.\n`);
         return 1;
     }
-    const chosen = format ?? (outPath && extname(outPath).toLowerCase() === ".html" ? "html" : "md");
-    const text = chosen === "html" ? renderHtml(parsed) : renderMarkdown(parsed);
+    // Not a proxy report at all (a benchmark result, some other JSON): say so
+    // instead of claiming that the run has not produced a result yet.
+    if (parsed === null ||
+        typeof parsed !== "object" ||
+        (typeof parsed.harnessVersion !== "string" && parsed.report === undefined)) {
+        process.stderr.write(`Error: ${file} is not a report written by the proxy (--report-file). ` +
+            "The benchmark result and the audit-report.json of the demo server are different files.\n");
+        return 1;
+    }
+    if (!dossier && (customerName !== undefined || systemName !== undefined)) {
+        process.stderr.write(`Error: --customer and --system only apply together with --dossier.\n${REPORT_USAGE}`);
+        return 1;
+    }
+    if (agentResponse !== undefined) {
+        if (parsed.report)
+            parsed.claim_check = evaluateAgentClaim(agentResponse, parsed.report);
+        else
+            process.stderr.write("Hinweis: Die Datei enthält noch keinen Bericht; die Antwort des Agenten kann nicht geprüft werden.\n");
+    }
+    const outExt = outPath ? extname(outPath).toLowerCase() : "";
+    if (format === "html" && [".md", ".markdown"].includes(outExt)) {
+        process.stderr.write(`Error: --format html does not fit the file name ${outPath}. Use .html or drop --format.\n`);
+        return 1;
+    }
+    if (format === "md" && [".html", ".htm"].includes(outExt)) {
+        process.stderr.write(`Error: --format md does not fit the file name ${outPath}. Use .md or drop --format.\n`);
+        return 1;
+    }
+    const chosen = format ?? (outExt === ".html" || outExt === ".htm" ? "html" : "md");
+    const dossierOptions = { customerName, systemName, agentResponse };
+    const text = dossier
+        ? chosen === "html" ? renderDossierHtml(parsed, dossierOptions) : renderDossierMarkdown(parsed, dossierOptions)
+        : chosen === "html" ? renderHtml(parsed) : renderMarkdown(parsed);
     if (outPath) {
-        await writeFile(outPath, text, "utf8");
+        if (isReservedFileName(outPath)) {
+            process.stderr.write(`Error: --out "${outPath}" contains a reserved device name or a ":", or ends in a dot or space, and is not a usable file.
+`);
+            return 1;
+        }
+        const real = async (p) => realpath(p).catch(() => resolve(p));
+        if ((await real(outPath)) === (await real(file))) {
+            process.stderr.write(`Error: --out ${outPath} is the report file itself. Writing there would replace the measurement. Choose another file.\n`);
+            return 1;
+        }
+        if (!(await mayReplaceOutput(outPath))) {
+            process.stderr.write(`Error: ${outPath} already exists and was not written by 'report'. Refusing to overwrite it. Choose another file name.\n`);
+            return 1;
+        }
+        try {
+            await writeFile(outPath, text, "utf8");
+        }
+        catch (err) {
+            const code = err.code;
+            const why = code === "ENOENT" ? "the folder does not exist" : code === "EISDIR" ? "it is a folder, not a file" : err.message;
+            process.stderr.write(`Error: cannot write ${outPath}: ${why}.\n`);
+            return 1;
+        }
         process.stdout.write(`Bericht geschrieben: ${outPath}\n`);
     }
     else {

package/dist/proxy/gateway.js

@@ -68,7 +68,7 @@ export function createProxyServer(interceptor, options = {}) {
         }));
         return { tools: [...upstreamDefs, ...ownDefs] };
     });
-    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
         const { name, arguments: rawArgs } = request.params;
         const toolArgs = (rawArgs ?? {});
         if (auditTools && isOwnTool(name)) {
@@ -91,7 +91,7 @@ export function createProxyServer(interceptor, options = {}) {
             }
             return handleGetScore(withSession);
         }
-        return interceptor.interceptToolCall(name, toolArgs);
+        return interceptor.interceptToolCall(name, toolArgs, extra.signal);
     });
     return server;
 }