@bevel-software/platform-mcp-core 0.25.0 → 0.26.0

package/dist/schema-validity.js

@@ -0,0 +1,254 @@
+/**
+ * Is a connected tool's input schema valid JSON Schema?
+ *
+ * AI clients ask this question themselves, and when the answer is no they drop
+ * the tool WITHOUT SAYING SO: the tool is simply missing for the agent, with
+ * nothing in Hexis to look at. So Hexis asks it first, when a server's tools
+ * are loaded, and keeps such a tool off every agent surface with a marker the
+ * server's owner can read.
+ *
+ * The check is the JSON Schema META-SCHEMA (2020-12, the draft the MCP
+ * specification names), run by `ajv` — the same validator the MCP SDK and the
+ * clients use, so a tool is hidden on exactly the violations a client would
+ * also refuse, and the reason is quoted in the words the client reports. The
+ * three refusals this started from reproduce to the character:
+ *
+ *   /properties/…/socialLinks/items/anyOf  must be an array
+ *   /properties/…/value/anyOf/0/required/0 must be a string
+ *   /properties/…/value/properties/table/type  must be equal to one of the allowed values
+ *
+ * One thing the meta-schema does not cover is checked beside it: a `pattern`
+ * (or a `patternProperties` key) that is not a compilable regular expression.
+ * The meta-schema says only that it is a string, while a client COMPILES it and
+ * drops the tool when that throws — see {@link regexDefect}.
+ *
+ * NOT a repair. Nothing here rewrites a schema — the proxy passes a connected
+ * server's schema through as sent, and an invalid one is reported, never fixed.
+ */
+import Ajv2020 from 'ajv/dist/2020.js';
+/**
+ * One validator for the process. `strict: false` keeps this to the
+ * meta-schema: ajv's strict mode objects to things no client refuses (an
+ * unknown keyword, a `required` naming an undeclared property), and hiding a
+ * tool that works is worse than listing one whose schema is merely unusual.
+ *
+ * `validateFormats: false` is the same rule applied to the META-schema's own
+ * `format` annotations (`$id` and `$ref` as `uri-reference`, `pattern` as
+ * `regex`). Switching them on is INERT, which is worth knowing before anyone
+ * reaches for it: `validateSchema` does not assert the meta-schema's formats
+ * at all, so every schema gets the same verdict with `validateFormats: true`
+ * as with it off — including `pattern: "["`, which ajv-formats' own `regex`
+ * function rejects when called directly. The switch changes configuration,
+ * not behaviour; `__tests__/schema-validity.test.ts` pins that.
+ *
+ * It would be the wrong thing to want in any case. An AI client never
+ * meta-validates the schema document: the MCP SDK's validator runs
+ * `{ strict: false, validateFormats: true, validateSchema: false }`
+ * (`validation/ajv-provider.js`) — formats on the INSTANCE, the schema
+ * document itself never checked against the meta-schema — so a malformed
+ * `$id` or `$ref` compiles there without complaint, and flagging one here
+ * would hide a tool every client accepts. The one URI-valued construct a
+ * client really refuses is a `$ref` it cannot RESOLVE (`can't resolve
+ * reference …` out of `compile`), and no format assertion catches that one
+ * either; none is ever offered, because `sanitizeInputSchema` replaces an
+ * unresolvable or non-local `$ref` with `{}` before the listing goes out.
+ * Each half is pinned where it belongs: what this check does NOT flag in
+ * `__tests__/schema-validity.test.ts`, and what the proxy offers in place of
+ * such a `$ref` in `__tests__/schema-pass-through.test.ts`.
+ *
+ * So the one format that does decide a client's verdict is `regex` — a client
+ * COMPILES a `pattern` — and because the meta-check misses it under either
+ * setting, it is checked directly, below.
+ */
+const ajv = new Ajv2020({ strict: false, allErrors: false, validateFormats: false });
+/**
+ * The first place `schema` is not valid JSON Schema, or `null` when it is.
+ *
+ * FAIL-OPEN: a schema the validator itself cannot process (an unknown
+ * `$schema` dialect, say) is reported as having no defect. A validator fault
+ * is not evidence against the tool, and the cost of being wrong here is one
+ * tool hidden from every agent.
+ */
+export function inputSchemaDefect(schema) {
+    // MCP requires an OBJECT input schema. `true`/`false` are legal JSON Schema
+    // but not legal here, and an array or a string is neither. Only `undefined`
+    // is ABSENT: a server that advertises `"inputSchema": null` has declared one
+    // and declared it wrong, which is a thing its owner wants to hear about.
+    if (schema === undefined)
+        return null; // absent: `toListedTool` supplies `{}`
+    if (schema === null || typeof schema !== 'object' || Array.isArray(schema)) {
+        return { path: '/', reason: 'must be an object' };
+    }
+    let valid;
+    try {
+        valid = ajv.validateSchema(schema);
+    }
+    catch {
+        return null;
+    }
+    if (!valid) {
+        const first = ajv.errors?.[0];
+        if (!first)
+            return null;
+        return {
+            path: first.instancePath || '/',
+            reason: withArticle(first.message ?? 'is not valid JSON Schema'),
+        };
+    }
+    return regexDefect(schema);
+}
+/** JSON Schema keywords whose value is a schema, or a list of schemas. */
+const SCHEMA_VALUED_KEYWORDS = [
+    'additionalItems',
+    'additionalProperties',
+    'allOf',
+    'anyOf',
+    'contains',
+    'contentSchema',
+    'else',
+    'if',
+    'items',
+    'not',
+    'oneOf',
+    'prefixItems',
+    'propertyNames',
+    'then',
+    'unevaluatedItems',
+    'unevaluatedProperties',
+];
+/**
+ * Keywords whose value is a MAP of schemas: the keys are names, the values
+ * schemas. `$defs`/`definitions` are NOT walked as such: an entry there is a
+ * schema only once a reference reaches it (ajv compiles nothing else, and the
+ * listing the proxy serves drops the block and inlines only what a `$ref`
+ * reaches), so the walk follows the references instead — see
+ * {@link regexDefect}.
+ */
+const SCHEMA_MAP_KEYWORDS = ['dependentSchemas', 'patternProperties', 'properties'];
+/**
+ * A bound on the walk below, for a schema whose shape is the sender's choice.
+ * It caps the QUEUE, so neither depth nor breadth can make the check cost more
+ * than this many entries.
+ */
+const MAX_REGEX_CHECK_NODES = 50_000;
+/**
+ * The first regex-bearing keyword in `schema` that does not compile, or `null`.
+ *
+ * The meta-schema does NOT catch these: `{ "type": "string", "pattern": "[" }`
+ * is a perfectly well-formed schema document. But a client does not merely read
+ * a `pattern` — it COMPILES it (the MCP SDK's own validator is `ajv.compile`),
+ * so that schema throws there and the tool is dropped just as silently as one
+ * the meta-schema rejects. Hexis has to find it for the same reason it finds
+ * the others.
+ *
+ * Tested with the `u` flag, which is how ajv compiles a `pattern`
+ * (`unicodeRegExp`, on by default) — so the verdict matches the validator the
+ * clients actually run rather than a looser reading. The walk is iterative and
+ * only ever descends through keywords whose value IS a schema, so a tool's own
+ * field named `pattern` (or a `pattern` string inside a `const` value) is data
+ * and is left alone.
+ *
+ * A `$defs`/`definitions` entry is reached only through a local `$ref` (or
+ * `$dynamicRef`) that names it, and reported at ITS OWN path — the place in
+ * the schema the server sent, which is what its owner edits. An entry nothing
+ * references is never compiled by a client and never listed by the proxy, so
+ * a bad regex in it hides no tool anywhere and is not a defect here: this
+ * module's contract is "hidden on exactly what a client would refuse".
+ */
+function regexDefect(schema) {
+    const queue = [{ node: schema, path: '' }];
+    // Each node once, by path: two references to one entry are one schema.
+    const seen = new Set(['']);
+    // The cap bounds what is ENQUEUED, not only what is dequeued: a wide schema
+    // reaches its limit by breadth rather than depth, and a queue entry costs a
+    // path string that the node it describes does not. Past the cap the check
+    // simply stops looking, which is the fail-open rule this whole file follows.
+    const enqueue = (node, path) => {
+        if (seen.has(path) || queue.length >= MAX_REGEX_CHECK_NODES)
+            return;
+        seen.add(path);
+        queue.push({ node, path });
+    };
+    for (let i = 0; i < queue.length; i += 1) {
+        const { node, path } = queue[i];
+        if (typeof node.pattern === 'string' && !compiles(node.pattern)) {
+            return { path: `${path}/pattern`, reason: 'must be a valid regular expression' };
+        }
+        for (const keyword of ['$ref', '$dynamicRef']) {
+            const reference = node[keyword];
+            if (typeof reference !== 'string' || !reference.startsWith('#/'))
+                continue;
+            const target = resolveLocalPointer(schema, reference);
+            if (isSchemaObject(target))
+                enqueue(target, reference.slice(1));
+        }
+        for (const keyword of SCHEMA_MAP_KEYWORDS) {
+            const map = node[keyword];
+            if (!isSchemaObject(map))
+                continue;
+            for (const [key, value] of Object.entries(map)) {
+                if (keyword === 'patternProperties' && !compiles(key)) {
+                    return { path: `${path}/patternProperties/${pointerPart(key)}`, reason: 'must be a valid regular expression' };
+                }
+                if (isSchemaObject(value))
+                    enqueue(value, `${path}/${keyword}/${pointerPart(key)}`);
+            }
+        }
+        for (const keyword of SCHEMA_VALUED_KEYWORDS) {
+            const value = node[keyword];
+            if (Array.isArray(value)) {
+                value.forEach((item, index) => {
+                    if (isSchemaObject(item))
+                        enqueue(item, `${path}/${keyword}/${index}`);
+                });
+            }
+            else if (isSchemaObject(value)) {
+                enqueue(value, `${path}/${keyword}`);
+            }
+        }
+    }
+    return null;
+}
+function isSchemaObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The node a local JSON Pointer (`#/$defs/x`) names in `root`, or undefined. */
+function resolveLocalPointer(root, pointer) {
+    let node = root;
+    for (const part of pointer.slice(2).split('/')) {
+        if (!isSchemaObject(node) && !Array.isArray(node))
+            return undefined;
+        const key = part.replace(/~1/g, '/').replace(/~0/g, '~');
+        // Own members only: `#/__proto__` must name nothing, not `Object.prototype`.
+        if (!Object.prototype.hasOwnProperty.call(node, key))
+            return undefined;
+        node = node[key];
+    }
+    return node;
+}
+function compiles(pattern) {
+    try {
+        new RegExp(pattern, 'u');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** A JSON Pointer path segment: `~` and `/` in a name have to be escaped. */
+function pointerPart(name) {
+    return name.replace(/~/g, '~0').replace(/\//g, '~1');
+}
+/**
+ * The sentence the tool's owner reads, wherever the marker is shown — the tool
+ * setup page and `list_tool_setup` say the same thing in the same words,
+ * because they are the same finding.
+ */
+export function schemaDefectMarker(defect) {
+    return `Hidden from agents: its schema is invalid at ${defect.path} (${defect.reason}).`;
+}
+/** ajv says `must be string`; a sentence a person reads says `must be a string`. */
+function withArticle(message) {
+    return message.replace(/^must be (array|boolean|integer|null|number|object|string)$/, (_full, type) => `must be a${/^[aeiou]/.test(type) ? 'n' : ''} ${type}`);
+}
+//# sourceMappingURL=schema-validity.js.map

package/dist/schema-validity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-validity.js","sourceRoot":"","sources":["../src/schema-validity.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-mcp-core",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "The transport-agnostic half of Bevel's MCP surface: UTCP manual registration, tool discovery, MCP listing/dispatch and the code-mode meta-tools. Shared by the hosted proxy and the local stdio server.",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,6 +28,7 @@
     "@utcp/http": "^1.1.12",
     "@utcp/mcp": "^1.2.0",
     "@utcp/sdk": "^1.2.0",
+    "ajv": "^8.20.0",
     "zod": "^4.0.0"
   },
   "devDependencies": {

package/src/index.ts

@@ -34,6 +34,12 @@ export {
   flattenDiscoveredTool,
 } from './proxied-tool.js';
 
+export {
+  type SchemaDefect,
+  inputSchemaDefect,
+  schemaDefectMarker,
+} from './schema-validity.js';
+
 export {
   describeToolFailure,
   withTransportDetail,

package/src/meta-tools.ts

@@ -25,7 +25,7 @@ import {
  *
  * What a chain DOES, though — to a failure, to a large result, to an image —
  * is true of every call, and those rules are stated once, in the handshake
- * instructions and in the platform-managed agent guide, rather than on each
+ * instructions and in the platform's agent guide, rather than on each
  * tool they cover. So on a surface that has those rules the chain description
  * ends with the same pointer sentence every file tool ends with, composed
  * where the tool is served and the guide's configured name is known

package/src/proxied-tool.ts

@@ -77,6 +77,69 @@ export function toListedTool(tool: ProxiedTool): McpTool | null {
   };
 }
 
+/**
+ * How deep {@link sanitizeInputSchema} descends before it stops walking and
+ * passes the remainder through untouched. Generous on purpose: a real schema
+ * costs two levels per nesting (the `properties` keyword, then the field name),
+ * and the whole reason for this constant is the call stack, not the schema.
+ */
+const MAX_SANITIZE_DEPTH = 200;
+
+/**
+ * How many nodes one schema's `$ref` inlining may produce before a `$ref`
+ * stops being expanded.
+ *
+ * The recursion guard tracks only the pointers on the ACTIVE path, which is
+ * what `$ref` recursion means — but it does not make expansion cheap. A
+ * schema whose references form a DAG rather than a tree (two `allOf` branches
+ * pointing at one `$defs` entry, that entry doing the same) expands its target
+ * once per branch, and that doubles per level: a few hundred bytes on the wire
+ * can ask `tools/list` for a reply no amount of memory will hold. Past this
+ * budget a `$ref` degrades to the same permissive `{}` a recursive one does,
+ * which stands at a schema position and leaves the result valid JSON Schema.
+ */
+const MAX_INLINED_NODES = 20_000;
+
+/**
+ * The stand-in for a subtree past {@link MAX_SANITIZE_DEPTH}: every plain
+ * object becomes `{}`, while arrays and scalars keep their shape. Iterative,
+ * because the whole reason for being here is that the recursion has to stop.
+ *
+ * `{}` is legal exactly where a SCHEMA stands, and an object this deep inside a
+ * schema is at a schema position. The positions the old cap destroyed were an
+ * `anyOf` LIST, a `required` entry and a `type` STRING — none of them an
+ * object, all of them handed back as they came. And because no object survives,
+ * nothing past the cap can carry a `$ref` left dangling by the `$defs` block
+ * this walk drops, or a `format` the Anthropic validator refuses.
+ */
+function stripPastDepth(node: unknown): unknown {
+  if (!node || typeof node !== 'object') return node;
+  if (!Array.isArray(node)) return {};
+  const out: unknown[] = [];
+  const queue: Array<{ from: readonly unknown[]; to: unknown[] }> = [{ from: node, to: out }];
+  for (let i = 0; i < queue.length; i += 1) {
+    const { from, to } = queue[i];
+    for (const item of from) {
+      if (!item || typeof item !== 'object') to.push(item);
+      else if (!Array.isArray(item)) to.push({});
+      else {
+        const nested: unknown[] = [];
+        to.push(nested);
+        queue.push({ from: item, to: nested });
+      }
+    }
+  }
+  return out;
+}
+
+/**
+ * Keywords whose value is INSTANCE DATA rather than a schema. A schema says
+ * what a value may be; these carry values themselves, so nothing in them is a
+ * construct for the sanitizer to touch — and nothing in them is a place where
+ * `{}` would mean "any value" either.
+ */
+const DATA_VALUED_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
+
 /** JSON-Schema string `format` values the Anthropic tool validator accepts. */
 const SUPPORTED_SCHEMA_FORMATS = new Set([
   'date-time',
@@ -99,9 +162,28 @@ const SUPPORTED_SCHEMA_FORMATS = new Set([
  *  - drop non-standard `format` values (OpenAPI's `int32`/`byte`/… — only the
  *    JSON-Schema-standard formats above are accepted; `format` is advisory, so
  *    dropping it doesn't change tool behavior).
- * Depth-bounded so a recursive schema degrades to a permissive `{}` node instead
- * of hanging or emitting the unsupported recursion; non-local/external refs
- * degrade the same way. Exported for direct testing.
+ * Everything else is passed through UNCHANGED, and both recursion guards are
+ * built so that hitting one cannot change a schema either:
+ *
+ *  - a `$ref` that resolves back onto a schema we are already inlining is
+ *    recursive, and inlining has no finite answer for it. It degrades to a
+ *    permissive `{}` — which is legal, because a `$ref` only ever stands where
+ *    a SCHEMA is expected and `{}` there means "any value". Non-local and
+ *    unresolvable refs degrade the same way, and so does one past
+ *    {@link MAX_INLINED_NODES}.
+ *  - the depth cap keeps the rest of the subtree's shape, replacing only the
+ *    objects in it with `{}` — see {@link stripPastDepth}. It cannot reach
+ *    inside instance data, because the walk never descends into a
+ *    {@link DATA_VALUED_KEYWORDS} value in the first place.
+ *
+ * That second rule is the fix for three tools AI clients silently dropped. The
+ * cap used to return `{}` at WHATEVER position it stopped at, and most
+ * positions in a schema are not schema positions: a tool nested deeper than
+ * the cap reached clients with `anyOf: {}`, `required: [{}]` or `type: {}` in
+ * it. None of those is valid JSON Schema, so the client refused the tool — and
+ * said so about a server that had sent a perfectly good schema.
+ *
+ * Exported for direct testing.
  */
 export function sanitizeInputSchema(schema: unknown): unknown {
   const root = schema;
@@ -111,30 +193,131 @@ export function sanitizeInputSchema(schema: unknown): unknown {
     for (const partRaw of pointer.slice(2).split('/')) {
       const part = partRaw.replace(/~1/g, '/').replace(/~0/g, '~');
       if (!node || typeof node !== 'object') return undefined;
+      // Own members only: `#/constructor` names nothing, not `Object`.
+      if (!Object.prototype.hasOwnProperty.call(node, part)) return undefined;
       node = (node as Record<string, unknown>)[part];
     }
     return node;
   };
-  // `isPropertyMap` marks the value of `properties`/`patternProperties`: its
-  // keys are the tool's OWN field names, not schema keywords, so a field
-  // literally named `format`, `$ref` or `definitions` must survive untouched
-  // (its VALUE is still a schema and is walked as one).
+  // The pointers currently being inlined, on THIS path. A `$ref` that points
+  // at a schema we are already inside is recursive: JSON Schema says that with
+  // the reference, and an inlined copy has no finite form.
+  const inlining = new Set<string>();
+  // Nodes charged to the expansion budget so far, against MAX_INLINED_NODES.
+  let inlined = 0;
+  // The size of each referenced target — objects, arrays, their entries and
+  // scalars, one count per pointer — stopped early past the budget, since
+  // past it the exact number no longer matters.
+  const costs = new Map<string, number>();
+  const costOf = (pointer: string): number => {
+    const known = costs.get(pointer);
+    if (known !== undefined) return known;
+    // Counted with a bounded frontier: children are pushed one at a time and
+    // only while the count is under the cap, so a target wider than the
+    // budget costs the cap in work and in memory, never its own width.
+    let count = 0;
+    const stack: unknown[] = [resolvePointer(pointer)];
+    const over = () => count + stack.length > MAX_INLINED_NODES;
+    while (stack.length > 0 && !over()) {
+      const item = stack.pop();
+      count += 1;
+      if (!item || typeof item !== 'object') continue;
+      if (Array.isArray(item)) {
+        for (let i = 0; i < item.length && !over(); i += 1) stack.push(item[i]);
+      } else {
+        for (const key in item as Record<string, unknown>) {
+          if (over()) break;
+          if (Object.prototype.hasOwnProperty.call(item, key)) stack.push((item as Record<string, unknown>)[key]);
+        }
+      }
+    }
+    const cost = over() ? MAX_INLINED_NODES + 1 : count;
+    costs.set(pointer, cost);
+    return cost;
+  };
+  // `isPropertyMap` marks the value of `properties`/`patternProperties`, and
+  // of `dependentSchemas`/`dependencies`: its keys are the tool's OWN field
+  // names, not schema keywords, so a field literally named `format`, `$ref`,
+  // `definitions` or `default` must survive untouched (its VALUE is still a
+  // schema and is walked as one).
   const walk = (node: unknown, depth: number, isPropertyMap = false): unknown => {
-    if (depth > 20) return {}; // recursion/cycle guard — permissive fallback
-    if (Array.isArray(node)) return node.map((item) => walk(item, depth + 1));
+    // Stack guard, not a schema rule: `$ref` recursion is caught below, so
+    // nothing a server legitimately sends reaches this. Stopping must never
+    // make a schema INVALID — which is exactly what the old cap did, by
+    // returning `{}` at whatever position it had reached.
+    if (depth > MAX_SANITIZE_DEPTH) return stripPastDepth(node);
     if (!node || typeof node !== 'object') return node;
+    if (Array.isArray(node)) return node.map((item) => walk(item, depth + 1));
     const obj = node as Record<string, unknown>;
-    if (!isPropertyMap && typeof obj.$ref === 'string') {
-      const target = resolvePointer(obj.$ref);
+    // `$dynamicRef` is a reference like `$ref` (2020-12's late-bound form):
+    // resolved the same way when it is a local pointer, degraded the same way
+    // when it is not — never left standing, because the `$defs` block it
+    // reaches into is dropped below and a dangling reference is what clients
+    // reject. Both at once is legal and both apply, so both are inlined, as
+    // the `allOf` they amount to.
+    const references = (['$ref', '$dynamicRef'] as const)
+      .map((keyword) => obj[keyword])
+      .filter((value): value is string => typeof value === 'string');
+    if (!isPropertyMap && references.length > 0) {
       // JSON Schema allows siblings next to $ref; keep them, target wins ties.
       const siblings: Record<string, unknown> = { ...obj };
       delete siblings.$ref;
-      const resolved = walk(target ?? {}, depth + 1);
-      return resolved && typeof resolved === 'object' && !Array.isArray(resolved)
-        ? { ...siblings, ...(resolved as Record<string, unknown>) }
-        : Object.keys(siblings).length
-          ? siblings
-          : resolved ?? {};
+      delete siblings.$dynamicRef;
+      // Sanitized ONCE, here, because every path below can return them: the
+      // siblings are schema keywords in their own right, and an unsupported
+      // `format` or a nested `$ref` left in them is precisely what this
+      // function exists to keep out of a listing. (`siblings` no longer holds
+      // a `$ref`, so this cannot re-enter this branch at this node; deeper
+      // ones terminate on `inlining` or on the depth cap.)
+      const kept = Object.keys(siblings).length ? (walk(siblings, depth + 1) as Record<string, unknown>) : null;
+      // Recursive, or past the expansion budget: `{}` ("any value") is the only
+      // finite answer, and a `$ref` stands at a schema position, so `{}` there
+      // is valid JSON Schema. The reference itself has to go — the `$defs`
+      // block it points into is dropped below, and a dangling `$ref` is what
+      // clients reject.
+      //
+      // The budget is charged AT THE REFERENCE, by the whole size of what it
+      // would copy — every object, array, array entry and scalar in the
+      // target, counted once per pointer — before a byte of it is copied. A
+      // target that does not fit the remaining budget is `{}` whole, never a
+      // partial copy: the only thing a copy can cost is what the reference
+      // multiplies, and that is the target's full size whatever shapes it is
+      // made of (a `required` list of ten thousand names as much as ten
+      // thousand properties).
+      const resolveOne = (pointer: string): unknown => {
+        if (inlining.has(pointer)) return {};
+        const cost = costOf(pointer);
+        if (inlined + cost > MAX_INLINED_NODES) return {};
+        inlined += cost;
+        inlining.add(pointer);
+        try {
+          return walk(resolvePointer(pointer) ?? {}, depth + 1);
+        } finally {
+          inlining.delete(pointer);
+        }
+      };
+      const asObject = (value: unknown): Record<string, unknown> =>
+        value && typeof value === 'object' && !Array.isArray(value) ? (value as Record<string, unknown>) : {};
+      if (references.length === 1) {
+        const resolved = resolveOne(references[0]!);
+        // An object target merges over the siblings; a boolean target is a
+        // schema in its own right (`false` rejects everything) and stands
+        // alone, or under `allOf` beside siblings; anything else a pointer
+        // can land on — a string, a number, an array — is not a schema and
+        // becomes `{}`, never the raw value.
+        if (typeof resolved === 'boolean') {
+          return kept ? { ...kept, allOf: [...(Array.isArray(kept.allOf) ? kept.allOf : []), resolved] } : resolved;
+        }
+        return { ...(kept ?? {}), ...asObject(resolved) };
+      }
+      // A boolean target is a schema too (`false` rejects everything) and is
+      // kept as it is; anything that is not an object schema is `{}`.
+      const targets = references.map((pointer) => {
+        const resolved = resolveOne(pointer);
+        return typeof resolved === 'boolean' ? resolved : asObject(resolved);
+      });
+      const allOf = Array.isArray(kept?.allOf) ? (kept!.allOf as unknown[]) : [];
+      return { ...(kept ?? {}), allOf: [...allOf, ...targets] };
     }
     const out: Record<string, unknown> = {};
     for (const [key, value] of Object.entries(obj)) {
@@ -143,12 +326,25 @@ export function sanitizeInputSchema(schema: unknown): unknown {
         continue;
       }
       if (key === '$defs' || key === 'definitions') continue; // inlined above
+      // Instance DATA, not a schema: handed back exactly as it came. A `default`
+      // or an `enum` entry that happens to carry a key named `format` or `$ref`
+      // is a value the tool expects, not a construct to rewrite — and since the
+      // walk never descends into one, the depth cap cannot reach inside it
+      // either.
+      if (DATA_VALUED_KEYWORDS.has(key)) {
+        out[key] = value;
+        continue;
+      }
       // Drop a non-standard `format` (OpenAPI `int32`/`byte`/…) — the validator
       // only allows the JSON-Schema-standard set; the annotation is non-load-bearing.
       if (key === 'format' && (typeof value !== 'string' || !SUPPORTED_SCHEMA_FORMATS.has(value))) {
         continue;
       }
-      out[key] = walk(value, depth + 1, key === 'properties' || key === 'patternProperties');
+      out[key] = walk(
+        value,
+        depth + 1,
+        key === 'properties' || key === 'patternProperties' || key === 'dependentSchemas' || key === 'dependencies',
+      );
     }
     return out;
   };