tool-rename-deprecation

A quality-gate procedure for Visual Studio Code contributors who rename built-in tool or tool set reference names in the chat and language-model tooling code. The central rule: whenever a tool's toolReferenceName or a tool set's referenceName changes, the previous value must be preserved in the corresponding legacy array (legacyToolReferenceFullNames for tools, legacyFullNames for tool sets) so existing .prompt.md files, tool configurations, and saved references keep resolving.

The workflow starts by identifying whether a tool or a tool set is being renamed and where it is registered: TypeScript IToolData/IToolSet versus extension package.json (languageModelTools or languageModelToolSets). It stresses the stable identifier that must never change, id for internal tools and the name field for extension tools, which maps to id and drives onLanguageModelTool activation events. Only toolReferenceName should be renamed. When a tool moves between tool sets, the old toolSet/toolName path becomes a legacy name, and repeated renames accumulate all prior names rather than dropping any.

It then covers the multi-consumer check: legacy names must be honored everywhere a tool is looked up by reference name, including prompt-file validation (getDeprecatedFullReferenceNames), tool enablement and picker aliases (getToolAliases, getToolSetAliases), the auto-approval setting (isToolEligibleForAutoApproval), and the RunInTerminalTool's own local check. The guide lists the affected source files, gives real rename examples (runInTerminal, todo, getTaskOutput), and cites reference PRs illustrating both the design and a regression where a stable name field was wrongly changed. It closes with a regression checklist for any PR that touches tool registration.