helloagents 3.0.9-beta.1 → 3.0.10

package/bootstrap-lite.md

@@ -172,10 +172,10 @@
 - `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
 - `T1` — 低风险小改动、明确实现、显式验证 → 直接执行或 `~build` / `~verify`
 - `T2` — 多文件功能、新项目、需要结构化产物 → `~plan` 或 `~auto`
-- `T3` — 高风险或不可逆链路（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
+- `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`
 
 ## 完成约束
-- 未激活项目且未进入方案包 / `contract.json` / 证据链路时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
+- 未激活项目且未进入方案包 / `contract.json` / 证据文件时，声称完成前必须完成与任务类型匹配的必要检查；无法执行的检查必须明确说明，不得直接宣称完成
 - 当前项目已激活，或已存在方案包 / `contract.json` / 证据文件时，以完整流程、对应 skill 与运行时交付约束为准，不得降级为本节
 - 只读分析、创意探索、方案比较、中间进度和阻塞汇报不适用本节
 
@@ -193,14 +193,14 @@
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
 - `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
-- `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
-- 当前 `STATE.md` 只认当前项目存储中的 `state_path`；支持会话标识时，它会落在 `.helloagents/sessions/{branch}/{session}/STATE.md`，未提供稳定会话标识时则落到 `.helloagents/sessions/{branch}/default/STATE.md`
+- `state_path` 指向的状态文件、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{branch}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{branch}/default/STATE.md`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 按上文 `~command` 路由中的相同技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一判断依据；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+- 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
   - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
@@ -208,14 +208,14 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
   - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
-  - 属于“强制创建并持续更新”范围且文件不存在时，按 templates/STATE.md 创建
-  - 每次更新是重写，不是追加。STATE.md 永远反映“此刻”的状态，不是历史
+  - 属于“强制创建并持续更新”范围且状态文件不存在时，按 templates/STATE.md 创建
+  - 每次更新是重写，不是追加。状态文件只记录当前状态，不记录历史
   - 更新时机：任务开始、关键决策落定、子任务完成、遇到/解除阻塞、任务完成
-  - 长流程中 STATE.md 过时就立即重写，不等任务结束
-  - 恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续；否则按当前消息、活跃方案包与代码事实重建主线，并立即重写 STATE.md
-  - `.helloagents/` 里只有 `STATE.md` 时，它只是恢复锚点，不是项目规则或自动授权
-  - 若宿主进入压缩/恢复前置阶段，且当前任务属于 STATE.md 适用范围，必须先确认 STATE.md 已同步到最新
-  - 自检：如果现在上下文被压缩，下一轮能否凭 STATE.md 找回进度？不能 → 该更新了
+  - 长流程中状态文件过时就立即重写，不等任务结束
+  - 恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件；否则按当前消息、活跃方案包与代码事实重新判断任务，并立即重写状态文件
+  - 当前项目只有状态文件时，它只是恢复参考，不是项目规则或自动授权
+  - 若宿主进入压缩/恢复前置阶段，且当前任务属于状态文件适用范围，必须先确认状态文件已同步到最新
+  - 自检：如果现在上下文被压缩，下一轮能否凭状态文件找回进度？不能 → 该更新了
   - “关键上下文”只保留恢复所需的信息，已不再相关的决策和变更移除
 - DESIGN.md — 项目级稳定 UI 契约（仅 UI 项目），`~plan` / `~auto` / `~prd` 创建或更新；不存在且当前任务涉及 UI → 按 templates/DESIGN.md 创建；不替代单次需求的 `plan.md`
 - plans/{feature}/ — 活跃方案包。`~plan` / `~auto` 生成：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`；`~prd` 生成：`prd/` 目录（多维度文档）+ `tasks.md` + `decisions.md` + `contract.json`
@@ -223,7 +223,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - archive/YYYY-MM/ — 已归档的方案包（整个 plans/{feature}/ 目录移入）
 - archive/_index.md — 归档索引
 
-### 知识沉淀（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
+### 知识记录（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -242,17 +242,17 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. 当前 `STATE.md`（始终取当前项目存储中的 `state_path`；恢复快照，只用于补齐最近进度）
-4. 其他知识沉淀与历史归档
+3. 当前状态文件（`state_path`，只用于补齐最近进度）
+4. 其他知识记录与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取当前项目存储中的 `state_path`
+- Tier 1 始终读取当前 `state_path`
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
-Tier 1 — 恢复当前链路时优先读取：
-- 当前 `STATE.md` → 恢复快照（始终取当前项目存储中的 `state_path`；先确认当前消息仍是同一任务，再用它找回最近进度）
+Tier 1 — 恢复当前任务时优先读取：
+- 当前状态文件（`state_path`）→ 先确认当前消息仍是同一任务，再用它找回最近进度
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引

package/bootstrap.md

@@ -176,14 +176,14 @@
   - `T0` — 只读分析、创意探索、方案比较 → 自然响应或 `~idea`
   - `T1` — 低风险小改动、明确实现、显式验证 → 直接执行或 `~build` / `~verify`
   - `T2` — 多文件功能、新项目、需要结构化产物 → `~plan` 或 `~auto`
-  - `T3` — 高风险或不可逆链路（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`，必要时单独确认
+  - `T3` — 高风险或不可逆操作（权限、安全、支付、数据库、生产发布等）→ 先 `~plan` / `~prd`，再 `~build` / `~verify`，必要时单独确认
 - 创意探索 / 方案比较 → `~idea`
 - 明确实现 / 小范围修复 → `~build`
 - 为指定模块编写测试 → `~test`
 - 结构化规划 / 新功能 / 新项目 → `~plan`
 - 完整产品规格 → `~prd`
 - 审查 / 执行验证 → `~verify`
