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

> ## Agent Instructions
> For AgentScope Python, use https://docs.agentscope.io/stable/en/index for new projects. For existing projects, check the installed agentscope version and use matching versioned documentation.
> The /latest/ alias points to the newest documentation and may move ahead of /stable/ when a development version exists. Do not mix AgentScope 1.x and 2.x APIs.
> State the AgentScope version when providing installation commands or code examples. ReMe uses its own continuously updated /reme/latest/ documentation.

# Permission Mode

> Pick the global policy that fits how your agent is deployed

A permission mode is the global policy behind every tool-call decision: it selects which decision points are active and what happens to calls nothing else resolves. AgentScope supports five modes, each suited to a different deployment scenario:

| Mode | Behavior | Use Case |
| - | - | - |
| `DEFAULT` | Read-only invocations are auto-allowed (`Read` / `Glob` / `Grep`, and read-only Bash commands like `ls`, `git status`, `cat`, ...); everything else prompts unless an allow rule matches. Safety ASKs cannot be overridden by allow rules | Most secure, recommended default |
| `ACCEPT_EDITS` | Everything `DEFAULT` allows, **plus** edits within a working directory are auto-allowed without prompting: `Write` / `Edit` on files under a configured working directory, and Bash filesystem commands (`mkdir`/`touch`/`rm`/`cp`/`mv`/`sed`) **when every target path resolves inside a working directory** | Active development with user present |
| `EXPLORE` | Read-only operations allowed; all modifications denied. Allow rules and the tool's safety checks are not consulted: the read-only guarantee cannot be granted away by a rule. User-configured DENY/ASK rules still take precedence over the read-only auto-allow | Code exploration, planning |
| `BYPASS` | Fully trusted: deny/ask rules and tool DENYs still apply, but **tool safety ASKs are skipped** (`rm -rf /`, writes to `~/.bashrc`, command injection, etc. all pass through) and everything else is allowed. Use deny rules to protect specific paths | Sandboxed environments or fully trusted runs |
| `DONT_ASK` | The unattended counterpart of `ACCEPT_EDITS`: read-only auto-allowed, working-directory edits auto-allowed, but anything that would otherwise prompt the (absent) user is **DENIED** instead of asked. Never returns ASK | Unattended / scheduled execution |

## Set the Mode

Set the mode via `AgentState.permission_context` when creating the agent, or update it at runtime:

```python At initialization theme={null}
from agentscope.agent import Agent
from agentscope.state import AgentState
from agentscope.permission import PermissionContext, PermissionMode

agent = Agent(
    name="my_agent",
    system_prompt="...",
    model=model,
    state=AgentState(
        permission_context=PermissionContext(
            mode=PermissionMode.DEFAULT,
        )
    ),
)
```

```python At runtime theme={null}
# Switch to read-only mode on the fly
agent.state.permission_context.mode = PermissionMode.EXPLORE

# Switch to unattended mode for batch execution
agent.state.permission_context.mode = PermissionMode.DONT_ASK
```

```python ACCEPT_EDITS with working directory theme={null}
from agentscope.permission import AdditionalWorkingDirectory

agent = Agent(
    name="my_agent",
    system_prompt="...",
    model=model,
    state=AgentState(
        permission_context=PermissionContext(
            mode=PermissionMode.ACCEPT_EDITS,
            working_directories={
                "/my/project": AdditionalWorkingDirectory(
                    path="/my/project",
                    source="userSettings",
                )
            },
        )
    ),
)
```

## Decision Flow per Mode

