add switch agent tool (#3144)

Author: sbatten

package.json

@@ -1148,7 +1148,6 @@
 				"userDescription": "%copilot.tools.askQuestions.description%",
 				"modelDescription": "Ask the user questions to clarify intent, validate assumptions, or choose between implementation approaches. Prefer proposing a sensible default so users can confirm quickly.\n\nOnly use this tool when the user's answer provides information you cannot determine or reasonably assume yourself. This tool is for gathering information, not for reporting status or problems. If a question has an obvious best answer, take that action instead of asking.\n\nWhen to use:\n- Clarify ambiguous requirements before proceeding\n- Get user preferences on implementation choices\n- Confirm decisions that meaningfully affect outcome\n\nWhen NOT to use:\n- The answer is determinable from code or context\n- Asking for permission to continue or abort\n- Confirming something you can reasonably decide yourself\n- Reporting a problem (instead, attempt to resolve it)\n\nQuestion guidelines:\n- Batch related questions into a single call (max 4 questions, 2-6 options each; omit options for free text input)\n- Provide brief context explaining what is being decided and why\n- Mark one option as `recommended` with a short justification\n- Keep options mutually exclusive for single-select; use `multiSelect: true` only when choices are additive and phrase the question accordingly\n\nAfter receiving answers:\n- Incorporate decisions and continue without re-asking unless requirements change\n\nAn \"Other\" option is automatically shown to users—do not add your own.",
 				"icon": "$(question)",
-				"canBeReferencedInPrompt": true,
 				"when": "config.github.copilot.chat.askQuestions.enabled",
 				"inputSchema": {
 					"type": "object",
@@ -1214,6 +1213,29 @@
 					]
 				}
 			},
+			{
+				"name": "copilot_switchAgent",
+				"toolReferenceName": "switchAgent",
+				"displayName": "%copilot.tools.switchAgent.name%",
+				"userDescription": "%copilot.tools.switchAgent.description%",
+				"modelDescription": "Switch to a different agent mode. Use this tool when you determine that the current task would be better handled by a different agent mode.\n\nCurrently supported agents:\n- 'Plan': Switch to Plan mode when the task requires careful planning before implementation. Use Plan mode when:\n  - The task is complex and requires multiple steps\n  - You need to explore the codebase and design an implementation approach\n  - The user would benefit from reviewing and approving a plan before you make changes\n  - The task involves architectural decisions or significant code modifications\n\nAfter calling this tool, the conversation will continue in the new agent mode.",
+				"icon": "$(arrow-swap)",
+				"inputSchema": {
+					"type": "object",
+					"properties": {
+						"agentName": {
+							"type": "string",
+							"description": "The name of the agent to switch to. Currently only 'Plan' is supported.",
+							"enum": [
+								"Plan"
+							]
+						}
+					},
+					"required": [
+						"agentName"
+					]
+				}
+			},
 			{
 				"name": "copilot_editFiles",
 				"modelDescription": "This is a placeholder tool, do not use",
@@ -1282,6 +1304,8 @@
 					"newWorkspace",
 					"openSimpleBrowser",
 					"runCommand",
+					"askQuestions",
+					"switchAgent",
 					"vscodeAPI"
 				]
 			},

package.nls.json

@@ -292,6 +292,8 @@
 	"copilot.tools.memory.description": "Manage persistent memory across conversations. Create, view, update, and delete memory files that remember important information between chat sessions. Only available with BYOK Anthropic Claude models.",
 	"copilot.tools.askQuestions.name": "Ask Questions",
 	"copilot.tools.askQuestions.description": "Ask questions to clarify requirements before proceeding with a task.",
+	"copilot.tools.switchAgent.name": "Switch Agent",
+	"copilot.tools.switchAgent.description": "Switch to a different agent mode. Currently only the Plan agent is supported.",
 	"copilot.tools.findTestFiles.name": "Find Test Files",
 	"copilot.tools.getDocInfo.name": "Doc Info",
 	"copilot.tools.createDirectory.name": "Create Directory",