-- 不确定或希望端到端自动推进时由 `~auto` 自动编排
+- 不确定或希望端到端自动推进时使用 `~auto`
 
 当前项目只要已建立 `.helloagents/`（例如执行过 `~wiki`、`~init`，或已进入项目级连续流程），就按项目级完整流程执行。
 
@@ -209,9 +209,9 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 - `~plan` 生成 `requirements.md`、`plan.md`、`tasks.md`、`contract.json`
 - `~prd` 生成 PRD 维度文档、`tasks.md`、`decisions.md`
 - `~build` 读取现有方案包并做定位，不重复发明方案
-- `contract.json` 是方案包的机器契约，至少明确 `verifyMode`、`reviewerFocus`、`testerFocus`；只有在 T3 / UI / 高风险链路确有收益时，才额外声明 `advisor`；进入验证或最终交付前，优先消费它而不是从自然语言描述里回推验证路径
+- `contract.json` 是方案包的机器契约，至少明确 `verifyMode`、`reviewerFocus`、`testerFocus`；只有在 T3 / UI / 高风险流程确有收益时，才额外声明 `advisor`；进入验证或最终交付前，优先消费它而不是从自然语言描述里回推验证路径
 - 涉及 UI 时，设计约束优先级固定为：当前 `plan.md` / PRD UI 决策 → 逻辑 `.helloagents/DESIGN.md`（实际路径按当前项目存储模式解析） → 通用 UI 规则
-- `~idea` 在输出比较与推荐后结束，不进入实现，也不创建 `.helloagents/`、`STATE.md` 或方案包
+- `~idea` 在输出比较与推荐后结束，不进入实现，也不创建 `.helloagents/`、状态文件或方案包
 
 ### 4. BUILD — 实现
 进入实现时，读取 PLAN 阶段标记的技能 SKILL.md（按上方 hello-* 技能查找路径读取 `skills/{技能名}/SKILL.md`），按其规范执行。
@@ -233,10 +233,10 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 非编码任务（文档 / 方案 / 审查等）：
 - 收集已激活技能的交付检查清单，逐项确认通过
 
-### 6. CONSOLIDATE — 状态、沉淀与归档
+### 6. CONSOLIDATE — 状态、资料与归档
 所有任务：
 - 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
