feat: add XML tool calling support as provider setting

packages/types/src/provider-settings.ts

@@ -187,6 +187,9 @@ const baseProviderSettingsSchema = z.object({
 
 	// Model verbosity.
 	verbosity: verbosityLevelsSchema.optional(),
+
+	// Tool calling protocol.
+	useXmlToolCalling: z.boolean().optional(),
 })
 
 // Several of the providers share common model config properties.

src/api/index.ts

@@ -86,6 +86,13 @@ export interface ApiHandlerCreateMessageMetadata {
 	 * Only applies to providers that support function calling restrictions (e.g., Gemini).
 	 */
 	allowedFunctionNames?: string[]
+	/**
+	 * When true, native tool definitions are omitted from the API request body.
+	 * The model relies solely on XML tool documentation in the system prompt
+	 * and outputs tool calls as raw XML text, which the existing TagMatcher
+	 * in presentAssistantMessage() parses into ToolUse objects.
+	 */
+	useXmlToolCalling?: boolean
 }
 
 export interface ApiHandler {

src/api/providers/__tests__/anthropic.spec.ts

@@ -787,5 +787,63 @@ describe("AnthropicHandler", () => {
 				arguments: '"London"}',
 			})
 		})
+
+		it("should omit tools and tool_choice when useXmlToolCalling is true", async () => {
+			const stream = handler.createMessage(systemPrompt, messages, {
+				taskId: "test-task",
+				tools: mockTools,
+				tool_choice: "auto",
+				useXmlToolCalling: true,
+			})
+
+			// Consume the stream to trigger the API call
+			for await (const _chunk of stream) {
+				// Just consume
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			// When useXmlToolCalling is true, the tools and tool_choice should NOT be in the request
+			expect(callArgs.tools).toBeUndefined()
+			expect(callArgs.tool_choice).toBeUndefined()
+		})
+
+		it("should include tools when useXmlToolCalling is false", async () => {
+			const stream = handler.createMessage(systemPrompt, messages, {
+				taskId: "test-task",
+				tools: mockTools,
+				tool_choice: "auto",
+				useXmlToolCalling: false,
+			})
+
+			// Consume the stream to trigger the API call
+			for await (const _chunk of stream) {
+				// Just consume
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			// When useXmlToolCalling is false, tools should be included normally
+			expect(callArgs.tools).toBeDefined()
+			expect(callArgs.tools.length).toBeGreaterThan(0)
+			expect(callArgs.tool_choice).toBeDefined()
+		})
+
+		it("should include tools when useXmlToolCalling is undefined", async () => {
+			const stream = handler.createMessage(systemPrompt, messages, {
+				taskId: "test-task",
+				tools: mockTools,
+				tool_choice: "auto",
+			})
+
+			// Consume the stream to trigger the API call
+			for await (const _chunk of stream) {
+				// Just consume
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			// Default behavior: tools should be included
+			expect(callArgs.tools).toBeDefined()
+			expect(callArgs.tools.length).toBeGreaterThan(0)
+			expect(callArgs.tool_choice).toBeDefined()
+		})
 	})
 })

src/api/providers/__tests__/openai.spec.ts

@@ -499,6 +499,133 @@ describe("OpenAiHandler", () => {
 		})
 	})
 
