[DOCS] Security Warning Needed for Inherited `bypassPermissions` in Subagents

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/agent-sdk/subagents

Section/Topic

The Permission modes section within the Subagents documentation.

Current Documentation

"If the parent uses bypassPermissions, this takes precedence and cannot be overridden."

What's Wrong or Missing?

While the documentation technically states that the mode is inherited, it lacks a critical security warning.

Subagents often use different (and sometimes simplified or less-steered) system prompts compared to the main agent. If a developer sets the main session to bypassPermissions for convenience, they may not realize they are granting a "blank check" to every subagent spawned. This creates a significant risk where a subagent could autonomously execute harmful system commands or file deletions without any human-in-the-loop, even if the subagent's specific task was intended to be narrow.

Suggested Improvement

Add a specific <Warning> block immediately following the statement about precedence.

Suggested Text:
<Warning>
Security Risk: Subagents inherit the bypassPermissions mode from the parent session. Because subagents operate with their own system prompts and may be less constrained than the main agent, enabling this mode grants them full, autonomous system access. Use extreme caution when using bypassPermissions in sessions that utilize subagents.
</Warning>

Impact

High - Prevents users from using a feature

Additional Context

• Links to related documentation: The main permissions guide (docs/en/agent-sdk/permissions.md) already contains a warning about bypassPermissions, but that warning is not echoed here in the context of the agent-delegation chain.
• Examples from other projects: Security-sensitive SDKs (like AWS or Kubernetes) typically include "recursive permission" warnings when a high-level toggle affects downstream or child processes. Given that Claude Code is an agentic tool capable of rm -rf or Bash execution, the inheritance of "bypass" mode is a high-severity context that requires visual callouts.