-- `STATE.md` 维护：按上文“流程状态”中的适用边界执行。属于“强制创建并持续更新”范围时，重写当前 `STATE.md`（始终使用当前项目存储中的 `state_path`；“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
+- 状态文件维护：按上文“流程状态”中的适用范围执行。属于“强制创建并持续更新”范围时，重写 `state_path` 指向的文件（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
 - 有方案包且任务已完成 → 将整个 `plans/{feature}/` 目录归档到 `.helloagents/archive/YYYY-MM/`，并更新 `archive/_index.md`。清理临时文件（`loop-results.tsv`、`.ralph-breaker.json`、`.ralph-verify.json`、`.ralph-review.json`、`.ralph-closeout.json`）
 - 按 `kb_create_mode` 同步知识库（0=关闭 / 1=已激活项目或全局模式中编码自动 / 2=已激活项目或全局模式中始终）：
   - `.helloagents/` 不存在则按 templates/ 创建知识库文件（`context.md`、`guidelines.md`、`verify.yaml`、`CHANGELOG.md`、`modules/`）
@@ -262,14 +262,14 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 所有文件的创建和更新必须按 templates/ 目录中对应模板的格式执行，不可自由发挥格式。
 说明：
 - `.helloagents/` 表示项目级存储路径，也是 standby 模式的激活信号
-- `STATE.md`、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
-- 当前 `STATE.md` 只认当前项目存储中的 `state_path`；支持会话标识时，它会落在 `.helloagents/sessions/{branch}/{session}/STATE.md`，未提供稳定会话标识时则落到 `.helloagents/sessions/{branch}/default/STATE.md`
+- `state_path` 指向的状态文件、`.ralph-*.json`、`loop-results.tsv` 等运行态文件始终保留在项目本地 `.helloagents/`
+- `state_path` 是状态文件的唯一位置。宿主提供会话标识时，写入 `.helloagents/sessions/{branch}/{session}/STATE.md`；没有稳定会话标识时，写入 `.helloagents/sessions/{branch}/default/STATE.md`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 按上文相同的技能根目录规则确定；确定根目录后读取其中的 `templates/`。
 
 ### 流程状态（不受 kb_create_mode 控制，始终可写）
-- STATE.md — ≤70 行，项目级恢复快照。它只用于恢复“上次做到哪里”，不是主线任务的唯一判断依据；当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于 STATE.md
+- 状态文件（`state_path`）— ≤70 行，用来记录“上次做到哪里”。判断当前任务时，当前用户消息、显式命令、活跃方案包 / PRD、代码与验证证据优先于状态文件
   内容：主线目标、正在做什么、关键上下文（决策/变更/假设）、下一步（具体可执行动作含文件路径）、阻塞项
   适用边界：
   - 强制创建并持续更新：`~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop`，以及进入统一执行流程/已激活项目的连续任务
@@ -277,14 +277,14 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
   - 已有则更新：`~verify`、`~review`（兼容别名）、`~test`、`~commit`
   - 不创建：`~help`、`~idea`、普通问答、一次性只读任务、子代理自身执行过程、压缩/恢复钩子
   更新规则：
-  - 属于“强制创建并持续更新”范围且文件不存在时，按 templates/STATE.md 创建
-  - 每次更新是重写，不是追加。STATE.md 永远反映“此刻”的状态，不是历史
+  - 属于“强制创建并持续更新”范围且状态文件不存在时，按 templates/STATE.md 创建
+  - 每次更新是重写，不是追加。状态文件只记录当前状态，不记录历史
   - 更新时机：任务开始、关键决策落定、子任务完成、遇到/解除阻塞、任务完成
-  - 长流程中 STATE.md 过时就立即重写，不等任务结束
-  - 恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续；否则按当前消息、活跃方案包与代码事实重建主线，并立即重写 STATE.md
-  - `.helloagents/` 里只有 `STATE.md` 时，它只是恢复锚点，不是项目规则或自动授权
-  - 若宿主进入压缩/恢复前置阶段，且当前任务属于 STATE.md 适用范围，必须先确认 STATE.md 已同步到最新
-  - 自检：如果现在上下文被压缩，下一轮能否凭 STATE.md 找回进度？不能 → 该更新了
+  - 长流程中状态文件过时就立即重写，不等任务结束
+  - 恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件；否则按当前消息、活跃方案包与代码事实重新判断任务，并立即重写状态文件
+  - 当前项目只有状态文件时，它只是恢复参考，不是项目规则或自动授权
+  - 若宿主进入压缩/恢复前置阶段，且当前任务属于状态文件适用范围，必须先确认状态文件已同步到最新
+  - 自检：如果现在上下文被压缩，下一轮能否凭状态文件找回进度？不能 → 该更新了
   - “关键上下文”只保留恢复所需的信息，已不再相关的决策和变更移除
 - DESIGN.md — 项目级稳定 UI 契约（仅 UI 项目），`~plan` / `~auto` / `~prd` 创建或更新；不存在且当前任务涉及 UI → 按 templates/DESIGN.md 创建；不替代单次需求的 `plan.md`
 - plans/{feature}/ — 活跃方案包。`~plan` / `~auto` 生成：`requirements.md` + `plan.md` + `tasks.md` + `contract.json`；`~prd` 生成：`prd/` 目录（多维度文档）+ `tasks.md` + `decisions.md` + `contract.json`
