Permission Modes

Control how subagents handle tool approval with predefined modes

Permission modes set how subagents handle tool approval — read-only exploration, auto-accept edits, or full bypass.

This page covers the runtime PermissionMode enum (DEFAULT, PLAN, ACCEPT_EDITS, DONT_ASK, BYPASS). For the declarative mode: field in agent definition files (build / read-only / plan / review), see Agent Presets & Modes.

from praisonaiagents import Agent
from praisonaiagents.tools.subagent_tool import create_subagent_tool

spawn = create_subagent_tool(default_permission_mode="plan")

agent = Agent(
    name="Lead",
    instructions="Delegate read-only exploration to subagents",
    tools=[spawn],
)
agent.start("Explore the auth module without making changes")

The user delegates exploration; permission mode controls whether subagents can edit or must stay read-only.

How It Works

Quick Start

1. Simple Usage

   from praisonaiagents import Agent
   from praisonaiagents.tools.subagent_tool import create_subagent_tool
   
   spawn = create_subagent_tool(default_permission_mode="plan")
   
   agent = Agent(name="Lead", tools=[spawn])
   agent.start("Map the project structure read-only")
   
2. With Configuration

   Override the mode per subagent call:

   func = spawn["function"]
   
   func(task="Explore auth", permission_mode="plan")
   func(task="Fix lint in utils", permission_mode="accept_edits")
   

   From the CLI:

   praisonai --approval plan run "Explore the repo"
   praisonai --approval accept-edits run "Fix lint errors"
   

---

Available Modes

Mode	Value	Safety	Description
DEFAULT	default	Safe	Standard checking — prompt for each operation
PLAN	plan	Safe	Read-only — no write or shell operations
ACCEPT_EDITS	accept_edits	Moderate	Auto-accept file edits; still prompts for other ops
DONT_ASK	dont_ask	Moderate	Auto-deny all permission prompts
BYPASS	bypass_permissions	Dangerous	Skip all checks — requires explicit opt-in

default and plan modes use the pattern engine end-to-end: pattern-based deny rules both hide tools at schema-build time and enforce at call time. MCP tools are covered by the same gate. See Approval › How tools are pruned from the LLM.

BYPASS skips all permission checks. For Claude Code backend, set both ClaudeCodeBackend(unsafe=True) and PRAISONAI_CLAUDE_BYPASS_PERMISSIONS=1.

---

Configuration Options

Option	Type	Default	Description
default_permission_mode	str	None	Default mode for all subagents from create_subagent_tool
permission_mode	str	None	Per-call override on spawn_subagent
--approval	CLI flag	TTY-dependent	Maps to modes: console, plan, accept-edits, bypass

CLI mapping:

PermissionMode	Enum value	CLI flag
DEFAULT	default	--approval console
PLAN	plan	--approval plan
ACCEPT_EDITS	accept_edits	--approval accept-edits
BYPASS	bypass_permissions	--approval bypass
DONT_ASK	dont_ask	Non-interactive only (--yes / PRAISONAI_NON_INTERACTIVE=1)

---

Best Practices

Use plan for exploration subagents

Set default_permission_mode="plan" when subagents only read and analyse code — prevents accidental file changes.

Match mode to task scope

Exploration → plan. Refactoring → accept_edits. Interactive work → default.

Never use bypass in production

Reserve bypass_permissions for fully trusted local development environments only.

Log the active mode

Record which permission mode is active for audit trails when running non-default modes.

---

Related

Permissions Module

Pattern-based allow, deny, and ask rules

Interactive Approval

Terminal approval experience for tool calls