fix(core): coerce routed tool arguments with Zod 4

YU
2d ago
+131-1

PR Checklist

  • The proposed commit message follows the contribution guidelines: fix(core): coerce routed tool arguments with Zod 4

Bugs / Features

  • Related issue(s) linked — found while inspecting tool routing; no existing report of this specific behavior identified.
  • Tests for the changes have been added.
  • Docs have been added / updated — an implementation comment explains the Zod version difference; no public API changes.
  • Changesets have been added.

What is the current behavior?

The callTool router can recover a stringified array/object argument after a tool schema reports invalid_type. However, the coercion helper requires issue.received === "string", a field present in Zod 3 errors but omitted in Zod 4 errors.

For example, a tool expecting files: string[] and filters: { owner: string } receives files: '["report.csv"]' and filters: '{"owner":"workspace"}'. With a Zod 4 schema, callTool returns an invalid-arguments error instead of coercing the values and executing the tool. The same input already works with Zod 3.

What is the new behavior?

Check the actual argument's type rather than requiring the version-specific error field. The helper still requires an invalid_type issue expecting an array/object, a valid path, a string value, parseable JSON, and the matching container type. The router still reparses the resulting arguments against the tool's schema before execution.

Tests use real zod/v3 and zod/v4 schemas, including nested array paths, input immutability, non-string inputs, malformed JSON, wrong container types, and revalidation of container contents. An additional test imports the actual Agent and Tool modules and exercises searchTools → callTool → the target tool. It uses MockLanguageModelV3 without making model requests.

Notes for reviewers

Validation used Node 24.22.1, Vitest 3.2.4, TypeScript 5.8.3, and Biome 1.9.4, with dependencies installed in isolated directories rather than a full monorepo install:

  • With Zod 4.1.11 and AI SDK 6.0.316: the two focused files went from 3 failing / 19 passing tests on the original source to 22 passing tests. A second independent AI review reproduced all 22 passes.
  • With Zod 3.25.76, ai 6.0.3 and @ai-sdk/provider-utils 4.0.1 (the SDK versions in the repository lockfile): 184 tests across 6 relevant files passed, including the complete agent.spec.ts, Tool, ToolManager, tool-input, and new regression suites.
  • In that lock-aligned SDK/Zod 3 environment, the official core build passed for CJS, ESM, and declarations; core tsc --noEmit passed. Strict checking of both new/expanded regression suites also passed using the core compiler library settings.
  • Whole-repository biome ci . passed: 1,785 files, five complexity warnings. Changed-file checks and git diff --check passed.
  • In the newer SDK/Zod 4 environment, the same six-file regression run had 183 passes and one failure in the unchanged tool/index.spec.ts:258, which reads Zod 3's .errors field. The untouched-source baseline reproduced that failure plus the three new regression failures. Core typechecking in that environment produced 14 diagnostics with byte-identical baseline output. These observations describe the isolated environment, not the status of upstream CI.

The full monorepo test/build, provider/e2e integrations, and Node 20/22 matrix were not run. No dependencies or lockfiles are changed by this PR.

This contribution was prepared and independently checked with AI assistance; this is not a claim of human review.

Summary by cubic

Fixes tool argument coercion for routed tools using Zod 4 schemas. The coercion helper relied on the received field in validation issues, which Zod 4 omits, so stringified arrays and objects were rejected instead of parsed and revalidated. Now the helper checks the actual argument value's type, preserving all existing constraints (invalid_type issue expecting array/object, valid path, parseable JSON, matching container type, and revalidation before execution). Adds tests covering both Zod 3 and Zod 4 schemas, including the real Agent routing path.

Summary by CodeRabbit

  • Bug Fixes
    • Restored handling of stringified arrays and objects for routed tools using Zod 4 schemas. Parsed arguments are revalidated against the schema before tool execution.