@@ -292,7 +292,7 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 - archive/YYYY-MM/ — 已归档的方案包（整个 plans/{feature}/ 目录移入）
 - archive/_index.md — 归档索引
 
-### 知识沉淀（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
+### 知识记录（受 kb_create_mode 控制，0=关闭/1=已激活项目或全局模式中编码自动/2=已激活项目或全局模式中始终）
 - context.md — 项目架构、技术栈、目录结构、模块索引
 - guidelines.md — 编码约定（仅含非显而易见的约定）
 - CHANGELOG.md — 变更历史
@@ -311,17 +311,17 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. 当前 `STATE.md`（始终取当前项目存储中的 `state_path`；恢复快照，只用于补齐最近进度）
-4. 其他知识沉淀与历史归档
+3. 当前状态文件（`state_path`，只用于补齐最近进度）
+4. 其他知识记录与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取当前项目存储中的 `state_path`
+- Tier 1 始终读取当前 `state_path`
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
-Tier 1 — 恢复当前链路时优先读取：
-- 当前 `STATE.md` → 恢复快照（始终取当前项目存储中的 `state_path`；先确认当前消息仍是同一任务，再用它找回最近进度）
+Tier 1 — 恢复当前任务时优先读取：
+- 当前状态文件（`state_path`）→ 先确认当前消息仍是同一任务，再用它找回最近进度
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.9-beta.1",
+  "version": "3.0.10",
   "description": "Quality-driven orchestration kernel for AI CLIs",
   "contextFileName": "bootstrap.md",
   "author": "HelloWind",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.9-beta.1",
+  "version": "3.0.10",
   "type": "module",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": "HelloWind",
@@ -36,17 +36,7 @@
     ".claude-plugin/",
     ".codex-plugin/"
   ],
-  "keywords": [
-    "ai",
-    "agent",
-    "claude",
-    "codex",
-    "cli",
-    "orchestration",
-    "subagent",
-    "hooks",
-    "skills"
-  ],
+  "keywords": ["ai", "agent", "claude", "codex", "cli", "orchestration", "subagent", "hooks", "skills"],
   "engines": {
     "node": ">=18"
   }

package/scripts/cli-codex-config.mjs