+	describe("useXmlToolCalling", () => {
+		const systemPrompt = "You are a helpful assistant."
+		const messages: Anthropic.Messages.MessageParam[] = [
+			{
+				role: "user",
+				content: [{ type: "text" as const, text: "Hello!" }],
+			},
+		]
+
+		const mockTools: OpenAI.Chat.ChatCompletionTool[] = [
+			{
+				type: "function",
+				function: {
+					name: "read_file",
+					description: "Read a file",
+					parameters: {
+						type: "object",
+						properties: { path: { type: "string" } },
+						required: ["path"],
+					},
+				},
+			},
+		]
+
+		it("should omit tools and tool_choice when useXmlToolCalling is true (streaming)", async () => {
+			const stream = handler.createMessage(systemPrompt, messages, {
+				taskId: "test",
+				tools: mockTools,
+				tool_choice: "auto",
+				useXmlToolCalling: true,
+			})
+
+			for await (const _chunk of stream) {
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			// When useXmlToolCalling is true, the tools and tool_choice should NOT be in the request
+			expect(callArgs.tools).toBeUndefined()
+			expect(callArgs.tool_choice).toBeUndefined()
+			expect(callArgs.parallel_tool_calls).toBeUndefined()
+		})
+
+		it("should omit tools and tool_choice when useXmlToolCalling is true (non-streaming)", async () => {
+			const nonStreamHandler = new OpenAiHandler({
+				...mockOptions,
+				openAiStreamingEnabled: false,
+			})
+
+			const stream = nonStreamHandler.createMessage(systemPrompt, messages, {
+				taskId: "test",
+				tools: mockTools,
+				tool_choice: "auto",
+				useXmlToolCalling: true,
+			})
+
+			for await (const _chunk of stream) {
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			expect(callArgs.tools).toBeUndefined()
+			expect(callArgs.tool_choice).toBeUndefined()
+			expect(callArgs.parallel_tool_calls).toBeUndefined()
+		})
+
+		it("should include tools when useXmlToolCalling is false", async () => {
+			const stream = handler.createMessage(systemPrompt, messages, {
+				taskId: "test",
+				tools: mockTools,
+				tool_choice: "auto",
+				useXmlToolCalling: false,
+			})
+
+			for await (const _chunk of stream) {
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			expect(callArgs.tools).toBeDefined()
+			expect(callArgs.tools.length).toBeGreaterThan(0)
+			expect(callArgs.tool_choice).toBe("auto")
+			expect(callArgs.parallel_tool_calls).toBe(true)
+		})
+
+		it("should include tools when useXmlToolCalling is undefined", async () => {
+			const stream = handler.createMessage(systemPrompt, messages, {
+				taskId: "test",
+				tools: mockTools,
+				tool_choice: "auto",
+			})
+
+			for await (const _chunk of stream) {
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			expect(callArgs.tools).toBeDefined()
+			expect(callArgs.tools.length).toBeGreaterThan(0)
+			expect(callArgs.tool_choice).toBe("auto")
+		})
+
+		it("should omit tools and tool_choice for O3 family when useXmlToolCalling is true", async () => {
+			const o3Handler = new OpenAiHandler({
+				...mockOptions,
+				openAiModelId: "o3-mini",
+				openAiCustomModelInfo: {
+					contextWindow: 128_000,
+					maxTokens: 65536,
+					supportsPromptCache: false,
+					reasoningEffort: "medium" as "low" | "medium" | "high",
+				},
+			})
+
+			const stream = o3Handler.createMessage(systemPrompt, messages, {
+				taskId: "test",
+				tools: mockTools,
+				tool_choice: "auto",
+				useXmlToolCalling: true,
+			})
+
+			for await (const _chunk of stream) {
+			}
+
+			const callArgs = mockCreate.mock.calls[mockCreate.mock.calls.length - 1][0]
+			expect(callArgs.tools).toBeUndefined()
+			expect(callArgs.tool_choice).toBeUndefined()
+			expect(callArgs.parallel_tool_calls).toBeUndefined()
+		})
+	})
+
 	describe("error handling", () => {
 		const testMessages: Anthropic.Messages.MessageParam[] = [
 			{

src/api/providers/anthropic-vertex.ts

@@ -75,10 +75,15 @@ export class AnthropicVertexHandler extends BaseProvider implements SingleComple
 		// Filter out non-Anthropic blocks (reasoning, thoughtSignature, etc.) before sending to the API
 		const sanitizedMessages = filterNonAnthropicBlocks(messages)
 
-		const nativeToolParams = {
-			tools: convertOpenAIToolsToAnthropic(metadata?.tools ?? []),
-			tool_choice: convertOpenAIToolChoiceToAnthropic(metadata?.tool_choice, metadata?.parallelToolCalls),
-		}
+		// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
+		// The model will rely on XML tool documentation in the system prompt instead,
+		// and output tool calls as raw XML text parsed by TagMatcher.
+		const nativeToolParams = metadata?.useXmlToolCalling
+			? {}
+			: {
+					tools: convertOpenAIToolsToAnthropic(metadata?.tools ?? []),
+					tool_choice: convertOpenAIToolChoiceToAnthropic(metadata?.tool_choice, metadata?.parallelToolCalls),
+				}
 
 		/**
 		 * Vertex API has specific limitations for prompt caching:

src/api/providers/anthropic.ts

@@ -75,10 +75,15 @@ export class AnthropicHandler extends BaseProvider implements SingleCompletionHa
 			betas.push("context-1m-2025-08-07")
 		}
 
-		const nativeToolParams = {
-			tools: convertOpenAIToolsToAnthropic(metadata?.tools ?? []),
-			tool_choice: convertOpenAIToolChoiceToAnthropic(metadata?.tool_choice, metadata?.parallelToolCalls),
-		}
+		// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
+		// The model will rely on XML tool documentation in the system prompt instead,
+		// and output tool calls as raw XML text parsed by TagMatcher.
+		const nativeToolParams = metadata?.useXmlToolCalling
+			? {}
+			: {
+					tools: convertOpenAIToolsToAnthropic(metadata?.tools ?? []),
+					tool_choice: convertOpenAIToolChoiceToAnthropic(metadata?.tool_choice, metadata?.parallelToolCalls),
+				}
 
 		switch (modelId) {
 			case "claude-sonnet-4-6":

src/api/providers/base-openai-compatible-provider.ts

@@ -93,9 +93,14 @@ export abstract class BaseOpenAiCompatibleProvider<ModelName extends string>
 			messages: [{ role: "system", content: systemPrompt }, ...convertToOpenAiMessages(messages)],
 			stream: true,
 			stream_options: { include_usage: true },
-			tools: this.convertToolsForOpenAI(metadata?.tools),
-			tool_choice: metadata?.tool_choice,
-			parallel_tool_calls: metadata?.parallelToolCalls ?? true,
+			// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
+			...(metadata?.useXmlToolCalling
+				? {}
+				: {
+						tools: this.convertToolsForOpenAI(metadata?.tools),
+						tool_choice: metadata?.tool_choice,
+						parallel_tool_calls: metadata?.parallelToolCalls ?? true,
+					}),
 		}
 
 		// Add thinking parameter if reasoning is enabled and model supports it

src/api/providers/bedrock.ts

@@ -450,10 +450,13 @@ export class AwsBedrockHandler extends BaseProvider implements SingleCompletionH
 			additionalModelRequestFields.anthropic_beta = anthropicBetas
 		}
 
-		const toolConfig: ToolConfiguration = {
-			tools: this.convertToolsForBedrock(metadata?.tools ?? []),
-			toolChoice: this.convertToolChoiceForBedrock(metadata?.tool_choice),
-		}
+		// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
+		const toolConfig: ToolConfiguration | undefined = metadata?.useXmlToolCalling
+			? undefined
+			: {
+					tools: this.convertToolsForBedrock(metadata?.tools ?? []),
+					toolChoice: this.convertToolChoiceForBedrock(metadata?.tool_choice),
+				}
 
 		// Build payload with optional service_tier at top level
 		// Service tier is a top-level parameter per AWS documentation, NOT inside additionalModelRequestFields
@@ -466,7 +469,7 @@ export class AwsBedrockHandler extends BaseProvider implements SingleCompletionH
 			...(additionalModelRequestFields && { additionalModelRequestFields }),
 			// Add anthropic_version at top level when using thinking features
 			...(thinkingEnabled && { anthropic_version: "bedrock-2023-05-31" }),
-			toolConfig,
+			...(toolConfig ? { toolConfig } : {}),
 			// Add service_tier as a top-level parameter (not inside additionalModelRequestFields)
 			...(useServiceTier && { service_tier: this.options.awsBedrockServiceTier }),
 		}

src/api/providers/deepseek.ts

@@ -76,9 +76,14 @@ export class DeepSeekHandler extends OpenAiHandler {
 			stream_options: { include_usage: true },
 			// Enable thinking mode for deepseek-reasoner or when tools are used with thinking model
 			...(isThinkingModel && { thinking: { type: "enabled" } }),
-			tools: this.convertToolsForOpenAI(metadata?.tools),
-			tool_choice: metadata?.tool_choice,
-			parallel_tool_calls: metadata?.parallelToolCalls ?? true,
+			// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
+			...(metadata?.useXmlToolCalling
+				? {}
+				: {
+						tools: this.convertToolsForOpenAI(metadata?.tools),
+						tool_choice: metadata?.tool_choice,
+						parallel_tool_calls: metadata?.parallelToolCalls ?? true,
+					}),
 		}
 
 		// Add max_tokens if needed

src/api/providers/gemini.ts

@@ -128,19 +128,22 @@ export class GeminiHandler extends BaseProvider implements SingleCompletionHandl
 			.map((message) => convertAnthropicMessageToGemini(message, { includeThoughtSignatures, toolIdToName }))
 			.flat()
 
+		// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
 		// Tools are always present (minimum ALWAYS_AVAILABLE_TOOLS).
 		// Google built-in tools (Grounding, URL Context) are mutually exclusive
 		// with function declarations in the Gemini API, so we always use
 		// function declarations when tools are provided.
-		const tools: GenerateContentConfig["tools"] = [
-			{
-				functionDeclarations: (metadata?.tools ?? []).map((tool) => ({
-					name: (tool as any).function.name,
-					description: (tool as any).function.description,
-					parametersJsonSchema: (tool as any).function.parameters,
-				})),
-			},
-		]
+		const tools: GenerateContentConfig["tools"] = metadata?.useXmlToolCalling
+			? []
+			: [
+					{
+						functionDeclarations: (metadata?.tools ?? []).map((tool) => ({
+							name: (tool as any).function.name,
+							description: (tool as any).function.description,
+							parametersJsonSchema: (tool as any).function.parameters,
+						})),
+					},
+				]
 
 		// Determine temperature respecting model capabilities and defaults:
 		// - If supportsTemperature is explicitly false, ignore user overrides
@@ -165,7 +168,9 @@ export class GeminiHandler extends BaseProvider implements SingleCompletionHandl
 		// When provided, all tool definitions are passed to the model (so it can reference
 		// historical tool calls in conversation), but only the specified tools can be invoked.
 		// This takes precedence over tool_choice to ensure mode restrictions are honored.
-		if (metadata?.allowedFunctionNames && metadata.allowedFunctionNames.length > 0) {
+		if (metadata?.useXmlToolCalling) {
+			// Skip toolConfig entirely when using XML tool calling
+		} else if (metadata?.allowedFunctionNames && metadata.allowedFunctionNames.length > 0) {
 			config.toolConfig = {
 				functionCallingConfig: {
 					// Use ANY mode to allow calling any of the allowed functions

src/api/providers/lite-llm.ts

@@ -207,8 +207,13 @@ export class LiteLLMHandler extends RouterProvider implements SingleCompletionHa
 			stream_options: {
 				include_usage: true,
 			},
-			tools: this.convertToolsForOpenAI(metadata?.tools),
-			tool_choice: metadata?.tool_choice,
+			// When useXmlToolCalling is enabled, omit native tool definitions from the API request.
+			...(metadata?.useXmlToolCalling
+				? {}
+				: {
+						tools: this.convertToolsForOpenAI(metadata?.tools),
+						tool_choice: metadata?.tool_choice,
+					}),
 		}
 
 		// GPT-5 models require max_completion_tokens instead of the deprecated max_tokens parameter