tool-rename-deprecation

ツール名の変更に関する非推奨化

ツールまたはツールセットの参照名を変更する場合、既存のプロンプトファイル、ツール構成、保存済みの参照を引き続き正しく解決できるよう、古い名前を必ず非推奨／レガシーの配列に追加してください。

使用する場面

回帰を検出するため、組み込みツールまたはツールセットの登録コードを変更する場合は必ずこのスキルを実行してください。

• ツールの toolReferenceName の名前を変更する
• ツールセットの referenceName の名前を変更する
• ツールを別のツールセットに移動する（古い toolSet/toolName パスがレガシー名になります）
• ツール登録を変更する PR をレビューする — レガシー名が削除されていないことを確認する

手順

ステップ 1 — 変更内容を特定する

ツールとツールセットのどちらの名前を変更するのか、また、どこで登録されているのかを確認します。

エンティティ	登録場所	名前を変更するフィールド	レガシー配列	安定 ID（変更厳禁）
ツール（IToolData）	TypeScript	toolReferenceName	legacyToolReferenceFullNames	id
ツール（拡張機能）	package.json languageModelTools	toolReferenceName	legacyToolReferenceFullNames	name（id になります）
ツールセット（IToolSet）	TypeScript	referenceName	legacyFullNames	id
ツールセット（拡張機能）	package.json languageModelToolSets	name または referenceName	legacyFullNames	—

重要：拡張機能が提供するツールでは、package.json の name フィールドが IToolData の id にマッピングされます（languageModelToolsContribution.ts の id: rawTool.name を参照）。また、アクティベーションイベント（onLanguageModelTool:<name>）にも使用されます。name フィールドの名前は変更しないでください — 変更するのは toolReferenceName のみです。

ステップ 2 — 古い名前をレガシー配列に追加する

古い toolReferenceName の値が legacyToolReferenceFullNames に含まれていることを確認してください。すでに含まれていると決めつけず、実際の配列の内容を確認してください。古い名前がすでに記載されている場合（以前の名前変更によるものなど）は、削除されていないことを確認します。記載されていない場合は追加してください。

内部／組み込みツール（TypeScript の IToolData）の場合：

// Before rename
export const MyToolData: IToolData = {
	id: 'myExtension.myTool',
	toolReferenceName: 'oldName',
	// ...
};

// After rename — old name preserved
export const MyToolData: IToolData = {
	id: 'myExtension.myTool',
	toolReferenceName: 'newName',
	legacyToolReferenceFullNames: ['oldName'],
	// ...
};

ツールが以前ツールセット内にあった場合は、完全な toolSet/toolName 形式を使用します。

legacyToolReferenceFullNames: ['oldToolSet/oldToolName'],

複数回名前を変更する場合は、過去の名前をすべて累積して追加してください。既存のエントリは削除しないでください。

legacyToolReferenceFullNames: ['firstOldName', 'secondOldName'],

ツールセットの場合は、createToolSet の呼び出し時に legacyFullNames オプションへ古い名前を追加します。

toolsService.createToolSet(source, id, 'newSetName', {
	legacyFullNames: ['oldSetName'],
});

拡張機能が提供するツール（package.json）の場合は、toolReferenceName のみを変更し、古い値を legacyToolReferenceFullNames に追加します。name フィールドの名前は変更しないでください。

// CORRECT — only toolReferenceName changes, name stays stable
{
	"name": "copilot_myTool",           // ← KEEP this unchanged
	"toolReferenceName": "newName",     // ← renamed
	"legacyToolReferenceFullNames": [
		"oldName"                       // ← old toolReferenceName preserved
	]
}

ステップ 3 — ツール名を使用する箇所をすべて確認する

レガシー名は、プロンプトの解決だけでなく、参照名によってツールを検索するすべての箇所で扱われる必要があります。主な使用箇所は次のとおりです。

• プロンプトファイル — getDeprecatedFullReferenceNames() が古い名前から現在の名前への対応付けを行い、.prompt.md の検証とコードアクションに使用されます
• ツールの有効化 — getToolAliases() / getToolSetAliases() がレガシー名を返し、ツールピッカーと有効化マップで解決できるようにします
• 自動承認の構成 — isToolEligibleForAutoApproval() が legacyToolReferenceFullNames（名前空間付きのレガシー名では / より後のセグメントも含む）を chat.tools.eligibleForAutoApproval の設定と照合します
• RunInTerminalTool — 独自の自動承認チェックがあり、LEGACY_TOOL_REFERENCE_FULL_NAMES も反復処理します

名前を変更した後、次の項目を確認してください。

1. .prompt.md ファイル内の #oldName が引き続き解決される（検証エラーが表示されない）
2. 古い名前を参照するツール構成で、引き続きツールが有効になる
3. "chat.tools.eligibleForAutoApproval": { "oldName": false } を設定していたユーザーに対して、その制限が引き続き適用される

ステップ 4 — 参照を更新する（任意）

レガシー名によって後方互換性は確保されますが、ファーストパーティの参照は新しい名前を使うよう更新してください。

