helloagents 3.0.7 → 3.0.9-beta.1

package/scripts/cli-codex.mjs

@@ -7,21 +7,19 @@ import {
 } from './cli-utils.mjs';
 import { ensureTimestampedBackup, readCodexBackup, removeCodexBackup } from './cli-codex-backup.mjs';
 import {
-  CODEX_DEVELOPER_INSTRUCTIONS,
   CODEX_MANAGED_TOML_COMMENT,
   CODEX_PLUGIN_CONFIG_HEADER,
-  installCodexDeveloperInstructions,
+  isManagedCodexHooks,
+  installCodexManagedTopLevelConfig,
   isManagedCodexBackupInstruction,
   isManagedCodexModelInstruction,
   isManagedCodexNotify,
   removeCodexPluginConfig,
-  uninstallCodexDeveloperInstructions,
+  restoreCodexTopLevelConfig,
   upsertCodexPluginConfig,
 } from './cli-codex-config.mjs';
 import {
-  upsertTopLevelTomlKey,
   readTopLevelTomlLine,
-  ensureTopLevelTomlLine,
   readTomlKeyInSection,
   removeTomlKeyInSection,
   ensureTomlKeyInSection,
@@ -31,7 +29,7 @@ import {
 export const CODEX_MARKETPLACE_NAME = 'local-plugins';
 export const CODEX_PLUGIN_NAME = 'helloagents';
 export const CODEX_PLUGIN_KEY = `${CODEX_PLUGIN_NAME}@${CODEX_MARKETPLACE_NAME}`;
-export { CODEX_DEVELOPER_INSTRUCTIONS, CODEX_MANAGED_TOML_COMMENT, CODEX_PLUGIN_CONFIG_HEADER };
+export { CODEX_MANAGED_TOML_COMMENT, CODEX_PLUGIN_CONFIG_HEADER };
 export const CODEX_RUNTIME_CARRIER = 'AGENTS.md';
 const CODEX_CONFIG_BASENAME = 'config.toml';
 export const CODEX_RUNTIME_ENTRIES = [
@@ -108,10 +106,6 @@ function removeCodexMarketplaceEntry(marketplaceFile) {
   return true;
 }
 
-function normalizePath(path) {
-  return path.replace(/\\/g, '/');
-}
-
 function buildCodexRuntimeCarrier(bootstrapContent) {
   const normalized = String(bootstrapContent || '').trim();
   return normalized ? `${normalized}\n` : '';
@@ -131,11 +125,55 @@ function writeCodexRuntimeCarrier(filePath, bootstrapPath) {
   return true;
 }
 
-function stripCodexModelInstructions(toml = '') {
-  return removeTopLevelTomlLines(
+function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } = {}) {
+  const backupToml = readCodexBackup(configPath, CODEX_CONFIG_BASENAME);
+  let toml = safeRead(configPath) || '';
+
+  const currentModelInstructions = readTopLevelTomlLine(toml, 'model_instructions_file');
+  const currentNotify = readTopLevelTomlLine(toml, 'notify');
+  const currentCodexHooks = readTomlKeyInSection(toml, '[features]', 'codex_hooks');
+
+  const shouldRestoreModelInstructions = isManagedCodexModelInstruction(currentModelInstructions);
+  const shouldRestoreNotify = isManagedCodexNotify(currentNotify);
+  const shouldRestoreCodexHooks = isManagedCodexHooks(currentCodexHooks);
+
+  if (removePluginConfig) {
+    toml = removeCodexPluginConfig(toml);
+  }
+  if (shouldRestoreModelInstructions) {
+    toml = removeTopLevelTomlLines(toml, (line) =>
+      line.startsWith('model_instructions_file =') && isManagedCodexModelInstruction(line)).text;
+  }
+  if (shouldRestoreNotify) {
+    toml = removeTopLevelTomlLines(toml, (line) =>
+      line.startsWith('notify =') && isManagedCodexNotify(line)).text;
+  }
+  if (shouldRestoreCodexHooks) {
+    toml = removeTomlKeyInSection(toml, '[features]', 'codex_hooks');
+  }
+
+  const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
+  const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
+  const backupCodexHooks = readTomlKeyInSection(backupToml, '[features]', 'codex_hooks');
+
+  toml = restoreCodexTopLevelConfig(toml, {
+    modelInstructionsLine: shouldRestoreModelInstructions && !isManagedCodexBackupInstruction(backupModelInstructions)
+      ? backupModelInstructions
+      : '',
+    notifyLine: shouldRestoreNotify && !isManagedCodexNotify(backupNotify)
+      ? backupNotify
+      : '',
+  });
+  toml = ensureTomlKeyInSection(
     toml,
-    (line) => line.startsWith('model_instructions_file ='),
-  ).text;
+    '[features]',
+    'codex_hooks',
+    shouldRestoreCodexHooks && !isManagedCodexHooks(backupCodexHooks)
+      ? backupCodexHooks
+      : '',
+  );
+
+  return toml;
 }
 
 export function installCodexStandby(home, pkgRoot) {
@@ -150,9 +188,10 @@ export function installCodexStandby(home, pkgRoot) {
   let toml = safeRead(configPath) || '';
   ensureTimestampedBackup(configPath, CODEX_CONFIG_BASENAME);
 
-  toml = stripCodexModelInstructions(toml);
-  toml = upsertTopLevelTomlKey(toml, 'notify', `["node", "${normalizePath(join(pkgRoot, 'scripts', 'notify.mjs'))}", "codex-notify"]`);
-  toml = installCodexDeveloperInstructions(configPath, toml);
+  toml = installCodexManagedTopLevelConfig(toml, {
+    modelInstructionsPath: codexAgentsPath,
+    notifyScriptPath: join(pkgRoot, 'scripts', 'notify.mjs'),
+  });
   safeWrite(configPath, toml);
 
   createLink(pkgRoot, join(codexDir, 'helloagents'));
@@ -167,34 +206,10 @@ export function uninstallCodexStandby(home) {
     removeMarkedContent(join(codexDir, 'AGENTS.md'));
 
     const configPath = join(codexDir, 'config.toml');
-    const backupToml = readCodexBackup(configPath, CODEX_CONFIG_BASENAME);
-    let toml = safeRead(configPath) || '';
-    if (toml.includes('helloagents') || toml.includes('HelloAGENTS')) {
-      toml = removeTopLevelTomlLines(toml, (line) => {
-        if (!line) return false;
-        if (line.startsWith('model_instructions_file =') && isManagedCodexModelInstruction(line)) return true;
-        if (line.startsWith('notify =') && line.includes('codex-notify')) return true;
-        return false;
-      }).text;
-      toml = uninstallCodexDeveloperInstructions(configPath, toml);
-      toml = removeTomlKeyInSection(toml, '[features]', 'codex_hooks');
-      const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
-      const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
-      toml = ensureTopLevelTomlLine(
-        toml,
-        'model_instructions_file',
-        isManagedCodexBackupInstruction(backupModelInstructions) ? '' : backupModelInstructions,
-      );
-      toml = ensureTopLevelTomlLine(
-        toml,
-        'notify',
-        isManagedCodexNotify(backupNotify) ? '' : backupNotify,
-      );
-      toml = ensureTomlKeyInSection(toml, '[features]', 'codex_hooks', readTomlKeyInSection(backupToml, '[features]', 'codex_hooks'));
-      if (toml.trim()) safeWrite(configPath, toml);
-      else removeIfExists(configPath);
-      changed = true;
-    }
+    const toml = cleanupCodexManagedConfig(configPath);
+    if (toml.trim()) safeWrite(configPath, toml);
+    else removeIfExists(configPath);
+    changed = true;
     removeCodexBackup(configPath, CODEX_CONFIG_BASENAME);
     removeIfExists(join(codexDir, 'hooks.json'));
     removeLink(join(codexDir, 'helloagents'));
@@ -233,6 +248,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'),
@@ -241,21 +257,19 @@ export function installCodexGlobal(home, pkgRoot) {
     join(installedPluginRoot, CODEX_RUNTIME_CARRIER),
     join(installedPluginRoot, 'bootstrap.md'),
   );
-  injectCodexRuntimeCarrier(join(codexDir, CODEX_RUNTIME_CARRIER), join(pkgRoot, 'bootstrap.md'));
+  const homeCarrierPath = join(codexDir, CODEX_RUNTIME_CARRIER);
+  injectCodexRuntimeCarrier(homeCarrierPath, join(pkgRoot, 'bootstrap.md'));
 
   ensureDir(join(home, '.agents', 'plugins'));
   updateCodexMarketplace(marketplaceFile);
 
   let toml = safeRead(configPath) || '';
   ensureTimestampedBackup(configPath, CODEX_CONFIG_BASENAME);
-  toml = stripCodexModelInstructions(toml);
-  toml = upsertTopLevelTomlKey(
-    toml,
-    'notify',
-    `["node", "${normalizePath(join(pluginRoot, 'scripts', 'notify.mjs'))}", "codex-notify"]`,
-  );
+  toml = installCodexManagedTopLevelConfig(toml, {
+    modelInstructionsPath: homeCarrierPath,
+    notifyScriptPath: join(pluginRoot, 'scripts', 'notify.mjs'),
+  });
   toml = upsertCodexPluginConfig(toml);
-  toml = installCodexDeveloperInstructions(configPath, toml);
   safeWrite(configPath, toml);
 
   return true;
@@ -273,31 +287,9 @@ export function uninstallCodexGlobal(home) {
   removeIfExists(pluginCacheRoot);
   removeCodexMarketplaceEntry(marketplaceFile);
   removeMarkedContent(join(codexDir, 'AGENTS.md'));
+  removeLink(join(codexDir, 'helloagents'));
 
-  const backupToml = readCodexBackup(configPath, CODEX_CONFIG_BASENAME);
-  let toml = safeRead(configPath) || '';
-  toml = removeCodexPluginConfig(toml);
-  toml = uninstallCodexDeveloperInstructions(configPath, toml);
-  toml = removeTomlKeyInSection(toml, '[features]', 'codex_hooks');
-  toml = removeTopLevelTomlLines(toml, (line) =>
-    line.startsWith('model_instructions_file =')
-    && isManagedCodexModelInstruction(line)).text;
-  toml = removeTopLevelTomlLines(toml, (line) =>
-    line.startsWith('notify =')
-    && line.includes('/plugins/helloagents/scripts/notify.mjs')).text;
-  const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
-  const backupNotify = readTopLevelTomlLine(backupToml, 'notify');
-  toml = ensureTopLevelTomlLine(
-    toml,
-    'model_instructions_file',
-    isManagedCodexBackupInstruction(backupModelInstructions) ? '' : backupModelInstructions,
-  );
-  toml = ensureTopLevelTomlLine(
-    toml,
-    'notify',
-    isManagedCodexNotify(backupNotify) ? '' : backupNotify,
-  );
-  toml = ensureTomlKeyInSection(toml, '[features]', 'codex_hooks', readTomlKeyInSection(backupToml, '[features]', 'codex_hooks'));
+  const toml = cleanupCodexManagedConfig(configPath, { removePluginConfig: true });
   if (toml.trim()) safeWrite(configPath, toml);
   else removeIfExists(configPath);
   removeCodexBackup(configPath, CODEX_CONFIG_BASENAME);

package/scripts/cli-doctor.mjs

@@ -140,8 +140,8 @@ function inspectClaudeDoctor(settings) {
     issues.push(buildDoctorIssue('tracked-mode-mismatch', '记录模式与检测模式不一致', 'Tracked mode does not match detected mode'))
   }
   if (detectedMode === 'standby') {
-    if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 载体缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
-    if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 载体内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
+    if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 规则文件缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
+    if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 规则文件内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
     if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向当前包根目录', 'Standby home link is missing or points to a different package root'))
     if (!checks.settingsHooks) issues.push(buildDoctorIssue('standby-hooks-missing', 'standby settings hooks 缺失', 'Standby settings hooks are missing'))
     if (checks.settingsHooks && !checks.settingsHooksMatch) issues.push(buildDoctorIssue('standby-hooks-drift', 'standby settings hooks 与当前 hooks 配置不一致', 'Standby settings hooks differ from the current hook configuration'))
@@ -160,7 +160,7 @@ function inspectClaudeDoctor(settings) {
     issues.push(buildDoctorIssue('untracked-managed-state', '检测到受管状态，但配置中未记录该 CLI 模式', 'Managed state detected but this CLI mode is not tracked in config'))
   }
   if (trackedMode !== 'none' && detectedMode === 'none' && trackedMode !== 'global') {
-    issues.push(buildDoctorIssue('tracked-state-missing', '配置记录该 CLI 已安装，但未检测到对应受管痕迹', 'Config says this CLI is installed, but no managed artifacts were detected'))
+    issues.push(buildDoctorIssue('tracked-state-missing', '配置记录该 CLI 已安装，但未检测到对应的受管文件或配置', 'Config says this CLI is installed, but no managed artifacts were detected'))
   }
 
   const status = summarizeDoctorStatus(issues, { host, trackedMode, detectedMode })
@@ -188,8 +188,8 @@ function inspectGeminiDoctor(settings) {
     issues.push(buildDoctorIssue('tracked-mode-mismatch', '记录模式与检测模式不一致', 'Tracked mode does not match detected mode'))
   }
   if (detectedMode === 'standby') {
-    if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 载体缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
-    if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 载体内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
+    if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 规则文件缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
+    if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 规则文件内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
     if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向当前包根目录', 'Standby home link is missing or points to a different package root'))
     if (!checks.settingsHooks) issues.push(buildDoctorIssue('standby-hooks-missing', 'standby settings hooks 缺失', 'Standby settings hooks are missing'))
     if (checks.settingsHooks && !checks.settingsHooksMatch) issues.push(buildDoctorIssue('standby-hooks-drift', 'standby settings hooks 与当前 hooks 配置不一致', 'Standby settings hooks differ from the current hook configuration'))
@@ -207,7 +207,7 @@ function inspectGeminiDoctor(settings) {
     issues.push(buildDoctorIssue('untracked-managed-state', '检测到受管状态，但配置中未记录该 CLI 模式', 'Managed state detected but this CLI mode is not tracked in config'))
   }
   if (trackedMode !== 'none' && detectedMode === 'none' && trackedMode !== 'global') {
-    issues.push(buildDoctorIssue('tracked-state-missing', '配置记录该 CLI 已安装，但未检测到对应受管痕迹', 'Config says this CLI is installed, but no managed artifacts were detected'))
+    issues.push(buildDoctorIssue('tracked-state-missing', '配置记录该 CLI 已安装，但未检测到对应的受管文件或配置', 'Config says this CLI is installed, but no managed artifacts were detected'))
   }
 
   const status = summarizeDoctorStatus(issues, { host, trackedMode, detectedMode })
@@ -215,31 +215,32 @@ function inspectGeminiDoctor(settings) {
 }
 
 function appendCodexStandbyIssues(issues, checks) {
-  if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 载体缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
-  if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 载体内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
+  if (!checks.carrierMarker) issues.push(buildDoctorIssue('standby-carrier-missing', 'standby 规则文件缺少 HELLOAGENTS 标记', 'Standby carrier is missing the HELLOAGENTS marker'))
+  if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue('standby-carrier-drift', 'standby 规则文件内容与当前 bootstrap-lite.md 不一致', 'Standby carrier content differs from the current bootstrap-lite.md'))
   if (!checks.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向当前包根目录', 'Standby home link is missing or points to a different package root'))
-  if (checks.modelInstructionsFile) issues.push(buildDoctorIssue('standby-model-instructions-shadow', 'standby config 中仍存在 model_instructions_file，可能覆盖 HelloAGENTS 载体', 'Standby config still contains model_instructions_file, which can shadow the HelloAGENTS carrier'))
+  if (!checks.modelInstructionsFile) issues.push(buildDoctorIssue('standby-model-instructions-missing', 'standby config 缺少受管 model_instructions_file', 'Standby config is missing the managed model_instructions_file'))
+  if (checks.modelInstructionsFile && !checks.modelInstructionsPathMatch) issues.push(buildDoctorIssue('standby-model-instructions-drift', 'standby model_instructions_file 未指向受管 `~/.codex/AGENTS.md`', 'Standby model_instructions_file does not point to the managed `~/.codex/AGENTS.md`'))
   if (!checks.codexNotify) issues.push(buildDoctorIssue('standby-notify-missing', 'standby notify 配置缺失', 'Standby notify configuration is missing'))
   if (checks.codexNotify && !checks.notifyPathMatch) issues.push(buildDoctorIssue('standby-notify-drift', 'standby notify 路径未指向当前包根目录', 'Standby notify path does not point to the current package root'))
-  if (!checks.developerInstructions) issues.push(buildDoctorIssue('standby-developer-instructions-missing', 'standby developer_instructions 缺失', 'Standby developer_instructions block is missing'))
   if (checks.pluginRoot || checks.pluginCache || checks.marketplaceEntry || checks.pluginEnabled || checks.globalNotifyPath) {
-    issues.push(buildDoctorIssue('standby-global-residue', 'standby 模式下仍残留 global 插件链路', 'Global plugin artifacts still remain while Codex is in standby mode'))
+    issues.push(buildDoctorIssue('standby-global-residue', 'standby 模式下仍残留 global 插件文件或配置', 'Global plugin artifacts still remain while Codex is in standby mode'))
   }
 }
 
 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) 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'))
   if (checks.pluginCache && !checks.pluginCacheCarrierMatch) issues.push(buildDoctorIssue('global-plugin-cache-carrier-drift', 'global 插件缓存中的 AGENTS.md 与当前 bootstrap.md 不一致', 'Global plugin cache AGENTS.md differs from the current bootstrap.md'))
   if (!checks.marketplaceEntry) issues.push(buildDoctorIssue('global-marketplace-missing', 'global marketplace 条目缺失', 'Global marketplace entry is missing'))
   if (!checks.pluginEnabled) issues.push(buildDoctorIssue('global-plugin-disabled', 'global config 中缺少插件启用段', 'Global plugin enablement block is missing from config'))
-  if (checks.modelInstructionsFile) issues.push(buildDoctorIssue('global-model-instructions-shadow', 'global config 中仍存在 model_instructions_file，可能覆盖 HelloAGENTS 载体', 'Global config still contains model_instructions_file, which can shadow the HelloAGENTS carrier'))
+  if (!checks.modelInstructionsFile) issues.push(buildDoctorIssue('global-model-instructions-missing', 'global config 缺少受管 model_instructions_file', 'Global config is missing the managed model_instructions_file'))
+  if (checks.modelInstructionsFile && !checks.modelInstructionsPathMatch) issues.push(buildDoctorIssue('global-model-instructions-drift', 'global model_instructions_file 未指向受管 `~/.codex/AGENTS.md`', 'Global model_instructions_file does not point to the managed `~/.codex/AGENTS.md`'))
   if (!checks.globalNotifyPath) issues.push(buildDoctorIssue('global-notify-missing', 'global notify 路径缺失', 'Global notify path is missing'))
   if (checks.globalNotifyPath && !checks.globalNotifyPathMatch) issues.push(buildDoctorIssue('global-notify-drift', 'global notify 路径未指向当前插件根目录', 'Global notify path does not point to the current plugin root'))
-  if (!checks.developerInstructions) issues.push(buildDoctorIssue('global-developer-instructions-missing', 'global developer_instructions 缺失', 'Global developer_instructions block is missing'))
   if (pluginVersion && !checks.pluginVersionMatch) issues.push(buildDoctorIssue('global-plugin-version-drift', 'global 插件根目录版本与当前包版本不一致', 'Global plugin root version does not match the current package version'))
   if (cacheVersion && !checks.pluginCacheVersionMatch) issues.push(buildDoctorIssue('global-plugin-cache-version-drift', 'global 插件缓存版本与当前包版本不一致', 'Global plugin cache version does not match the current package version'))
   if (checks.homeLink) {
@@ -258,19 +259,26 @@ 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'))
+  const modelInstructionsLine = readTopLevelTomlLine(codexConfig, 'model_instructions_file')
   const expectedHomeCarrier = (detectedMode === 'global' || (detectedMode === 'none' && trackedMode === 'global'))
     ? 'bootstrap.md'
     : 'bootstrap-lite.md'
   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,
-    modelInstructionsFile: !!readTopLevelTomlLine(codexConfig, 'model_instructions_file'),
+    homeLink: homeLinkTarget === pkgRootTarget,
+    globalHomeLink: homeLinkTarget === pluginRootTarget,
+    modelInstructionsFile: !!modelInstructionsLine,
+    modelInstructionsPathMatch: !!modelInstructionsLine
+      && normalizePath(modelInstructionsLine).includes(`"${managedHomeCarrierPath}"`),
     codexNotify: codexConfig.includes('codex-notify'),
     notifyPathMatch: codexConfig.includes(standbyNotifyPath),
-    developerInstructions: codexConfig.includes('HelloAGENTS'),
     pluginRoot: existsSync(pluginRoot),
     pluginCache: existsSync(pluginCacheRoot),
     pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '') === readBootstrapContent('bootstrap.md'),
@@ -298,7 +306,7 @@ function inspectCodexDoctor(settings) {
     issues.push(buildDoctorIssue('untracked-managed-state', '检测到受管状态，但配置中未记录该 CLI 模式', 'Managed state detected but this CLI mode is not tracked in config'))
   }
   if (trackedMode !== 'none' && detectedMode === 'none') {
-    issues.push(buildDoctorIssue('tracked-state-missing', '配置记录该 CLI 已安装，但未检测到对应受管痕迹', 'Config says this CLI is installed, but no managed artifacts were detected'))
+    issues.push(buildDoctorIssue('tracked-state-missing', '配置记录该 CLI 已安装，但未检测到对应的受管文件或配置', 'Config says this CLI is installed, but no managed artifacts were detected'))
   }
   if (!checks.pluginVersionMatch && !pluginVersion && detectedMode === 'global') {
     notes.push(runtime.msg('未读到 global 插件根目录版本信息', 'Global plugin root version was not readable'))

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-messages.mjs

@@ -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, model_instructions_file shadowing risks, and version drift')}
+  ${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('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}

package/scripts/cli-toml.mjs

@@ -33,6 +33,15 @@ function findFirstTomlSectionIndex(text) {
   return normalized.length;
 }
 
+function splitTopLevelToml(text) {
+  const normalized = String(text || '').replace(/\r\n/g, '\n');
+  const topLevelEnd = findFirstTomlSectionIndex(normalized);
+  return {
+    topLevel: normalized.slice(0, topLevelEnd),
+    sections: normalized.slice(topLevelEnd),
+  };
+}
+
 function findTopLevelTomlBlock(text, key) {
   const normalized = String(text || '').replace(/\r\n/g, '\n');
   const topLevelEnd = findFirstTomlSectionIndex(normalized);
@@ -93,6 +102,27 @@ export function removeTopLevelTomlBlock(text, key) {
   return normalizeToml(`${normalized.slice(0, existing.start)}${normalized.slice(existing.end)}`);
 }
 
+export function prependTopLevelTomlBlocks(text, blocks) {
+  const normalizedBlocks = blocks
+    .map((block) => String(block || '').trim())
+    .filter(Boolean);
+
+  const { topLevel, sections } = splitTopLevelToml(text);
+  const normalizedTopLevel = topLevel.replace(/^\n+/, '').trimEnd();
+  const normalizedSections = sections.replace(/^\n+/, '').trimEnd();
+  const remainder = normalizedTopLevel && normalizedSections
+    ? `${normalizedTopLevel}\n\n${normalizedSections}`
+    : normalizedTopLevel || normalizedSections;
+  if (!normalizedBlocks.length) return normalizeToml(remainder);
+  const managedPrelude = normalizedBlocks.join('\n');
+
+  return normalizeToml(
+    remainder
+      ? `${managedPrelude}\n\n${remainder}`
+      : managedPrelude,
+  );
+}
+
 export function upsertTopLevelTomlKey(text, key, value) {
   const re = new RegExp(`^${key}\\s*=.*$`, 'm');
   const next = re.test(text)

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-rules.mjs

@@ -6,10 +6,12 @@ export const DANGEROUS_PATTERNS = [
   { pattern: /(sudo\s+)?rm\s+(-[a-zA-Z]*r[a-zA-Z]*\s+)?(-[a-zA-Z]*f[a-zA-Z]*\s+)?(\/|~|\*)/, reason: 'Recursive delete of critical path' },
   { pattern: /(sudo\s+)?rm\s+--recursive/, reason: 'Recursive delete (long option)' },
   { pattern: /(sudo\s+)?rm\s+-[a-zA-Z]*r[a-zA-Z]*\s+\.\.?(\s|$)/, reason: 'Recursive delete of current/parent directory' },
+  { pattern: /\bcmd(?:\.exe)?\s*\/c\b/i, reason: 'Nested cmd invocation bypasses PowerShell safety rules' },
+  { pattern: /\bStart-Process\s+cmd(?:\.exe)?\b/i, reason: 'Nested cmd invocation bypasses PowerShell safety rules' },
   { pattern: /git\s+push\s+(-f|--force)/, reason: 'Force push (specify branch explicitly)' },
   { pattern: /git\s+reset\s+--hard/, reason: 'Hard reset (destructive operation)' },
   { pattern: /DROP\s+(DATABASE|TABLE|SCHEMA)/i, reason: 'Database destruction command' },
-  { pattern: /TRUNCATE\s+TABLE/i, reason: 'Table truncation' },
+  { pattern: /\bTRUNCATE(?:\s+TABLE)?\b/i, reason: 'Table truncation' },
   { pattern: /chmod\s+777/, reason: 'World-writable permissions' },
   { pattern: /mkfs\b/, reason: 'Filesystem format command' },
   { pattern: /dd\s+.*of=\/dev\//, reason: 'Direct device write' },
@@ -68,6 +70,29 @@ export function scanHighRiskCommands(command) {
   return warnings
 }
 
+export function scanShellSafetyWarnings(command = '') {
+  const warnings = []
+  const normalized = String(command || '')
+
+  if (/\bpowershell(?:\.exe)?\b/i.test(normalized) && /\s-Command\b/i.test(normalized)) {
+    const inlineScript = normalized.split(/\s-Command\b/i).slice(1).join(' ').trim()
+    const logicalLines = inlineScript
+      .split(/[;\r\n]+/)
+      .map((entry) => entry.trim())
+      .filter(Boolean)
+    if (logicalLines.length > 3) {
+      warnings.push('PowerShell inline script exceeds 3 logical lines; prefer a temporary .ps1 file')
+    }
+  }
+
+  const fileOps = normalized.match(/\b(remove-item|move-item|copy-item|new-item|set-content|add-content|out-file|mkdir|md|touch|cp|copy|mv|move|ren|rename|del|erase|rm|rmdir)\b/ig) || []
+  if (fileOps.length > 1 && /[;\r\n]/.test(normalized)) {
+    warnings.push('Multiple file operations are chained in one shell command; split them into separate commands')
+  }
+
+  return warnings
+}
+
 export function scanUnrequestedFiles(filePath, toolName) {
   if (!filePath || toolName?.toLowerCase() !== 'write') return []
   const basename = filePath.split(/[/\\]/).pop() || ''

package/scripts/guard.mjs

@@ -18,6 +18,7 @@ import {
   scanEnvCoverage,
   scanForSecrets,
   scanHighRiskCommands,
+  scanShellSafetyWarnings,
   scanUnrequestedFiles,
 } from './guard-rules.mjs'
 
@@ -61,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 {
@@ -122,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)] : []),
@@ -168,10 +170,10 @@ function handleDangerousCommand(data, command) {
 
 function handleHighRiskCommand(data, command) {
   const warnings = scanHighRiskCommands(command)
-  if (warnings.length === 0) return
+  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: {
@@ -185,20 +187,43 @@ function handleHighRiskCommand(data, command) {
       guardType: 'high-risk-gate',
       matches: warnings.map((warning) => warning.reason),
     })
-    return
+    return null
+  }
+  return warnings.map((warning) => warning.reason)
+}
+
+function emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings) {
+  const sections = []
+  if (highRiskWarnings.length > 0) {
+    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当前仅提示，不中断执行。`)
   }
+  if (sections.length === 0) return
 
   emitHookPayload({
     hookSpecificOutput: {
       hookEventName: HOOK_EVENT,
-      additionalContext: `⚠️ [HelloAGENTS 高风险链路提醒] 检测到高风险命令:\n${warnings.map((warning) => `  - ${warning.reason}`).join('\n')}\n请确认已完成相应规划/审查并获得必要授权。`,
+      additionalContext: sections.join('\n\n'),
     },
   })
-  emitGuardEvent(cwd, 'guard_warning', 'command', '', {
-    guardType: 'high-risk-warning',
-    command: command.slice(0, 200),
-    warnings: warnings.map((warning) => warning.reason),
-  })
+
+  const cwd = data.cwd || process.cwd()
+  if (highRiskWarnings.length > 0) {
+    emitGuardEvent(cwd, 'guard_warning', 'command', '', {
+      guardType: 'high-risk-warning',
+      command: command.slice(0, 200),
+      warnings: highRiskWarnings,
+    })
+  }
+  if (shellSafetyWarnings.length > 0) {
+    emitGuardEvent(cwd, 'guard_warning', 'command', '', {
+      guardType: 'shell-safety-warning',
+      command: command.slice(0, 200),
+      warnings: shellSafetyWarnings,
+    })
+  }
 }
 
 function handleShellCommand(data) {
@@ -217,7 +242,11 @@ function handleShellCommand(data) {
   }
 
   if (handleDangerousCommand(data, command)) return
-  handleHighRiskCommand(data, command)
+  const highRiskWarnings = handleHighRiskCommand(data, command)
+  if (highRiskWarnings === null) return
+
+  const shellSafetyWarnings = scanShellSafetyWarnings(command)
+  emitShellWarnings(data, command, highRiskWarnings, shellSafetyWarnings)
 }
 
 async function main() {