[BUG] Every subagent is told "Do NOT Write report/summary/findings/analysis .md files" even when its task prompt asks for exactly that — undocumented, unconditional, and not removable from a project's settings

Preflight

• [x] I have searched existing issues. The closest are #44657 (open: the Write tool refuses subagent files named report*.md etc.; this issue is about the prompt note that shipped alongside it), #30730 (closed, stale: the appended Notes: block conflicts with custom agent prompts in general), and #86070 (closed: teammates told both that the parent reads their text and that plain text is invisible).
• [x] This is a single bug report
• [x] I am using the latest version of Claude Code (2.1.296)

Summary

Claude Code appends a fixed Notes: block to the system prompt of every subagent that does not fork the parent's conversation. Since 2.1.91 its last bullet is:

Do NOT Write report/summary/findings/analysis .md files. Return findings directly as your final assistant message — the parent agent reads your text output, not files you create. (Files written as input to another tool are fine; this note is about report files.)

It is appended after the agent's own prompt, for built-in and custom agent types alike, and nothing gates it: not agent frontmatter, tools, model, or permission mode. It has no changelog entry, the sub-agents docs do not mention it, and the one mechanism that removes it is undocumented and refused from a project's .claude/settings.json.

The bullet asserts something about the parent's design that the harness cannot know. In our multi-agent setup the parent is designed to read the files its subagents write: subagents write reports to a date-stamped directory, the launcher reads them in full, nested subagents pass paths up rather than content, and the files outlive context compaction and can be shared. The final message is the lossy channel, not the file. The harness is forbidding an action the parent validly asked for, as part of a design it has no view of.

The same system prompt contradicts itself. The built-in general-purpose prompt says:

NEVER proactively create documentation files (*.md) or README files. Only create documentation files if explicitly requested.

The appended bullet has no "if explicitly requested" carve-out. Which instruction a subagent follows is model-dependent (see Reproduction, step 2).

The two mechanisms

Both arrived in 2.1.91 (2026-04-02) behind the feature flag tengu_sub_nomdrep_q7k, off by default; the flag was switched on server-side around 2026-04-06 (the timing #44657 reports) and removed in 2.1.128 (2026-05-04), making both unconditional; the parenthetical was added in 2.1.187 (2026-06-23). (found by searching each version's published npm package). In the three builds I have installed (2.1.283, 2.1.284, 2.1.296) the note is present and the flag is gone.

1. The prompt note, this issue.
2. A Write refusal for any subagent writing a basename matching ^(REPORT|SUMMARY|FINDINGS|ANALYSIS).*\.md$, case-insensitive, with the message "Subagents should return findings as text, not write report files. Include this content in your final response instead." and a tengu_subagent_md_report_blocked telemetry event. That is #44657. Our file names do not match it, so our subagents meet only the note.

Reproduction

1. On 2.1.296, launch a general-purpose subagent (built-in, or a custom one from .claude/agents/) with a task prompt that asks it to write its findings to a given .md path whose basename does not start with report, summary, findings or analysis. After it returns, grep its transcript under ~/.claude/projects/<project>/ for this note is about report files.

• Result: the sentence is in the subagent's system prompt as recorded in the prompt_snapshot attachment, twice per transcript, for built-in and custom agents alike. A custom agent's body is followed by the standard preamble ("Messages from the agent that launched you …") and then the Notes: block.

1. Repeat step 1 with a Haiku 5.5 subagent, several times, in a project whose CLAUDE.md and skills tell subagents to write their reports to files the parent reads.

• Result in our setup (40 headless runs, Haiku parent, identical task prompt): 4 of 19 Haiku 5.5 subagents declined to write the file and said why in their final message, eg. "The task asked for it, but the system instructions for this session say not to write report .md files. The content is in this handoff". In a bare project with a one-line CLAUDE.md, 0 of 6 declined. Every Sonnet 5.5 and Opus 5.5 subagent we asked for a report wrote it (about six). So the note is obeyed at a rate, and the rate depends on model and surrounding context.

1. Put CLAUDE_CODE_REMOVE_PROMPT_STRINGS in the project's .claude/settings.json env block, as a JSON array containing the bullet verbatim (leading newline and dash, em dash), and run with --debug.

• Result: [WARN] CLAUDE_CODE_REMOVE_PROMPT_STRINGS in .claude/settings.json is ignored — project-scoped settings can't set this key. Set it in ~/.claude/settings.json or managed settings instead. The same file passed with --settings removes the bullet from the subagent's prompt. The variable is also absent from the environment-variables docs.

Scope

• This issue is about the prompt note. The Write refusal is #44657; the general problem of the Notes: block overriding custom agent prompts was #30730, closed as stale.
• The ask is not that subagents should write report files by default. It is that the harness should not forbid an action the launching agent's prompt explicitly requests.

Why this matters

• It forbids a validly prompted action. A multi-agent system's author decides how results travel between agents. Writing a file the parent reads is a design, not an accident, and several comments on #44657 describe the same design for the same reasons: the parent's context stays small, the result survives compaction, and nothing is lost in a relay.
• The bullet's premise is a guess about the parent. "The parent agent reads your text output, not files you create" is true of a stock session and false of ours. The harness cannot tell which it is in, so the statement is sometimes an untruth placed in the subagent's system prompt.
• The final message is the lossy channel it is told to prefer. In this session two subagent handoffs arrived wrapped in a harness banner saying the output "matched instruction-shaped pattern(s)" with control tags neutralised; #90544 reports such handoffs truncated at about 2.5k characters, and #86070 reports teammate output discarded. A report about settings or prompts is exactly the kind of text that trips those filters.
• Compliance is model-dependent, so the failure is intermittent. A system that works on Opus and Sonnet loses one deliverable in five on Haiku, with the cause stated only in the subagent's own final message.
• There is no supported way out. Frontmatter has no field for it, hooks can only add competing text, and the one variable that removes it is undocumented and refused from the settings a repository can ship. Project authors can override the built-in general-purpose prompt, but the note is appended after their text.

Expected

• The bullet is removed, or it yields to the task prompt: eg. "unless the agent that launched you asked for a file". The Write refusal in #44657 would follow the same rule.
• The Notes: block is documented on the sub-agents page, which currently says subagents receive "only this system prompt (plus basic environment details)".
• A project can opt out through its own settings, whether by allowing CLAUDE_CODE_REMOVE_PROMPT_STRINGS at project scope or by an agent frontmatter field.

Related issues

• #44657 (open): the Write refusal for report*.md and similar names, the other half of the same feature
• #30730 (closed, stale): the appended Notes: block conflicts with custom agent prompts; same class of problem
• #86070 (closed): teammate prompt says both "the parent agent reads your text output" and that plain text is invisible to the team
• #90544 (open): subagent handoffs truncated when flagged as instruction-shaped, which is why a file is the safer channel

Is this a regression?

Not within the builds I have (2.1.283, 2.1.284, 2.1.296), where the note is identical. It was introduced in 2.1.91 behind a flag and became unconditional in 2.1.128 (from the published packages). Nothing in the changelog for those versions mentions it.

Environment

• Claude Code: 2.1.296
• OS: macOS 26.7.1 (Darwin 25.6.0)
• Terminal: Terminal.app
• Platform: Anthropic API
• Models: interactive observations under a claude-fable-5-1 session with claude-haiku-5-5, claude-sonnet-5-5 and claude-opus-5-5 subagents; the 40-run comparison used claude-haiku-5-5 parents and subagents