docs(core-internal): note zod <4.3.0 override skip on reused cloned schemas

On zod 4.0-4.2.x, toJSONSchema guards the override hook with
'if (!seen.isParent)' (v4/core/to-json-schema.js), and a schema instance
is marked isParent whenever a clone of it (.describe()/.meta()) appears
in the same conversion — so a schema reused both bare and via a clone
skips sanitization on the bare node: untruthful required/
additionalProperties survive and z.date() emits {}. zod 4.3.0 removed
the guard, so the lockfile resolution (4.3.6) and the test suite cannot
observe it. Verified against the published 4.2.1 and 4.3.0 tarballs.
Document it as a known residual gap and scope the changeset claim;
bumping the declared zod floor (^4.2.0 -> ^4.3.0) would close it for
the primary path but is a maintainer decision.

Co-Authored-By: Claude <noreply@anthropic.com>

Author: claude

.changeset/zod-tojsonschema-wire-truthful.md

@@ -16,6 +16,9 @@ and `additionalProperties: false` is dropped for plain `z.object()` (kept for
 `z.strictObject()`), so validating clients no longer reject legitimate tool results for
 these schema shapes. (Output schemas containing `.transform()`/`.pipe()`/`z.coerce` still
 advertise the post-transform shape while the server ships the raw pre-transform value — a
-pre-existing gap this change does not address.) Elicitation is unaffected:
+pre-existing gap this change does not address. And on zod 4.0–4.2.x, `toJSONSchema` skips
+the sanitization hook on a schema reused both bare and via a `.describe()`/`.meta()` clone
+in the same conversion; full per-node sanitization requires zod >=4.3.0.) Elicitation is
+unaffected:
 `inputRequired.elicit()` keeps throwing on schemas its restricted form grammar cannot
 round-trip, including `z.date()`.

packages/core-internal/src/util/standardSchema.ts

@@ -191,12 +191,18 @@ export const JSON_SCHEMA_CONVERSION_TARGET = 'draft-2020-12';
  *   absent from the shipped payload (`.default()`, undefined-accepting types) from
  *   `required`: zod fills defaults during validation, but ships the raw object.
  *
- * Known residual gap: output schemas containing `.transform()`/`.pipe()`/`z.coerce`
- * still advertise the post-transform shape (`io: 'output'`) even though the server
- * validates and ships the raw pre-transform value — rewriting pipe nodes to their
- * input side per-node would break `$ref`s to registered schemas, and converting
- * output advertisements with input semantics wholesale is a design decision that
- * interacts with SEP-2106 non-object output roots (see #2464 discussion).
+ * Known residual gaps:
+ * - Output schemas containing `.transform()`/`.pipe()`/`z.coerce` still advertise the
+ *   post-transform shape (`io: 'output'`) even though the server validates and ships
+ *   the raw pre-transform value — rewriting pipe nodes to their input side per-node
+ *   would break `$ref`s to registered schemas, and converting output advertisements
+ *   with input semantics wholesale is a design decision that interacts with SEP-2106
+ *   non-object output roots (see #2464 discussion).
+ * - On zod 4.0–4.2.x, `toJSONSchema` skips the `override` hook on any node whose
+ *   clone (`.describe()`/`.meta()`) appears in the same conversion (the
+ *   `if (!seen.isParent)` guard in `v4/core/to-json-schema.js`, removed in zod
+ *   4.3.0), so a schema reused both bare and via a clone leaves the bare node
+ *   unsanitized. Full per-node sanitization requires zod >=4.3.0.
  */
 function zodConversionOptions(io: 'input' | 'output'): Pick<z.core.ToJSONSchemaParams, 'unrepresentable' | 'override'> {
     return {