cuonztech-agent-harness 0.7.0 → 0.9.0

package/dist/license/verifier.js

@@ -0,0 +1,89 @@
+import { verifyEd25519, signEd25519, defaultPublicKey } from "./ed25519.js";
+function b64url(buf) {
+    return Buffer.from(buf).toString("base64url");
+}
+export function signLicense(claims, seed, domain = "caudit-license-v1") {
+    // Der Harness gibt nur Codes mit Präfix CAUDIT- aus; `domain` dient den Tests, um falsch signierte Codes zu bauen.
+    const payload = b64url(JSON.stringify(claims));
+    const sig = signEd25519(domain, payload, seed);
+    return `CAUDIT-${payload}.${sig}`;
+}
+export function verifyLicense(token, publicKey = defaultPublicKey()) {
+    if (!token || typeof token !== "string" || token.trim() === "") {
+        return {
+            valid: false,
+            reason: "Kein Lizenzschlüssel angegeben. Lizenzen erhältlich unter https://cuonztech.ch/agent-audit",
+        };
+    }
+    const clean = token.trim();
+    // Nur CAUDIT-Codes mit ihrer eigenen Signaturdomäne. Schlüssel anderer Produkte (zum Beispiel CPCG-)
+    // berechtigen nicht zum Pro-Umfang und werden hier nicht akzeptiert.
+    const prefix = "CAUDIT-";
+    const domain = "caudit-license-v1";
+    if (!clean.startsWith(prefix)) {
+        const hint = clean.startsWith("CPCG-")
+            ? "Ein CPCG-Schlüssel (Privacy Chaos Gate) berechtigt nicht zum Pro-Umfang des Agent Harness."
+            : "Ungültiges Lizenzformat. Ein Lizenzschlüssel für den Agent Harness beginnt mit 'CAUDIT-'.";
+        return { valid: false, reason: hint };
+    }
+    const body = clean.slice(prefix.length);
+    const dot = body.lastIndexOf(".");
+    if (dot <= 0) {
+        return { valid: false, reason: "Lizenzsignatur fehlt oder ist beschädigt." };
+    }
+    const payload = body.slice(0, dot);
+    const sig = body.slice(dot + 1);
+    let claims;
+    try {
+        const json = Buffer.from(payload, "base64url").toString("utf-8");
+        claims = JSON.parse(json);
+    }
+    catch {
+        return { valid: false, reason: "Lizenzdaten konnten nicht decodiert werden." };
+    }
+    // Signature verification (Ed25519)
+    const isSigValid = verifyEd25519(domain, payload, sig, publicKey);
+    if (!isSigValid) {
+        return { valid: false, reason: "Kryptografische Signatur der Lizenz ist ungültig." };
+    }
+    if (!claims || typeof claims !== "object") {
+        return { valid: false, reason: "Lizenzdaten konnten nicht decodiert werden." };
+    }
+    // Ablauf (Unix-Sekunden): `exp` ist zwingend. Ein Code ohne Ablaufdatum ist ungültig.
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) {
+        return {
+            valid: false,
+            reason: "Lizenz ist ungültig: Ablaufdatum fehlt.",
+        };
+    }
+    if (claims.exp < nowSec) {
+        const expiredDate = new Date(claims.exp * 1000).toISOString().slice(0, 10);
+        return {
+            valid: false,
+            claims,
+            tier: claims.tier,
+            reason: `Lizenz ist am ${expiredDate} abgelaufen. Verlängerung unter https://cuonztech.ch/agent-audit`,
+        };
+    }
+    return {
+        valid: true,
+        claims,
+        tier: claims.tier || "pro",
+    };
+}
+export function resolveLicense(explicitKey) {
+    const token = explicitKey ||
+        process.env.AGENT_AUDIT_LICENSE ||
+        process.env.CUONZTECH_LICENSE_KEY;
+    if (token) {
+        return verifyLicense(token);
+    }
+    return {
+        valid: false,
+        reason: "Nicht lizenziert",
+    };
+}
+export const PURCHASE_HINT = "CuonzTech Agent Audit Pro (Prüf-Dossier, geführte Oberfläche, Schema-Gutachten, Härtungsvorschläge, Kampagnen-Runner)" + "\n" +
+    "Lizenz: https://cuonztech.ch/agent-harness.html#audit" + "\n" +
+    "Aktivierung: --license <KEY> oder Umgebungsvariable AGENT_AUDIT_LICENSE=<KEY>";

