AstroResearch/docs/architecture/agent/permission.md

权限系统 (Permission System)

Agent 权限系统采用多层纵深防御架构，从工具级 trait 约束到运行时的 Hook 拦截、路径沙箱、命令黑名单，形成 7 层安全防线。

---

整体架构

graph TD
    subgraph L1["第一层：工具 Trait 约束"]
        IB["InterruptBehavior<br/>(Cancel vs Block)"]
        CS["is_concurrency_safe<br/>(并行安全声明)"]
        CP["check_permissions<br/>(自定义 PermissionRule)"]
        SA["causes_sibling_abort<br/>(兄弟中断)"]
    end

    subgraph L2["第二层：PermissionChecker 规则引擎"]
        Rules["有序规则链<br/>Deny → Allow → Ask → Default Allow"]
        WC["通配符 '*' 全匹配"]
    end

    subgraph L3["第三层：Hook 管道"]
        PreH["PreToolUse<br/>Continue | Block | MutateInput | PermissionRequired"]
        PostH["PostToolUse<br/>Continue | MutateOutput"]
        Builtins["3 内置 Hook<br/>Cancellation | Metrics | AuditLog"]
    end

    subgraph L4["第四层：文件系统沙箱"]
        PS["路径沙箱<br/>library_dir / skills_dir / cwd"]
        PT["穿越防护<br/>拒绝 .. 和 ~"]
    end

    subgraph L5["第五层：Bash 命令安全"]
        Blacklist["黑名单 21 条<br/>交互式/破坏性命令"]
        Timeout["超时控制 60s (max 120s)"]
        OutputLimit["输出截断 4000 字符"]
    end

    subgraph L6["第六层：子代理隔离"]
        SilentCtx["Silent 上下文<br/>禁止 ask_user"]
        FreshMsg["全新消息上下文<br/>不污染父代理"]
        InheritPerm["继承 PermissionChecker<br/>+ HookRegistry"]
    end

    subgraph L7["第七层：运行时安全约束"]
        MaxSteps["max_steps 上限"]
        DupDetect["同质调用检测"]
        TokenBudget["Token 预算 diminishing returns"]
        Cancel["用户取消 (cancelled_runs)"]
    end

    AgentRuntime["AgentRuntime::run_turn()"] --> L1
    L1 --> L2
    L2 --> L3
    L3 --> L4
    L4 --> L5
    L5 --> L6
    L6 --> L7

---

第一层：工具级 Trait 约束

每个工具通过覆写 AgentTool trait 的 4 个安全方法声明自身行为边界。

定义位置：src/agent/tools/mod.rs:179

方法说明

方法	默认值	作用
interrupt_behavior()	Cancel	用户取消时的响应：Cancel 立即停止（只读工具），Block 等待完成（有副作用的写入工具）
is_concurrency_safe(args)	false	是否可与其他工具并行执行。保守默认，只读工具须显式覆写为 true
check_permissions(args)	空 Vec	返回 PermissionRule 列表，由 PermissionChecker 运行时逐条匹配
causes_sibling_abort()	false	该工具失败时是否中止兄弟并行执行（下载/解析类工具可设为 true）

工具安全分类表

只读并发安全工具

工具	域	is_concurrency_safe	interrupt_behavior
search_papers	astro/search	true	Cancel
get_paper_metadata	astro/search	true	Cancel
get_paper_content	astro/paper	true	Cancel
rag_search	astro/rag	true	Cancel
query_target	astro/target	true	Cancel
read_file	filesystem	true	Cancel
grep_files	filesystem	true	Cancel
glob_files	filesystem	true	Cancel
load_skill	skill	true	Cancel

写入/IO 串行安全工具

工具	域	is_concurrency_safe	interrupt_behavior
download_paper	astro/paper	false	Cancel
parse_paper	astro/paper	false	Cancel
file_write	filesystem	false	Cancel
file_edit	filesystem	false	Cancel
save_note	astro/note	false	Cancel
save_memory	memory	false	Block
run_bash	filesystem	false	Block
ask_user	ask_user	false	Block
todo_write	todo	false	Cancel
compress_context	compress	false	Cancel
subagent	subagent	false	Block

设计原理：Block 工具在用户取消时忽略中断信号，确保写操作完整提交后才停止。save_memory 和 run_bash 涉及文件系统修改，ask_user 依赖 oneshot 通道生命周期，subagent 开启了完整的子代理 ReAct 循环，中断可能导致数据不一致。

---

第二层：PermissionChecker 规则引擎

参考 Claude Code 的 PermissionChecker 设计，提供可编程的权限规则链。

定义位置：src/agent/runtime/permission.rs

权限判定规则

┌────────────────────────────────────────────────────────────┐
│                    规则匹配优先级 (first-match-wins)         │
│                                                            │
│  1. Deny { tool_name, reason }    — 不可覆盖的拒绝           │
│  2. Allow { tool_name }           — 显式允许                 │
│  3. Ask { tool_name, message }    — 需要用户确认              │
│  4. (default)                     — 无匹配 → Allow           │
│                                                            │
│  通配符 "*" 匹配所有工具名                                   │
└────────────────────────────────────────────────────────────┘

PermissionChecker API

