helloagents 3.0.18 → 3.0.19-beta.1

package/scripts/cli-codex-goals.mjs

@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+import { ensureTimestampedBackup } from './cli-codex-backup.mjs'
+import {
+  CODEX_GOALS_FEATURE_KEY,
+  CODEX_MANAGED_TOML_COMMENT,
+  isManagedCodexGoalsFeature,
+  readCodexGoalsFeatureLine,
+  removeCodexGoalsFeatureConfig,
+  setCodexGoalsFeatureConfig,
+} from './cli-codex-config.mjs'
+import { ensureDir, safeRead, safeWrite } from './cli-utils.mjs'
+
+const CODEX_CONFIG_BASENAME = 'config.toml'
+
+function isJsonMode(args) {
+  return args.includes('--json')
+}
+
+function readStatus(home) {
+  const configPath = join(home, '.codex', CODEX_CONFIG_BASENAME)
+  const toml = safeRead(configPath) || ''
+  const line = readCodexGoalsFeatureLine(toml)
+  const valueMatch = line.match(/^\s*goals\s*=\s*(true|false)\b/)
+  const configured = Boolean(valueMatch)
+  const enabled = valueMatch ? valueMatch[1] === 'true' : false
+
+  return {
+    configPath,
+    configured,
+    enabled,
+    managed: isManagedCodexGoalsFeature(line),
+    line,
+  }
+}
+
+function printStatus(status, jsonMode) {
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify({
+      feature: CODEX_GOALS_FEATURE_KEY,
+      enabled: status.enabled,
+      configured: status.configured,
+      managed: status.managed,
+      configPath: status.configPath,
+    }, null, 2)}\n`)
+    return
+  }
+
+  const state = status.enabled ? 'enabled' : 'disabled'
+  const source = status.configured ? (status.managed ? 'managed' : 'user') : 'default'
+  process.stdout.write(`Codex goals: ${state} (${source})\n`)
+}
+
+function updateGoals(home, enabled) {
+  const codexDir = join(home, '.codex')
+  const configPath = join(codexDir, CODEX_CONFIG_BASENAME)
+  ensureDir(codexDir)
+  ensureTimestampedBackup(configPath, CODEX_CONFIG_BASENAME)
+
+  const current = safeRead(configPath) || ''
+  const next = enabled
+    ? setCodexGoalsFeatureConfig(current, true)
+    : removeCodexGoalsFeatureConfig(setCodexGoalsFeatureConfig(current, false))
+
+  if (next.trim()) safeWrite(configPath, next)
+  else safeWrite(configPath, '')
+}
+
+function printUsage() {
+  process.stdout.write([
+    'Usage: helloagents codex goals <status|enable|disable> [--json]',
+    '',
+    `This only manages [features].goals ${CODEX_MANAGED_TOML_COMMENT}.`,
+  ].join('\n') + '\n')
+}
+
+export function runCodexGoalsCli(args = process.argv.slice(2), { home = homedir() } = {}) {
+  const command = args.find((arg) => !arg.startsWith('--')) || 'status'
+  const jsonMode = isJsonMode(args)
+
+  if (!existsSync(join(home, '.codex')) && command === 'status') {
+    const status = {
+      configPath: join(home, '.codex', CODEX_CONFIG_BASENAME),
+      configured: false,
+      enabled: false,
+      managed: false,
+      line: '',
+    }
+    printStatus(status, jsonMode)
+    return
+  }
+
+  if (command === 'status') {
+    printStatus(readStatus(home), jsonMode)
+    return
+  }
+
+  if (command === 'enable' || command === 'disable') {
+    updateGoals(home, command === 'enable')
+    printStatus(readStatus(home), jsonMode)
+    return
+  }
+
+  printUsage()
+  process.exitCode = 1
+}
+
+if (process.argv[1]?.endsWith('cli-codex-goals.mjs')) {
+  runCodexGoalsCli()
+}

package/scripts/cli-codex.mjs

@@ -4,6 +4,7 @@ import {
   ensureDir, safeRead, safeWrite, removeIfExists,
   readJsonOrThrow, copyEntries,
   createLink, removeLink, injectMarkedContent, removeMarkedContent,
+  cleanSettingsHooks, loadHooksWithCliEntry, mergeSettingsHooks,
 } from './cli-utils.mjs';
 import { ensureTimestampedBackup, readCodexBackup, removeCodexBackup } from './cli-codex-backup.mjs';
 import {
@@ -12,9 +13,16 @@ import {
   CODEX_PLUGIN_CONFIG_HEADER,
   installCodexManagedTopLevelConfig,
   isManagedCodexBackupInstruction,
+  isManagedCodexGoalsFeature,
   isManagedCodexModelInstruction,
   isManagedCodexNotify,
+  isManagedLegacyCodexHooksFeature,
+  readCodexGoalsFeatureLine,
+  readLegacyCodexHooksFeatureLine,
+  removeCodexGoalsFeatureConfig,
+  removeLegacyManagedCodexHooksFeatureConfig,
   removeCodexPluginConfig,
+  restoreCodexGoalsFeatureConfig,
   restoreCodexTopLevelConfig,
   upsertCodexPluginConfig,
 } from './cli-codex-config.mjs';
@@ -31,6 +39,7 @@ export const CODEX_PLUGIN_KEY = `${CODEX_PLUGIN_NAME}@${CODEX_MARKETPLACE_NAME}`
 export { CODEX_MANAGED_TOML_COMMENT, CODEX_PLUGIN_CONFIG_HEADER };
 export const CODEX_RUNTIME_CARRIER = 'AGENTS.md';
 const CODEX_CONFIG_BASENAME = 'config.toml';
+const CODEX_HOOKS_BASENAME = 'hooks.json';
 export const CODEX_RUNTIME_ENTRIES = [
   '.codex-plugin',
   'assets',
@@ -120,19 +129,40 @@ function writeCodexRuntimeCarrier(filePath, bootstrapPath, settings) {
   return true;
 }
 
+function installCodexStandaloneHooks(home, pkgRoot) {
+  const hooksData = loadHooksWithCliEntry(pkgRoot, 'hooks-codex.json', '${PLUGIN_ROOT}');
+  if (!hooksData) return false;
+  mergeSettingsHooks(join(home, '.codex', CODEX_HOOKS_BASENAME), hooksData);
+  return true;
+}
+
+function cleanupCodexStandaloneHooks(home) {
+  cleanSettingsHooks(join(home, '.codex', CODEX_HOOKS_BASENAME));
+}
+
 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 = readTopLevelTomlBlock(toml, 'notify');
+  const currentCodexGoalsFeature = readCodexGoalsFeatureLine(toml);
+  const currentLegacyCodexHooksFeature = readLegacyCodexHooksFeatureLine(toml);
 
   const shouldRestoreModelInstructions = isManagedCodexModelInstruction(currentModelInstructions);
   const shouldRestoreNotify = isManagedCodexNotify(currentNotify);
+  const shouldRestoreCodexGoalsFeature = isManagedCodexGoalsFeature(currentCodexGoalsFeature);
+  const shouldRemoveLegacyCodexHooksFeature = isManagedLegacyCodexHooksFeature(currentLegacyCodexHooksFeature);
 
   if (removePluginConfig) {
     toml = removeCodexPluginConfig(toml);
   }
+  if (shouldRestoreCodexGoalsFeature) {
+    toml = removeCodexGoalsFeatureConfig(toml);
+  }
+  if (shouldRemoveLegacyCodexHooksFeature) {
+    toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
+  }
   if (shouldRestoreModelInstructions) {
     toml = removeTopLevelTomlLines(toml, (line) =>
       line.startsWith('model_instructions_file =') && isManagedCodexModelInstruction(line)).text;
@@ -144,6 +174,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
 
   const backupModelInstructions = readTopLevelTomlLine(backupToml, 'model_instructions_file');
   const backupNotify = readTopLevelTomlBlock(backupToml, 'notify');
+  const backupCodexGoalsFeature = readCodexGoalsFeatureLine(backupToml);
 
   toml = restoreCodexTopLevelConfig(toml, {
     modelInstructionsLine: shouldRestoreModelInstructions && !isManagedCodexBackupInstruction(backupModelInstructions)
@@ -153,6 +184,11 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
       ? backupNotify
       : '',
   });
+  toml = restoreCodexGoalsFeatureConfig(toml, {
+    codexGoalsLine: shouldRestoreCodexGoalsFeature && !isManagedCodexGoalsFeature(backupCodexGoalsFeature)
+      ? backupCodexGoalsFeature
+      : '',
+  });
 
   return toml;
 }
@@ -173,7 +209,9 @@ export function installCodexStandby(home, pkgRoot) {
   toml = installCodexManagedTopLevelConfig(toml, {
     modelInstructionsPath: CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   });
+  toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   safeWrite(configPath, toml);
+  installCodexStandaloneHooks(home, pkgRoot);
 
   createLink(pkgRoot, join(codexDir, 'helloagents'));
   return true;
@@ -210,6 +248,7 @@ export function uninstallCodexStandby(home) {
     else removeIfExists(configPath);
     changed = true;
     removeCodexBackup(configPath, CODEX_CONFIG_BASENAME);
+    cleanupCodexStandaloneHooks(home);
     removeLink(join(codexDir, 'helloagents'));
     changed = true;
   }
@@ -265,8 +304,10 @@ export function installCodexGlobal(home, pkgRoot) {
   toml = installCodexManagedTopLevelConfig(toml, {
     modelInstructionsPath: CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   });
+  toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   toml = upsertCodexPluginConfig(toml);
   safeWrite(configPath, toml);
+  installCodexStandaloneHooks(home, pkgRoot);
 
   return true;
 }
@@ -284,6 +325,7 @@ export function uninstallCodexGlobal(home) {
   removeCodexMarketplaceEntry(marketplaceFile);
   removeMarkedContent(join(codexDir, 'AGENTS.md'));
   removeLink(join(codexDir, 'helloagents'));
+  cleanupCodexStandaloneHooks(home);
 
   const toml = cleanupCodexManagedConfig(configPath, { removePluginConfig: true });
   if (toml.trim()) safeWrite(configPath, toml);

package/scripts/cli-doctor-codex.mjs

@@ -0,0 +1,208 @@
+import { existsSync, realpathSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_CONFIG_HEADER, CODEX_PLUGIN_NAME } from './cli-codex.mjs'
+import {
+  CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
+  CODEX_MANAGED_NOTIFY_VALUE,
+  readCodexGoalsFeatureLine,
+  readCodexHooksFeatureLine,
+  readLegacyCodexHooksFeatureLine,
+} from './cli-codex-config.mjs'
+import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
+import { readTopLevelTomlLine } from './cli-toml.mjs'
+import { loadHooksWithCliEntry, safeJson, safeRead } from './cli-utils.mjs'
+
+function safeRealTarget(linkPath) {
+  try {
+    return realpathSync(linkPath)
+  } catch {
+    return ''
+  }
+}
+
+function normalizeText(text = '') {
+  return String(text || '').replace(/\r\n/g, '\n').trim()
+}
+
+function normalizePath(value = '') {
+  return String(value || '').replace(/\\/g, '/')
+}
+
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson)
+  if (value && typeof value === 'object') {
+    return Object.keys(value).sort().reduce((acc, key) => {
+      acc[key] = sortJson(value[key])
+      return acc
+    }, {})
+  }
+  return value
+}
+
+function pickManagedHooks(hooks) {
+  const next = {}
+  for (const [event, entries] of Object.entries(hooks || {})) {
+    if (!Array.isArray(entries)) continue
+    const managedEntries = entries.filter((entry) => JSON.stringify(entry).includes('helloagents'))
+    if (managedEntries.length > 0) next[event] = managedEntries
+  }
+  return next
+}
+
+function managedHooksMatch(actualHooks, expectedHooks) {
+  return JSON.stringify(sortJson(pickManagedHooks(actualHooks || {})))
+    === JSON.stringify(sortJson(expectedHooks || {}))
+}
+
+function readExpectedHooks(runtime, hooksFile, pathVar) {
+  return pickManagedHooks(loadHooksWithCliEntry(runtime.pkgRoot, hooksFile, pathVar)?.hooks || {})
+}
+
+function readExpectedCarrierContent(runtime, fileName, settings) {
+  const bootstrap = safeRead(join(runtime.pkgRoot, fileName)) || ''
+  return normalizeText(buildRuntimeCarrier(bootstrap, settings))
+}
+
+function buildDoctorIssue(runtime, code, cn, en) {
+  return {
+    code,
+    message: runtime.msg(cn, en),
+  }
+}
+
+function normalizeDoctorMode(mode = '') {
+  return mode || 'none'
+}
+
+function summarizeDoctorStatus(issues, { trackedMode, detectedMode } = {}) {
+  if (issues.length > 0) return 'drift'
+  if (detectedMode !== 'none') return 'ok'
+  if (trackedMode !== 'none') return 'drift'
+  return 'not-installed'
+}
+
+function suggestCodexDoctorFix(status, trackedMode) {
+  if (status === 'drift') {
+    return `helloagents update codex${trackedMode && trackedMode !== 'none' ? ` --${trackedMode}` : ''}`
+  }
+  if (status === 'not-installed') return 'helloagents install codex --standby'
+  return ''
+}
+
+function appendCodexStandbyIssues(runtime, issues, checks) {
+  if (!checks.carrierMarker) issues.push(buildDoctorIssue(runtime, 'standby-carrier-missing', 'standby `~/.codex/AGENTS.md` 缺少 HelloAGENTS 标记', 'Standby `~/.codex/AGENTS.md` is missing the HELLOAGENTS marker'))
+  if (checks.carrierMarker && !checks.carrierContentMatch) issues.push(buildDoctorIssue(runtime, 'standby-carrier-drift', 'standby `~/.codex/AGENTS.md` 与当前 bootstrap-lite.md 不一致', 'Standby `~/.codex/AGENTS.md` differs from the current bootstrap-lite.md'))
+  if (!checks.homeLink) issues.push(buildDoctorIssue(runtime, 'standby-link-missing', 'standby `~/.codex/helloagents` 链接缺失或未指向稳定运行根目录', 'Standby `~/.codex/helloagents` link is missing or points to a different runtime root'))
+  if (!checks.modelInstructionsFile) issues.push(buildDoctorIssue(runtime, '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(runtime, '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(runtime, 'standby-notify-missing', 'standby notify 配置缺失', 'Standby notify configuration is missing'))
+  if (checks.codexNotify && !checks.notifyPathMatch) issues.push(buildDoctorIssue(runtime, 'standby-notify-drift', 'standby notify 未使用受管命令入口', 'Standby notify does not use the managed command entrypoint'))
+  if (!checks.codexHooksFeature) issues.push(buildDoctorIssue(runtime, 'codex-hooks-feature-disabled', 'Codex hooks 功能被显式关闭', 'Codex hooks feature is explicitly disabled'))
+  if (!checks.standaloneHooks) issues.push(buildDoctorIssue(runtime, 'standby-hooks-missing', 'standby `~/.codex/hooks.json` 缺少 HelloAGENTS hooks', 'Standby `~/.codex/hooks.json` is missing HelloAGENTS hooks'))
+  if (checks.standaloneHooks && !checks.standaloneHooksMatch) issues.push(buildDoctorIssue(runtime, 'standby-hooks-drift', 'standby `~/.codex/hooks.json` 与当前 hooks-codex.json 不一致', 'Standby `~/.codex/hooks.json` differs from the current hooks-codex.json'))
+  if (checks.pluginRoot || checks.pluginCache || checks.marketplaceEntry || checks.pluginEnabled) {
+    issues.push(buildDoctorIssue(runtime, 'standby-global-residue', 'standby 模式下仍残留 global 插件文件或配置', 'Global plugin artifacts still remain while Codex is in standby mode'))
+  }
+}
+
+function appendCodexGlobalIssues(runtime, issues, checks, pluginVersion, cacheVersion) {
+  if (!checks.carrierMarker) issues.push(buildDoctorIssue(runtime, '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(runtime, '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(runtime, '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(runtime, 'global-plugin-root-missing', 'global 插件根目录缺失', 'Global plugin root is missing'))
+  if (!checks.pluginCache) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-missing', 'global 插件缓存目录缺失', 'Global plugin cache directory is missing'))
+  if (checks.pluginRoot && !checks.pluginCarrierMatch) issues.push(buildDoctorIssue(runtime, '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(runtime, '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(runtime, 'global-marketplace-missing', 'global marketplace 条目缺失', 'Global marketplace entry is missing'))
+  if (!checks.pluginEnabled) issues.push(buildDoctorIssue(runtime, 'global-plugin-disabled', 'global config 中缺少插件启用段', 'Global plugin enablement block is missing from config'))
+  if (!checks.modelInstructionsFile) issues.push(buildDoctorIssue(runtime, '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(runtime, '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.codexNotify) issues.push(buildDoctorIssue(runtime, 'global-notify-missing', 'global notify 配置缺失', 'Global notify configuration is missing'))
+  if (checks.codexNotify && !checks.globalNotifyPathMatch) issues.push(buildDoctorIssue(runtime, 'global-notify-drift', 'global notify 未使用受管命令入口', 'Global notify does not use the managed command entrypoint'))
+  if (!checks.codexHooksFeature) issues.push(buildDoctorIssue(runtime, 'codex-hooks-feature-disabled', 'Codex hooks 功能被显式关闭', 'Codex hooks feature is explicitly disabled'))
+  if (!checks.standaloneHooks) issues.push(buildDoctorIssue(runtime, 'global-hooks-missing', 'global `~/.codex/hooks.json` 缺少 HelloAGENTS hooks', 'Global `~/.codex/hooks.json` is missing HelloAGENTS hooks'))
+  if (checks.standaloneHooks && !checks.standaloneHooksMatch) issues.push(buildDoctorIssue(runtime, 'global-hooks-drift', 'global `~/.codex/hooks.json` 与当前 hooks-codex.json 不一致', 'Global `~/.codex/hooks.json` differs from the current hooks-codex.json'))
+  if (pluginVersion && !checks.pluginVersionMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-version-drift', 'global 插件根目录版本与当前包版本不一致', 'Global plugin root version does not match the current package version'))
+  if (cacheVersion && !checks.pluginCacheVersionMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-version-drift', 'global 插件缓存版本与当前包版本不一致', 'Global plugin cache version does not match the current package version'))
+  if (checks.homeLink) issues.push(buildDoctorIssue(runtime, 'global-standby-link-residue', 'global 模式下仍残留 standby home 链接', 'Standby home link still remains while Codex is in global mode'))
+}
+
+function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
+  const codexDir = join(runtime.home, '.codex')
+  const codexConfig = safeRead(join(codexDir, 'config.toml')) || ''
+  const pluginRoot = join(runtime.home, 'plugins', CODEX_PLUGIN_NAME)
+  const pluginCacheRoot = join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME, 'local')
+  const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
+  const expectedHomeCarrier = (detectedMode === 'global' || (detectedMode === 'none' && trackedMode === 'global'))
+    ? 'bootstrap.md'
+    : 'bootstrap-lite.md'
+  const codexHooks = safeJson(join(codexDir, 'hooks.json')) || {}
+  const marketplace = safeJson(join(runtime.home, '.agents', 'plugins', 'marketplace.json')) || {}
+  const modelInstructionsLine = readTopLevelTomlLine(codexConfig, 'model_instructions_file')
+  const expectedHooks = readExpectedHooks(runtime, 'hooks-codex.json', '${PLUGIN_ROOT}')
+  const hooksFeatureLine = readCodexHooksFeatureLine(codexConfig)
+  const goalsFeatureLine = readCodexGoalsFeatureLine(codexConfig)
+  const legacyHooksFeatureLine = readLegacyCodexHooksFeatureLine(codexConfig)
+
+  return {
+    checks: {
+      carrierMarker: (safeRead(join(codexDir, 'AGENTS.md')) || '').includes('HELLOAGENTS_START'),
+      carrierContentMatch: normalizeText((safeRead(join(codexDir, 'AGENTS.md')) || '').match(/<!-- HELLOAGENTS_START -->([\s\S]*?)<!-- HELLOAGENTS_END -->/)?.[1] || '')
+        === readExpectedCarrierContent(runtime, expectedHomeCarrier, settings),
+      homeLink: homeLinkTarget === (safeRealTarget(runtime.pkgRoot) || normalizePath(runtime.pkgRoot)),
+      globalHomeLink: homeLinkTarget === (safeRealTarget(pluginRoot) || normalizePath(pluginRoot)),
+      modelInstructionsFile: !!modelInstructionsLine,
+      modelInstructionsPathMatch: !!modelInstructionsLine && normalizePath(modelInstructionsLine).includes(`"${CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH}"`),
+      codexNotify: codexConfig.includes('codex-notify'),
+      notifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
+      codexHooksFeature: !/^\s*hooks\s*=\s*false\b/.test(hooksFeatureLine)
+        && !/^\s*codex_hooks\s*=\s*false\b/.test(legacyHooksFeatureLine),
+      codexGoalsFeature: /^\s*goals\s*=\s*true\b/.test(goalsFeatureLine),
+      legacyCodexHooksFeature: Boolean(legacyHooksFeatureLine),
+      standaloneHooks: JSON.stringify(codexHooks.hooks || {}).includes('helloagents'),
+      standaloneHooksMatch: managedHooksMatch(codexHooks.hooks || {}, expectedHooks),
+      pluginRoot: existsSync(pluginRoot),
+      pluginCache: existsSync(pluginCacheRoot),
+      pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '') === readExpectedCarrierContent(runtime, 'bootstrap.md', settings),
+      pluginCacheCarrierMatch: normalizeText(safeRead(join(pluginCacheRoot, 'AGENTS.md')) || '') === readExpectedCarrierContent(runtime, 'bootstrap.md', settings),
+      marketplaceEntry: Array.isArray(marketplace.plugins) && marketplace.plugins.some((plugin) => plugin?.name === CODEX_PLUGIN_NAME),
+      pluginEnabled: codexConfig.includes(CODEX_PLUGIN_CONFIG_HEADER) && codexConfig.includes('enabled = true'),
+      globalNotifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
+      pluginVersionMatch: false,
+      pluginCacheVersionMatch: false,
+    },
+    pluginVersion: safeJson(join(pluginRoot, 'package.json'))?.version || '',
+    cacheVersion: safeJson(join(pluginCacheRoot, 'package.json'))?.version || '',
+  }
+}
+
+export function inspectCodexDoctor(runtime, settings) {
+  const host = 'codex'
+  const trackedMode = normalizeDoctorMode(runtime.getTrackedHostMode(settings, host))
+  const detectedMode = normalizeDoctorMode(runtime.detectHostMode(host))
+  const { checks, pluginVersion, cacheVersion } = buildCodexChecks(runtime, settings, trackedMode, detectedMode)
+  checks.pluginVersionMatch = pluginVersion ? pluginVersion === runtime.pkgVersion : false
+  checks.pluginCacheVersionMatch = cacheVersion ? cacheVersion === runtime.pkgVersion : false
+
+  const issues = []
+  const notes = []
+  if (trackedMode !== 'none' && detectedMode !== 'none' && trackedMode !== detectedMode) {
+    issues.push(buildDoctorIssue(runtime, 'tracked-mode-mismatch', '记录模式与检测模式不一致', 'Tracked mode does not match detected mode'))
+  }
+  if (detectedMode === 'standby') appendCodexStandbyIssues(runtime, issues, checks)
+  if (detectedMode === 'global') appendCodexGlobalIssues(runtime, issues, checks, pluginVersion, cacheVersion)
+  if (trackedMode === 'none' && detectedMode !== 'none') {
+    issues.push(buildDoctorIssue(runtime, 'untracked-managed-state', '检测到受管状态，但配置中未记录该 CLI 模式', 'Managed state detected but this CLI mode is not tracked in config'))
+  }
+  if (trackedMode !== 'none' && detectedMode === 'none') {
+    issues.push(buildDoctorIssue(runtime, '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'))
+  if (!checks.pluginCacheVersionMatch && !cacheVersion && detectedMode === 'global') notes.push(runtime.msg('未读到 global 插件缓存版本信息', 'Global plugin cache version was not readable'))
+  if (detectedMode !== 'none' && !checks.codexGoalsFeature) notes.push(runtime.msg('Codex /goal 未启用；如需长程执行，可运行 `helloagents codex goals enable`。', 'Codex /goal is not enabled; run `helloagents codex goals enable` if you need long-running goals.'))
+  if (detectedMode !== 'none' && checks.legacyCodexHooksFeature) notes.push(runtime.msg('检测到旧版 `codex_hooks`；HelloAGENTS 只兼容 Codex 最新版，建议移除旧 key。', 'Legacy `codex_hooks` was detected; HelloAGENTS targets latest Codex only, so remove the old key.'))
+
+  const status = summarizeDoctorStatus(issues, { trackedMode, detectedMode })
+  return { host, label: runtime.getHostLabel(host), trackedMode, detectedMode, status, checks, issues, notes, suggestedFix: suggestCodexDoctorFix(status, trackedMode) }
+}

package/scripts/cli-doctor.mjs

@@ -1,12 +1,8 @@
-import { existsSync, realpathSync } from 'node:fs'
+import { realpathSync } from 'node:fs'
 import { join } from 'node:path'
 
-import { CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_CONFIG_HEADER, CODEX_PLUGIN_NAME } from './cli-codex.mjs'
-import {
-  CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
-  CODEX_MANAGED_NOTIFY_VALUE,
-} from './cli-codex-config.mjs'
 import { DEFAULTS } from './cli-config.mjs'
+import { inspectCodexDoctor as inspectCodexDoctorImpl } from './cli-doctor-codex.mjs'
 import { printDoctorText } from './cli-doctor-render.mjs'
 import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
 import { readTopLevelTomlLine } from './cli-toml.mjs'
@@ -223,111 +219,6 @@ function inspectGeminiDoctor(settings) {
   return { host, label: runtime.getHostLabel(host), trackedMode, detectedMode, status, checks, issues, notes, suggestedFix: suggestDoctorFix(host, status, trackedMode) }
 }
 
-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.homeLink) issues.push(buildDoctorIssue('standby-link-missing', 'standby home 链接缺失或未指向稳定运行根目录', 'Standby home link is missing or points to a different runtime root'))
-  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 does not use the managed command entrypoint'))
-  if (checks.pluginRoot || checks.pluginCache || checks.marketplaceEntry || checks.pluginEnabled) {
-    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 && !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-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.codexNotify) issues.push(buildDoctorIssue('global-notify-missing', 'global notify 配置缺失', 'Global notify configuration is missing'))
-  if (checks.codexNotify && !checks.globalNotifyPathMatch) issues.push(buildDoctorIssue('global-notify-drift', 'global notify 未使用受管命令入口', 'Global notify does not use the managed command entrypoint'))
-  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) {
-    issues.push(buildDoctorIssue('global-standby-link-residue', 'global 模式下仍残留 standby home 链接', 'Standby home link still remains while Codex is in global mode'))
-  }
-}
-
-function inspectCodexDoctor(settings) {
-  const host = 'codex'
-  const trackedMode = normalizeDoctorMode(runtime.getTrackedHostMode(settings, host))
-  const detectedMode = normalizeDoctorMode(runtime.detectHostMode(host))
-  const codexDir = join(runtime.home, '.codex')
-  const codexConfig = safeRead(join(codexDir, 'config.toml')) || ''
-  const pluginRoot = join(runtime.home, 'plugins', CODEX_PLUGIN_NAME)
-  const pluginCacheRoot = join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME, 'local')
-  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 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'))
-      === readExpectedCarrierContent(expectedHomeCarrier, settings),
-    homeLink: homeLinkTarget === pkgRootTarget,
-    globalHomeLink: homeLinkTarget === pluginRootTarget,
-    modelInstructionsFile: !!modelInstructionsLine,
-    modelInstructionsPathMatch: !!modelInstructionsLine
-      && normalizePath(modelInstructionsLine).includes(`"${CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH}"`),
-    codexNotify: codexConfig.includes('codex-notify'),
-    notifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
-    pluginRoot: existsSync(pluginRoot),
-    pluginCache: existsSync(pluginCacheRoot),
-    pluginCarrierMatch: normalizeText(safeRead(join(pluginRoot, 'AGENTS.md')) || '')
-      === readExpectedCarrierContent('bootstrap.md', settings),
-    pluginCacheCarrierMatch: normalizeText(safeRead(join(pluginCacheRoot, 'AGENTS.md')) || '')
-      === readExpectedCarrierContent('bootstrap.md', settings),
-    marketplaceEntry: Array.isArray(marketplace.plugins) && marketplace.plugins.some((plugin) => plugin?.name === CODEX_PLUGIN_NAME),
-    pluginEnabled: codexConfig.includes(CODEX_PLUGIN_CONFIG_HEADER) && codexConfig.includes('enabled = true'),
-    globalNotifyPath: codexConfig.includes('codex-notify'),
-    globalNotifyPathMatch: codexConfig.includes(CODEX_MANAGED_NOTIFY_VALUE),
-    pluginVersionMatch: pluginVersion ? pluginVersion === runtime.pkgVersion : false,
-    pluginCacheVersionMatch: cacheVersion ? cacheVersion === runtime.pkgVersion : false,
-  }
-
-  const issues = []
-  const notes = []
-  if (trackedMode !== 'none' && detectedMode !== 'none' && trackedMode !== detectedMode) {
-    issues.push(buildDoctorIssue('tracked-mode-mismatch', '记录模式与检测模式不一致', 'Tracked mode does not match detected mode'))
-  }
-  if (detectedMode === 'standby') {
-    appendCodexStandbyIssues(issues, checks)
-  }
-  if (detectedMode === 'global') {
-    appendCodexGlobalIssues(issues, checks, pluginVersion, cacheVersion)
-  }
-  if (trackedMode === 'none' && detectedMode !== 'none') {
-    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'))
-  }
-  if (!checks.pluginVersionMatch && !pluginVersion && detectedMode === 'global') {
-    notes.push(runtime.msg('未读到 global 插件根目录版本信息', 'Global plugin root version was not readable'))
-  }
-  if (!checks.pluginCacheVersionMatch && !cacheVersion && detectedMode === 'global') {
-    notes.push(runtime.msg('未读到 global 插件缓存版本信息', 'Global plugin cache version was not readable'))
-  }
-
-  const status = summarizeDoctorStatus(issues, { host, trackedMode, detectedMode })
-  return { host, label: runtime.getHostLabel(host), trackedMode, detectedMode, status, checks, issues, notes, suggestedFix: suggestDoctorFix(host, status, trackedMode) }
-}
-
 function parseDoctorArgs(args) {
   const wantsJson = args.includes('--json')
   const unknownFlags = args.filter((arg) => arg.startsWith('--') && arg !== '--json' && arg !== '--all')
@@ -348,7 +239,7 @@ function parseDoctorArgs(args) {
 function inspectDoctorHost(host, settings) {
   if (host === 'claude') return inspectClaudeDoctor(settings)
   if (host === 'gemini') return inspectGeminiDoctor(settings)
-  return inspectCodexDoctor(settings)
+  return inspectCodexDoctorImpl(runtime, settings)
 }
 
 function buildDoctorReport(host) {

package/scripts/cli-messages.mjs

@@ -112,6 +112,11 @@ ${msg('诊断', 'Diagnostics')}:
   helloagents doctor codex --json
   ${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('Codex /goal', 'Codex /goal')}:
+  helloagents codex goals status
+  helloagents codex goals enable
+  ${msg('仅显式管理 Codex 最新版 [features].goals，不替代 /goal', 'Explicitly manages only latest Codex [features].goals; does not replace /goal')}
+
 ${msg('卸载', 'Uninstall')}:
   helloagents cleanup      ${msg('（推荐先执行，显式清理所有 CLI 注入/链接）', '(recommended first, explicitly cleans CLI injections/links)')}
   npm uninstall -g helloagents