helloagents 3.0.22-beta.1 → 3.0.23

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.22-beta.1",
+  "version": "3.0.23",
   "description": "HelloAGENTS — The orchestration kernel that makes any AI CLI smarter. Adds intelligent routing, quality verification (Ralph Loop), safety guards, and notifications.",
   "author": {
     "name": "HelloWind",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.22-beta.1",
+  "version": "3.0.23",
   "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 @@
 
 **A workflow layer for AI coding CLIs: skills, project knowledge, delivery checks, safer config writes, and resumable execution.**
 
-[![Version](https://img.shields.io/badge/version-3.0.22-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.23-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)
@@ -209,7 +209,7 @@ Runtime evidence files include:
 - `.helloagents/sessions/<workspace>/<session>/artifacts/closeout.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
-Delivery gate, guard, and loop messages use action-oriented wording such as processing path, closeout action, and visual validation action, so blocked flows show what to do next without turning executable steps into optional suggestions.
+Delivery gate, guard, and loop messages use action-oriented wording such as processing path, closeout action, and visual validation action, so blocked flows show what to do next without turning executable steps into optional suggestions. Final closeout also enforces a single HelloAGENTS wrapper, so one reply does not emit duplicate closeout headers.
 
 ### 7) Safer install, update, cleanup, and diagnostics
 
@@ -220,6 +220,7 @@ The CLI manages host files explicitly:
 - `cleanup` removes managed injections and links
 - `uninstall` performs scoped cleanup before package removal
 - `doctor` reports drift in carriers, links, hooks, config entries, plugin roots, cache copies, and versions
+- per-host mode tracking is written only after a host setup succeeds, so failed native global installs do not leave stale mode records
 
 ## Quick Start
 
@@ -616,7 +617,7 @@ Default shape:
 | `project_store_mode` | `"local"` | `local` or `repo-shared` |
 | `commit_attribution` | `""` | optional text appended to commit messages |
 | `install_mode` | `"standby"` | current default install mode |
-| `host_install_modes` | `{}` | managed per-CLI mode map, such as `{ "codex": "standby" }`; used before falling back to `install_mode` |
+| `host_install_modes` | `{}` | managed per-CLI mode map, such as `{ "codex": "standby" }`; recorded only after successful host setup and used before falling back to `install_mode` |
 
 ## How Each CLI Is Integrated
 
@@ -657,7 +658,7 @@ Run all tests:
 npm test
 ```
 
-The current suite includes 103 tests and covers:
+The current suite includes 107 tests and covers:
 
 - install, update, uninstall, cleanup, and mode switching
 - Claude, Gemini, and Codex config merge and restore behavior
@@ -666,7 +667,7 @@ The current suite includes 103 tests and covers:
 - `helloagents doctor`
 - project storage and `repo-shared` behavior
 - session-scoped `state_path`, runtime signals, and evidence
-- runtime routing, guard, verification, visual evidence, and delivery gates
+- runtime routing, guard, verification, visual evidence, delivery gates, single-wrapper closeout validation, and successful-mode tracking after native install failures
 - README and skill contract alignment
 
 ## FAQ

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.22-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.23-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)
@@ -209,7 +209,7 @@ HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交
 - `.helloagents/sessions/<workspace>/<session>/artifacts/closeout.json`
 - `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
-交付门控、守卫和循环提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。
+交付门控、守卫和循环提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终收尾还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
 
 ### 7）更安全的安装、更新、清理和诊断
 
@@ -220,6 +220,7 @@ CLI 显式管理宿主文件：
 - `cleanup` 删除受管注入和链接
 - `uninstall` 在移除包前执行对应清理
 - `doctor` 检查规则文件、链接、hooks、配置项、插件根目录、缓存副本和版本漂移
+- 单 CLI 模式记录只会在宿主安装成功后写入，避免原生全局安装失败后留下错误模式记录
 
 ## 快速开始
 
@@ -618,7 +619,7 @@ UI 任务遵循以下优先级：
 | `project_store_mode` | `"local"` | `local` 或 `repo-shared` |
 | `commit_attribution` | `""` | 提交信息附加署名 |
 | `install_mode` | `"standby"` | 当前默认安装模式 |
-| `host_install_modes` | `{}` | 受管的单 CLI 模式记录，如 `{ "codex": "standby" }`；优先于 `install_mode` |
+| `host_install_modes` | `{}` | 受管的单 CLI 模式记录，如 `{ "codex": "standby" }`；仅在宿主安装成功后写入，并优先于 `install_mode` |
 
 ## 各 CLI 集成方式
 
@@ -659,7 +660,7 @@ Codex 默认走规则文件驱动。
 npm test
 ```
 
-当前测试共 103 项，覆盖：
+当前测试共 107 项，覆盖：
 
 - 安装、更新、卸载、清理和模式切换
 - Claude、Gemini、Codex 的配置合并与恢复
@@ -668,7 +669,7 @@ npm test
 - `helloagents doctor`
 - 项目存储和 `repo-shared`
 - 会话级 `state_path`、运行态信号和证据
-- 运行时选路、Guard、验证、视觉证据和交付门控
+- 运行时选路、Guard、验证、视觉证据、交付门控、单次收尾包装校验，以及原生安装失败后的模式记录
 - README 与 skill 契约一致性
 
 ## FAQ

package/bootstrap-lite.md

@@ -116,7 +116,7 @@
 图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
 
 使用约束：
-- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案或修改）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
+- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案或修改）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。同一条最终收尾消息只使用一次该格式；若主体需要分段，在同一个外层块内分节，不得在正文中再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
 - `🔄 下一步` 必须写真正的下一步动作，不写单纯当前状态或条件式能力表述。若正在等待确认，写清待确认动作；若仍有已授权且可继续执行的动作，不得收尾，必须继续执行；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成；无后续动作。”
 
 ### 收尾状态信号

package/bootstrap.md

@@ -116,7 +116,7 @@
 图标：💡直接响应 | ⚡快速执行 | 🔵规划流程 | ✅完成 | ❓等待输入 | ⚠️警告 | ❌错误
 
 使用约束：
-- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案或修改）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。
+- 首行必须保留 `【HelloAGENTS】` 和连字符 `-`，不得省略；状态图标与收尾内容必须一致。正文仍在等待用户输入、确认、授权或补充信息（含确认是否执行已给出的方案或修改）时，只能使用 `❓等待输入`；仅在本轮执行已完成且不存在待确认动作时，才能使用 `✅完成`。同一条最终收尾消息只使用一次该格式；若主体需要分段，在同一个外层块内分节，不得在正文中再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
 - `🔄 下一步` 必须写真正的下一步动作，不写单纯当前状态或条件式能力表述。若正在等待确认，写清待确认动作；若仍有已授权且可继续执行的动作，不得收尾，必须继续执行；若当前任务已完整结束且确无合理后续，可填写“当前任务已完成；无后续动作。”
 
 ### 收尾状态信号

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.22-beta.1",
+  "version": "3.0.23",
   "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.22-beta.1",
+  "version": "3.0.23",
   "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/cli-lifecycle.mjs

@@ -59,14 +59,18 @@ function clearTrackedHostMode(settings, host) {
   delete settings.host_install_modes[host]
 }
 
-function setAllTrackedHostModes(settings, mode) {
-  settings.host_install_modes = Object.fromEntries(HOSTS.map((host) => [host, mode]))
-}
-
 function clearAllTrackedHostModes(settings) {
   settings.host_install_modes = {}
 }
 
+function syncTrackedHostMode(settings, host, result, mode) {
+  if (!result?.skipped && result?.ok !== false) {
+    setTrackedHostMode(settings, host, mode)
+    return
+  }
+  clearTrackedHostMode(settings, host)
+}
+
 export function normalizeHost(value = '') {
   return normalizeLifecycleHost(value)
 }
@@ -157,8 +161,11 @@ export function switchMode(newMode) {
     runtime.ok(runtime.msg(`当前已是 ${newMode} 模式，正在刷新安装`, `Already in ${newMode} mode, refreshing installation`))
   }
 
-  installAllHosts(runtime, newMode)
-  setAllTrackedHostModes(config, newMode)
+  const results = installAllHosts(runtime, newMode)
+  clearAllTrackedHostModes(config)
+  for (const host of HOSTS) {
+    syncTrackedHostMode(config, host, results?.[host], newMode)
+  }
   writeSettings(config)
   runtime.printInstallMsg(newMode, isRefresh ? 'refresh' : 'switch')
 }
@@ -229,7 +236,7 @@ export function runScopedLifecycle(action, rawArgs) {
       writeSettings(settings)
     }
   } else if (!result.skipped) {
-    setTrackedHostMode(settings, host, mode)
+    syncTrackedHostMode(settings, host, result, mode)
     writeSettings(settings)
   }
 }

