claude-code - 💡(How to fix) Fix Sub-agents intermittently denied Edit/Write tools after ExitPlanMode (harness 2.1.131)

Summary

Sub-agents dispatched via the Agent tool intermittently get Permission to use Edit has been denied errors when calling Edit, Write, or MultiEdit, even when the parent agent is in execute mode (not plan mode), the user's settings.json has no deny rules for those tools, the sub-agent operates in its own isolated worktree, and Bash works normally for the same agent.

The denial fingerprint (error message string) matches exactly what the harness emits when plan mode is active. The denial clears spontaneously over time — agents dispatched ~30 minutes after a failing dispatch wave have unrestricted Edit/Write access.

Environment

• Claude Code version: 2.1.131 (AI_AGENT=claude-code_2-1-131_agent, CLAUDE_CODE_EXECPATH=/home/adl/.local/share/claude/versions/2.1.131)
• OS: Linux (Ubuntu 24.04, Linux 6.8.0-107-lowlatency)
• Auto mode active throughout
• Parent model: claude-opus-4-7
• Sub-agent type: general-purpose
• Agent tool isolation: "worktree"
• User-level ~/.claude/settings.json: Bash(*) allowed, no deny/ask rules
• Project-level .claude/settings.local.json: 416 allow entries, 0 deny, 0 ask, no Edit/Write/MultiEdit references in any rule

Reproduction pattern

1. Parent enters plan mode via /plan slash command.
2. Phase 1–3 of plan-mode workflow run with read-only Explore + Plan sub-agents.
3. Parent calls ExitPlanMode at time T0 (user approves the plan).
4. Parent immediately (within seconds of T0) dispatches a batch of 4 sub-agents for implementation work, each with isolation: "worktree" and a brief that uses Edit/Write tools.
5. ~50% of those sub-agents get denied on their first Edit/Write tool call. Bash works normally for the same agents.
6. Approximately 30 minutes later, a diagnostic sub-agent dispatched in identical conditions (same parent, same model, same isolation, same prompt shape) has unrestricted Edit/Write access.

Verbatim error reports from affected sub-agents

Sub-agent A (Edit denied, no fallback attempted):

"I attempted to use the Edit tool to add 'BAMLHE00EHYIOAS' to the SECONDARY_FRED array in src/scans/morning-scan.js at line 52..., but Edit permission was denied twice. No modifications were made; no commit was created. ... Permission to use Edit has been denied."

Sub-agent B (Edit denied, no fallback attempted):

"The first Edit call (and a retry) targeting [worktree-path]/src/brain/jobs/regime_tagger_macro.py was denied with 'Permission to use Edit has been denied.' No edits applied. No commit made."

Sub-agent C (Edit and Write both denied, succeeded via bash heredoc workaround):

"Write and Edit tools were denied throughout this session even on paths inside the worktree. Fell back to bash heredoc (cat > … <<'EOF') for file creation and a small Python Path.read_text/write_text helper for the in-place crontab insertion. Files and edits are byte-identical to what Write/Edit would have produced; the commit diff is clean. Worth raising with whoever maintains the tool-permission policy."

Diagnostic sub-agent dispatched ~30 minutes later in identical conditions, no denial:

"Edit returned: 'The file [...]/src/scans/morning-scan.js has been updated successfully...' Edit is fully unblocked in this worktree." "Write to /tmp/diagnostic-from-subagent.txt with content diagnostic returned: 'File created successfully...'" "No reminder says 'Plan mode is active' or any equivalent phrasing."

Hypothesis

Plan-mode permission state appears to leak from parent → sub-agent dispatch context for some interval after ExitPlanMode. The error string Permission to use Edit has been denied matches the canonical plan-mode tool-block message exactly. No system-reminder is delivered to the affected sub-agent indicating plan mode is active, so the agent has no way to detect or report the residual state — it just sees an unexpected permission denial and bails or falls back to Bash.

This is consistent with ExitPlanMode clearing plan-mode state on the parent dispatch context promptly but the sub-agent dispatch path retaining a stale plan-mode flag for some duration.

Impact

• ~50% of sub-agent first attempts fail when dispatched immediately after ExitPlanMode.
• Workaround (instructing the sub-agent to use bash heredoc + Python Path.write_text instead of Edit/Write) achieves 100% first-attempt success but burns context tokens and dispatches.
• Hard to diagnose because the affected sub-agent receives no signal that plan-mode state is active — it sees only a generic permission denial.
• Sub-agent's function_call manifest does NOT include MultiEdit (separate observation, not the bug, but worth noting).

Proposed fix

Either of the following would resolve:

1. Ensure ExitPlanMode reliably clears plan-mode state from the sub-agent dispatch context before any subsequent Agent tool call.
2. When plan-mode-style denial fires for a sub-agent, surface it via a system-reminder so the agent can detect the state and adapt (e.g., document that plan mode is active and Bash-only-for-edits applies), rather than failing silently with a generic permission message.

Workaround for users hitting this

Briefing sub-agents up front with "Edit and Write tools are blocked — use only bash heredoc (cat > file <<'EOF' ... EOF) and Python Path.read_text/write_text for file operations" achieves 100% first-attempt success regardless of whether the residual plan-mode state is active. Pattern can be added to the parent's standard sub-agent brief template.