// src/agent/runtime/permission.rs

pub struct PermissionChecker {
    rules: Vec<PermissionRule>,  // 有序规则列表，先添加的优先级更高
}

impl PermissionChecker {
    pub fn new() -> Self;                         // 空检查器 = 默认允许所有
    pub fn add_rule(&mut self, rule: PermissionRule);  // 添加规则
    pub fn check(&self, tool_name: &str) -> PermissionResult;  // 检查单个工具
    pub fn is_denied(&self, tool_name: &str) -> bool;          // 快捷 deny 检查

    fn matches(pattern: &str, tool_name: &str) -> bool {
        pattern == "*" || pattern == tool_name  // 通配符或精确匹配
    }
}

pub enum PermissionResult {
    Denied { reason: String },
    Allowed,
    AskUser { message: String },
}

使用示例

// 创建受限检查器：只允许只读操作
let mut checker = PermissionChecker::new();
checker.add_rule(PermissionRule::Deny {
    tool_name: "run_bash".into(),
    reason: "此会话中禁止执行命令".into(),
});
checker.add_rule(PermissionRule::Deny {
    tool_name: "download_paper".into(),
    reason: "禁止下载".into(),
});
checker.add_rule(PermissionRule::Ask {
    tool_name: "file_write".into(),
    message: "是否允许写入文件？".into(),
});

// 默认 Allow — 其余工具正常执行
assert!(checker.check("search_papers").is_allowed());
assert!(checker.check("run_bash").is_denied());

当前集成状态

graph LR
    subgraph "AgentConfig::from_env_optional()"
        PC0["解析 AGENT_PERMISSIONS_* 环境变量<br/>构造 PermissionChecker::from_config()"]
    end

    subgraph "AgentRuntime::run_turn()"
        PC1["permission_checker: PermissionChecker<br/>(Deny → Ask → Allow 规则链 + 4种模式)"]
    end

    subgraph "SubAgentRunner"
        PC2["permission_checker: Arc&lt;PermissionChecker&gt;"]
        PC2 -->|"check(tool_name, Some(&args))"| SubExec["三态检查<br/>Deny→注入错误 | Ask→自动拒绝 | Allow→执行"]
    end

    subgraph "execute_parallel() Phase 2.5"
        PC3["permission_checker: Option&lt;&PermissionChecker&gt;"]
        PC3 -->|"check() + apply_mode() + 工具级叠加"| DenyCheck["━━ 三态处理 ━━<br/>Deny → 注入错误跳过执行<br/>AskUser → SSE PermissionRequest + oneshot 等待(120s超时)<br/>Allowed → 正常进入执行队列"]
    end

    PC0 -.->|"构建"| PC1
    PC1 -.->|"传递给"| PC2
    PC1 -.->|"传递给"| PC3

    style PC3 fill:#ccffcc,stroke:#00aa00

✅ 完整已实现：executor::execute_parallel() 在 Phase 2.5（PreToolUse hooks 之后、工具执行之前）执行完整的权限检查管道：

1. PermissionChecker::check(tool_name, tool_args) — 规则链匹配 + 内容级匹配
2. PermissionChecker::apply_mode() — 模式变换（Bypass/DontAsk/AcceptEdits）
3. Hook PermissionRequired 升级 — hook 请求的权限确认为 AskUser
4. 工具级 check_permissions() 叠加 — 工具自定义规则在 Allow 时升级为 Ask
5. 最终三态分流：Deny → 注入错误 / AskUser → oneshot 交互(120s 超时) / Allowed → 正常执行

---

第三层：Hook 管道

Hook 系统提供了可编程的事件拦截点，参考 Claude Code 的 PreToolUse/PostToolUse/Stop hooks 设计。

定义位置：src/agent/hooks.rs

PreToolUse 动作类型

graph TD
    PreToolUse["PreToolUse hook"]
    PreToolUse --> Continue["Continue<br/>正常执行"]
    PreToolUse --> Block["Block { reason }<br/>阻止执行，第一个 Block 短路整个链"]
    PreToolUse --> Mutate["MutateInput { updated_args, additional_context }<br/>修改参数 + 注入附加上下文"]
    PreToolUse --> PermReq["PermissionRequired { permission, tool_name }<br/>请求权限决策（Phase 2 待完善）"]

PostToolUse 动作类型

graph TD
    PostToolUse["PostToolUse hook"]
    PostToolUse --> Continue2["Continue<br/>保持输出不变"]
    PostToolUse --> MutateOut["MutateOutput { updated_content }<br/>修改工具输出（如脱敏）"]

Hook 链执行逻辑 (run_pre_tool_use)

// 遍历所有已注册 hook
for hook in &self.hooks {
    let action = hook.pre_tool_use(ctx).await;
    match action {
        Block { reason } => {
            // 第一个 Block 立即短路返回，不执行后续 hook
            return PreToolUseResult { action, ... };
        }
        MutateInput { updated_args, additional_context } => {
            // 累积 additional_context（多 hook 拼接）
            // 更新 final_args（最后一个 MutateInput 的修改生效）
        }
        PermissionRequired { .. } => {
            // 记录日志，但暂不阻塞（Phase 2 完善）
        }
        Continue => {} // 继续下一个 hook
    }
}

