@jkudish/jev-mcp 0.5.0 → 0.6.0

package/dist/index.js

@@ -19,18 +19,28 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { choice, noul, score } from "@typesafe-ai/sdk";
 import { z } from "zod";
 import { createRequire } from "node:module";
-import { classificationDecision, claimAction, contradictsRecommendation, DECIDE_ESCAPE_HATCHES, DEFAULT_COMPOSITE_FLOOR, ensureUniqueIds, existsVerdict, hasNonEmptyEvidence, marginOf, MAX_CANDIDATES_DECIDE, MAX_CLASSES, MAX_ITEM_CHARS, MAX_ITEMS, MAX_REQUIREMENTS, MAX_CANDIDATES, MAX_CANDIDATE_CHARS, MAX_GATE_CLAIMS, MAX_GATE_EVIDENCE_CHARS, MAX_GATE_EVIDENCE_ITEMS, MAX_CLAIM_CHARS, MAX_REVIEW_DOC_CHARS, normalizeEvidence, rankCandidates, requireCompleteContext, resolvePolicyThresholds, REVIEW_WEIGHTS, reviewAction, reviewComposite, COMPARE_RELATIONS, ASPECT_RELATIONS, MAX_COMPARE_ASPECTS, MAX_EXTRACT_CANDIDATES, MAX_EXTRACT_CANDIDATE_CHARS, MAX_EXTRACT_FIELDS, MAX_EXTRACT_TOTAL_CHARS, MAX_RERANK_CANDIDATES, MAX_RERANK_TOTAL_CHARS, REGEX_TIMEOUT_MS, rerankByScore, RELATION_TO_VERDICT, screenRecommendation, truncate, verifyAction, VERIFY_CLAIM_CRITERIA, worstAction, } from "./lib.js";
+import { classificationDecision, claimAction, contradictsRecommendation, DECIDE_ESCAPE_HATCHES, DEFAULT_COMPOSITE_FLOOR, ensureUniqueIds, existsVerdict, hasNonEmptyEvidence, isRecord, marginOf, MAX_CANDIDATES_DECIDE, MAX_CLASSES, MAX_ITEM_CHARS, MAX_ITEMS, MAX_REQUIREMENTS, MAX_CANDIDATES, MAX_CANDIDATE_CHARS, PROBABILITY_SUM_TOLERANCE, SCORE_MEAN_TOLERANCE, MAX_GATE_CLAIMS, MAX_GATE_EVIDENCE_CHARS, MAX_GATE_EVIDENCE_ITEMS, MAX_CLAIM_CHARS, MAX_REVIEW_DOC_CHARS, normalizeEvidence, rankCandidates, requireCompleteContext, resolvePolicyThresholds, REVIEW_WEIGHTS, reviewAction, reviewComposite, COMPARE_RELATIONS, ASPECT_RELATIONS, MAX_COMPARE_ASPECTS, MAX_EXTRACT_CANDIDATES, MAX_EXTRACT_CANDIDATE_CHARS, MAX_EXTRACT_FIELDS, MAX_EXTRACT_TOTAL_CHARS, MAX_RERANK_CANDIDATES, MAX_RERANK_TOTAL_CHARS, REGEX_TIMEOUT_MS, rerankByScore, RELATION_TO_VERDICT, screenRecommendation, truncate, verifyAction, VERIFY_CLAIM_CRITERIA, worstAction, } from "./lib.js";
 const MODEL = process.env.JEV_MCP_MODEL ?? "jev-latest";
 // Resolved at runtime so the MCP handshake version always matches the package.
 const { version: packageVersion } = createRequire(import.meta.url)("../package.json");
 const server = new McpServer({ name: "jev-mcp", version: packageVersion });
 import { askJev as askProvider } from "./provider.js";
-async function askJev(state, questions) {
-    return askProvider(state, questions, MODEL);
+async function askJev(state, questions, signal) {
+    const result = await askProvider(state, questions, MODEL, signal);
+    // The typesafe SDK transport returns unchecked `answers: any`; a null or
+    // non-object envelope must not crash tools that index it. Normalize once
+    // here so every tool takes the same {}-to-invalid_response path. The
+    // compatible transport already rejects such envelopes itself.
+    return { ...result, answers: (isRecord(result.answers) ? result.answers : {}) };
 }
 const text = (payload) => ({
     content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
 });
+// Tool inputs are strict: unknown top-level keys are rejected instead of
+// silently stripped, so a client typos-as-error rather than typos-as-default.
+// Nested fixed-shape objects are strict for the same reason; `context`
+// deliberately stays an open record.
+const strictShape = (shape) => z.object(shape).strict();
 const evidenceSchema = z.union([
     z.string().describe("A single evidence document."),
     z
@@ -38,12 +48,13 @@ const evidenceSchema = z.union([
         id: z.string().optional().describe("Short identifier for this evidence item."),
         text: z.string().describe("The evidence text."),
     })
+        .strict()
         .describe("A single evidence item."),
     z
         .array(z.object({
         id: z.string().optional().describe("Short identifier for this evidence item (e.g. 'site-html', 'rfc-4.1.3')."),
         text: z.string().describe("The evidence text."),
-    }))
+    }).strict())
         .min(1)
         .describe("Multiple evidence items; each claim is also matched to the item it rests on."),
 ]);
@@ -51,7 +62,7 @@ const candidatesSchema = z
     .array(z.object({
     id: z.string().optional().describe("Short identifier for this candidate (e.g. a file path, note name, or line id)."),
     text: z.string().describe("The candidate's text."),
-}))
+}).strict())
     .min(1)
     .max(MAX_CANDIDATES)
     .describe(`Candidates to search. Up to ${MAX_CANDIDATES} in one call; texts are truncated at ${MAX_CANDIDATE_CHARS} chars.`);
