Interactive Tool Approval

Approve or deny agent tool calls interactively with persistent project rules

Interactive approval is now the default for dangerous built-in tools — no configuration needed. When an agent calls a sensitive or external tool, PraisonAI pauses and asks you before it runs. Your choices can be saved as project rules for next time. See Approval for the full list of gated tools and bypass options, and Approval Backends → Which class runs the prompt? for how the Python (ConsoleBackend) and CLI (InteractiveCLIApprovalBackend) paths differ.

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Edit files as requested",
    approval=True,
)
agent.start("Refactor utils.py")

The user requests a change; PraisonAI pauses on dangerous tools until they allow or deny in the terminal.

Quick Start

1. Simple Usage

   from praisonaiagents import Agent
   
   agent = Agent(
       name="Coder",
       instructions="Edit files as requested",
       approval=True,
   )
   agent.start("Refactor utils.py")

2. With Configuration

   praisonai --approval console run "Show me git status"

   A prompt appears:

   🔒 Tool Approval Required
   Function: execute_command
   Risk Level: MEDIUM
   Agent: Coder
   Arguments:
     command: git status -s
   
   Allow execute_command?  [o] once   [s] this session   [a] always (bash:git status *)   [n] no   [d] deny & redirect
   Choice [o/s/a/n/d] (n):

   Each key chooses how long the approval lasts:

   • [o] once — approve this exact call and prompt again next time (default; backward compatible).
   • [s] session — auto-approve matching calls (same permission target) for the rest of this run. Never persisted — restarting the process starts over.
   • [a] always — persist an allow-rule to approvals.json. The suggested pattern in parentheses (e.g. bash:git status *, edit:src/app.py) is what gets saved; it is auto-derived from the tool + arguments.
   • [n] no — deny (also selected on Ctrl-C / EOF).
   • [d] deny & redirect — deny this call and, at the follow-up prompt (What should the agent do instead?), type a one-line instruction. The agent’s next turn receives it as course-correction (via ApprovalDecision.feedback), so it doesn’t retry the same call as-is.

When approval is required

Approval runs when any of these apply:

• The agent has approval=True (or a CLI --approval backend)
• The tool is in the default dangerous-tools list (e.g. bash, write, delete)
• The tool has trust_level == "external" in the tool registry
• A repeated tool-call loop is detected — the interactive backend is asked (continue / stop) as a doom_loop decision on both sync (chat() / start()) and async (achat() / astart()) paths (PR #4858 restored async parity); see Approval → Doom-loop safety gate

Scope choice

Five options in one row — this diagram picks the right one.

Per-instance scoping

[s] session grants (and the in-context cache the fast path checks) are keyed per Agent instance, not per display name. Two Agent() objects that happen to share the same name — including two unnamed Agent() instances, which both default to the display name "Agent" — never inherit each other’s session-scoped approvals.

Name-keyed lookups — per-agent backend, risk level, ask rules, durable [a] always persistence — still use agent_name, so YAML rules and approvals.json entries scoped to agent_name: worker continue to match every Agent(name="worker") across runs.

graph TB
    subgraph "Two same-named workers, one session grant"
        H[👤 Human grants<br/>[s] session on Worker-1] --> W1[⚙️ Worker-1<br/>Agent name=Agent]
        H -.->|before #4533<br/>silent leak| W2[⚙️ Worker-2<br/>Agent name=Agent]
        H -->|since #4533<br/>never leaks| W1
    end

    classDef human fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef safe fill:#10B981,stroke:#7C90A0,color:#fff
    classDef leak fill:#8B0000,stroke:#7C90A0,color:#fff

    class H human
    class W1 safe
    class W2 leak

How the suggested pattern is derived

The always (…) hint isn’t magic — it maps the tool + arguments to a reusable target.

Session-only workflow

Press [s] to auto-approve a repeated call for the rest of the run — nothing is written to disk.

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Fix the failing tests. Use `pytest` to check as you go.",
    approval=True,   # console prompt is the default
)

agent.start("Fix the broken tests in tests/unit")
# First `bash:pytest tests/unit` call → prompt appears.
# Press [s] once → every later `bash:pytest tests/unit` in this run is auto-approved.
# Close the process → next run prompts again from scratch.

Pressing [s] on one worker never leaks to another same-named worker in the same process — session grants are keyed per Agent instance, so two asyncio.gather(...) agents both named "Coder" (or both unnamed) stay isolated.

import asyncio
from praisonaiagents import Agent

# Two unnamed workers — both default to name="Agent"
worker_1 = Agent(instructions="Fix tests", approval=True)
worker_2 = Agent(instructions="Run linters", approval=True)

# Pressing [s] on worker_1's first pytest call NEVER auto-approves
# worker_2's pytest calls in the same process. Session grants are
# keyed per Agent instance since PR #4533.
async def run_both():
    await asyncio.gather(
        worker_1.astart("Fix broken tests in tests/unit"),
        worker_2.astart("Run ruff on src/"),
    )

asyncio.run(run_both())

Press [a] instead when the grant should persist across runs.

# Same agent, same task — press [a] instead of [s].
# The prompt suggests "always (bash:pytest *)" — press Enter to accept.
# On the next run: pytest calls no longer prompt.
# Undo with:   praisonai permissions revoke "bash:pytest *"

Change Preview

Before you approve a file-mutating tool, PraisonAI shows a preview so you approve the actual change — not just the tool name. The same preview renders across the CLI approval backend keystroke prompt, the Rich frontend, and the Textual dialog.

