81 lines
4.7 KiB
Markdown
81 lines
4.7 KiB
Markdown
---
|
|
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.
|