---
title: "Fix: Subagent Write/Edit tools blocked by permission mode mismatch"
description: "Claude Code subagents cannot use Write or Edit tools unless spawned with mode: acceptEdits — other permission modes (dontAsk, auto, bypassPermissions) do not grant file-write capability."
type: troubleshooting
domain: development
tags: [troubleshooting, claude-code, permissions, agents, subagents]
---

# Fix: Subagent Write/Edit tools blocked by permission mode mismatch

**Date:** 2026-03-28
**Severity:** Medium — blocks all agent-driven code generation workflows until identified

## Problem

When orchestrating multi-agent code generation (spawning engineer agents to write code in parallel), all subagents could Read/Glob/Grep files but Write and Edit tool calls were silently denied. Agents would complete their analysis, prepare the full file content, then report "blocked on Write/Edit permission."

This happened across **every** permission mode tried:
- `mode: bypassPermissions` — denied (with worktree isolation)
- `mode: auto` — denied (with and without worktree isolation)
- `mode: dontAsk` — denied (with and without worktree isolation)

## Root Cause

Claude Code's Agent tool has multiple permission modes that control different things:

| Mode | What it controls | Grants Write/Edit? |
|------|-----------------|-------------------|
| `default` | User prompted for each tool call | No — user must approve each |
| `dontAsk` | Suppresses user prompts | **No** — suppresses prompts but doesn't grant capability |
| `auto` | Auto-approves based on context | **No** — same issue |
| `bypassPermissions` | Skips permission-manager hooks | **No** — only bypasses plugin hooks, not tool-level gates |
| `acceptEdits` | Grants file modification capability | **Yes** — this is the correct mode |

The key distinction: `dontAsk`/`auto`/`bypassPermissions` control the **user-facing permission prompt** (whether the user gets asked to approve). But Write/Edit tools have an **internal capability gate** that checks whether the agent was explicitly authorized to modify files. Only `acceptEdits` provides that authorization.

## Additional Complication: permission-manager plugin

The `permission-manager@agent-toolkit` plugin (`cmd-gate` PreToolUse hook) adds a second layer that blocks Bash-based file writes (output redirection `>`, `tee`, etc.). When agents fell back to Bash after Write/Edit failed, the plugin caught those too.

- `bypassPermissions` mode is documented to skip cmd-gate entirely, but this didn't work reliably in worktree isolation
- Disabling the plugin (`/plugin` → toggle off `permission-manager@agent-toolkit`, then `/reload-plugins`) removed the Bash-level blocks but did NOT fix Write/Edit

## Fix

**Use `mode: acceptEdits`** when spawning any agent that needs to create or modify files:

```
Agent(
    subagent_type="engineer",
    mode="acceptEdits",  # <-- This is the critical setting
    prompt="..."
)
```

**Additional recommendations:**
- Worktree isolation (`isolation: "worktree"`) may compound permission issues — avoid it unless the agents genuinely need isolation (e.g., conflicting file edits)
- For agents that only read (reviewers, validators), any mode works
- If the permission-manager plugin is also blocking Bash fallbacks, disable it temporarily or add classifiers for the specific commands needed

## Reproduction

1. Spawn an engineer agent with `mode: dontAsk` and a prompt to create a new file
2. Agent will Read reference files successfully, prepare content, then report Write tool denied
3. Change to `mode: acceptEdits` — same prompt succeeds immediately

## Environment

- Claude Code CLI on Linux (Nobara/Fedora)
- Plugins: permission-manager@agent-toolkit (St0nefish/agent-toolkit)
- Agent types tested: engineer, general-purpose
- Models tested: sonnet subagents

## Lessons

- **Always use `acceptEdits` for code-writing agents.** The mode name is the clue — it's not just "accepting" edits from the user, it's granting the agent the capability to make edits.
- **`dontAsk` ≠ "can do anything."** It means "don't prompt the user" — but the capability to write files is a separate authorization layer.
- **Test agent permissions early.** When building a multi-agent orchestration workflow, verify the first agent can actually write before launching a full wave. A quick single-file test agent saves time.
- **Worktree isolation adds complexity.** Only use it when agents would genuinely conflict on the same files. For non-overlapping file changes, skip isolation.
- **The permission-manager plugin is a separate concern.** It blocks Bash file-write commands (>, tee, cat heredoc). Disabling it fixes Bash fallbacks but not Write/Edit tool calls. Both layers must be addressed independently.