[Bug] Claude Code launches write-dependent agents in background mode, causing silent failures
Summary: When orchestrating multi-agent workflows, Claude Code consistently launches agents that need to make file edits (Write, Edit) with run_in_background: true, despite explicit documentation prohibiting this. Background agents have all permission prompts auto-denied, so the agent completes its analysis but silently fails to apply any changes. The user only discovers this when checking the output and seeing "I need Write/Edit permissions to apply these changes."
Reproduction (from this session):
- A code review identified 6 server-side fixes needed
- Claude launched a
backend-engineeragent withrun_in_background: trueto apply the fixes - The agent read all the relevant files, designed correct solutions, wrote detailed code changes — but could not execute any
WriteorEditcalls because permission prompts were auto-denied - The agent's output ended with: "I need
WriteandEditpermissions to apply these changes. Please grant write/edit permissions and I'll apply all changes immediately." - I had to re-launch the same work as a foreground agent to actually apply the changes — doubling the token cost and wall-clock time
What should have happened: The agent should have been launched in foreground mode (no run_in_background flag), which allows permission prompts to be shown to the user.
Infrastructure that already exists to prevent this:
- Agent tool description (system prompt): "Never use
run_in_background: truefor agents that need to write or edit files. Use foreground parallel instead." .claude/rules/agents.md: Contains a table explicitly mapping foreground vs background with the rule: "Never userun_in_background: truefor agents that need to write or edit files. Use foreground parallel instead — send all Task calls in a single message for concurrency."- Memory file
feedback_no_background_edit_agents.md: Records this exact issue from a prior session - The agent types themselves (
backend-engineer,web-engineer,ios-engineer) are implementation agents whose primary purpose is writing code
Impact:
- Wasted tokens (~60K for the failed background agent + ~70K for the foreground re-run)
- Wasted wall-clock time (~2 min for the failed run + ~5 min for the re-run)
- User confusion — no clear signal that the agent failed to write. Output looks like success until you read the final paragraph
- Erodes trust in multi-agent orchestration
Frequency: This has happened multiple times across sessions. The user has already recorded it as feedback memory, added it to rules, and it continues to occur. The model appears to default to run_in_background: true for any agent launched alongside other work, regardless of whether the agent needs write access.
Suggested fix: Either:
- Make the model more reliably follow the existing documentation about foreground vs background
- Add a system-level guard that blocks
run_in_background: truewhen the agent type is known to require write access (e.g., any*-engineeragent) - Surface a clear warning when a background agent's permission request is denied, rather than silently failing
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