helloagents 3.0.11-beta.1 → 3.0.12-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.11-beta.1",
+      "version": "3.0.12-beta.1",
       "source": "./",
       "author": {
         "name": "HelloWind",

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.11-beta.1",
+  "version": "3.0.12-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": {
     "name": "HelloWind",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.11-beta.1",
+  "version": "3.0.12-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 @@
 
 **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.11-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.12-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)
@@ -30,7 +30,7 @@
 ## Contents
 
 - [What HelloAGENTS Does](#what-helloagents-does)
-- [What Changed Since v3.0.7](#what-changed-since-v307)
+- [What Changed Since v3.0.11](#what-changed-since-v3011)
 - [Core Features](#core-features)
 - [Quick Start](#quick-start)
 - [CLI Management](#cli-management)
@@ -77,19 +77,13 @@ HelloAGENTS adds a workflow layer on top of Claude Code, Gemini CLI, and Codex C
 | Completion is vague | Natural language says “done” | Delivery checks use state, evidence, and verification |
 | Config writes are risky | CLI files can drift | Install, update, cleanup, and doctor flows check managed files |
 
-## What Changed Since v3.0.7
+## What Changed Since v3.0.11
 
-These are the main user-visible runtime and install changes in `v3.0.11`, compared with `v3.0.7`:
+These are the main user-visible runtime changes in `v3.0.12`, compared with `v3.0.11`:
 
-- Workflow runtime hints now use execution wording instead of staged “next command / next stage” suggestions, so active work is less likely to stop at phase boundaries.
-- Explicit `~auto` now treats the chosen path as a direct execution path and tells the agent to keep going until delivery or a real blocker, instead of turning phase results into “next-step” hand-offs.
-- Explicit `~loop` now follows its own loop rules directly; existing plan or verify recommendations stay as context only and no longer try to reroute the loop itself.
-- The final closeout fallback wording no longer sounds like it is waiting for another manual approval after the task is already complete.
-- Main-agent delivery now uses structured `turn-state` values such as `complete`, `waiting`, and `blocked`; stop, notify, and closeout no longer infer completion from natural-language text.
-- Workflow recovery now uses the current `state_path`, with session-scoped state files under `.helloagents/sessions/<branch>/<session-or-default>/STATE.md`.
-- The old project-root state fallback has been removed, so recovery follows one current state path.
-- Codex standby/global install, refresh, cleanup, and doctor checks are stricter: managed `notify` entries are marked, multiline `notify` arrays are preserved, and user-owned `model_instructions_file`, `notify`, and non-managed `codex_hooks` are kept during restore.
-- Codex global mode now refreshes the home read root, local plugin root, marketplace entry, enabled plugin block, and cache copy after reinstall, update, or local branch changes.
+- Explicit `~auto` and `~loop` no longer get a free pass to stop a turn early. Before the runtime accepts the turn end, it now checks whether the main agent wrote a valid structured stop state.
+- `waiting` and `blocked` turn states now require both a `reasonCategory` and a concrete `reason`, so only real blockers can pause the workflow instead of vague “next step” hand-offs.
+- The stop hook and Codex turn-complete notification path now enforce the same gate, reducing cases where work still should continue but the agent stops as if it is waiting for approval.
 
 ## Core Features
 

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.11-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.12-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)
@@ -30,7 +30,7 @@
 ## 目录
 
 - [HelloAGENTS 做什么](#helloagents-做什么)
-- [相对 v3.0.7 的真实变化](#相对-v307-的真实变化)
+- [相对 v3.0.11 的真实变化](#相对-v3011-的真实变化)
 - [核心功能](#核心功能)
 - [快速开始](#快速开始)
 - [CLI 管理](#cli-管理)
@@ -77,19 +77,13 @@ HelloAGENTS 叠加在 Claude Code、Gemini CLI 和 Codex CLI 之上，帮助模
 | 完成态模糊 | 自然语言说“完成” | 按状态、证据和验证结果交付 |
 | 配置容易漂移 | CLI 文件可能不一致 | 安装、更新、清理和 doctor 会检查受管文件 |
 
-## 相对 v3.0.7 的真实变化
+## 相对 v3.0.11 的真实变化
 
-下面是当前 `v3.0.11` 相对 `v3.0.7` 的主要运行时和安装变化：
+下面是当前 `v3.0.12` 相对 `v3.0.11` 的主要运行时变化：
 
-- 运行时工作流提示改成执行型表述，不再用“下一命令 / 下一阶段”这类分阶段建议去强化停顿感。
-- 显式使用 `~auto` 时，当前主路径会被当成直接执行路径；除非命中真实阻塞，否则不会把阶段结果改写成“下一步”交接。
-- 显式使用 `~loop` 时，当前循环按 `~loop` 自己的规则直接执行；现有方案包和验证建议只作为上下文，不再把循环本身带偏到别的命令。
-- 最终收尾的兜底文案不再写成“等待下一步指示”，避免任务已经完成时仍表现得像在等人工批准。
-- 主代理交付改用结构化 `turn-state`，明确区分 `complete`、`waiting`、`blocked`；stop、notify、收尾流程不再从自然语言里猜完成态。
-- 工作流恢复改为读取当前 `state_path`，状态文件按会话写入 `.helloagents/sessions/<branch>/<session-or-default>/STATE.md`。
-- 移除旧的项目根状态文件回退逻辑，恢复流程只走当前状态路径。
-- Codex 标准/全局模式的安装、刷新、清理和 doctor 检查更严格：受管 `notify` 会带标记，多行 `notify` 数组可保留，用户自己的 `model_instructions_file`、`notify`、非托管 `codex_hooks` 会在恢复时保留。
-- Codex 全局模式在重装、更新或本地切分支后，会同步刷新 home 读取根、本地插件根目录、marketplace 条目、插件启用段和缓存副本。
+- 显式使用 `~auto` 和 `~loop` 时，运行时不再默认接受中途停下；主代理结束本轮前，必须先写出有效的结构化停下状态。
+- `waiting` 和 `blocked` 现在必须同时带 `reasonCategory` 和具体 `reason`，只有真实阻塞才能暂停流程，不再接受含糊的“下一步”式停顿。
+- stop hook 和 Codex 的 turn-complete 通知链路现在共用同一层门控，减少任务本应继续执行却表现得像在等批准的情况。
 
 ## 核心功能
 

package/bootstrap-lite.md

@@ -123,8 +123,9 @@
 ### 收尾状态信号
 - 为避免运行时从自然语言、图标或格式反推“完成 / 等待输入”，主代理在本轮最终收尾前必须先调用 `scripts/turn-state.mjs write`
 - 本轮已完成且不再等待用户输入 → 写 `kind=complete`、`role=main`
-- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`
-- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`
+- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`，并同时写 `reasonCategory` 与 `reason`
+- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`，并同时写 `reasonCategory` 与 `reason`
+- `reasonCategory` 只允许：`ambiguity`、`missing-input`、`missing-file`、`missing-credential`、`unauthorized-side-effect`、`high-risk-confirmation`、`external-dependency`、`error`
 - 子代理不得写 turn-state；子代理结束只直接返回结果，不为主代理代写完成态
 
 ## 交互规则

package/bootstrap.md

@@ -123,8 +123,9 @@
 ### 收尾状态信号
 - 为避免运行时从自然语言、图标或格式反推“完成 / 等待输入”，主代理在本轮最终收尾前必须先调用 `scripts/turn-state.mjs write`
 - 本轮已完成且不再等待用户输入 → 写 `kind=complete`、`role=main`
-- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`
-- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`
+- 因阻塞判定等待用户输入、确认、授权或补充信息 → 写 `kind=waiting`、`role=main`，并同时写 `reasonCategory` 与 `reason`
+- 因错误、缺少前置条件或外部依赖而本轮停下 → 写 `kind=blocked`、`role=main`，并同时写 `reasonCategory` 与 `reason`
+- `reasonCategory` 只允许：`ambiguity`、`missing-input`、`missing-file`、`missing-credential`、`unauthorized-side-effect`、`high-risk-confirmation`、`external-dependency`、`error`
 - 子代理不得写 turn-state；子代理结束只直接返回结果，不为主代理代写完成态
 
 ## 交互规则

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.11-beta.1",
+  "version": "3.0.12-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.11-beta.1",
+  "version": "3.0.12-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/notify.mjs

@@ -93,6 +93,19 @@ function runDeliveryGate(payload) {
   });
 }
 
+function runTurnStopGate(payload) {
+  return runGateScript({
+    payload,
+    host: HOST,
+    scriptPath: join(__dirname, 'turn-stop-gate.mjs'),
+    source: 'turn-stop-gate',
+    blockEvent: 'turn_stop_blocked',
+    timeout: 30_000,
+    appendReplayEvent,
+    output,
+  });
+}
+
 function readMainTurnState(cwd) {
   const turnState = readTurnState(cwd);
   return turnState?.role === 'main' ? turnState : null;
@@ -197,8 +210,11 @@ function cmdStop() {
   const payload = readStdinJson();
   const cwd = payload.cwd || process.cwd();
   const turnState = readMainTurnState(cwd);
+  if (runTurnStopGate(payload)) {
+    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState);
+    return;
+  }
   const shouldProcess = shouldProcessCloseout(turnState);
-  clearRouteContext();
   if (shouldProcess && runRalphLoop(payload)) {
     consumeMainTurnState(cwd, turnState);
     notifyByLevel('warning', buildNotifyExtra(payload));
@@ -215,6 +231,7 @@ function cmdStop() {
     notifyByLevel('complete', buildNotifyExtra(payload), settings);
   }
   consumeMainTurnState(cwd, turnState);
+  clearRouteContext();
   emptySuppress();
 }
 
@@ -242,9 +259,14 @@ function cmdCodexNotify() {
 
   const cwd = data.cwd || process.cwd();
   const turnState = readMainTurnState(cwd);
+  if (runTurnStopGate(data)) {
+    if (turnState && turnState.kind !== 'complete') consumeMainTurnState(cwd, turnState);
+    return;
+  }
   if (!turnState) return;
   if (turnState.kind !== 'complete') {
     consumeMainTurnState(cwd, turnState);
+    clearRouteContext();
     return;
   }
 
@@ -262,6 +284,7 @@ function cmdCodexNotify() {
 
   notifyByLevel('complete', buildNotifyExtra(data), settings);
   consumeMainTurnState(cwd, turnState);
+  clearRouteContext();
 }
 
 const cmd = process.argv[2] || '';

package/scripts/turn-state.mjs

@@ -9,6 +9,16 @@ const TURN_STATE_PATH = join(homedir(), '.helloagents', 'runtime', 'turn-state.j
 const TURN_STATE_TTL_MS = 30 * 60 * 1000
 const VALID_KINDS = new Set(['complete', 'waiting', 'blocked', 'progress'])
 const VALID_ROLES = new Set(['main', 'subagent'])
+const VALID_REASON_CATEGORIES = new Set([
+  'ambiguity',
+  'missing-input',
+  'missing-file',
+  'missing-credential',
+  'unauthorized-side-effect',
+  'high-risk-confirmation',
+  'external-dependency',
+  'error',
+])
 
 function normalizePath(filePath = '') {
   return filePath ? normalize(resolve(filePath)) : ''
@@ -44,6 +54,10 @@ function getTurnStateKey(cwd = process.cwd()) {
 function normalizeTurnState(input = {}) {
   const kind = typeof input.kind === 'string' ? input.kind.trim().toLowerCase() : ''
   const role = typeof input.role === 'string' ? input.role.trim().toLowerCase() : 'main'
+  const reasonCategory = typeof input.reasonCategory === 'string'
+    ? input.reasonCategory.trim().toLowerCase()
+    : ''
+  const reason = typeof input.reason === 'string' ? input.reason.trim() : ''
 
   return {
     kind: VALID_KINDS.has(kind) ? kind : '',
@@ -51,6 +65,8 @@ function normalizeTurnState(input = {}) {
     phase: typeof input.phase === 'string' ? input.phase.trim().toLowerCase() : '',
     source: typeof input.source === 'string' && input.source.trim() ? input.source.trim() : 'manual',
     requiresDeliveryGate: Boolean(input.requiresDeliveryGate),
+    reasonCategory: VALID_REASON_CATEGORIES.has(reasonCategory) ? reasonCategory : '',
+    reason,
   }
 }
 
@@ -105,6 +121,12 @@ export function writeTurnState(cwd = process.cwd(), input = {}) {
   if (!key || !normalized.kind) {
     throw new Error('turn-state requires cwd and a valid kind')
   }
+  if (
+    (normalized.kind === 'waiting' || normalized.kind === 'blocked')
+    && (!normalized.reasonCategory || !normalized.reason)
+  ) {
+    throw new Error('turn-state waiting/blocked requires reasonCategory and reason')
+  }
 
   const store = readStore()
   const payload = {
@@ -123,6 +145,8 @@ export function writeTurnState(cwd = process.cwd(), input = {}) {
       role: normalized.role,
       phase: normalized.phase,
       requiresDeliveryGate: normalized.requiresDeliveryGate,
+      reasonCategory: normalized.reasonCategory,
+      reason: normalized.reason,
     },
   })
 

package/scripts/turn-stop-gate.mjs

@@ -0,0 +1,92 @@
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+
+import { getApplicableRouteContext } from './runtime-context.mjs'
+import { readTurnState } from './turn-state.mjs'
+import { getWorkflowRecommendation } from './workflow-state.mjs'
+
+const ENFORCED_COMMANDS = new Set(['auto', 'loop'])
+const ALLOWED_STOP_REASON_CATEGORIES = [
+  'ambiguity',
+  'missing-input',
+  'missing-file',
+  'missing-credential',
+  'unauthorized-side-effect',
+  'high-risk-confirmation',
+  'external-dependency',
+  'error',
+]
+
+function readStdinJson() {
+  try {
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+function buildWorkflowHint(cwd) {
+  const recommendation = getWorkflowRecommendation(cwd)
+  if (!recommendation) return ''
+  return [
+    `当前工作流：${recommendation.summary}`,
+    `建议路径：${recommendation.nextPath}`,
+    recommendation.guidance,
+  ].filter(Boolean).join('\n')
+}
+
+function buildBlockReason(routeContext, detail, cwd) {
+  const commandLabel = `~${routeContext.skillName}`
+  const workflowHint = buildWorkflowHint(cwd)
+  return [
+    `[HelloAGENTS Runtime] 显式 ${commandLabel} 本轮不应直接停下。`,
+    detail,
+    workflowHint,
+    '若无真实阻塞，请继续沿当前路径执行。',
+    `若确需停下，先调用 \`scripts/turn-state.mjs write\` 写结构化状态：\`kind=waiting\` 或 \`kind=blocked\`，并同时填写 \`reasonCategory\` 与 \`reason\`。`,
+    `允许的 \`reasonCategory\`：${ALLOWED_STOP_REASON_CATEGORIES.join(' | ')}。`,
+  ].filter(Boolean).join('\n')
+}
+
+function getMainTurnState(cwd) {
+  const turnState = readTurnState(cwd)
+  return turnState?.role === 'main' ? turnState : null
+}
+
+function validateTurnState(routeContext, turnState, cwd) {
+  if (!turnState) {
+    return buildBlockReason(routeContext, '缺少主代理 turn-state。', cwd)
+  }
+  if (turnState.kind === 'complete') {
+    return ''
+  }
+  if (turnState.kind === 'waiting' || turnState.kind === 'blocked') {
+    if (turnState.reasonCategory && turnState.reason) {
+      return ''
+    }
+    return buildBlockReason(
+      routeContext,
+      `当前 turn-state 为 \`${turnState.kind}\`，但缺少 \`reasonCategory\` 或 \`reason\`。`,
+      cwd,
+    )
+  }
+  return buildBlockReason(routeContext, `当前 turn-state 为 \`${turnState.kind}\`，不能作为本轮结束状态。`, cwd)
+}
+
+function main() {
+  const payload = readStdinJson()
+  const cwd = payload.cwd || process.cwd()
+  const routeContext = getApplicableRouteContext({ cwd })
+
+  if (!routeContext || !ENFORCED_COMMANDS.has(routeContext.skillName)) {
+    process.stdout.write(JSON.stringify({ decision: 'continue' }))
+    return
+  }
+
+  const reason = validateTurnState(routeContext, getMainTurnState(cwd), cwd)
+  process.stdout.write(JSON.stringify(reason ? { decision: 'block', reason } : { decision: 'continue' }))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}

package/skills/hello-verify/SKILL.md

@@ -76,7 +76,7 @@ description: 声称工作完成前、提交代码前、创建 PR 前、报告任
 5. 若当前存在方案包并准备最终收尾，优先调用 `scripts/closeout-state.mjs write` 写 `.helloagents/.ralph-closeout.json`，记录 `requirementsCoverage` 与 `deliveryChecklist` 两项结论；两项都必须包含 `status`（`PASS` / `BLOCKED`）和 `summary`
 6. 若当前方案包要求 `review-first`，必须先确认 `.helloagents/.ralph-review.json` 已通过 `scripts/review-state.mjs write` 写成最新结构化证据；不要把审查自然语言消息直接当成交付证据
 7. 若 `contract.json` 中 `ui.visualValidation.required=true`，必须确认 `.helloagents/.ralph-visual.json` 已通过 `scripts/visual-state.mjs write` 写成最新结构化证据；若没有视觉验收证据，不得把本轮视为 UI 可交付
-8. 准备以本轮最终收尾消息报告完成时，先调用 `scripts/turn-state.mjs write` 写 `kind=complete`、`role=main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，不要让运行时从自然语言消息里猜状态
+8. 准备以本轮最终收尾消息报告完成时，先调用 `scripts/turn-state.mjs write` 写 `kind=complete`、`role=main`；若因阻塞判定等待输入或因前置条件缺失而停下，写 `kind=waiting` 或 `kind=blocked`，并同时写 `reasonCategory` 与 `reason`，不要让运行时从自然语言消息里猜状态
 
 ## 需求追踪验证
 

package/skills/helloagents/SKILL.md

@@ -7,7 +7,7 @@ description: 每次对话开始时使用 — 建立质量驱动工作流，通
 
 主代理触发或读取任意 skill 时，只有在该条消息是本轮最终收尾消息时，才按当前已加载 bootstrap 规则包装 HelloAGENTS 外层输出格式；任何 skill 若在本轮明确要求输出停顿、确认或总结，对应消息也必须同时满足相同条件。
 子代理只豁免路由与收尾要求，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。所有流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都不得触发外层格式。
-主代理在本轮最终收尾前，如要报告“已完成 / 等待输入 / 本轮阻塞”，必须先调用 `scripts/turn-state.mjs write` 写机器可读的 turn-state；不要让运行时再从自然语言或图标反推状态。子代理不得写 turn-state。
+主代理在本轮最终收尾前，如要报告“已完成 / 等待输入 / 本轮阻塞”，必须先调用 `scripts/turn-state.mjs write` 写机器可读的 turn-state；不要让运行时再从自然语言或图标反推状态。若写 `kind=waiting` 或 `kind=blocked`，还必须同时写 `reasonCategory` 与 `reason`。子代理不得写 turn-state。
 
 `.helloagents/` 在所有 skill 中都统一按项目级存储路径理解：项目本地 `.helloagents/` 继续承担激活信号与 `.ralph-*.json` 等运行态文件；状态文件只使用 `state_path`（实际位于 `sessions/{branch}/{session-or-default}/STATE.md`）；若 `project_store_mode=repo-shared`，`context.md`、`guidelines.md`、`DESIGN.md`、`verify.yaml`、`modules/`、`plans/`、`archive/` 按当前上下文中已注入的“当前项目存储”/“项目知识/方案目录”解析，不要假定这些文件一定实际位于当前工作树中。