[BUG] Sub-agents (Task tool) write files with incorrect encoding on macOS

Sub-agents (Task tool) write files with incorrect encoding on macOS

Summary

Sub-agents invoked via the Task tool write files with incorrect text encoding on macOS, causing non-ASCII characters (German umlauts, Unicode symbols) to display as garbled text or be classified as binary data by the file command.

Environment

• Platform: macOS 14.5 (Darwin 24.5.0)
• Claude Code: Latest version
• Terminal: Built-in macOS Terminal with UTF-8 locale
• Shell: zsh with LC_ALL=en_US.UTF-8

Steps to Reproduce

1. Use Task tool to invoke any sub-agent (e.g., developer, architect)
2. Instruct sub-agent to write a file containing:

• German umlauts: äöüß ÄÖÜ
• Unicode symbols: ✅ ❌ 🔧 → ←

1. Check file encoding with file filename.md
2. View file content in terminal with cat filename.md

Expected Behavior

• file command should report: filename.md: UTF-8 Unicode text
• Terminal should display all characters correctly
• File should be readable as standard UTF-8 text

Actual Behavior

• file command reports: filename.md: data or filename.md: ISO-8859 text
• Non-ASCII characters display as garbled: äöüß becomes �ber, für becomes f�r
• Unicode symbols become unreadable placeholders
• Files appear corrupted/binary to text processing tools

Example

Sub-agent prompt:

Write a file with German text: "Für Qualität sorgen" and symbols: ✅ ❌

Result:

$ file output.md
output.md: data

$ cat output.md
F�r Qualit�t sorgen � �

Expected:

$ file output.md  
output.md: UTF-8 Unicode text

$ cat output.md
Für Qualität sorgen ✅ ❌

Workaround

Adding explicit UTF-8 encoding instructions to agent configurations (.claude/agents/*.md) resolves the issue:

## MANDATORY UTF-8 ENCODING COMPLIANCE
When writing ANY file, you MUST:
1. EXPLICITLY specify UTF-8 encoding in your instructions
2. Include German umlauts: äöüß ÄÖÜ  
3. Include Unicode symbols: ✅ ❌ 🔧 → ←

This workaround works but shouldn't be necessary - UTF-8 should be the default.

Impact

• German/International users: Cannot read sub-agent generated documentation
• Team communication: Breaks when using non-English languages
• Code comments: International comments become unreadable
• Documentation: Technical docs with symbols/umlauts corrupted

Root Cause Analysis

The Task tool appears to:

1. Write files using a non-UTF-8 encoding (possibly ISO-8859-1 or system default)
2. Not inherit proper locale settings from the parent Claude Code process
3. Lack explicit UTF-8 encoding specification in file write operations

Proposed Fix

1. Default to UTF-8: Task tool should write all files as UTF-8 by default
2. Locale inheritance: Respect system locale settings (LC_ALL, LANG)
3. Encoding parameter: Optional encoding parameter for edge cases
4. BOM handling: Consider UTF-8 BOM for Windows compatibility

System Information

$ locale
LANG=en_US.UTF-8
LC_CTYPE=en_US.UTF-8
LC_NUMERIC=en_US.UTF-8
LC_TIME=en_US.UTF-8
LC_COLLATE=en_US.UTF-8
LC_MONETARY=en_US.UTF-8
LC_MESSAGES=en_US.UTF-8
LC_PAPER=en_US.UTF-8
LC_NAME=en_US.UTF-8
LC_ADDRESS=en_US.UTF-8
LC_TELEPHONE=en_US.UTF-8
LC_MEASUREMENT=en_US.UTF-8
LC_IDENTIFICATION=en_US.UTF-8
LC_ALL=en_US.UTF-8

$ echo $LANG
en_US.UTF-8

Additional Context

This issue significantly impacts non-English speaking developers using Claude Code with sub-agents for documentation, team communication, and international projects. The current workaround (explicit agent configuration) works but creates maintenance overhead and should not be required for basic UTF-8 support in 2025.

---

Workaround confirmed working ✅
Issue affects international users 🌍
Simple fix would benefit entire community 💪