helloagents 3.0.31 → 3.0.32

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.31",
+  "version": "3.0.32",
   "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.31",
+  "version": "3.0.32",
   "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.31-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.32-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)
@@ -211,6 +211,7 @@ Runtime evidence files include:
 - `.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. Final closeout also enforces a single HelloAGENTS wrapper, so one reply does not emit duplicate closeout headers.
+That wrapper is now reserved for direct final-user delivery only. Intermediate reports, delegated task results, and sub-agent replies stay natural, and sub-agent stop hooks reject wrapped closeout replies.
 
 ### 7) Safer install, update, cleanup, and diagnostics
 
@@ -612,7 +613,7 @@ Default shape:
 | Key | Default | Meaning |
 |-----|---------|---------|
 | `output_language` | `""` | follow the user language unless set |
-| `output_format` | `true` | main-agent final closeout must use the HelloAGENTS layout; intermediate and sub-agent output stays natural |
+| `output_format` | `true` | direct final-user closeout from the main agent uses the HelloAGENTS layout; intermediate, delegated, and sub-agent output stays natural |
 | `notify_level` | `0` | `0` off, `1` desktop, `2` sound, `3` both |
 | `ralph_loop_enabled` | `true` | run verification for explicit `~verify` / `~loop` or required closeout gates |
 | `guard_enabled` | `true` | block dangerous commands |

package/README_CN.md

@@ -8,7 +8,7 @@
 
 **面向 AI 编码 CLI 的工作流层：技能、知识库、交付检查、更安全的配置写入，以及可恢复的执行流程。**
 
-[![Version](https://img.shields.io/badge/version-3.0.31-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.32-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)
@@ -211,6 +211,7 @@ HelloAGENTS 不把“命令通过”和“任务完成”简单画等号。交
 - `.helloagents/sessions/<workspace>/<session>/artifacts/loop-results.tsv`
 
 交付门控、守卫和循环提示使用执行性表述，例如处理路径、收尾动作和视觉验收动作。阻塞流程会说明下一步要做什么，而不是把可执行步骤写成泛化建议。最终回复还会强制只保留一个 HelloAGENTS 外层块，避免同一条回复重复输出完成标题。
+这个外层格式现在只保留给直接面向最终用户的终局交付。中间汇报、委派任务结果和子代理回复都保持自然输出；子代理结束钩子也会拦截错误的外层收尾格式。
 
 ### 7）更安全的安装、更新、清理和诊断
 
@@ -616,7 +617,7 @@ UI 任务遵循以下优先级：
 | 键 | 默认值 | 含义 |
 |----|--------|------|
 | `output_language` | `""` | 默认跟随用户语言 |
-| `output_format` | `true` | 主代理最终回复必须使用 HelloAGENTS 格式；中间输出和子代理输出保持自然 |
+| `output_format` | `true` | 仅主代理直接面向最终用户的终局交付使用 HelloAGENTS 格式；中间输出、委派结果和子代理输出保持自然 |
 | `notify_level` | `0` | `0` 关闭，`1` 桌面通知，`2` 声音，`3` 两者 |
 | `ralph_loop_enabled` | `true` | 显式 `~verify` / `~loop` 或收尾要求时运行验证 |
 | `guard_enabled` | `true` | 拦截危险命令 |

package/bootstrap-lite.md

@@ -1,6 +1,6 @@
 # HelloAGENTS
 
-子代理执行子任务时，仅跳过输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行并返回结果。不使用 `~command`，不包装 HelloAGENTS 外层格式；其余规则持续生效。
+当当前任务属于上级代理分派的局部任务、当前输出会交回上级代理或控制器继续汇总/决策/复述，或当前回复并非直接面向最终用户的终局交付时，按子代理处理：仅跳过输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行并返回结果。不使用 `~command`，不包装 HelloAGENTS 外层格式；其余规则持续生效。
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
@@ -112,8 +112,8 @@
 
 排除条件：
 - 当 `output_format` 为 `false` 时，所有回复保持自然输出，不得使用输出格式。
-- 以下内容一律视为中间输出，必须自然输出，不得使用输出格式：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报，以及任何发出后仍会继续调用工具或继续执行的回复。
-- 子代理在任何场景下都不得使用输出格式。
+- 以下内容一律视为中间输出，必须自然输出，不得使用输出格式：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报，以及任何发出后仍会继续调用工具、继续执行，或会交回上级代理/控制器继续消费的回复。
+- 凡是不直接面向最终用户终局交付的回复，包括子代理、协作汇报和会交回上级代理继续处理的结果，都不得使用输出格式。
 
 输出格式：
 

package/bootstrap.md

@@ -1,6 +1,6 @@
 # HelloAGENTS
 
-子代理执行子任务时，仅跳过输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行并返回结果。不使用 `~command`，不包装 HelloAGENTS 外层格式；其余规则持续生效。
+当当前任务属于上级代理分派的局部任务、当前输出会交回上级代理或控制器继续汇总/决策/复述，或当前回复并非直接面向最终用户的终局交付时，按子代理处理：仅跳过输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行并返回结果。不使用 `~command`，不包装 HelloAGENTS 外层格式；其余规则持续生效。
 
 ## 配置
 配置文件: ~/.helloagents/helloagents.json
@@ -112,8 +112,8 @@
 
 排除条件：
 - 当 `output_format` 为 `false` 时，所有回复保持自然输出，不得使用输出格式。
-- 以下内容一律视为中间输出，必须自然输出，不得使用输出格式：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报，以及任何发出后仍会继续调用工具或继续执行的回复。
-- 子代理在任何场景下都不得使用输出格式。
+- 以下内容一律视为中间输出，必须自然输出，不得使用输出格式：流式输出阶段的可见文本、思考/进度说明、工具调用前的说明、工具执行中的状态汇报，以及任何发出后仍会继续调用工具、继续执行，或会交回上级代理/控制器继续消费的回复。
+- 凡是不直接面向最终用户终局交付的回复，包括子代理、协作汇报和会交回上级代理继续处理的结果，都不得使用输出格式。
 
 输出格式：
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.31",
+  "version": "3.0.32",
   "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.31",
+  "version": "3.0.32",
   "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-context.mjs

@@ -54,6 +54,10 @@ function buildAliasRouteNote(skillName) {
   return '';
 }
 
+function buildDelegatedTaskHint() {
+  return '若当前输入明显来自上级代理、控制器或多代理协作上下文，且本次输出会交回上级代理继续汇总、决策或复述，而不是直接交付给最终用户，则按子代理处理：直接完成局部任务并返回结果、证据或阻塞项，不使用 HelloAGENTS 外层输出格式，不写 turn-state，不做面向最终用户的收尾。'
+}
+
 export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFile, host }) {
   const summaryParts = [];
   summaryParts.push('## HelloAGENTS 压缩摘要');
@@ -148,7 +152,7 @@ export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot
   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}`;