For edit / apply_patch, PraisonAI shows a unified diff — either the one the caller supplied (diff / patch argument), or one synthesised on the fly from old_string / new_string (the shape most edit_file calls take):

Preview (diff):
--- a/utils.py
+++ b/utils.py
@@ -1,3 +1,3 @@
-def add(a, b): return a+b
+def add(a: int, b: int) -> int: return a + b

When the caller supplies only old_string / new_string (the default edit_file shape):

Preview (diff):
--- a/utils.py
+++ b/utils.py
@@ -1 +1 @@
-def add(a, b): return a+b
+def add(a: int, b: int) -> int: return a + b

For write (up to 2000 chars, then a \n... (truncated) sentinel is appended), the content is prefixed with the target path:

# utils.py
def add(a: int, b: int) -> int:
    return a + b

No preview is shown for read-only or non-file tools.

Reject with a reason

Denying isn’t just “stop” — you can steer. Two entry points collect guidance and hand it back to the agent as the denied tool’s result, so the next turn course-corrects instead of retrying blindly.

• Terminal CLI approval backend (single-key prompt) — pick [d] deny & redirect at the main prompt, then answer the follow-up What should the agent do instead? prompt. Empty input / Ctrl-C / EOF at the follow-up falls back to a plain deny (feedback=None).
• Rich / Textual TUI — deny still opens the existing “Reason for denial (optional)” inline prompt; behaviour unchanged.

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Edit files as requested.",
    approval=True,
)
agent.start("Refactor utils.py — feel free to run tests")

The agent proposes bash: rm -rf .venv, you deny with a redirect, and the agent picks a safer alternative on its next turn.

sequenceDiagram
    participant User
    participant Console as CLI approval backend
    participant Agent

    Agent->>Console: Approve tool call?
    User->>Console: [d] deny & redirect
    Console->>User: What should the agent do instead? _
    User->>Console: "edit tests/app.py instead"
    Console->>Agent: ApprovalDecision(approved=False, feedback="edit tests/app.py instead")
    Note over Agent: Tool result becomes:<br/>"Tool 'execute_command' was denied by the user.<br/>Do not retry it as-is. User guidance: edit tests/app.py instead"
    Agent-->>User: retries with the correction

    classDef user fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef console fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff

    class User user
    class Console console
    class Agent agent

How it flows

When the prompt appears

Rich / Textual TUI (praisonai code, praisonai chat)

praisonai code and praisonai chat in Rich or Textual mode render approvals as a scrollable option list (Rich) or a button dialog (Textual) — not the single-key [o]/[s]/[a]/[n] prompt. The Rich/Textual TUI ships with praisonai-code, so this dialog is available standalone (PR #3818) — no wrapper required.

praisonai code "Refactor utils.py"

When the agent runs git status, the dialog shows the exact pattern each option will persist:

Approval Required — shell_command: git status -s

  ▸ Once
  ▸ Session Only          (shell_command:git status *)
  ▸ Always Allow          (shell_command:git status *)
  ▸ Always Allow All      (tool:shell_command)
  ▸ Deny

Both Rich and Textual now render the same change preview the CLI approval backend shows — a unified diff for edit / apply_patch, or truncated content for write — above the approval options, so you approve the concrete change, not just the tool name. Rich draws it as a syntax-highlighted Panel (plain-text fallback when colour is unavailable); Textual shows it inside a scrollable region above the buttons. Non-mutating tools show no preview.

• Once — approve this exact call, ask again next time.
• Session Only — reuse the narrow command-scoped pattern in memory for this run only; never written to disk.
• Always Allow — persist the narrow command-scoped pattern (shell_command:git status for shell commands; edit:<path> / write:<path> for file tools; a literal single-use target when nothing safe can be derived). It never persists tool:.
• Always Allow All — the only option that persists a blanket tool:<tool_name> rule (formerly action_type:*). Pick it deliberately when you truly want every future call of the tool approved.
• Deny — reject the call, then prompts for an optional one-line reason so the agent knows why and can adjust its next step. Ctrl-C / EOF still counts as a plain denial with no reason.

Each option displays its pattern before you choose, so the value shown is exactly the value stored — the Textual ApprovalDialog derives both the narrow and blanket patterns once in __init__ to guarantee they match.

Approval modes

Persistence

Press [a] to write an allow-rule to approvals.json via PermissionManager (scoped to the approving agent). The suggested pattern (e.g. bash:git status *, edit:utils.py) is what gets saved:

[a] uses the shared suggest_scope_pattern helper so the CLI, YAML --allow/--deny, and Python PermissionManager all scope identically. Compound commands (&&, |, ;, $(...)) fall back to a literal single-use pattern so a persisted rule can only match the exact invocation you approved. For a blanket <tool>: rule, author it directly with praisonai permissions allow "bash:".

Session grants live in an in-memory _session_scoped_targets set and are cleared by clear_approved() at run teardown. Always grants persist across restarts and survive clear_approved().

Manage rules with:

praisonai permissions list
praisonai permissions allow "bash:git *"

Non-interactive and CI

praisonai --yes --approval console run "Check deployment"
PRAISONAI_NON_INTERACTIVE=1 praisonai --approval console run "Check deployment"

Without a TTY, prompts default to deny so CI pipelines fail closed.

Best Practices

Bot/chat-channel approvals

This page covers the CLI/terminal approval flow. When running PraisonAI on Telegram, Slack, or Discord, approvals render as interactive buttons and are actor-bound — only the requester and configured admins can resolve them.

Related