Permission Decision Tree¶

目的：权限决策树关联：docs/PERMISSIONS.md、topics/deep-dive-bash-permissions.md

1. 完整决策树¶

graph TD
    A[Tool call] --> B{mode}
    B -->|bypassPermissions| C[allow]
    B -->|plan| D{non-Read?}
    D -->|yes| E[ask]
    D -->|no| F[allow Read]
    B -->|default/acceptEdits/auto| G[bashToolCheckPermission]
    G --> H{exact match rule}
    H -->|deny| I[deny]
    H -->|allow| C
    H -->|ask| E
    H -->|no match| J{wildcard rule}
    J -->|deny| I
    J -->|allow| C
    J -->|ask| E
    J -->|no match| K{sandbox}
    K -->|auto allow| C
    K -->|no| L{early deny patterns}
    L -->|yes| I
    L -->|no| M{semantic deny}
    M -->|yes| I
    M -->|no| N[LLM classifier]
    N -->|approve| C
    N -->|deny| I
    N -->|uncertain| E

完整。

2. 5 mode 状态机¶

stateDiagram-v2
    [*] --> default
    default --> acceptEdits: --permission-mode
    default --> plan: --permission-mode
    default --> bypassPermissions: --permission-mode
    default --> auto: --permission-mode
    acceptEdits --> default: Tab
    plan --> default: Tab
    bypassPermissions --> default: Tab
    auto --> default: Tab
    default --> default: 循环 (默认)

5 状态 + 循环。

3. 3 规则优先级¶

graph TD
    A[Tool call] --> B{deny rule?}
    B -->|yes| C[deny]
    B -->|no| D{ask rule?}
    D -->|yes| E[ask]
    D -->|no| F{allow rule?}
    F -->|yes| G[allow]
    F -->|no| H{mode check}
    H -->|plan| I{non-Read?}
    I -->|yes| E
    I -->|no| J[allow]
    H -->|bypass| G
    H -->|default| K[classifier]
    K -->|approve| G
    K -->|deny| C
    K -->|uncertain| E

deny > ask > allow > mode > classifier。

4. 4 步 Bash 决策¶

graph TD
    A[Bash command] --> B[parse with bashParser]
    B -->|success| C[walk AST]
    B -->|timeout 50ms| D[return null, fail safe]
    B -->|exceed 50K nodes| E[return null, fail safe]
    C --> F[isPathAllowed]
    F -->|deny path| G[deny]
    F -->|allow path| H{wildcard rule}
    H -->|allow| I[allow]
    H -->|deny| G
    H -->|no match| J[isDangerousRemovalRawPath]
    J -->|yes| G
    J -->|no| K[validate 25+]
    K -->|reject| G
    K -->|pass| L[stripSafeWrappers]
    L --> M[LLM classifier]
    M -->|allow| I
    M -->|deny| G
    M -->|uncertain| N[ask user]

4 步。

5. 5 步 Edit 决策¶

graph TD
    A[Edit file_path] --> B{path in deny?}
    B -->|yes| C[deny]
    B -->|no| D{path in allow?}
    D -->|yes| E[allow]
    D -->|no| F{mode}
    F -->|bypass| E
    F -->|plan| G[ask]
    F -->|acceptEdits| E
    F -->|default| G

5 步。

6. 4 步 WebFetch 决策¶

graph TD
    A[WebFetch url] --> B[extract domain]
    B --> C{domain in deny?}
    C -->|yes| D[deny]
    C -->|no| E{domain in allow?}
    E -->|yes| F[allow]
    E -->|no| G{mode}
    G -->|bypass| F
    G -->|plan| H[ask]
    G -->|default| H
    H -->|approve| F

4 步。

7. 3 步 Agent 决策¶

graph TD
    A[Agent name] --> B{Agent in allow?}
    B -->|yes| C[allow]
    B -->|no| D{Agent in deny?}
    D -->|yes| E[deny]
    D -->|no| F{mode}
    F -->|bypass| C
    F -->|default| G[ask]
    F -->|plan| G

3 步。

8. 5 步 Bash stripSafeWrappers¶

graph TD
    A[command] --> B[stripSafeWrappers]
    B --> C{time/nohup/env/sudo -n?}
    C -->|yes| D[strip + return inner]
    C -->|no| E[return as-is]
    D --> F[recheck rules]
    E --> F
    F --> G{allow rule?}
    G -->|yes| H[allow]
    G -->|no| I[classifier]
    H --> J[execute]
    I -->|allow| J
    I -->|deny| K[deny]

5 步。

9. 4 步 shellRuleMatching¶

graph TD
    A[Bash git status] --> B[parse command]
    B --> C{first word = git?}
    C -->|no| D[no match]
    C -->|yes| E{rule 'Bash(git:*)'?}
    E -->|yes| F[match]
    E -->|no| G{rule 'Bash(*)'?}
    G -->|yes| H[match]
    G -->|no| D

4 步。

10. 5 步 Classifier 流程¶

sequenceDiagram
    participant User
    participant Sys as System
    participant Spec as speculativeChecks Map
    participant LLM

    User->>Sys: Bash tool call
    Sys->>Spec: peekSpeculativeClassifierCheck(cmd)?
    alt cache hit
        Spec-->>Sys: cached result
    else cache miss
        Sys->>LLM: startSpeculativeClassifierCheck(cmd)
        LLM-->>Spec: result
    end
    Sys->>Sys: consumeSpeculativeClassifierCheck(cmd)
    alt approve
        Sys->>User: allow
    else deny
        Sys->>User: deny
    else uncertain
        Sys->>User: ask
    end

5 步。