3 个内置 Hook

classDiagram
    class CancellationHook {
        -cancelled_runs: Arc~Mutex~HashSet~String~~
        +pre_tool_use() → Block | Continue
        +on_session_stop() → 清理取消状态
    }

    class MetricsHook {
        -data: Arc~Mutex~MetricsData~
        +on_session_start() → 关联 session_id
        +post_tool_use() → 累计工具调用/错误计数
        +on_step_complete() → 每 3 步输出摘要日志
        +on_session_stop() → 输出终止原因
        +snapshot() → 返回可查询的指标快照
    }

    class AuditLogHook {
        -db: SqlitePool
        +post_tool_use() → fire-and-forget 写入 agent_audit_log
        +on_session_stop() → 写入 SESSION_STOP 标记
    }

    class AgentHook {
        <<interface>>
        +name() &str
        +on_session_start()
        +pre_tool_use()
        +post_tool_use()
        +on_step_complete()
        +on_session_stop()
        +on_subagent_start()
        +on_subagent_stop()
        +on_pre_compact()
        +on_post_compact()
    }

    AgentHook <|-- CancellationHook
    AgentHook <|-- MetricsHook
    AgentHook <|-- AuditLogHook

审计日志 (agent_audit_log 表)

AuditLogHook 在每次工具执行后通过 fire-and-forget（tokio::spawn）写入审计记录：

字段	说明
session_id	会话 ID
step	ReAct 步数
tool_name	工具名称
status	"OK" 或 "FAIL"
elapsed_ms	执行耗时（毫秒）
output_preview	输出内容前 200 字符
agent_name	代理身份（"lead" 或子代理名）

会话终止时写入一条 tool_name = 'session'、status = 'SESSION_STOP' 的汇总记录。

---

第四层：文件系统路径沙箱

所有文件操作工具（read_file、file_write、file_edit、glob_files、grep_files、run_bash 的 working_dir 参数）共享的路径安全检查。

定义位置：src/agent/tools/filesystem/security.rs

允许的根目录

let allowed_roots = [
    config.library_dir.canonicalize(),   // 论文库目录
    config.skills_dir.canonicalize(),    // Agent Skills 目录
    std::env::current_dir(),             // 项目根目录
];

安全检查函数

flowchart TD
    Input["用户提供的路径字符串"] --> PT{"has_path_traversal()<br/>包含 .. 或 ~ ？"}
    PT -->|是| Reject1["❌ 拒绝"]
    PT -->|否| Resolve["resolve_path()<br/>绝对路径直接用，相对路径基于 cwd 拼接"]
    Resolve --> Canon["canonicalize()<br/>消除符号链接"]
    Canon -->|失败| TryParent["尝试对父目录 canonicalize"]
    TryParent -->|失败| Reject2["❌ 拒绝：无法解析"]
    Canon -->|成功| Check{"is_path_allowed()<br/>在 allowed_roots 内？"}
    TryParent -->|成功| Check
    Check -->|是| Allow["✅ 允许"]
    Check -->|否| Reject3["❌ 拒绝：无权访问"]

防护能力

攻击类型	防护方式
路径穿越 (../../../etc/passwd)	has_path_traversal() 拒绝含 .. 的路径
家目录访问 (~/)	has_path_traversal() 拒绝含 ~ 的路径
符号链接逃逸	canonicalize() 解析符号链接到真实路径后再检查
绝对路径越界	resolve_path() 解析后再 is_path_allowed()

覆盖的工具

工具	受保护的参数
read_file	file_path
file_write	file_path
file_edit	file_path
glob_files	pattern (解析后)
grep_files	path
run_bash	working_dir

---

第五层：Bash 命令安全校验

run_bash 工具在路径沙箱之上叠加了命令级安全校验。

定义位置：src/agent/tools/filesystem/bash.rs

校验流程

flowchart TD
    Cmd["command 参数"] --> Trim["trim() 去空格"]
    Trim --> Empty{"空命令 / bash / bash -c？"}
    Empty -->|是| Reject1["❌ 拒绝"]
    Empty -->|否| Lower["to_lowercase()"]
    Lower --> Blacklist{"黑名单子串匹配<br/>（21 条模式）"}
    Blacklist -->|命中| Reject2["❌ 拒绝：不允许执行 'X' 类命令"]
    Blacklist -->|未命中| Execute["✅ 执行"]

黑名单（精确首词匹配，已修复子串误伤问题）

校验流程：

flowchart TD
    Cmd["command 参数"] --> Trim["trim() 去空格"]
    Trim --> Empty{"空命令 / bash / bash -c？"}
    Empty -->|是| Reject1["❌ 拒绝"]
    Empty -->|否| Bypass{"命令替换绕过？<br/>$() 或反引号开头的首词"}
    Bypass -->|是| Reject2["❌ 拒绝"]
    Bypass -->|否| Extract["extract_first_command_word()<br/>提取首个命令单词"]
    Extract --> Whitelist{"SAFE_COMMANDS 白名单？<br/>（35 个安全命令）"}
    Whitelist -->|是| Allow["✅ 直接允许"]
    Whitelist -->|否| Blacklist{"DANGEROUS_COMMANDS 黑名单？<br/>（33 个精确匹配）"}
    Blacklist -->|是| Reject3["❌ 拒绝"]
    Blacklist -->|否| ArgCheck{"DANGEROUS_ARG_PATTERNS？<br/>（5 个危险参数子串）"}
    ArgCheck -->|命中| Reject4["❌ 拒绝"]
    ArgCheck -->|未命中| Allow2["✅ 默认允许<br/>（路径沙箱 + 超时兜底）"]