@@ -65,7 +76,7 @@ server.registerTool("jev_verify", {
         "and whether the verdict stands on its own (auto) or needs human review. " +
         "Pattern: docs.typesafe.ai/cookbooks/citation_check. Pass reports, PR descriptions, or agent briefs as claims " +
         "and their cited sources, diffs, or documents as evidence.",
-    inputSchema: {
+    inputSchema: strictShape({
         claims: z.array(z.string()).min(1).describe("Claims to verify, e.g. individual factual statements from a report."),
         evidence: evidenceSchema,
         auto_accept: z
@@ -74,8 +85,8 @@ server.registerTool("jev_verify", {
             .max(1)
             .optional()
             .describe("Verdicts at or above this confidence stand automatically; below it they are flagged 'review'. Default 0.8."),
-    },
-}, async ({ claims, evidence: rawEvidence, auto_accept }) => {
+    }),
+}, async ({ claims, evidence: rawEvidence, auto_accept }, extra) => {
     const autoAccept = auto_accept ?? 0.8;
     const evidenceItems = typeof rawEvidence === "string"
         ? [{ id: "evidence", text: rawEvidence }]
@@ -102,20 +113,42 @@ server.registerTool("jev_verify", {
         claims: claimItems,
         evidence,
     };
-    const { answers, usage, provider, model } = await askJev(state, questions);
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
     const results = claimItems.map((claim) => {
         const relation = answers[`relation_${claim.id}`];
-        const source = answers[`source_${claim.id}`];
-        const confidence = relation?.confidence ?? null;
-        const verdict = RELATION_TO_VERDICT[relation?.choice] ?? "unknown";
+        const validated = validateChoiceAnswer(relation, Object.keys(RELATION_TO_VERDICT));
+        // source_* is optional auxiliary information, requested only for multiple
+        // evidence items. Its absence does not invalidate the relation verdict,
+        // but a present source must name a supplied evidence id (or "none").
+        const sourceKeys = [...evidence.map((e) => e.id), "none"];
+        const source = validateChoiceAnswer(answers[`source_${claim.id}`], sourceKeys);
+        const valid = validated && Object.hasOwn(RELATION_TO_VERDICT, validated.choice) &&
+            (relation.confidence == null || validated.confidence !== null);
+        const confidence = valid ? validated.confidence : null;
+        if (!valid) {
+            // A missing or malformed relation must not masquerade as an unsupported
+            // claim: surface it as invalid so callers can tell protocol failure
+            // apart from a real verdict.
+            return {
+                id: claim.id,
+                claim: claim.text,
+                verdict: "unknown",
+                probabilities: null,
+                confidence: null,
+                status: "invalid_response",
+                action: "review",
+                supporting_evidence: null,
+            };
+        }
+        const verdict = RELATION_TO_VERDICT[relation.choice];
         return {
             id: claim.id,
             claim: claim.text,
             verdict,
-            probabilities: relation?.probabilities ?? null,
+            probabilities: relation.probabilities ?? null,
             confidence,
             action: confidence === null ? "review" : verifyAction(confidence, autoAccept),
-            supporting_evidence: source?.choice && source.choice !== "none" ? source.choice : null,
+            supporting_evidence: source && source.choice !== "none" ? source.choice : null,
         };
     });
     return text({
@@ -142,7 +175,7 @@ server.registerTool("jev_screen", {
         "instructions aimed at an AI agent (prompt injection), whether it has substantive content, and (when a purpose " +
         "is given) whether it is relevant to the task. Returns a recommendation: pass | review | block | skip. " +
         "Pattern: docs.typesafe.ai/cookbooks/llm_guardrails.",
-    inputSchema: {
+    inputSchema: strictShape({
         text: z.string().min(1).describe("The content to screen, e.g. a fetched web page or pasted document."),
         purpose: z
             .string()
@@ -150,8 +183,8 @@ server.registerTool("jev_screen", {
             .describe("What the consuming agent is trying to do; enables a relevance judgment and the 'skip' action."),
         block_at: z.number().min(0).max(1).optional().describe("Injection probability at or above which content is blocked. Default 0.75."),
         review_at: z.number().min(0).max(1).optional().describe("Injection probability at or above which content is flagged for review. Default 0.25."),
-    },
-}, async ({ text: content, purpose, block_at, review_at }) => {
+    }),
+}, async ({ text: content, purpose, block_at, review_at }, extra) => {
     const blockAt = block_at ?? 0.75;
     const reviewAt = review_at ?? 0.25;
     const questions = {
@@ -171,11 +204,25 @@ server.registerTool("jev_screen", {
         });
     }
     const state = { content, purpose: purpose ?? null };
-    const { answers, usage, provider, model } = await askJev(state, questions);
-    const injection = answers.injection?.noul ?? 0;
-    const substance = answers.substance?.noul ?? undefined;
-    const relevance = purpose ? (answers.relevance?.noul ?? undefined) : undefined;
-    const recommendation = screenRecommendation({ injection, relevance, substance, blockAt, reviewAt });
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
+    const injection = validateNoulAnswer(answers.injection);
+    const substance = validateNoulAnswer(answers.substance);
+    const relevance = purpose ? validateNoulAnswer(answers.relevance) : undefined;
+    if (injection === null || substance === null || (purpose && relevance === null)) {
+        // A screening tool must fail closed: a missing or malformed answer must
+        // not be treated as a clean bill of health (injection ?? 0 would pass).
+        return text({
+            tool: "jev_screen",
+            model: model,
+            provider,
+            status: "invalid_response",
+            probabilities: { injection: injection ?? null, substance: substance ?? null, relevance: relevance ?? null },
+            thresholds: { block_at: blockAt, review_at: reviewAt },
+            recommendation: { action: "review", reason: "missing or malformed answers; cannot screen safely" },
+            usage,
+        });
+    }
+    const recommendation = screenRecommendation({ injection, relevance: relevance ?? undefined, substance, blockAt, reviewAt });
     return text({
         tool: "jev_screen",
         model: model,
@@ -196,12 +243,12 @@ server.registerTool("jev_find", {
         "any candidate addresses the query at all (so a confident 'top hit' cannot masquerade as an answer). " +
         "Pattern: docs.typesafe.ai/cookbooks/semantic_find. Use for 'which file/note/line covers X' across up to " +
         `${MAX_CANDIDATES} candidates.`,
-    inputSchema: {
+    inputSchema: strictShape({
         query: z.string().min(1).describe("What you are looking for, in natural language."),
         candidates: candidatesSchema,
         top_k: z.number().int().min(1).max(50).optional().describe("How many ranked candidates to return. Default 5."),
-    },
-}, async ({ query, candidates: rawCandidates, top_k }) => {
+    }),
+}, async ({ query, candidates: rawCandidates, top_k }, extra) => {
     const topK = top_k ?? 5;
     const { items: candidates } = ensureUniqueIds(rawCandidates.map((c) => ({ id: c.id ?? "", text: truncate(c.text, MAX_CANDIDATE_CHARS) })), "candidate");
     const criteria = Object.fromEntries(candidates.map((c) => [c.id, null]));
@@ -213,10 +260,26 @@ server.registerTool("jev_find", {
         }),
     };
     const state = { query, candidates };
-    const { answers, usage, provider, model } = await askJev(state, questions);
-    const probabilities = answers.best?.probabilities ?? {};
-    const ranked = rankCandidates(candidates, probabilities).slice(0, topK);
-    const exists = answers.exists?.noul ?? 0;
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
+    const exists = validateNoulAnswer(answers.exists);
+    const best = validateChoiceAnswer(answers.best, candidates.map((c) => c.id));
+    if (exists === null || best === null) {
+        // A missing exists/best answer must not be read as "no match" (exists ?? 0)
+        // or "no ranking": surface the protocol failure instead.
+        return text({
+            tool: "jev_find",
+            model: model,
+            provider,
+            query,
+            status: "invalid_response",
+            exists: exists ?? null,
+            exists_verdict: null,
+            top: [],
+            reason: "missing or malformed best or exists answer; cannot rank safely",
+            usage,
+        });
+    }
+    const ranked = rankCandidates(candidates, best.probabilities).slice(0, topK);
     return text({
         tool: "jev_find",
         model: model,
@@ -239,14 +302,14 @@ server.registerTool("jev_classify", {
         "and an auto-versus-review decision. Auto requires both a high top probability (default 0.85) and a " +
         "clear margin (default 0.50); everything else is flagged for review. Include a manual_review class " +
         "in the catalog if you want an explicit escape hatch; the tool never invents one.",
-    inputSchema: {
+    inputSchema: strictShape({
         items: z
-            .array(z.object({ id: z.string().optional(), text: z.string() }))
+            .array(z.object({ id: z.string().optional(), text: z.string() }).strict())
             .min(1)
             .max(MAX_ITEMS)
             .describe(`Items to classify. Text is truncated at ${MAX_ITEM_CHARS} characters; send bounded excerpts, not whole documents.`),
         classes: z
-            .array(z.object({ id: z.string().optional(), description: z.string() }))
+            .array(z.object({ id: z.string().optional(), description: z.string() }).strict())
             .min(2)
             .max(MAX_CLASSES)
             .describe("Shared class catalog. Strong descriptions carry the decision: a precise definition, " +
@@ -258,8 +321,8 @@ server.registerTool("jev_classify", {
             .describe("Shared context available to every item's judgment: policies, catalogs, anything stable."),
         auto_accept: z.number().min(0).max(1).optional().describe("Minimum top probability for auto. Default 0.85."),
         minimum_margin: z.number().min(0).max(1).optional().describe("Minimum winner-to-runner-up gap for auto. Default 0.5."),
-    },
-}, async ({ items: rawItems, classes: rawClasses, purpose, context, auto_accept, minimum_margin }) => {
+    }),
+}, async ({ items: rawItems, classes: rawClasses, purpose, context, auto_accept, minimum_margin }, extra) => {
     const autoAccept = auto_accept ?? 0.85;
     const minMargin = minimum_margin ?? 0.5;
     // Preserve caller IDs exactly; use opaque internal keys (i0/c0) for the
@@ -303,23 +366,11 @@ server.registerTool("jev_classify", {
     for (const item of items) {
         questions[item.key] = choice({ task: "Which class does this item belong to?", item: { id: item.key, text: item.text } }, criteria);
     }
-    const { answers, usage, provider, model } = await askJev(state, questions);
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
     const keyToExternal = new Map(classes.map((c) => [c.key, c.external]));
     const results = items.map((item) => {
-        const answer = answers[item.key];
-        const expected = new Set(classes.map((c) => c.key));
-        const probabilities = answer?.probabilities ?? {};
-        const keys = Object.keys(probabilities);
-        const values = Object.values(probabilities);
-        const sum = values.reduce((a, b) => a + b, 0);
-        const valid = answer &&
-            typeof answer.choice === "string" &&
-            expected.has(answer.choice) &&
-            keys.length >= expected.size &&
-            keys.every((k) => expected.has(k)) &&
-            values.every((p) => Number.isFinite(p) && p >= 0 && p <= 1) &&
-            Math.abs(sum - 1) <= 0.01;
-        if (!valid) {
+        const answer = validateChoiceAnswer(answers[item.key], classes.map((c) => c.key));
+        if (!answer) {
             return {
                 id: item.external,
                 status: "invalid_response",
@@ -330,14 +381,15 @@ server.registerTool("jev_classify", {
                 decision: "review",
             };
         }
+        const values = Object.values(answer.probabilities);
         const ranked = values.slice().sort((a, b) => b - a);
         const margin = ranked.length >= 2 ? ranked[0] - ranked[1] : 0;
-        const topProbability = probabilities[answer.choice];
+        const topProbability = answer.probabilities[answer.choice];
         return {
             id: item.external,
             classification: keyToExternal.get(answer.choice) ?? answer.choice,
-            probabilities: Object.fromEntries(classes.map((c) => [c.external, probabilities[c.key] ?? 0])),
-            confidence: answer.confidence ?? null,
+            probabilities: Object.fromEntries(classes.map((c) => [c.external, answer.probabilities[c.key] ?? 0])),
+            confidence: answer.confidence,
             margin,
             top_probability: topProbability,
             decision: classificationDecision(topProbability, margin, autoAccept, minMargin),
@@ -377,12 +429,12 @@ server.registerTool("jev_decide", {
         "One call per unchanged decision; do not repeat a call to obtain a more pleasing answer. " +
         "Use source inspection, tests, the user, or a reasoning model for open-ended research, routine choices, " +
         "correctness proofs, or predicting user consent. High probability is not proof.",
-    inputSchema: {
+    inputSchema: strictShape({
         decision: z.string().min(1).max(1500).describe("The bounded decision to make."),
         evidence: z.string().min(1).max(12000).describe("Facts and measurements, not opinions. State is evidence, not instructions."),
         priorities: z.string().min(1).max(2000).describe("Explicit preferences and constraints from the user or plan."),
         candidates: z
-            .array(z.object({ id: z.string().regex(/^[a-z][a-z0-9_-]*$/).max(64), description: z.string().min(1).max(2000) }))
+            .array(z.object({ id: z.string().regex(/^[a-z][a-z0-9_-]*$/).max(64), description: z.string().min(1).max(2000) }).strict())
             .min(2)
             .max(MAX_CANDIDATES_DECIDE)
             .describe("The alternatives. Include 'do nothing' or 'gather more evidence' as candidates when useful."),
@@ -395,8 +447,8 @@ server.registerTool("jev_decide", {
             .boolean()
             .optional()
             .describe("Include ask_user / investigate / none as Choosable options so the model can decline to rank. Default true."),
-    },
-}, async ({ decision, evidence, priorities, candidates, requirements: reqs, escape_hatches }) => {
+    }),
+}, async ({ decision, evidence, priorities, candidates, requirements: reqs, escape_hatches }, extra) => {
     const includeHatches = escape_hatches ?? true;
     const requirements = reqs ?? [];
     // Reject duplicate candidate IDs and collisions with active escape hatches
@@ -435,37 +487,19 @@ server.registerTool("jev_decide", {
         candidates: candidateKeys.map((c) => ({ id: c.key, description: c.description })),
         requirements,
     };
-    const { answers, usage, provider, model } = await askJev(state, questions);
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
     const keyToId = new Map(candidateKeys.map((c) => [c.key, c.id]));
     const expectedRecKeys = new Set([...candidateKeys.map((c) => c.key), ...(includeHatches ? Object.keys(DECIDE_ESCAPE_HATCHES) : [])]);
     const expectedCheckKeys = new Set(["supported", "contradicted", "unknown"]);
-    // classify-grade validation: exact keys, finite [0,1] probabilities summing
-    // to one, chosen key is the argmax, confidence finite or null. Malformed
-    // responses are never semantic outcomes.
-    const validateChoice = (answer, expected) => {
-        if (!answer || typeof answer.choice !== "string" || !expected.has(answer.choice))
-            return null;
-        const probabilities = answer.probabilities ?? {};
-        const keys = Object.keys(probabilities);
-        const values = Object.values(probabilities);
-        if (keys.length !== expected.size ||
-            !keys.every((k) => expected.has(k)) ||
-            !values.every((p) => Number.isFinite(p) && p >= 0 && p <= 1) ||
-            Math.abs(values.reduce((a, b) => a + b, 0) - 1) > 0.01 ||
-            // Choice contract: the chosen option must be the argmax.
-            probabilities[answer.choice] < Math.max(...values) - 1e-9)
-            return null;
-        const rawConfidence = answer.confidence;
-        const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) && rawConfidence >= 0 && rawConfidence <= 1
-            ? rawConfidence
-            : null;
-        return { choice: answer.choice, confidence, probabilities };
-    };
-    const rec = validateChoice(answers.recommendation, expectedRecKeys);
+    // classify-grade validation via the shared validateChoiceAnswer: exact
+    // keys, finite [0,1] probabilities summing to one within the shared
+    // tolerance, chosen key is the argmax, confidence finite or null.
+    // Malformed responses are never semantic outcomes.
+    const rec = validateChoiceAnswer(answers.recommendation, expectedRecKeys);
     const recProbabilities = rec?.probabilities ?? {};
     const recommendedKey = rec?.choice ?? null;
     const checks = candidateKeys.flatMap((c, i) => requirements.map((_, j) => {
-        const answer = validateChoice(answers[`check_${i}_${j}`], expectedCheckKeys);
+        const answer = validateChoiceAnswer(answers[`check_${i}_${j}`], expectedCheckKeys);
         return { candidate: c.id, requirement: j, answer: answer?.choice ?? "invalid_response" };
     }));
     const contradicted = recommendedKey && candidateKeySet.has(recommendedKey)
@@ -501,12 +535,12 @@ server.registerTool("jev_rerank", {
         "every candidate so the full ordering survives. TypeSafe's rerank cookbook reports that on the CLERC benchmark " +
         "this pattern lifted top-1 from 5% to 18% and top-10 from 38% to 62% (docs.typesafe.ai/cookbooks). " +
         `Use for retrieval ordering, dedup triage, or feed ranking across up to ${MAX_RERANK_CANDIDATES} candidates.`,
-    inputSchema: {
+    inputSchema: strictShape({
         query: z.string().min(1).max(2000).describe("What relevance is measured against, in natural language."),
         candidates: candidatesSchema,
         top_k: z.number().int().min(1).max(250).optional().describe("How many ranked candidates to return. Default: all."),
-    },
-}, async ({ query, candidates: rawCandidates, top_k }) => {
+    }),
+}, async ({ query, candidates: rawCandidates, top_k }, extra) => {
     const topK = top_k ?? null;
     // Caller IDs are preserved verbatim; opaque wire keys (classify pattern).
     // Duplicate supplied IDs are rejected rather than silently renamed, and
@@ -549,7 +583,7 @@ server.registerTool("jev_rerank", {
             false: "The candidate is about a different subject, or only shares vocabulary with the query",
         });
     });
-    const { answers, usage, provider, model } = await askJev(state, questions);
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
     // One invalid Noul makes the whole ordering untrustworthy; never sort a
     // missing answer as a confident zero.
     const scores = candidates.map((_, i) => {
@@ -597,7 +631,7 @@ server.registerTool("jev_compare", {
         "Optionally supply aspects (price, date, method, …) and each gets an independent per-aspect judgment " +
         "in the same single request. Use for source reconciliation, changelog-vs-code drift, or merge sanity checks. " +
         "The request supplies no evidence beyond the two passages, so a same_fact verdict means they agree with each other, not that they are true.",
-    inputSchema: {
+    inputSchema: strictShape({
         passage_a: z.string().min(1).max(20000).describe("First passage. Rejected above 20,000 characters."),
         passage_b: z.string().min(1).max(20000).describe("Second passage. Rejected above 20,000 characters."),
         aspects: z
@@ -608,8 +642,8 @@ server.registerTool("jev_compare", {
         purpose: z.string().optional().describe("What this comparison is for; helps disambiguate overlap."),
         auto_accept: z.number().min(0).max(1).optional().describe("Minimum top probability for auto. Default 0.85."),
         minimum_margin: z.number().min(0).max(1).optional().describe("Minimum winner-to-runner-up gap for auto. Default 0.5."),
-    },
-}, async ({ passage_a, passage_b, aspects: rawAspects, purpose, auto_accept, minimum_margin }) => {
+    }),
+}, async ({ passage_a, passage_b, aspects: rawAspects, purpose, auto_accept, minimum_margin }, extra) => {
     const autoAccept = auto_accept ?? 0.85;
     const minMargin = minimum_margin ?? 0.5;
     const aspects = rawAspects ?? [];
@@ -625,29 +659,12 @@ server.registerTool("jev_compare", {
         questions[`aspect_${i}`] = choice(`Judging only the aspect "${aspect}" of the two passages in the state, which relation holds?`, { ...ASPECT_RELATIONS });
     });
     const state = { purpose: purpose ?? null, passage_a: a, passage_b: b, aspects };
-    const { answers, usage, provider, model } = await askJev(state, questions);
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
     const expected = new Set(Object.keys(COMPARE_RELATIONS));
-    const validateChoice = (answer) => {
-        if (!answer || typeof answer.choice !== "string" || !expected.has(answer.choice))
-            return null;
-        const probabilities = answer.probabilities ?? {};
-        const keys = Object.keys(probabilities);
-        const values = Object.values(probabilities);
-        if (keys.length !== expected.size ||
-            !keys.every((k) => expected.has(k)) ||
-            !values.every((p) => Number.isFinite(p) && p >= 0 && p <= 1) ||
-            Math.abs(values.reduce((x, y) => x + y, 0) - 1) > 0.01 ||
-            // Choice contract: the chosen option must be the argmax.
-            probabilities[answer.choice] < Math.max(...values) - 1e-9)
-            return null;
-        const rawConfidence = answer.confidence;
-        const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) && rawConfidence >= 0 && rawConfidence <= 1
-            ? rawConfidence
-            : null;
-        return { choice: answer.choice, confidence, probabilities };
-    };
+    // classify-grade validation via the shared validateChoiceAnswer; the
+    // overall and aspect questions share the same three relation keys.
     const shape = (raw) => {
-        const answer = validateChoice(raw);
+        const answer = validateChoiceAnswer(raw, expected);
         if (!answer) {
             return {
                 relation: null,
@@ -739,7 +756,7 @@ server.registerTool("jev_extract", {
         "returned verbatim — never model-generated text. Fields with zero regex matches never reach the model " +
         "(not_found); if no field has matches, no API call is made. Ambiguous picks are flagged for review. Use for prices, dates, version numbers, " +
         "IDs, and anything with a recognizable shape; keep documents bounded.",
-    inputSchema: {
+    inputSchema: strictShape({
         document: z.string().min(1).max(50000).describe("The document to extract from. Rejected above 50,000 characters."),
         fields: z
             .array(z.object({
@@ -747,15 +764,15 @@ server.registerTool("jev_extract", {
             pattern: z.string().min(1).max(500).describe("JavaScript regex source (without delimiters) that matches candidate values. Runs in a sandboxed worker with a hard timeout."),
             flags: z.string().max(8).optional().describe("Regex flags (e.g. 'i'). 'g' is always added; non-letters are dropped."),
             description: z.string().min(1).max(2000).describe("What the field is, so Jev can pick the right candidate among regex matches."),
-        }))
+        }).strict())
             .min(1)
             .max(MAX_EXTRACT_FIELDS)
             .describe(`Fields to extract. Up to ${MAX_EXTRACT_FIELDS} per call, all judged in one request.`),
         purpose: z.string().optional().describe("What the extraction is for; shared across fields."),
         auto_accept: z.number().min(0).max(1).optional().describe("Minimum top probability for auto. Default 0.85."),
         minimum_margin: z.number().min(0).max(1).optional().describe("Minimum winner-to-runner-up gap for auto. Default 0.5."),
-    },
-}, async ({ document, fields: rawFields, purpose, auto_accept, minimum_margin }) => {
+    }),
+}, async ({ document, fields: rawFields, purpose, auto_accept, minimum_margin }, extra) => {
     const autoAccept = auto_accept ?? 0.85;
     const minMargin = minimum_margin ?? 0.5;
     const doc = truncate(document, 50000);
@@ -802,7 +819,7 @@ server.registerTool("jev_extract", {
         questions[f.key] = choice(`Which candidate is the correct value of the field "${f.id}" (${f.description}) in the document in the state? Pick the exact substring the document presents as this field's value.`, criteria);
         stateFields.push({ id: f.key, description: f.description, pattern: f.pattern });
     }
-    const { answers, usage, provider, model } = stateFields.length > 0 ? await askJev({ purpose: purpose ?? null, document: doc, fields: stateFields }, questions) : { answers: {}, usage: null, provider: "none", model: MODEL };
+    const { answers, usage, provider, model } = stateFields.length > 0 ? await askJev({ purpose: purpose ?? null, document: doc, fields: stateFields }, questions, extra.signal) : { answers: {}, usage: null, provider: "none", model: MODEL };
     const results = fields.map((f) => {
         const flags = { candidates_truncated: f.truncated, matches_skipped_too_long: f.tooLong };
         // An incomplete candidate universe (capped or overlong-skipped matches)
@@ -829,7 +846,7 @@ server.registerTool("jev_extract", {
             keys.length === expectedKeys.size &&
             keys.every((k) => expectedKeys.has(k)) &&
             values.every((p) => Number.isFinite(p) && p >= 0 && p <= 1) &&
-            Math.abs(values.reduce((x, y) => x + y, 0) - 1) <= 0.01 &&
+            Math.abs(values.reduce((x, y) => x + y, 0) - 1) <= PROBABILITY_SUM_TOLERANCE &&
             probabilities[answer.choice] >= Math.max(...values) - 1e-9;
         if (!valid) {
             return { id: f.id, value: null, status: "invalid_response", reason: null, candidates_considered: f.candidates.length, ...flags };
@@ -920,6 +937,13 @@ function reviewQuestions(extraFraming = "") {
 }
 // Score contract: a finite score within the 0..2 rubric and confidence finite
 // or null. Malformed responses are never semantic outcomes.
+// Score questions always offer exactly three options (0, 1, 2).
+const SCORE_OPTION_KEYS = ["0", "1", "2"];
+// Score contract: a finite 0..2 score, plus, when a distribution is present
+// at all, an exact three-key distribution over the option scores summing to
+// one whose expected value matches the reported score. A distribution the
+// provider did not report stays null (still valid); a malformed or
+// contradictory one invalidates the answer.
 function validateScoreAnswer(answer) {
     const a = answer;
     if (!a || typeof a.score !== "number" || !Number.isFinite(a.score) || a.score < 0 || a.score > 2)
@@ -927,7 +951,46 @@ function validateScoreAnswer(answer) {
     const confidence = typeof a.confidence === "number" && Number.isFinite(a.confidence) && a.confidence >= 0 && a.confidence <= 1
         ? a.confidence
         : null;
-    return { score: a.score, confidence };
+    if (a.probabilities == null)
+        return { score: a.score, confidence, probabilities: null };
+    if (!isRecord(a.probabilities))
+        return null;
+    const probabilities = a.probabilities;
+    const keys = Object.keys(probabilities);
+    const values = Object.values(probabilities);
+    const expected = new Set(SCORE_OPTION_KEYS);
+    if (keys.length !== expected.size ||
+        !keys.every((key) => expected.has(key)) ||
+        !values.every((p) => typeof p === "number" && Number.isFinite(p) && p >= 0 && p <= 1) ||
+        Math.abs(values.reduce((x, y) => x + y, 0) - 1) > PROBABILITY_SUM_TOLERANCE) {
+        return null;
+    }
+    const mean = SCORE_OPTION_KEYS.reduce((sum, key) => sum + Number(key) * probabilities[key], 0);
+    if (Math.abs(mean - a.score) > SCORE_MEAN_TOLERANCE)
+        return null;
+    return { score: a.score, confidence, probabilities };
+}
+// Choice contract: exact candidate keys, finite [0,1] probabilities summing
+// to one within PROBABILITY_SUM_TOLERANCE, and a choice tied for the maximum
+// probability.
+function validateChoiceAnswer(answer, expectedKeys) {
+    if (!isRecord(answer) || typeof answer.choice !== "string" || !isRecord(answer.probabilities))
+        return null;
+    const expected = new Set(expectedKeys);
+    // Shape is enforced by the isRecord guards above and the finite [0,1] check below.
+    const probabilities = answer.probabilities;
+    const keys = Object.keys(probabilities);
+    const values = Object.values(probabilities);
+    if (!expected.has(answer.choice) || keys.length !== expected.size ||
+        !keys.every((key) => expected.has(key)) ||
+        !values.every((p) => typeof p === "number" && Number.isFinite(p) && p >= 0 && p <= 1) ||
+        Math.abs(values.reduce((a, b) => a + b, 0) - 1) > PROBABILITY_SUM_TOLERANCE ||
+        probabilities[answer.choice] < Math.max(...values) - 1e-9)
+        return null;
+    const confidence = typeof answer.confidence === "number" && Number.isFinite(answer.confidence) && answer.confidence >= 0 && answer.confidence <= 1
+        ? answer.confidence
+        : null;
+    return { choice: answer.choice, probabilities, confidence };
 }
 // Noul contract: a finite probability in [0,1].
 function validateNoulAnswer(answer) {
@@ -946,7 +1009,7 @@ function projectReviewHalf(answers, thresholds, truncated) {
     for (const key of rubrics) {
         const parsed = validateScoreAnswer(answers[key]);
         if (!parsed) {
-            scores[key] = { score: null, confidence: null, status: "invalid_response" };
+            scores[key] = { score: null, confidence: null, probabilities: null, status: "invalid_response" };
             invalid = true;
         }
         else {
@@ -964,8 +1027,26 @@ function projectReviewHalf(answers, thresholds, truncated) {
         thresholds: { auto_accept: thresholds.autoAccept, review_at: thresholds.reviewAt, composite_floor: thresholds.compositeFloor },
     };
     if (invalid) {
-        return { ...base, action: "escalate", status: "invalid_response", composite: null };
+        return {
+            ...base,
+            action: "escalate",
+            status: "invalid_response",
+            composite: null,
+            reason_codes: ["invalid_response"],
+            limiting_rubrics: [],
+        };
     }
+    // Per-rubric favorability: the normalized 0..1 contribution each rubric
+    // makes to the composite (test gap and blast radius inverted), used to name
+    // the limiting rubric(s) when the composite is what blocks auto.
+    const favorability = {
+        correctness: valid.correctness.score / 2,
+        spec_match: valid.spec_match.score / 2,
+        test_gap: 1 - valid.test_gap.score / 2,
+        blast_radius: 1 - valid.blast_radius.score / 2,
+    };
+    const favorabilities = rubrics.map((r) => favorability[r]);
+    const minFavorability = Math.min(...favorabilities);
     const composite = reviewComposite({
         correctness: valid.correctness.score,
         specMatch: valid.spec_match.score,
@@ -976,8 +1057,46 @@ function projectReviewHalf(answers, thresholds, truncated) {
     // number that can satisfy a threshold (a bare zero would, at auto_accept 0).
     const rubricConfidences = rubrics.map((r) => valid[r].confidence);
     const minConfidence = rubricConfidences.some((c) => c === null) ? null : Math.min(...rubricConfidences);
-    const action = requireCompleteContext(reviewAction({ composite, safeToApply: safeToApply, minConfidence, ...thresholds }), truncated);
-    return { ...base, action, composite };
+    const rawAction = reviewAction({ composite, safeToApply: safeToApply, minConfidence, ...thresholds });
+    const action = requireCompleteContext(rawAction, truncated);
+    // Reason codes cover every action path; limiting_rubrics names the rubric(s)
+    // that bound the decision: the null-confidence ones when confidence is
+    // unknown, every rubric tied at the minimum confidence when confidence is
+    // what blocks, and every rubric tied at the minimum favorability when the
+    // composite floor is what blocks (ties always included, never a lone winner).
+    const reasonCodes = [];
+    let limitingRubrics = [];
+    if (minConfidence === null) {
+        reasonCodes.push("unknown_confidence");
+        limitingRubrics = rubrics.filter((r) => valid[r].confidence === null);
+    }
+    else if (minConfidence < thresholds.reviewAt) {
+        reasonCodes.push("confidence_below_review");
+        limitingRubrics = rubrics.filter((r) => valid[r].confidence === minConfidence);
+    }
+    if (safeToApply !== null && safeToApply < thresholds.reviewAt)
+        reasonCodes.push("safe_to_apply_below_review");
+    if (rawAction !== "escalate") {
+        if (safeToApply !== null && safeToApply < thresholds.autoAccept)
+            reasonCodes.push("safe_to_apply_below_auto_accept");
+        if (minConfidence !== null && minConfidence < thresholds.autoAccept) {
+            reasonCodes.push("confidence_below_auto_accept");
+            if (limitingRubrics.length === 0)
+                limitingRubrics = rubrics.filter((r) => valid[r].confidence === minConfidence);
+        }
+        if (composite < thresholds.compositeFloor) {
+            reasonCodes.push("composite_below_floor");
+            // Tolerant equality: complementary scores (0.6 vs 1.4) are
+            // mathematically tied but differ by a float ulp after inversion.
+            if (limitingRubrics.length === 0)
+                limitingRubrics = rubrics.filter((r) => Math.abs(favorability[r] - minFavorability) <= 1e-12);
+        }
+    }
+    if (truncated)
+        reasonCodes.push("incomplete_context");
+    if (action === "auto")
+        reasonCodes.push("accepted");
+    return { ...base, action, composite, reason_codes: reasonCodes, limiting_rubrics: limitingRubrics };
 }
 server.registerTool("jev_review", {
     title: "Review a proposed patch",
@@ -987,7 +1106,7 @@ server.registerTool("jev_review", {
         "safe_to_apply and min score confidence at auto_accept and the composite at composite_floor; truncated or " +
         "malformed input never returns auto. Does not apply the patch or run tests. " +
         "Use jev_gate to also verify completion claims against evidence in the same call.",
-    inputSchema: {
+    inputSchema: strictShape({
         request: z.string().min(1).describe("What the user asked for; this frames the review, it is not proof of anything."),
         diff: z
             .string()
@@ -1012,8 +1131,8 @@ server.registerTool("jev_review", {
             .max(1)
             .optional()
             .describe("Weighted composite at or above this is required for auto. Default 0.7."),
-    },
-}, async ({ request, diff, tests, auto_accept, review_at, composite_floor }) => {
+    }),
+}, async ({ request, diff, tests, auto_accept, review_at, composite_floor }, extra) => {
     const { autoAccept, reviewAt } = resolvePolicyThresholds(auto_accept ?? 0.8, review_at);
     const compositeFloor = composite_floor ?? DEFAULT_COMPOSITE_FLOOR;
     const truncated = request.length > MAX_REVIEW_DOC_CHARS ||
@@ -1025,7 +1144,7 @@ server.registerTool("jev_review", {
         diff: truncate(diff, MAX_REVIEW_DOC_CHARS),
         tests: tests ? truncate(tests, MAX_REVIEW_DOC_CHARS) : null,
     };
-    const { answers, usage, provider, model } = await askJev(state, reviewQuestions());
+    const { answers, usage, provider, model } = await askJev(state, reviewQuestions(), extra.signal);
     return text({
         tool: "jev_review",
         model,
@@ -1044,7 +1163,7 @@ server.registerTool("jev_gate", {
         "evidence. Evidence is capped at 16 items and 200,000 characters in aggregate. " +
         "Does not run tests or apply changes. Use jev_review for a patch without claims, jev_verify for " +
         "claims without a patch review.",
-    inputSchema: {
+    inputSchema: strictShape({
         request: z.string().min(1).describe("What the user asked for; this is not evidence of completion."),
         diff: z
             .string()
@@ -1077,8 +1196,8 @@ server.registerTool("jev_gate", {
             .max(1)
             .optional()
             .describe("Weighted composite at or above this is required for auto. Default 0.7."),
-    },
-}, async ({ request, diff, claims, evidence: rawEvidence, tests, auto_accept, review_at, composite_floor }) => {
+    }),
+}, async ({ request, diff, claims, evidence: rawEvidence, tests, auto_accept, review_at, composite_floor }, extra) => {
     const { autoAccept, reviewAt } = resolvePolicyThresholds(auto_accept ?? 0.8, review_at);
     const compositeFloor = composite_floor ?? DEFAULT_COMPOSITE_FLOOR;
     const evidence = normalizeEvidence(rawEvidence);
@@ -1124,31 +1243,14 @@ server.registerTool("jev_gate", {
             "diff and tests belong to the separate patch review. If a claim needs a diff or test log as support, it " +
             "must be supplied in evidence." + ANTI_INJECTION, VERIFY_CLAIM_CRITERIA);
     });
-    const { answers, usage, provider, model } = await askJev(state, questions);
+    const { answers, usage, provider, model } = await askJev(state, questions, extra.signal);
     const review = projectReviewHalf(answers, { autoAccept, reviewAt, compositeFloor }, truncated);
-    // classify-grade validation: exact keys, finite [0,1] probabilities summing
-    // to one, chosen key is the argmax, confidence finite or null.
+    // classify-grade validation via the shared validateChoiceAnswer: exact
+    // keys, finite [0,1] probabilities summing to one within the shared
+    // tolerance, chosen key is the argmax, confidence finite or null.
     const expectedClaimKeys = new Set(Object.keys(VERIFY_CLAIM_CRITERIA));
-    const validateChoice = (answer) => {
-        if (!answer || typeof answer.choice !== "string" || !expectedClaimKeys.has(answer.choice))
-            return null;
-        const probabilities = answer.probabilities ?? {};
-        const keys = Object.keys(probabilities);
-        const values = Object.values(probabilities);
-        if (keys.length !== expectedClaimKeys.size ||
-            !keys.every((k) => expectedClaimKeys.has(k)) ||
-            !values.every((p) => Number.isFinite(p) && p >= 0 && p <= 1) ||
-            Math.abs(values.reduce((a, b) => a + b, 0) - 1) > 0.01 ||
-            probabilities[answer.choice] < Math.max(...values) - 1e-9)
-            return null;
-        const rawConfidence = answer.confidence;
-        const confidence = typeof rawConfidence === "number" && Number.isFinite(rawConfidence) && rawConfidence >= 0 && rawConfidence <= 1
-            ? rawConfidence
-            : null;
-        return { choice: answer.choice, confidence, probabilities };
-    };
     const results = claims.map((claim, i) => {
-        const answer = validateChoice(answers[`claim_${i}`]);
+        const answer = validateChoiceAnswer(answers[`claim_${i}`], expectedClaimKeys);
         if (!answer) {
             return {
                 claim,
@@ -1181,6 +1283,13 @@ server.registerTool("jev_gate", {
         reasonCodes.push("incomplete_context");
     if (review.status === "invalid_response" || verification.summary.invalid_response > 0)
         reasonCodes.push("invalid_response");
+    // The review half's specific reason codes (unknown confidence, threshold
+    // and composite misses, safe_to_apply) surface at the top level too, so a
+    // gate consumer never has to open review.reason_codes to learn why.
+    for (const code of review.reason_codes) {
+        if (code !== "invalid_response" && code !== "incomplete_context" && code !== "accepted")
+            reasonCodes.push(code);
+    }
     if (review.action === "escalate")
         reasonCodes.push("review_escalated");
     if (review.action === "review")