fix(ai): undo strict-mode nulls before an approved tool check

.changeset/approval-resume-null-widening.md

@@ -0,0 +1,6 @@
+---
+'@tanstack/ai': patch
+'@tanstack/openai-base': patch
+---
+
+Undo strict-mode `null`s on tool arguments before the input check. An approved call whose history still has those `null`s now runs when `repairToolInput` is off.

docs/config.json

@@ -360,7 +360,7 @@
           "label": "Server Tools: Advanced",
           "to": "tools/server-tools-advanced",
           "addedAt": "2026-10-21",
-          "updatedAt": "2026-10-22"
+          "updatedAt": "2026-11-09"
         },
         {
           "label": "Client Tools",

docs/tools/server-tools-advanced.md

@@ -24,7 +24,7 @@ The `inputSchema` checks the input right before the tool runs:
 
 Malformed JSON arguments and failed input checks (Standard Schema or JSON Schema) become tool errors. The tool does not run. The agent loop can send the error back to the model, so the model can correct the call. This also applies to Chat Completions tools with no required input fields.
 
-For OpenAI-compatible providers, an omitted `.optional()` field is absent when your tool runs. A `.nullable()` field keeps `null`.
+For OpenAI-compatible providers, an omitted `.optional()` field is absent when your tool runs. A `.nullable()` field keeps `null`. The removal runs before the input check. When you resume an approved call, the optional field stays absent. `repairToolInput: false` does not put the `null` back.
 
 ### The built-in repair
 

packages/ai/src/activities/chat/adapter.ts

@@ -1,4 +1,5 @@
 import type {
+  AnyTool,
   DefaultMessageMetadataByModality,
   JSONSchema,
   MidConversationChannels,
@@ -228,6 +229,19 @@ export interface TextAdapter<
   combinedStructuredOutputSource?: (
     modelOptions?: TProviderOptions | undefined,
   ) => 'text' | 'event'
+
+  /**
+   * Undo a provider rewrite of tool arguments before the input check.
+   * Strict mode returns `null` for an omitted optional field. The live
+   * stream undoes that on `TOOL_CALL_END`. History rebuilt from
+   * `TOOL_CALL_ARGS` still has the `null`, so a resume calls this first.
+   * Omit it when the adapter does not rewrite arguments.
+   */
+  normalizeToolInput?: (
+    toolName: string,
+    input: unknown,
+    tools: ReadonlyArray<AnyTool> | undefined,
+  ) => unknown
 }
 
 /**

packages/ai/src/activities/chat/index.ts

@@ -2829,6 +2829,9 @@ class TextEngine<
       this.params.toolExecution,
       this.params.repairToolInput,
       this.toolCapabilities(),
+      this.toolInputNormalizer(
+        this.resolveExecutableTools(executablePendingCalls),
+      ),
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -3079,6 +3082,9 @@ class TextEngine<
       this.params.toolExecution,
       this.params.repairToolInput,
       this.toolCapabilities(),
+      this.toolInputNormalizer(
+        this.resolveExecutableTools(executableToolCalls),
+      ),
     )
 
     // Consume the async generator, yielding custom events and collecting the return value
@@ -4193,9 +4199,23 @@ class TextEngine<
       undefined,
       this.params.repairToolInput,
       this.toolCapabilities(),
+      this.toolInputNormalizer(tools),
     )
   }
 
+  /**
+   * The adapter's undo for provider-rewritten tool arguments, closed over
+   * the tools of this batch. Absent when the adapter does not rewrite them.
+   */
+  private toolInputNormalizer(
+    tools: ReadonlyArray<AnyTool>,
+  ): ((toolName: string, input: unknown) => unknown) | undefined {
+    const normalize = this.adapter.normalizeToolInput
+    if (!normalize) return undefined
+    const adapter = this.adapter
+    return (toolName, input) => normalize.call(adapter, toolName, input, tools)
+  }
+
   /** The run's capability readers, for each server tool's context. */
   private toolCapabilities(): Pick<
     ToolExecutionContext,

packages/ai/src/activities/chat/tools/tool-calls.ts

@@ -1022,6 +1022,9 @@ async function buildClientToolResult(
  *   repaired: the built-in repair (default), none (`false`), or a function.
  * @param capabilities - The run's capability readers. Each server tool gets
  *   them on its context as `get` and `getOptional`.
+ * @param normalizeToolInput - Undo a provider rewrite of the parsed
+ *   arguments before the check. Strict-mode `null`s for omitted optional
+ *   fields are removed here, including on an approval resume.
  */
 export async function* executeToolCalls<TContext = unknown>(
   toolCalls: Array<ToolCall>,
@@ -1041,6 +1044,7 @@ export async function* executeToolCalls<TContext = unknown>(
   toolExecution: NonNullable<TextOptions['toolExecution']> = 'parallel',
   repairToolInput?: TextOptions['repairToolInput'],
   capabilities?: Pick<ToolExecutionContext, 'get' | 'getOptional'>,
+  normalizeToolInput?: (toolName: string, input: unknown) => unknown,
 ): AsyncGenerator<CustomEvent | StreamChunk, ExecuteToolCallsResult, void> {
   const results: Array<ToolResult> = []
   const needsApproval: Array<ApprovalRequest> = []
@@ -1184,6 +1188,7 @@ export async function* executeToolCalls<TContext = unknown>(
         const parsed = JSON.parse(argsStr)
         // Normalize null/non-object to {} (e.g. Anthropic empty tool_use blocks)
         input = parsed && typeof parsed === 'object' ? parsed : {}
+        if (normalizeToolInput) input = normalizeToolInput(toolName, input)
       } catch {
         results.push({
           toolCallId: toolCall.id,
@@ -1423,6 +1428,7 @@ export async function* executeToolCalls<TContext = unknown>(
       toolExecution,
       repairToolInput,
       capabilities,
+      normalizeToolInput,
     )
     results.push(...rest.results)
     needsClientExecution.push(...rest.needsClientExecution)

packages/ai/tests/tool-input-validation.test.ts

@@ -43,6 +43,7 @@ async function runTool(
     middleware?: ToolExecutionMiddlewareHooks
     clientResults?: Map<string, unknown>
     repairToolInput?: TextOptions['repairToolInput']
+    normalizeToolInput?: (toolName: string, input: unknown) => unknown
   } = {},
 ) {
   const executed: Array<unknown> = []
@@ -78,6 +79,8 @@ async function runTool(
     undefined,
     undefined,
     options.repairToolInput,
+    undefined,
+    options.normalizeToolInput,
   )
   while (true) {
     const next = await generator.next()
@@ -1260,6 +1263,116 @@ describe('client tool input in chat()', () => {
     expect(clientInput(chunks)).toBeUndefined()
   })
 
+  it('runs an approved tool when history arguments still have a strict null', async () => {
+    const { adapter } = createMockAdapter({
+      iterations: [[ev.runStarted(), ev.runFinished()]],
+    })
+    adapter.normalizeToolInput = (_toolName, input) => {
+      if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return input
+      }
+      const record = input as Record<string, unknown>
+      if (record.date !== null) return input
+      const { date: _date, ...rest } = record
+      return rest
+    }
+    const executed: Array<unknown> = []
+    const chunks = await collectChunks(
+      chat({
+        threadId: 'thread-1',
+        adapter,
+        parentRunId: 'old',
+        messages: history({ destination: 'Tokyo', date: null, note: null }),
+        tools: [
+          {
+            name: 'check',
+            description: 'Book a flight',
+            needsApproval: true,
+            inputSchema: {
+              type: 'object',
+              properties: {
+                destination: { type: 'string' },
+                date: { type: 'string' },
+                note: { type: ['string', 'null'] },
+              },
+              required: ['destination'],
+              additionalProperties: false,
+            },
+            execute: (input: unknown) => {
+              executed.push(input)
+              return { booked: true }
+            },
+          },
+        ],
+        resume: [
+          {
+            interruptId: 'approval_call',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        repairToolInput: false,
+      }),
+    )
+    expect(executed).toEqual([{ destination: 'Tokyo', note: null }])
+    expect(
+      chunks.some(
+        (chunk) =>
+          chunk.type === EventType.TOOL_CALL_RESULT &&
+          typeof chunk.content === 'string' &&
+          chunk.content.includes('Input validation failed'),
+      ),
+    ).toBe(false)
+  })
+
+  it('keeps a strict null when the adapter does not undo it', async () => {
+    const { adapter } = createMockAdapter({
+      iterations: [[ev.runStarted(), ev.runFinished()]],
+    })
+    const chunks = await collectChunks(
+      chat({
+        threadId: 'thread-1',
+        adapter,
+        parentRunId: 'old',
+        messages: history({ destination: 'Tokyo', date: null }),
+        tools: [
+          {
+            name: 'check',
+            description: 'Book a flight',
+            needsApproval: true,
+            inputSchema: {
+              type: 'object',
+              properties: {
+                destination: { type: 'string' },
+                date: { type: 'string' },
+              },
+              required: ['destination'],
+              additionalProperties: false,
+            },
+            execute: () => ({ booked: true }),
+          },
+        ],
+        resume: [
+          {
+            interruptId: 'approval_call',
+            status: 'resolved',
+            payload: { approved: true },
+          },
+        ],
+        repairToolInput: false,
+      }),
+    )
+    expect(
+      chunks.some(
+        (chunk) =>
+          chunk.type === EventType.TOOL_CALL_RESULT &&
+          typeof chunk.content === 'string' &&
+          chunk.content.includes('Input validation failed') &&
+          chunk.content.includes('\\"date\\":null'),
+      ),
+    ).toBe(true)
+  })
+
   it('checks an approval edit after middleware on resume', async () => {
     const { adapter, calls } = createMockAdapter({ iterations: [] })
     const seen: Array<unknown> = []

packages/openai-base/src/adapters/chat-completions-text.ts

@@ -48,6 +48,7 @@ import type {
   ChatCompletionMessageParam,
 } from 'openai/resources/chat/completions/completions'
 import type {
+  AnyTool,
   ContentPart,
   DefaultMessageMetadataByModality,
   Modality,
@@ -822,6 +823,17 @@ export abstract class OpenAIBaseChatCompletionsTextAdapter<
     return makeStructuredOutputCompatibleWithMap(schema, originalRequired)
   }
 
+  /** Undo strict-mode nulls before the engine checks recorded arguments. */
+  normalizeToolInput(
+    toolName: string,
+    input: unknown,
+    tools: ReadonlyArray<AnyTool> | undefined,
+  ): unknown {
+    return createToolInputNormalizer(tools, (schema, required) =>
+      this.makeStructuredOutputCompatibleWithMap(schema, required),
+    )(toolName, input)
+  }
+
   /**
    * Applies provider-specific transformations for structured output compatibility.
    * Override `makeStructuredOutputCompatibleWithMap` when you need the inverse map

packages/openai-base/src/adapters/responses-text.ts

@@ -1309,6 +1309,17 @@ export abstract class OpenAIBaseResponsesTextAdapter<
     return makeStructuredOutputCompatibleWithMap(schema, originalRequired)
   }
 
+  /** Undo strict-mode nulls before the engine checks recorded arguments. */
+  normalizeToolInput(
+    toolName: string,
+    input: unknown,
+    tools: ReadonlyArray<AnyTool> | undefined,
+  ): unknown {
+    return createToolInputNormalizer(tools, (schema, required) =>
+      this.makeStructuredOutputCompatibleWithMap(schema, required),
+    )(toolName, input)
+  }
+
   /**
    * Applies provider-specific transformations for structured output compatibility.
    * Override `makeStructuredOutputCompatibleWithMap` when you need the inverse map

packages/openai-base/src/utils/tool-input-normalizer.test.ts

@@ -1,7 +1,12 @@
 import { describe, expect, it } from 'vitest'
+import { OpenAIBaseChatCompletionsTextAdapter } from '../adapters/chat-completions-text'
+import { OpenAIBaseResponsesTextAdapter } from '../adapters/responses-text'
 import { createToolInputNormalizer } from './tool-input-normalizer'
 import type { Tool } from '@tanstack/ai'
 
+class Completions extends OpenAIBaseChatCompletionsTextAdapter<string> {}
+class Responses extends OpenAIBaseResponsesTextAdapter<string> {}
+
 describe('createToolInputNormalizer', () => {
   it('removes a null synthesized for an optional enum', () => {
     const tool: Tool = {
@@ -144,3 +149,33 @@ describe('createToolInputNormalizer', () => {
     expect(normalize(tool.name, { note: null })).toEqual({})
   })
 })
+
+describe('adapter normalizeToolInput', () => {
+  const tool: Tool = {
+    name: 'bookFlight',
+    description: 'Book a flight',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        destination: { type: 'string' },
+        date: { type: 'string' },
+        note: { type: ['string', 'null'] },
+      },
+      required: ['destination'],
+      additionalProperties: false,
+    },
+  }
+
+  it('removes a strict null and keeps a nullable null', () => {
+    const input = { destination: 'Tokyo', date: null, note: null }
+    for (const adapter of [
+      new Completions('gpt-test', 'openai', {} as never),
+      new Responses('gpt-test', 'openai', {} as never),
+    ]) {
+      expect(adapter.normalizeToolInput(tool.name, input, [tool])).toEqual({
+        destination: 'Tokyo',
+        note: null,
+      })
+    }
+  })
+})

packages/openai-base/src/utils/tool-input-normalizer.ts

@@ -21,7 +21,7 @@ type SchemaConverterWithMap = (
  * null-widened on the wire.
  */
 export function createToolInputNormalizer(
-  tools: Array<Tool> | undefined,
+  tools: ReadonlyArray<Pick<Tool, 'name' | 'inputSchema'>> | undefined,
   convertSchema: SchemaConverterWithMap = makeStructuredOutputCompatibleWithMap,
 ): ToolInputNormalizer {
   const maps = new Map<string, NullWideningMap>()