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

Spawn an engineer agent with mode: dontAsk and a prompt to create a new file
Agent will Read reference files successfully, prepare content, then report Write tool denied
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.

4.7 KiB Raw Blame History