Background subagents do not inherit Write/Edit permission allow rules from settings.json or settings.local.json
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.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