Background agents cannot perform write operations despite settings allow rules

Status Closed — not planned

Reported on v2.1.81

Maintainer reply None cached

Activity 7 comments · opened Mar 29, 2026 · closed May 1, 2026

Description

Background agents (launched via the Agent tool with run_in_background: true) cannot perform any write operations, even when those operations are explicitly in the permissions.allow list in settings.json. Read-only operations from the allow list work fine.

Reproduction

Add these to ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(mkdir *)",
      "Bash(unzip *)",
      "Bash(touch *)",
      "Bash(echo *)"
    ]
  }
}

Launch a background agent:

Launch a background agent that runs these commands one at a time and reports success/failure: 1) git status 2) mkdir -p /tmp/test 3) unzip --help 4) touch /tmp/test.txt 5) echo hello > /tmp/test2.txt

Results

| Command | Type | Result |
|---------|------|--------|
| git status | read-only | pass |
| unzip --help | read-only (no file write) | pass |
| mkdir -p /tmp/test | write (filesystem) | fail |
| mkdir -p ./test | write (working dir) | fail |
| touch /tmp/test.txt | write | fail |
| echo hello > /tmp/test.txt | write | fail |

The Write tool is also denied for background agents, not just Bash writes.

Running the same agent in the foreground (without run_in_background) — all operations succeed (with interactive prompts where needed).

Expected behavior

According to the subagents documentation:

Before launching, Claude Code prompts for any tool permissions the subagent will need, ensuring it has the necessary approvals upfront.

However, no pre-approval prompt fires before the background agent launches. The agent simply starts and then all write operations are auto-denied.

Operations that are in the permissions.allow list should be auto-approved for background agents the same way they are for foreground agents, without requiring an interactive prompt.

Additional context

Read-only allow-listed Bash commands DO work in background agents, confirming the allow list IS read
The issue is specifically with write operations (Bash writes + Write tool)
additionalDirectories / allowedDirectories with /tmp configured — no effect
Tested across fresh sessions and --continue sessions — same behavior
Claude Code version: 2.1.81
Platform: macOS Darwin 23.6.0

Workaround

Run agents in the foreground instead of background. Foreground agents can prompt for write permissions interactively.

View original on GitHub ↗

7 Comments

github-actions[bot] · 6 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

yurukusa · 6 months ago

Workaround: use bypassPermissions + hooks for safety
Background agents run in a restricted sandbox where permissions.allow rules may not fully apply. As a workaround, you can:

Set the agent to mode: "bypassPermissions" (or "auto") to skip the broken permissions layer
Add PreToolUse hooks to enforce safety at the process level (hooks fire regardless of permission mode)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/hooks/destructive-guard.sh"
          }
        ]
      }
    ]
  }
}

The hook blocks dangerous commands (rm -rf, git push --force, etc.) while allowing everything else through. This gives background agents write access while maintaining safety guardrails.
The key difference: permissions.allow is evaluated by the model's permission resolver (which may not work correctly for background agents), but hooks run at the process level and fire for every tool call regardless of agent type.

wotpsycho · 6 months ago

Workaround confirmed: `permissionMode: bypassPermissions` in agent frontmatter

Tested the workaround suggested above — adding permissionMode: bypassPermissions to a custom agent definition (.claude/agents/quality-audit.md) fixes background writes.

Test results with permissionMode: bypassPermissions:

| Operation | Result |
|-----------|--------|
| mkdir -p /tmp/... (Bash) | PASS |
| echo "..." > /tmp/.../test.txt (Bash) | PASS |
| Write tool to /tmp/.../write-tool.txt | PASS |
| PreToolUse hook (ls → Glob redirect) | Still fires correctly |

Without it (default / general-purpose agent): All writes denied, reads work — same as original report.

Key takeaway: permissionMode: bypassPermissions bypasses the broken permission resolver, and PreToolUse hooks still enforce safety at process level. This only works for custom agents defined in .claude/agents/ — general-purpose agents launched via the Agent tool can't use this workaround since there's no way to set permissionMode on ad-hoc agent launches.

Tested on macOS Darwin 23.6.0, Claude Code latest.

jwebbdev · 6 months ago

I've been running into a similar issue. What I noticed is that a general allow of "Bash" tends to work for mkdir etc. But no combination of "Bash(mkdir *)" seems to work. Combining it with general "Write" or "Edit" permissions doesn't seem to help either. I'm not sure if that's the same result for you, but it would imply that it is possible to bypass the permission checks for them via the allowlist but not granularly.

It would be great to be able to use these properly.

github-actions[bot] · 5 months ago

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

betovildoza · 5 months ago

Consolidating discussion of this cluster (15+ open issues sharing the same root cause in the background-subagent permissions resolver) at #50267 — please add 👍 there if affected, so triage can see the aggregate impact.

github-actions[bot] · 3 months ago

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.