refactor: centralize task tool protocol locking in resolveToolProtocol

- Add optional 'lockedProtocol' parameter to resolveToolProtocol() that takes
  absolute precedence over all other resolution logic (precedence level 0)
- Update all task-context call sites to pass task.taskToolProtocol as third param
- Fix API providers (anthropic, openrouter, requesty) to use metadata.toolProtocol
  when available, ensuring consistent protocol throughout task lifetime
- Add tests for lockedProtocol parameter

This ensures that once a task's tool protocol is locked at creation/resumption,
all protocol checks throughout the task's execution respect the locked value,
even if user settings change mid-task.

Author: daniel-lxs

packages/types/src/history.ts

@@ -19,6 +19,16 @@ export const historyItemSchema = z.object({
 	size: z.number().optional(),
 	workspace: z.string().optional(),
 	mode: z.string().optional(),
+	/**
+	 * The tool protocol used by this task. Once a task uses tools with a specific
+	 * protocol (XML or Native), it is permanently locked to that protocol.
+	 *
+	 * - "xml": Tool calls are parsed from XML text (no tool IDs)
+	 * - "native": Tool calls come as tool_call chunks with IDs
+	 *
+	 * This ensures task resumption works correctly even when NTC settings change.
+	 */
+	toolProtocol: z.enum(["xml", "native"]).optional(),
 	status: z.enum(["active", "completed", "delegated"]).optional(),
 	delegatedToId: z.string().optional(), // Last child this parent delegated to
 	childIds: z.array(z.string()).optional(), // All children spawned by this task

src/api/providers/anthropic.ts

@@ -73,8 +73,9 @@ export class AnthropicHandler extends BaseProvider implements SingleCompletionHa
 		// Enable native tools by default using resolveToolProtocol (which checks model's defaultToolProtocol)
 		// This matches OpenRouter's approach of always including tools when provided
 		// Also exclude tools when tool_choice is "none" since that means "don't use tools"
+		// IMPORTANT: Use metadata.toolProtocol if provided (task's locked protocol) for consistency
 		const model = this.getModel()
-		const toolProtocol = resolveToolProtocol(this.options, model.info)
+		const toolProtocol = resolveToolProtocol(this.options, model.info, metadata?.toolProtocol)
 		const shouldIncludeNativeTools =
 			metadata?.tools &&
 			metadata.tools.length > 0 &&

src/api/providers/openrouter.ts

@@ -244,7 +244,8 @@ export class OpenRouterHandler extends BaseProvider implements SingleCompletionH
 		}
 
 		// Process reasoning_details when switching models to Gemini for native tool call compatibility
-		const toolProtocol = resolveToolProtocol(this.options, model.info)
+		// IMPORTANT: Use metadata.toolProtocol if provided (task's locked protocol) for consistency
+		const toolProtocol = resolveToolProtocol(this.options, model.info, metadata?.toolProtocol)
 		const isNativeProtocol = toolProtocol === TOOL_PROTOCOL.NATIVE
 		const isGemini = modelId.startsWith("google/gemini")
 

src/api/providers/requesty.ts

@@ -139,7 +139,8 @@ export class RequestyHandler extends BaseProvider implements SingleCompletionHan
 			: undefined
 
 		// Check if native tool protocol is enabled
-		const toolProtocol = resolveToolProtocol(this.options, info)
+		// IMPORTANT: Use metadata.toolProtocol if provided (task's locked protocol) for consistency
+		const toolProtocol = resolveToolProtocol(this.options, info, metadata?.toolProtocol)
 		const useNativeTools = toolProtocol === TOOL_PROTOCOL.NATIVE
 
 		const completionParams: RequestyChatCompletionParamsStreaming = {

src/core/environment/getEnvironmentDetails.ts

@@ -236,9 +236,12 @@ export async function getEnvironmentDetails(cline: Task, includeFileDetails: boo
 		language: language ?? formatLanguage(vscode.env.language),
 	})
 
-	// Resolve and add tool protocol information
+	// Use the task's locked tool protocol for consistent environment details.
+	// This ensures the model sees the same tool format it was started with,
+	// even if user settings have changed. Fall back to resolving fresh if
+	// the task hasn't been fully initialized yet (shouldn't happen in practice).
 	const modelInfo = cline.api.getModel().info
-	const toolProtocol = resolveToolProtocol(state?.apiConfiguration ?? {}, modelInfo)
+	const toolProtocol = resolveToolProtocol(state?.apiConfiguration ?? {}, modelInfo, cline.taskToolProtocol)
 
 	details += `\n\n# Current Mode\n`
 	details += `<slug>${currentMode}</slug>\n`

src/core/task-persistence/taskMetadata.ts

@@ -1,7 +1,7 @@
 import NodeCache from "node-cache"
 import getFolderSize from "get-folder-size"
 
-import type { ClineMessage, HistoryItem } from "@roo-code/types"
+import type { ClineMessage, HistoryItem, ToolProtocol } from "@roo-code/types"
 
 import { combineApiRequests } from "../../shared/combineApiRequests"
 import { combineCommandSequences } from "../../shared/combineCommandSequences"
@@ -23,6 +23,11 @@ export type TaskMetadataOptions = {
 	mode?: string
 	/** Initial status for the task (e.g., "active" for child tasks) */
 	initialStatus?: "active" | "delegated" | "completed"
+	/**
+	 * The tool protocol locked to this task. Once set, the task will
+	 * continue using this protocol even if user settings change.
+	 */
+	toolProtocol?: ToolProtocol
 }
 
 export async function taskMetadata({
@@ -35,6 +40,7 @@ export async function taskMetadata({
 	workspace,
 	mode,
 	initialStatus,
+	toolProtocol,
 }: TaskMetadataOptions) {
 	const taskDir = await getTaskDirectoryPath(globalStoragePath, id)
 
@@ -90,6 +96,8 @@ export async function taskMetadata({
 	// initialStatus is included when provided (e.g., "active" for child tasks)
 	// to ensure the status is set from the very first save, avoiding race conditions
 	// where attempt_completion might run before a separate status update.
+	// toolProtocol is persisted to ensure tasks resume with the correct protocol
+	// even if user settings have changed.
 	const historyItem: HistoryItem = {
 		id,
 		rootTaskId,
@@ -107,6 +115,7 @@ export async function taskMetadata({
 		size: taskDirSize,
 		workspace,
 		mode,
+		...(toolProtocol && { toolProtocol }),
 		...(initialStatus && { status: initialStatus }),
 	}