Background subagents silently skip Write for .md files (two layers)

Resolved 💬 2 comments Opened Apr 22, 2026 by AlexKenbo Closed Jun 3, 2026

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.json and reading the base prompt.
  • Affects any task expected to produce a file (research, drafting, review).

Suggested fixes

  1. User-level permissions.allow should fall back for background subagents.
  2. 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.
  3. Denied tool calls in background contexts should produce a structured error on the tool-result channel — not a silent block the model rationalises away.
  4. Document permission scoping and rule interaction for delegation.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