Ambiguity in Subagent Behavior When Main Agent is in Plan Mode

[coygeek]

Subject: Ambiguity in Subagent Behavior When Main Agent is in Plan Mode

Labels: bug, feature-request, documentation, safety

Issue Summary

The current documentation does not specify how a subagent behaves when the main agent is operating in Plan Mode. This ambiguity can lead to unexpected and potentially unsafe behavior, where a subagent might execute modifying actions (like writing files or running commands) even when the user has enabled a "plan-only" session.

This issue proposes clarifying this interaction and introducing an explicit configuration option to control it, ensuring predictable and safe agentic workflows.

Problem Description

The Plan Mode is a critical safety feature that allows users to have Claude analyze a codebase and formulate a plan without making any actual changes. However, when a task is delegated to a subagent, its behavior within this mode is undefined.

Scenario:

1. A user starts claude in Plan Mode (e.g., using claude --permission-mode plan or by setting it in /permissions). The user's expectation is that no files will be edited and no commands will be executed.
2. The user gives a prompt that causes the main agent to delegate a task to a specialized subagent, for example, a test-runner or code-fixer subagent which has been configured with Edit and Bash tool permissions.
3. Ambiguity: It is unclear what the subagent will do.
   • Will it inherit Plan Mode? Will it only plan to run the tests and propose edits?
   • Will it ignore Plan Mode? Will it execute its tools as configured, thereby running tests and editing files, directly contradicting the user's session-level intent?

This uncertainty undermines the safety promise of Plan Mode. A user could inadvertently approve a plan that leads to a subagent making unsupervised, and unwanted, system modifications.

Relevant Documentation

This ambiguity is present in the documentation for Subagents and IAM/Permissions:

• Subagents Documentation
• Identity and Access Management

Suggested Solution

To resolve this, we recommend adding a new, explicit configuration property to the subagent's frontmatter that defines its behavior relative to Plan Mode.

Proposed Property: planModeBehavior

Proposed Options:

• inherit (Default): The subagent respects the main agent's Plan Mode status. If the main agent is in Plan Mode, the subagent is too.
• ignore: The subagent always operates with its own defined tool permissions, regardless of the main agent's mode. This would be useful for trusted, read-only diagnostic subagents.
• force: The subagent is always in Plan Mode, even if the main agent is not. This is ideal for agents designed purely for auditing, reviewing, or planning (e.g., a security-reviewer subagent).

Example Subagent Configuration:

---
name: code-reviewer
description: A subagent that proactively reviews code for quality and style.
tools: Read, Grep
planModeBehavior: "force" # Options: "inherit" (default), "ignore", "force"
---
You are a senior code reviewer. Your task is to analyze code changes and
provide feedback. You must not make any modifications yourself.

Rationale for Change

• Safety and Predictability: Explicitly defining this interaction removes dangerous ambiguity and ensures the tool behaves as the user expects.
• Enhanced Control: It provides developers with fine-grained control over multi-agent workflows, which is essential for building robust and reliable automations.
• Enables More Sophisticated Agents: This feature would allow for the safe creation of complex agentic systems where different agents have different levels of operational capabilities, even within the same session.

By implementing this change, you would significantly enhance the safety and power of Claude Code's agentic capabilities. Thank you for your consideration.

[github-actions]

Found 3 possible duplicate issues:

1. BUG: Task Tool Agents Bypass Plan Mode Write Restrictions #5406
2. [BUG] Subagent plan mode conflict #4525
3. [BUG] Task tool calls in 'plan mode' present plans #4231

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

[catherinewu]

We added docs for plan mode subagent: https://code.claude.com/docs/en/sub-agents#plan-subagent

[github-actions]

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.