fix(tool): clarify write_file nested-JSON escape semantics and add tests (#2320)

* fix(tool): clarify write_file nested-JSON escape semantics and add tests

* fix(tool): improve formatting of escaping rules in CLI tool prompt

* fix(tool): align escape notation with function.arguments layer

pkg/providers/common/common_test.go

@@ -262,6 +262,22 @@ func TestDecodeToolCallArguments_StringJSON(t *testing.T) {
 	}
 }
 
+func TestDecodeToolCallArguments_StringJSON_NewlineEscape(t *testing.T) {
+	raw := json.RawMessage(`"{\"content\":\"line1\\nline2\"}"`)
+	args := DecodeToolCallArguments(raw, "write_file")
+	if args["content"] != "line1\nline2" {
+		t.Errorf("content = %q, want newline-expanded string", args["content"])
+	}
+}
+
+func TestDecodeToolCallArguments_StringJSON_LiteralBackslashN(t *testing.T) {
+	raw := json.RawMessage(`"{\"content\":\"line1\\\\nline2\"}"`)
+	args := DecodeToolCallArguments(raw, "write_file")
+	if args["content"] != `line1\nline2` {
+		t.Errorf("content = %q, want literal backslash-n", args["content"])
+	}
+}
+
 func TestDecodeToolCallArguments_EmptyInput(t *testing.T) {
 	args := DecodeToolCallArguments(nil, "test")
 	if len(args) != 0 {

pkg/providers/toolcall_utils.go

@@ -23,6 +23,12 @@ 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 (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(
+		"- `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")
 
 	for _, tool := range tools {

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."
+	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",
+				"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",
+				"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"
+	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",
+				"description": "The content to append. In `function.arguments`, use \\n for newline and \\\\n for literal backslash-n.",
 			},
 		},
 		"required": []string{"path", "content"},

pkg/tools/filesystem.go

@@ -870,7 +870,7 @@ func (t *WriteFileTool) Name() string {
 }
 
 func (t *WriteFileTool) Description() string {
-	return "Write content to a file. 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",
+				"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",

pkg/tools/filesystem_test.go

@@ -128,6 +128,45 @@ func TestFilesystemTool_WriteFile_Success(t *testing.T) {
 	}
 }
 
+// TestFilesystemTool_WriteFile_LiteralBackslashN verifies write_file keeps
+// literal backslash sequences unchanged when they are passed as plain text.
+func TestFilesystemTool_WriteFile_LiteralBackslashN(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "literal.txt")
+
+	tool := NewWriteFileTool("", false)
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":    testFile,
+		"content": `aaa\naaa`,
+	})
+
+	assert.False(t, result.IsError, "expected success, got: %s", result.ForLLM)
+
+	data, err := os.ReadFile(testFile)
+	assert.NoError(t, err)
+	assert.Equal(t, `aaa\naaa`, string(data))
+}
+
+// TestFilesystemTool_WriteFile_PreservesCRLF verifies write_file does not
+// normalize line endings and writes CRLF bytes as provided.
+func TestFilesystemTool_WriteFile_PreservesCRLF(t *testing.T) {
+	tmpDir := t.TempDir()
+	testFile := filepath.Join(tmpDir, "crlf.txt")
+	content := "line1\r\nline2\r\n"
+
+	tool := NewWriteFileTool("", false)
+	result := tool.Execute(context.Background(), map[string]any{
+		"path":    testFile,
+		"content": content,
+	})
+
+	assert.False(t, result.IsError, "expected success, got: %s", result.ForLLM)
+
+	data, err := os.ReadFile(testFile)
+	assert.NoError(t, err)
+	assert.Equal(t, []byte(content), data)
+}
+
 // TestFilesystemTool_WriteFile_CreateDir verifies directory creation
 func TestFilesystemTool_WriteFile_CreateDir(t *testing.T) {
 	tmpDir := t.TempDir()