> ## 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.

# 权限规则

> 为特定工具与调用编写允许、拒绝和询问规则

`PermissionRule` 把某个工具与具体的调用模式映射到三种行为之一：`ALLOW`、`DENY`、`ASK`。规则在每种[权限模式](https://docs.agentscope.io/zh/versions/2.0.11/building-blocks/permission-system/permission-mode.md)下都以最高优先级评估：拒绝与询问规则最先，允许规则排在工具内置检查之后。

每条规则由下述字段组成。当权限引擎评估一条规则时，它会用 `rule_content` 与实际调用入参调用该工具的 `match_rule()` 方法，判断规则是否命中。

**tool\_name** `str` *required*

规则适用的工具名：`"Bash"`、`"Read"`、`"Write"`、`"Edit"`，或任意自定义工具名。

**rule\_content** `str | None` *required*

匹配模式，语义随 `tool_name` 变化：

* **Bash**：通配前缀模式（`npm run:*` 命中 `npm run build`、`npm run test`）
* **Read / Write / Edit**：glob 模式（`src/**/*.py` 命中 `src/` 下任意 `.py`）
* **其他工具**：对 JSON 序列化后的参数做精确匹配

**behavior** `PermissionBehavior` *required*

`ALLOW`、`DENY` 或 `ASK`

**source** `str` *required*

规则来源：`"userSettings"`、`"projectSettings"`、`"session"` 等。

## 匹配模式示例

`rule_content` 由各工具的 `match_rule()` 方法消费，并由 `ToolBase.generate_suggestions()` 自动生成。由于这两个方法都属于工具接口的一部分，每个工具可以独立定义自己的模式语法与匹配逻辑。

AgentScope 内置工具的模式约定如下：

**Bash**

针对 **`command`** 参数做匹配。模式格式为 `COMMAND_PREFIX:*`：前缀是命令的首段 token，`*` 匹配后续任意参数。

| 模式 | 匹配 | 不匹配 |
| - | - | - |
| `npm run:*` | `npm run build`、`npm run test` | `npm install` |
| `git commit:*` | `git commit -m "fix"` | `git push` |
| `rm:*` | `rm file.txt`、`rm -rf /tmp/x` | `ls` |

```python theme={null}
PermissionRule(
    tool_name="Bash",
    rule_content="npm run:*",
    behavior=PermissionBehavior.ALLOW,
    source="userSettings",
)
```

**文件类工具（Read / Write / Edit）**

针对 **`file_path`** 参数，通过 `fnmatch` 做 glob 匹配。

| 模式 | 匹配 |
| - | - |
| `src/**` | `src/` 下任意文件 |
| `src/**/*.py` | `src/` 下的 Python 文件 |
| `config.json` | 精确匹配该文件 |

```python theme={null}
PermissionRule(
    tool_name="Write",
    rule_content="src/**",
    behavior=PermissionBehavior.ALLOW,
    source="userSettings",
)
```

## 配置规则

规则通过两种途径进入引擎：初始化时静态配置，或运行时由用户接受建议规则动态加入。

**初始化时**：在创建智能体时把规则传入 `PermissionContext`：

```python theme={null}
from agentscope.agent import Agent
from agentscope.state import AgentState
from agentscope.permission import (
    PermissionContext, PermissionMode, PermissionRule, PermissionBehavior
)

agent = Agent(
    name="my_agent",
    system_prompt="...",
    model=model,
    state=AgentState(
        permission_context=PermissionContext(
            mode=PermissionMode.DEFAULT,
            allow_rules={
                "Bash": [PermissionRule(tool_name="Bash", rule_content="npm run:*",
                                        behavior=PermissionBehavior.ALLOW, source="userSettings")],
                "Write": [PermissionRule(tool_name="Write", rule_content="src/**",
                                         behavior=PermissionBehavior.ALLOW, source="userSettings")],
            },
            deny_rules={
                "Bash": [PermissionRule(tool_name="Bash", rule_content="rm:*",
                                        behavior=PermissionBehavior.DENY, source="userSettings")],
            },
        )
    ),
)
```

**运行时通过建议规则**：当权限系统返回 ASK 时，会基于本次调用自动生成建议规则。把已接受的规则附在 `ConfirmResult.rules` 中回传，智能体会自动写入引擎：

```python theme={null}
from agentscope.event import ConfirmResult

# ASK 决策中包含基于本次调用生成的 suggested_rules。
# 接受建议时，把它放入结果事件即可：
result = ConfirmResult(
    confirmed=True,
    tool_call=tool_call_block,  # 被确认的原始工具调用对象
    rules=[suggested_rule],  # 已接受的规则会被持久化进引擎
)
```

> [!NOTE]
>
> 允许规则无法覆盖工具发出的**安全 ASK**（`bypass_immune=True`），例如写入 `~/.ssh/` 的操作。详见[安全检查契约](https://docs.agentscope.io/zh/versions/2.0.11/building-blocks/permission-system/tool-check.md#安全检查契约)。


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