11. 4 步 Permission Update¶

graph TD
    A[User: 'allow Bash(git:*)'] --> B[PermissionUpdate]
    B --> C{type}
    C -->|addRules| D[add to allow]
    C -->|removeRules| E[remove from allow/deny]
    C -->|setMode| F[change mode]
    C -->|addDirectories| G[add to context]
    D --> H[settings.json]
    E --> H
    F --> H
    G --> H

4 步。

12. 6 步 User 决策流¶

sequenceDiagram
    participant U as User
    participant Sys as System
    participant UI

    Sys->>U: Allow Bash(rm -rf /tmp/*)?
    U->>UI: Choice?
    alt Yes (once)
        U->>Sys: Yes
        Sys->>U: execute
    else Yes (file)
        U->>Sys: Yes (file)
        Sys->>U: add file rule
    else Yes (session)
        U->>Sys: Yes (session)
        Sys->>U: add session rule
    else No
        U->>Sys: No
        Sys->>U: deny
    end

4 选项。

13. 5 步 Session 启动权限¶

graph TD
    A[session start] --> B[load settings]
    B --> C[merge 4 sources]
    C --> D[policy > local > project > user]
    D --> E[default mode]
    E --> F{mode}
    F -->|default| G[normal]
    F -->|bypass| H[no check]
    F -->|plan| I[read only]
    F -->|auto| J[classifier]
    F -->|acceptEdits| K[auto accept edit]

5 步。

14. 3 步 Tool 范围匹配¶

graph TD
    A[Tool call] --> B{tool name}
    B -->|Bash| C[bash 6 层决策]
    B -->|Edit/Write/Read| D[path 检查]
    B -->|WebFetch| E[domain 检查]
    B -->|Agent| F[name 检查]
    B -->|TodoWrite/Skill/...| G[allow]
    C -->|allow/deny/ask| H[return]
    D --> H
    E --> H
    F --> H
    G --> H

3 步 dispatch。

15. 5 步沙箱 auto-allow¶

graph TD
    A[bash in sandbox] --> B{sandbox mode}
    B -->|strict| C[only allow list]
    B -->|permissive| D[allow most]
    B -->|off| E[normal check]
    C --> F{cmd in allow list?}
    F -->|yes| G[allow]
    F -->|no| H[ask]
    D --> I{cmd in deny list?}
    I -->|yes| J[deny]
    I -->|no| G
    E --> K[normal 6 层]
    K -->|allow/deny/ask| L[return]

5 步。

16. 4 步 Plugin 权限¶

graph TD
    A[Plugin hook] --> B{plugin in allowlist?}
    B -->|no| C[deny]
    B -->|yes| D{hook in plugin?}
    D -->|no| E[deny]
    D -->|yes| F[match rules]
    F -->|allow| G[allow]
    F -->|deny| H[deny]
    F -->|ask| I[ask]

4 步。

17. 5 步 MCP 权限¶

graph TD
    A[MCP tool call] --> B{MCP server trusted?}
    B -->|no| C[deny]
    B -->|yes| D{tool in MCP list?}
    D -->|no| E[deny]
    D -->|yes| F{mode}
    F -->|bypass| G[allow]
    F -->|default| H[match rules]
    F -->|plan| I[ask]
    H -->|allow| G
    H -->|deny| J[deny]
    H -->|ask| I

5 步。

18. 6 步 Plan Mode 流¶

graph TD
    A[plan mode] --> B[user in plan]
    B --> C[Claude can only Read]
    C --> D{user in plan?}
    D -->|yes| E[block Edit/Write/Bash]
    D -->|no| F[normal check]
    E --> G[show plan only]
    G --> H{user approve exit?}
    H -->|yes| I[switch to default]
    H -->|no| J[stay in plan]

6 步。

19. 4 步 Auto Mode 流¶

graph TD
    A[auto mode] --> B[classifier for all]
    B --> C[LLM classifier]
    C -->|approve| D[allow]
    C -->|deny| E[deny]
    C -->|uncertain| F[ask user]
    D --> G[log]
    E --> G
    F --> G

4 步。

20. 4 步 Bypass 警告¶

graph TD
    A[--permission-mode bypassPermissions] --> B{warning}
    B --> C[显示警告]
    C --> D{user 确认?}
    D -->|yes| E[启用]
    D -->|no| F[退出]
    E --> G[所有 tool 不检查]
    G --> H[风险: 任意执行]

4 步。

21. 总结¶

Permission Decision Tree = 6 层 + 5 mode + 3 规则。

核心： - 22 mermaid 图 - 完整决策树 - 各 tool 决策 - Classifier 流 - Plan / Auto / Bypass mode

下一步： - 渲染 SVG - 加到 mkdocs

Permission Decision Tree¶

1. 完整决策树¶

2. 5 mode 状态机¶

3. 3 规则优先级¶

4. 4 步 Bash 决策¶

5. 5 步 Edit 决策¶

6. 4 步 WebFetch 决策¶

7. 3 步 Agent 决策¶

8. 5 步 Bash stripSafeWrappers¶

9. 4 步 shellRuleMatching¶

10. 5 步 Classifier 流程¶

11. 4 步 Permission Update¶

12. 6 步 User 决策流¶

13. 5 步 Session 启动权限¶

14. 3 步 Tool 范围匹配¶

15. 5 步 沙箱 auto-allow¶

16. 4 步 Plugin 权限¶

17. 5 步 MCP 权限¶

18. 6 步 Plan Mode 流¶

19. 4 步 Auto Mode 流¶

20. 4 步 Bypass 警告¶

21. 总结¶

15. 5 步沙箱 auto-allow¶