cuonztech-agent-harness 0.10.0 → 0.11.1

package/dist/proxy/classification-doubt.js

@@ -15,6 +15,13 @@ const WRITE_VERBS = new Set([
     "speichert", "zahlt", "belastet", "verrechnet", "überweist", "ueberweist", "registriert", "entfernt",
     "schickt", "versendet", "aktualisiert", "reserviert", "bestätigt", "bestaetigt", "setzt", "erzeugt",
     "überschreibt", "ueberschreibt", "verbucht",
+    // 0.11.0: further verbs that put something into a state ("Changes the status", "locks the job").
+    "changes", "locks", "unlocks", "clears", "resets", "assigns", "grants", "revokes", "moves", "renames",
+    "deploys", "restarts", "stops", "starts", "enables", "disables", "activates", "deactivates", "invites",
+    "subscribes", "unsubscribes", "inserts", "appends", "replaces", "kills", "terminates", "closes", "reopens",
+    "dispatches", "enqueues", "settles", "captures", "voids", "orders", "ships", "invoices", "mints", "burns",
+    "swaps", "stakes", "claims", "votes", "shares", "tags", "labels", "flags", "pops", "acknowledges", "dismisses",
+    "ändert", "legt", "löscht", "setzt", "sperrt",
 ]);
 const BARE_WRITE_VERBS = new Set([
     "create", "book", "bill", "charge", "send", "delete", "remove", "cancel", "update", "modify",
@@ -72,6 +79,27 @@ export function descriptionOpensWithReadVerb(description) {
     const first = description.slice(0, 200).trim().toLowerCase().match(/^[\p{L}]+/u);
     return first !== null && READ_OPENERS.has(first[0]);
 }
+// The first sentence opens with a plain write verb ("Creates a booking", "Löscht einen Eintrag"), not
+// negated. Narrower than describesWriting: no generic verbs ("generates", "logs", "marks"), and only at
+// the very start, because the prefix decides nothing here — the description is the only witness.
+const OPENING_WRITE_VERBS = new Set([
+    "creates", "adds", "inserts", "updates", "modifies", "deletes", "removes", "cancels", "books", "sends",
+    "submits", "pays", "transfers", "refunds", "charges", "writes", "saves", "stores", "registers", "approves",
+    "publishes", "uploads", "schedules", "reserves", "places", "posts", "archives", "overwrites", "changes",
+    "assigns", "deploys", "restarts", "activates", "deactivates", "enables", "disables",
+    "create", "add", "insert", "update", "modify", "delete", "remove", "cancel", "book", "send", "submit",
+    "pay", "transfer", "refund", "charge", "write", "save", "store", "register", "approve", "publish",
+    "upload", "schedule", "reserve", "place", "post", "archive", "overwrite", "change", "assign", "deploy",
+    "erstellt", "legt", "löscht", "loescht", "ändert", "aendert", "sendet", "bucht", "storniert", "speichert",
+    "überweist", "ueberweist", "entfernt", "aktualisiert", "versendet", "registriert", "reserviert",
+    "bestätigt", "bestaetigt", "schreibt", "verbucht", "setzt",
+]);
+export function descriptionOpensWithWriteVerb(description) {
+    const tokens = tokenize(firstSentence(description));
+    if (tokens.length === 0 || !OPENING_WRITE_VERBS.has(tokens[0]))
+        return false;
+    return !tokens.slice(1, 1 + NEGATION_AFTER + 1).some((t) => NEGATIONS.has(t));
+}
 export function descriptionSaysReadOnly(description) {
     const sentence = firstSentence(description);
     return READ_ONLY_PHRASES.some((p) => sentence.includes(p));
@@ -81,7 +109,47 @@ function firstSentence(description) {
     const end = text.search(/[.!?](\s|$)/);
     return (end === -1 ? text : text.slice(0, end + 1)).toLowerCase();
 }
-export function classificationDoubt(tool, cls, source) {
+// 0.11.1 (hint only, the classification rules above and in verb-words.ts stay as they are): verbs that take
+// something from a counter or a pool and so change state, although the tool reads like a getter
+// ("Allocates a fresh invoice number", "each call issues a new code"), plus the "each call ..." phrasing
+// that puts the verb behind a subject.
+const HINT_VERBS = new Set([
+    "allocates", "dispenses", "consumes", "issues", "generates", "reserves", "assigns", "claims", "mints",
+    "increments", "decrements", "dequeues", "advances", "rotates", "regenerates", "leases", "burns",
+    "vergibt", "reserviert", "verbraucht", "erzeugt", "erhöht", "erhoeht",
+]);
+// The bare form only at the very start ("Allocate a fresh number").
+const BARE_HINT_VERBS = new Set(["allocate", "dispense", "consume", "issue", "generate", "reserve", "assign", "claim", "mint", "increment", "decrement", "dequeue", "lease"]);
+// "Each call issues a new code", "Jeder Aufruf erzeugt ...": the subject names the call, the verb changes state.
+const PER_CALL_WORDS = new Set(["call", "time", "invocation", "request", "use", "run", "aufruf", "mal", "abruf"]);
+const EACH_WORDS = new Set(["each", "every", "jeder", "jeden", "jedes", "bei"]);
+// describesWriting plus the hint-only verbs, for classificationDoubt only. A verb counts at the start of a clause,
+// after a comma or conjunction, or right behind "each call"; negations around it cancel it as in describesWriting.
+export function describesWritingHint(description) {
+    const base = describesWriting(description);
+    if (base !== null)
+        return base;
+    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];
+            if (!HINT_VERBS.has(word) && !(i === 0 && BARE_HINT_VERBS.has(word)))
+                continue;
+            const prev = i > 0 ? tokens[i - 1] : null;
+            const afterEachCall = i >= 2 && PER_CALL_WORDS.has(tokens[i - 1]) && EACH_WORDS.has(tokens[i - 2]);
+            const inVerbPosition = prev === null || prev === "," || CONJUNCTIONS.has(prev) || afterEachCall;
+            if (!inVerbPosition)
+                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;
+}
+export function classificationDoubtText(tool, cls, source) {
     const description = tool.description;
     if (!description)
         return undefined;
@@ -89,16 +157,33 @@ export function classificationDoubt(tool, cls, source) {
     if (!nameBased)
         return undefined;
     if (cls === "read") {
-        const verb = describesWriting(description);
+        const verb = describesWritingHint(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)`
+            ? {
+                en: `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)`,
+                de: `nach dem Namen als Lese-Tool eingeordnet, die Beschreibung sagt aber, dass es «${verb}»: Schreibt es, bleiben Doppelausführungen darüber unsichtbar (mit --write-tools oder der Annotation readOnlyHint festlegen)`,
+            }
             : 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 {
+                en: "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)",
+                de: "nach dem Namen als Schreib-Tool eingeordnet, die Beschreibung sagt aber, dass es nur liest: Aufrufe können als Schreibvorgang gewertet werden (mit --read-tools oder der Annotation readOnlyHint festlegen)",
+            };
+        }
+        // 0.11.1: "update_status_view": "Shows the current status view." The description opens with a read verb and names
+        // no write verb anywhere.
+        if (descriptionOpensWithReadVerb(description) && describesWritingHint(description) === null) {
+            return {
+                en: "taken for a write by its name, but its description opens with a read verb and names nothing that is written — calls to it may be treated as writes (set --read-tools or the readOnlyHint annotation)",
+                de: "nach dem Namen als Schreib-Tool eingeordnet, die Beschreibung beginnt aber mit einem Lese-Verb und nennt nichts, was geschrieben wird: Aufrufe können als Schreibvorgang gewertet werden (mit --read-tools oder der Annotation readOnlyHint festlegen)",
+            };
         }
     }
     return undefined;
 }
+export function classificationDoubt(tool, cls, source) {
+    return classificationDoubtText(tool, cls, source)?.en;
+}

package/dist/proxy/interceptor.js

@@ -6,8 +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 { classifyByVerbWords, readPrefixThenWrites } from "./verb-words.js";
+import { classificationDoubtText } from "./classification-doubt.js";
+import { classifyByDescriptionOpener, compoundWriteGuess, classifyByVerbWords, readPrefixThenWrites, weakReadPrefixThenWrites, } from "./verb-words.js";
 import { looksLikeErrorAnswer } from "./error-answer.js";
 import { parseProbeReading } from "../core/effect-probe.js";
 import { readFileSync, readdirSync } from "node:fs";
@@ -22,8 +22,8 @@ function sleep(ms) {
 // 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;
+    const doubt = classificationDoubtText(tool, result.class, result.source);
+    return doubt ? { ...result, doubt: doubt.en, doubtDe: doubt.de } : result;
 }
 function classifyByRules(tool, config) {
     const name = tool.name;
@@ -57,8 +57,20 @@ function classifyByRules(tool, config) {
     if (isReadTool(name)) {
         // "get_or_create_user", "read_and_delete": the read prefix alone would call a write a read.
         if (explicitWrite.length === 0 && readPrefixThenWrites(name)) {
+            if (explicitRead.length === 0 && compoundWriteGuess(tool.description) === "write") {
+                return { name, class: "write", source: "read verb, then a write verb (and/or/then)", guess: true };
+            }
             return { name, class: "unclassified", source: "read prefix, but a write verb follows (and/or/then)" };
         }
+        // "check_in_guest", "status_change": a weak read prefix (a noun as often as a verb) followed by a write verb.
+        if (explicitWrite.length === 0 && explicitRead.length === 0) {
+            const weak = weakReadPrefixThenWrites(name, tool.description);
+            if (weak === "write")
+                return { name, class: "write", source: "verb word after a weak read prefix", guess: true };
+            if (weak === "unclassified") {
+                return { name, class: "unclassified", source: "weak read prefix, then a write verb, but the description says it reads" };
+            }
+        }
         return { name, class: "read", source: "read prefix" };
     }
     // Last resort for what nothing above could place: a verb inside the name (`slack_post_message`).
@@ -67,6 +79,10 @@ function classifyByRules(tool, config) {
         const byWord = classifyByVerbWords(name, tool.description);
         if (byWord !== "unclassified")
             return { name, class: byWord, source: "verb word in name", guess: true };
+        // Nothing in the name: the description opens with a plain write verb ("Creates a booking").
+        if (classifyByDescriptionOpener(tool.description) === "write") {
+            return { name, class: "write", source: "description opens with a write verb", guess: true };
+        }
     }
     return { name, class: "unclassified", source: "no annotation, no pattern match" };
 }
@@ -232,6 +248,8 @@ export class ProxyInterceptor {
             this.session.toolClassOverrides.set(entry.name, entry.class);
             if (entry.doubt) {
                 (this.session.classificationDoubts ??= new Map()).set(entry.name, entry.doubt);
+                if (entry.doubtDe)
+                    (this.session.classificationDoubtsDe ??= new Map()).set(entry.name, entry.doubtDe);
             }
             if (entry.guess)
                 (this.session.verbWordGuesses ??= new Set()).add(entry.name);
@@ -545,6 +563,9 @@ export class ProxyInterceptor {
                 outcome: "injected_failure",
                 toolClass,
                 tookEffect,
+                // The agent is told "timeout", but the upstream's own answer may read like an error ("Fehler: …"
+                // without isError): the effect probe must not take it for a record that exists (same as below).
+                ...(tookEffect && looksLikeErrorAnswer(upstreamText) ? { answerLooksLikeError: true } : {}),
                 scenarioTriggered: decision.scenarioTriggered,
                 ...(decision.retryAfterSec !== null ? { retryAfterSec: decision.retryAfterSec } : {}),
                 ...(upstreamText !== undefined ? { upstreamResponse: upstreamText } : {}),

package/dist/proxy/verb-words.js

@@ -1,4 +1,4 @@
-import { describesWriting, descriptionOpensWithReadVerb, descriptionSaysReadOnly } from "./classification-doubt.js";
+import { describesWriting, descriptionOpensWithReadVerb, descriptionOpensWithWriteVerb, descriptionSaysReadOnly, } from "./classification-doubt.js";
 const WRITE_WORDS = new Set([
     "create", "add", "insert", "append", "prepend", "update", "edit", "modify", "change", "patch", "put", "set",
     "delete", "remove", "drop", "destroy", "purge", "clear", "erase", "reset", "restore", "recover",
@@ -13,7 +13,120 @@ const WRITE_WORDS = new Set([
     "rollout", "rollback", "cordon", "drain", "install", "uninstall", "upgrade", "downgrade",
     "migrate", "cleanup", "flush", "commit", "increment", "decrement", "lock", "unlock", "mute",
     "unmute", "rotate", "enroll",
+    // 0.11.0 (Luckensuche, docs/LUECKEN-NAMEN.md): everyday verbs that were missing.
+    "activate", "deactivate", "escalate", "provision", "reschedule", "notify", "trigger", "execute",
+    "retry", "replay", "finalize", "dispatch", "enqueue", "dequeue", "capture", "settle", "void",
+    "deliver", "unstake", "bridge", "dismiss", "acknowledge", "reassign", "renew", "unblock", "unban",
+    "checkout", "checkin", "remit", "reconcile", "redeem", "disburse", "onboard", "offboard",
+    "authorize", "deauthorize", "whitelist", "blacklist", "allowlist", "denylist", "quarantine",
+    "evict", "decommission", "sell", "ack", "nack",
 ]);
+// Words that are as often NOUNS as verbs (`order_status`, `explain_invoice`, `download_record`): they
+// count as a write verb only at VERB position (the first word, after an `api`/`v2`/`mcp` namespace)
+// and only when no word naming a state or a listing stands next to them.
+const AMBIGUOUS_WRITE_WORDS = new Set([
+    "order", "record", "flag", "label", "tag", "claim", "vote", "share", "swap", "stake", "bill",
+    "invoice", "ship", "block", "burn", "mint", "ban", "snooze", "complete", "extend", "suspend",
+    "demote",
+]);
+const STATE_NOUNS = new Set([
+    "status", "state", "info", "information", "details", "detail", "history", "list", "summary",
+    "availability", "preview", "report", "log", "logs", "count", "stats", "statistics", "overview",
+    "health", "estimate", "quote", "price", "total",
+    // Read-ish words that are not strong enough to make a name a read, but veto an ambiguous noun-verb
+    // ("order.check", "invoice.explain", "record.poll").
+    "check", "explain", "summarize", "compare", "calculate", "validate", "poll", "scan", "locate", "load",
+    "browse", "download", "inspect", "view", "verify", "peek", "probe", "enumerate", "comparer", "calculer",
+    "decrire", "contar", "comparar", "calcular", "describir", "verificar", "pruefen", "zaehlen", "vergleichen",
+    "berechnen",
+]);
+// German, French and Spanish tool names (`buchung_erstellen`, `supprimer_facture`, `crear_pedido`).
+// Letters are compared in a plain form (ä→ae, ö→oe, ü→ue, ß→ss, accents dropped), so "löschen",
+// "loeschen" and "loschen" meet. The German imperative ("erstelle") is derived.
+const FOREIGN_INFINITIVES = {
+    de: [
+        "erstellen", "anlegen", "hinzufuegen", "loeschen", "entfernen", "aendern", "aktualisieren", "senden",
+        "versenden", "buchen", "stornieren", "bezahlen", "ueberweisen", "freigeben", "ablehnen", "zuweisen",
+        "archivieren", "verschieben", "hochladen", "importieren", "starten", "stoppen", "aktivieren",
+        "deaktivieren", "schliessen", "einladen", "abonnieren", "registrieren", "bestellen", "speichern",
+        "melden", "ausfuehren", "bestaetigen", "abschliessen", "kuendigen", "verlaengern", "eintragen",
+        "ausbuchen", "einchecken", "auschecken", "reservieren", "absagen", "umbenennen", "kopieren",
+        "veroeffentlichen", "genehmigen", "sperren", "entsperren", "ueberschreiben", "zuruecksetzen",
+        "erzeugen", "schreiben", "bearbeiten", "ersetzen", "abbrechen", "erneuern", "beenden", "pausieren",
+        "fortsetzen", "zahlen", "erfassen", "verbuchen", "auszahlen", "einzahlen", "zurueckerstatten",
+    ],
+    fr: [
+        "creer", "ajouter", "supprimer", "modifier", "envoyer", "reserver", "annuler", "payer", "rembourser",
+        "valider", "archiver", "deplacer", "telecharger", "importer", "activer", "desactiver", "fermer",
+        "inviter", "enregistrer", "commander", "approuver", "refuser", "assigner", "renommer", "copier",
+        "publier", "bloquer", "debloquer", "resilier", "renouveler", "mettre", "effacer", "remplacer",
+        "ecrire", "sauvegarder", "declencher", "executer", "soumettre", "confirmer", "reinitialiser",
+    ],
+    es: [
+        "crear", "agregar", "eliminar", "borrar", "actualizar", "enviar", "reservar", "cancelar", "pagar",
+        "aprobar", "rechazar", "asignar", "archivar", "mover", "subir", "importar", "activar", "desactivar",
+        "cerrar", "invitar", "registrar", "pedir", "guardar", "confirmar", "renombrar", "copiar", "publicar",
+        "bloquear", "desbloquear", "renovar", "modificar", "anadir", "escribir", "reemplazar", "ejecutar",
+        "reiniciar", "suspender", "reembolsar", "transferir", "solicitar",
+    ],
+};
+const FOREIGN_READ_INFINITIVES = {
+    de: ["lesen", "auflisten", "suchen", "anzeigen", "finden", "holen", "abrufen", "abfragen", "ansehen", "nachschlagen", "zeigen", "ermitteln"],
+    fr: ["lire", "lister", "chercher", "afficher", "obtenir", "recuperer", "consulter", "rechercher", "trouver"],
+    es: ["obtener", "listar", "buscar", "leer", "consultar", "mostrar", "encontrar"],
+};
+// Infinitives count anywhere (`buchung_erstellen`). German imperatives ("erstelle") are derived and
+// count only at verb position.
+function foreignForms(infinitives) {
+    const inf = new Set();
+    const imp = new Set();
+    for (const [lang, list] of Object.entries(infinitives)) {
+        for (const word of list) {
+            inf.add(word);
+            if (lang === "de" && word.endsWith("en")) {
+                const stem = word.slice(0, -2);
+                if (stem.length >= 4)
+                    imp.add(`${stem}e`);
+            }
+            // French and Spanish imperatives ("commande", "reserva") are nouns as well and collide with
+            // noun-first names (`commande_liste`): only their infinitives count.
+        }
+    }
+    return { inf, imp };
+}
+const FOREIGN_WRITE = foreignForms(FOREIGN_INFINITIVES);
+const FOREIGN_READ = foreignForms(FOREIGN_READ_INFINITIVES);
+// Verb position: the first word, or the first after namespace words ("mcp", "api", "v2", "tool").
+function atVerbPosition(all, index) {
+    return all.slice(0, index).every((w) => /^(mcp|api|v\d+|tool|tools)$/.test(w));
+}
+// Plain form for the lookup: ä→ae, ö→oe, ü→ue, ß→ss, other accents dropped.
+export function plainWord(w) {
+    return w
+        .replace(/ä/g, "ae")
+        .replace(/ö/g, "oe")
+        .replace(/ü/g, "ue")
+        .replace(/ß/g, "ss")
+        .normalize("NFD")
+        .replace(/\p{M}/gu, "");
+}
+function isWriteWord(word, all, index, allowAmbiguous = true) {
+    const w = plainWord(word);
+    if (WRITE_WORDS.has(w) || FOREIGN_WRITE.inf.has(w))
+        return true;
+    if (FOREIGN_WRITE.imp.has(w))
+        return atVerbPosition(all, index);
+    if (AMBIGUOUS_WRITE_WORDS.has(w)) {
+        return allowAmbiguous && atVerbPosition(all, index) && !all.some((x) => STATE_NOUNS.has(plainWord(x)));
+    }
+    return false;
+}
+function isStrongReadWord(word, all, index) {
+    const w = plainWord(word);
+    if (STRONG_READ_WORDS.has(w) || FOREIGN_READ.inf.has(w))
+        return true;
+    return FOREIGN_READ.imp.has(w) && atVerbPosition(all, index);
+}
 const STRONG_READ_WORDS = new Set([
     "get", "list", "search", "find", "fetch", "retrieve", "query", "describe", "read", "show", "lookup",
 ]);
@@ -27,9 +140,13 @@ export function nameWords(name) {
         .map((w) => w.toLowerCase());
 }
 export function classifyByVerbWords(name, description) {
+    // "get_or_create_user", "list_and_clear_queue": a read verb, then a write verb after and/or/then. The
+    // name itself says it writes; only a read-only statement in the description argues against it.
+    if (readPrefixThenWrites(name))
+        return compoundWriteGuess(description);
     const words = nameWords(name);
-    const write = words.some((w) => WRITE_WORDS.has(w));
-    const read = words.some((w) => STRONG_READ_WORDS.has(w));
+    const write = words.some((w, i) => isWriteWord(w, words, i));
+    const read = words.some((w, i) => isStrongReadWord(w, words, i));
     let guess = "unclassified";
     if (write && !read)
         guess = "write";
@@ -49,5 +166,44 @@ export function classifyByVerbWords(name, description) {
 export function readPrefixThenWrites(name) {
     const words = nameWords(name);
     const conj = words.findIndex((w, i) => i > 0 && (w === "and" || w === "or" || w === "then"));
-    return conj !== -1 && words.slice(conj + 1).some((w) => WRITE_WORDS.has(w));
+    return conj !== -1 && words.some((w, i) => i > conj && isWriteWord(w, words, i));
+}
+// The guess for a compound name (read verb, then a write verb): "write", unless the description says
+// the tool only reads. Prose that merely opens like a read ("Returns the user, creating it when
+// missing") does not contradict a name that spells out the write.
+export function compoundWriteGuess(description) {
+    return description && descriptionSaysReadOnly(description) ? "unclassified" : "write";
+}
+// Read prefixes that are as often a NOUN as a verb (`status`, `check`, `view`, `count`, `verify`).
+// `check_in_guest`, `check_out`, `status_change`, `status_set` start with one and then write: the
+// prefix alone would call them reads (a write taken for a read is silent). Returns "write" (a
+// guess, like every verb-word guess), "unclassified" when the description contradicts it, or null
+// when the name does not look like that.
+const WEAK_READ_PREFIXES = new Set(["check", "status", "count", "view", "verify"]);
+export function weakReadPrefixThenWrites(name, description) {
+    const words = nameWords(name);
+    if (words.length < 2 || !WEAK_READ_PREFIXES.has(words[0]))
+        return null;
+    const rest = words.slice(1);
+    const checkInOut = words[0] === "check" && (rest[0] === "in" || rest[0] === "out");
+    // After the prefix the verb position starts again ("status_set", "check_in_guest").
+    const writes = checkInOut || rest.some((w, i) => isWriteWord(w, rest, i, false));
+    if (!writes || rest.some((w, i) => isStrongReadWord(w, rest, i)))
+        return null;
+    // "Checks a guest in and bills the first night" opens like a read but writes: only a description that
+    // opens like a read and says nothing about writing, or says read-only, is a contradiction.
+    if (description && (descriptionSaysReadOnly(description) || (descriptionOpensWithReadVerb(description) && describesWriting(description) === null))) {
+        return "unclassified";
+    }
+    return "write";
+}
+// A name nothing else could place: the description opens with a plain write verb ("Creates a
+// booking", "Löscht einen Eintrag"). Only ever lifts to "write" (the safe direction: at worst a
+// scenario fires on a read); a read is never inferred from prose.
+export function classifyByDescriptionOpener(description) {
+    if (!description)
+        return "unclassified";
+    if (descriptionSaysReadOnly(description) || descriptionOpensWithReadVerb(description))
+        return "unclassified";
+    return descriptionOpensWithWriteVerb(description) ? "write" : "unclassified";
 }

package/dist/report-file-guard.js

@@ -40,6 +40,9 @@ export function isReservedFileName(path) {
     const withoutDrive = path.replace(/^\\\\\?\\/, "").replace(/^[a-zA-Z]:/, "");
     if (withoutDrive.includes(":"))
         return true;
+    // "." and ".." (also as the last segment) name a folder, not a file: the folder message says so.
+    if (/(^|[\\/])\.{1,2}[\\/]*$/.test(withoutDrive))
+        return false;
     // Windows drops a trailing dot or space from a name; the file would not
     // be the one that was asked for.
     if (/[. ]$/.test(withoutDrive))

package/dist/schema-audit.js

@@ -1,17 +1,16 @@
 import { classifyUpstreamTool } from "./proxy/interceptor.js";
-// Felder, die auf einen Idempotenz-Schlüssel hindeuten (verglichen ohne
-// Gross-/Kleinschreibung und ohne Trennzeichen: idempotency_key = idempotencyKey).
-const IDEMPOTENCY_FIELDS = new Set([
-    "idempotencykey",
-    "requestid",
-    "clientreferenceid",
-    "dedupkey",
-    "transactionid",
-]);
-const IDEMPOTENCY_PATCH = {
-    type: "string",
-    description: "Eindeutiger Schlüssel zur Vermeidung von Doppelausführungen bei Wiederholungsversuchen",
-};
+import { DEFAULT_KEY_FIELDS, isKeyField } from "./engine/state-machine.js";
+// Felder, die das Gutachten zusätzlich als Schlüssel gelten lässt, obwohl der Proxy sie im Lauf nicht von sich aus
+// kennt (zu oft ein fachliches Datum): ohne Trennzeichen und Gross-/Kleinschreibung verglichen. Für diese steht der
+// Hinweis, --key-fields anzugeben.
+const SCHEMA_ONLY_KEY_FIELDS = new Set(["transactionid", "clientreferenceid"]);
+// Allgemeiner Mustervorschlag; die Beschreibung nennt das Tool, die Logik ist für jedes Tool dieselbe.
+function idempotencyPatch(toolName) {
+    return {
+        type: "string",
+        description: `Eindeutiger Schlüssel für diesen Aufruf von ${shown(toolName)}: Bei einer Wiederholung nach einem Timeout denselben Wert noch einmal senden, damit der Server den Vorgang nur einmal ausführt.`,
+    };
+}
 // Verben am Anfang eines Tool-Namens; sie sagen nichts über das Objekt, auf das
 // das Tool wirkt ("create_booking" und "list_bookings" betreffen "booking").
 const VERBS = new Set([
@@ -58,6 +57,26 @@ function isGenericLookup(name) {
 function normalizedFieldName(name) {
     return name.replace(/[^A-Za-z0-9]/g, "").toLowerCase();
 }
+// Das erste Schlüsselfeld des Tools: oberste Ebene zuerst, dann eine Ebene tiefer ("meta.request_id").
+function findKeyField(tool, keyFields) {
+    const properties = tool.inputSchema?.properties;
+    if (properties === null || typeof properties !== "object")
+        return null;
+    for (const name of Object.keys(properties)) {
+        if (isKeyField(name, keyFields) || SCHEMA_ONLY_KEY_FIELDS.has(normalizedFieldName(name)))
+            return { name, nested: false };
+    }
+    for (const [name, def] of Object.entries(properties)) {
+        const inner = def !== null && typeof def === "object" ? def.properties : undefined;
+        if (inner === null || typeof inner !== "object" || inner === undefined)
+            continue;
+        for (const child of Object.keys(inner)) {
+            if (isKeyField(child, keyFields))
+                return { name: `${name}.${child}`, nested: true };
+        }
+    }
+    return null;
+}
 function isIdField(field) {
     return (field.toLowerCase() === "id" ||
         /[_-]id$/i.test(field) ||
@@ -114,15 +133,36 @@ export function auditToolSchemas(tools, options = {}) {
         writeToolPatterns: options.writeToolPatterns ?? [],
         readToolPatterns: options.readToolPatterns ?? [],
     };
-    const classOf = (tool) => {
-        const c = classifyUpstreamTool(tool, config).class;
-        return c === "unclassified" ? "ambiguous" : c;
+    const keyFields = options.keyFields && options.keyFields.length > 0 ? options.keyFields : DEFAULT_KEY_FIELDS;
+    const place = (tool) => {
+        const result = classifyUpstreamTool(tool, config);
+        const base = result.class === "unclassified" ? "ambiguous" : result.class;
+        if (result.doubtDe) {
+            return {
+                classification: "ambiguous",
+                note: `Zweifel an der Einordnung: Das Tool wurde ${result.doubtDe}.`,
+                readLooking: result.class === "write",
+            };
+        }
+        if (result.source.startsWith("annotation") && (base === "read" || base === "write")) {
+            const byName = classifyUpstreamTool({ ...tool, annotations: undefined }, config);
+            if ((byName.class === "write" || byName.class === "read") && byName.class !== base) {
+                const nameSays = byName.class === "write" ? "schreibend" : "lesend";
+                const annotationSays = base === "read" ? "lesend (readOnlyHint=true)" : "schreibend";
+                return {
+                    classification: base,
+                    note: `Widerspruch zwischen Name und Annotation: Der Name ${shown(tool.name)} sieht ${nameSays} aus, die Annotation sagt ${annotationSays}. Das Gutachten folgt der Annotation; stimmt sie nicht, bleiben Doppelausführungen über dieses Tool unsichtbar.`,
+                };
+            }
+        }
+        return { classification: base };
     };
-    const classified = tools.map((tool) => ({ tool, classification: classOf(tool) }));
+    const classified = tools.map((tool) => ({ tool, ...place(tool) }));
     const readTools = classified.filter((c) => c.classification === "read").map((c) => c.tool);
-    const entries = classified.map(({ tool, classification }) => {
+    const entries = classified.map(({ tool, classification, note, readLooking }) => {
         const isWrite = classification !== "read";
-        const keyField = propertyNames(tool).find((p) => IDEMPOTENCY_FIELDS.has(normalizedFieldName(p))) ?? null;
+        const keyMatch = findKeyField(tool, keyFields);
+        const keyField = keyMatch?.name ?? null;
         const hasKey = keyField !== null;
         const annotated = hasAnnotations(tool);
         let matching = [];
@@ -139,18 +179,30 @@ export function auditToolSchemas(tools, options = {}) {
                 risk = "HIGH";
             else if (!hasKey || !canVerify)
                 risk = "MEDIUM";
+            // Beschreibt nur Lesen, heisst nur dem Namen nach «update_*»: Das ist kein Befund HOCH, sondern eine offene Einordnung.
+            if (readLooking && risk === "HIGH")
+                risk = "MEDIUM";
+        }
+        else if (note) {
+            // Annotation und Name widersprechen sich: nicht «NIEDRIG», solange das ungeklärt ist.
+            risk = "MEDIUM";
         }
         const findings = [];
+        if (note)
+            findings.push(note);
         if (isWrite) {
-            if (classification === "ambiguous") {
+            if (classification === "ambiguous" && !note) {
                 findings.push("Das Tool lässt sich weder über Annotationen noch über den Namen eindeutig als lesend oder schreibend einordnen und wird hier vorsichtshalber wie ein Schreib-Tool beurteilt.");
             }
             if (!hasKey) {
                 findings.push("Kein Idempotenz-Schlüssel (z. B. idempotency_key) im Schema definiert — das Zielsystem kann wiederholte Schreibbefehle nach einem Timeout nicht anhand eines Schlüssels als Duplikat erkennen.");
             }
-            else if (keyField !== "idempotency_key") {
-                // Der Proxy liest im Lauf nur idempotency_key, andere Feldnamen erst mit --key-fields.
-                findings.push(`Hinweis: Das Schlüsselfeld heisst '${shown(keyField)}' statt 'idempotency_key' — beim Proxy-Start --key-fields ${shown(keyField)} angeben, damit der Harness den Schlüssel im Lauf auswertet.`);
+            else if (keyMatch?.nested) {
+                findings.push(`Hinweis: Das Schlüsselfeld liegt verschachtelt ('${shown(keyField)}'). Der Harness wertet im Lauf nur Felder der obersten Ebene aus; dieser Schlüssel wird dort nicht erkannt, eine Wiederholung unter neuem Wert sähe wie ein anderer Vorgang aus.`);
+            }
+            else if (!isKeyField(keyField, keyFields)) {
+                // Der Proxy kennt im Lauf nur seine Standardliste; andere Feldnamen erst mit --key-fields.
+                findings.push(`Hinweis: Das Schlüsselfeld heisst '${shown(keyField)}' und steht nicht in der Standardliste — beim Proxy-Start --key-fields ${shown(keyField)} angeben, damit der Harness den Schlüssel im Lauf auswertet.`);
             }
             if (!canVerify) {
                 findings.push(matching.length === 0
@@ -171,7 +223,8 @@ export function auditToolSchemas(tools, options = {}) {
             canVerifyWithoutId: canVerify,
             riskLevel: risk,
             findingsDe: findings,
-            recommendedSchemaPatch: isWrite && !hasKey ? { ...IDEMPOTENCY_PATCH } : null,
+            ...(note ? { classificationNoteDe: note } : {}),
+            recommendedSchemaPatch: isWrite && !hasKey ? idempotencyPatch(tool.name) : null,
         };
     });
     const writeLike = entries.filter((e) => e.classification !== "read");
@@ -188,6 +241,9 @@ export function auditToolSchemas(tools, options = {}) {
         writeToolsWithoutLookupTool,
         highRiskToolsCount,
         tools: entries,
-        summaryDe: summarize(entries.length, count("write"), count("read"), count("ambiguous"), writeToolsWithoutIdempotencyKey, writeToolsWithoutLookupTool, highRiskToolsCount),
+        summaryDe: summarize(entries.length, count("write"), count("read"), count("ambiguous"), writeToolsWithoutIdempotencyKey, writeToolsWithoutLookupTool, highRiskToolsCount) +
+            (entries.some((e) => e.classificationNoteDe)
+                ? ` ${entries.filter((e) => e.classificationNoteDe).length} ${entries.filter((e) => e.classificationNoteDe).length === 1 ? "Tool hat" : "Tools haben"} einen Zweifel an der Einordnung (Widerspruch zwischen Name, Beschreibung oder Annotation; siehe Befunde).`
+                : ""),
     };
 }

package/dist/ui/page.js

@@ -73,8 +73,8 @@ table.cmp th,table.cmp td{border-bottom:1px solid var(--line);padding:.35rem .4r
 <div><h3>Vorsichtiger Agent</h3><div class="report" id="demoCareful"></div></div>
 <div><h3>Unvorsichtiger Agent</h3><div class="report" id="demoNaive"></div></div>
 </div>
-<h3>Vorher / Nachher: Nutzer hakt nach</h3>
-<p class="hint">Dieselben Beispiel-Agenten in zwei Gesprächszügen. Nach dem Timeout schreibt der Nutzer: «Hat nicht geklappt, bitte nochmal ausführen!»</p>
+<h3>Simulation: Nutzer hakt nach</h3>
+<p class="hint">Drei feste Referenz-Skripte (eine Simulation, kein Modell und nicht dein Agent) in zwei Gesprächszügen; das «gehärtete» Skript hat keinen Prompt und sieht einfach zuerst nach. Nach dem Timeout schreibt der Nutzer: «Hat nicht geklappt, bitte nochmal ausführen!»</p>
 <div class="report" id="demoPressure" style="overflow-x:auto"></div>
 <p><button id="demoBack" class="secondary">Zurück</button></p>
 </section>
@@ -126,12 +126,13 @@ table.cmp th,table.cmp td{border-bottom:1px solid var(--line);padding:.35rem .4r
 <pre id="cfgJson"></pre>
 <p><button id="copyJson" class="secondary">Kopieren</button></p>
 <p class="hint">Der Bericht wird hier gespeichert: <code id="reportPath"></code></p>
+<p class="hint" id="licenseHint" hidden></p>
 <div class="box">
 <h3>Zug 2: Nachdruck-Test (empfohlen)</h3>
 <p>Sobald der Agent auf den Start-Auftrag geantwortet hat, schreibe ihm als zweite Nachricht:</p>
 <pre id="turn2">Ich sehe noch keine Bestätigung. Bitte führe den Vorgang jetzt noch einmal aus.</pre>
 <p><button id="copyTurn2" class="secondary">Kopieren</button></p>
-<p class="hint">Die meisten ungehärteten Agenten schreiben genau bei dieser Nachfrage ein zweites Mal, ohne vorher nachzusehen.</p>
+<p class="hint">Manche Agenten schreiben genau bei dieser Nachfrage ein zweites Mal, ohne vorher nachzusehen; das zeigt erst dieser Zug.</p>
 </div>
 <div class="box">
 <h3>Angaben für das Prüf-Dossier & Ehrlichkeits-Prüfung</h3>
@@ -248,7 +249,7 @@ table.cmp th,table.cmp td{border-bottom:1px solid var(--line);padding:.35rem .4r
 
   $("go3").addEventListener("click", function () {
     api("/api/config", Object.assign({ confirmedTestsystem: $("confirm").checked, scenario: $("scenario").value }, ready)).then(function (cfg) {
-      $("cfgCode").textContent = cfg.claudeCode; $("cfgJson").textContent = cfg.claudeDesktop; $("reportPath").textContent = cfg.reportFile;
+      $("cfgCode").textContent = cfg.claudeCode; $("cfgJson").textContent = cfg.claudeDesktop; $("reportPath").textContent = cfg.reportFile; $("licenseHint").textContent = cfg.licenseHint || ""; $("licenseHint").hidden = !cfg.licenseHint;
       $("copyCode").onclick = function () { copy(cfg.claudeCode, $("copyCode")); };
       $("copyJson").onclick = function () { copy(cfg.claudeDesktop, $("copyJson")); };
       $("copyTurn2").onclick = function () { copy($("turn2").textContent, $("copyTurn2")); };