Add explanatory comments for automated workflow focus preservation

- Add detailed comments explaining why we preserve focus during automated workflows
- Clarify the security implications of accidental API key exposure
- Reference issue #4574 for additional context
- Improve code documentation for future maintainers

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

src/core/mentions/index.ts

@@ -37,7 +37,9 @@ export async function openMention(mention?: string): Promise<void> {
 		if (mention.endsWith("/")) {
 			vscode.commands.executeCommand("revealInExplorer", vscode.Uri.file(absPath))
 		} else {
-			// Check if we're in an automated workflow to preserve chat focus during AI processing
+			// Check if we're in an automated workflow to preserve chat focus during AI processing.
+			// When users mention files (e.g., @/path/to/file.txt) while the AI is actively processing,
+			// we want to prevent the chatbox from losing focus to avoid accidental input interruption.
 			const shouldPreserveFocus = isInAutomatedWorkflowFromVisibleProvider()
 
 			openFile(absPath, { preserveFocus: shouldPreserveFocus })

src/core/webview/webviewMessageHandler.ts

@@ -427,7 +427,10 @@ export const webviewMessageHandler = async (
 			openImage(message.text!)
 			break
 		case "openFile":
-			// Check if we're in an automated workflow to preserve chat focus during AI processing
+			// Check if we're in an automated workflow to preserve chat focus during AI processing.
+			// This prevents the chatbox from losing focus when the AI is actively working,
+			// which could cause users to accidentally type sensitive information (like API keys)
+			// into the wrong window. See issue #4574 for more context.
 			const shouldPreserveFocus = isInAutomatedWorkflowFromProvider(provider)
 
 			openFile(message.text!, {