codex-plugin-doctor 1.63.0 → 1.65.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Furkan Tasci
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Furkan Tasci
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -109,6 +109,23 @@ tool, and finding limits. It does not establish server inventory completeness or
 execute tools. See [Offline MCP Tool Definitions](docs/guides/offline-tool-definitions.md)
 for the accepted input format, coverage, and exit codes.
 
+### Offline MCP Tool Diff
+
+Compare two saved tool-list responses before updating a server or client:
+
+```bash
+codex-plugin-doctor doctor tools-diff --before ./tools-old.json --after ./tools-new.json --json
+```
+
+This reports added, removed, and structurally changed definitions using numeric
+locations, and labels each change `breaking`, `compatible`, or `unclassified`
+with fixed reason codes. Add `--fail-on breaking` to fail CI only on breaking or
+unclassified changes. Incomplete inputs, invalid definitions, or duplicate names
+prevent a comparison. Impact labels are root-level schema heuristics, not proof
+of compatibility.
+See [Offline MCP Tool Diff](docs/guides/offline-tool-diff.md) for matching rules,
+privacy, limits, and exit codes.
+
 ### HTTP MCP Tool Catalog
 
 Inspect a modern HTTP MCP server's tool definitions without invoking them:
@@ -541,9 +558,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.63.0
+      - uses: Esquetta/CodexPluginDoctor@v1.65.0
         with:
-          version: "1.63.0"
+          version: "1.65.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-tool-diff.d.ts

@@ -0,0 +1,38 @@
+import { type ToolChangeImpact, type ToolChangeReason } from "./mcp-tool-impact.js";
+import { type McpToolFileReport } from "./mcp-tool-file.js";
+type DiffField = "inputSchema" | "outputSchema" | "description" | "title" | "annotations" | "other";
+export interface McpToolDiffReport {
+    schemaVersion: 1;
+    scope: "tool-definitions-diff";
+    status: "pass" | "warn" | "incomplete" | "blocked";
+    before: McpToolFileReport;
+    after: McpToolFileReport;
+    comparison: {
+        complete: boolean;
+        reason: "input-blocked" | "input-incomplete" | "invalid-definitions" | "ambiguous-names" | null;
+        added: number | null;
+        removed: number | null;
+        changed: number | null;
+        unchanged: number | null;
+        breaking: number | null;
+        unclassified: number | null;
+    };
+    coverage: {
+        comparison: "structural-only";
+        schema: "root-shape-only";
+        compatibility: "not-tested";
+        serverCatalog: "not-tested";
+        toolExecution: "not-tested";
+        impactClassification: "heuristic";
+    };
+    changes: Array<{
+        kind: "added" | "removed" | "changed";
+        beforeToolIndex: number | null;
+        afterToolIndex: number | null;
+        fields: DiffField[];
+        impact: ToolChangeImpact;
+        reasons: ToolChangeReason[];
+    }>;
+}
+export declare function compareMcpToolFiles(beforePath: string, afterPath: string): Promise<McpToolDiffReport>;
+export {};

package/dist/core/mcp-tool-diff.js

