From 85f2bd64dcbb8e13ac7f739a0e7c132c786d7a38 Mon Sep 17 00:00:00 2001
From: Toray Altas <toray.altas@gmail.com>
Date: Fri, 16 Jan 2026 17:10:13 -0500
Subject: [PATCH] fix: clarify tool names for hooks matchers

Update Hooks UI to explicitly document that matchers use Roo Code internal tool IDs (e.g. write_to_file, execute_command) rather than display labels.
Add regression test ensuring display labels do not unintentionally match internal IDs.
---
 src/services/hooks/__tests__/HookMatcher.spec.ts |  8 ++++++++
 .../src/components/settings/HooksSettings.tsx    | 16 +++++++++++++++-
 webview-ui/src/i18n/locales/en/settings.json     |  6 ++++++
 3 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/services/hooks/__tests__/HookMatcher.spec.ts b/src/services/hooks/__tests__/HookMatcher.spec.ts
index 004857366a..caca0a9a24 100644
--- a/src/services/hooks/__tests__/HookMatcher.spec.ts
+++ b/src/services/hooks/__tests__/HookMatcher.spec.ts
@@ -189,6 +189,14 @@ describe("HookMatcher", () => {
 			const matching = filterMatchingHooks(hooks, "Write")
 			expect(matching).toHaveLength(0)
 		})
+
+		it("should NOT treat Claude Code-style tool labels as Roo Code internal tool ids", () => {
+			// Roo Code hook matching is against tool ids like write_to_file/apply_diff.
+			// A Claude Code-style matcher like Write|Edit should not match apply_diff.
+			const hooks = [createMockHook("hook1", "Write|Edit")]
+			const matching = filterMatchingHooks(hooks, "apply_diff")
+			expect(matching).toHaveLength(0)
+		})
 	})
 
 	describe("hookMatchesTool", () => {
diff --git a/webview-ui/src/components/settings/HooksSettings.tsx b/webview-ui/src/components/settings/HooksSettings.tsx
index fee595d2af..63b229a45c 100644
--- a/webview-ui/src/components/settings/HooksSettings.tsx
+++ b/webview-ui/src/components/settings/HooksSettings.tsx
@@ -127,7 +127,21 @@ export const HooksSettings: React.FC = () => {
 				)}
 
 				{/* Note about edits requiring reload */}
-				<div className="text-sm text-vscode-descriptionForeground mb-4">{t("settings:hooks.reloadNote")}</div>
+				<div className="text-sm text-vscode-descriptionForeground mb-4">
+					{t("settings:hooks.reloadNote")}
+					<br />
+					{t("settings:hooks.matcherNote")}
+					<br />
+					<span className="font-medium">{t("settings:hooks.matcherExamplesLabel")}</span>
+					<ul className="list-disc list-inside mt-1">
+						<li>
+							<code className="font-mono">{t("settings:hooks.matcherExamples.writeOrEdit")}</code>
+						</li>
+						<li>
+							<code className="font-mono">{t("settings:hooks.matcherExamples.readOnly")}</code>
+						</li>
+					</ul>
+				</div>
 
 				{/* Hooks list */}
 				{enabledHooks.length === 0 ? (
diff --git a/webview-ui/src/i18n/locales/en/settings.json b/webview-ui/src/i18n/locales/en/settings.json
index a175bbefc1..514b7b5f74 100644
--- a/webview-ui/src/i18n/locales/en/settings.json
+++ b/webview-ui/src/i18n/locales/en/settings.json
@@ -55,6 +55,12 @@
 		"projectHooksWarningTitle": "Project-level hooks detected",
 		"projectHooksWarningMessage": "This project includes hook configurations that will execute shell commands. Only enable hooks from sources you trust.",
 		"reloadNote": "Changes to hook configuration files require clicking Reload to take effect.",
+		"matcherNote": "Matchers are evaluated against Roo Code's internal tool IDs (e.g. write_to_file, edit_file, apply_diff, apply_patch), not UI labels like Write/Edit.",
+		"matcherExamplesLabel": "Examples:",
+		"matcherExamples": {
+			"writeOrEdit": "write_to_file|edit_file|apply_diff|apply_patch",
+			"readOnly": "read_file|list_files"
+		},
 		"noHooksConfigured": "No hooks configured",
 		"noHooksHint": "Create hook configuration files to automate actions on tool execution events.",
 		"enabled": "Enabled",