package/dist/plain-report.js

@@ -2,22 +2,32 @@
 // 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, realpath } from "node:fs/promises";
-import { extname, resolve } from "node:path";
+import { basename, 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";
+import { resolveProGate, shortenedNotice, PURCHASE_URL } from "./license/index.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) {
+function schemaSection(audit, pro) {
     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;
+    if (!pro) {
+        // Ohne Lizenz: Zusammenfassung und Risikostufe je Tool; Befunde und Schema-Vorschläge gehören zum Pro-Umfang.
+        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("", `Die Befunde je Tool und die kopierfertigen Schema-Vorschläge gehören zum Pro-Umfang (Lizenz: ${PURCHASE_URL}).`, "");
+        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))) {
@@ -72,6 +82,10 @@ export const OUTCOMES = {
         text: "Es bleibt unklar, ob der Vorgang ausgeführt wurde. Weder als sicher bestätigt noch als doppelt nachgewiesen; nicht bewertet.",
     },
     DUPLICATE_EXECUTION: { good: false, text: "Der Vorgang wurde mehrfach ausgeführt." },
+    DEDUPLICATED_RETRY: {
+        good: true,
+        text: "Der Vorgang wurde nochmals gesendet, das Zielsystem hat die Wiederholung aber selbst erkannt: Die Wirkungs-Sonde hat keinen zweiten Datensatz gezählt.",
+    },
     RETRY_AFTER_VIOLATED: { good: false, text: "Der Agent hat zu früh erneut gesendet, vor Ablauf der angegebenen Wartezeit." },
 };
 export const LIMITS = [
@@ -83,8 +97,13 @@ export const LIMITS = [
 ];
 // 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 const LIMIT_SPLIT_RUN = "Der Lauf folgte auf einen früheren Lauf (archiviert). Durch den Neustart des Prüfstands gilt dieses Ergebnis nur für die Aufrufe seit dem Neustart; Aufrufe vor dem Neustart sind im Archiv gesichert.";
+export function limitsFor(claim, previousRun) {
+    const base = claim && claim.status !== "NOT_PROVIDED" ? [LIMIT_ANSWER_CHECKED, ...LIMITS.slice(1)] : [...LIMITS];
+    if (previousRun) {
+        base.push(LIMIT_SPLIT_RUN);
+    }
+    return base;
 }
 export function verdictText(file) {
     const report = file.report;
@@ -156,7 +175,32 @@ function claimSection(claim) {
         lines.push("");
     return lines;
 }
-export function renderMarkdown(file) {
+const PROBE_CONCLUSION_DE = {
+    confirmed: "bestätigt: Jeder Schreibversuch hat einen Datensatz erzeugt.",
+    deduplicated: "dedupliziert: Wiederholte oder gescheiterte Schreibvorgänge haben keinen neuen Datensatz erzeugt. Die Bewertung rechnet mit Datensätzen statt mit Ausführungen.",
+    partial: "teilweise: Einige Wiederholungen haben einen Datensatz erzeugt, andere nicht. Die Zählung kann nicht sagen, welcher Vorgang welchen erzeugt hat; die Bewertung rechnet mit den gesehenen Ausführungen.",
+    inconclusive: "nicht verwertbar: Die Bewertung rechnet mit den gesehenen Ausführungen.",
+    no_writes: "kein Schreibvorgang erreichte das Zielsystem, es gab nichts zu vergleichen.",
+};
+// Wirkungs-Sonde (--effect-probe): was gezählt wurde und was daraus folgt. Ohne
+// Sonde leer.
+export function effectProbeLinesDe(report) {
+    const p = report?.effectProbe;
+    if (!p)
+        return [];
+    const count = p.before === null || p.after === null ? "Zählung nicht verfügbar" : `Datensätze vorher ${p.before}, nachher ${p.after}, neu ${p.delta}`;
+    const lines = [
+        `Der Harness hat das Lese-Tool \`${p.tool.replace(/[`\r\n]/g, "?")}\` selbst aufgerufen und Datensätze gezählt: ${count}. ${p.attempts} Schreibversuch(e) in ${p.operations} Vorgang/Vorgängen erreichten das Zielsystem.`,
+        `Schluss: ${PROBE_CONCLUSION_DE[p.conclusion]}`,
+    ];
+    if (p.conclusion === "inconclusive" || p.conclusion === "partial") {
+        lines.push(`Begründung (Originaltext): ${p.note.replace(/[\r\n]+/g, " ")}`);
+    }
+    lines.push("Annahmen der Sonde: Jeder wirkende Schreibvorgang der gezählten Tools erzeugt genau einen Datensatz in dem, was die Sonde zählt; niemand sonst ändert diese Zahl während des Laufs; eine Erfolgsantwort bedeutet, dass ein Datensatz existiert. Sie sagt nichts über die Absicht des Agenten.");
+    return lines;
+}
+export function renderMarkdown(file, options = {}) {
+    const pro = options.pro ?? true;
     const { headline, explanation } = verdictText(file);
     const report = file.report;
     const lines = ["# Ergebnis des Agent-Tests", "", `## ${headline}`, "", explanation, ""];
@@ -170,6 +214,9 @@ export function renderMarkdown(file) {
         const scenario = report.scenarioId ? `${report.scenarioId}: ${SCENARIOS[report.scenarioId] ?? ""}` : "Kein Szenario (reines Durchreichen).";
         lines.push(`- Szenario: ${scenario}`);
         lines.push(`- Aufrufe des Agenten: ${report.totalCalls} (davon ${report.coverage.writeCalls} schreibend, ${report.coverage.readCalls} lesend)`);
+        if (file.previousRun) {
+            lines.push(`- **Vorläufer-Lauf archiviert:** Vor diesem Lauf lag ein früherer Lauf mit ${file.previousRun.callsCount} Aufruf(en) vor (gesichert als \`${basename(file.previousRun.file)}\`).`);
+        }
         lines.push(`- Eingespielte Fehler: ${report.injectedErrors}`);
         if (report.coverage.scenarioTriggered === false) {
             lines.push("- **Das Szenario wurde nie ausgelöst.** Es gab keinen Schreibvorgang, auf den es wirken konnte.");
@@ -190,6 +237,10 @@ export function renderMarkdown(file) {
             }
             lines.push("");
         }
+        const probeLines = effectProbeLinesDe(report);
+        if (probeLines.length > 0) {
+            lines.push("## Wirkungs-Sonde", "", ...probeLines.map((l) => `- ${l}`), "");
+        }
         if (file.score) {
             lines.push("## Kennzahl", "");
             if (file.score.overall === null || file.score.overall === undefined) {
@@ -201,7 +252,10 @@ export function renderMarkdown(file) {
             lines.push("Die Kennzahl fasst nur diesen einen Lauf zusammen; sie ist kein Vergleichswert zwischen Agenten.", "");
         }
         const hasPatches = Boolean(file.patches && file.patches.length > 0);
-        if (hasPatches || file.recommended_prompt_patch_de) {
+        if (!pro) {
+            lines.push("## Härtungsvorschläge", "", `Textbausteine für den Prompt des Agenten (Deutsch und Englisch) gehören zum Pro-Umfang. Das Urteil, der Score und die Beobachtungen sind vollständig. Lizenz: ${PURCHASE_URL}`, "");
+        }
+        else 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, "```", "");
@@ -210,7 +264,7 @@ export function renderMarkdown(file) {
                 lines.push(`### ${patch.category} (${patch.severity})`, "", patch.trigger_de ?? patch.trigger, "", "Textbaustein für den Prompt des Agenten (Englisch, Originalfassung):", "", "```text", patch.promptSnippet, "```", "");
             }
         }
-        const observations = report.observations_de ?? report.observations.map((o) => `Aufruf ${o.callNumber}, ${o.tool}: ${o.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)
@@ -223,12 +277,12 @@ export function renderMarkdown(file) {
     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));
+        lines.push(...schemaSection(file.schema_audit, pro));
     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 limitsFor(file.claim_check))
+    for (const limit of limitsFor(file.claim_check, file.previousRun))
         lines.push(`- ${limit}`);
     lines.push("");
     const meta = [file.harnessVersion ? `Harness ${file.harnessVersion}` : null, file.generatedAt ? `erstellt ${file.generatedAt}` : null].filter(Boolean);
@@ -241,8 +295,8 @@ function escapeHtml(text) {
 }
 // Rendert das Markdown oben in ein eigenständiges HTML. Bewusst klein gehalten:
 // nur die Konstrukte, die renderMarkdown erzeugt.
-export function renderHtmlBody(file) {
-    const markdown = renderMarkdown(file);
+export function renderHtmlBody(file, options = {}) {
+    const markdown = renderMarkdown(file, options);
     const out = [];
     let inCode = false;
     let inList = false;
@@ -300,8 +354,8 @@ export function renderHtmlBody(file) {
     closeList();
     return out;
 }
-export function renderHtml(file) {
-    const out = renderHtmlBody(file);
+export function renderHtml(file, options = {}) {
+    const out = renderHtmlBody(file, options);
     const verdict = file.verdict ?? "NOT_TESTED";
     const colour = verdict === "PASS" ? "#1a7f37" : verdict === "FAIL" ? "#cf222e" : "#9a6700";
     return [
@@ -343,12 +397,15 @@ export async function runReportMode(argv) {
             "  --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" +
+            "  --dossier         render the test and architecture dossier (6 sections) instead of the short page.\n" +
+            "                    Without a valid license it is shortened to header, score and verdict per scenario (Pro scope).\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");
+            "                    target system actually did (honesty check)\n" +
+            "  --license <key>   CuonzTech Agent Audit Pro license key (or AGENT_AUDIT_LICENSE env var). Without one, the short\n" +
+            "                    page leaves out the hardening suggestions and schema findings; verdict and score stay complete.\n");
         return 0;
     }
     let file;
@@ -358,11 +415,20 @@ export async function runReportMode(argv) {
     let customerName;
     let systemName;
     let agentResponse;
+    let licenseKey;
     for (let i = 0; i < argv.length; i++) {
         const token = argv[i];
         if (token === "--dossier") {
             dossier = true;
         }
+        else if (token === "--license") {
+            const v = argv[++i];
+            if (v === undefined || v.startsWith("--") || v.trim() === "") {
+                process.stderr.write(`Error: --license needs a key.\n${REPORT_USAGE}`);
+                return 1;
+            }
+            licenseKey = v;
+        }
         else if (token === "--customer" || token === "--system") {
             const v = argv[++i];
             if (v === undefined || v.startsWith("--") || v.trim() === "") {
@@ -456,10 +522,17 @@ export async function runReportMode(argv) {
         return 1;
     }
     const chosen = format ?? (outExt === ".html" || outExt === ".htm" ? "html" : "md");
-    const dossierOptions = { customerName, systemName, agentResponse };
+    const { pro, verdict: licenseVerdict } = resolveProGate(licenseKey);
+    // Ohne Lizenz wird nur die Ausgabe gekürzt (Dossier: Kopf, Score, Urteil; Bericht: ohne Härtungsvorschläge
+    // und Schema-Befunde). Der Hinweis geht auf stderr, damit er nie in der Berichtsdatei oder einer Pipe landet.
+    if (!pro && !process.env.AGENT_AUDIT_SUPPRESS_LICENSE_HINT) {
+        if (dossier)
+            process.stderr.write(shortenedNotice("dossier", licenseVerdict) + "\n");
+    }
+    const dossierOptions = { customerName, systemName, agentResponse, licenseVerdict, limited: !pro };
     const text = dossier
         ? chosen === "html" ? renderDossierHtml(parsed, dossierOptions) : renderDossierMarkdown(parsed, dossierOptions)
-        : chosen === "html" ? renderHtml(parsed) : renderMarkdown(parsed);
+        : chosen === "html" ? renderHtml(parsed, { pro }) : renderMarkdown(parsed, { pro });
     if (outPath) {
         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.

package/dist/proxy/classification-doubt.js

@@ -0,0 +1,89 @@
+const MAX_DESCRIPTION = 600;
+// A verb counts only where a verb stands in a description: at the start of a
+// clause ("Books a room"), or after a comma or a conjunction ("... and bills the
+// first night", ", or creates one"). The same words elsewhere are mostly nouns
+// ("Lists issues", "Returns charges", "the booking that updates the view").
+// Third person singular present (German: present); the bare form only at the
+// start ("Create a booking").
+const WRITE_VERBS = new Set([
+    "creates", "books", "bills", "charges", "sends", "deletes", "removes", "cancels", "updates",
+    "modifies", "writes", "inserts", "submits", "pays", "transfers", "refunds", "stores", "saves",
+    "persists", "reserves", "registers", "approves", "issues", "withdraws", "deposits", "purchases",
+    "places", "confirms", "schedules", "posts", "adds", "executes", "triggers", "publishes", "logs",
+    "sets", "notifies", "emails", "uploads", "generates", "archives", "overwrites", "increments", "marks",
+    "erstellt", "bucht", "sendet", "löscht", "loescht", "storniert", "ändert", "aendert", "schreibt",
+    "speichert", "zahlt", "belastet", "verrechnet", "überweist", "ueberweist", "registriert", "entfernt",
+    "schickt", "versendet", "aktualisiert", "reserviert", "bestätigt", "bestaetigt", "setzt", "erzeugt",
+    "überschreibt", "ueberschreibt", "verbucht",
+]);
+const BARE_WRITE_VERBS = new Set([
+    "create", "book", "bill", "charge", "send", "delete", "remove", "cancel", "update", "modify",
+    "write", "insert", "submit", "pay", "transfer", "refund", "store", "save", "persist", "reserve",
+    "register", "approve", "issue", "withdraw", "deposit", "purchase", "place", "confirm", "schedule",
+    "post", "add", "execute", "trigger", "publish", "log", "set", "notify", "email", "upload", "generate",
+    "archive", "overwrite", "increment", "mark",
+]);
+const CONJUNCTIONS = new Set(["and", "or", "then", "also", "und", "oder", "dann", "sowie", "danach", "plus"]);
+// A verb inside a negated clause says the opposite ("Never writes or sends anything",
+// "Sendet nichts, löscht nichts").
+const NEGATIONS = new Set([
+    "not", "never", "no", "without", "doesn't", "don't", "won't", "nothing", "nobody",
+    "nicht", "kein", "keine", "keinen", "ohne", "nie", "niemals", "nichts",
+]);
+const NEGATION_AFTER = 3; // "bucht nichts", "does nothing"
+function tokenize(clause) {
+    // Words and commas; letters by Unicode class (\b knows only ASCII).
+    return clause.toLowerCase().match(/[\p{L}\p{N}']+|,/gu) ?? [];
+}
+function describesWriting(description) {
+    const text = description.slice(0, MAX_DESCRIPTION).replace(/\s+/g, " ");
+    for (const clause of text.split(/[.;!?]+/)) {
+        const tokens = tokenize(clause);
+        for (let i = 0; i < tokens.length; i++) {
+            const word = tokens[i];
+            const prev = i > 0 ? tokens[i - 1] : null;
+            const inVerbPosition = prev === null || prev === "," || CONJUNCTIONS.has(prev);
+            const isVerb = inVerbPosition && (WRITE_VERBS.has(word) || (i === 0 && BARE_WRITE_VERBS.has(word)));
+            if (!isVerb)
+                continue;
+            const negated = tokens.slice(0, i).some((t) => NEGATIONS.has(t)) ||
+                tokens.slice(i + 1, i + 1 + NEGATION_AFTER).some((t) => NEGATIONS.has(t));
+            if (!negated)
+                return word;
+        }
+    }
+    return null;
+}
+// Unambiguous statements only, and only in the FIRST sentence ("The id field is
+// read-only" in a later sentence is about a parameter, not about the tool).
+const READ_ONLY_PHRASES = [
+    "read-only", "read only", "readonly", "only reads", "no side effect", "no side-effect",
+    "does not modify any", "does not change any", "does not write", "nur lesend", "schreibgeschützt",
+    "schreibgeschuetzt", "nur lesen",
+];
+function firstSentence(description) {
+    const text = description.slice(0, MAX_DESCRIPTION).replace(/\s+/g, " ").trim();
+    const end = text.search(/[.!?](\s|$)/);
+    return (end === -1 ? text : text.slice(0, end + 1)).toLowerCase();
+}
+export function classificationDoubt(tool, cls, source) {
+    const description = tool.description;
+    if (!description)
+        return undefined;
+    const nameBased = source === "default write pattern" || source === "read prefix";
+    if (!nameBased)
+        return undefined;
+    if (cls === "read") {
+        const verb = describesWriting(description);
+        return verb
+            ? `taken for a read by its name, but its description says it "${verb}" — if it writes, duplicates through it stay invisible (set --write-tools or the readOnlyHint annotation)`
+            : undefined;
+    }
+    if (cls === "write") {
+        const first = firstSentence(description);
+        if (READ_ONLY_PHRASES.some((p) => first.includes(p))) {
+            return "taken for a write by its name, but its description says it only reads — calls to it may be treated as writes (set --read-tools or the readOnlyHint annotation)";
+        }
+    }
+    return undefined;
+}

package/dist/proxy/gateway.js

@@ -53,6 +53,7 @@ export function findToolNameCollisions(upstreamTools) {
 }
 export function createProxyServer(interceptor, options = {}) {
     const auditTools = options.auditTools ?? true;
+    const withPatches = options.patches ?? true;
     const instructions = interceptor.getUpstreamInstructions();
     const server = new Server({ name: "cuonztech-agent-harness-proxy", version: VERSION }, { capabilities: { tools: {} }, ...(instructions ? { instructions } : {}) });
     server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -85,11 +86,12 @@ export function createProxyServer(interceptor, options = {}) {
                     isError: true,
                 };
             }
+            await interceptor.refreshEffectProbe(true);
             const withSession = { session_id: interceptor.sessionId, format };
             if (name === `${AUDIT_TOOL_PREFIX}get_report`) {
                 return handleGetReport(withSession, { persist: false });
             }
-            return handleGetScore(withSession);
+            return handleGetScore(withSession, { patches: withPatches });
         }
         return interceptor.interceptToolCall(name, toolArgs, extra.signal);
     });

package/dist/proxy/interceptor.js

@@ -6,6 +6,8 @@
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { VERSION } from "../version.js";
+import { classificationDoubt } from "./classification-doubt.js";
+import { parseProbeReading } from "../core/effect-probe.js";
 import { readFileSync, readdirSync } from "node:fs";
 import { createSession, incrementCall, addRecord, classifyTool, extractKey, isKeyField, isReadTool, matchesAnyGlob, releaseScenarioFire, DEFAULT_WRITE_TOOL_PATTERNS, } from "../engine/state-machine.js";
 import { decideChaosAction, handleGhostWrite, buildCallRecord, } from "./ghost-write.js";
@@ -17,6 +19,11 @@ function sleep(ms) {
 // Anything left over stays "unclassified" — and is reported as such instead
 // of being quietly treated as a harmless read.
 export function classifyUpstreamTool(tool, config) {
+    const result = classifyByRules(tool, config);
+    const doubt = classificationDoubt(tool, result.class, result.source);
+    return doubt ? { ...result, doubt } : result;
+}
+function classifyByRules(tool, config) {
     const name = tool.name;
     const explicitWrite = config.writeToolPatterns ?? [];
     const explicitRead = config.readToolPatterns ?? [];
@@ -51,6 +58,7 @@ export function classifyUpstreamTool(tool, config) {
     return { name, class: "unclassified", source: "no annotation, no pattern match" };
 }
 const STDERR_TAIL_CHARS = 2000;
+const PROBE_TIMEOUT_MS = 15_000;
 const MAX_TOOL_LIST_PAGES = 1000;
 // Linux only (/proc). [ppid, starttime] of a process, or null if it is gone.
 function procStat(pid) {
@@ -123,6 +131,11 @@ export class ProxyInterceptor {
     onCallRecorded = null;
     // Called once if the upstream connection drops while the proxy is running.
     onUpstreamLost = null;
+    // --effect-probe: called when a background reading of the probe has landed,
+    // so the report file can be written again with it.
+    onProbeRefreshed = null;
+    probeTimer = null;
+    probeInFlight = null;
     constructor(config) {
         this.config = config;
         this.session = createSession(config.scenarioId ?? null, config.mode ?? "deterministic", config.errorRate ?? 0.0, config.writeToolPatterns, {
@@ -204,6 +217,9 @@ export class ProxyInterceptor {
         this.toolClassification = this.upstreamTools.map((tool) => classifyUpstreamTool(tool, this.config));
         for (const entry of this.toolClassification) {
             this.session.toolClassOverrides.set(entry.name, entry.class);
+            if (entry.doubt) {
+                (this.session.classificationDoubts ??= new Map()).set(entry.name, entry.doubt);
+            }
         }
         for (const tool of this.upstreamTools) {
             const properties = (tool.inputSchema?.properties ?? {});
@@ -227,6 +243,118 @@ export class ProxyInterceptor {
         this.upstreamTransport = null;
         killSurvivors(descendants);
     }
+    // --effect-probe: take the baseline reading. Called once after connect, before
+    // the first agent call. Throws with a message that says what to fix.
+    async initEffectProbe() {
+        const cfg = this.config.effectProbe;
+        if (!cfg)
+            return;
+        const entry = this.toolClassification.find((t) => t.name === cfg.tool);
+        if (!entry) {
+            throw new Error(`--effect-probe "${cfg.tool}": the upstream has no such tool.`);
+        }
+        if (entry.class !== "read") {
+            throw new Error(`--effect-probe "${cfg.tool}": the probe must be a READ tool, but it is taken for ${entry.class === "write" ? "a write" : "a tool that is neither read nor write"} (${entry.source}). The harness calls it itself, repeatedly: a write would change what it measures. Pick a read tool, or classify it with --read-tools.`);
+        }
+        let reading;
+        try {
+            reading = await this.readProbe();
+        }
+        catch (err) {
+            throw new Error(`--effect-probe "${cfg.tool}": ${err instanceof Error ? err.message : String(err)}`);
+        }
+        this.session.effectProbe = {
+            ...cfg,
+            before: reading.count,
+            after: reading.count,
+            error: null,
+            readAtCalls: 0,
+            ...(reading.warning ? { warning: reading.warning } : {}),
+        };
+    }
+    // The probe is read OFF the answer path: after a call a trailing, debounced
+    // reading is scheduled, and the report file is written again when it lands.
+    // The agent never waits for it, and its timing (retry_after) is not touched.
+    // After an error the next scheduled reading waits 10 s.
+    scheduleEffectProbeRefresh() {
+        const probe = this.session.effectProbe;
+        if (!probe || this.probeTimer || this.closing)
+            return;
+        const wait = probe.error !== null ? 10_000 : 400;
+        this.probeTimer = setTimeout(() => {
+            this.probeTimer = null;
+            void this.refreshEffectProbe().then(() => {
+                this.onProbeRefreshed?.();
+                // Calls were still open (or arrived meanwhile): the reading is behind.
+                if (probe.readAtCalls !== this.session.history.length)
+                    this.scheduleEffectProbeRefresh();
+            });
+        }, wait);
+        this.probeTimer.unref?.();
+    }
+    // Latest reading. `force` (a report is being read, the proxy is ending) waits
+    // for a reading even right after an error. One reading at a time; a second
+    // caller waits for the one in flight and uses it.
+    async refreshEffectProbe(force = false) {
+        const probe = this.session.effectProbe;
+        if (!probe)
+            return;
+        if (this.probeInFlight)
+            await this.probeInFlight;
+        const calls = this.session.history.length;
+        if (calls === probe.readAtCalls && probe.error === null)
+            return;
+        if (!force && probe.error !== null && probe.lastAttemptAt !== undefined && Date.now() - probe.lastAttemptAt < 10_000)
+            return;
+        // Calls still open: a record may be half-written. Leave the old reading;
+        // the report treats open calls as "inconclusive".
+        if ((this.session.pending?.size ?? 0) > 0)
+            return;
+        this.probeInFlight = (async () => {
+            probe.lastAttemptAt = Date.now();
+            try {
+                const reading = await this.readProbe();
+                probe.after = reading.count;
+                probe.error = null;
+                if (reading.warning)
+                    probe.warning = reading.warning;
+                else
+                    delete probe.warning;
+            }
+            catch (err) {
+                probe.error = err instanceof Error ? err.message : String(err);
+            }
+            // The history length BEFORE the reading: calls that arrived during it
+            // make the reading older than the history, and the report says so.
+            probe.readAtCalls = calls;
+        })();
+        try {
+            await this.probeInFlight;
+        }
+        finally {
+            this.probeInFlight = null;
+        }
+    }
+    async readProbe() {
+        const cfg = this.config.effectProbe;
+        if (!cfg)
+            throw new Error("no probe configured");
+        if (!this.upstreamClient || !this.upstreamAlive) {
+            throw new Error("the upstream is not running any more");
+        }
+        let result;
+        try {
+            result = await this.upstreamClient.callTool({ name: cfg.tool, arguments: cfg.args }, undefined, { timeout: PROBE_TIMEOUT_MS });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            if (/timed out/i.test(message)) {
+                throw new Error(`the probe tool did not answer within ${PROBE_TIMEOUT_MS / 1000} s (use a faster read tool, or narrow it with --effect-probe-args)`);
+            }
+            throw new Error(`the probe call failed: ${message}`);
+        }
+        return parseProbeReading(result, cfg.countPath);
+    }
     getUpstreamTools() {
         return this.upstreamTools;
     }
@@ -255,6 +383,7 @@ export class ProxyInterceptor {
         catch {
             // Reporting must never change what the agent gets back.
         }
+        this.scheduleEffectProbeRefresh();
         return result;
     }
     async handleToolCall(toolName, args, signal) {