helloagents 3.0.8-beta.1 → 3.0.9-beta.1

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "helloagents",
       "description": "Quality-driven orchestration kernel for AI CLIs: intelligent routing, quality verification, safety guards, and notifications",
-      "version": "3.0.8-beta.1",
+      "version": "3.0.9-beta.1",
       "source": "./",
       "author": {
         "name": "HelloWind",

package/.claude-plugin/plugin.json

@@ -1,8 +1,11 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.9-beta.1",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
-  "author": "HelloWind",
+  "author": {
+    "name": "HelloWind",
+    "email": "hellowind777@gmail.com"
+  },
   "license": "Apache-2.0",
   "keywords": [
     "orchestration",
@@ -12,10 +15,7 @@
     "notification",
     "safety"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/hellowind777/helloagents.git"
-  },
+  "repository": "https://github.com/hellowind777/helloagents",
   "skills": "./skills",
   "hooks": "./hooks/hooks-claude.json"
 }

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.9-beta.1",
   "description": "HelloAGENTS — Quality-driven orchestration kernel for AI CLIs with intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/README.md

@@ -8,7 +8,7 @@
 
 **Quality-driven workflow framework for AI coding CLIs — 14 auto-activated skills, process discipline, and checklist-based quality checks.**
 
-[![Version](https://img.shields.io/badge/version-3.0.8-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.9-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -95,7 +95,7 @@ HelloAGENTS fixes that. It's a workflow layer that sits on top of your AI CLI an
 
 If the last version you used seriously was `v2.3.8`, this is not a minor update. The current line is a full product-line reset.
 
-| Dimension | v2.3.8 | Local `v3.0.8` |
+| Dimension | v2.3.8 | Local `v3.0.9` |
 |-----------|--------|----------------|
 | **Implementation base** | Python package plus mixed scripts/rules | Pure Node.js + Markdown runtime built around `cli.mjs`, `bootstrap*.md`, `skills/`, and `scripts/` |
 | **Product shape** | More like a multi-CLI management tool plus prompt protocol bundle | More like a quality workflow framework for AI CLIs, centered on routing, checks, verification, and resumable execution |
@@ -108,7 +108,7 @@ If the last version you used seriously was `v2.3.8`, this is not a minor update.
 | **KB storage** | Project-local only | Project-local by default, plus `project_store_mode=repo-shared` for sharing stable KB/plan assets across git worktrees |
 | **Codex integration** | Earlier compatibility layers and legacy paths | Standby = injected rules + local links; global = native local-plugin chain with less noise and drift |
 
-In one sentence: `v2.3.8` was closer to "workflow glue for multiple CLIs"; `v3.0.8` is a workflow framework that unifies quality rules, plan files, verification records, and installation lifecycle into one operating model.
+In one sentence: `v2.3.8` was closer to "workflow glue for multiple CLIs"; `v3.0.9` is a workflow framework that unifies quality rules, plan files, verification records, and installation lifecycle into one operating model.
 
 ## ✨ Core Features
 
@@ -304,12 +304,12 @@ HelloAGENTS touches different files depending on mode. The write/cleanup rules a
 |-----|------------------------|----------------|
 | Claude Code | Native plugin install (manual CLI command) | Managed by Claude's plugin system |
 | Gemini CLI | Native extension install (manual CLI command) | Managed by Gemini's extension system |
-| Codex CLI | Native local-plugin chain (automatic) | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/`, `~/.codex/plugins/cache/local-plugins/helloagents/local/`, `~/.codex/config.toml` |
+| Codex CLI | Native local-plugin chain (automatic) | `~/.agents/plugins/marketplace.json`, `~/plugins/helloagents/`, `~/.codex/plugins/cache/local-plugins/helloagents/local/`, `~/.codex/config.toml`, `~/.codex/helloagents -> ~/plugins/helloagents` |
 
 ### Update / reinstall / branch-switch behavior
 
 - **Standby mode** keeps scripts, skills, templates, and hooks on `~/.claude/helloagents`, `~/.gemini/helloagents`, and `~/.codex/helloagents` symlinks, so linked package files reflect local changes immediately. The injected rules files (`CLAUDE.md`, `GEMINI.md`, `AGENTS.md`) are still snapshots and must be refreshed after bootstrap or branch changes.
-- **Codex global mode** uses copied runtime files. Re-running `helloagents --global` refreshes both `~/plugins/helloagents/` and the Codex cache copy.
+- **Codex global mode** uses copied runtime files and keeps `~/.codex/helloagents -> ~/plugins/helloagents` as the stable read-root fallback expected by bootstrap routing. Re-running `helloagents --global` refreshes both `~/plugins/helloagents/` and the Codex cache copy.
 - Re-running the current mode command is supported intentionally: `helloagents --standby` and `helloagents --global` both act as **switch-or-refresh** commands.
 - For deterministic manual cleanup, run `helloagents cleanup` before `npm uninstall -g helloagents`.
 - `npm uninstall -g helloagents` removes the package; `~/.helloagents/helloagents.json` is intentionally preserved.
@@ -499,9 +499,9 @@ After every task, Ralph Loop auto-runs your project's verification commands:
 
 `~wiki` creates or syncs the project knowledge base only. `~init` is the fuller bootstrap: it also writes project-level rule files (`AGENTS.md`, `CLAUDE.md`, `.gemini/GEMINI.md`), refreshes host-native project skill links, and appends the related ignore rules. In standby mode, the presence of the local `.helloagents/` is what promotes the current project into the full project workflow; project-level rule files are optional.
 
-By default, KB and plan files live in the project's local `.helloagents/`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` directory keeps only the activation signal, `STATE.md`, and runtime files such as `.ralph-*`, while `context.md`, `guidelines.md`, `DESIGN.md`, `verify.yaml`, `modules/`, `plans/`, and `archive/` move to `~/.helloagents/projects/<repo-key>/` so multiple worktrees of the same git repo can share stable project memory.
+By default, KB and plan files live in the project's local `.helloagents/`. The active recovery snapshot now has a single authoritative path: `state_path`. When the host exposes a stable conversation/session identifier, HelloAGENTS writes it to `.helloagents/sessions/<branch>/<session>/STATE.md`; otherwise it uses the branch default slot at `.helloagents/sessions/<branch>/default/STATE.md`. If `project_store_mode = "repo-shared"`, the local `.helloagents/` directory keeps the activation signal, session-scoped `STATE.md`, and runtime files such as `.ralph-*`, while `context.md`, `guidelines.md`, `DESIGN.md`, `verify.yaml`, `modules/`, `plans/`, and `archive/` move to `~/.helloagents/projects/<repo-key>/` so multiple worktrees of the same git repo can share stable project memory.
 
-`STATE.md` is a project-level recovery snapshot, not a universal memory file for every interaction. It is created and continuously updated for long-running project workflows such as `~wiki`, `~init`, `~plan`, `~build`, `~auto`, `~prd`, and `~loop`; updated when already present for verification/review style tasks; and intentionally not created for one-off read-only interactions such as `~help`.
+`STATE.md` is the active recovery snapshot resolved from `state_path`, not a universal memory file for every interaction. Its branch + session layout prevents concurrent conversations on the same repo from fighting over one shared file. It is created and continuously updated for long-running project workflows such as `~wiki`, `~init`, `~plan`, `~build`, `~auto`, `~prd`, and `~loop`; updated when already present for verification/review style tasks; and intentionally not created for one-off read-only interactions such as `~help`.
 
 | File | Purpose |
 |------|---------|
@@ -718,7 +718,7 @@ Subagents may skip workflow packaging such as routing, interaction flow, and out
 
 ## 📈 Version History
 
-### v3.0.8 (current)
+### v3.0.9 (current)
 
 **Fixes and verification:**
 - 🔧 Claude Code / Gemini CLI `stop` delivery gating now prioritizes structured `turn-state` instead of inferring completion from natural-language text, so ordinary waiting turns no longer get misclassified as finished delivery

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **质量驱动的 AI 编码 CLI 工作流框架 — 14 个自动激活技能、流程纪律、检查清单把关。**
 
-[![Version](https://img.shields.io/badge/version-3.0.8-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.9-orange.svg)](./package.json)
 [![npm](https://img.shields.io/npm/v/helloagents.svg)](https://www.npmjs.com/package/helloagents)
 [![Node](https://img.shields.io/badge/node-%3E%3D18-339933.svg)](./package.json)
 [![Skills](https://img.shields.io/badge/skills-14-6366f1.svg)](./skills)
@@ -95,7 +95,7 @@ HelloAGENTS 就是为了解决这个问题。它是一个编排层，装在你
 
 如果你上一次认真使用 HelloAGENTS 还是 `v2.3.8`，这一代的变化不是“增量补丁”，而是整条产品线重构。
 
-| 维度 | v2.3.8 | 本地 `v3.0.8` |
+| 维度 | v2.3.8 | 本地 `v3.0.9` |
 |------|--------|---------------|
 | **底层实现** | Python 包 + 大量脚本/规则混合 | 纯 Node.js + Markdown 运行时，围绕 `cli.mjs`、`bootstrap*.md`、`skills/`、`scripts/` 重建 |
 | **目标定位** | 更像多 CLI 管理工具 + 提示协议集合 | 更像 AI CLI 的质量工作流框架，重点是路由、把关、验证和可恢复执行 |
@@ -108,7 +108,7 @@ HelloAGENTS 就是为了解决这个问题。它是一个编排层，装在你
 | **知识库存储** | 默认项目本地 | 默认项目本地，同时新增 `project_store_mode=repo-shared`，支持同一 git 仓库多个 worktree 共享稳定知识和方案资产 |
 | **Codex 集成** | 早期依赖更多兼容层和旧链路 | 标准模式使用注入规则 + 本地链接；全局模式使用原生本地插件链路，减少噪音与漂移 |
 
-一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.8` 更像“把质量协议、计划产物、验证证据和安装生命周期统一成一套真正可运转的工作流框架”。
+一句话概括：`v2.3.8` 更像“给多个 CLI 加一层工作流外壳”，`v3.0.9` 更像“把质量协议、计划产物、验证证据和安装生命周期统一成一套真正可运转的工作流框架”。
 
 ## ✨ 核心特性
 
@@ -304,12 +304,12 @@ HelloAGENTS 在不同模式下会写入不同文件，但写入/恢复/清理都
 |-----|---------|----------|
 | Claude Code | 原生插件安装（手动命令） | 由 Claude 插件系统管理 |
 | Gemini CLI | 原生扩展安装（手动命令） | 由 Gemini 扩展系统管理 |
-| Codex CLI | 原生本地插件链路（自动） | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml` |
+| Codex CLI | 原生本地插件链路（自动） | `~/.agents/plugins/marketplace.json`、`~/plugins/helloagents/`、`~/.codex/plugins/cache/local-plugins/helloagents/local/`、`~/.codex/config.toml`、`~/.codex/helloagents -> ~/plugins/helloagents` |
 
 ### 更新 / 重装 / 切分支行为
 
 - **标准模式** 通过 `~/.claude/helloagents`、`~/.gemini/helloagents`、`~/.codex/helloagents` 这三个符号链接保持脚本、技能、模板和 hooks 与包根目录同步，相关链接文件会立即反映本地变化；但 `CLAUDE.md`、`GEMINI.md`、`AGENTS.md` 这类注入后的规则文件仍是快照，bootstrap 或分支变化后需要显式刷新。
-- **Codex 全局模式** 使用复制后的运行时文件。重新执行 `helloagents --global` 会刷新 `~/plugins/helloagents/` 和 Codex cache 中的副本。
+- **Codex 全局模式** 使用复制后的运行时文件，并维护 `~/.codex/helloagents -> ~/plugins/helloagents` 作为 bootstrap 路由期望的稳定读取根目录。重新执行 `helloagents --global` 会刷新 `~/plugins/helloagents/` 和 Codex cache 中的副本。
 - 重新执行当前模式命令是被支持的：`helloagents --standby` 和 `helloagents --global` 都是 **切换或刷新** 命令。
 - 如需确定性的手动清理，先执行 `helloagents cleanup`，再执行 `npm uninstall -g helloagents`。
 - `npm uninstall -g helloagents` 会移除包本身；`~/.helloagents/helloagents.json` 会被有意保留。
@@ -499,9 +499,9 @@ HelloAGENTS 支持两种安装模式，采用不同的安装方式：
 
 `~wiki` 只创建或同步项目知识库。`~init` 是更完整的项目初始化：它还会写入项目级规则文件（`AGENTS.md`、`CLAUDE.md`、`.gemini/GEMINI.md`）、刷新各宿主项目级原生 skills 链接，并补齐相关忽略项。在标准模式下，真正让当前项目进入完整项目流程的是项目本地 `.helloagents/` 的存在，项目级规则文件只是 `~init` 的附加能力。
 
-默认情况下，知识库和方案包都写在项目本地 `.helloagents/`。若 `project_store_mode = "repo-shared"`，本地 `.helloagents/` 仅保留激活信号、`STATE.md` 与 `.ralph-*` 等运行态文件；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 会改写到 `~/.helloagents/projects/<repo-key>/`，从而在同一 git 仓库的多个 worktree 间共享稳定资料。
+默认情况下，知识库和方案包都写在项目本地 `.helloagents/`。当前恢复快照现在只认一个权威路径：`state_path`。当宿主能提供稳定的会话标识时，HelloAGENTS 会把它写到 `.helloagents/sessions/<branch>/<session>/STATE.md`；否则写到分支默认槽位 `.helloagents/sessions/<branch>/default/STATE.md`。若 `project_store_mode = "repo-shared"`，本地 `.helloagents/` 仅保留激活信号、会话级 `STATE.md` 与 `.ralph-*` 等运行态文件；`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 会改写到 `~/.helloagents/projects/<repo-key>/`，从而在同一 git 仓库的多个 worktree 间共享稳定资料。
 
-`STATE.md` 是项目级恢复快照，不是所有交互的统一记忆文件。它会在 `~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop` 这类项目级连续流程中创建并持续更新；在验证/审查类任务中仅在文件已存在时更新；对 `~help` 这类一次性只读交互则不会创建。
+`STATE.md` 是由 `state_path` 解析出的当前恢复快照，不是所有交互的统一记忆文件。按“分支 + 会话 / 默认槽位”存储后，同仓库并发对话不再争用同一个文件。它会在 `~wiki`、`~init`、`~plan`、`~build`、`~auto`、`~prd`、`~loop` 这类项目级连续流程中创建并持续更新；在验证/审查类任务中仅在文件已存在时更新；对 `~help` 这类一次性只读交互则不会创建。
 
 | 文件 | 用途 |
 |------|------|
@@ -718,7 +718,7 @@ npm test
 
 ## 📈 版本历史
 
-### v3.0.8（当前版本）
+### v3.0.9（当前版本）
 
 **修复与验证：**
 - 🔧 Claude Code / Gemini CLI 的 `stop` 交付门控现在优先读取结构化 `turn-state`，不再先从自然语言文本反推“是否完成交付”，普通等待态不再被误判为已完成

package/bootstrap-lite.md

@@ -194,6 +194,7 @@
 说明：
 - `.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`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 按上文 `~command` 路由中的相同技能根目录规则确定；确定根目录后读取其中的 `templates/`。
@@ -241,17 +242,17 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
+3. 当前 `STATE.md`（始终取当前项目存储中的 `state_path`；恢复快照，只用于补齐最近进度）
 4. 其他知识沉淀与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
+- Tier 1 的 `STATE.md` 始终读取当前项目存储中的 `state_path`
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
 Tier 1 — 恢复当前链路时优先读取：
-- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
+- 当前 `STATE.md` → 恢复快照（始终取当前项目存储中的 `state_path`；先确认当前消息仍是同一任务，再用它找回最近进度）
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引

package/bootstrap.md

@@ -236,7 +236,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 ### 6. CONSOLIDATE — 状态、沉淀与归档
 所有任务：
 - 有方案包且准备报告完成 → 优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录“需求覆盖”和“交付清单”；每项写明 `PASS` / `BLOCKED` 与简要摘要，再进入最终交付
-- `STATE.md` 维护：按上文“流程状态”中的适用边界执行。属于“强制创建并持续更新”范围时，重写 `.helloagents/STATE.md`（“正在做什么”更新为已完成，清空关键上下文 / 下一步 / 阻塞项）；属于“已有则更新”范围时，仅在文件已存在时重写；属于“不创建”范围时不生成此文件
+- `STATE.md` 维护：按上文“流程状态”中的适用边界执行。属于“强制创建并持续更新”范围时，重写当前 `STATE.md`（始终使用当前项目存储中的 `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/`）
@@ -263,6 +263,7 @@ hello-* 技能读取路径：`{HELLOAGENTS_READ_ROOT}/skills/{技能名}/SKILL.m
 说明：
 - `.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`
 - 若 helloagents.json 中 `project_store_mode = "repo-shared"`，`context.md`、`guidelines.md`、`CHANGELOG.md`、`verify.yaml`、`DESIGN.md`、`modules/`、`plans/`、`archive/` 改按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析；未注入具体路径时，按当前存储模式自行解析，不要假定这些文件一定实际位于当前工作树中
 templates/ 查找路径（按优先级；首次确定模板根目录后，本轮复用）：
 按上文相同的技能根目录规则确定；确定根目录后读取其中的 `templates/`。
@@ -310,17 +311,17 @@ templates/ 查找路径（按优先级；首次确定模板根目录后，本轮
 主线判断依据优先级：
 1. 当前用户最新消息、显式 `~command`、本轮已确认的范围与结论
 2. 当前活跃方案包 / PRD、代码与验证证据
-3. `.helloagents/STATE.md`（恢复快照，只用于补齐最近进度）
+3. 当前 `STATE.md`（始终取当前项目存储中的 `state_path`；恢复快照，只用于补齐最近进度）
 4. 其他知识沉淀与历史归档
 
 ### .helloagents/ 文件读取优先级
 以下文件在任务需要时按需读取，按优先级分层：
 说明：
-- Tier 1 的 `STATE.md` 始终读取项目本地 `.helloagents/STATE.md`
+- Tier 1 的 `STATE.md` 始终读取当前项目存储中的 `state_path`
 - Tier 2 / Tier 3 中的 `.helloagents/...` 路径默认按项目级存储路径解析；`project_store_mode=repo-shared` 时按共享知识/方案目录解析
 
 Tier 1 — 恢复当前链路时优先读取：
-- .helloagents/STATE.md → 恢复快照（先确认当前消息仍是同一任务，再用它找回最近进度）
+- 当前 `STATE.md` → 恢复快照（始终取当前项目存储中的 `state_path`；先确认当前消息仍是同一任务，再用它找回最近进度）
 
 Tier 2 — 理解项目时读取：
 - .helloagents/context.md → 项目架构、技术栈、目录结构、模块索引

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.8-beta.1",
+  "version": "3.0.9-beta.1",
   "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.8-beta.1",
+  "version": "3.0.9-beta.1",
   "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",

package/scripts/capability-registry.mjs

@@ -8,9 +8,9 @@ function getPrimaryPlan(snapshot) {
   return snapshot.activePlans[0] || snapshot.plans[0] || null
 }
 
-export function selectCapabilities({ cwd, skillName = '' }) {
-  const snapshot = getWorkflowSnapshot(cwd)
-  const recommendation = getWorkflowRecommendation(cwd)
+export function selectCapabilities({ cwd, skillName = '', options = {} }) {
+  const snapshot = getWorkflowSnapshot(cwd, options)
+  const recommendation = getWorkflowRecommendation(cwd, options)
   const plan = getPrimaryPlan(snapshot)
   const advisorRequirement = getAdvisorRequirement(plan?.contract)
   const visualRequirement = getVisualValidationRequirement(plan?.contract)
@@ -52,8 +52,8 @@ export function selectCapabilities({ cwd, skillName = '' }) {
   return capabilities
 }
 
-export function buildCapabilityHint({ cwd, skillName = '' }) {
-  const capabilities = selectCapabilities({ cwd, skillName })
+export function buildCapabilityHint({ cwd, skillName = '', options = {} }) {
+  const capabilities = selectCapabilities({ cwd, skillName, options })
   if (capabilities.length === 0) return ''
   return `按需能力：${capabilities.map((entry) => `${entry.id}=${entry.description}`).join(' ')}`
 }

package/scripts/cli-codex.mjs

@@ -248,6 +248,7 @@ export function installCodexGlobal(home, pkgRoot) {
 
   copyEntries(pkgRoot, pluginRoot, CODEX_RUNTIME_ENTRIES);
   copyEntries(pkgRoot, installedPluginRoot, CODEX_RUNTIME_ENTRIES);
+  createLink(pluginRoot, join(codexDir, 'helloagents'));
   writeCodexRuntimeCarrier(
     join(pluginRoot, CODEX_RUNTIME_CARRIER),
     join(pluginRoot, 'bootstrap.md'),
@@ -286,6 +287,7 @@ export function uninstallCodexGlobal(home) {
   removeIfExists(pluginCacheRoot);
   removeCodexMarketplaceEntry(marketplaceFile);
   removeMarkedContent(join(codexDir, 'AGENTS.md'));
+  removeLink(join(codexDir, 'helloagents'));
 
   const toml = cleanupCodexManagedConfig(configPath, { removePluginConfig: true });
   if (toml.trim()) safeWrite(configPath, toml);

package/scripts/cli-doctor.mjs

@@ -230,6 +230,7 @@ function appendCodexStandbyIssues(issues, checks) {
 function appendCodexGlobalIssues(issues, checks, pluginVersion, cacheVersion) {
   if (!checks.carrierMarker) issues.push(buildDoctorIssue('global-home-carrier-missing', 'global `~/.codex/AGENTS.md` 缺少 HelloAGENTS 规则内容', 'Global `~/.codex/AGENTS.md` is missing the HelloAGENTS carrier'))
   if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('global-home-carrier-drift', 'global `~/.codex/AGENTS.md` 与当前 bootstrap.md 不一致', 'Global `~/.codex/AGENTS.md` differs from the current bootstrap.md'))
+  if (!checks.globalHomeLink) issues.push(buildDoctorIssue('global-read-root-link-missing', 'global `~/.codex/helloagents` 链接缺失或未指向当前插件根目录', 'Global `~/.codex/helloagents` link is missing or does not point to the current plugin root'))
   if (!checks.pluginRoot) issues.push(buildDoctorIssue('global-plugin-root-missing', 'global 插件根目录缺失', 'Global plugin root is missing'))
   if (!checks.pluginCache) issues.push(buildDoctorIssue('global-plugin-cache-missing', 'global 插件缓存目录缺失', 'Global plugin cache directory is missing'))
   if (checks.pluginRoot && !checks.pluginCarrierMatch) issues.push(buildDoctorIssue('global-plugin-carrier-drift', 'global 插件根目录中的 AGENTS.md 与当前 bootstrap.md 不一致', 'Global plugin AGENTS.md differs from the current bootstrap.md'))
@@ -258,6 +259,9 @@ function inspectCodexDoctor(settings) {
   const marketplace = safeJson(join(runtime.home, '.agents', 'plugins', 'marketplace.json')) || {}
   const pluginVersion = safeJson(join(pluginRoot, 'package.json'))?.version || ''
   const cacheVersion = safeJson(join(pluginCacheRoot, 'package.json'))?.version || ''
+  const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
+  const pkgRootTarget = safeRealTarget(runtime.pkgRoot) || normalizePath(runtime.pkgRoot)
+  const pluginRootTarget = safeRealTarget(pluginRoot) || normalizePath(pluginRoot)
   const standbyNotifyPath = normalizePath(join(runtime.pkgRoot, 'scripts', 'notify.mjs'))
   const globalNotifyPath = normalizePath(join(pluginRoot, 'scripts', 'notify.mjs'))
   const managedHomeCarrierPath = normalizePath(join(codexDir, 'AGENTS.md'))
@@ -268,7 +272,8 @@ function inspectCodexDoctor(settings) {
   const checks = {
     carrierMarker: (safeRead(join(codexDir, 'AGENTS.md')) || '').includes('HELLOAGENTS_START'),
     carrierContentMatch: extractManagedCarrierContent(join(codexDir, 'AGENTS.md')) === readBootstrapContent(expectedHomeCarrier),
-    homeLink: safeRealTarget(join(codexDir, 'helloagents')) === runtime.pkgRoot,
+    homeLink: homeLinkTarget === pkgRootTarget,
+    globalHomeLink: homeLinkTarget === pluginRootTarget,
     modelInstructionsFile: !!modelInstructionsLine,
     modelInstructionsPathMatch: !!modelInstructionsLine
       && normalizePath(modelInstructionsLine).includes(`"${managedHomeCarrierPath}"`),

package/scripts/cli-host-detect.mjs

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
 import {
@@ -27,6 +27,18 @@ function hasHelloagentsSettings(filePath) {
   return JSON.stringify(safeJson(filePath) || {}).includes('helloagents')
 }
 
+function normalizePath(value = '') {
+  return String(value || '').replace(/\\/g, '/').toLowerCase()
+}
+
+function safeRealTarget(linkPath) {
+  try {
+    return normalizePath(realpathSync(linkPath))
+  } catch {
+    return ''
+  }
+}
+
 function detectClaudeMode(home) {
   const claudeDir = join(home, '.claude')
   if (
@@ -53,19 +65,23 @@ function detectGeminiMode(home) {
 
 function detectCodexMode(home) {
   const codexDir = join(home, '.codex')
+  const codexHomeLink = join(codexDir, 'helloagents')
   const codexConfig = safeRead(join(codexDir, 'config.toml')) || ''
   const marketplace = safeRead(join(home, '.agents', 'plugins', 'marketplace.json')) || ''
+  const globalPluginRoot = normalizePath(join(home, 'plugins', CODEX_PLUGIN_NAME))
+  const codexHomeLinkTarget = safeRealTarget(codexHomeLink)
   if (
     existsSync(join(home, 'plugins', CODEX_PLUGIN_NAME))
     || existsSync(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME))
     || marketplace.includes(`"name": "${CODEX_PLUGIN_NAME}"`)
     || codexConfig.includes(CODEX_PLUGIN_KEY)
     || codexConfig.includes(`/plugins/${CODEX_PLUGIN_NAME}/scripts/notify.mjs`)
+    || codexHomeLinkTarget === globalPluginRoot
   ) {
     return 'global'
   }
   if (
-    existsSync(join(codexDir, 'helloagents'))
+    (existsSync(codexHomeLink) && codexHomeLinkTarget !== globalPluginRoot)
     || hasHelloagentsMarker(join(codexDir, 'AGENTS.md'))
     || codexConfig.includes('codex-notify')
     || codexConfig.includes('HelloAGENTS')

package/scripts/delivery-gate.mjs

@@ -205,10 +205,11 @@ function main() {
     data = JSON.parse(readFileSync(0, 'utf-8'))
   } catch {}
   const cwd = data.cwd || process.cwd()
-  const snapshot = getWorkflowSnapshot(cwd)
-  const recommendation = getWorkflowRecommendation(cwd)
+  const workflowOptions = { payload: data }
+  const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
+  const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
   const verificationStatus = getVerifyEvidenceStatus(cwd)
-  const deliveryAction = getDeliveryAction(cwd)
+  const deliveryAction = getDeliveryAction(cwd, workflowOptions)
   const gatePlans = selectGatePlans(snapshot)
   const reviewStatus = getReviewEvidenceStatus(cwd, {
     required: deliveryAction?.phase === 'verify' && deliveryAction?.mode === 'review-first',
@@ -248,7 +249,7 @@ function main() {
 
   process.stdout.write(JSON.stringify({
     decision: 'block',
-    reason: buildBlockReason(issues, recommendation, buildDeliveryGateHint(cwd)),
+    reason: buildBlockReason(issues, recommendation, buildDeliveryGateHint(cwd, workflowOptions)),
     suppressOutput: true,
   }))
 }

package/scripts/guard.mjs

@@ -62,15 +62,16 @@ function emitGuardEvent(cwd, event, source, reason, details = {}) {
   })
 }
 
-function buildHighRiskGate(matches, cwd) {
-  const stateSyncHint = buildStateSyncHint(cwd)
+function buildHighRiskGate(matches, cwd, payload = {}) {
+  const workflowOptions = { payload }
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions)
   if (stateSyncHint) {
     return {
       reason: `[HelloAGENTS Guard] Blocked T3 command until project recovery state is synced.\n${stateSyncHint}`,
     }
   }
 
-  const recommendation = getWorkflowRecommendation(cwd)
+  const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
   if (!recommendation) return null
   if (matches.some((match) => match.gate === 'post-verify')) {
     return {
@@ -172,7 +173,7 @@ function handleHighRiskCommand(data, command) {
   if (warnings.length === 0) return []
 
   const cwd = data.cwd || process.cwd()
-  const gate = buildHighRiskGate(warnings, cwd)
+  const gate = buildHighRiskGate(warnings, cwd, data)
   if (gate) {
     emitHookPayload({
       hookSpecificOutput: {

package/scripts/notify-context.mjs

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint } from './workflow-state.mjs';
+import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint, readStateSnapshot } from './workflow-state.mjs';
 import { buildCapabilityHint } from './capability-registry.mjs';
 import {
   buildProjectStorageBlock,
@@ -69,16 +69,14 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   summaryParts.push('以下信息在上下文压缩前保存，确保压缩后不丢失关键状态。');
 
   const cwd = payload.cwd || process.cwd();
-  const statePath = join(cwd, '.helloagents', 'STATE.md');
-  const stateSyncHint = buildStateSyncHint(cwd);
-  if (existsSync(statePath)) {
-    try {
-      const stateContent = readFileSync(statePath, 'utf-8');
-      summaryParts.push('');
-      summaryParts.push('## 恢复快照（从 STATE.md 读取，只用于找回上次停在哪）');
-      summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
-      summaryParts.push(stateContent);
-    } catch {}
+  const workflowOptions = { payload };
+  const stateSnapshot = readStateSnapshot(cwd, workflowOptions);
+  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.content);
   }
 
   let bootstrap = '';
@@ -103,7 +101,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
     summaryParts.push(readRootBlock);
   }
 
-  const projectStorageBlock = buildProjectStorageBlock(cwd);
+  const projectStorageBlock = buildProjectStorageBlock(cwd, workflowOptions);
   if (projectStorageBlock) {
     summaryParts.push('');
     summaryParts.push(projectStorageBlock);
@@ -123,13 +121,15 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   return summaryParts.join('\n');
 }
 
-export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd }) {
+export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd, payload = {} }) {
+  const workflowOptions = { payload };
   const packageRootBlock = buildPackageRootBlock(pkgRoot);
   const readRootBlock = buildReadRootBlock(resolveReadRoot({ cwd, pkgRoot, host, settings }));
-  const workflowHint = buildWorkflowRouteHint(cwd);
-  const capabilityHint = buildCapabilityHint({ cwd });
-  const projectStorageBlock = buildProjectStorageBlock(cwd);
-  const stateSyncHint = buildStateSyncHint(cwd);
+  const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
+  const projectStorageBlock = buildProjectStorageBlock(cwd, workflowOptions);
+  const stateSnapshot = readStateSnapshot(cwd, workflowOptions);
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
   const settingsBlock = Object.keys(settings).length
     ? `\n\n## 当前用户设置\n\`\`\`json\n${JSON.stringify(settings, null, 2)}\n\`\`\``
     : '';
@@ -143,26 +143,28 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   if (stateSyncHint) context += `\n\n## STATE.md 提醒\n${stateSyncHint}`;
   context += settingsBlock;
   if (source === 'resume' || source === 'compact') {
-    context += '\n\n> ⚠️ 会话已恢复/压缩，请先读取 `.helloagents/STATE.md` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。';
+    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取当前 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。`;
   }
   return context;
 }
 
-export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings }) {
+export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings, payload = {} }) {
+  const workflowOptions = { payload };
   const readRoot = resolveReadRoot({ cwd, pkgRoot, host, settings });
   const canonicalSkillName = resolveCanonicalCommandSkill(skillName);
   const skillPath = join(readRoot.root, 'skills', 'commands', canonicalSkillName, 'SKILL.md');
   const aliasNote = buildAliasRouteNote(skillName);
-  const commandHint = buildCommandRouteHint(canonicalSkillName, cwd);
-  const capabilityHint = buildCapabilityHint({ cwd, skillName: canonicalSkillName });
-  const projectStorageHint = buildProjectStorageHint(cwd);
+  const commandHint = buildCommandRouteHint(canonicalSkillName, cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, skillName: canonicalSkillName, options: workflowOptions });
+  const projectStorageHint = buildProjectStorageHint(cwd, workflowOptions);
   return `用户使用了 ~${skillName} 命令。当前命令技能文件已解析为：${skillPath}。请直接读取这个 SKILL.md；不要再探测其他 helloagents 路径。${aliasNote ? ` ${aliasNote}` : ''}${projectStorageHint ? ` ${projectStorageHint}` : ''}${commandHint ? ` ${commandHint}` : ''}${capabilityHint ? ` ${capabilityHint}` : ''}${extraRules}`;
 }
 
-export function buildSemanticRouteInstruction(cwd) {
-  const workflowHint = buildWorkflowRouteHint(cwd);
-  const capabilityHint = buildCapabilityHint({ cwd });
-  const projectStorageHint = buildProjectStorageHint(cwd);
+export function buildSemanticRouteInstruction(cwd, payload = {}) {
+  const workflowOptions = { payload };
+  const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
+  const projectStorageHint = buildProjectStorageHint(cwd, workflowOptions);
   return [
     '当前消息未使用 ~command。',
     '请根据用户请求的真实意图选路，不依赖关键词表。',

package/scripts/notify-route.mjs

@@ -17,6 +17,7 @@ function buildHelpExtraRules(skillName) {
 
 function routeExplicitCommand({
   prompt,
+  payload,
   cwd,
   host,
   pkgRoot,
@@ -51,6 +52,7 @@ function routeExplicitCommand({
     pkgRoot,
     host,
     settings,
+    payload,
   }))
   return true
 }
@@ -80,6 +82,7 @@ export function handleRouteCommand({
 
   if (routeExplicitCommand({
     prompt,
+    payload,
     cwd,
     host,
     pkgRoot,
@@ -100,9 +103,9 @@ export function handleRouteCommand({
       host,
       event: 'semantic_route_prompted',
       source: 'route',
-      recommendation: getWorkflowRecommendation(cwd),
+      recommendation: getWorkflowRecommendation(cwd, { payload }),
     })
-    suppress(buildSemanticRouteInstruction(cwd))
+    suppress(buildSemanticRouteInstruction(cwd, payload))
     return
   }