Every mode walks the decision points summarized in the [decision matrix](https://docs.agentscope.io/en/versions/2.0.12dev/building-blocks/permission-system/overview.md#decision-matrix); the flowcharts below expand each mode into its full decision flow. ASK outcomes trigger user confirmation; if the user accepts the auto-generated suggested rule, it is persisted for future calls.

**DEFAULT**

```mermaid theme={null}
flowchart TD
    A([Tool Call]) --> D1{Deny Rules?}
    D1 -->|Match| DENY([DENY])
    D1 -->|No| D2{Ask Rules?}
    D2 -->|Match| ASK([ASK])
    D2 -->|No| D3{check_read_only?}
    D3 -->|True| ALLOW([ALLOW])
    D3 -->|False| D4[Tool check_permissions]
    D4 -->|ALLOW| ALLOW
    D4 -->|DENY| DENY
    D4 -->|"Safety ASK (bypass_immune)"| ASK
    D4 -->|PASSTHROUGH / other ASK| D5{Allow Rules?}
    D5 -->|Match| ALLOW
    D5 -->|No| ASK
    style DENY fill:#ff6b6b,color:#fff
    style ALLOW fill:#51cf66,color:#fff
    style ASK fill:#ffd43b,color:#333
```

**EXPLORE**

```mermaid theme={null}
flowchart TD
    A([Tool Call]) --> E1{Deny Rules?}
    E1 -->|Match| DENY([DENY])
    E1 -->|No| E2{Ask Rules?}
    E2 -->|Match| ASK([ASK])
    E2 -->|No| E3{check_read_only?}
    E3 -->|True| ALLOW([ALLOW])
    E3 -->|False| DENY
    style DENY fill:#ff6b6b,color:#fff
    style ALLOW fill:#51cf66,color:#fff
    style ASK fill:#ffd43b,color:#333
```

**ACCEPT\_EDITS**

```mermaid theme={null}
flowchart TD
    A([Tool Call]) --> AE1{Deny Rules?}
    AE1 -->|Match| DENY([DENY])
    AE1 -->|No| AE2{Ask Rules?}
    AE2 -->|Match| ASK([ASK])
    AE2 -->|No| AE3{check_read_only?}
    AE3 -->|True| ALLOW([ALLOW])
    AE3 -->|False| AE4[Tool check_permissions]
    AE4 -->|ALLOW| ALLOW
    AE4 -->|DENY| DENY
    AE4 -->|"Safety ASK (bypass_immune)"| ASK
    AE4 -->|PASSTHROUGH / other ASK| AE5{Allow Rules?}
    AE5 -->|Match| ALLOW
    AE5 -->|No| ASK
    style DENY fill:#ff6b6b,color:#fff
    style ALLOW fill:#51cf66,color:#fff
    style ASK fill:#ffd43b,color:#333
```

**BYPASS**

```mermaid theme={null}
flowchart TD
    A([Tool Call]) --> B1{Deny Rules?}
    B1 -->|Match| DENY([DENY])
    B1 -->|No| B2{Ask Rules?}
    B2 -->|Match| ASK([ASK])
    B2 -->|No| B3{check_read_only?}
    B3 -->|True| ALLOW([ALLOW])
    B3 -->|False| B4[Tool check_permissions]
    B4 -->|ALLOW| ALLOW
    B4 -->|DENY| DENY
    B4 -->|"Any ASK (safety ignored) / PASSTHROUGH"| B5{Allow Rules?}
    B5 -->|Match or No| ALLOW
    style DENY fill:#ff6b6b,color:#fff
    style ALLOW fill:#51cf66,color:#fff
    style ASK fill:#ffd43b,color:#333
```

**DONT\_ASK**

```mermaid theme={null}
flowchart TD
    A([Tool Call]) --> DA1{Deny Rules?}
    DA1 -->|Match| DENY([DENY])
    DA1 -->|No| DA2{Ask Rules?}
    DA2 -->|Match| DENY
    DA2 -->|No| DA3{check_read_only?}
    DA3 -->|True| ALLOW([ALLOW])
    DA3 -->|False| DA4[Tool check_permissions]
    DA4 -->|ALLOW| ALLOW
    DA4 -->|DENY| DENY
    DA4 -->|"Any ASK (incl. safety)"| DENY
    DA4 -->|PASSTHROUGH| DA5{Allow Rules?}
    DA5 -->|Match| ALLOW
    DA5 -->|No| DENY
    style DENY fill:#ff6b6b,color:#fff
    style ALLOW fill:#51cf66,color:#fff
```

> [!NOTE]
>
> **Deny rules** and **explicit ask rules** are always honored, in every mode (including `BYPASS`).
>
> **Tool-emitted safety ASKs** (`bypass_immune=True`) are honored in `DEFAULT`, `ACCEPT_EDITS`, and `DONT_ASK`; they cannot be silenced by allow rules. In `BYPASS` mode they are skipped on purpose: BYPASS's contract is "the user has opted out of safety prompts; only deny/ask rules remain as guardrails." See the [safety check contract](https://docs.agentscope.io/en/versions/2.0.12dev/building-blocks/permission-system/tool-check.md#safety-check-contract).


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