@zanii/blackbox 0.2.0 → 0.4.0

package/dist/analysis/hallucination.js

@@ -0,0 +1,357 @@
+// Tool hallucinations, checked exactly (spec/findings.md §8, H1): the agent calling a tool that
+// doesn't exist, with arguments its schema refuses, with a value it never saw; saying it worked
+// right after an error; quoting a tool it never called. Pure functions over the record, no model.
+// Mirrors sdks/python/src/zanii_blackbox/analysis/hallucination.py; pinned by
+// spec/vectors/hallucination.json.
+import { callsOf } from "../reconcile/record.js";
+import { canonical, isObj } from "../reconcile/shared.js";
+import { toolCallsOf, toolResultsOf } from "./detectors.js";
+const decoder = new TextDecoder();
+const f = (code, ref, detail) => ({
+    code,
+    source: "hallucination",
+    severity: "warning",
+    ref,
+    detail,
+});
+/** JSON, or the last JSON-RPC message of an SSE body. */
+function rpcOf(bytes) {
+    if (!bytes)
+        return undefined;
+    const text = decoder.decode(bytes);
+    const tries = [
+        text,
+        ...text
+            .split("\n")
+            .flatMap((l) => (l.startsWith("data:") ? [l.slice(5)] : []))
+            .reverse(),
+    ];
+    for (const t of tries) {
+        try {
+            const v = JSON.parse(t);
+            if (isObj(v))
+                return v;
+        }
+        catch { }
+    }
+    return undefined;
+}
+// ---------------------------------------------------------------- schemas (§8.2)
+/**
+ * The first way `value` breaks `schema`, or null. ponytail: the JSON Schema subset tools use
+ * (type, required, properties, additionalProperties: false, enum, items), not $ref or anyOf.
+ */
+export function schemaProblem(schema, value, path = "$") {
+    if (!isObj(schema))
+        return null;
+    if (Array.isArray(schema.enum) && !schema.enum.some((e) => canonical(e) === canonical(value)))
+        return `enum:${path}`;
+    const types = typeof schema.type === "string" ? [schema.type] : Array.isArray(schema.type) ? schema.type : [];
+    if (types.length > 0 && !types.some((t) => typeMatches(t, value)))
+        return `type:${path}`;
+    if (isObj(value)) {
+        const props = isObj(schema.properties) ? schema.properties : {};
+        for (const r of Array.isArray(schema.required) ? schema.required : [])
+            if (typeof r === "string" && !(r in value))
+                return `missing:${path}.${r}`;
+        for (const [k, v] of Object.entries(value)) {
+            if (k in props) {
+                const p = schemaProblem(props[k], v, `${path}.${k}`);
+                if (p)
+                    return p;
+            }
+            else if (schema.additionalProperties === false)
+                return `extra:${path}.${k}`;
+        }
+    }
+    if (Array.isArray(value) && isObj(schema.items))
+        for (const [i, v] of value.entries()) {
+            const p = schemaProblem(schema.items, v, `${path}[${i}]`);
+            if (p)
+                return p;
+        }
+    return null;
+}
+function typeMatches(type, v) {
+    switch (type) {
+        case "string":
+            return typeof v === "string";
+        case "number":
+            return typeof v === "number";
+        case "integer":
+            return typeof v === "number" && Number.isInteger(v);
+        case "boolean":
+            return typeof v === "boolean";
+        case "array":
+            return Array.isArray(v);
+        case "object":
+            return isObj(v);
+        case "null":
+            return v === null;
+        default:
+            return true;
+    }
+}
+/** A model request's declared tools: name → input schema (Anthropic, Chat Completions, Responses). */
+function declaredTools(request) {
+    const tools = Array.isArray(request?.tools) ? request.tools.filter(isObj) : [];
+    const out = new Map();
+    for (const t of tools) {
+        const fn = isObj(t.function) ? t.function : t;
+        if (typeof fn.name === "string")
+            out.set(fn.name, fn.input_schema ?? fn.parameters ?? t.input_schema ?? null);
+    }
+    return out.size > 0 ? out : null;
+}
+// ---------------------------------------------------------------- values the agent never saw (§8.3)
+const ARABIC_DIGITS = /[٠-٩۰-۹]/g;
+/** Arabic-Indic digits as Western ones. */
+export const western = (s) => s.replace(ARABIC_DIGITS, (d) => String((d.charCodeAt(0) & 0xf) % 10));
+/** Lower case, Western digits, and no separators, so `784-1990 1234567` matches `78419901234567`. */
+export function normaliseValue(s) {
+    return western(s)
+        .toLowerCase()
+        .replace(/[\s\-_./()+:,]/g, "");
+}
+const DATE = /^[0-9]{4}-[0-9]{2}-[0-9]{2}$|^[0-9]{2}-[0-9]{2}-[0-9]{4}$/;
+const VALUE_KINDS = [
+    ["email", /[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g],
+    ["iban", /\b[A-Z]{2}[0-9]{2}(?:[ ]?[A-Z0-9]){11,30}\b/g],
+    ["uuid", /\b[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\b/g],
+    ["reference", /\b[A-Za-z]{2,10}[-_]?[0-9]{3,}[A-Za-z0-9]*\b/g],
+    ["number", /(?<![A-Za-z0-9])\+?[0-9][0-9 -]{4,}[0-9](?![A-Za-z0-9])/g],
+];
+/** The identifying values in a string (Western digits) and where they are, skipping `taken` spans. */
+export function identifierSpans(s, taken = []) {
+    const out = [];
+    for (const [kind, re] of VALUE_KINDS)
+        for (const m of s.matchAll(re)) {
+            const at = m.index ?? 0;
+            const end = at + m[0].length;
+            if (taken.some(([a, b]) => at < b && end > a))
+                continue;
+            const norm = normaliseValue(m[0]);
+            // a date is something an agent makes up legitimately (today, a deadline): not an identifier
+            if (kind === "number" && (norm.replace(/[^0-9]/g, "").length < 6 || DATE.test(m[0])))
+                continue;
+            taken.push([at, end]);
+            out.push({ kind, value: norm, at, end });
+        }
+    return out;
+}
+/** Fields an agent fills in itself (detectors' volatile keys): their values are made, not recalled. */
+const GENERATED = new Set([
+    "timestamp",
+    "ts",
+    "time",
+    "date",
+    "request_id",
+    "requestId",
+    "nonce",
+    "uuid",
+    "trace_id",
+    "idempotency_key",
+    "idempotencyKey",
+]);
+/** The identifying values in tool arguments' strings: emails, IBANs, UUIDs, references, long
+ * numbers. ponytail: JSON numbers are skipped (counts, sizes, epoch times), as are generated fields. */
+export function identifiersIn(args, path = "$") {
+    const out = [];
+    const walk = (v, p) => {
+        if (out.length >= 50)
+            return;
+        if (typeof v === "string")
+            for (const x of identifierSpans(western(v)))
+                out.push({ kind: x.kind, path: p, value: x.value });
+        if (Array.isArray(v))
+            for (const [i, x] of v.entries())
+                walk(x, `${p}[${i}]`);
+        else if (isObj(v))
+            for (const k of Object.keys(v).sort())
+                if (!GENERATED.has(k))
+                    walk(v[k], `${p}.${k}`);
+    };
+    walk(args, path);
+    return out;
+}
+/** `1,250.50` → `1250.5`: no separators, leading or trailing zeros. */
+export function canonicalNumber(s) {
+    const [whole = "0", frac = ""] = s.replaceAll(",", "").split(".");
+    const w = whole.replace(/^0+(?=[0-9])/, "");
+    const f = frac.replace(/0+$/, "");
+    return f ? `${w}.${f}` : w;
+}
+// ---------------------------------------------------------------- answers (§8.4, §8.5)
+/** The answer's text: Anthropic and Chat Completions text blocks, Responses message items. */
+export function answerText(c) {
+    const parts = [];
+    for (const [, b] of [...c.blocks].sort(([x], [y]) => x - y))
+        if (b.type === "text" && typeof b.text === "string")
+            parts.push(b.text);
+    for (const item of c.items)
+        if (item.type === "message" && Array.isArray(item.content))
+            for (const p of item.content.filter(isObj))
+                if (typeof p.text === "string")
+                    parts.push(p.text);
+    return parts.join("\n");
+}
+const SUCCESS = /\b(?:successfully|succeeded|completed|all set|has been (?:sent|created|updated|processed|booked|transferred|refunded|cancell?ed|saved|deleted|submitted|approved|paid)|have (?:sent|created|updated|processed|booked|transferred|refunded|cancell?ed|saved|deleted|submitted|paid)|is (?:done|complete))\b|تم |بنجاح|اكتمل/i;
+const FAILURE = /\b(?:error|failed|fail|unable|couldn't|could not|can't|cannot|didn't|did not|not able|problem|issue)\b|خطأ|فشل|تعذر|لم /i;
+const CITES = "(?:called|ran|used|queried|checked|according to|the results? (?:of|from)|returned by|output of)";
+/** Right before a citation: it's not a claim that the tool ran ("I haven't called", "I could use"). */
+const NEGATED = /(?:not|n't|never|will|can|could|would|should|shall|may|might|to|if|before)\s*$/i;
+function escapeRe(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// ---------------------------------------------------------------- the findings
+/** spec/findings.md §8: UNKNOWN_TOOL, TOOL_ARGS_INVALID, FABRICATED_VALUE, SUCCESS_AFTER_ERROR,
+ * PHANTOM_RESULT, in record order. */
+export function toolHallucinations(lines, bodies) {
+    const calls = callsOf(lines, bodies);
+    const modelCalls = toolCallsOf(calls);
+    const results = toolResultsOf(calls, lines);
+    const events = lines.map((l) => JSON.parse(l));
+    const out = [];
+    const push = (at, finding) => out.push({ ...finding, at });
+    // the model side: each tool call against the request that produced it
+    const byEnd = new Map(calls.map((c) => [c.endSeq, c]));
+    const seenBy = new Map();
+    for (const t of modelCalls) {
+        const c = byEnd.get(t.seq);
+        if (!c)
+            continue;
+        const declared = declaredTools(c.request);
+        if (declared && !declared.has(t.tool)) {
+            push(t.seq, unknownTool(t.seq, t.tool, "model"));
+            continue;
+        }
+        const schema = declared?.get(t.tool);
+        const problem = typeof t.args === "string" ? "not_json" : schemaProblem(schema, t.args ?? {});
+        if (problem)
+            push(t.seq, argsInvalid(t.seq, t.tool, "model", problem));
+        let seen = seenBy.get(t.seq);
+        if (seen === undefined) {
+            seen = normaliseValue(c.request ? canonical(c.request) : "");
+            seenBy.set(t.seq, seen);
+        }
+        for (const v of identifiersIn(t.args))
+            if (!seen.includes(v.value))
+                push(t.seq, fabricated(t.seq, t.tool, "model", v));
+    }
+    // the gateway side: MCP calls against the server's listing and what came before
+    const listed = new Map();
+    const called = new Map(); // tool → first seq it was called at
+    // ponytail: the latest model request holds the conversation so far; tool results are added once
+    let request = "";
+    let toolText = "";
+    let sawModel = false;
+    for (const t of modelCalls)
+        if (!called.has(t.tool))
+            called.set(t.tool, t.seq);
+    for (const e of events) {
+        const m = e.meta;
+        const text = () => {
+            const b = bodies(e.body_hash);
+            return b ? decoder.decode(b) : "";
+        };
+        if (e.kind === "llm.request") {
+            sawModel = true;
+            request = normaliseValue(text());
+        }
+        else if (e.kind === "tool.result" && typeof m.server === "string" && isObj(m.tool_defs)) {
+            const tools = rpcOf(bodies(e.body_hash))?.result;
+            const schemas = new Map();
+            for (const name of Object.keys(m.tool_defs))
+                schemas.set(name, null);
+            if (isObj(tools) && Array.isArray(tools.tools))
+                for (const t of tools.tools.filter(isObj))
+                    if (typeof t.name === "string")
+                        schemas.set(t.name, t.inputSchema ?? null);
+            listed.set(m.server, schemas);
+            toolText += `\n${normaliseValue(text())}`;
+        }
+        else if (e.kind === "tool.result" || (e.kind === "sdk.event" && m.type === "tool.result")) {
+            toolText += `\n${normaliseValue(text())}`;
+        }
+        else if (e.kind === "sdk.event" && m.type === "tool.call" && typeof m.name === "string") {
+            if (!called.has(m.name))
+                called.set(m.name, e.seq);
+        }
+        else if (e.kind === "tool.call" && m.method === "tools/call" && typeof m.tool === "string") {
+            if (!called.has(m.tool))
+                called.set(m.tool, e.seq);
+            if (m.policy?.action === "deny")
+                continue;
+            const server = typeof m.server === "string" ? m.server : "";
+            const schemas = listed.get(server);
+            if (schemas && !schemas.has(m.tool)) {
+                push(e.seq, unknownTool(e.seq, m.tool, "mcp", server));
+                continue;
+            }
+            const params = rpcOf(bodies(e.body_hash))?.params;
+            const args = isObj(params) ? (params.arguments ?? {}) : {};
+            const problem = schemaProblem(schemas?.get(m.tool), args);
+            if (problem)
+                push(e.seq, argsInvalid(e.seq, m.tool, "mcp", problem, server));
+            // ponytail: without a recorded model request there's no input to compare with (SDK-only runs)
+            if (sawModel)
+                for (const v of identifiersIn(args))
+                    if (!request.includes(v.value) && !toolText.includes(v.value))
+                        push(e.seq, fabricated(e.seq, m.tool, "mcp", v, server));
+        }
+    }
+    // answers: success right after an error, and tools quoted that never ran
+    const known = new Set();
+    for (const c of [...calls].sort((a, b) => a.endSeq - b.endSeq)) {
+        for (const name of declaredTools(c.request)?.keys() ?? [])
+            known.add(name);
+        for (const [, schemas] of listed)
+            for (const name of schemas.keys())
+                known.add(name);
+        if (!c.complete || modelCalls.some((t) => t.seq === c.endSeq))
+            continue;
+        const text = answerText(c);
+        if (!text)
+            continue;
+        const last = results.filter((r) => r.seq <= c.requestSeq).at(-1);
+        if (last?.error && SUCCESS.test(text) && !FAILURE.test(text))
+            push(c.endSeq, {
+                code: "SUCCESS_AFTER_ERROR",
+                source: "hallucination",
+                severity: "warning",
+                ref: { seq: c.endSeq, error_seq: last.seq },
+                detail: "The agent said it worked right after its last tool call failed, with nothing succeeding in between.",
+            });
+        for (const name of [...known].sort()) {
+            if (name.length < 4)
+                continue;
+            const first = called.get(name);
+            if (first !== undefined && first < c.endSeq)
+                continue;
+            const cite = new RegExp(`${CITES}\\W+(?:the\\W+)?\`?${escapeRe(name)}\\b`, "i").exec(text);
+            if (cite && !NEGATED.test(text.slice(Math.max(0, cite.index - 16), cite.index)))
+                push(c.endSeq, {
+                    code: "PHANTOM_RESULT",
+                    source: "hallucination",
+                    severity: "warning",
+                    ref: { seq: c.endSeq, tool: name },
+                    detail: `The answer cites ${name}, which the agent never called before it: the result it quotes didn't come from that tool.`,
+                });
+        }
+    }
+    return out.sort((a, b) => a.at - b.at).map(({ at: _, ...rest }) => rest);
+}
+function unknownTool(seq, tool, via, server) {
+    return f("UNKNOWN_TOOL", { seq, tool, via, ...(server ? { server } : {}) }, via === "model"
+        ? `The model called ${tool}, which wasn't among the tools it was given.`
+        : `The agent called ${tool}, which the server ${server} never listed.`);
+}
+function argsInvalid(seq, tool, via, problem, server) {
+    return {
+        ...f("TOOL_ARGS_INVALID", { seq, tool, via, problem, ...(server ? { server } : {}) }, `The arguments to ${tool} don't fit its schema (${problem}).`),
+        severity: "caution",
+    };
+}
+function fabricated(seq, tool, via, v, server) {
+    return f("FABRICATED_VALUE", { seq, tool, via, kind: v.kind, path: v.path, ...(server ? { server } : {}) }, `The ${v.kind} at ${v.path} in the call to ${tool} appears nowhere the agent could have read it: no input or earlier tool result holds it.`);
+}

package/dist/analysis/index.d.ts

@@ -3,7 +3,13 @@ import { type DutyLimits } from "../duty/index.ts";
 import { type CompiledPolicy } from "../policy/index.ts";
 import { type PrecogModel } from "../precog/index.ts";
 import type { Envelope, Json } from "../verify/index.ts";
+import type { ReferencePack } from "./reference.ts";
+export { type Accuracy, detectorAccuracy, type Label, wilsonLow } from "./accuracy.ts";
+export { type AnswerClaims, answerClaims, answerCredential, type ClaimEntry, verifyAnswerCredential, } from "./credential.ts";
+export { answerRisk, answersOf, canonicalNumber, Evidence, type Fact, factsIn, type GroundedClaim, groundingFindings, groundingRequest, HOLD_TRIGGERS, judgeFindings, judgeRequest, modelGroundingFindings, parseGroundingAnswer, parseJudgeAnswer, } from "./grounding.ts";
+export { answerText, identifiersIn, normaliseValue, schemaProblem, toolHallucinations, } from "./hallucination.ts";
 export { type ClaimVerdict, type CriterionResult, checkFlightPlan, type Landing, landing, } from "./landing.ts";
+export { checkAgainstPacks, loadReferencePacks, packsFor, type ReferenceFact, type ReferencePack, type ReferenceVerdict, referenceContext, } from "./reference.ts";
 export { OUTCOMES, type Outcome, type OutcomeRollup, rollup, type WasteReason, type WasteReport, waste, } from "./waste.ts";
 export type Severity = "advisory" | "caution" | "warning";
 export interface Finding {
@@ -27,6 +33,10 @@ export interface AnalyzeOptions {
     policy?: CompiledPolicy;
     /** spec/precog.md §3: the early-failure model, for PRECOG_RISK (needs `prices`). */
     precog?: PrecogModel;
+    /** spec/governance.md §5: the walls model answers are checked against (WALL_CROSSED). */
+    walls?: readonly string[];
+    /** spec/findings.md §10: the reference packs answers are checked against (the session's tenant's). */
+    reference?: readonly ReferencePack[];
     /** Epoch ms; +Infinity = judge everything (a session being closed). Default: now. */
     now?: number;
     graceMs?: number;
@@ -41,6 +51,12 @@ export interface Ev extends Envelope {
 export declare function eventsOf(lines: readonly string[], bodies: AnalyzeOptions["bodies"]): Ev[];
 /** Every analysis, in spec order. */
 export declare function analyze(lines: readonly string[], options: AnalyzeOptions): Finding[];
+/**
+ * spec/approvals.md §2: the agent ran an approved tool with other arguments than the person saw.
+ * An SDK `tool.call` that names its `approval_id` carries the hash of what it ran (`args_sha256`);
+ * the `approval_request` carries the hash of what was asked. A difference is a finding.
+ */
+export declare function approvalArgsChanged(events: Ev[]): Finding[];
 /** spec/attestation.md §3: a re-run that printed something else than the model was given. */
 export declare function attestationFindings(events: readonly Ev[]): Finding[];
 /** spec/fleet.md §3: the agent's own near-miss reports. */
@@ -59,6 +75,13 @@ export declare function checkpointReplay(events: Ev[]): Finding[];
 export declare function orphanedToolCalls(events: Ev[], now: number): Finding[];
 /** N4 (idea R5): a LangGraph run in `exit` durability that ran tools. Once per session. */
 export declare function exitDurability(events: Ev[]): Finding[];
+/**
+ * spec/findings.md §1a: a tool's definition changed during the session (the MCP "rug pull"). Every
+ * definition the gateway saw is an observation: each `tools/list` answer's `tool_defs`, and each
+ * `tools/call`'s `tool_def` (the definition it was judged by). Per server and tool, the first one
+ * is the reference; a different one later is a finding, and becomes the new reference.
+ */
+export declare function toolChanged(events: Ev[]): Finding[];
 /** N6 (idea S3): the gateway refused a request that carried the session's own token. */
 export declare function tokenMisuse(events: Ev[]): Finding[];
 /** Stage 2 R3: a `verify` check that passed, then failed later in the run. */

package/dist/analysis/index.js

@@ -3,15 +3,25 @@
 import { approvalFindings } from "../approvals/index.js";
 import { automationSurprise } from "../authority/index.js";
 import { dutyFindings } from "../duty/index.js";
+import { financeFindings } from "../finance/index.js";
+import { healthFindings } from "../health/index.js";
 import { policyFindings } from "../policy/index.js";
 import { precogFindings } from "../precog/index.js";
 import { preflightFindings } from "../preflight/index.js";
 import { canonical } from "../reconcile/shared.js";
 import { undoFindings } from "../undo/index.js";
+import { wallFindings } from "../walls/index.js";
 import { detectors } from "./detectors.js";
+import { groundingFindings, judgeFindings } from "./grounding.js";
+import { toolHallucinations } from "./hallucination.js";
 import { flightPlan } from "./landing.js";
 import { memoryFindings } from "./memory.js";
+export { detectorAccuracy, wilsonLow } from "./accuracy.js";
+export { answerClaims, answerCredential, verifyAnswerCredential, } from "./credential.js";
+export { answerRisk, answersOf, canonicalNumber, Evidence, factsIn, groundingFindings, groundingRequest, HOLD_TRIGGERS, judgeFindings, judgeRequest, modelGroundingFindings, parseGroundingAnswer, parseJudgeAnswer, } from "./grounding.js";
+export { answerText, identifiersIn, normaliseValue, schemaProblem, toolHallucinations, } from "./hallucination.js";
 export { checkFlightPlan, landing, } from "./landing.js";
+export { checkAgainstPacks, loadReferencePacks, packsFor, referenceContext, } from "./reference.js";
 export { OUTCOMES, rollup, waste, } from "./waste.js";
 const decoder = new TextDecoder();
 /** Parses the lines once, attaching SDK event bodies. */
@@ -45,8 +55,12 @@ export function analyze(lines, options) {
         ...checkpointReplay(events),
         ...orphanedToolCalls(events, now),
         ...tokenMisuse(events),
+        ...toolChanged(events),
         ...verifyRegression(events),
         ...falseSuccess(events, now),
+        ...toolHallucinations(lines, options.bodies),
+        ...groundingFindings(lines, options.bodies, options.reference ?? []),
+        ...judgeFindings(lines, options.bodies),
         ...exitDurability(events),
         ...detectors(lines, {
             bodies: options.bodies,
@@ -56,12 +70,16 @@ export function analyze(lines, options) {
         }),
         ...flightPlan(events, lines, options.bodies),
         ...(options.policy ? policyFindings(lines, options.bodies, options.policy) : []),
+        ...(options.walls?.length ? wallFindings(lines, options.bodies, options.walls) : []),
         ...nearMisses(events),
         ...memoryFindings(events),
         ...attestationFindings(events),
         ...automationSurprise(lines),
         ...undoFindings(lines, options.bodies),
         ...approvalFindings(lines),
+        ...financeFindings(lines, options.bodies, now === Number.POSITIVE_INFINITY),
+        ...healthFindings(lines, options.bodies, now === Number.POSITIVE_INFINITY),
+        ...approvalArgsChanged(events),
         ...preflightFindings(lines),
         ...dutyFindings(lines, options.prices, options.duty),
         ...(options.precog && options.prices
@@ -69,6 +87,38 @@ export function analyze(lines, options) {
             : []),
     ];
 }
+/**
+ * spec/approvals.md §2: the agent ran an approved tool with other arguments than the person saw.
+ * An SDK `tool.call` that names its `approval_id` carries the hash of what it ran (`args_sha256`);
+ * the `approval_request` carries the hash of what was asked. A difference is a finding.
+ */
+export function approvalArgsChanged(events) {
+    const asked = new Map();
+    const out = [];
+    for (const e of events) {
+        if (e.kind === "control" &&
+            e.meta.action === "approval_request" &&
+            typeof e.meta.approval_id === "string" &&
+            typeof e.meta.args_sha256 === "string")
+            asked.set(e.meta.approval_id, e.meta.args_sha256);
+        if (e.kind !== "sdk.event" || e.meta.type !== "tool.call")
+            continue;
+        const id = e.data?.approval_id;
+        const ran = e.data?.args_sha256;
+        if (typeof id !== "string" || typeof ran !== "string")
+            continue;
+        const want = asked.get(id);
+        if (want !== undefined && want !== ran)
+            out.push({
+                code: "APPROVAL_ARGS_CHANGED",
+                source: "approval",
+                severity: "warning",
+                ref: { sdk_seq: e.meta.sdk_seq, approval_id: id },
+                detail: "The agent ran an approved tool with other arguments than the person approved.",
+            });
+    }
+    return out;
+}
 /** spec/attestation.md §3: a re-run that printed something else than the model was given. */
 export function attestationFindings(events) {
     return events
@@ -308,6 +358,49 @@ export function exitDurability(events) {
         },
     ];
 }
+/**
+ * spec/findings.md §1a: a tool's definition changed during the session (the MCP "rug pull"). Every
+ * definition the gateway saw is an observation: each `tools/list` answer's `tool_defs`, and each
+ * `tools/call`'s `tool_def` (the definition it was judged by). Per server and tool, the first one
+ * is the reference; a different one later is a finding, and becomes the new reference.
+ */
+export function toolChanged(events) {
+    const seen = new Map();
+    const out = [];
+    const observe = (seq, server, tool, def) => {
+        const key = `${server}\u0000${tool}`;
+        const before = seen.get(key);
+        seen.set(key, def);
+        if (before !== undefined && before !== def)
+            out.push({
+                code: "TOOL_CHANGED",
+                source: "detectors",
+                severity: "warning",
+                ref: { seq, server, tool, before, after: def },
+                detail: "A tool's description, schema or annotations changed after the agent first saw it: approvals and policy were judged on the old definition.",
+            });
+    };
+    for (const e of events) {
+        const server = e.meta.server;
+        if (typeof server !== "string")
+            continue;
+        const defs = e.meta.tool_defs;
+        if (e.kind === "tool.result" &&
+            typeof defs === "object" &&
+            defs !== null &&
+            !Array.isArray(defs))
+            for (const tool of Object.keys(defs).sort()) {
+                const def = defs[tool];
+                if (typeof def === "string")
+                    observe(e.seq, server, tool, def);
+            }
+        if (e.kind === "tool.call" &&
+            typeof e.meta.tool === "string" &&
+            typeof e.meta.tool_def === "string")
+            observe(e.seq, server, e.meta.tool, e.meta.tool_def);
+    }
+    return out;
+}
 /** N6 (idea S3): the gateway refused a request that carried the session's own token. */
 export function tokenMisuse(events) {
     return events

package/dist/analysis/memory.d.ts

@@ -8,6 +8,14 @@ export declare function memoryXrayOf(events: readonly Ev[], revokedElsewhere?: r
         seq: number;
         memory_id: string;
     }[];
+    chain?: {
+        ok: boolean;
+        length: number;
+        broken: Array<{
+            seq: number;
+            reason: string;
+        }>;
+    };
 };
 /** The findings part (this record's own revocations only). */
 export declare function memoryFindings(events: readonly Ev[]): Finding[];

package/dist/analysis/memory.js

@@ -1,16 +1,21 @@
 // The Memory X-ray (spec/agents.md §2). Mirrors analysis/memory.py.
+import { memoryChain } from "../memory/index.js";
 /** spec/agents.md §2, over parsed events (sdk.event bodies attached). */
 export function memoryXrayOf(events, revokedElsewhere = []) {
     const revoked = new Set(revokedElsewhere);
     const stale = [];
+    const entries = [];
     let writes = 0;
     let reads = 0;
     for (const e of events) {
         if (e.kind !== "sdk.event")
             continue;
         const d = e.data ?? {};
-        if (e.meta.type === "memory.write")
+        if (e.meta.type === "memory.write") {
             writes++;
+            if (d.entry && typeof d.entry === "object" && !Array.isArray(d.entry))
+                entries.push([e.seq, d.entry]);
+        }
         else if (e.meta.type === "memory.revoke" && typeof d.memory_id === "string")
             revoked.add(d.memory_id);
         else if (e.meta.type === "memory.read") {
@@ -20,14 +25,36 @@ export function memoryXrayOf(events, revokedElsewhere = []) {
                     stale.push({ seq: e.seq, memory_id: id });
         }
     }
-    return { writes, reads, revoked: [...revoked].sort(), stale_reads: stale };
+    const out = { writes, reads, revoked: [...revoked].sort(), stale_reads: stale };
+    if (entries.length > 0) {
+        // spec/agents.md §4: the Zanii memory chain the writes carry
+        const chain = memoryChain(entries.map(([, p]) => p));
+        out.chain = {
+            ok: chain.ok,
+            length: chain.length,
+            broken: chain.broken.map((b) => ({
+                seq: entries[b.index][0],
+                reason: b.reason,
+            })),
+        };
+    }
+    return out;
 }
 /** The findings part (this record's own revocations only). */
 export function memoryFindings(events) {
-    return memoryXrayOf(events).stale_reads.map((r) => ({
-        code: "REVOKED_MEMORY_READ",
-        source: "memory",
-        severity: "warning",
-        ref: { seq: r.seq, memory_id: r.memory_id },
-    }));
+    const xray = memoryXrayOf(events);
+    return [
+        ...xray.stale_reads.map((r) => ({
+            code: "REVOKED_MEMORY_READ",
+            source: "memory",
+            severity: "warning",
+            ref: { seq: r.seq, memory_id: r.memory_id },
+        })),
+        ...(xray.chain?.broken ?? []).map((b) => ({
+            code: "MEMORY_CHAIN_BROKEN",
+            source: "memory",
+            severity: "warning",
+            ref: { seq: b.seq, reason: b.reason },
+        })),
+    ];
 }