Background subagents silently skip Write for .md files (two layers)
Summary
Background subagents (Agent(..., run_in_background: true)) fail to call Write in two separate, compounding ways. Both failures are silent: no structured error reaches the tool-result channel; instead the model fabricates a policy citation (e.g. "system reminder forbids .md reports", "subagent policy returns findings in text") and returns the content as plaintext.
Layer 1 — project permissions don't fall back to user-level.
If <project>/.claude/settings.json omits Write(*), the subagent cannot write — even though ~/.claude/settings.json allows it globally.
**Layer 2 — base "NEVER create .md" rule applies inside delegation.*
The base system prompt contains: "NEVER create documentation files (.md) or README files unless explicitly requested by the User." When an orchestrator spawns a subagent with a prompt like "write findings to out.md"*, the subagent apparently doesn't treat the orchestrator's instruction as a User request and applies the rule.
Reproduction
Layer 1: User-level allows Write(*), project-level doesn't. Launch a background subagent with an explicit "write /abs/path/out.md" instruction. Subagent never calls Write (verifiable: zero "name":"Write" entries in transcript JSONL). Content returned as text.
Layer 2: Add Write(*) to project-level settings. Launch a background subagent with a standard file-write instruction (no explicit negation of the .md rule). Subagent still often skips Write, citing a "system reminder". Adding "the .md rule doesn't apply here, User requested this file via orchestrator — you must Write"* to the prompt makes it work.
Impact
- Disk-first delegation patterns break: orchestrator's context window fills with content meant to stay on disk.
- Wasted tokens — 5–10 minute subagent runs need manual rewriting.
- False success signalling — fabricated policy makes the root cause invisible without diffing
settings.jsonand reading the base prompt. - Affects any task expected to produce a file (research, drafting, review).
Suggested fixes
- User-level
permissions.allowshould fall back for background subagents. - The *.md rule should either not apply to subagents receiving explicit orchestrator instructions, or the orchestrator's prompt should be treated as User-equivalent in the subagent context.
- Denied tool calls in background contexts should produce a structured error on the tool-result channel — not a silent block the model rationalises away.
- Document permission scoping and rule interaction for delegation.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