feat: add write tool for creating and overwriting files

docs/changelogs/0.6.x.md

@@ -5,6 +5,13 @@ All notable changes in the **0.6.x** release series are documented here.
 ## [Unreleased]
 
 ### Added
+- A `write` tool creates a file or replaces its entire content from a
+  structured `{path, content}` call. Content lands on disk as data instead
+  of passing through shell quoting and heredocs, which could silently
+  corrupt it; missing parent directories are created, directories and
+  non-regular files (FIFOs, device files) are refused as targets, and the
+  result states whether the file was created or overwritten. The terminal
+  echoes the target path with the content folded to its first lines.
 - A spinner animates while waiting for the model's reply or a running bash
   command, so long waits no longer look like a frozen terminal. It draws
   only when stdout is a terminal (and `NO_COLOR` is unset) and erases

docs/dev_notes/en/0.6.x.md

@@ -4,6 +4,45 @@
 
 ## 0.6.0 - 2026.08.01
 
+### Tool output polish
+
 Before continuing with the write tool, let's first add some improvements to how the agent presents its output: tool use and tool output now get separate background colors, so it is easier to tell at a glance which part is the tool use and which is the tool use result. Down the road we may want to emit something like an execution trace into a jsonl file; for now this will do.
 
 I also tried the animated ASCII indicator pi shows while waiting for the agent's reply: `⠋ Working`. To my surprise, the animated characters turn out to be a few Braille glyphs displayed in rotation — and they are fairly easy to implement, so let's just build it.
+
+### The write tool
+
+This version implements the write tool. Today the agent writes files like this:
+
+````text
+You> write a python version hello world to hello.py
+
+Agent>
+[bash]$ cat > hello.py << 'EOF'
+print("Hello, World!")
+EOF
+cat hello.py
+python3 hello.py
+print("Hello, World!")
+Hello, World!
+
+Agent> I created `hello.py` with the following content:
+
+```python
+print("Hello, World!")
+```
+
+Running it outputs: `Hello, World!`
+````
+
+Based on the revised conclusion of the [write tool research](../../research/write_tool.md), the write tool should implement:
+
+- Structured `{path, content}` input: the content lands on disk as data, never passing through shell expansion, heredoc delimiters, or quote escaping — eliminating the whole class of failures where a heredoc silently corrupts a file;
+- Create the file when it does not exist, overwrite it whole when it does, and state which of the two happened in the result;
+- Path handling identical to read's: absolute or relative to the working directory, with a leading `~` expanded;
+- Automatically create missing parent directories;
+- Refuse directories and non-regular files (FIFOs, device files) as write targets — opening a FIFO for writing blocks without a timeout and hangs the session, and a device file could be written by mistake; read already performs the same check on its targets, and write follows the same approach;
+- Write the content exactly as given, as UTF-8 text, with no newline or whitespace normalization;
+- Error messages state what to do next, in read's style;
+- The terminal echoes the target path and a content preview folded to the first few lines, consistent with the tool output shading presentation;
+- The tool description limits its purpose to new files and whole-file rewrites (appending and bulk transforms still go through bash) and claims no safety whatsoever: no prior-Read check, no mtime/revision staleness guard, no atomic replace — the semantics are last-writer-wins.

docs/dev_notes/zh-CN/0.6.x.md

@@ -3,6 +3,44 @@
 > 本文件为**手写中文源文件**(source of truth);英文版 [`../en/0.6.x.md`](../en/0.6.x.md) 由其生成。
 
 ## 0.6.0 - 2026.08.01
+### 工具输出优化
 继续开发 write tool 之前，先加一些 Agent 输出方式相关的优化，tool use 和 tool output 背景颜色分开，更容易看出哪里是 tool use ，哪里是 tool use result。后续可能需要输出类似执行轨迹的东西，放 jsonl 里，目前暂时先这样处理。
 
 另外，尝试了一下 pi 里等待 Agent 回复时的 ascii 动态字符: `⠋ Working`，没想到动态字符居然是几个交替显示的盲文，实现起来也比较容易，就先实现吧。
+
+### write 工具
+
+这一版本实现 write 相关工具，当前这个 agent 对文件的写入方式是这样：
+
+````text
+You> write a python version hello world to hello.py
+
+Agent>
+[bash]$ cat > hello.py << 'EOF'
+print("Hello, World!")
+EOF
+cat hello.py
+python3 hello.py
+print("Hello, World!")
+Hello, World!
+
+Agent> I created `hello.py` with the following content:
+
+```python
+print("Hello, World!")
+```
+
+Running it outputs: `Hello, World!`
+````
+
+基于 [write 工具调研](../../research/write_tool.md)修正后的结论，write 工具要实现的功能：
+
+- 结构化 `{path, content}` 入参：内容作为数据直接落盘，不经过 shell 展开、heredoc delimiter 和引号转义，消除 heredoc 静默写坏文件这一整类失败；
+- 文件不存在则创建，存在则整文件覆盖，并在结果中说明是哪一种；
+- 路径处理与 read 一致：绝对路径或相对工作目录，展开开头的 `~`；
+- 自动创建缺失的父目录；
+- 拒绝目录和非常规文件（FIFO、设备文件）作为写入目标——对 FIFO 的写打开会无超时阻塞挂死会话，设备文件则可能被误写；read 对读取目标已有同样的检查，write 沿用同一做法；
+- 内容按给定原样写入，UTF-8 文本，不做换行或空白归一化；
+- 错误信息按 read 的风格指出下一步该怎么做；
+- 终端回显目标路径和折叠到前几行的内容预览，与 tool output shading 的展示风格一致；
+- 工具描述限定用途为新建文件和整文件重写（追加、批量变换仍走 bash），并且不宣称任何安全性：没有先 Read 检查、没有 mtime/revision 防陈旧、没有原子替换——语义就是 last-writer-wins。