[FEATURE] Allow restrictive permission modes for subagents even when parent uses `bypassPermissions`

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When a parent agent uses bypassPermissions mode, all subagents unconditionally inherit this mode and it cannot be overridden. This creates significant security concerns:

1. Privilege escalation: A subagent with a different (potentially user-defined or third-party) system prompt inherits full autonomous system access, even if the user intended to restrict it.

1. Increased attack surface: Third-party subagents, plugins, or skills that spawn subagents automatically gain bypass privileges without explicit user consent.

1. No defense-in-depth: Users cannot create configurations like "trusted main agent with bypass, restricted subagent for untrusted operations"—the permission model is all-or-nothing.

1. Prompt injection amplification: If an attacker can influence a subagent's prompt (via plugin, skill injection, or other vector), they gain the same dangerous permissions as the parent.

The current documentation explicitly states this limitation:

"When using bypassPermissions, all subagents inherit this mode and it cannot be overridden. Subagents may have different system prompts and less constrained behavior than your main agent."

Proposed Solution

Allow users to restrict subagent permissions independently of the parent's bypassPermissions mode. Specifically:

1. Add a subagentPermissionMode option to ClaudeAgentOptions that controls the default permission mode for spawned subagents:

``typescript
options: {
permissionMode: "bypassPermissions",
subagentPermissionMode: "default" // Subagents use normal permissions
}
``

1. Allow subagent-level permissionMode to override inheritance when explicitly set in the subagent configuration, rather than having bypassPermissions always take precedence.

1. Default to more restrictive subagent permissions when parent uses bypassPermissions—perhaps acceptEdits or default instead of inheriting bypass.

1. Log subagent operations with elevated permissions so users can audit what actions were taken without approval.

Alternative Solutions

1. Require explicit opt-in for bypass inheritance: Add allowSubagentBypass: true that must be explicitly set for subagents to inherit bypassPermissions. Default to false.

1. Warning prompt before spawning subagents in bypass mode: Even if permissions bypass approval, show a one-time warning when a subagent is about to be spawned with inherited bypass permissions.

1. Per-subagent bypass allowlist: In settings.json, allow users to specify which subagent names can inherit bypassPermissions:

``json
{
"permissions": {
"subagentBypassAllowlist": ["Explore", "Plan"]
}
}
``

Priority

Critical - Blocking my work

Feature Category

CLI commands and flags

Use Case Example

Scenario: A developer uses Claude Code with bypassPermissions for trusted file operations in their own codebase. They've also installed a third-party plugin that provides a specialized "documentation-generator" subagent.

Current behavior:

1. Developer runs Claude with --dangerously-skip-permissions
2. Claude delegates documentation task to the plugin's subagent
3. The third-party subagent (with an untrusted system prompt) inherits full bypass permissions
4. The subagent can execute any bash command, modify any file, without approval

Desired behavior:

1. Developer configures: permissionMode: "bypassPermissions", subagentPermissionMode: "acceptEdits"
2. Main agent has full bypass for trusted operations
3. Third-party subagent only has auto-approved file edits, but bash commands still require approval
4. Defense-in-depth is maintained

Additional Context

Documentation references:

• https://platform.claude.com/docs/en/agent-sdk/permissions (Permission modes section)
• https://code.claude.com/en/sub-agents (Permission modes section)

Current documentation explicitly warns about this:

"Subagents may have different system prompts and less constrained behavior than your main agent. Enabling bypassPermissions grants them full, autonomous system access without any approval prompts."

The fact that this warning exists suggests the design team recognizes the risk but hasn't yet provided users a way to mitigate it.

Related security principle: Least privilege. Subagents should receive only the permissions they need for their specific task, not automatically inherit the most privileged mode available.