> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Safe Tools by Default

> Dangerous built-in tools require interactive approval before running — keep CI safe with a single flag

Dangerous built-in tools (shell commands, file writes, edits, deletes, and patch application) now prompt for confirmation before running. Safe mode is ON by default — no config needed.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.tools import (
    execute_command, write_file, edit_file, delete_file, apply_patch
)

agent = Agent(
    name="DevAgent",
    instructions="Help with coding tasks",
    tools=[execute_command, write_file, edit_file, delete_file, apply_patch],
)

agent.start("Refactor main.py")
```

The user asks the agent to run shell commands or edit files; dangerous built-in tools pause for interactive approval first.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Safe Tools by Default"
        A[🤖 Agent] --> B[🛡️ Tool call]
        B --> C{TTY + safe mode?}
        C -->|Yes| D[🔔 Approval prompt]
        C -->|No / bypassed| F[⚡ Execute directly]
        D -->|Approved| F
        D -->|Rejected| E[⛔ Skipped]
        F --> G[✅ Result]
    end

    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff
    classDef danger fill:#6366F1,stroke:#7C90A0,color:#fff

    class A agent
    class B,D process
    class C decision
    class G success
    class E,F danger
```

## Quick Start

**1. Run safely out of the box**

`praisonai code` is safe by default — dangerous tools pause and ask before running:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai code "Delete the tmp directory"
```

```
praisonai: delete_file wants to remove /project/tmp — allow? [y/N]
```

No flags needed. Safe mode is always on for interactive TTY sessions.

**2. Disable for a single trusted task**

When you trust a specific one-off task, use `--no-safe`:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai code --no-safe "Run the cleanup script"
```

Only that session bypasses approval. Subsequent sessions remain safe by default.

**3. Disable for CI / non-interactive scripts**

Set the environment variable once in your CI pipeline and every praisonai command in that shell skips approval prompts automatically:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
PRAISONAI_TOOL_SAFETY=off praisonai code "Run all tests and fix failures"
```

Or export it in the job environment:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
env:
  PRAISONAI_TOOL_SAFETY: "off"
```

**4. Use --dangerously-skip-approval for headless agents**

For long-running headless processes that have their own external approval gate, use the explicit flag:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai code --dangerously-skip-approval "Automated code review fix"
```

This also sets `PRAISONAI_TOOL_SAFETY=off` for the duration of the process.

***

## Which Tools Require Approval

| Tool | What it does | Gated |
| - | - | - |
| `execute_command` / `shell` | Runs arbitrary shell commands | ✅ Yes |
| `write_file` | Creates or overwrites files | ✅ Yes |
| `edit_file` | In-place file edits | ✅ Yes |
| `delete_file` | Permanently deletes files | ✅ Yes |
| `apply_patch` | Applies unified diff patches | ✅ Yes |
| Read-only tools (search, read\_file, etc.) | Read but don't modify | ❌ No |

> [!NOTE]
>
> `praisonai code` enforces per-call approval for `edit_file` / `apply_patch` through the core `@require_approval` gate (PR #6049). Previously `--safe` wrote `PRAISON_APPROVAL_MODE=prompt`, which the tool loader silently dropped, so the edit tools were auto-approved.

***

## Precedence Ladder

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    A["--dangerously-skip-approval flag"] --> B["PRAISONAI_TOOL_SAFETY=off env var"]
    B --> C["--no-safe flag"]
    C --> D["Default: safe mode ON (TTY)"]

    classDef explicit fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef env fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef flag fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef def fill:#10B981,stroke:#7C90A0,color:#fff

    class A explicit
    class B env
    class C flag
    class D def
```

Higher entries override lower entries. The explicit `--dangerously-skip-approval` flag always wins.

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant CLI as praisonai code
    participant Agent
    participant Guard as Safety Guard
    participant Tool

    User->>CLI: praisonai code "Delete old logs"
    CLI->>Agent: Start with safe_mode=True
    Agent->>Guard: delete_file("/var/log/old.log")
    Guard->>User: ⚠ delete_file wants to remove /var/log/old.log — allow? [y/N]
    User->>Guard: y
    Guard->>Tool: Execute delete_file
    Tool-->>Agent: {"success": true}
    Agent-->>User: Deleted successfully
```

On non-interactive TTYs (CI, piped stdin, `PRAISONAI_TOOL_SAFETY=off`), the guard is bypassed and tools execute immediately.

***

## Best Practices

> [accordion] Always be explicit in CI
>
> Never rely on the default behaviour in automated pipelines. Set `PRAISONAI_TOOL_SAFETY=off` explicitly in every CI job that runs `praisonai code`:
>
> ```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
> - name: Auto-fix code
>   env:
>     PRAISONAI_TOOL_SAFETY: "off"
>   run: praisonai code "Fix all linting errors"
> ```
>
> This makes the bypass intentional and visible in code review.

> [accordion] Prefer per-run flags over global env vars
>
> Use `--no-safe` for individual commands rather than exporting `PRAISONAI_TOOL_SAFETY=off` globally in your shell. A global bypass means every subsequent `praisonai code` in that shell runs without approval — easy to forget.

> [accordion] Layer approval with --dangerously-skip-approval for trusted pipelines
>
> If your pipeline already has an external approval gate (pull request review, policy-as-code), use `--dangerously-skip-approval` to document the intent clearly. This is better than `--no-safe` because it communicates that the operator consciously chose to skip the built-in guard.

> [accordion] Keep shared keys safe
>
> Never run with `PRAISONAI_TOOL_SAFETY=off` on a machine where the API key is shared across users. The approval guard is the last line of defence against a prompt injection tricking an agent into deleting or exfiltrating files.

***

## Related

> [card] [Interactive Approval](https://praison.ai/docs/features/interactive-approval.md)
>
> Deep dive into the interactive approval flow and how to customise it

> [card] [Core Controls](https://praison.ai/docs/features/core-controls.md)
>
> Other safety controls available for agents

> [card] [Shell Modes](https://praison.ai/docs/features/praison-shell.md)
>
> How `praisonai code` refuses shell operators unless a real shell is opted in

> [card] [OS Sandbox](https://praison.ai/docs/features/os-sandbox.md)
>
> Kernel-enforced containment for agent shell commands


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.