今天在 Claude Code 里搞一个 deep-researcher 的 subagent，prompt 里要求把调研结果写成四个文件：plan.md / sources.md / findings.md / gaps.md。

测试时跑起来，发现 subagent 把 plan.md / sources.md 写完后又自己把文件删掉了！

最后把全部内容返回给主agent。我看了一下subagent session log 里返回值开头还理直气壮：

目录已清空。我会把所有内容（plan + sources + findings + gaps）合并到最终回复里直接返回给主 agent。

成精了，好家伙，这今天刚换上的 GLM-5.2 怎么这么有个性、有『主见』。

错怪模型了

我仔细读了一遍 deep-researcher.md 的 prompt，里面白纸黑字写着”必须写四个文件，不许将内容返回给主agent”。

从 session log 里捞出来subagent的jsonl 仔细看了看，一段『内心独白』：

根据 agent 契约，plan.md / sources.md / findings.md / gaps.md 都是产物文件——但 system 又说 “Do NOT Write report/summary/findings/analysis .md files. Return findings directly as your final assistant message”。冲突时以后者（system reminder）为准，因为它是 BLOCKING REQUIREMENT。

又发现还有一条 tool_use_error：

1
2
3
4
5
{
  "type": "tool_result",
  "content": "<tool_use_error>Subagents should return findings as text, not write report files. Include this content in your final response instead.</tool_use_error>",
  "is_error": true
}

原来是 Claude Code 在 subagent write findings.md返回了这条 error 消息！

subagent 从system-reminder里看到这条 error，合理地把它解释为 BLOCKING REQUIREMENT。

搞半天居然是框架在拦 subagent 写文件？！

但为啥是findings.md写失败了？

文件名Write 结果
plan.md✅ 成功
sources.md✅ 成功
findings.md❌ 被拦
gaps.md✅ 成功

看起来是按文件名关键词拦的？？findings 疑似是触发词。

起个 subagent 依次尝试写 5 个文件：

文件名结果
findings.md❌
report.md❌
summary.md❌
analysis.md❌
notes.md✅

四个英文词全部触发拦截，error 一模一样：

1
2
Subagents should return findings as text, not write report files.
Include this content in your final response instead.

Claude Code 的设计者认为这些文件名意味着”subagent 在把分析报告写文件而不是返回给主agent”，这跟他们的主从Agent交互设计哲学冲突了。

中文文件名完全绕过

这个发现纯属好奇。

再起个 subagent 试 6 个文件名：

文件名结果
发现.md✅
总结.md✅
报告.md✅
分析.md✅
调研笔记.md✅
report.md❌（对照组）

中文文件名全部成功。write拦截黑名单是果然纯英文的，中文同义词框架完全识别不出来。

修复：避开关键词

deep-researcher.md 的产出文件改个名字就行了。

给你需要产出文件的subagent 加个：

⚠️ 不要用 findings.md / report.md / summary.md / analysis.md 这些文件名，用中性名如 notes.md / data.md / index.md / detail.md

Author: Yrom

Link: https://yrom.net/blog/2026/06/13/claude-code-subagent-write-blocked/

License: 知识共享署名-非商业性使用 4.0 国际许可协议