From fcf1b34ac52bc2fc3fc93205bf85d9db9320b44d Mon Sep 17 00:00:00 2001
From: lc6464 <64722907+lc6464@users.noreply.github.com>
Date: Sat, 4 Apr 2026 13:19:53 +0800
Subject: [PATCH] fix(tool): align escape notation with function.arguments
 layer

---
 pkg/providers/toolcall_utils.go |  8 ++++----
 pkg/tools/edit.go               | 10 +++++-----
 pkg/tools/filesystem.go         |  4 ++--
 3 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/pkg/providers/toolcall_utils.go b/pkg/providers/toolcall_utils.go
index c5e6ad007..7d0908158 100644
--- a/pkg/providers/toolcall_utils.go
+++ b/pkg/providers/toolcall_utils.go
@@ -23,11 +23,11 @@ func buildCLIToolsPrompt(tools []ToolDefinition) string {
 	)
 	sb.WriteString("\n```\n\n")
 	sb.WriteString("CRITICAL: The 'arguments' field MUST be a JSON-encoded STRING.\n\n")
-	sb.WriteString("Escaping rules for string arguments:\n")
-	sb.WriteString("- `\\n` means a real newline.\n")
-	sb.WriteString("- To pass a literal backslash+n (`\\n`), encode it as `\\\\n` inside arguments JSON.\n")
+	sb.WriteString("Escaping rules (what to type in `function.arguments`):\n")
+	sb.WriteString("- Use `\\n` to represent a real newline character.\n")
+	sb.WriteString("- Use `\\\\n` to represent a literal backslash+n sequence (`\\n`).\n")
 	sb.WriteString(
-		"- Because `arguments` is itself a JSON string, this often appears as `\\\\\\\\n` in the outer payload.\n\n",
+		"- `function.arguments` is a JSON-encoded string, so quotes/backslashes must be escaped in the outer payload.\n\n",
 	)
 	sb.WriteString("### Tool Definitions:\n\n")
 
diff --git a/pkg/tools/edit.go b/pkg/tools/edit.go
index 6c9f19190..09d1f545b 100644
--- a/pkg/tools/edit.go
+++ b/pkg/tools/edit.go
@@ -29,7 +29,7 @@ func (t *EditFileTool) Name() string {
 }
 
 func (t *EditFileTool) Description() string {
-	return "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file. JSON escapes apply (for example, \\n is newline and \\\\n is literal backslash-n)."
+	return "Edit a file by replacing old_text with new_text. The old_text must exist exactly in the file. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n."
 }
 
 func (t *EditFileTool) Parameters() map[string]any {
@@ -42,11 +42,11 @@ func (t *EditFileTool) Parameters() map[string]any {
 			},
 			"old_text": map[string]any{
 				"type":        "string",
-				"description": "The exact text to find and replace. JSON escapes apply: \\n is newline, \\\\n is literal backslash-n.",
+				"description": "The exact text to find and replace. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n.",
 			},
 			"new_text": map[string]any{
 				"type":        "string",
-				"description": "The text to replace with. JSON escapes apply: \\n is newline, \\\\n is literal backslash-n.",
+				"description": "The text to replace with. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n.",
 			},
 		},
 		"required": []string{"path", "old_text", "new_text"},
@@ -92,7 +92,7 @@ func (t *AppendFileTool) Name() string {
 }
 
 func (t *AppendFileTool) Description() string {
-	return "Append content to the end of a file. JSON escapes apply (for example, \\n is newline and \\\\n is literal backslash-n)."
+	return "Append content to the end of a file. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n."
 }
 
 func (t *AppendFileTool) Parameters() map[string]any {
@@ -105,7 +105,7 @@ func (t *AppendFileTool) Parameters() map[string]any {
 			},
 			"content": map[string]any{
 				"type":        "string",
-				"description": "The content to append. JSON escapes apply: \\n is newline, \\\\n is literal backslash-n.",
+				"description": "The content to append. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n.",
 			},
 		},
 		"required": []string{"path", "content"},
diff --git a/pkg/tools/filesystem.go b/pkg/tools/filesystem.go
index 3282a2ff4..52d77f665 100644
--- a/pkg/tools/filesystem.go
+++ b/pkg/tools/filesystem.go
@@ -870,7 +870,7 @@ func (t *WriteFileTool) Name() string {
 }
 
 func (t *WriteFileTool) Description() string {
-	return "Write content to a file. Content is written byte-for-byte after JSON argument decoding (for example, \\n becomes a newline, while \\\\n writes a literal backslash-n). If the file already exists, you must set overwrite=true to replace it."
+	return "Write content to a file. In `function.arguments`, use \\n for a newline and \\\\n for a literal backslash-n sequence. Content is written byte-for-byte after argument decoding. If the file already exists, you must set overwrite=true to replace it."
 }
 
 func (t *WriteFileTool) Parameters() map[string]any {
@@ -883,7 +883,7 @@ func (t *WriteFileTool) Parameters() map[string]any {
 			},
 			"content": map[string]any{
 				"type":        "string",
-				"description": "Content to write to the file. JSON escapes apply: \\n is newline, \\\\n is literal backslash-n.",
+				"description": "Content to write to the file. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n.",
 			},
 			"overwrite": map[string]any{
 				"type":        "boolean",