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/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/core/prompts/sections/__tests__/tool-use.spec.ts

@@ -1,31 +1,174 @@
 import { getSharedToolUseSection } from "../tool-use"
+import { getToolUseGuidelinesSection } from "../tool-use-guidelines"
 
 describe("getSharedToolUseSection", () => {
-	it("should include native tool-calling instructions", () => {
-		const section = getSharedToolUseSection()
+	describe("default (native) mode", () => {
+		it("should include native tool-calling instructions", () => {
+			const section = getSharedToolUseSection()
 
-		expect(section).toContain("provider-native tool-calling mechanism")
-		expect(section).toContain("Do not include XML markup or examples")
+			expect(section).toContain("provider-native tool-calling mechanism")
+			expect(section).toContain("Do not include XML markup or examples")
+		})
+
+		it("should include multiple tools per message guidance", () => {
+			const section = getSharedToolUseSection()
+
+			expect(section).toContain("You must call at least one tool per assistant response")
+			expect(section).toContain("Prefer calling as many tools as are reasonably needed")
+		})
+
+		it("should NOT include single tool per message restriction", () => {
+			const section = getSharedToolUseSection()
+
+			expect(section).not.toContain("You must use exactly one tool call per assistant response")
+			expect(section).not.toContain("Do not call zero tools or more than one tool")
+		})
+
+		it("should NOT include XML formatting instructions", () => {
+			const section = getSharedToolUseSection()
+
+			expect(section).not.toContain("<actual_tool_name>")
+			expect(section).not.toContain("</actual_tool_name>")
+		})
+
+		it("should return native instructions when useXmlToolCalling is false", () => {
+			const section = getSharedToolUseSection(false)
+
+			expect(section).toContain("provider-native tool-calling mechanism")
+			expect(section).not.toContain("<actual_tool_name>")
+		})
 	})
 
-	it("should include multiple tools per message guidance", () => {
-		const section = getSharedToolUseSection()
+	describe("XML tool calling mode", () => {
+		it("should include XML formatting instructions when useXmlToolCalling is true", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("<actual_tool_name>")
+			expect(section).toContain("</actual_tool_name>")
+			expect(section).toContain("Tool uses are formatted using XML-style tags")
+		})
+
+		it("should NOT include provider-native tool-calling text when useXmlToolCalling is true", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).not.toContain("provider-native tool-calling mechanism")
+			expect(section).not.toContain("Do not include XML markup or examples")
+		})
+
+		it("should include parameter tag syntax example when useXmlToolCalling is true", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("<parameter1_name>value1</parameter1_name>")
+			expect(section).toContain("<parameter2_name>value2</parameter2_name>")
+		})
+
+		it("should include TOOL USE header when useXmlToolCalling is true", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("TOOL USE")
+			expect(section).toContain("You have access to a set of tools")
+		})
+
+		it("should include new_task XML example", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("<new_task>")
+			expect(section).toContain("<mode>code</mode>")
+			expect(section).toContain("</new_task>")
+		})
+
+		it("should include execute_command XML example", () => {
+			const section = getSharedToolUseSection(true)
 
-		expect(section).toContain("You must call at least one tool per assistant response")
-		expect(section).toContain("Prefer calling as many tools as are reasonably needed")
+			expect(section).toContain("<execute_command>")
+			expect(section).toContain("<command>npm run dev</command>")
+			expect(section).toContain("</execute_command>")
+		})
+
+		it("should include IMPORTANT XML FORMATTING RULES section", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("IMPORTANT XML FORMATTING RULES")
+			expect(section).toContain("Every opening tag MUST have a matching closing tag")
+			expect(section).toContain("Do NOT use self-closing tags")
+			expect(section).toContain("Do NOT include JSON objects")
+			expect(section).toContain("Do NOT wrap tool calls in markdown code blocks")
+		})
+
+		it("should include COMMON MISTAKES TO AVOID section", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("COMMON MISTAKES TO AVOID")
+			expect(section).toContain("Using JSON format")
+			expect(section).toContain("Missing closing tags")
+			expect(section).toContain("Using self-closing")
+			expect(section).toContain("Correct XML format")
+		})
+
+		it("should include read_file correct example in common mistakes", () => {
+			const section = getSharedToolUseSection(true)
+
+			expect(section).toContain("<read_file>")
+			expect(section).toContain("<path>src/app.ts</path>")
+			expect(section).toContain("</read_file>")
+		})
 	})