+  return `用户使用了 ~${skillName} 命令。当前命令技能文件已解析为：${skillPath}。请直接读取这个 SKILL.md；不要再探测其他 helloagents 路径。 ${buildDelegatedTaskHint()}${aliasNote ? ` ${aliasNote}` : ''}${projectStorageHint ? ` ${projectStorageHint}` : ''}${commandHint ? ` ${commandHint}` : ''}${capabilityHint ? ` ${capabilityHint}` : ''}${extraRules}`;
 }
 
 export function buildSemanticRouteInstruction(cwd, payload = {}) {
@@ -159,6 +163,7 @@ export function buildSemanticRouteInstruction(cwd, payload = {}) {
   return [
     '当前消息未使用 ~command。',
     '请根据用户请求的真实意图选路，不依赖关键词表。',
+    buildDelegatedTaskHint(),
     'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆操作。',
     '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
     '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',

package/scripts/notify-events.mjs

@@ -4,10 +4,6 @@ export function shouldIgnoreCodexNotifyClient(client) {
   return normalized !== 'codex' && !normalized.startsWith('codex-');
 }
 
-export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
-  return outputFormatEnabled && !lastMsg.includes('【HelloAGENTS】');
-}
-
 export function resolveNotifyHost(argv = []) {
   const args = Array.from(argv, (value) => String(value || ''));
   const command = args[2] || args[0] || '';

package/scripts/notify-route.mjs

@@ -17,7 +17,7 @@ export function resolveBootstrapFile(cwd, settings = {}, host = '') {
 }
 
 function shouldBypassRoute(prompt) {
-  return !prompt || /^\[子代理任务\]/.test(prompt)
+  return !prompt
 }
 
 function buildHelpExtraRules(skillName) {

package/scripts/ralph-loop.mjs

@@ -89,6 +89,30 @@ function runVerify(commands, cwd) {
   return failures;
 }
 
+function getLastAssistantMessage(data = {}) {
+  return String(
+    data.lastAssistantMessage
+    || data.last_assistant_message
+    || data['last-assistant-message']
+    || '',
+  ).trim();
+}
+
+function hasHelloagentsWrapper(message = '') {
+  if (!message.includes('【HelloAGENTS】')) return false;
+  const firstNonEmptyLine = message
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return /^[💡⚡🔵✅❓⚠️❌]【HelloAGENTS】- /.test(firstNonEmptyLine || '') || message.includes('【HelloAGENTS】');
+}
+
+function validateSubagentOutput(data = {}) {
+  const message = getLastAssistantMessage(data);
+  if (!message || !hasHelloagentsWrapper(message)) return '';
+  return '[HelloAGENTS Runtime] 子代理输出不应使用 HelloAGENTS 外层格式。当前回复不是直接面向最终用户的终局交付，请改为自然输出，只返回结果、证据或阻塞项。';
+}
+
 /** Filter commands to fast checks only for subagent mode. Returns null if no fast commands found. */
 function filterSubagentCommands(commands) {
   const fast = commands.filter(cmd =>
@@ -117,6 +141,17 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
   const isSubagent = runtime.isSubagent ?? IS_SUBAGENT;
   const hookEventName = runtime.hookEventName || HOOK_EVENT;
 
+  if (isSubagent) {
+    const formatReason = validateSubagentOutput(data);
+    if (formatReason) {
+      return {
+        decision: 'block',
+        reason: formatReason,
+        suppressOutput: true,
+      };
+    }
+  }
+
   let commands = detectCommands(cwd);
   if (!commands?.length) {
     return { suppressOutput: true };

package/skills/hello-subagent/SKILL.md

@@ -12,7 +12,7 @@ description: 使用子代理执行任务、并行开发、分派工作时使用
 ## 派遣规范
 - 每个子代理获得：tasks.md 中的对应任务 + 方案包中的相关约束（~plan: requirements.md + plan.md；~prd: prd/ 中的相关维度文件 + decisions.md）+ 验证命令；涉及 UI 时，再附 `.helloagents/DESIGN.md`（按当前项目存储模式解析）或其中相关片段
 - 新鲜上下文：不继承主会话历史，避免上下文污染
-- 提示开头标记 [子代理任务]，让子代理跳过 HelloAGENTS 外层流程
+- 明确这是局部委派任务：当前输出会交回上级代理继续汇总、决策或复述，而不是直接交付给最终用户；因此只返回结果、证据或阻塞项，不包装 HelloAGENTS 外层格式，也不写 turn-state
 - 单一职责：一个子代理只做一件事
 - 只提取子代理需要的上下文，不把整个方案包全部塞给子代理
 

package/skills/helloagents/SKILL.md

@@ -5,8 +5,8 @@ description: 按任务类型适用 — 建立质量驱动工作流，通过技
 
 # HelloAGENTS
 
-主代理触发或读取任意 skill 时，只有当前对话的最终回复才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行的文本，都保持自然输出。最终回复中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。同一条最终回复只包装一次；若需要分段，在同一个外层块内展开，不在正文里再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
-子代理只豁免输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。
+主代理触发或读取任意 skill 时，只有直接面向最终用户、且当前对话已经结束的终局交付，才按通用输出格式包装；流式内容、进度或状态汇报、中间文本，以及任何仍将继续执行或会交回上级代理继续消费的文本，都保持自然输出。最终回复中的 `🔄 下一步` 写真实动作，不写当前状态；等待用户授权时使用等待输入态收尾，已获授权且可继续执行时不得收尾。同一条最终回复只包装一次；若需要分段，在同一个外层块内展开，不在正文里再次输出 `【HelloAGENTS】` 或第二个 `🔄 下一步`。
+若当前输出会交回上级代理、控制器或其他代理继续汇总、决策、复述或等待后续动作，则按子代理处理：只豁免输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行任务；安全、质量、验证和失败处理规则仍持续生效，且不得包装 HelloAGENTS 外层输出格式。
 只有运行时必须识别当前对话“完成 / 等待输入 / 阻塞”时，主代理才写 turn-state；普通问候、普通问答、T0 只读分析和一次性解释不调用。必须调用场景：显式 `~auto` / `~loop`、非只读任务完成验证并进入收尾、需要让运行时识别当前对话已完成、等待输入或已阻塞时、已进入项目连续流程或方案包闭环。首选 `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。
 普通问答、解释、分析、改写、邮件回复和其他一次性交付虽然不进入完整实现、验证或收尾流程，但仍属于交付：默认只交付与当前请求直接对应的一版最终结果；请求已满足时直接结束，不主动追加无执行价值的延伸、派生版本、不同写法、第二版或邀约式收尾，除非用户明确要求。