helloagents 3.0.31 → 3.0.33

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.31",
+  "version": "3.0.33",
   "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.33",
   "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.33-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 |
@@ -656,7 +657,7 @@ Codex is rules-file driven by default.
 - global mode installs the native local-plugin chain, but keeps `~/.helloagents/helloagents` as the single managed runtime source by linking plugin roots, plugin cache, and `~/.codex/helloagents` back to it
 - cleanup removes only the HelloAGENTS-managed hook trust entries and legacy managed notify residues, while keeping user-owned hook state untouched
 - Codex hooks only synchronize runtime state and enforce Stop gates; they do not inject HelloAGENTS rules or route text through hook output
-- Codex closeout de-duplicates Stop hooks and native `codex-notify`, so one turn does not notify twice
+- Codex closeout de-duplicates Stop hooks and native `codex-notify`, so one turn does not notify twice, and clientless delegated child-completion events stay silent when the managed Stop hook is active
 - `/goal` remains Codex-native. Enable it explicitly with `helloagents codex goals enable` when long-running plan execution is needed
 - Goal-aware commands resume from `tasks.md`, `contract.json`, and `state_path`; they do not create goals automatically or mark them complete before HelloAGENTS verification and closeout
 
@@ -679,7 +680,7 @@ The current suite covers:
 - `helloagents doctor`
 - project storage and `repo-shared` behavior
 - session-scoped `state_path`, runtime signals, and evidence