精确匹配 vs 子串匹配（修复前/后对比）：

命令	修复前（子串）	修复后（首词精确）
grep "ssh_config" *.rs	❌ 误拦（含子串 ssh ）	✅ 允许（首词 grep 在白名单）
echo "use sudo carefully"	❌ 误拦（含子串 sudo ）	✅ 允许（首词 echo 在白名单）
cat /usr/share/vim/vimrc	❌ 误拦（含子串 vim ）	✅ 允许（首词 cat 在白名单）
python script.py	✅ 允许	✅ 允许（不在黑名单，默认允许）
vim file.txt	✅ 拒绝	✅ 拒绝（首词 vim 在黑名单）
$(echo sud; echo o) /etc/passwd	✅ 允许（绕过！）	❌ 拒绝（检测到命令替换绕过）

安全白名单（已启用）

const SAFE_COMMANDS: &[&str] = &[
    "ls", "cat", "head", "tail", "find", "grep", "wc", "echo",
    "pwd", "sort", "uniq", "cut", "tr", "awk", "sed", "jq",
    "diff", "file", "stat", "du", "df", "env", "printenv",
    "which", "basename", "dirname", "realpath", "readlink",
    "xargs", "tee", "date", "sleep", "true", "false",
];

白名单内的命令优先放行，不经过黑名单检查。非白名单命令经过黑名单精确匹配和危险参数二次检查后默认允许。

其他约束

约束	值	说明
超时	默认 60s，最大 120s	AGENT_TOOL_TIMEOUT_SECS 环境变量
输出截断	4000 字符	truncate_content()
工作目录	library_dir / skills_dir / cwd	受路径沙箱约束

已知局限

1. 黑名单子串匹配 — ✅ 已修复：改用首词精确匹配，grep "ssh_config" 不再误拦
2. 未限制网络访问 — curl、wget 不在黑名单中
3. 未限制进程数 — fork bomb（如 :(){ :\|:& };:）未被检测
4. 管道/重定向完整放行 — <、>、| 不做限制
5. $() 命令替换 — ✅ 已修复：检测首词位置 $() 和反引号绕过
6. 白名单未被使用 — ✅ 已修复：SAFE_COMMANDS 已集成到 validate_bash_command() 中，白名单命令优先放行

---

第六层：子代理隔离

子代理通过 SubAgentRunner 创建上下文隔离的执行环境，参考 Claude Code Subagents 设计。

定义位置：src/agent/subagent.rs、src/agent/tools/subagent.rs

隔离维度对比

维度	父代理	子代理
消息上下文	完整历史 + 所有中间工具调用	全新 messages：仅 [system_prompt, user_prompt]
工具注册表	完整 ToolRegistry（19+ 工具）	完整 ToolRegistry（共享同一个引用）
工具上下文	ToolContext::new()	ToolContext::silent() — silent = true
Hook 管道	完整 HookRegistry	继承父代理的 HookRegistry
PermissionChecker	自己的实例	继承父代理的 PermissionChecker
上下文压缩	多层压缩（micro/auto/manual）	独立的自动压缩
死循环检测	DuplicateDetector per turn	独立的 (last_call, consecutive_count)

Silent 模式

// src/agent/tools/mod.rs:114
pub fn silent(app_state: Arc<AppState>) -> Self {
    ToolContext {
        app_state,
        session_id: String::new(),
        silent: true,           // ← 关键标志
        read_file_state: ...,
        sse_tx: None,           // ← 无 SSE 通道
        enable_thinking: false,
    }
}

Silent 模式效果：

• ask_user 工具检测到 ctx.silent == true 时直接返回错误
• 阻止子代理绕过父代理向终端用户提问
• 无 SSE 通道 → 子代理的工具调用进度不会单独推送到前端

子代理内部权限流程

sequenceDiagram
    participant SA as SubAgentRunner
    participant Hook as HookRegistry
    participant PC as PermissionChecker
    participant Tool as AgentTool

    SA->>Hook: PreToolUseContext { tool_name, args }
    Hook-->>SA: PreToolUseResult { action, final_args }

    alt action = Block
        SA-->>SA: 注入错误 tool_result，跳过执行
    else action = Continue / MutateInput
        SA->>PC: is_denied(tool_name)
        alt 被拒绝
            SA-->>SA: 注入错误 tool_result，跳过执行
        else 允许
            SA->>Tool: execute(final_args, silent_ctx)
            Tool-->>SA: ToolOutput
            SA->>Hook: PostToolUse hooks → 可能修改输出
        end
    end

⚠️ 当前局限：子代理使用完整的父代理 ToolRegistry，不支持按子任务需求裁剪工具列表（如"仅搜索"模式只给只读工具）。未来可引入 ToolRegistry::restrict() 方法实现最小权限原则。