+})
+
+describe("getToolUseGuidelinesSection", () => {
+	describe("default (non-XML) mode", () => {
+		it("should include base guidelines without XML reinforcement", () => {
+			const section = getToolUseGuidelinesSection()
+
+			expect(section).toContain("# Tool Use Guidelines")
+			expect(section).toContain("Assess what information you already have")
+			expect(section).toContain("Choose the most appropriate tool")
+			expect(section).toContain("If multiple actions are needed")
+		})
 
-	it("should NOT include single tool per message restriction", () => {
-		const section = getSharedToolUseSection()
+		it("should NOT include XML reinforcement when called without arguments", () => {
+			const section = getToolUseGuidelinesSection()
 
-		expect(section).not.toContain("You must use exactly one tool call per assistant response")
-		expect(section).not.toContain("Do not call zero tools or more than one tool")
+			expect(section).not.toContain("REMINDER: You MUST format all tool calls as XML")
+			expect(section).not.toContain("Formulate your tool use using the XML format")
+		})
+
+		it("should NOT include XML reinforcement when useXmlToolCalling is false", () => {
+			const section = getToolUseGuidelinesSection(false)
+
+			expect(section).not.toContain("REMINDER: You MUST format all tool calls as XML")
+			expect(section).not.toContain("Formulate your tool use using the XML format")
+		})
 	})
 
-	it("should NOT include XML formatting instructions", () => {
-		const section = getSharedToolUseSection()
+	describe("XML tool calling mode", () => {
+		it("should include XML reinforcement guidelines when useXmlToolCalling is true", () => {
+			const section = getToolUseGuidelinesSection(true)
+
+			expect(section).toContain("Formulate your tool use using the XML format")
+			expect(section).toContain("REMINDER: You MUST format all tool calls as XML")
+		})
+
+		it("should include XML-specific numbered steps", () => {
+			const section = getToolUseGuidelinesSection(true)
+
+			expect(section).toContain("4. Formulate your tool use using the XML format")
+			expect(section).toContain("5. After each tool use, the user will respond")
+			expect(section).toContain("6. ALWAYS wait for user confirmation")
+		})
+
+		it("should still include base guidelines alongside XML reinforcement", () => {
+			const section = getToolUseGuidelinesSection(true)
+
+			expect(section).toContain("# Tool Use Guidelines")
+			expect(section).toContain("Assess what information you already have")
+			expect(section).toContain("Choose the most appropriate tool")
+		})
+
+		it("should include explicit XML structure reminder", () => {
+			const section = getToolUseGuidelinesSection(true)
 
-		expect(section).not.toContain("<actual_tool_name>")
-		expect(section).not.toContain("</actual_tool_name>")
+			expect(section).toContain("<tool_name><param>value</param></tool_name>")
+		})
 	})
 })

src/core/prompts/sections/tool-use-guidelines.ts

@@ -1,9 +1,18 @@
-export function getToolUseGuidelinesSection(): string {
+export function getToolUseGuidelinesSection(useXmlToolCalling?: boolean): string {
+	const xmlReinforcement = useXmlToolCalling
+		? `
+4. Formulate your tool use using the XML format specified for each tool. The tool name becomes the outermost XML tag, with each parameter as a nested child tag.
+5. After each tool use, the user will respond with the result of that tool use. This result will provide you with the necessary information to continue your task or make further decisions.
+6. ALWAYS wait for user confirmation after each tool use before proceeding. Never assume the success of a tool use without explicit confirmation of the result from the user.
+
+**REMINDER: You MUST format all tool calls as XML.** Do not use JSON, function-call syntax, or any other format. Each tool call must use the exact XML structure: \`<tool_name><param>value</param></tool_name>\`.`
+		: ""
+
 	return `# Tool Use Guidelines
 
 1. Assess what information you already have and what information you need to proceed with the task.
 2. Choose the most appropriate tool based on the task and the tool descriptions provided. Assess if you need additional information to proceed, and which of the available tools would be most effective for gathering this information. For example using the list_files tool is more effective than running a command like \`ls\` in the terminal. It's critical that you think about each available tool and use the one that best fits the current step in the task.
 3. If multiple actions are needed, you may use multiple tools in a single message when appropriate, or use tools iteratively across messages. Each tool use should be informed by the results of previous tool uses. Do not assume the outcome of any tool use. Each step must be informed by the previous step's result.
-
+${xmlReinforcement}
 By carefully considering the user's response after tool executions, you can react accordingly and make informed decisions about how to proceed with the task. This iterative process helps ensure the overall success and accuracy of your work.`
 }

src/core/prompts/sections/tool-use.ts

@@ -1,4 +1,52 @@
-export function getSharedToolUseSection(): string {
+export function getSharedToolUseSection(useXmlToolCalling?: boolean): string {
+	if (useXmlToolCalling) {
+		return `====
+
+TOOL USE
+
+You have access to a set of tools that are executed upon the user's approval. You can use one tool per message, and will receive the result of that tool use in the user's response. You use tools step-by-step to accomplish a given task, with each tool use informed by the result of the previous tool use.
+
+# Tool Use Formatting
+
+Tool uses are formatted using XML-style tags. The tool name itself becomes the XML tag name. Each parameter is enclosed within its own set of tags. Here's the structure:
+
+<actual_tool_name>
+<parameter1_name>value1</parameter1_name>
+<parameter2_name>value2</parameter2_name>
+...
+</actual_tool_name>
+
+For example, to use the new_task tool:
+
+<new_task>
+<mode>code</mode>
+<message>Implement a new feature for the application.</message>
+</new_task>
+
+For example, to use the execute_command tool:
+
+<execute_command>
+<command>npm run dev</command>
+</execute_command>
+
+**IMPORTANT XML FORMATTING RULES:**
+- Always use the actual tool name as the XML tag name for proper parsing and execution.
+- Every opening tag MUST have a matching closing tag (e.g., <tool_name>...</tool_name>).
+- Parameter tags must be nested inside the tool tag.
+- Do NOT use self-closing tags (e.g., <param /> is invalid).
+- Do NOT include JSON objects or other non-XML formatting for tool calls.
+- Do NOT wrap tool calls in markdown code blocks - output raw XML directly.
+
+**COMMON MISTAKES TO AVOID:**
+- ❌ Using JSON format: { "tool": "read_file", "path": "src/app.ts" }
+- ❌ Missing closing tags: <read_file><path>src/app.ts</path>
+- ❌ Using self-closing: <read_file path="src/app.ts" />
+- ✅ Correct XML format:
+<read_file>
+<path>src/app.ts</path>
+</read_file>`
+	}
+
 	return `====
 
 TOOL USE