package/scripts/turn-stop-gate.mjs

@@ -48,6 +48,56 @@ function buildBlockReason(routeContext, detail, cwd) {
   ].filter(Boolean).join('\n')
 }
 
+function getLastAssistantMessage(payload = {}) {
+  return String(
+    payload.lastAssistantMessage
+    || payload.last_assistant_message
+    || payload['last-assistant-message']
+    || '',
+  ).trim()
+}
+
+function countMatches(text, pattern) {
+  const matches = text.match(pattern)
+  return matches ? matches.length : 0
+}
+
+function validateFormattedCloseoutMessage(routeContext, payload, cwd) {
+  const message = getLastAssistantMessage(payload)
+  if (!message || !message.includes('【HelloAGENTS】')) return ''
+
+  const firstNonEmptyLine = message
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean)
+
+  if (!firstNonEmptyLine || !/^[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】- /.test(firstNonEmptyLine)) {
+    return buildBlockReason(
+      routeContext,
+      '最终收尾消息使用了 HelloAGENTS 外层格式，但首个非空行不是规范标题行。',
+      cwd,
+    )
+  }
+
+  if (countMatches(message, /[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】-/g) > 1) {
+    return buildBlockReason(
+      routeContext,
+      '最终收尾消息重复输出了 HelloAGENTS 标题；请把所有内容合并到同一个外层块内。',
+      cwd,
+    )
+  }
+
+  if (countMatches(message, /^🔄 下一步:/gm) > 1) {
+    return buildBlockReason(
+      routeContext,
+      '最终收尾消息重复输出了 `🔄 下一步`；请只保留一个真实下一步。',
+      cwd,
+    )
+  }
+
+  return ''
+}
+
 function getMainTurnState(cwd, payload = {}) {
   const turnState = readTurnState(cwd, { payload })
   return turnState?.role === 'main' ? turnState : null
@@ -64,11 +114,13 @@ function hasStructuredBlocker(turnState) {
   )
 }
 
-function validateTurnState(routeContext, turnState, cwd) {
+function validateTurnState(routeContext, turnState, cwd, payload = {}) {
   if (!turnState) {
     return buildBlockReason(routeContext, '缺少主代理 turn-state。', cwd)
   }
   if (turnState.kind === 'complete') {
+    const formatReason = validateFormattedCloseoutMessage(routeContext, payload, cwd)
+    if (formatReason) return formatReason
     return ''
   }
   if (turnState.kind === 'waiting' || turnState.kind === 'blocked') {
@@ -101,7 +153,7 @@ function main() {
     return
   }
 
-  const reason = validateTurnState(routeContext, getMainTurnState(cwd, payload), cwd)
+  const reason = validateTurnState(routeContext, getMainTurnState(cwd, payload), cwd, payload)
   process.stdout.write(JSON.stringify(reason ? { decision: 'block', reason } : { decision: 'continue' }))
 }
 

package/skills/helloagents/SKILL.md

@@ -5,7 +5,7 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有本轮最终收尾消息才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终收尾中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。
+主代理触发或读取任意 skill 时，只有本轮最终收尾消息才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终收尾中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。同一条最终收尾消息只包装一次；若需要分段，在同一个外层块内展开，不在正文里再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。
 只有运行时必须识别本轮“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要 delivery gate / Ralph Loop / closeout evidence、需要等待或阻塞且运行时必须识别状态、已进入项目连续流程或方案包闭环。首选 `helloagents-turn-state write --kind complete --role main`；等待或阻塞时写 `kind=waiting` / `kind=blocked`，并同时写 `reasonCategory` 与 `reason`。显式 `~auto` / `~loop` 下，还必须写入 `blocker.target`、`blocker.evidence`、`blocker.requiredAction`。不要查找、读取或拼接 `turn-state.mjs` 源码路径。子代理不得写 turn-state。