fix(compat): reject Zod v3 fields in raw-shape auto-wrap with actionable error

isZodSchema previously matched on `_def` / `~standard.vendor === 'zod'`,
both of which Zod v3 schemas also satisfy. A v3 raw shape would pass
isZodRawShape, get wrapped by v4's z.object(), and crash deep inside
zod when listing or calling the tool.

Now detect v4 via the `_zod` property (absent on v3), and add a
dedicated runtime guard in normalizeRawShapeSchema that throws a clear
TypeError when v3 fields are seen, telling the user to import from
zod/v4 or wrap the shape themselves.

Author: felixweinberger

packages/core/src/util/zodCompat.ts

@@ -6,13 +6,26 @@
 
 import * as z from 'zod/v4';
 
-import type { StandardSchemaV1, StandardSchemaWithJSON } from './standardSchema.js';
+import type { StandardSchemaWithJSON } from './standardSchema.js';
 import { isStandardSchema, isStandardSchemaWithJSON } from './standardSchema.js';
 
-function isZodSchema(v: unknown): v is z.ZodType {
-    if (typeof v !== 'object' || v === null) return false;
-    if ('_def' in v) return true;
-    return isStandardSchema(v) && (v as StandardSchemaV1)['~standard'].vendor === 'zod';
+function isZodV4Schema(v: unknown): v is z.ZodType {
+    // `_zod` is the v4 internal namespace property. Zod v3 schemas have `_def`
+    // and (since 3.24) `~standard.vendor === 'zod'`, but never `_zod`. We require
+    // v4 because the wrap path below uses v4's `z.object()`, which cannot consume
+    // v3 field schemas.
+    return typeof v === 'object' && v !== null && '_zod' in v;
+}
+
+function looksLikeZodV3(v: unknown): boolean {
+    // v3 schemas have `_def.typeName` (e.g. 'ZodString') and no `_zod`.
+    return (
+        typeof v === 'object' &&
+        v !== null &&
+        !('_zod' in v) &&
+        '_def' in v &&
+        typeof (v as { _def?: { typeName?: unknown } })._def?.typeName === 'string'
+    );
 }
 
 /**
@@ -27,7 +40,7 @@ export function isZodRawShape(obj: unknown): obj is Record<string, z.ZodType> {
     if (typeof obj !== 'object' || obj === null) return false;
     if (isStandardSchema(obj)) return false;
     // [].every() is true, so an empty object is a valid raw shape (matches v1).
-    return Object.values(obj).every(v => isZodSchema(v));
+    return Object.values(obj).every(v => isZodV4Schema(v));
 }
 
 /**
@@ -45,6 +58,11 @@ export function normalizeRawShapeSchema(
     if (isZodRawShape(schema)) {
         return z.object(schema) as StandardSchemaWithJSON;
     }
+    if (typeof schema === 'object' && !isStandardSchema(schema) && Object.values(schema).some(v => looksLikeZodV3(v))) {
+        throw new TypeError(
+            'Raw-shape inputSchema/outputSchema/argsSchema fields must be Zod v4 schemas. Got a Zod v3 field schema. Import from `zod/v4` (or upgrade your zod import), or wrap with `z.object({...})` yourself.'
+        );
+    }
     if (!isStandardSchemaWithJSON(schema)) {
         throw new TypeError(
             'inputSchema/outputSchema/argsSchema must be a Standard Schema with JSON Schema export (`~standard.jsonSchema`, e.g. z.object({...}) from zod >=4.2.0) or a raw Zod shape ({ field: z.string() }).'

packages/core/test/util/zodCompat.test.ts

@@ -17,8 +17,21 @@ describe('isZodRawShape', () => {
         const nonZod = { '~standard': { version: 1, vendor: 'arktype', validate: () => ({ value: 'x' }) } };
         expect(isZodRawShape({ a: nonZod })).toBe(false);
     });
+    test('rejects a shape with Zod v3 fields (only v4 is wrappable)', () => {
+        expect(isZodRawShape({ a: mockZodV3String() })).toBe(false);
+    });
 });
 
+// Minimal structural mock of a Zod v3 schema: has `_def.typeName` and
+// `~standard.vendor === 'zod'` (zod >=3.24), but no `_zod`.
+function mockZodV3String(): unknown {
+    return {
+        _def: { typeName: 'ZodString', checks: [], coerce: false },
+        '~standard': { version: 1, vendor: 'zod', validate: (v: unknown) => ({ value: v }) },
+        parse: (v: unknown) => v
+    };
+}
+
 describe('normalizeRawShapeSchema', () => {
     test('wraps empty raw shape into z.object({})', () => {
         const wrapped = normalizeRawShapeSchema({});
@@ -39,4 +52,7 @@ describe('normalizeRawShapeSchema', () => {
         const noJson = { '~standard': { version: 1, vendor: 'x', validate: () => ({ value: {} }) } };
         expect(() => normalizeRawShapeSchema(noJson as never)).toThrow(/~standard\.jsonSchema/);
     });
+    test('throws actionable TypeError for a raw shape with Zod v3 fields', () => {
+        expect(() => normalizeRawShapeSchema({ a: mockZodV3String() } as never)).toThrow(/Zod v4 schemas.*Got a Zod v3 field schema/);
+    });
 });