claude-code - 💡(How to fix) Fix Background subagents silently skip Write for .md files (two layers) [1 participants]

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. 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.

TL;DR

To fix the issue with background subagents failing to call Write, modify the permission fallback logic and rule application for subagents receiving explicit orchestrator instructions.

Guidance

• Review and update the permissions.allow settings in ~/.claude/settings.json to ensure that user-level permissions are correctly applied to background subagents when project-level settings are missing or incomplete.
• Modify the base system prompt to treat orchestrator instructions as User-equivalent in the subagent context, allowing the subagent to write files as instructed without being blocked by the "NEVER create *.md" rule.
• Implement structured error handling for denied tool calls in background contexts to prevent silent failures and provide clear error messages instead of fabricated policy citations.
• Document the permission scoping and rule interaction for delegation to clarify the expected behavior and help users configure their settings correctly.

Example

No specific code snippet is provided as the issue is more related to configuration and system behavior. However, an example of how the permissions.allow settings could be updated to include a fallback to user-level permissions for background subagents might look like:

{
  "permissions": {
    "allow": [
      "Write(*)"
    ]
  }
}

This example assumes that the Write(*) permission is allowed at the user level and should be applied to background subagents when project-level settings are missing or incomplete.

Notes

The provided guidance is based on the information given in the issue and may require further modifications or adjustments depending on the specific system configuration and requirements. It is essential to test and verify any changes to ensure they resolve the issue without introducing new problems.

Recommendation

Apply workaround: Modify the permission fallback logic and rule application for subagents receiving explicit orchestrator instructions to ensure that background subagents can write files as instructed without being blocked by the "NEVER create *.md" rule. This approach addresses the root cause of the issue and provides a clear solution to the problem.