AGENTS.md@src/host/agent git:20260928.0bc633cA

Immutable. This exact content never changes and is served at /api/v1/blob/e92e4d6c8f163523.

# Agent Module Rules

## 范围与职责

适用于 `src/host/agent/`。

治理「一个角色节点 ⇄ 一个可延续子代理」这一执行单元，并承担父代理会话能力的宿主适配：

- 把节点配置确定性翻译为官方子代理运行时的创建参数；
- 创建/复用节点子代理，并把本轮任务块投递进去；
- 在该子代理作用域内注入 Agent 语义；
- 为编排层与工具层提供父代理会话宿主能力。

判断归属：该修改是否改变「节点 → 子代理」的创建/复用/投递/作用域装配语义，或改变本模块对官方 Agent 能力的适配契约？若主要属于其他领域，应放到对应模块。

## 依赖边界

- 官方能力仅经 `ctx.get()` / 注入缝**运行时解析**，并以本模块自带的最小结构守卫收窄；允许 `import type` 官方纯类型（如 `Context`），不得有官方运行时 import；
- orchestrator 仅允许**类型**导入其公共入口（`NodeRunner` / `AgentHost` / `NodeStartInput` 等契约缝）；本模块不得成为 orchestrator 的运行时依赖；

## 生命周期

执行单元生命周期：创建 → 复用派发 → 进行中（不等待）→ 结束/失败/中断 → 清理（宿主统一）。

必须保证：
- **复用由配置签名决定**：签名必须覆盖一切影响子代理组成的输入。
- 创建/复用路径**不得等待子代理完成**；完成事实只经官方事件观察，由编排层回写。
- 中断是**尽力而为**：目标不存在或已停止视为成功；调用方不得依赖中断同步生效。
- **重建子代理时，旧子代理的处置语义必须明确**（保留/中断/归属回收），并在注释中说明其事件对节点结论的影响；不得让旧子代理的事件静默影响新子代理。

## 验证补充

- 涉及官方适配、宿主装配或产物契约时追加构建验证；
- 复用签名组成与作用域装配（安装/撤销）有测试锁定；
- 面向模型文本与工具白名单未意外改变。

## 核心原则

1. 节点配置确定性映射为官方子代理调用。
2. 复用由签名决定，签名必须完整。
3. 作用域装配的生命周期归宿主，模块不私建撤销表。
4. 创建即推理、不等待完成，完成只经事件观察。
5. 每子代理状态必须有释放条件与上界。
6. 面向模型的文本、工具白名单与官方消息 payload 是对外契约。