• システムプロンプトと組み込みの .prompt.md ファイル
• ツールを参照名で言及しているドキュメントとモデルの説明
• 古い名前を直接参照しているテストファイル

主要なファイル

ファイル	内容
src/vs/workbench/contrib/chat/common/tools/languageModelToolsService.ts	レガシー名フィールドを持つ IToolData および IToolSet インターフェイス
src/vs/workbench/contrib/chat/browser/tools/languageModelToolsService.ts	解決ロジック：getToolAliases、getToolSetAliases、getDeprecatedFullReferenceNames、isToolEligibleForAutoApproval
src/vs/workbench/contrib/chat/common/tools/languageModelToolsContribution.ts	拡張ポイントのスキーマ、検証、重要な id: rawTool.name のマッピング（274 行目付近）
src/vs/workbench/contrib/terminalContrib/chatAgentTools/browser/tools/runInTerminalTool.ts	レガシー名を照合する、独自のローカルな自動承認チェックを持つツールの例

実例

• runInTerminal ツール：runCommands/runInTerminal から改名 → legacyToolReferenceFullNames: ['runCommands/runInTerminal']
• todo ツール：todos から改名 → legacyToolReferenceFullNames: ['todos']
• getTaskOutput ツール：runTasks/getTaskOutput から改名 → legacyToolReferenceFullNames: ['runTasks/getTaskOutput']

参考 PR

• #277047 — 設計 PR：legacyToolReferenceFullNames と legacyFullNames を導入し、解決のための基盤を構築して、最初のツール群の改名を実施しました。レガシー名を使って適切に改名する方法のテンプレートとして使用してください。
• #278506 — コンシューマー側の修正：#277047 での改名後、eligibleForAutoApproval 設定がレガシー名をチェックしていませんでした。古い名前を制限していたユーザーは、その制限が失われました。ツール参照名を利用するすべてのコンシューマーがレガシー名を考慮する必要がある理由を示しています。
• vscode-copilot-chat#3810 — 見落としの例：openSimpleBrowser から openIntegratedBrowser に改名した際、name フィールド（安定した ID）も copilot_openSimpleBrowser から copilot_openIntegratedBrowser に変更しました。toolReferenceName の後方互換性が機能したのは偶然にすぎません（以前の変更で古い名前がすでにレガシー配列に含まれていました。この改名の一環として意図的に追加されたものではありません）。

回帰チェック

ツール登録（TypeScript の IToolData、createToolSet、または package.json の languageModelTools／languageModelToolSets）に関係する PR では、次のチェックを実行してください。

1. **差分で変更された toolReferenceName または referenceName の値を検索します。**変更ごとに、変更前の値が legacyToolReferenceFullNames または legacyFullNames に記載されていることを確認してください。すでに記載されていると決めつけず、実際の配列を確認してください。
2. 拡張機能から提供されるツールの、変更された name フィールドを差分で検索します。name フィールドはツールの安定した id であり、決して変更してはいけません。変更されていた場合は、バグとして指摘してください。（これにより、アクティベーションイベント、ID によるツール呼び出し、ツールの name を参照するすべてのコードが壊れます。）
3. 既存のレガシー配列から項目が削除されていないことを確認します。
4. ツールがツールセット間を移動した場合は、古い toolSet/toolName のフルパスがレガシー配列に含まれていることを確認します。
5. **ツールセットのメンバー一覧（languageModelToolSets のコントリビューションにある tools 配列）を確認します。**ツールの toolReferenceName が変更された場合、古い名前を参照しているツールセットの tools 配列も更新する必要があります。ただし、レガシー解決システムがこれを処理するため、古い名前も引き続き機能します。

アンチパターン

• 拡張機能から提供されるツールの name フィールドを変更する — package.json の name は、languageModelToolsContribution.ts の id: rawTool.name を介して IToolData の id になります。これを変更すると、アクティベーションイベント（onLanguageModelTool:<name>）、ツールを ID で参照するコード、ツールの呼び出しがすべて壊れます。変更するのは toolReferenceName だけにし、name は変更しないでください。（name と toolReferenceName の両方が変更された vscode-copilot-chat#3810 を参照してください。）
• TypeScript で登録されたツールの id フィールドを変更する — 上記と同じ原則です。id は安定した内部識別子であり、決して変更してはいけません。
• 古い名前がすでにレガシー配列に含まれていると思い込む — フィールドの存在を確認するだけでなく、legacyToolReferenceFullNames の実際の内容を読み、必ず確認してください。レガシー配列には、さらに前の名前変更時の名前が含まれていても、今回変更する名前が含まれていない場合があります。
• 古い名前をレガシー配列から削除する — 既存の保存済みプロンプトやユーザー設定が壊れます。
• レガシー名の追加をまるごと忘れる — プロンプトファイルやツール設定が、解決されなくなっても何も通知されません。
• プロンプトの解決処理だけを更新し、他の利用箇所を更新しない — 自動承認設定、ツール有効化マップ、RunInTerminalTool のような個別ツールのチェックでも、レガシー名を考慮する必要があります（#278506 を参照してください）。