Background subagents do not inherit Write/Edit permission allow rules from settings.json or settings.local.json

Open 💬 1 comment Opened Jun 12, 2026 by JacobButts

Summary

Background subagents (Agent tool with run_in_background: true) are denied Write/Edit tool calls even when an allow rule is present in either project .claude/settings.local.json or user-global ~/.claude/settings.json. Foreground subagents with the identical prompt, model, and target path succeed under the same rules.

Environment

  • Claude Code CLI, model claude-opus-4-7 (main session), sonnet (subagents)
  • Platform: WSL2 Linux on Windows 11
  • Subagent type: general-purpose

Reproduction

Allow rule under test: Write(/home/jake/scripts/docs/**)

| Probe | Subagent type | Rule location | Result |
|-------|---------------|---------------|--------|
| 1 | Foreground | Project (settings.local.json) | allowed |
| 2 | Background | Project (settings.local.json) | denied |
| 3 | Background | User-global (~/.claude/settings.json) | denied |
| 4 | Foreground | User-global (~/.claude/settings.json) | allowed |

All four probes used the same minimal prompt: "Write a file to /home/jake/scripts/docs/_perm_probe_*.md with one line of content. Report success/failure."

Denial message returned to the subagent:

Permission to use Write has been denied. IMPORTANT: You may attempt to accomplish this action using other tools...

Expected

Background subagents should inherit allow rules from the same settings files as foreground subagents and the main session, OR the docs should clearly state that background subagents run with a narrower permission scope and which permissions they actually honor.

Impact

Fire-and-forget background subagents are unusable for any task requiring file writes outside the project cwd, forcing main-session takeover or foreground subagent fallback. The workaround "run it in foreground" was not discoverable without controlled testing.

Ask

Either (a) fix propagation so background subagents honor allow rules, or (b) document the narrower scope and the recommended pattern in the Agent / permissions docs.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