@@ -0,0 +1,168 @@
+import { classifyAddedTool, classifyChangedTool, classifyRemovedTool } from "./mcp-tool-impact.js";
+import { loadMcpToolFileSnapshot } from "./mcp-tool-file.js";
+const FIXED_FIELDS = [
+    "inputSchema",
+    "outputSchema",
+    "description",
+    "title",
+    "annotations"
+];
+const EXCLUDED_OTHER_FIELDS = new Set(["name", ...FIXED_FIELDS]);
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function structurallyEqual(left, right) {
+    const pending = [[left, right]];
+    while (pending.length > 0) {
+        const [currentLeft, currentRight] = pending.pop();
+        if (Object.is(currentLeft, currentRight))
+            continue;
+        if (Array.isArray(currentLeft) || Array.isArray(currentRight)) {
+            if (!Array.isArray(currentLeft) || !Array.isArray(currentRight) || currentLeft.length !== currentRight.length)
+                return false;
+            for (let index = 0; index < currentLeft.length; index += 1)
+                pending.push([currentLeft[index], currentRight[index]]);
+            continue;
+        }
+        if (!isJsonObject(currentLeft) || !isJsonObject(currentRight))
+            return false;
+        const leftKeys = Object.keys(currentLeft);
+        const rightKeys = Object.keys(currentRight);
+        if (leftKeys.length !== rightKeys.length)
+            return false;
+        for (const key of leftKeys) {
+            if (!Object.hasOwn(currentRight, key))
+                return false;
+            pending.push([currentLeft[key], currentRight[key]]);
+        }
+    }
+    return true;
+}
+function filteredOther(definition) {
+    const other = Object.create(null);
+    for (const key of Object.keys(definition)) {
+        if (!EXCLUDED_OTHER_FIELDS.has(key))
+            other[key] = definition[key];
+    }
+    return other;
+}
+function changedFields(before, after) {
+    const fields = [];
+    for (const field of FIXED_FIELDS) {
+        if (!structurallyEqual(before[field], after[field]))
+            fields.push(field);
+    }
+    if (!structurallyEqual(filteredOther(before), filteredOther(after)))
+        fields.push("other");
+    return fields;
+}
+function toolDefinitions(tools) {
+    const definitions = new Map();
+    for (let offset = 0; offset < tools.length; offset += 1) {
+        const value = tools[offset];
+        if (!isJsonObject(value) || typeof value.name !== "string" || definitions.has(value.name))
+            return null;
+        definitions.set(value.name, { index: offset + 1, value });
+    }
+    return definitions;
+}
+function incompleteReport(before, after, status, reason) {
+    return {
+        schemaVersion: 1,
+        scope: "tool-definitions-diff",
+        status,
+        before,
+        after,
+        comparison: { complete: false, reason, added: null, removed: null, changed: null, unchanged: null, breaking: null, unclassified: null },
+        coverage: {
+            comparison: "structural-only",
+            schema: "root-shape-only",
+            compatibility: "not-tested",
+            serverCatalog: "not-tested",
+            toolExecution: "not-tested",
+            impactClassification: "heuristic"
+        },
+        changes: []
+    };
+}
+export async function compareMcpToolFiles(beforePath, afterPath) {
+    const [beforeSnapshot, afterSnapshot] = await Promise.all([
+        loadMcpToolFileSnapshot(beforePath),
+        loadMcpToolFileSnapshot(afterPath)
+    ]);
+    const { report: before } = beforeSnapshot;
+    const { report: after } = afterSnapshot;
+    if (before.status === "blocked" || after.status === "blocked") {
+        return incompleteReport(before, after, "blocked", "input-blocked");
+    }
+    if (!before.inspection.complete || !after.inspection.complete) {
+        return incompleteReport(before, after, "incomplete", "input-incomplete");
+    }
+    if (before.status === "fail" || after.status === "fail" || beforeSnapshot.tools === null || afterSnapshot.tools === null) {
+        return incompleteReport(before, after, "incomplete", "invalid-definitions");
+    }
+    const beforeDefinitions = toolDefinitions(beforeSnapshot.tools);
+    const afterDefinitions = toolDefinitions(afterSnapshot.tools);
+    if (beforeDefinitions === null || afterDefinitions === null) {
+        return incompleteReport(before, after, "incomplete", "ambiguous-names");
+    }
+    const changes = [];
+    let added = 0;
+    let removed = 0;
+    let changed = 0;
+    let unchanged = 0;
+    for (const [name, beforeDefinition] of beforeDefinitions) {
+        const afterDefinition = afterDefinitions.get(name);
+        if (afterDefinition === undefined) {
+            removed += 1;
+            changes.push({ kind: "removed", beforeToolIndex: beforeDefinition.index, afterToolIndex: null, fields: [], ...classifyRemovedTool() });
+            continue;
+        }
+        const fields = changedFields(beforeDefinition.value, afterDefinition.value);
+        if (fields.length === 0) {
+            unchanged += 1;
+        }
+        else {
+            changed += 1;
+            changes.push({
+                kind: "changed",
+                beforeToolIndex: beforeDefinition.index,
+                afterToolIndex: afterDefinition.index,
+                fields,
+                ...classifyChangedTool(beforeDefinition.value, afterDefinition.value, fields, structurallyEqual)
+            });
+        }
+    }
+    for (const [name, afterDefinition] of afterDefinitions) {
+        if (!beforeDefinitions.has(name)) {
+            added += 1;
+            changes.push({ kind: "added", beforeToolIndex: null, afterToolIndex: afterDefinition.index, fields: [], ...classifyAddedTool() });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        scope: "tool-definitions-diff",
+        status: changes.length === 0 && before.status === "pass" && after.status === "pass" ? "pass" : "warn",
+        before,
+        after,
+        comparison: {
+            complete: true,
+            reason: null,
+            added,
+            removed,
+            changed,
+            unchanged,
+            breaking: changes.filter((change) => change.impact === "breaking").length,
+            unclassified: changes.filter((change) => change.impact === "unclassified").length
+        },
+        coverage: {
+            comparison: "structural-only",
+            schema: "root-shape-only",
+            compatibility: "not-tested",
+            serverCatalog: "not-tested",
+            toolExecution: "not-tested",
+            impactClassification: "heuristic"
+        },
+        changes
+    };
+}

package/dist/core/mcp-tool-file.d.ts

@@ -24,4 +24,9 @@ export interface McpToolFileReport {
     };
     findings: CatalogFinding[];
 }