-- runtime injection, routing, guard, verification, visual evidence, delivery gates, closeout de-duplication, and successful-mode tracking after native install failures
+- runtime injection, routing, guard, verification, visual evidence, delivery gates, closeout de-duplication, sub-agent wrapper and notification suppression, 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.31-orange.svg)](./package.json)
+[![Version](https://img.shields.io/badge/version-3.0.33-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` | 拦截危险命令 |
@@ -660,7 +661,7 @@ Codex 默认走规则文件驱动。
 - 全局模式安装原生本地插件流程，但仍把 `~/.helloagents/helloagents` 作为唯一受管运行时源；插件根目录、插件缓存和 `~/.codex/helloagents` 都会回链到它
 - 清理时只删除 HelloAGENTS 自己写入的 hook trust 条目和旧式受管 notify 残留，不影响用户已有的 hook 状态
 - Codex hooks 只做静默运行态同步和 Stop 门禁，不通过 hook 注入 HelloAGENTS 规则或路由说明
-- Codex 收尾会对 Stop hook 和原生 `codex-notify` 去重，避免同一轮重复通知
+- Codex 收尾会对 Stop hook 和原生 `codex-notify` 去重，避免同一轮重复通知；受管 Stop hook 生效时，client 为空的委派子任务完成事件也会保持静默
 - `/goal` 保持 Codex 原生能力；需要长程执行时，用 `helloagents codex goals enable` 显式启用
 - 感知 goal 的命令从 `tasks.md`、`contract.json` 和 `state_path` 恢复；不会自动创建 goal，也不会在 HelloAGENTS 验证和收尾前标记完成
 
@@ -683,7 +684,7 @@ npm test
 - `helloagents doctor`
 - 项目存储和 `repo-shared`
 - 会话级 `state_path`、运行态信号和证据
-- 运行时注入、选路、Guard、验证、视觉证据、交付门控、收尾去重，以及原生安装失败后的模式记录
+- 运行时注入、选路、Guard、验证、视觉证据、交付门控、收尾去重、子代理外层格式与通知静默保护，以及原生安装失败后的模式记录
 - README 与 skill 契约一致性
 
 ## FAQ

package/bootstrap-lite.md

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

package/bootstrap.md

@@ -1,6 +1,6 @@
 # HelloAGENTS
 
-子代理执行子任务时，仅跳过输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行并返回结果。不使用 `~command`，不包装 HelloAGENTS 外层格式；其余规则持续生效。
+当当前任务属于上级代理分派的局部任务、由宿主协作/委派机制创建（包括 spawn_agent、worker / explorer、并行代理、Codex agent/delegate/wait 等）、当前输出会交回上级代理或控制器继续汇总/决策/复述，或当前回复并非直接面向最终用户的终局交付时，一律按子代理处理：仅跳过输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行并返回结果。只返回结果、证据或阻塞项；禁止输出 `【HelloAGENTS】` 外层格式、`🔄 下一步:`、面向最终用户的收尾或 turn-state；其余规则持续生效。
 
 ## 配置
 配置文件: ~/.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.33",
   "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.33",
   "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-payload.mjs

@@ -14,6 +14,14 @@ const PAYLOAD_KEY_ALIASES = {
   stop_hook_active: 'stopHookActive',
   'goal-id': 'goalId',
   goal_id: 'goalId',
+  is_subagent: 'isSubagent',
+  sub_agent: 'subagent',
+  parent_agent_id: 'parentAgentId',
+  parent_turn_id: 'parentTurnId',
+  delegated_by_agent_id: 'delegatedByAgentId',
+  agent_id: 'agentId',
+  agent_role: 'agentRole',
+  agent_kind: 'agentKind',
 }
 
 function assignAlias(target, source, sourceKey, targetKey) {

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/notify-ui.mjs

@@ -4,7 +4,7 @@
  */
 import { platform } from 'node:os';
 import { join } from 'node:path';
-import { existsSync } from 'node:fs';
+import { appendFileSync, existsSync } from 'node:fs';
 import { execFileSync, spawn } from 'node:child_process';
 
 const PLAT = platform();
@@ -19,6 +19,17 @@ const NOTIFY_MESSAGES = {
 
 const WIN_APPID = 'HelloAgents.Notification';
 const DISABLE_OS_NOTIFICATIONS = process.env.HELLOAGENTS_DISABLE_OS_NOTIFICATIONS === '1';
+const TEST_NOTIFY_LOG = String(process.env.HELLOAGENTS_NOTIFY_TEST_LOG || '').trim();
+
+function recordTestTransport(kind, event) {
+  if (!TEST_NOTIFY_LOG) return false;
+  try {
+    appendFileSync(TEST_NOTIFY_LOG, `${kind} ${String(event || '')}\n`, 'utf-8');
+    return true;
+  } catch {
+    return false;
+  }
+}
 
 function escapeToastText(value = '') {
   return String(value)
@@ -100,6 +111,7 @@ function runSoundHelper(pkgRoot, event, mode = 'background') {
 
 export function playSound(pkgRoot, event, options = {}) {
   if (DISABLE_OS_NOTIFICATIONS) return;
+  if (recordTestTransport('sound', event)) return;
   const wav = resolveWav(pkgRoot, event);
   if (!wav) { process.stderr.write('\x07'); return; }
   if (runSoundHelper(pkgRoot, event, options.mode === 'blocking' ? 'blocking' : 'background')) return;
@@ -152,6 +164,7 @@ $toast = [Windows.UI.Notifications.ToastNotification]::new($doc)
 
 export function desktopNotify(pkgRoot, event, extra) {
   if (DISABLE_OS_NOTIFICATIONS) return;
+  if (recordTestTransport('desktop', event)) return;
   const notification = buildDesktopNotificationContent(event, extra);
   try {
     if (PLAT === 'win32') {

package/scripts/notify.mjs

@@ -88,6 +88,59 @@ function getSettings() {
   return readSettings(CONFIG_FILE);
 }
 
+function hasTruthyAgentFlag(value) {
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value || '').trim().toLowerCase();
+  return ['1', 'true', 'yes', 'subagent'].includes(normalized);
+}
+
+function hasNonEmptyValue(value) {
+  return String(value || '').trim().length > 0;
+}
+
+function looksLikeCodexDelegatedTurn(payload = {}) {
+  if (!IS_CODEX || !payload || typeof payload !== 'object') return false;
+  const client = String(payload.client || '').trim();
+  const inputMessages = Array.isArray(payload.inputMessages) ? payload.inputMessages : [];
+  return !client && inputMessages.length > 1;
+}
+
+function isSubagentPayload(payload = {}) {
+  if (!payload || typeof payload !== 'object') return false;
+
+  if ([payload.isSubagent, payload.subagent].some(hasTruthyAgentFlag)) {
+    return true;
+  }
+
+  const roleLike = [
+    payload.role,
+    payload.agentRole,
+    payload.agent_role,
+    payload.agentKind,
+    payload.agent_kind,
+    payload.kind,
+  ]
+    .map((value) => String(value || '').trim().toLowerCase())
+    .filter(Boolean);
+
+  if (roleLike.some((value) => ['subagent', 'delegate', 'delegated', 'worker', 'explorer'].includes(value))) {
+    return true;
+  }
+
+  if ([
+    payload.parentAgentId,
+    payload.parent_agent_id,
+    payload.parentTurnId,
+    payload.parent_turn_id,
+    payload.delegatedByAgentId,
+    payload.delegated_by_agent_id,
+  ].some(hasNonEmptyValue)) {
+    return true;
+  }
+
+  return looksLikeCodexDelegatedTurn(payload);
+}
+
 function shouldRunRalphLoop(cwd, turnState, payload = {}) {
   if (!turnState || turnState.kind !== 'complete') return false;
   if (turnState.requiresDeliveryGate) return true;
@@ -230,13 +283,28 @@ async function runRalphLoop(payload, { turnState } = {}) {
     blockEvent: 'verify_gate_blocked',
     exportName: 'evaluateRalphLoop',
     evaluateArgs: [payload, {
-      isSubagent: false,
+      isSubagent: isSubagentPayload(payload),
       isGemini: IS_GEMINI,
       hookEventName: HOST === 'codex' ? 'Stop' : (IS_GEMINI ? 'SessionEnd' : 'Stop'),
     }],
   });
 }
 
+async function runCodexSubagentGate(payload) {
+  if (!IS_CODEX || !isSubagentPayload(payload)) return false;
+  return await runInlineGate({
+    payload,
+    source: 'ralph-loop',
+    blockEvent: 'verify_gate_blocked',
+    exportName: 'evaluateRalphLoop',
+    evaluateArgs: [payload, {
+      isSubagent: true,
+      isGemini: false,
+      hookEventName: 'Stop',
+    }],
+  });
+}
+
 async function runDeliveryGate(payload) {
   return await runInlineGate({
     payload,
@@ -447,6 +515,11 @@ async function cmdStop() {
   const payload = readPayloadFromStdin();
   const cwd = payload.cwd || process.cwd();
   const turnPayload = attachTurnSession(payload, cwd);
+  if (await runCodexSubagentGate(turnPayload)) return;
+  if (IS_CODEX && isSubagentPayload(turnPayload)) {
+    emptySuppress();
+    return;
+  }
   const turnState = readMainTurnState(cwd, turnPayload);
   const managedCodexStopHook = IS_CODEX && hasManagedCodexStopHook();
   const skipCompleteNotify = managedCodexStopHook && hasCodexQuickNotifyEvidence(cwd, {
@@ -504,7 +577,10 @@ async function cmdCodexNotify() {
     return;
   }
   if (type !== 'agent-turn-complete') return;
-  if (hasManagedCodexStopHook()) {
+  const managedCodexStopHook = hasManagedCodexStopHook();
+  if (managedCodexStopHook && !String(turnPayload.client || '').trim()) return;
+  if (isSubagentPayload(turnPayload)) return;
+  if (managedCodexStopHook) {
     const turnState = readMainTurnState(cwd, turnPayload);
     if (shouldEmitManagedCodexCompleteNotify(cwd, turnState, turnPayload)) {
       notifyByLevel('complete', buildNotifyExtra(data), getSettings(), { mode: 'blocking' });

package/scripts/ralph-loop.mjs

@@ -89,6 +89,83 @@ function runVerify(commands, cwd) {
   return failures;
 }
 
+function getLastAssistantMessage(data = {}) {
+  return String(
+    data.lastAssistantMessage
+    || data.last_assistant_message
+    || data['last-assistant-message']
+    || '',
+  ).trim();
+}
+
+function hasTruthyAgentFlag(value) {
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value || '').trim().toLowerCase();
+  return ['1', 'true', 'yes', 'subagent'].includes(normalized);
+}
+
+function hasNonEmptyValue(value) {
+  return String(value || '').trim().length > 0;
+}
+
+function looksLikeCodexDelegatedTurn(data = {}) {
+  if (!data || typeof data !== 'object') return false;
+  const client = String(data.client || '').trim();
+  const inputMessages = Array.isArray(data.inputMessages) ? data.inputMessages : [];
+  return !client && inputMessages.length > 1;
+}
+
+function inferSubagentFromPayload(data = {}) {
+  if (!data || typeof data !== 'object') return false;
+
+  if ([data.isSubagent, data.subagent].some(hasTruthyAgentFlag)) {
+    return true;
+  }
+
+  const roleLike = [
+    data.role,
+    data.agentRole,
+    data.agent_role,
+    data.agentKind,
+    data.agent_kind,
+    data.kind,
+  ]
+    .map((value) => String(value || '').trim().toLowerCase())
+    .filter(Boolean);
+
+  if (roleLike.some((value) => ['subagent', 'delegate', 'delegated', 'worker', 'explorer'].includes(value))) {
+    return true;
+  }
+
+  if ([
+    data.parentAgentId,
+    data.parent_agent_id,
+    data.parentTurnId,
+    data.parent_turn_id,
+    data.delegatedByAgentId,
+    data.delegated_by_agent_id,
+  ].some(hasNonEmptyValue)) {
+    return true;
+  }
+
+  return looksLikeCodexDelegatedTurn(data);
+}
+
+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 =>
@@ -114,9 +191,20 @@ export function evaluateRalphLoop(data = {}, runtime = {}) {
 
   const cwd = data.cwd || process.cwd();
   const runtimeOptions = { payload: data };
-  const isSubagent = runtime.isSubagent ?? IS_SUBAGENT;
+  const isSubagent = runtime.isSubagent === true || inferSubagentFromPayload(data) || 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】` 或第二个 `🔄 下一步`。
+若当前输出会交回上级代理、控制器或其他代理继续汇总、决策、复述或等待后续动作，或当前任务由宿主协作/委派机制创建（包括 spawn_agent、worker / explorer、并行代理、Codex agent/delegate/wait 等），则一律按子代理处理：只豁免输出格式、交互确认与停顿、统一执行流程、任务分层、完成判定、命令路由和流程状态，直接执行任务；安全、质量、验证和失败处理规则仍持续生效。子代理只返回结果、证据或阻塞项；不得包装 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。
 普通问答、解释、分析、改写、邮件回复和其他一次性交付虽然不进入完整实现、验证或收尾流程，但仍属于交付：默认只交付与当前请求直接对应的一版最终结果；请求已满足时直接结束，不主动追加无执行价值的延伸、派生版本、不同写法、第二版或邀约式收尾，除非用户明确要求。