@@ -27,7 +27,13 @@ export function isManagedCodexModelInstruction(line = '') {
 }
 
 export function isManagedCodexNotify(line = '') {
-  return line.includes('codex-notify')
+  const value = String(line || '').replace(/\\/g, '/')
+  return value.includes(CODEX_MANAGED_TOML_COMMENT)
+    || (
+      value.includes('codex-notify')
+      && value.includes('/scripts/notify.mjs')
+      && /(^|[/\\])helloagents([/\\]|-|$)|[/\\]plugins[/\\]helloagents[/\\]/i.test(value)
+    )
 }
 
 export function isManagedCodexBackupInstruction(line = '') {
@@ -51,7 +57,7 @@ function formatManagedCodexNotifyValue(notifyScriptPath) {
 }
 
 function formatManagedCodexNotifyLine(notifyScriptPath) {
-  return `notify = ${formatManagedCodexNotifyValue(notifyScriptPath)}`
+  return `notify = ${formatManagedCodexNotifyValue(notifyScriptPath)} ${CODEX_MANAGED_TOML_COMMENT}`
 }
 
 function removeTopLevelLinesBeingReplaced(toml, lines) {

package/scripts/cli-codex.mjs

@@ -20,6 +20,7 @@ import {
 } from './cli-codex-config.mjs';
 import {
   readTopLevelTomlLine,
+  readTopLevelTomlBlock,
   readTomlKeyInSection,
   removeTomlKeyInSection,
   ensureTomlKeyInSection,
@@ -98,7 +99,8 @@ function removeCodexMarketplaceEntry(marketplaceFile) {
   }
   if (!removedHelloagents) return false;
   if (!nextPlugins.length) {
-    removeIfExists(marketplaceFile);
+    marketplace.plugins = [];
+    safeWrite(marketplaceFile, JSON.stringify(marketplace, null, 2) + '\n');
     return true;
   }
   marketplace.plugins = nextPlugins;
@@ -130,7 +132,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
   let toml = safeRead(configPath) || '';
 
   const currentModelInstructions = readTopLevelTomlLine(toml, 'model_instructions_file');
-  const currentNotify = readTopLevelTomlLine(toml, 'notify');
+  const currentNotify = readTopLevelTomlBlock(toml, 'notify');
   const currentCodexHooks = readTomlKeyInSection(toml, '[features]', 'codex_hooks');
 
   const shouldRestoreModelInstructions = isManagedCodexModelInstruction(currentModelInstructions);
@@ -153,7 +155,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
   }
 
   const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
-  const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
+  const backupNotify = readTopLevelTomlBlock(backupToml, 'notify');
   const backupCodexHooks = readTomlKeyInSection(backupToml, '[features]', 'codex_hooks');
 
   toml = restoreCodexTopLevelConfig(toml, {

package/scripts/cli-lifecycle.mjs

@@ -181,6 +181,17 @@ function runAllHostsLifecycle(action, explicitMode) {
   }
 
   const settings = readSettings(true)
+  if (action === 'update' && !explicitMode) {
+    for (const host of HOSTS) {
+      const mode = resolveHostMode(host, '', settings)
+      const result = runHostLifecycle(runtime, action, host, mode)
+      if (!result.skipped) setTrackedHostMode(settings, host, mode)
+    }
+    writeSettings(settings)
+    runtime.printInstallMsg(settings.install_mode || DEFAULTS.install_mode, 'refresh')
+    return
+  }
+
   const mode = resolveInstallMode(explicitMode, settings)
   if (explicitMode) settings.install_mode = explicitMode
   installAllHosts(runtime, mode)

package/scripts/cli-messages.mjs

@@ -44,8 +44,8 @@ function renderInstallMessage(context, mode, state) {
     }
     return msg(
       refresh
-        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件链路已重装并同步最新文件。'
-        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动走原生本地插件链路。',
+        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件已重装并同步最新文件。'
+        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动安装原生本地插件。',
       refresh
         ? '  Global mode refreshed.\n  Keep Claude Code / Gemini plugins installed; Codex native local-plugin files were reinstalled and synced.'
         : '  All projects will use full HelloAGENTS rules.\n  Install Claude Code / Gemini plugins manually; Codex now uses the native local-plugin path automatically.',
@@ -92,7 +92,7 @@ ${msg('单 CLI 管理', 'Scoped CLI management')}:
 ${msg('诊断', 'Diagnostics')}:
   helloagents doctor
   helloagents doctor codex --json
-  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件链路、受管 model_instructions_file 指向与版本漂移', 'Checks carriers, links, hooks, config injections, the Codex plugin chain, managed model_instructions_file targeting, and version drift')}
+  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件安装、受管 model_instructions_file 指向与版本漂移', 'Checks carriers, links, hooks, config injections, Codex plugin installation, managed model_instructions_file targeting, and version drift')}
 
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}

package/scripts/cli-toml-values.mjs

@@ -0,0 +1,25 @@
+export function getTomlArrayDepthDelta(text) {
+  let depth = 0
+  let quoted = false
+  let escaped = false
+
+  for (const char of String(text || '')) {
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (char === '\\' && quoted) {
+      escaped = true
+      continue
+    }
+    if (char === '"') {
+      quoted = !quoted
+      continue
+    }
+    if (quoted) continue
+    if (char === '[') depth += 1
+    if (char === ']') depth -= 1
+  }
+
+  return depth
+}

package/scripts/cli-toml.mjs

@@ -3,6 +3,8 @@
  * Targets the small subset of TOML structures used by Codex CLI config.
  */
 
+import { getTomlArrayDepthDelta } from './cli-toml-values.mjs'
+
 export function isTomlTableHeader(line) {
   const trimmed = String(line || '').trim();
   return trimmed.startsWith('[') && trimmed.endsWith(']');
@@ -62,6 +64,19 @@ function findTopLevelTomlBlock(text, key) {
     const closeIndex = normalized.indexOf('"""', openIndex + 3);
     end = closeIndex >= 0 ? closeIndex + 3 : normalized.length;
   }
+  if (value.startsWith('[')) {
+    let depth = getTomlArrayDepthDelta(firstLine.slice(firstLine.indexOf('=') + 1));
+    let lineStart = firstLineEnd + (normalized[firstLineEnd] === '\n' ? 1 : 0);
+
+    while (depth > 0 && lineStart < normalized.length) {
+      const lineEndIndex = normalized.indexOf('\n', lineStart);
+      const nextLineEnd = lineEndIndex >= 0 ? lineEndIndex : normalized.length;
+      const nextLine = normalized.slice(lineStart, nextLineEnd);
+      depth += getTomlArrayDepthDelta(nextLine);
+      end = nextLineEnd;
+      lineStart = nextLineEnd + 1;
+    }
+  }
 
   while (end < normalized.length && normalized[end] === '\n') {
     end += 1;

package/scripts/guard.mjs

@@ -124,7 +124,7 @@ function buildPostWriteWarnings(data) {
   const filePath = data.tool_input?.file_path || ''
   return [
     ...(detectIdeaBoundaryContext(data)?.zeroSideEffect
-      ? ['~idea 本轮要求只读探索；检测到写入工具落地，请回退到探索输出或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
+      ? ['~idea 本轮要求只读探索；检测到写入文件的工具调用，请回到探索输出，或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
       : []),
     ...scanUnrequestedFiles(filePath, data.tool_name),
     ...(content ? [...scanForSecrets(content), ...scanDangerousPackages(content, filePath)] : []),
@@ -195,7 +195,7 @@ function handleHighRiskCommand(data, command) {
 function emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings) {
   const sections = []
   if (highRiskWarnings.length > 0) {
-    sections.push(`⚠️ [HelloAGENTS 高风险链路提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
+    sections.push(`⚠️ [HelloAGENTS 高风险操作提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
   }
   if (shellSafetyWarnings.length > 0) {
     sections.push(`⚠️ [HelloAGENTS Shell 安全提醒] 检测到建议调整的命令写法:\n${shellSafetyWarnings.map((warning) => `  - ${warning}`).join('\n')}\n当前仅提示，不中断执行。`)

package/scripts/notify-context.mjs

@@ -74,8 +74,8 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
   if (stateSnapshot.exists && stateSnapshot.content) {
     summaryParts.push('');
-    summaryParts.push(`## 恢复快照（从 ${stateSnapshot.statePath.replace(/\\/g, '/')} 读取，只用于找回上次停在哪）`);
-    summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
+    summaryParts.push(`## 状态文件（从 ${stateSnapshot.statePath.replace(/\\/g, '/')} 读取，只用于找回上次停在哪）`);
+    summaryParts.push('恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件。');
     summaryParts.push(stateSnapshot.content);
   }
 
@@ -109,7 +109,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
 
   if (stateSyncHint) {
     summaryParts.push('');
-    summaryParts.push('## STATE.md 提醒');
+    summaryParts.push('## 状态文件提醒');
     summaryParts.push(stateSyncHint);
   }
 
@@ -140,10 +140,10 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   if (projectStorageBlock) context += `\n\n${projectStorageBlock}`;
   if (workflowHint) context += `\n\n## 当前工作流提示\n${workflowHint}`;
   if (capabilityHint) context += `\n\n## 当前按需能力\n${capabilityHint}`;
-  if (stateSyncHint) context += `\n\n## STATE.md 提醒\n${stateSyncHint}`;
+  if (stateSyncHint) context += `\n\n## 状态文件提醒\n${stateSyncHint}`;
   context += settingsBlock;
   if (source === 'resume' || source === 'compact') {
-    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取当前 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。`;
+    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\`；先看当前用户消息，如果仍是同一任务，再参考状态文件。`;
   }
   return context;
 }
@@ -168,8 +168,8 @@ export function buildSemanticRouteInstruction(cwd, payload = {}) {
   return [
     '当前消息未使用 ~command。',
     '请根据用户请求的真实意图选路，不依赖关键词表。',
-    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆链路。',
-    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动编排并自动衔接后续阶段。',
+    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆操作。',
+    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
     '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',
     `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 通用 UI 规则。`,
     projectStorageHint,

package/scripts/notify-events.mjs

@@ -5,11 +5,3 @@ export function shouldIgnoreCodexNotifyClient(client) {
 export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
   return outputFormatEnabled && !lastMsg.includes('【HelloAGENTS】');
 }
-
-export function claimsTaskComplete(lastMsg) {
-  if (!lastMsg) return false;
-  if (/^✅【HelloAGENTS】- .*(当前任务已完成|任务已完成|已修复|完成交付|done|fixed|completed|finished)/im.test(lastMsg)) {
-    return true;
-  }
-  return /(当前任务已完成|任务已完成|已全部完成|已修复|修复完成|\b(done|fixed|completed|finished)\b)/i.test(lastMsg);
-}

package/scripts/notify-gates.mjs

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+function truncateText(value = '') {
+  const text = String(value || '').trim()
+  return text.length > 1000 ? `${text.slice(0, 1000)}\n...(truncated)` : text
+}
+
+function buildGateErrorReason(source, detail = '') {
+  return [
+    `[HelloAGENTS Runtime] ${source} 执行失败，已暂停完成通知。`,
+    detail ? `原因：${detail}` : '',
+    '请修复脚本或重新运行验证后再报告完成。',
+  ].filter(Boolean).join('\n')
+}
+
+function emitGateError({
+  payload,
+  host,
+  source,
+  reason,
+  appendReplayEvent,
+  output,
+}) {
+  appendReplayEvent(payload.cwd || process.cwd(), {
+    host,
+    event: 'runtime_gate_error',
+    source,
+    reason,
+  })
+  output({
+    decision: 'block',
+    reason,
+    suppressOutput: true,
+  })
+  return true
+}
+
+export function runGateScript({
+  payload,
+  host,
+  scriptPath,
+  args = [],
+  source,
+  blockEvent,
+  timeout,
+  appendReplayEvent,
+  output,
+}) {
+  if (!existsSync(scriptPath)) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, `脚本不存在：${scriptPath}`),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    input: JSON.stringify(payload),
+    encoding: 'utf-8',
+    timeout,
+  })
+
+  if (result.error) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, result.error.message),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  if (result.status !== 0) {
+    const detail = truncateText(`${result.stderr || ''}\n${result.stdout || ''}`) || `退出码 ${result.status}`
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, detail),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  const stdout = String(result.stdout || '').trim()
+  if (!stdout) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, '脚本未返回有效结果'),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  let gateOutput
+  try {
+    gateOutput = JSON.parse(stdout)
+  } catch {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, `脚本返回了无法解析的 JSON：${truncateText(stdout)}`),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  if (gateOutput.decision === 'block') {
+    appendReplayEvent(payload.cwd || process.cwd(), {
+      host,
+      event: blockEvent,
+      source,
+      reason: gateOutput.reason || '',
+    })
+    output(gateOutput)
+    return true
+  }
+
+  return false
+}

package/scripts/notify-ui.mjs

@@ -18,6 +18,7 @@ const NOTIFY_MESSAGES = {
 };
 
 const WIN_APPID = 'HelloAgents.Notification';
+const DISABLE_OS_NOTIFICATIONS = process.env.HELLOAGENTS_DISABLE_OS_NOTIFICATIONS === '1';
 
 function escapeToastText(value = '') {
   return String(value)
@@ -55,6 +56,7 @@ function resolveWav(pkgRoot, event) {
 }
 
 export function playSound(pkgRoot, event) {
+  if (DISABLE_OS_NOTIFICATIONS) return;
   const wav = resolveWav(pkgRoot, event);
   if (!wav) { process.stderr.write('\x07'); return; }
   try {
@@ -83,6 +85,7 @@ function ensureWinAppId(pkgRoot) {
 }
 
 export function desktopNotify(pkgRoot, event, extra) {
+  if (DISABLE_OS_NOTIFICATIONS) return;
   const notification = buildDesktopNotificationContent(event, extra);
   try {
     if (PLAT === 'win32') {