同步 recursive 上下文工具与接口文档

更新模式、架构、工具和 Trace API 文档，说明 root_task_anchor 创建参数、read_context_ref 权限及上下文观测字段。

同步前端 API 示例和旧参数迁移提示，使公开接口描述与 Recursive revision 2 的实际实现保持一致。

cyber_agent/docs/agent-modes.md

@@ -38,7 +38,7 @@
 
 本地子孙继承该持久化策略；续跑、回溯或服务环境变更不会改变已有任务树的模式。没有模式字段的历史 Trace 按 `legacy` 续跑并补写模式。
 
-Recursive revision 2 的新根 Trace 必须同时具备根完成标准和预算快照。缺少这些必需数据的早期实验 Trace 不会自动升级，续跑时会要求重新创建任务。
+Recursive revision 2 的新根 Trace 必须同时具备 `RootTaskAnchor`、其内容哈希和预算快照。缺少这些必需数据的早期实验 Trace 不会自动升级，续跑时会要求重新创建任务。
 
 **实现**：`cyber_agent/core/runner.py:AgentRunner._prepare_new_trace`，`cyber_agent/core/runner.py:AgentRunner._prepare_existing_trace`
 
@@ -93,7 +93,7 @@ Recursive 子级的基础能力是下列集合的交集：
 ∩ 当前深度允许工具
 ```
 
-`evaluate` 和 `bash_command` 不会授予 Recursive 子级；`agent` 只能在父级实际拥有且子级未到 depth 5 时继承。协议工具还会按 `pending_review`、已批准下一任务、是否根 Trace 等当前状态动态收紧。
+`evaluate` 和 `bash_command` 不会授予 Recursive 子级；`agent` 只能在父级实际拥有且子级未到 depth 5 时继承。`read_context_ref` 同样只能逐层继承，depth 5 可以继续读取已授权引用。协议工具还会按 `pending_review`、已批准下一任务、是否根 Trace 等当前状态动态收紧。
 
 权限同时作用于模型可见 Schema 和 `ToolRegistry.execute()` 的运行时 dispatch；即使伪造未暴露的 Tool Call，也会在参数注入和函数调用前被拒绝。内部权限快照由 Runner 注入，自定义 context 不能覆盖。
 
@@ -140,11 +140,13 @@ Recursive 在当前 Python 进程内登记活跃和排队的父子 Trace。停
 Recursive 孩子只获得当前任务必需的明确输入：
 
 - 规范化 TaskBrief 及从父 TaskBrief 继承的硬约束。
+- 从根 Trace 读取的不可变 RootTaskAnchor。
+- 当前 Trace 本地已授权的最多 8 个 ContextRef 快照；深层获取祖先结论必须逐边转授。
 - `parent_trace_id` / `root_trace_id` / `agent_depth` 等 Trace 血缘。
 - 冻结的工具能力快照和调度策略。
 - 任务协议状态和预算所属根 Trace。
 
-不自动继承父 Agent 的完整消息历史、未筛选 Tool Result、父 Runner 的全部 `config.context`、内部运行对象或祖先 GoalTree。TaskBrief 的规范化、大小限制和 Validator 输入裁剪见 [Context 管理](./context-management.md#recursive-委托的-context-边界)。
+不自动继承父 Agent 的完整消息历史、未筛选 Tool Result、父 Runner 的全部 `config.context`、内部运行对象或祖先 GoalTree。`parent_findings`、普通 `context` 和 ContextRef 也不会自动累积；引用需逐层重新下发。完整规则见 [Context 管理](./context-management.md#recursive-委托的-context-边界)。
 
 **实现**：`cyber_agent/core/context_policy.py:normalize_task_brief`，`cyber_agent/core/context_policy.py:task_briefs_match`，`cyber_agent/core/runner.py:AgentRunner._build_tool_context`
 
@@ -202,6 +204,8 @@ Recursive 新根 Trace 会从环境变量读取一次预算，并把不可变快
 | `tests/test_recursive_replan_context.py` | 上下文继承、任务匹配和逐级回退 |
 | `tests/test_recursive_validation_core.py` | Validator 输入、独立性和结果校验 |
 | `tests/test_recursive_runtime_extensions.py` | 根门禁、预算包装和停止后协议行为 |
+| `tests/test_recursive_context_policy.py` | 根锚点、TaskBrief 版本、引用授权与限额 |
+| `tests/test_recursive_context_integration.py` | 五层上下文漂移、真实读取、工具权限与逐层验收 |
 
 ---
 

cyber_agent/docs/architecture.md

@@ -697,7 +697,7 @@ async def agent(
 
 **Recursive revision 2**：
 
-- 使用 `TaskBrief → TaskReport → ValidationResult → TaskReview` 的逐层任务协议，根结果也必须通过独立 Validator。
+- 使用 `RootTaskAnchor + TaskBrief → TaskReport → ValidationResult → TaskReview` 的逐层任务协议；已审核协议内容可通过 ContextRef 逐边授权、按需读取，根结果也必须通过独立 Validator。
 
 ### evaluate 工具
 

cyber_agent/docs/tools.md

@@ -1006,6 +1006,14 @@ review_task_result(
 )
 ```
 