---

第七层：运行时安全约束

ReAct 循环中的多层终止条件，防止无限循环和资源耗尽。

定义位置：src/agent/runtime/mod.rs:442

终止条件矩阵

条件	触发阈值	行为
最大步数	step > max_steps (默认 8)	强制 LLM 生成最终答案（不带工具调用），注入提醒消息
同质调用	连续 3 次相同 (tool_name, args)	注入错误 tool_result，跳过本轮该工具
Token diminishing returns	连续多步无新增信息	强制结束，注入"请基于已收集信息直接回答"
用户取消	cancelled_runs 含当前 session_id	循环开始和工具执行中双重检查，发送 Error SSE 事件
压缩熔断	CompactionCircuitBreaker 连续失败	跳过自动压缩，避免无限压缩循环
Token 硬限制	token_hard_limit (默认 40000)	TokenBudget 触发强制动作

用户取消的双重检查

sequenceDiagram
    participant User as 用户
    participant API as API 层
    participant State as cancelled_runs
    participant Loop as ReAct 循环
    participant Exec as 工具执行

    User->>API: POST /api/chat/cancel
    API->>State: insert(session_id)
    
    Note over Loop: 每步迭代开始
    Loop->>State: contains(session_id)?
    State-->>Loop: true → break 循环

    Note over Exec: 工具执行中 (每 250ms)
    loop 取消轮询
        Exec->>State: contains(session_id)?
        State-->>Exec: true → interrupt
    end
    
    Note over Exec: InterruptBehavior 判断
    alt interrupt_behavior = Cancel
        Exec-->>Exec: 立即停止，返回 "执行已被用户取消"
    else interrupt_behavior = Block
        Exec-->>Exec: 忽略中断信号，等待完成
    end

• 主循环在每步开始检查取消标志
• 工具执行器以 250ms 间隔轮询取消状态
• Block 工具（run_bash、save_memory、ask_user、subagent）忽略取消信号直到自然完成

取消状态生命周期

1. 用户通过 API 端点设置 cancelled_runs.insert(session_id)
2. CancellationHook::pre_tool_use() 检测到 → 返回 Block
3. ReAct 循环入口检测到 → break 跳出
4. 工具执行检测到 + InterruptBehavior::Cancel → 立即返回
5. CancellationHook::on_session_stop() → 清理 cancelled_runs.remove(session_id)

---

配套安全机制

Background Task 安全

位置：src/agent/tools/background.rs、src/agent/background.rs

• bg_task_run 用于在后台执行慢速操作（下载、解析）
• 后台任务通过 BgNotificationQueue 注入结果，不直接访问 Agent 上下文
• 结果注入在下一次 LLM 调用前以 user 消息形式推送

工具输出持久化

位置：src/agent/tools/persist.rs

• 大型工具结果（超过 max_tool_output_chars）写入磁盘，消息中只包含 stub
• 写入路径：{library_dir}/tool-results/{tool_call_id}.txt
• 通过调用外部工具读取完整结果，避免上下文污染

Token 预算管理

位置：src/agent/runtime/token_budget.rs

软限制 (token_soft_limit, 默认 32000)
  ↓ 触发渐进式 nudging 提醒 → 建议 LLM 总结/给出答案
  ↓
硬限制 (token_hard_limit, 默认 40000)
  ↓ 触发强制动作 → 上下文压缩或强制结束
  ↓
Diminishing Returns 检测
  ↓ 连续无新增信息 → 强制结束 + 直接回答

---

权限检查全链路

一次完整的工具调用穿越全部 7 层防线：

工具调用请求
  │
  ├─ [L7] 循环入口：步数 / 取消 / diminishing returns 检查
  │
  ├─ [L7] validate_and_prepare()：死循环检测 + 参数解析
  │
  ├─ [L3] PreToolUse hooks：
  │   ├── CancellationHook → 检查 cancelled_runs
  │   ├── 自定义 Hook → Block? MutateInput?
  │   └── 返回 final_args + additional_context
  │
  ├─ [L2] PermissionChecker.check() ← ✅ 在 Phase 2.5 调用（PreToolUse hooks 之后、执行之前）
  │   ├── Deny → 注入错误 result，跳过执行，不进入队列
  │   ├── AskUser → 暂视为允许（Phase 2 确认交互待完善）
  │   └── Allowed → 正常进入执行队列
  │
  ├─ [L1] 分区器 (ToolPartitioner)：
  │   └── is_concurrency_safe() 判断 → 并行 or 串行批次
  │
  ├─ 工具执行 (每工具独立 Future)：
  │   │
  │   ├─ [L1] InterruptBehavior 判断 → Cancel 可中断 / Block 不可中断
  │   │
  │   ├─ [L4] 路径沙箱 (read_file / file_write / file_edit / glob / grep / bash)
  │   │
  │   ├─ [L5] Bash 黑名单 (run_bash):
  │   │   ├── validate_bash_command() → 空命令 / 黑名单
  │   │   ├── 工作目录路径沙箱检查
  │   │   └── 超时控制 (60s default / 120s max)
  │   │
  │   ├─ [L6] ask_user Silent 模式检查 → 子代理中直接返回错误
  │   │
  │   └─ 超时控制 (AGENT_TOOL_TIMEOUT_SECS, default 120s)
  │
  └─ [L3] PostToolUse hooks：
      ├── 输出截断 + 大结果持久化
      ├── MetricsHook → 累计指标
      ├── AuditLogHook → fire-and-forget 审计日志
      └── MutateOutput → 输出修改

