helloagents 3.0.32 → 3.0.33

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "helloagents",
-  "version": "3.0.32",
+  "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.32",
+  "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.32-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)
@@ -657,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
 
@@ -680,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.32-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)
@@ -661,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 验证和收尾前标记完成
 
@@ -684,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

package/bootstrap.md

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

package/gemini-extension.json

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

@@ -55,7 +55,7 @@ function buildAliasRouteNote(skillName) {
 }
 
 function buildDelegatedTaskHint() {
-  return '若当前输入明显来自上级代理、控制器或多代理协作上下文，且本次输出会交回上级代理继续汇总、决策或复述，而不是直接交付给最终用户，则按子代理处理：直接完成局部任务并返回结果、证据或阻塞项，不使用 HelloAGENTS 外层输出格式，不写 turn-state，不做面向最终用户的收尾。'
+  return '若当前任务由上级代理、控制器或宿主协作/委派机制创建，或本次输出会交回上级代理继续汇总、决策或复述，而不是直接交付给最终用户，则一律按子代理处理：直接完成局部任务并返回结果、证据或阻塞项；禁止输出 HelloAGENTS 外层格式、`🔄 下一步:`、turn-state 或面向最终用户的收尾。'
 }
 
 export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFile, host }) {

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-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

@@ -98,6 +98,59 @@ function getLastAssistantMessage(data = {}) {
   ).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
@@ -138,7 +191,7 @@ 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) {

package/skills/helloagents/SKILL.md

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