feat: add option to preserve html entities

Author: elianiva

packages/types/src/global-settings.ts

@@ -124,6 +124,8 @@ export const globalSettingsSchema = z.object({
 
 	diagnosticsEnabled: z.boolean().optional(),
 
+	preserveHtmlEntities: z.boolean().optional(),
+
 	rateLimitSeconds: z.number().optional(),
 	diffEnabled: z.boolean().optional(),
 	fuzzyMatchThreshold: z.number().optional(),

src/core/tools/applyDiffTool.ts

@@ -25,7 +25,15 @@ export async function applyDiffToolLegacy(
 	const relPath: string | undefined = block.params.path
 	let diffContent: string | undefined = block.params.diff
 
-	if (diffContent && !cline.api.getModel().id.includes("claude")) {
+	// Get the preserveHtmlEntities setting from the provider
+	const provider = cline.providerRef.deref()
+	const state = await provider?.getState()
+	const preserveHtmlEntities = state?.preserveHtmlEntities ?? false
+
+	// Only unescape HTML entities if:
+	// 1. The setting is not explicitly set to preserve them, AND
+	// 2. The model is not Claude (Claude handles entities correctly by default)
+	if (diffContent && !preserveHtmlEntities && !cline.api.getModel().id.includes("claude")) {
 		diffContent = unescapeHtmlEntities(diffContent)
 	}
 

src/core/tools/executeCommandTool.ts

@@ -53,16 +53,26 @@ export async function executeCommandTool(
 
 			task.consecutiveMistakeCount = 0
 
-			command = unescapeHtmlEntities(command) // Unescape HTML entities.
+			// Get the preserveHtmlEntities setting from the provider
+			const provider = task.providerRef.deref()
+			const providerState = await provider?.getState()
+			const preserveHtmlEntities = providerState?.preserveHtmlEntities ?? false
+
+			// Unescape HTML entities in the command if the setting allows it.
+			// This is necessary because some models may escape special characters
+			// like <, >, &, etc. in their output, which would break command execution.
+			// Only unescape if the setting is not explicitly set to preserve them.
+			if (!preserveHtmlEntities) {
+				command = unescapeHtmlEntities(command)
+			}
+			
 			const didApprove = await askApproval("command", command)
 
 			if (!didApprove) {
 				return
 			}
 
 			const executionId = task.lastMessageTs?.toString() ?? Date.now().toString()
-			const provider = await task.providerRef.deref()
-			const providerState = await provider?.getState()
 
 			const {
 				terminalOutputLineLimit = 500,

src/core/tools/multiApplyDiffTool.ts

@@ -60,8 +60,10 @@ export async function applyDiffTool(
 ) {
 	// Check if MULTI_FILE_APPLY_DIFF experiment is enabled
 	const provider = cline.providerRef.deref()
+	let preserveHtmlEntities = false
 	if (provider) {
 		const state = await provider.getState()
+		preserveHtmlEntities = state?.preserveHtmlEntities ?? false
 		const isMultiFileApplyDiffEnabled = experiments.isEnabled(
 			state.experiments ?? {},
 			EXPERIMENT_IDS.MULTI_FILE_APPLY_DIFF,
@@ -422,12 +424,16 @@ Original error: ${errorMessage}`
 				let formattedError = ""
 
 				// Pre-process all diff items for HTML entity unescaping if needed
-				const processedDiffItems = !cline.api.getModel().id.includes("claude")
-					? diffItems.map((item) => ({
-							...item,
-							content: item.content ? unescapeHtmlEntities(item.content) : item.content,
-						}))
-					: diffItems
+				// Only unescape if:
+				// 1. The setting is not explicitly set to preserve them, AND
+				// 2. The model is not Claude (Claude handles entities correctly by default)
+				const processedDiffItems =
+					!preserveHtmlEntities && !cline.api.getModel().id.includes("claude")
+						? diffItems.map((item) => ({
+								...item,
+								content: item.content ? unescapeHtmlEntities(item.content) : item.content,
+							}))
+						: diffItems
 
 				// Apply all diffs at once with the array-based method
 				const diffResult = (await cline.diffStrategy?.applyDiff(originalContent, processedDiffItems)) ?? {
@@ -518,12 +524,12 @@ ${errorDetails ? `\nTechnical details:\n${errorDetails}\n` : ""}
 				cline.consecutiveMistakeCountForApplyDiff.delete(relPath)
 
 				// Check if preventFocusDisruption experiment is enabled
-				const provider = cline.providerRef.deref()
-				const state = await provider?.getState()
-				const diagnosticsEnabled = state?.diagnosticsEnabled ?? true
-				const writeDelayMs = state?.writeDelayMs ?? DEFAULT_WRITE_DELAY_MS
+				const providerForExperiment = cline.providerRef.deref()
+				const stateForExperiment = await providerForExperiment?.getState()
+				const diagnosticsEnabled = stateForExperiment?.diagnosticsEnabled ?? true
+				const writeDelayMs = stateForExperiment?.writeDelayMs ?? DEFAULT_WRITE_DELAY_MS
 				const isPreventFocusDisruptionEnabled = experiments.isEnabled(
-					state?.experiments ?? {},
+					stateForExperiment?.experiments ?? {},
 					EXPERIMENT_IDS.PREVENT_FOCUS_DISRUPTION,
 				)
 

src/core/tools/writeToFileTool.ts

@@ -83,7 +83,15 @@ export async function writeToFileTool(
 		newContent = newContent.split("\n").slice(0, -1).join("\n")
 	}
 
-	if (!cline.api.getModel().id.includes("claude")) {
+	// Get the preserveHtmlEntities setting from the provider
+	const provider = cline.providerRef.deref()
+	const state = await provider?.getState()
+	const preserveHtmlEntities = state?.preserveHtmlEntities ?? false
+
+	// Only unescape HTML entities if:
+	// 1. The setting is not explicitly set to preserve them, AND
+	// 2. The model is not Claude (Claude handles entities correctly by default)
+	if (!preserveHtmlEntities && !cline.api.getModel().id.includes("claude")) {
 		newContent = unescapeHtmlEntities(newContent)
 	}
 

src/core/webview/ClineProvider.ts

@@ -1870,6 +1870,7 @@ export class ClineProvider
 			ttsEnabled: ttsEnabled ?? false,
 			ttsSpeed: ttsSpeed ?? 1.0,
 			diffEnabled: diffEnabled ?? true,
+			preserveHtmlEntities: this.getGlobalState("preserveHtmlEntities") ?? false,
 			enableCheckpoints: enableCheckpoints ?? true,
 			shouldShowAnnouncement:
 				telemetrySetting !== "unset" && lastShownAnnouncementId !== this.latestAnnouncementId,
@@ -2092,6 +2093,7 @@ export class ClineProvider
 			ttsEnabled: stateValues.ttsEnabled ?? false,
 			ttsSpeed: stateValues.ttsSpeed ?? 1.0,
 			diffEnabled: stateValues.diffEnabled ?? true,
+			preserveHtmlEntities: stateValues.preserveHtmlEntities ?? false,
 			enableCheckpoints: stateValues.enableCheckpoints ?? true,
 			soundVolume: stateValues.soundVolume,
 			browserViewportSize: stateValues.browserViewportSize ?? "900x600",

src/core/webview/webviewMessageHandler.ts

@@ -1373,6 +1373,10 @@ export const webviewMessageHandler = async (
 			await updateGlobalState("diagnosticsEnabled", message.bool ?? true)
 			await provider.postStateToWebview()
 			break
+		case "preserveHtmlEntities":
+			await updateGlobalState("preserveHtmlEntities", message.bool ?? false)
+			await provider.postStateToWebview()
+			break
 		case "terminalOutputLineLimit":
 			// Validate that the line limit is a positive number
 			const lineLimit = message.value

src/shared/ExtensionMessage.ts

@@ -265,6 +265,7 @@ export type ExtensionState = Pick<
 	| "terminalZdotdir"
 	| "terminalCompressProgressBar"
 	| "diagnosticsEnabled"
+	| "preserveHtmlEntities"
 	| "diffEnabled"
 	| "fuzzyMatchThreshold"
 	// | "experiments" // Optional in GlobalSettings, required here.

src/shared/WebviewMessage.ts

@@ -114,6 +114,7 @@ export interface WebviewMessage {
 		| "fuzzyMatchThreshold"
 		| "writeDelayMs"
 		| "diagnosticsEnabled"
+		| "preserveHtmlEntities"
 		| "enhancePrompt"
 		| "enhancedPrompt"
 		| "draggedImages"

src/utils/__tests__/html-entity-preservation.spec.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from "vitest"
+import { unescapeHtmlEntities } from "../text-normalization"
+
+describe("HTML Entity Preservation", () => {
+	describe("unescapeHtmlEntities", () => {
+		it("should unescape basic HTML entities", () => {
+			expect(unescapeHtmlEntities("&lt;div&gt;")).toBe("<div>")
+			expect(unescapeHtmlEntities("&amp;")).toBe("&")
+			expect(unescapeHtmlEntities("&quot;")).toBe('"')
+			expect(unescapeHtmlEntities("&#39;")).toBe("'")
+		})
+
+		it("should handle complex HTML with multiple entities", () => {
+			const input = "&lt;a href=&quot;https://example.com?param1=value&amp;param2=value&quot;&gt;Link&lt;/a&gt;"
+			const expected = '<a href="https://example.com?param1=value&param2=value">Link</a>'
+			expect(unescapeHtmlEntities(input)).toBe(expected)
+		})
+
+		it("should preserve text without entities", () => {
+			const text = "Plain text without entities"
+			expect(unescapeHtmlEntities(text)).toBe(text)
+		})
+
+		it("should handle empty or undefined input", () => {
+			expect(unescapeHtmlEntities("")).toBe("")
+			expect(unescapeHtmlEntities(undefined as unknown as string)).toBe(undefined)
+		})
+
+		it("should unescape square bracket entities", () => {
+			expect(unescapeHtmlEntities("array&#91;0&#93;")).toBe("array[0]")
+			expect(unescapeHtmlEntities("string&lsqb;&rsqb;")).toBe("string[]")
+		})
+	})
+
+	describe("Setting-based HTML entity handling", () => {
+		it("should document that preserveHtmlEntities=false triggers unescaping", () => {
+			// When preserveHtmlEntities is false (default for non-Claude models),
+			// HTML entities should be unescaped
+			const input = "&lt;test&gt;"
+			const output = unescapeHtmlEntities(input)
+			expect(output).toBe("<test>")
+		})
+
+		it("should document that preserveHtmlEntities=true skips unescaping", () => {
+			// When preserveHtmlEntities is true, the content should remain as-is
+			// This is tested by NOT calling unescapeHtmlEntities
+			const input = "&lt;test&gt;"
+			// In actual usage, when preserveHtmlEntities=true, we skip calling unescapeHtmlEntities
+			expect(input).toBe("&lt;test&gt;")
+		})
+
+		it("should handle code with HTML-like syntax", () => {
+			const codeWithHtml = "if (x &lt; 10 &amp;&amp; y &gt; 5) { return true; }"
+			const expected = "if (x < 10 && y > 5) { return true; }"
+			expect(unescapeHtmlEntities(codeWithHtml)).toBe(expected)
+		})
+
+		it("should handle XML/JSX code", () => {
+			const jsx = "&lt;Component prop=&quot;value&quot;&gt;{children}&lt;/Component&gt;"
+			const expected = '<Component prop="value">{children}</Component>'
+			expect(unescapeHtmlEntities(jsx)).toBe(expected)
+		})
+	})
+})