---

Claude Code 权限系统对比分析

对比基准：Claude Code (/home/fmq/program/claudecode/src/utils/permissions/) 分析日期：2026-06-17

架构差异总览

维度	AstroResearch (当前)	Claude Code (参考)	差距
规则引擎	✅ PermissionChecker (完成)	✅ hasPermissionsToUseTool 多步流水线	相当
规则匹配粒度	✅ 内容级 Tool(content*) 前缀/后缀/包含	✅ 前缀/通配/内容级 / 正则	小
AskUser 交互流	✅ SSE → PermissionRequestCard → Allow/Deny/Always Allow	✅ 完整 SSE → Dialog → 决策	相当
权限模式	✅ Default/AcceptEdits/Bypass/DontAsk	✅ 6种模式 (含 plan/auto)	小
规则持久化	✅ 环境变量加载 + PermissionChecker::from_config()	✅ settings.json 多层加载 (8级来源优先级)	小
规则来源追踪	✅ PermissionRuleSource 枚举 (Env/Session)	✅ cliArg > command > session > userSettings > ...	小
Bash 权限分类器	✅ SAFE_COMMANDS 白名单 + check_permissions() 集成	✅ AST解析 + AI分类器 + 异步推测	中等
拒绝追踪/熔断	✅ DenialTracker 连续/累计计数 + ReAct 循环熔断	✅ 连续/总计拒绝计数 + 自动终止	相当
权限 Hook 集成	✅ PreToolUseAction::PermissionRequired 完整流程	✅ 完整 PermissionRequest hook + 多路径决议	相当
规则遮蔽检测	✅ detect_shadowed_rules() deny/ask 双重检查	✅ shadowedRuleDetection deny/ask 遮蔽检测	相当
Auto Mode (AI 分类)	❌ 无	✅ YOLO classifier + 快速路径 + 安全工具白名单	远期
权限解释器	✅ 启发式 explain_permission() (Bash 风险等级 + 路径检测)	✅ Haiku 生成风险解释	中等
会话内规则更新	✅ POST/PUT /api/chat/sessions/:id/permissions/*	✅ /permissions 命令 + API	小
子代理权限继承	✅ 完整 check() 三态检查	✅ 完整继承父级权限上下文	相当
附加目录沙箱	✅ AGENT_ADDITIONAL_DIRS + is_path_allowed() 扩展	✅ additionalDirectories 可配置	相当

Claude Code 权限流水线 (参考架构)

hasPermissionsToUseTool(toolName, input, context):
  Step 1a: 工具级 deny 规则检查     → deny  → 返回 deny
  Step 1b: 工具级 ask 规则检查      → ask   → 返回 ask (sandbox 例外)
  Step 1c: 工具自定义 checkPermissions() → 内容级规则匹配
  Step 1d: 工具实现返回 deny        → deny  → 返回 deny
  Step 1e: requiresUserInteraction?  → ask   → 强制 ask (bypass 免疫)
  Step 1f: 内容级 ask 规则          → ask   → 强制 ask (bypass 免疫)
  Step 1g: 安全检查 (敏感路径等)    → ask   → 强制 ask (bypass 免疫)
  Step 2a: bypassPermissions 模式?  → allow → 返回 allow
  Step 2b: 工具级 allow 规则        → allow → 返回 allow
  Step 3:  剩余 passthrough         → ask   → 返回 ask

外层模式变换:
  dontAsk 模式: ask → deny
  auto 模式:    acceptEdits 快速路径 → 安全工具白名单 → AI分类器
  headless:     hooks 先运行 → 无 hook 决定 → auto-deny

关键设计决策对比

1. 规则格式

Claude Code 使用 ToolName(content) 格式支持内容级规则：

Bash                    → 匹配所有 bash 命令
Bash(npm install)       → 匹配精确命令
Bash(npm *)             → 前缀通配
Bash(rm:*)              → 旧版前缀（已废弃）
Read(.env)              → 文件模式
mcp__server__tool       → MCP 工具级
mcp__server             → MCP 服务级
Agent(Explore)          → 代理类型级

AstroResearch 已实现相同格式：

"*"                     → 通配所有工具
"tool_name"             → 精确工具名匹配
"tool_name(content*)"   → 前缀通配（如 "run_bash(rm *)" 匹配 "rm -rf /"）
"tool_name(*suffix)"    → 后缀通配（如 "read_file(*.env)" 匹配 ".env"）
"tool_name(exact)"      → 包含匹配（子串命中）
"*(content)"            → 工具通配 + 内容匹配（如 "*(sudo)" 匹配任意工具的 sudo 命令）

从 args 中自动提取 command/file_path/path/pattern/url 字段进行内容匹配。

2. 权限模式

Claude Code 的 6 种模式通过 Shift+Tab 循环切换：

• default — 标准逐项确认
• acceptEdits — 工作目录内文件编辑自动通过
• bypassPermissions — 跳过所有 Ask（deny/ask 规则仍生效；安全检查 bypass 免疫）
• dontAsk — 所有 Ask 转 Deny
• plan — 计划模式
• auto — AI 自动分类（内部使用）

AstroResearch 已实现 4 种模式（通过 AGENT_PERMISSION_MODE 环境变量或 API 切换）：

• default — 标准规则链，Ask 触发用户交互
• acceptEdits — 工作目录内文件编辑自动通过（路径检查由 executor 完成）
• bypassPermissions — 跳过所有 Ask（Deny 规则仍生效）
• dontAsk — 所有 Ask 转为 Deny

PermissionChecker::from_config() 从 AgentConfig 加载环境变量规则并构造完整检查器。

3. 多路径权限决议

Claude Code 的 AskUser 决议支持多个并行路径，任一先返回即生效（claim() 模式）：

• 本地 UI 对话框
• Bridge 响应（CCR 远程）
• Channel 响应（Telegram 等）
• PermissionRequest hooks（后台异步运行）
• Bash 分类器（后台推测性异步分类）

AstroResearch 已实现完整的 AskUser 交互流：

• PermissionChecker::check() 返回 AskUser 时，executor 发送 AgentStreamEvent::PermissionRequest SSE 事件
• 通过 oneshot 通道创建 PendingPermission，存入 AppState::pending_permissions
• 等待用户通过前端 PermissionRequestCard 组件响应（Allow / Deny / Always Allow），120s 超时自动拒绝
• 单一路径决议（oneshot），不支持多路径 claim 模式

---

优化路线图

✅ P0 — 已全部完成

P0-1: 规则加载与持久化 ✅

AgentConfig::from_env_optional() 从环境变量加载规则（AGENT_PERMISSIONS_DENY/ALLOW/ASK），PermissionChecker::from_config() 按 Deny → Ask → Allow 优先级顺序构造规则链。

实现位置: src/agent/runtime/mod.rs:113-117, src/agent/runtime/permission.rs:268-290

P0-2: 完成 AskUser 权限交互流 ✅

executor Phase 2.5 中完整的 AskUser 处理：

• AgentStreamEvent::PermissionRequest SSE 事件 → 前端 PermissionRequestCard 组件
• oneshot 通道 + AppState::pending_permissions 存储
• 120s 超时自动拒绝，支持 Allow / Deny / Always Allow 决策

实现位置: src/agent/runtime/executor.rs:282-422, src/api/agent.rs, dashboard/src/features/agent/PermissionRequestCard.tsx

P0-3: 内容级权限匹配 ✅

PermissionChecker::matches() 支持 "tool_name(content_pattern)" 格式，前缀通配（prefix*）、后缀通配（*suffix）、包含匹配，自动从 args 提取 command/file_path/path/pattern/url 字段。

实现位置: src/agent/runtime/permission.rs:183-255

✅ P1 — 已全部完成

P1-1: 权限模式系统 ✅

PermissionMode 枚举实现 4 种模式（Default/AcceptEdits/Bypass/DontAsk），通过 AGENT_PERMISSION_MODE 环境变量或 API 切换。PermissionChecker::apply_mode() 在 executor Phase 2.5 中对检查结果进行模式变换（Bypass 将 Ask→Allowed，DontAsk 将 Ask→Denied）。

实现位置: src/agent/runtime/permission.rs:39-60, 139-177

P1-2: Bash 权限接入 PermissionChecker ✅

RunBashTool::check_permissions() 调用 bash_needs_permission() —— 安全白名单中的命令返回空规则（自动允许），非白名单命令返回 Ask 规则。executor Phase 2.5 中与 PermissionChecker 结果叠加。

实现位置: src/agent/tools/filesystem/bash.rs:58-73, 362-365

P1-3: 权限 Hook 集成 ✅

PreToolUseAction::PermissionRequired 在 executor 中被检测：若 hook 返回 PermissionRequired 且 PermissionChecker 返回 Allowed，则升级为 AskUser 触发用户交互。已修复 Continue 覆盖 meaningful action 的 bug。

实现位置: src/agent/hooks.rs:378-384, src/agent/runtime/executor.rs:221-230

P1-4: 子代理完整权限继承 ✅

SubAgentRunner 使用 check(tool_name, Some(&final_args)) 进行三态检查：Deny → 注入错误跳过执行，AskUser → 自动拒绝（子代理不应打断用户），Allowed → 正常执行。

实现位置: src/agent/subagent.rs

✅ P2-1、P2-2 — 已实现

P2-1: 拒绝追踪与熔断 ✅

DenialTracker 追踪连续拒绝和总拒绝数，阈值触发 ReAct 循环终止。 配置：AGENT_DENIAL_MAX_CONSECUTIVE (默认 3) / AGENT_DENIAL_MAX_TOTAL (默认 20)。

实现位置: src/agent/runtime/denial_tracker.rs, src/agent/runtime/mod.rs

P2-2: 会话内规则更新 API ✅

POST /api/chat/sessions/:id/permissions/rules — add/remove 规则 PUT /api/chat/sessions/:id/permissions/mode — 切换权限模式 通过 AppState::session_permission_checker (Arc<RwLock<PermissionChecker>>) 实现跨 turn 共享。

实现位置: src/api/permissions.rs, src/agent/runtime/executor.rs Phase 2.5

🟡 P2-3~P2-5 — 远期增强（按需实现）

P2-3: 规则遮蔽检测 ✅

PermissionChecker::detect_shadowed_rules() 检测 Deny/Ask 遮蔽 Allow 的情况，输出 ShadowedRule 列表（含 reason + fix 建议），在 AgentRuntime 初始化时通过 warn! 日志输出。

实现位置: src/agent/runtime/permission.rs

P2-4: 权限解释器 ✅

启发式 explain_permission() 函数，根据工具名和参数生成 {risk_level, explanation, reasoning, risk} 结构。Bash 命令通过关键词检测风险等级（HIGH/MEDIUM/LOW），文件操作检测系统路径。结果随 PermissionRequest SSE 事件推送到前端。

实现位置: src/agent/runtime/permission_explainer.rs, src/agent/runtime/mod.rs AgentStreamEvent::PermissionRequest.explanation

P2-5: Auto Mode (AI 权限分类器) ❌

使用 LLM 自动评估工具调用的风险：

• 快速路径：AcceptEdits 模式自动允许工作目录内的文件编辑
• 安全工具白名单：read_file、grep_files、search_papers 等只读操作自动允许
• AI 分类：对不确定的操作调用快速模型判断安全性
• 失败封闭：分类器不可用时拒绝所有非白名单操作（安全优先）

工作量: 3-5天

P2-4: 权限解释器

在执行前用 LLM 生成人类可读的风险描述：

"该命令将执行 npm install，可能修改 node_modules/ 目录并下载外部依赖包。"

工作量: 1天

P2-5: 子代理最小权限 (ToolRegistry::restrict)

impl ToolRegistry {
    pub fn restrict(&self, allowed_tools: &[&str]) -> Self {
        // 创建仅包含指定工具的受限注册表
    }
}

工作量: 0.5天

---

实现路线图

已完成 (Phase 1): P0-1 规则加载 + P0-2 AskUser 交互流 + P0-3 内容级匹配
已完成 (Phase 2): P1-1 权限模式 + P1-2 Bash 集成 + P1-3 Hook 集成 + P1-4 子代理继承
已完成 (Phase 3): P2-1 拒绝追踪熔断 + P2-2 会话内规则更新 + P2-3 规则遮蔽检测 + P2-4 权限解释器 + 附加目录沙箱 + 规则来源追踪
远期规划 (按需):   P2-5 Auto Mode (AI 分类器) + P2-6 权限解释器 LLM 升级 + 子代理最小权限 + 文件写入大小限制

---

待完善项

优先级	项目	当前状态	建议
HIGH	PermissionChecker 集成到主执行路径	✅ 已完成	—
HIGH	Bash 黑名单改为命令解析	✅ 已完成	—
P0	规则加载与持久化	✅ 已完成：AgentConfig 新增 permission_deny_rules / permission_allow_rules / permission_ask_rules / permission_mode 字段，通过 AGENT_PERMISSIONS_* 环境变量加载	—
P0	AskUser 权限交互流	✅ 已完成：executor Phase 2.5 AskUser 分支重写为完整 oneshot → SSE → 120s 超时流程。前端 PermissionRequestCard 组件提供 Allow / Deny / Always Allow	—
P0	内容级权限匹配	✅ 已完成：check(tool_name, tool_args) 签名，matches() 支持 "tool(content*)" 格式（前缀/后缀/包含），自动提取 args 字段	—
P1	权限模式系统	✅ 已完成：PermissionMode (Default/AcceptEdits/Bypass/DontAsk)，apply_mode() 方法，AGENT_PERMISSION_MODE 配置	—
P1	Bash 权限集成	✅ 已完成：RunBashTool::check_permissions() 调用 bash_needs_permission()（安全命令自动允许），executor 合并工具级检查	—
P1	权限 Hook 集成	✅ 已完成：PreToolUseResult::is_permission_required()，修复 Continue 覆盖 bug，executor 触发 AskUser	—
P1	子代理完整权限继承	✅ 已完成：is_denied() → check(tool_name, Some(&final_args))，子代理中 AskUser 自动拒绝	—
MEDIUM	拒绝追踪与熔断	✅ 已完成	DenialTracker：连续/总计拒绝计数，阈值触发 ReAct 循环终止
MEDIUM	会话内规则更新 API	✅ 已完成	POST/PUT /api/chat/sessions/:id/permissions/* 动态 add/remove/mode
MEDIUM	权限解释器	✅ 已完成	启发式 explain_permission()，Bash 风险等级 + 路径检测，随 SSE PermissionRequest 推送前端
MEDIUM	Auto Mode (AI 分类器)	未实现	LLM 评估风险，快速路径 + 安全工具白名单
LOW	子代理最小权限	继承全部父工具	ToolRegistry::restrict()
LOW	文件写入大小限制	无上限	添加 max_file_size 参数
LOW	网络访问控制	curl/wget 未限制	Bash 黑名单扩展
LOW	用户权限 profiles	不支持	YAML/TOML 权限配置