helloagents 3.0.8-beta.1 → 3.0.10-beta.1

package/scripts/cli-codex-config.mjs

@@ -27,7 +27,13 @@ export function isManagedCodexModelInstruction(line = '') {
 }
 
 export function isManagedCodexNotify(line = '') {
-  return line.includes('codex-notify')
+  const value = String(line || '').replace(/\\/g, '/')
+  return value.includes(CODEX_MANAGED_TOML_COMMENT)
+    || (
+      value.includes('codex-notify')
+      && value.includes('/scripts/notify.mjs')
+      && /(^|[/\\])helloagents([/\\]|-|$)|[/\\]plugins[/\\]helloagents[/\\]/i.test(value)
+    )
 }
 
 export function isManagedCodexBackupInstruction(line = '') {
@@ -51,7 +57,7 @@ function formatManagedCodexNotifyValue(notifyScriptPath) {
 }
 
 function formatManagedCodexNotifyLine(notifyScriptPath) {
-  return `notify = ${formatManagedCodexNotifyValue(notifyScriptPath)}`
+  return `notify = ${formatManagedCodexNotifyValue(notifyScriptPath)} ${CODEX_MANAGED_TOML_COMMENT}`
 }
 
 function removeTopLevelLinesBeingReplaced(toml, lines) {

package/scripts/cli-codex.mjs

@@ -20,6 +20,7 @@ import {
 } from './cli-codex-config.mjs';
 import {
   readTopLevelTomlLine,
+  readTopLevelTomlBlock,
   readTomlKeyInSection,
   removeTomlKeyInSection,
   ensureTomlKeyInSection,
@@ -98,7 +99,8 @@ function removeCodexMarketplaceEntry(marketplaceFile) {
   }
   if (!removedHelloagents) return false;
   if (!nextPlugins.length) {
-    removeIfExists(marketplaceFile);
+    marketplace.plugins = [];
+    safeWrite(marketplaceFile, JSON.stringify(marketplace, null, 2) + '\n');
     return true;
   }
   marketplace.plugins = nextPlugins;
@@ -130,7 +132,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
   let toml = safeRead(configPath) || '';
 
   const currentModelInstructions = readTopLevelTomlLine(toml, 'model_instructions_file');
-  const currentNotify = readTopLevelTomlLine(toml, 'notify');
+  const currentNotify = readTopLevelTomlBlock(toml, 'notify');
   const currentCodexHooks = readTomlKeyInSection(toml, '[features]', 'codex_hooks');
 
   const shouldRestoreModelInstructions = isManagedCodexModelInstruction(currentModelInstructions);
@@ -153,7 +155,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
   }
 
   const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
-  const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
+  const backupNotify = readTopLevelTomlBlock(backupToml, 'notify');
   const backupCodexHooks = readTomlKeyInSection(backupToml, '[features]', 'codex_hooks');
 
   toml = restoreCodexTopLevelConfig(toml, {
@@ -248,6 +250,7 @@ export function installCodexGlobal(home, pkgRoot) {
 
   copyEntries(pkgRoot, pluginRoot, CODEX_RUNTIME_ENTRIES);
   copyEntries(pkgRoot, installedPluginRoot, CODEX_RUNTIME_ENTRIES);
+  createLink(pluginRoot, join(codexDir, 'helloagents'));
   writeCodexRuntimeCarrier(
     join(pluginRoot, CODEX_RUNTIME_CARRIER),
     join(pluginRoot, 'bootstrap.md'),
@@ -286,6 +289,7 @@ export function uninstallCodexGlobal(home) {
   removeIfExists(pluginCacheRoot);
   removeCodexMarketplaceEntry(marketplaceFile);
   removeMarkedContent(join(codexDir, 'AGENTS.md'));
+  removeLink(join(codexDir, 'helloagents'));
 
   const toml = cleanupCodexManagedConfig(configPath, { removePluginConfig: true });
   if (toml.trim()) safeWrite(configPath, toml);

package/scripts/cli-doctor.mjs

@@ -230,6 +230,7 @@ function appendCodexStandbyIssues(issues, checks) {
 function appendCodexGlobalIssues(issues, checks, pluginVersion, cacheVersion) {
   if (!checks.carrierMarker) issues.push(buildDoctorIssue('global-home-carrier-missing', 'global `~/.codex/AGENTS.md` 缺少 HelloAGENTS 规则内容', 'Global `~/.codex/AGENTS.md` is missing the HelloAGENTS carrier'))
   if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('global-home-carrier-drift', 'global `~/.codex/AGENTS.md` 与当前 bootstrap.md 不一致', 'Global `~/.codex/AGENTS.md` differs from the current bootstrap.md'))
+  if (!checks.globalHomeLink) issues.push(buildDoctorIssue('global-read-root-link-missing', 'global `~/.codex/helloagents` 链接缺失或未指向当前插件根目录', 'Global `~/.codex/helloagents` link is missing or does not point to the current plugin root'))
   if (!checks.pluginRoot) issues.push(buildDoctorIssue('global-plugin-root-missing', 'global 插件根目录缺失', 'Global plugin root is missing'))
   if (!checks.pluginCache) issues.push(buildDoctorIssue('global-plugin-cache-missing', 'global 插件缓存目录缺失', 'Global plugin cache directory is missing'))
   if (checks.pluginRoot && !checks.pluginCarrierMatch) issues.push(buildDoctorIssue('global-plugin-carrier-drift', 'global 插件根目录中的 AGENTS.md 与当前 bootstrap.md 不一致', 'Global plugin AGENTS.md differs from the current bootstrap.md'))
@@ -258,6 +259,9 @@ function inspectCodexDoctor(settings) {
   const marketplace = safeJson(join(runtime.home, '.agents', 'plugins', 'marketplace.json')) || {}
   const pluginVersion = safeJson(join(pluginRoot, 'package.json'))?.version || ''
   const cacheVersion = safeJson(join(pluginCacheRoot, 'package.json'))?.version || ''
+  const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
+  const pkgRootTarget = safeRealTarget(runtime.pkgRoot) || normalizePath(runtime.pkgRoot)
+  const pluginRootTarget = safeRealTarget(pluginRoot) || normalizePath(pluginRoot)
   const standbyNotifyPath = normalizePath(join(runtime.pkgRoot, 'scripts', 'notify.mjs'))
   const globalNotifyPath = normalizePath(join(pluginRoot, 'scripts', 'notify.mjs'))
   const managedHomeCarrierPath = normalizePath(join(codexDir, 'AGENTS.md'))
@@ -268,7 +272,8 @@ function inspectCodexDoctor(settings) {
   const checks = {
     carrierMarker: (safeRead(join(codexDir, 'AGENTS.md')) || '').includes('HELLOAGENTS_START'),
     carrierContentMatch: extractManagedCarrierContent(join(codexDir, 'AGENTS.md')) === readBootstrapContent(expectedHomeCarrier),
-    homeLink: safeRealTarget(join(codexDir, 'helloagents')) === runtime.pkgRoot,
+    homeLink: homeLinkTarget === pkgRootTarget,
+    globalHomeLink: homeLinkTarget === pluginRootTarget,
     modelInstructionsFile: !!modelInstructionsLine,
     modelInstructionsPathMatch: !!modelInstructionsLine
       && normalizePath(modelInstructionsLine).includes(`"${managedHomeCarrierPath}"`),

package/scripts/cli-host-detect.mjs

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs'
+import { existsSync, realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
 import {
@@ -27,6 +27,18 @@ function hasHelloagentsSettings(filePath) {
   return JSON.stringify(safeJson(filePath) || {}).includes('helloagents')
 }
 
+function normalizePath(value = '') {
+  return String(value || '').replace(/\\/g, '/').toLowerCase()
+}
+
+function safeRealTarget(linkPath) {
+  try {
+    return normalizePath(realpathSync(linkPath))
+  } catch {
+    return ''
+  }
+}
+
 function detectClaudeMode(home) {
   const claudeDir = join(home, '.claude')
   if (
@@ -53,19 +65,23 @@ function detectGeminiMode(home) {
 
 function detectCodexMode(home) {
   const codexDir = join(home, '.codex')
+  const codexHomeLink = join(codexDir, 'helloagents')
   const codexConfig = safeRead(join(codexDir, 'config.toml')) || ''
   const marketplace = safeRead(join(home, '.agents', 'plugins', 'marketplace.json')) || ''
+  const globalPluginRoot = normalizePath(join(home, 'plugins', CODEX_PLUGIN_NAME))
+  const codexHomeLinkTarget = safeRealTarget(codexHomeLink)
   if (
     existsSync(join(home, 'plugins', CODEX_PLUGIN_NAME))
     || existsSync(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME))
     || marketplace.includes(`"name": "${CODEX_PLUGIN_NAME}"`)
     || codexConfig.includes(CODEX_PLUGIN_KEY)
     || codexConfig.includes(`/plugins/${CODEX_PLUGIN_NAME}/scripts/notify.mjs`)
+    || codexHomeLinkTarget === globalPluginRoot
   ) {
     return 'global'
   }
   if (
-    existsSync(join(codexDir, 'helloagents'))
+    (existsSync(codexHomeLink) && codexHomeLinkTarget !== globalPluginRoot)
     || hasHelloagentsMarker(join(codexDir, 'AGENTS.md'))
     || codexConfig.includes('codex-notify')
     || codexConfig.includes('HelloAGENTS')

package/scripts/cli-lifecycle.mjs

@@ -181,6 +181,17 @@ function runAllHostsLifecycle(action, explicitMode) {
   }
 
   const settings = readSettings(true)
+  if (action === 'update' && !explicitMode) {
+    for (const host of HOSTS) {
+      const mode = resolveHostMode(host, '', settings)
+      const result = runHostLifecycle(runtime, action, host, mode)
+      if (!result.skipped) setTrackedHostMode(settings, host, mode)
+    }
+    writeSettings(settings)
+    runtime.printInstallMsg(settings.install_mode || DEFAULTS.install_mode, 'refresh')
+    return
+  }
+
   const mode = resolveInstallMode(explicitMode, settings)
   if (explicitMode) settings.install_mode = explicitMode
   installAllHosts(runtime, mode)

package/scripts/cli-messages.mjs

@@ -44,8 +44,8 @@ function renderInstallMessage(context, mode, state) {
     }
     return msg(
       refresh
-        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件链路已重装并同步最新文件。'
-        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动走原生本地插件链路。',
+        ? '  global 模式已刷新。\n  Claude Code / Gemini 请保持插件已安装；Codex 原生本地插件已重装并同步最新文件。'
+        : '  所有项目将自动启用完整 HelloAGENTS 规则。\n  Claude Code / Gemini 请手动安装插件；Codex 已自动安装原生本地插件。',
       refresh
         ? '  Global mode refreshed.\n  Keep Claude Code / Gemini plugins installed; Codex native local-plugin files were reinstalled and synced.'
         : '  All projects will use full HelloAGENTS rules.\n  Install Claude Code / Gemini plugins manually; Codex now uses the native local-plugin path automatically.',
@@ -92,7 +92,7 @@ ${msg('单 CLI 管理', 'Scoped CLI management')}:
 ${msg('诊断', 'Diagnostics')}:
   helloagents doctor
   helloagents doctor codex --json
-  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件链路、受管 model_instructions_file 指向与版本漂移', 'Checks carriers, links, hooks, config injections, the Codex plugin chain, managed model_instructions_file targeting, and version drift')}
+  ${msg('检查 carrier、链接、hooks、配置注入、Codex 插件安装、受管 model_instructions_file 指向与版本漂移', 'Checks carriers, links, hooks, config injections, Codex plugin installation, managed model_instructions_file targeting, and version drift')}
 
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}

package/scripts/cli-toml-values.mjs

@@ -0,0 +1,25 @@
+export function getTomlArrayDepthDelta(text) {
+  let depth = 0
+  let quoted = false
+  let escaped = false
+
+  for (const char of String(text || '')) {
+    if (escaped) {
+      escaped = false
+      continue
+    }
+    if (char === '\\' && quoted) {
+      escaped = true
+      continue
+    }
+    if (char === '"') {
+      quoted = !quoted
+      continue
+    }
+    if (quoted) continue
+    if (char === '[') depth += 1
+    if (char === ']') depth -= 1
+  }
+
+  return depth
+}

package/scripts/cli-toml.mjs

@@ -3,6 +3,8 @@
  * Targets the small subset of TOML structures used by Codex CLI config.
  */
 
+import { getTomlArrayDepthDelta } from './cli-toml-values.mjs'
+
 export function isTomlTableHeader(line) {
   const trimmed = String(line || '').trim();
   return trimmed.startsWith('[') && trimmed.endsWith(']');
@@ -62,6 +64,19 @@ function findTopLevelTomlBlock(text, key) {
     const closeIndex = normalized.indexOf('"""', openIndex + 3);
     end = closeIndex >= 0 ? closeIndex + 3 : normalized.length;
   }
+  if (value.startsWith('[')) {
+    let depth = getTomlArrayDepthDelta(firstLine.slice(firstLine.indexOf('=') + 1));
+    let lineStart = firstLineEnd + (normalized[firstLineEnd] === '\n' ? 1 : 0);
+
+    while (depth > 0 && lineStart < normalized.length) {
+      const lineEndIndex = normalized.indexOf('\n', lineStart);
+      const nextLineEnd = lineEndIndex >= 0 ? lineEndIndex : normalized.length;
+      const nextLine = normalized.slice(lineStart, nextLineEnd);
+      depth += getTomlArrayDepthDelta(nextLine);
+      end = nextLineEnd;
+      lineStart = nextLineEnd + 1;
+    }
+  }
 
   while (end < normalized.length && normalized[end] === '\n') {
     end += 1;

package/scripts/delivery-gate.mjs

@@ -205,10 +205,11 @@ function main() {
     data = JSON.parse(readFileSync(0, 'utf-8'))
   } catch {}
   const cwd = data.cwd || process.cwd()
-  const snapshot = getWorkflowSnapshot(cwd)
-  const recommendation = getWorkflowRecommendation(cwd)
+  const workflowOptions = { payload: data }
+  const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
+  const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
   const verificationStatus = getVerifyEvidenceStatus(cwd)
-  const deliveryAction = getDeliveryAction(cwd)
+  const deliveryAction = getDeliveryAction(cwd, workflowOptions)
   const gatePlans = selectGatePlans(snapshot)
   const reviewStatus = getReviewEvidenceStatus(cwd, {
     required: deliveryAction?.phase === 'verify' && deliveryAction?.mode === 'review-first',
@@ -248,7 +249,7 @@ function main() {
 
   process.stdout.write(JSON.stringify({
     decision: 'block',
-    reason: buildBlockReason(issues, recommendation, buildDeliveryGateHint(cwd)),
+    reason: buildBlockReason(issues, recommendation, buildDeliveryGateHint(cwd, workflowOptions)),
     suppressOutput: true,
   }))
 }

package/scripts/guard.mjs

@@ -62,15 +62,16 @@ function emitGuardEvent(cwd, event, source, reason, details = {}) {
   })
 }
 
-function buildHighRiskGate(matches, cwd) {
-  const stateSyncHint = buildStateSyncHint(cwd)
+function buildHighRiskGate(matches, cwd, payload = {}) {
+  const workflowOptions = { payload }
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions)
   if (stateSyncHint) {
     return {
       reason: `[HelloAGENTS Guard] Blocked T3 command until project recovery state is synced.\n${stateSyncHint}`,
     }
   }
 
-  const recommendation = getWorkflowRecommendation(cwd)
+  const recommendation = getWorkflowRecommendation(cwd, workflowOptions)
   if (!recommendation) return null
   if (matches.some((match) => match.gate === 'post-verify')) {
     return {
@@ -123,7 +124,7 @@ function buildPostWriteWarnings(data) {
   const filePath = data.tool_input?.file_path || ''
   return [
     ...(detectIdeaBoundaryContext(data)?.zeroSideEffect
-      ? ['~idea 本轮要求只读探索；检测到写入工具落地，请回退到探索输出或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
+      ? ['~idea 本轮要求只读探索；检测到写入文件的工具调用，请回到探索输出，或升级到 ~plan / ~build / ~prd / ~auto 后再修改文件']
       : []),
     ...scanUnrequestedFiles(filePath, data.tool_name),
     ...(content ? [...scanForSecrets(content), ...scanDangerousPackages(content, filePath)] : []),
@@ -172,7 +173,7 @@ function handleHighRiskCommand(data, command) {
   if (warnings.length === 0) return []
 
   const cwd = data.cwd || process.cwd()
-  const gate = buildHighRiskGate(warnings, cwd)
+  const gate = buildHighRiskGate(warnings, cwd, data)
   if (gate) {
     emitHookPayload({
       hookSpecificOutput: {
@@ -194,7 +195,7 @@ function handleHighRiskCommand(data, command) {
 function emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings) {
   const sections = []
   if (highRiskWarnings.length > 0) {
-    sections.push(`⚠️ [HelloAGENTS 高风险链路提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
+    sections.push(`⚠️ [HelloAGENTS 高风险操作提醒] 检测到高风险命令:\n${highRiskWarnings.map((warning) => `  - ${warning}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`)
   }
   if (shellSafetyWarnings.length > 0) {
     sections.push(`⚠️ [HelloAGENTS Shell 安全提醒] 检测到建议调整的命令写法:\n${shellSafetyWarnings.map((warning) => `  - ${warning}`).join('\n')}\n当前仅提示，不中断执行。`)

package/scripts/notify-context.mjs

@@ -1,7 +1,7 @@
 import { join } from 'node:path';
 import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint } from './workflow-state.mjs';
+import { buildCommandRouteHint, buildStateSyncHint, buildWorkflowRouteHint, readStateSnapshot } from './workflow-state.mjs';
 import { buildCapabilityHint } from './capability-registry.mjs';
 import {
   buildProjectStorageBlock,
@@ -69,16 +69,14 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   summaryParts.push('以下信息在上下文压缩前保存，确保压缩后不丢失关键状态。');
 
   const cwd = payload.cwd || process.cwd();
-  const statePath = join(cwd, '.helloagents', 'STATE.md');
-  const stateSyncHint = buildStateSyncHint(cwd);
-  if (existsSync(statePath)) {
-    try {
-      const stateContent = readFileSync(statePath, 'utf-8');
-      summaryParts.push('');
-      summaryParts.push('## 恢复快照（从 STATE.md 读取，只用于找回上次停在哪）');
-      summaryParts.push('恢复时先看当前用户消息，确认仍是同一任务再按 STATE.md 接续。');
-      summaryParts.push(stateContent);
-    } catch {}
+  const workflowOptions = { payload };
+  const stateSnapshot = readStateSnapshot(cwd, workflowOptions);
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
+  if (stateSnapshot.exists && stateSnapshot.content) {
+    summaryParts.push('');
+    summaryParts.push(`## 状态文件（从 ${stateSnapshot.statePath.replace(/\\/g, '/')} 读取，只用于找回上次停在哪）`);
+    summaryParts.push('恢复时先看当前用户消息；如果仍是同一任务，再参考状态文件。');
+    summaryParts.push(stateSnapshot.content);
   }
 
   let bootstrap = '';
@@ -103,7 +101,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
     summaryParts.push(readRootBlock);
   }
 
-  const projectStorageBlock = buildProjectStorageBlock(cwd);
+  const projectStorageBlock = buildProjectStorageBlock(cwd, workflowOptions);
   if (projectStorageBlock) {
     summaryParts.push('');
     summaryParts.push(projectStorageBlock);
@@ -111,7 +109,7 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
 
   if (stateSyncHint) {
     summaryParts.push('');
-    summaryParts.push('## STATE.md 提醒');
+    summaryParts.push('## 状态文件提醒');
     summaryParts.push(stateSyncHint);
   }
 
@@ -123,13 +121,15 @@ export function buildCompactionContext({ payload, pkgRoot, settings, bootstrapFi
   return summaryParts.join('\n');
 }
 
-export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd }) {
+export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host, cwd, payload = {} }) {
+  const workflowOptions = { payload };
   const packageRootBlock = buildPackageRootBlock(pkgRoot);
   const readRootBlock = buildReadRootBlock(resolveReadRoot({ cwd, pkgRoot, host, settings }));
-  const workflowHint = buildWorkflowRouteHint(cwd);
-  const capabilityHint = buildCapabilityHint({ cwd });
-  const projectStorageBlock = buildProjectStorageBlock(cwd);
-  const stateSyncHint = buildStateSyncHint(cwd);
+  const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
+  const projectStorageBlock = buildProjectStorageBlock(cwd, workflowOptions);
+  const stateSnapshot = readStateSnapshot(cwd, workflowOptions);
+  const stateSyncHint = buildStateSyncHint(cwd, workflowOptions);
   const settingsBlock = Object.keys(settings).length
     ? `\n\n## 当前用户设置\n\`\`\`json\n${JSON.stringify(settings, null, 2)}\n\`\`\``
     : '';
@@ -140,34 +140,36 @@ export function buildInjectContext({ source, bootstrap, settings, pkgRoot, host,
   if (projectStorageBlock) context += `\n\n${projectStorageBlock}`;
   if (workflowHint) context += `\n\n## 当前工作流提示\n${workflowHint}`;
   if (capabilityHint) context += `\n\n## 当前按需能力\n${capabilityHint}`;
-  if (stateSyncHint) context += `\n\n## STATE.md 提醒\n${stateSyncHint}`;
+  if (stateSyncHint) context += `\n\n## 状态文件提醒\n${stateSyncHint}`;
   context += settingsBlock;
   if (source === 'resume' || source === 'compact') {
-    context += '\n\n> ⚠️ 会话已恢复/压缩，请先读取 `.helloagents/STATE.md` 恢复工作状态；先看当前用户消息确认仍是同一任务，再按 STATE.md 接续。';
+    context += `\n\n> ⚠️ 会话已恢复/压缩，请先读取 \`state_path\` 指向的 \`${stateSnapshot.statePath.replace(/\\/g, '/')}\`；先看当前用户消息，如果仍是同一任务，再参考状态文件。`;
   }
   return context;
 }
 
-export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings }) {
+export function buildRouteInstruction({ skillName, extraRules = '', cwd, pkgRoot, host, settings, payload = {} }) {
+  const workflowOptions = { payload };
   const readRoot = resolveReadRoot({ cwd, pkgRoot, host, settings });
   const canonicalSkillName = resolveCanonicalCommandSkill(skillName);
   const skillPath = join(readRoot.root, 'skills', 'commands', canonicalSkillName, 'SKILL.md');
   const aliasNote = buildAliasRouteNote(skillName);
-  const commandHint = buildCommandRouteHint(canonicalSkillName, cwd);
-  const capabilityHint = buildCapabilityHint({ cwd, skillName: canonicalSkillName });
-  const projectStorageHint = buildProjectStorageHint(cwd);
+  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}`;
 }
 
-export function buildSemanticRouteInstruction(cwd) {
-  const workflowHint = buildWorkflowRouteHint(cwd);
-  const capabilityHint = buildCapabilityHint({ cwd });
-  const projectStorageHint = buildProjectStorageHint(cwd);
+export function buildSemanticRouteInstruction(cwd, payload = {}) {
+  const workflowOptions = { payload };
+  const workflowHint = buildWorkflowRouteHint(cwd, workflowOptions);
+  const capabilityHint = buildCapabilityHint({ cwd, options: workflowOptions });
+  const projectStorageHint = buildProjectStorageHint(cwd, workflowOptions);
   return [
     '当前消息未使用 ~command。',
     '请根据用户请求的真实意图选路，不依赖关键词表。',
-    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆链路。',
-    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动编排并自动衔接后续阶段。',
+    'Delivery Tier: T0=探索/比较；T1=低风险小改动或显式验证；T2=多文件功能/新项目/需要结构化产物；T3=高风险或不可逆操作。',
+    '路由映射：~idea=只读探索，不创建文件；~build=明确实现；~verify=审查/验证；~plan=结构化规划；~prd=重型规格；~auto=自动选择并继续执行后续阶段。',
     '若判定为 T3，默认先走 ~plan / ~prd；纯审查/验证请求才优先 ~verify。',
     `涉及 UI 任务时，设计决策优先级：当前活跃 plan / PRD → ${describeProjectStoreFile(cwd, 'DESIGN.md')} → 通用 UI 规则。`,
     projectStorageHint,

package/scripts/notify-events.mjs

@@ -5,11 +5,3 @@ export function shouldIgnoreCodexNotifyClient(client) {
 export function shouldIgnoreFormattedSubagent(lastMsg, outputFormatEnabled) {
   return outputFormatEnabled && !lastMsg.includes('【HelloAGENTS】');
 }
-
-export function claimsTaskComplete(lastMsg) {
-  if (!lastMsg) return false;
-  if (/^✅【HelloAGENTS】- .*(当前任务已完成|任务已完成|已修复|完成交付|done|fixed|completed|finished)/im.test(lastMsg)) {
-    return true;
-  }
-  return /(当前任务已完成|任务已完成|已全部完成|已修复|修复完成|\b(done|fixed|completed|finished)\b)/i.test(lastMsg);
-}

package/scripts/notify-gates.mjs

@@ -0,0 +1,128 @@
+import { existsSync } from 'node:fs'
+import { spawnSync } from 'node:child_process'
+
+function truncateText(value = '') {
+  const text = String(value || '').trim()
+  return text.length > 1000 ? `${text.slice(0, 1000)}\n...(truncated)` : text
+}
+
+function buildGateErrorReason(source, detail = '') {
+  return [
+    `[HelloAGENTS Runtime] ${source} 执行失败，已暂停完成通知。`,
+    detail ? `原因：${detail}` : '',
+    '请修复脚本或重新运行验证后再报告完成。',
+  ].filter(Boolean).join('\n')
+}
+
+function emitGateError({
+  payload,
+  host,
+  source,
+  reason,
+  appendReplayEvent,
+  output,
+}) {
+  appendReplayEvent(payload.cwd || process.cwd(), {
+    host,
+    event: 'runtime_gate_error',
+    source,
+    reason,
+  })
+  output({
+    decision: 'block',
+    reason,
+    suppressOutput: true,
+  })
+  return true
+}
+
+export function runGateScript({
+  payload,
+  host,
+  scriptPath,
+  args = [],
+  source,
+  blockEvent,
+  timeout,
+  appendReplayEvent,
+  output,
+}) {
+  if (!existsSync(scriptPath)) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, `脚本不存在：${scriptPath}`),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  const result = spawnSync(process.execPath, [scriptPath, ...args], {
+    input: JSON.stringify(payload),
+    encoding: 'utf-8',
+    timeout,
+  })
+
+  if (result.error) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, result.error.message),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  if (result.status !== 0) {
+    const detail = truncateText(`${result.stderr || ''}\n${result.stdout || ''}`) || `退出码 ${result.status}`
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, detail),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  const stdout = String(result.stdout || '').trim()
+  if (!stdout) {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, '脚本未返回有效结果'),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  let gateOutput
+  try {
+    gateOutput = JSON.parse(stdout)
+  } catch {
+    return emitGateError({
+      payload,
+      host,
+      source,
+      reason: buildGateErrorReason(source, `脚本返回了无法解析的 JSON：${truncateText(stdout)}`),
+      appendReplayEvent,
+      output,
+    })
+  }
+
+  if (gateOutput.decision === 'block') {
+    appendReplayEvent(payload.cwd || process.cwd(), {
+      host,
+      event: blockEvent,
+      source,
+      reason: gateOutput.reason || '',
+    })
+    output(gateOutput)
+    return true
+  }
+
+  return false
+}

package/scripts/notify-route.mjs

@@ -17,6 +17,7 @@ function buildHelpExtraRules(skillName) {
 
 function routeExplicitCommand({
   prompt,
+  payload,
   cwd,
   host,
   pkgRoot,
@@ -51,6 +52,7 @@ function routeExplicitCommand({
     pkgRoot,
     host,
     settings,
+    payload,
   }))
   return true
 }
@@ -80,6 +82,7 @@ export function handleRouteCommand({
 
   if (routeExplicitCommand({
     prompt,
+    payload,
     cwd,
     host,
     pkgRoot,
@@ -100,9 +103,9 @@ export function handleRouteCommand({
       host,
       event: 'semantic_route_prompted',
       source: 'route',
-      recommendation: getWorkflowRecommendation(cwd),
+      recommendation: getWorkflowRecommendation(cwd, { payload }),
     })
-    suppress(buildSemanticRouteInstruction(cwd))
+    suppress(buildSemanticRouteInstruction(cwd, payload))
     return
   }