AstroResearch/docs/architecture/agent/permission.md

# 权限系统 (Permission System)

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

---

## 整体架构

```mermaid
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           │
│                                                            │
│  通配符 "*" 匹配所有工具名                                   │
└────────────────────────────────────────────────────────────┘
```

### 多源权限优先级 (Multi-Source Permission Precedence)

当多个来源（Checker 规则、Hook、工具级规则、会话规则）同时做出权限决策时，
`resolve_permission_precedence()` 按以下优先级裁决：

| Priority | Source | Description |
|----------|--------|-------------|
| **P0** (highest) | `PermissionChecker::Deny` | 环境变量/配置文件配置的 Deny 规则，不可覆盖 |
| **P1** | Tool-level `PermissionRule::Deny` | 工具自身拒绝执行（如 Bash 危险命令） |
| **P2** | Session-level `PermissionChecker::Deny` | API 动态添加的会话级 Deny |
| **P3** | Hook `PreToolUseAction::Block` | Hook 主动阻止工具执行 |
| **P4** | Hook `PermissionRequired` | 仅当 Checker 返回 Allowed 时升级为 AskUser |
| **P5** | Session-level `PermissionChecker::Ask` | 仅当当前为 Allowed 时升级 |
| **P6** | Tool-level `PermissionRule::Ask` | 仅当当前为 Allowed 时升级 |
| **P7** | `PermissionChecker::Allow` | 显式 Allow 规则 |
| **P8** (lowest) | Implicit Allow (default) | 无任何规则匹配 → 允许 |

**关键规则：**
- **Deny 不可覆盖**: P0-P2 的 Deny 规则在任何情况下生效
- **Ask 可升级**: P4-P6 在 Allow 状态下升级为 Ask；在 Deny 状态下被忽略
- **Block = Deny**: Hook Block 等同于 Deny，由 P0-P2 可覆盖
- **冲突日志**: `conflict_log` 记录所有被覆盖的决策，用于审计```

### PermissionChecker API

```rust
// 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 },
}
```

### 使用示例

```rust
// 创建受限检查器：只允许只读操作
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());
```

### 当前集成状态

```mermaid
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 动作类型

```mermaid
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 动作类型

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

### Hook 链执行逻辑 (`run_pre_tool_use`)

```rust
// 遍历所有已注册 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

```mermaid
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`

### 允许的根目录

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

### 安全检查函数

```mermaid
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`

### 校验流程

```mermaid
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["✅ 执行"]
```

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

校验流程：

```mermaid
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` | ✅ 允许 | ⚠️ 通过校验，但触发 `Ask` 用户确认（不在白名单） |
| `vim file.txt` | ✅ 拒绝 | ✅ 拒绝（首词 `vim` 在黑名单） |
| `$(echo sud; echo o) /etc/passwd` | ✅ 允许（绕过！） | ❌ 拒绝（检测到命令替换绕过） |

### 安全白名单（已启用）

```rust
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",
];
```

白名单内的命令**优先放行**，不经过黑名单检查。非白名单命令经黑名单精确匹配和危险参数检查后，通过 `bash_needs_permission()` → `RunBashTool::check_permissions()` 返回 `Ask` 规则，触发用户确认弹窗（PermissionRequestCard）。

### 其他约束

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

### 已知局限

1. ~~**黑名单子串匹配**~~ — ✅ 已修复：改用首词精确匹配，`grep "ssh_config"` 不再误拦
2. ~~**未限制网络访问**~~ — ✅ 已修复：`NETWORK_COMMANDS` 名单（curl/wget/nc/socat 等）默认阻止，`AGENT_BLOCK_NETWORK=false` 可放行
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 模式

```rust
// 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 通道 → 子代理的工具调用进度不会单独推送到前端

### 子代理内部权限流程

```mermaid
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` 触发强制动作 |

### 用户取消的双重检查

```mermaid
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 → 输出修改
```

---

## 待完善项

| 优先级 | 项目 | 当前状态 | 建议 |
|---|---|---|---|
| **MEDIUM** | Auto Mode (AI 分类器) | 未实现 | LLM 评估风险，快速路径 + 安全工具白名单 |
| **LOW** | 文件写入大小限制 | 无上限 | 添加 `max_file_size` 参数 |