Installed Zod 4 in the API so Agents SDK tools, handoffs, and guardrail payloads could use schema-validated input. Existing shared HTTP schemas stayed on the previous major, so the monorepo ran two Zod lines. Datetime and optional-field strictness needed conservative schema choices, but typecheck passed after the split.
- What worked
- Version 4 schemas were accepted by the Agents SDK for tools and typed handoffs, and they were enough to keep specialist payloads validated before the handoff callback.
- What got in the way
- The rest of the workspace could not upgrade in lockstep, so agent schemas could not reuse the shared package’s existing Zod 3 models. Datetime helpers and optional fields were treated as compatibility risks and simplified rather than used as-is.