src/extension/tools/common/toolNames.ts

@@ -69,7 +69,8 @@ export enum ToolName {
 	CoreConfirmationTool = 'vscode_get_confirmation',
 	CoreTerminalConfirmationTool = 'vscode_get_terminal_confirmation',
 	SearchSubagent = 'search_subagent',
-	AskQuestions = 'ask_questions'
+	AskQuestions = 'ask_questions',
+	SwitchAgent = 'switch_agent'
 }
 
 export enum ContributedToolName {
@@ -114,6 +115,7 @@ export enum ContributedToolName {
 	ToolReplay = 'copilot_toolReplay',
 	EditFilesPlaceholder = 'copilot_editFiles',
 	AskQuestions = 'copilot_askQuestions',
+	SwitchAgent = 'copilot_switchAgent',
 }
 
 export const byokEditToolNamesToToolNames = {
@@ -227,6 +229,7 @@ export const toolCategories: Record<ToolName, ToolCategory> = {
 	[ToolName.CoreConfirmationTool]: ToolCategory.VSCodeInteraction,
 	[ToolName.CoreTerminalConfirmationTool]: ToolCategory.VSCodeInteraction,
 	[ToolName.AskQuestions]: ToolCategory.VSCodeInteraction,
+	[ToolName.SwitchAgent]: ToolCategory.VSCodeInteraction,
 } as const;
 
 

src/extension/tools/vscode-node/allTools.ts

@@ -7,3 +7,4 @@
 
 import './askQuestionsTool';
 import './fetchWebPageTool';
+import './switchAgentTool';

src/extension/tools/vscode-node/switchAgentTool.ts

@@ -0,0 +1,52 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import * as vscode from 'vscode';
+import { CancellationToken } from '../../../util/vs/base/common/cancellation';
+import { LanguageModelTextPart, LanguageModelToolResult, MarkdownString } from '../../../vscodeTypes';
+import { ToolName } from '../common/toolNames';
+import { ICopilotTool, ToolRegistry } from '../common/toolsRegistry';
+
+interface ISwitchAgentParams {
+	agentName: string;
+}
+
+export class SwitchAgentTool implements ICopilotTool<ISwitchAgentParams> {
+	public static readonly toolName = ToolName.SwitchAgent;
+
+	async invoke(options: vscode.LanguageModelToolInvocationOptions<ISwitchAgentParams>, token: CancellationToken): Promise<vscode.LanguageModelToolResult> {
+		const { agentName } = options.input;
+
+		// Only 'Plan' is supported
+		if (agentName !== 'Plan') {
+			throw new Error(vscode.l10n.t('Only "Plan" agent is supported'));
+		}
+
+		// Execute command to switch agent
+		await vscode.commands.executeCommand('workbench.action.chat.toggleAgentMode', {
+			modeId: agentName,
+			sessionResource: options.chatSessionResource ? vscode.Uri.parse(options.chatSessionResource) : undefined
+		});
+
+		return new LanguageModelToolResult([
+			new LanguageModelTextPart(JSON.stringify({ success: true, agentName }))
+		]);
+	}
+
+	prepareInvocation(options: vscode.LanguageModelToolInvocationPrepareOptions<ISwitchAgentParams>, token: vscode.CancellationToken): vscode.ProviderResult<vscode.PreparedToolInvocation> {
+		const { agentName } = options.input;
+
+		if (agentName !== 'Plan') {
+			throw new Error(vscode.l10n.t('Only "Plan" agent is supported. Received: "{0}"', agentName));
+		}
+
+		return {
+			invocationMessage: new MarkdownString(vscode.l10n.t('Switching to {0} agent', agentName)),
+			pastTenseMessage: new MarkdownString(vscode.l10n.t('Switched to {0} agent', agentName))
+		};
+	}
+}
+
+ToolRegistry.registerTool(SwitchAgentTool);