+当前 Trace 拥有框架授权的 ContextRef 时，Recursive 业务 Agent 还可按精确版本读取：
+
+```python
+read_context_ref(ref_id: str, version: str)
+```
+
+该工具只查询当前 Trace 本地的不可变授权目录，不接受 Trace ID，不遍历父级或兄弟。它可在 `pending_review` 阶段使用，depth 5 也可继承；父级没有该工具时，后代不会重新获得。Legacy、Validator 和 `remote_*` 不暴露该工具。
+
 待审核期间不能创建孩子或修改 Goal；审核批准的新建或修订任务
 必须用同一份 TaskBrief 执行。字段、决策矩阵、Validator、根完成门禁
 与回溯恢复详见 [Recursive 任务协议](./recursive-task-protocol.md)。

cyber_agent/docs/trace-api.md

@@ -74,8 +74,9 @@ Recursive 的关键 `context` 字段：
 | `agent_mode` / `agent_mode_revision` | 创建时固化的 `recursive` 模式及协议版本 |
 | `root_trace_id` / `agent_depth` | 根 Trace ID 和业务 Agent 深度（根为 0） |
 | `created_by_tool` | `agent` 表示业务子 Agent，`validator` 表示独立验收 Trace |
-| `root_completion_criteria` | Recursive 根任务的完成标准 |
+| `root_task_anchor` / `root_task_anchor_hash` | Recursive 根任务的不可变目标、完成标准、硬约束及内容哈希 |
 | `task_protocol` | TaskBrief、报告、审核、待审核项和下一步动作等权威协议状态 |
+| `context_access` | 当前 Trace 本地被授权的不可变协议引用及静态字符用量 |
 | `resource_budget` | 根 Trace 固化的树级资源预算快照；动态用量单独保存 |
 
 旧 Trace 缺少 `agent_mode` 时按 Legacy 处理。详细语义见 [Agent 运行模式](./agent-modes.md) 和 [Recursive 任务协议](./recursive-task-protocol.md)。
@@ -261,11 +262,15 @@ Content-Type: application/json
   "name": "任务名称",
   "uid": "user_id",
   "project_name": null,
-  "root_completion_criteria": ["根任务的完成标准"]
+  "root_task_anchor": {
+    "objective": "分析项目架构",
+    "completion_criteria": ["列出模块与核心调用链"],
+    "constraints": ["结论必须来自实际代码"]
+  }
 }
 ```
 
-`root_completion_criteria` 在 Recursive 模式下必填且至少一项，Legacy 模式忽略该字段。
+`root_task_anchor` 在 Recursive 模式下必填，`objective` 和至少一项 `completion_criteria` 不能为空；Legacy 模式忽略该字段。旧字段 `root_completion_criteria` 会明确报错，不静默兼容。
 
 #### 5. 运行（统一续跑 + 回溯）
 

frontend/API.md

@@ -77,11 +77,15 @@ Content-Type: application/json
   "name": "任务名称",
   "uid": "user_id",
   "project_name": null,
-  "root_completion_criteria": ["产出物通过验收"]
+  "root_task_anchor": {
+    "objective": "完成任务",
+    "completion_criteria": ["产出物通过验收"],
+    "constraints": []
+  }
 }
 ```
 
-`root_completion_criteria` 在 Recursive 模式下必填且至少一项；Legacy 忽略该字段。该端点立即返回 `trace_id` 和 `status="started"`，执行过程通过 WebSocket 监听。
+`root_task_anchor` 在 Recursive 模式下必填，且 `objective/completion_criteria` 不能为空；Legacy 忽略该字段。旧字段 `root_completion_criteria` 会明确报错。该端点立即返回 `trace_id` 和 `status="started"`，执行过程通过 WebSocket 监听。
 
 ### 0.1 续跑、回溯与停止
 
@@ -719,6 +723,8 @@ Recursive 前端相关的 `context` 字段：
 | `root_trace_id` / `agent_depth` | 任务树根 ID 和业务 Agent 深度 |
 | `created_by_tool` | `agent` 为业务子 Trace，`validator` 为验收 Trace |
 | `task_protocol` | TaskBrief、待审核报告、审核记录和下一步动作 |
+| `root_task_anchor` | Recursive 任务树固化的根目标、完成标准和硬约束 |
+| `context_access` | 当前 Trace 已授权的协议引用目录；前端不应将其视为自由 Trace 读取接口 |
 
 **Trace ID 规则**：
 - 主 Trace：标准 UUID（如 "2f8d3a1c-4b6e-4f9a-8c2d-1e5b7a9f3c4d"）