Permission System - 权限管道与行动控制

管道顺序原则#

四层顺序有深刻理由：

顺序为什么是 Deny → Mode → Allow → Ask？

• Deny 优先：安全高于效率。危险操作必须先拦截，不问用户意愿。
• Mode 第二：会话风格控制。Plan 模式下写操作必须拦截，不管 Allow 规则。
• Allow 第三：效率优化。白名单命中直接放行，不需要问用户。
• Ask 兜底：未知操作问用户。用户决策优于系统猜测。

管道执行流程#

1
def permission_pipeline(tool_call):
2
    # Layer 1: Bash特殊检查（独立前置）
3
    if tool_call.tool == "bash":
4
        result = bash_validator(tool_call.input["command"])
5
        if result == "deny":
6
            return PermissionDecision(behavior="deny", reason="Bash validator")
7

8
    # Layer 2: Deny Rules
9
    if matches_deny_rules(tool_call):
10
        return PermissionDecision(behavior="deny", reason="matched deny rule")
11

12
    # Layer 3: Mode Check
13
    if mode == "plan" and is_write_operation(tool_call):
14
        return PermissionDecision(behavior="deny", reason="plan mode blocks writes")
15
    if mode == "auto" and is_safe_read(tool_call):
16
        return PermissionDecision(behavior="allow", reason="auto mode allows reads")
17

18
    # Layer 4: Allow Rules
19
    if matches_allow_rules(tool_call):
20
        return PermissionDecision(behavior="allow", reason="matched allow rule")
21

22
    # Layer 5: Ask User（兜底）
23
    return PermissionDecision(behavior="ask", reason="no rules matched")

关键点：管道在 dispatch map 和 handler 之间——找到 handler 后不直接执行，先过管道。

验证你的理解#

Q1：Allow 规则命中后，还会 Ask 用户吗？

:::details 答案 不会。Allow 规则命中直接 allow，不问用户。

管道顺序：Deny → Mode → Allow → Ask。

Allow 是效率层——白名单命中表示”系统已判断安全”，不需要问用户。

如果 Allow 后还要 Ask，白名单就失去效率意义。每次都要问用户，流畅度下降。 :::

default 模式：用户参与决策#

适用场景：日常交互，用户希望参与关键决策。

特点：未知操作问用户，用户决策优于系统猜测。

plan 模式：只读约束#

适用场景：分析代码、审查日志、查看配置——只看不改。

特点：写操作强制拦截，不问用户。这是会话风格控制，不是安全判断。

auto 模式：安全自动过#

适用场景：高流畅度探索，减少确认中断。

特点：安全操作（read_file、search）自动放行，危险操作（write_file、bash危险命令）问用户。

验证你的理解#

Q2：plan 模式下，Allow 规则命中的写操作会被放行吗？

:::details 答案 不会。plan 模式下写操作强制拦截，不管 Allow 规则。

管道顺序：Deny → Mode → Allow → Ask。

Mode 检查在 Allow 之前——plan 模式写操作在 Mode 层就被 Deny，不会到达 Allow。

设计理由：plan 模式是”只读约束”，是会话风格控制，高于白名单效率。用户说”只看不改”，系统必须遵守，不能因为白名单而放行写操作。 :::

Bash 危险 pattern#

检查时机：bash 命令进入权限管道前，先过 Bash Validator。

1
def bash_validator(command: str) -> str:
2
    # 危险pattern检查
3
    dangerous_patterns = ["sudo", "rm -rf", "$(", "> /etc/", "> ~/.ssh/"]
4
    for pattern in dangerous_patterns:
5
        if pattern in command:
6
            return "deny"
7

8
    # 可疑重定向检查
9
    if ">" in command and not is_safe_redirect(command):
10
        return "deny"
11

12
    return "allow"  # 通过，继续走后续管道

Bash 读写分类#

bash 命令需要判断读还是写操作：

判断方法：内容分析——识别命令关键词。

1
def classify_bash_operation(command: str) -> str:
2
    read_keywords = ["ls", "cat", "find", "grep", "git status", "git log", "git diff"]
3
    write_keywords = ["rm", "mv", "cp", "git add", "git commit", "git push", ">"]
4

5
    for kw in read_keywords:
6
        if kw in command:
7
            return "read"
8

9
    for kw in write_keywords:
10
        if kw in command:
11
            return "write"
12

13
    return "unknown"  # 需进一步判断或问用户

验证你的理解#

Q3：git status 是读操作还是写操作？为什么？

:::details 答案 git status 是读操作。

git status 只查看状态，不修改 Git 工作区、暂存区、仓库。

常见误判：看到 “git” 就认为是写操作。正确分类需要理解命令语义：

命令	类型	原因
git status	读	只查看状态
git log	读	只查看历史
git diff	读	只查看差异
git add	写	修改暂存区
git commit	写	创建 commit
git push	写	写入远程

plan 模式下，git status 可以执行，git add 被拦截。 :::

与后续课程的关系#

理解 L07 后，你会发现后续课程都在 Permission System 上叠加——循环本身始终不变：

核心洞察：Permission System 是”行动可靠可控”的机制。理解 L07，就理解了 Agent 如何”行动先过安全判断”。后续课程都在扩展权限机制——权限继承、跨会话保留、执行前后插入逻辑。

L07 核心概念的理解升级路径#

如何检验你达到了 L2？#

用这个问题自测：

如果迁移到数据库 Agent，权限系统怎么设计？

:::details L2 层级回答 迁移设计：

Claude原则	数据库迁移
Bash特殊检查	SQL危险命令前置deny（DELETE TABLE、TRUNCATE）
Deny→Mode→Allow→Ask	同样顺序架构
内容分析	Query内容分析
Plan=只读	Plan=SELECT only

困难点：

1. 存储过程边界：存储过程读写性质判断困难，需要元数据标注。
2. 数量级别预判：UPDATE 1 行 vs UPDATE 100万行，风险不同。

设计决策：

• 高敏感操作（DROP TABLE）硬编码 Deny
• 普通规则配置文件
• 存储过程需要元数据标注读写性质 :::

本章目标：让每个核心概念都从 L0 升级到 L2。理解 L07，不只是记住管道顺序，而是掌握”如何在循环上行动可靠可控”的设计原则。

权限管道流程#

三种模式对比#

Bash读写分类#

数据库Agent迁移#