+export interface McpToolFileSnapshot {
+    report: McpToolFileReport;
+    tools: unknown[] | null;
+}
+export declare function loadMcpToolFileSnapshot(filePath: string): Promise<McpToolFileSnapshot>;
 export declare function inspectMcpToolFile(filePath: string): Promise<McpToolFileReport>;

package/dist/core/mcp-tool-file.js

@@ -4,6 +4,9 @@ import { inspectMcpToolDefinition } from "./mcp-tool-definition.js";
 const MAX_FILE_BYTES = 1024 * 1024;
 const MAX_TOOLS = 500;
 const MAX_FINDINGS = 100;
+function snapshot(report, tools = null) {
+    return { report, tools };
+}
 function isJsonObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -143,43 +146,43 @@ async function readBoundedRegularFile(filePath) {
         await fileHandle?.close().catch(() => undefined);
     }
 }
-export async function inspectMcpToolFile(filePath) {
+export async function loadMcpToolFileSnapshot(filePath) {
     if (isBlockedOfflinePath(filePath)) {
-        return blockedFileReport("offline-path-blocked", fileFinding("plugin.tools_file.path.blocked", "fail", "The local tool definition path is not permitted for offline inspection.", "The offline tool definition inspection does not access remote or device paths.", "Provide a local regular file path."));
+        return snapshot(blockedFileReport("offline-path-blocked", fileFinding("plugin.tools_file.path.blocked", "fail", "The local tool definition path is not permitted for offline inspection.", "The offline tool definition inspection does not access remote or device paths.", "Provide a local regular file path.")));
     }
     const file = await readBoundedRegularFile(filePath);
     if (file.kind === "unavailable") {
-        return incompleteFileReport(file.bytesRead, "file-unavailable", fileFinding("plugin.tools_file.file.unavailable", "fail", "The local tool definition file could not be read.", "The offline tool definition inspection could not start.", "Provide a readable local regular file."));
+        return snapshot(incompleteFileReport(file.bytesRead, "file-unavailable", fileFinding("plugin.tools_file.file.unavailable", "fail", "The local tool definition file could not be read.", "The offline tool definition inspection could not start.", "Provide a readable local regular file.")));
     }
     if (file.kind === "too-large") {
-        return incompleteFileReport(file.bytesRead, "file-size-limit", fileFinding("plugin.tools_file.file.too_large", "fail", "The local tool definition file exceeds the one MiB inspection limit.", "The offline tool definition inspection cannot safely read this file within its byte limit.", "Provide a tool definition file no larger than one MiB."));
+        return snapshot(incompleteFileReport(file.bytesRead, "file-size-limit", fileFinding("plugin.tools_file.file.too_large", "fail", "The local tool definition file exceeds the one MiB inspection limit.", "The offline tool definition inspection cannot safely read this file within its byte limit.", "Provide a tool definition file no larger than one MiB.")));
     }
     if (file.kind === "changed") {
-        return incompleteFileReport(file.bytesRead, "file-changed", fileFinding("plugin.tools_file.file.changed", "fail", "The local tool definition file changed during inspection.", "The offline tool definition inspection cannot rely on an inconsistent file snapshot.", "Retry after the file is stable."));
+        return snapshot(incompleteFileReport(file.bytesRead, "file-changed", fileFinding("plugin.tools_file.file.changed", "fail", "The local tool definition file changed during inspection.", "The offline tool definition inspection cannot rely on an inconsistent file snapshot.", "Retry after the file is stable.")));
     }
     if (file.kind === "symlink") {
-        return blockedFileReport("final-symlink", fileFinding("plugin.tools_file.file.symlink", "fail", "The local tool definition target is a symbolic link.", "The offline tool definition inspection does not follow final symbolic links.", "Provide a regular file directly."));
+        return snapshot(blockedFileReport("final-symlink", fileFinding("plugin.tools_file.file.symlink", "fail", "The local tool definition target is a symbolic link.", "The offline tool definition inspection does not follow final symbolic links.", "Provide a regular file directly.")));
     }
     if (file.kind === "not-regular") {
-        return blockedFileReport("non-regular-file", fileFinding("plugin.tools_file.file.not_regular", "fail", "The local tool definition target is not a regular file.", "The offline tool definition inspection reads only bounded regular files.", "Provide a regular file directly."));
+        return snapshot(blockedFileReport("non-regular-file", fileFinding("plugin.tools_file.file.not_regular", "fail", "The local tool definition target is not a regular file.", "The offline tool definition inspection reads only bounded regular files.", "Provide a regular file directly.")));
     }
     let decoded;
     try {
         decoded = new TextDecoder("utf-8", { fatal: true }).decode(file.content);
     }
     catch {
-        return incompleteFileReport(file.bytesRead, "invalid-utf8", fileFinding("plugin.tools_file.encoding.invalid", "fail", "The local tool definition file is not valid UTF-8.", "The offline tool definition inspection cannot parse the file safely.", "Save the tools/list response as UTF-8 JSON."));
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-utf8", fileFinding("plugin.tools_file.encoding.invalid", "fail", "The local tool definition file is not valid UTF-8.", "The offline tool definition inspection cannot parse the file safely.", "Save the tools/list response as UTF-8 JSON.")));
     }
     let value;
     try {
         value = JSON.parse(decoded);
     }
     catch {
-        return incompleteFileReport(file.bytesRead, "invalid-json", fileFinding("plugin.tools_file.json.invalid", "fail", "The local tool definition file is not valid JSON.", "The offline tool definition inspection cannot parse the file safely.", "Provide one UTF-8 JSON-RPC tools/list response."));
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-json", fileFinding("plugin.tools_file.json.invalid", "fail", "The local tool definition file is not valid JSON.", "The offline tool definition inspection cannot parse the file safely.", "Provide one UTF-8 JSON-RPC tools/list response.")));
     }
     const parsed = parseToolsResult(value);
     if (parsed === null) {
-        return incompleteFileReport(file.bytesRead, "response-invalid", fileFinding("plugin.tools_file.response.invalid", "fail", "The local JSON value is not a supported complete tools/list response.", "The offline tool definition inspection cannot identify a valid tool list.", "Provide one JSON-RPC 2.0 complete tools/list result with valid cache metadata."));
+        return snapshot(incompleteFileReport(file.bytesRead, "response-invalid", fileFinding("plugin.tools_file.response.invalid", "fail", "The local JSON value is not a supported complete tools/list response.", "The offline tool definition inspection cannot identify a valid tool list.", "Provide one JSON-RPC 2.0 complete tools/list result with valid cache metadata.")));
     }
     const findings = [];
     const names = new Map();
@@ -225,17 +228,20 @@ export async function inspectMcpToolFile(filePath) {
     if (reason === null && parsed.hasNextCursor)
         reason = "more-pages-present";
     if (reason !== null) {
-        return report(file.bytesRead, "incomplete", {
+        return snapshot(report(file.bytesRead, "incomplete", {
             complete: false,
             toolsChecked,
             hasNextCursor: parsed.hasNextCursor,
             reason
-        }, findings);
+        }, findings), parsed.tools);
     }
-    return report(file.bytesRead, finalStatus(findings), {
+    return snapshot(report(file.bytesRead, finalStatus(findings), {
         complete: true,
         toolsChecked,
         hasNextCursor: false,
         reason: null
-    }, findings);
+    }, findings), parsed.tools);
+}
+export async function inspectMcpToolFile(filePath) {
+    return (await loadMcpToolFileSnapshot(filePath)).report;
 }

package/dist/core/mcp-tool-impact.d.ts

@@ -0,0 +1,13 @@
+type JsonObject = Record<string, unknown>;
+export type ToolChangeImpact = "breaking" | "compatible" | "unclassified";
+export declare const TOOL_CHANGE_REASONS: readonly ["tool-removed", "input-type-narrowed", "input-required-added", "input-property-removed", "input-property-type-narrowed", "input-property-enum-narrowed", "input-additional-properties-closed", "input-schema-unclassified", "output-schema-removed", "output-type-widened", "output-property-removed", "output-guarantee-removed", "output-property-type-widened", "output-property-enum-widened", "output-schema-unclassified", "annotation-safety-reduced", "other-fields-unclassified"];
+export type ToolChangeReason = (typeof TOOL_CHANGE_REASONS)[number];
+export interface ToolChangeClassification {
+    impact: ToolChangeImpact;
+    reasons: ToolChangeReason[];
+}
+type Equal = (left: unknown, right: unknown) => boolean;
+export declare function classifyRemovedTool(): ToolChangeClassification;
+export declare function classifyAddedTool(): ToolChangeClassification;
+export declare function classifyChangedTool(before: JsonObject, after: JsonObject, fields: readonly string[], equal: Equal): ToolChangeClassification;
+export {};

package/dist/core/mcp-tool-impact.js

@@ -0,0 +1,230 @@
+export const TOOL_CHANGE_REASONS = [
+    "tool-removed",
+    "input-type-narrowed",
+    "input-required-added",
+    "input-property-removed",
+    "input-property-type-narrowed",
+    "input-property-enum-narrowed",
+    "input-additional-properties-closed",
+    "input-schema-unclassified",
+    "output-schema-removed",
+    "output-type-widened",
+    "output-property-removed",
+    "output-guarantee-removed",
+    "output-property-type-widened",
+    "output-property-enum-widened",
+    "output-schema-unclassified",
+    "annotation-safety-reduced",
+    "other-fields-unclassified"
+];
+const UNCLASSIFIED_REASONS = new Set([
+    "input-schema-unclassified",
+    "output-schema-unclassified",
+    "other-fields-unclassified"
+]);
+// Keywords that document a schema without constraining accepted or produced values.
+const DOCUMENTATION_KEYWORDS = new Set(["title", "description", "examples", "default", "deprecated", "$comment"]);
+const ROOT_STRUCTURAL_KEYWORDS = new Set(["type", "properties", "required", "additionalProperties", "$schema"]);
+const PROPERTY_STRUCTURAL_KEYWORDS = new Set(["type", "enum"]);
+// MCP tool annotation defaults, oriented so `true` is the safer reading.
+const SAFETY_HINTS = [
+    { key: "readOnlyHint", absent: false, safe: true },
+    { key: "destructiveHint", absent: true, safe: false },
+    { key: "idempotentHint", absent: false, safe: true },
+    { key: "openWorldHint", absent: true, safe: false }
+];
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Returns the set of declared JSON types, or null when the schema does not restrict type. */
+function typeSet(schema) {
+    const declared = schema.type;
+    if (typeof declared === "string")
+        return new Set([declared]);
+    if (Array.isArray(declared) && declared.every((entry) => typeof entry === "string"))
+        return new Set(declared);
+    return null;
+}
+/** True when every value admitted by `inner` is also admitted by `outer`. */
+function typesCovered(inner, outer) {
+    if (outer === null)
+        return true;
+    if (inner === null)
+        return false;
+    for (const type of inner) {
+        if (outer.has(type))
+            continue;
+        if (type === "integer" && outer.has("number"))
+            continue;
+        return false;
+    }
+    return true;
+}
+function enumCovered(inner, outer, equal) {
+    if (outer === undefined)
+        return true;
+    if (!Array.isArray(outer))
+        return null;
+    if (inner === undefined)
+        return false;
+    if (!Array.isArray(inner))
+        return null;
+    return inner.every((value) => outer.some((candidate) => equal(value, candidate)));
+}
+function stringSet(value) {
+    if (value === undefined)
+        return new Set();
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string"))
+        return null;
+    return new Set(value);
+}
+function objectMap(value) {
+    if (value === undefined)
+        return {};
+    return isJsonObject(value) ? value : null;
+}
+function keywordsOutside(schema, allowed) {
+    const rest = Object.create(null);
+    for (const key of Object.keys(schema)) {
+        if (!allowed.has(key) && !DOCUMENTATION_KEYWORDS.has(key))
+            rest[key] = schema[key];
+    }
+    return rest;
+}
+/**
+ * Compares one property subschema. `direction` is "input" when callers must keep being
+ * accepted (after must cover before) and "output" when consumers must keep understanding
+ * results (before must cover after).
+ */
+function compareProperty(before, after, direction, equal, reasons) {
+    if (equal(before, after))
+        return;
+    const unclassified = direction === "input" ? "input-schema-unclassified" : "output-schema-unclassified";
+    if (!isJsonObject(before) || !isJsonObject(after)
+        || !equal(keywordsOutside(before, PROPERTY_STRUCTURAL_KEYWORDS), keywordsOutside(after, PROPERTY_STRUCTURAL_KEYWORDS))) {
+        reasons.add(unclassified);
+        return;
+    }
+    const [inner, outer] = direction === "input" ? [before, after] : [after, before];
+    if (!typesCovered(typeSet(inner), typeSet(outer))) {
+        reasons.add(direction === "input" ? "input-property-type-narrowed" : "output-property-type-widened");
+    }
+    const enumResult = enumCovered(inner.enum, outer.enum, equal);
+    if (enumResult === null)
+        reasons.add(unclassified);
+    else if (!enumResult)
+        reasons.add(direction === "input" ? "input-property-enum-narrowed" : "output-property-enum-widened");
+}
+function classifyInputSchema(before, after, equal, reasons) {
+    if (!isJsonObject(before) || !isJsonObject(after)
+        || !equal(keywordsOutside(before, ROOT_STRUCTURAL_KEYWORDS), keywordsOutside(after, ROOT_STRUCTURAL_KEYWORDS))
+        || !equal(before.$schema, after.$schema)) {
+        reasons.add("input-schema-unclassified");
+        return;
+    }
+    if (!typesCovered(typeSet(before), typeSet(after)))
+        reasons.add("input-type-narrowed");
+    const beforeRequired = stringSet(before.required);
+    const afterRequired = stringSet(after.required);
+    const beforeProperties = objectMap(before.properties);
+    const afterProperties = objectMap(after.properties);
+    if (beforeRequired === null || afterRequired === null || beforeProperties === null || afterProperties === null) {
+        reasons.add("input-schema-unclassified");
+        return;
+    }
+    for (const key of afterRequired) {
+        if (!beforeRequired.has(key))
+            reasons.add("input-required-added");
+    }
+    for (const key of Object.keys(beforeProperties)) {
+        if (!Object.hasOwn(afterProperties, key))
+            reasons.add("input-property-removed");
+        else
+            compareProperty(beforeProperties[key], afterProperties[key], "input", equal, reasons);
+    }
+    if (!equal(before.additionalProperties, after.additionalProperties)) {
+        if (after.additionalProperties === false)
+            reasons.add("input-additional-properties-closed");
+        else if (!(after.additionalProperties === undefined || after.additionalProperties === true))
+            reasons.add("input-schema-unclassified");
+    }
+}
+function classifyOutputSchema(before, after, equal, reasons) {
+    if (before === undefined)
+        return;
+    if (after === undefined) {
+        reasons.add("output-schema-removed");
+        return;
+    }
+    if (!isJsonObject(before) || !isJsonObject(after)
+        || !equal(keywordsOutside(before, ROOT_STRUCTURAL_KEYWORDS), keywordsOutside(after, ROOT_STRUCTURAL_KEYWORDS))
+        || !equal(before.$schema, after.$schema)) {
+        reasons.add("output-schema-unclassified");
+        return;
+    }
+    if (!typesCovered(typeSet(after), typeSet(before)))
+        reasons.add("output-type-widened");
+    const beforeRequired = stringSet(before.required);
+    const afterRequired = stringSet(after.required);
+    const beforeProperties = objectMap(before.properties);
+    const afterProperties = objectMap(after.properties);
+    if (beforeRequired === null || afterRequired === null || beforeProperties === null || afterProperties === null) {
+        reasons.add("output-schema-unclassified");
+        return;
+    }
+    for (const key of beforeRequired) {
+        if (!afterRequired.has(key))
+            reasons.add("output-guarantee-removed");
+    }
+    for (const key of Object.keys(beforeProperties)) {
+        if (!Object.hasOwn(afterProperties, key))
+            reasons.add("output-property-removed");
+        else
+            compareProperty(beforeProperties[key], afterProperties[key], "output", equal, reasons);
+    }
+    if (!equal(before.additionalProperties, after.additionalProperties))
+        reasons.add("output-schema-unclassified");
+}
+function hint(annotations, key, absent) {
+    if (annotations === undefined)
+        return absent;
+    if (!isJsonObject(annotations))
+        return null;
+    const value = annotations[key];
+    if (value === undefined)
+        return absent;
+    return typeof value === "boolean" ? value : null;
+}
+function classifyAnnotations(before, after, reasons) {
+    for (const { key, absent, safe } of SAFETY_HINTS) {
+        const beforeValue = hint(before, key, absent);
+        const afterValue = hint(after, key, absent);
+        if (beforeValue === safe && afterValue !== safe)
+            reasons.add("annotation-safety-reduced");
+    }
+}
+function result(reasons) {
+    const ordered = TOOL_CHANGE_REASONS.filter((reason) => reasons.has(reason));
+    const impact = ordered.some((reason) => !UNCLASSIFIED_REASONS.has(reason))
+        ? "breaking"
+        : ordered.length > 0 ? "unclassified" : "compatible";
+    return { impact, reasons: ordered };
+}
+export function classifyRemovedTool() {
+    return { impact: "breaking", reasons: ["tool-removed"] };
+}
+export function classifyAddedTool() {
+    return { impact: "compatible", reasons: [] };
+}
+export function classifyChangedTool(before, after, fields, equal) {
+    const reasons = new Set();
+    if (fields.includes("inputSchema"))
+        classifyInputSchema(before.inputSchema, after.inputSchema, equal, reasons);
+    if (fields.includes("outputSchema"))
+        classifyOutputSchema(before.outputSchema, after.outputSchema, equal, reasons);
+    if (fields.includes("annotations"))
+        classifyAnnotations(before.annotations, after.annotations, reasons);
+    if (fields.includes("other"))
+        reasons.add("other-fields-unclassified");
+    return result(reasons);
+}