Approval Backends

Choose how tool approvals reach a human — console prompt, plan mode, accept-edits, or a chat channel

Pick who (or what) approves a tool call — the terminal, a coding-mode fast path, or a chat channel that fans out to Slack/Telegram/Discord.

from praisonaiagents import Agent

agent = Agent(
    name="coder",
    instructions="Edit files carefully.",
    tools=["write_file"],
    approval="console",
)
agent.start("Refactor utils.py")

The user triggers a risky tool; the chosen approval backend prompts or routes the decision to a human.

Available Backends

Which class runs the prompt?

• Agent(approval=True) in Python → praisonaiagents.approval.ConsoleBackend (Rich terminal prompt, no permission-mode features).
• praisonai --approval console (also true, Console, plan, accept-edits, bypass) → praisonai_code.cli.approval_backend.InteractiveCLIApprovalBackend, which layers PermissionMode (plan / accept-edits / bypass) and declarative permission rules on top.

Both render the same unified-diff preview for file-mutating tools. The extra CLI-only features (plan mode, accept-edits, bypass, praisonai permissions rules) come from InteractiveCLIApprovalBackend.

• On any of these backends, standing registry grants (PRAISONAI_AUTO_APPROVE, YAML approve:, session grants recorded via [s]) are now checked before the backend is invoked — no more re-prompting for calls the user already blessed. Fixed in PR #4878. See Standing grants and attached backends.

How It Works

A risky tool call pauses until the chosen backend collects a human decision.

Diff preview

The console backend renders a coloured unified diff for file-mutating tools — edit_file, acp_edit_file, write_file, acp_create_file, and apply_patch — so the reviewer sees the concrete change, not truncated arguments.

The diff rides on ApprovalRequest.context["diff"], a stable public field. Wrapper backends (slack, telegram, discord, webhook, http) can read it and render or attach it in their channel — this is where custom-backend authors should look.

# Inside a custom backend
def request_approval_sync(self, request):
    diff = request.context.get("diff")
    if diff:
        ...  # render as a code block, attachment, or on-request expand

See Approval › Diff preview in approval prompts for the full tool contract and safety rules.

Backend Matrix

Backend	Where it runs	One-line meaning
console (also true/yes/1)	Standalone	Ask on the terminal, y/N — shows a rendered diff for file-mutating tools
none (also false/no/0)	Standalone	Auto-approve everything (unsafe)
auto	Standalone	Auto-approve safe read-only tools
plan	Standalone	Coding-mode plan approval
accept-edits	Standalone	Auto-accept file-edit tools
bypass	Standalone	Approve without prompting (dev)
agent	Standalone	Delegate to a reviewer agent (see below)
slack	Wrapper	Approvals routed to Slack
telegram	Wrapper	Approvals routed to Telegram
discord	Wrapper	Approvals routed to Discord
webhook	Wrapper	Custom outbound HTTP webhook
http	Wrapper	Inbound HTTP approval endpoint
secure	Wrapper	Secure-mode policy (audit-logged)
presentation	Wrapper	Presentation/demo-safe policy

Wrapper backends (slack, telegram, discord, webhook, http, secure, presentation) require pip install praisonai.

CLI opt-outs register a registry backend

praisonai code --no-safe and --dangerously-skip-approval do two things, not one:

• Set env vars — PRAISON_APPROVAL_MODE=auto, PRAISONAI_TOOL_SAFETY=off — consumed by the CLI’s own tool wiring.
• Register AutoApproveBackend on the approval registry — consumed by the core @require_approval decorator that gates critical tools like acp_execute_command. Without this the flag was a no-op for any registry-decorated tool.

A safe-mode run removes the AutoApproveBackend a prior --no-safe installed in the same process, and removes only that backend — a caller-supplied backend or one installed by --plan is preserved. A per-agent backend still wins, since the core consults Agent(approval=…) before the global registry. See Approval → Bypassing safety for the full resolution order.

---

Quick Start

from praisonaiagents import Agent

agent = Agent(
    name="Code assistant",
    instructions="Help refactor code files.",
)
agent.start("Refactor utils.py")

1. Choose your approval mode

   Terminal

   Ask the user on the terminal before each risky tool call:

   praisonai-code run --approval console "Refactor utils.py"
   

   Coding fast path

   Use plan/accept-edits mode (Claude Code-style flow) for unattended coding runs:

   praisonai-code run --approval plan "Refactor utils.py"
   

   accept-edits auto-accepts file edits; plan requires explicit plan approval before execution.

   Chat channel (wrapper)

   Route approvals to a Slack channel:

   praisonai run --approval slack --approval-timeout 300 "Refactor utils.py"
   

   Channel backends (slack, telegram, discord, webhook, http, secure, presentation) require pip install praisonai.

---

--approval-timeout

--approval-timeout takes seconds. Pass none to wait indefinitely.

praisonai-code run --approval console --approval-timeout 60 "..."
praisonai-code run --approval slack --approval-timeout none "..."

---

Reviewer-Agent Mode (--approval agent)

When you pass --approval agent, a built-in LLM reviewer gates every tool call. The default reviewer instruction is:

“You are a security reviewer. Only approve low-risk read operations. Deny anything destructive. Respond with exactly one word: APPROVE or DENY”

praisonai-code run --approval agent "List all files and summarise the project"

The reviewer responds with exactly APPROVE or DENY for each pending tool call. You can override the default instruction by passing a custom reviewer prompt via the API:

from praisonaiagents import Agent
from praisonaiagents.approval import AgentApproval

reviewer = Agent(
    name="strict-reviewer",
    instructions="Only approve file reads. Deny everything else. Reply APPROVE or DENY.",
)

agent = Agent(
    name="Assistant",
    instructions="Help with coding tasks.",
    approval=AgentApproval(approver_agent=reviewer),
)
agent.start("Read and summarise main.py")

---

Unknown-Backend Error

If you pass an unrecognised backend name, the CLI raises:

Unknown approval backend: '<value>'. Valid options: console, plan, accept-edits, bypass, auto, agent, none, discord, http, presentation, secure, slack, telegram, webhook

Use this to trap typos — the valid list is alphabetically sorted within the wrapper group.

---

Best Practices

Use console in interactive dev, agent for unattended runs

Use console in interactive dev, agent for unattended runs where a reviewer LLM can gate tools.

Pair accept-edits and plan with praisonai-code code

accept-edits and plan are the coding-mode fast paths — pair them with praisonai-code code.

Never use none outside throwaway sandboxes

none disables approval entirely; only use it in throwaway sandboxes.

---

Related

Local Tools Loading

Approval decides who says yes to your local tools.

Approval

The full approval system — dangerous tool gating, TTY detection, and safe defaults.