helloagents 3.0.22 → 3.0.25

package/scripts/cli-codex-hooks-state.mjs

@@ -0,0 +1,264 @@
+import { createHash } from 'node:crypto'
+
+import { isTomlTableHeader, normalizeToml } from './cli-toml.mjs'
+import { removeIfExists, safeJson, safeRead, safeWrite } from './cli-utils.mjs'
+
+const MANAGED_MARKER = '# helloagents-managed'
+
+const HOOK_EVENT_KEY = {
+  PreToolUse: 'pre_tool_use',
+  PermissionRequest: 'permission_request',
+  PostToolUse: 'post_tool_use',
+  PreCompact: 'pre_compact',
+  PostCompact: 'post_compact',
+  SessionStart: 'session_start',
+  UserPromptSubmit: 'user_prompt_submit',
+  Stop: 'stop',
+}
+
+const EVENTS_WITH_MATCHER = new Set([
+  'PreToolUse',
+  'PermissionRequest',
+  'PostToolUse',
+  'PreCompact',
+  'PostCompact',
+  'SessionStart',
+])
+
+const HOOK_STATE_HEADER_RE = /^\[hooks\.state\."((?:\\.|[^"])*)"\](?:\s*#.*)?$/
+
+function normalizeLineEndings(text = '') {
+  return String(text || '').replace(/\r\n/g, '\n')
+}
+
+function escapeTomlBasicString(value = '') {
+  return String(value || '')
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+}
+
+function unescapeTomlBasicString(value = '') {
+  return String(value || '')
+    .replace(/\\"/g, '"')
+    .replace(/\\\\/g, '\\')
+}
+
+function canonicalizeJson(value) {
+  if (Array.isArray(value)) return value.map(canonicalizeJson)
+  if (!value || typeof value !== 'object') return value
+
+  return Object.keys(value)
+    .sort()
+    .reduce((acc, key) => {
+      if (value[key] !== undefined) acc[key] = canonicalizeJson(value[key])
+      return acc
+    }, {})
+}
+
+function hashNormalizedHookIdentity(identity) {
+  const serialized = JSON.stringify(canonicalizeJson(identity))
+  return `sha256:${createHash('sha256').update(serialized).digest('hex')}`
+}
+
+function normalizeHookMatcher(eventName, matcher) {
+  if (!EVENTS_WITH_MATCHER.has(eventName)) return undefined
+  return matcher === undefined ? undefined : String(matcher)
+}
+
+function normalizeHookTimeout(timeout) {
+  const value = Number(timeout)
+  if (!Number.isFinite(value)) return 600
+  return Math.max(1, Math.trunc(value))
+}
+
+function buildHookDescriptor(eventName, group, handler) {
+  return JSON.stringify({
+    eventName,
+    matcher: normalizeHookMatcher(eventName, group?.matcher),
+    command: handler?.command || '',
+  })
+}
+
+function buildNormalizedHookIdentity(eventName, group, handler) {
+  const matcher = normalizeHookMatcher(eventName, group?.matcher)
+  const statusMessage = typeof handler?.statusMessage === 'string'
+    ? handler.statusMessage
+    : undefined
+
+  return {
+    event_name: HOOK_EVENT_KEY[eventName],
+    ...(matcher !== undefined ? { matcher } : {}),
+    hooks: [
+      {
+        type: 'command',
+        command: String(handler?.command || ''),
+        timeout: normalizeHookTimeout(handler?.timeout),
+        async: Boolean(handler?.async),
+        ...(statusMessage !== undefined ? { statusMessage } : {}),
+      },
+    ],
+  }
+}
+
+function isHelloagentsCommandHandler(handler) {
+  return handler?.type === 'command'
+    && typeof handler.command === 'string'
+    && handler.command.includes('helloagents')
+}
+
+function serializeHookStateBlock(entry) {
+  const lines = [`[hooks.state."${escapeTomlBasicString(entry.key)}"]`]
+  if (entry.enabled === false) lines.push('enabled = false')
+  lines.push(`trusted_hash = "${escapeTomlBasicString(entry.trustedHash)}" ${MANAGED_MARKER}`)
+  return lines.join('\n')
+}
+
+function collectHookStateSections(text = '') {
+  const lines = normalizeLineEndings(text).split('\n')
+  const sections = []
+
+  for (let index = 0; index < lines.length; index += 1) {
+    const match = HOOK_STATE_HEADER_RE.exec(lines[index].trim())
+    if (!match) continue
+
+    let end = lines.length
+    for (let cursor = index + 1; cursor < lines.length; cursor += 1) {
+      if (isTomlTableHeader(lines[cursor])) {
+        end = cursor
+        break
+      }
+    }
+
+    const bodyLines = lines.slice(index + 1, end)
+    const enabledLine = bodyLines.find((line) => /^\s*enabled\s*=/.test(line))
+    const trustedHashLine = bodyLines.find((line) => /^\s*trusted_hash\s*=/.test(line))
+    const trustedHashMatch = trustedHashLine?.match(/^\s*trusted_hash\s*=\s*"((?:\\.|[^"])*)"/)
+
+    sections.push({
+      key: unescapeTomlBasicString(match[1]),
+      start: index,
+      end,
+      enabled: /^\s*enabled\s*=\s*false\b/.test(enabledLine || '') ? false : undefined,
+      trustedHash: trustedHashMatch ? unescapeTomlBasicString(trustedHashMatch[1]) : '',
+      managed: lines[index].includes(MANAGED_MARKER)
+        || bodyLines.some((line) => line.includes(MANAGED_MARKER)),
+    })
+
+    index = end - 1
+  }
+
+  return { lines, sections }
+}
+
+function removeHookStateSections(text, shouldRemove) {
+  const { lines, sections } = collectHookStateSections(text)
+  if (!sections.length) return normalizeToml(text)
+
+  const removedStarts = new Set(
+    sections
+      .filter(shouldRemove)
+      .map((section) => section.start),
+  )
+
+  if (!removedStarts.size) return normalizeToml(text)
+
+  const kept = []
+  for (let index = 0; index < lines.length;) {
+    const section = sections.find((item) => item.start === index)
+    if (!section) {
+      kept.push(lines[index])
+      index += 1
+      continue
+    }
+    if (!removedStarts.has(section.start)) {
+      kept.push(...lines.slice(section.start, section.end))
+    }
+    index = section.end
+  }
+
+  return normalizeToml(kept.join('\n'))
+}
+
+function appendHookStateBlocks(text, entries) {
+  if (!entries.length) return normalizeToml(text)
+  const blocks = entries.map(serializeHookStateBlock).join('\n\n')
+  const base = normalizeLineEndings(text).trimEnd()
+  return normalizeToml(base ? `${base}\n\n${blocks}` : blocks)
+}
+
+export function buildManagedCodexHookTrustEntries(hooksPath, hooksData = safeJson(hooksPath)) {
+  const hooks = hooksData?.hooks
+  if (!hooks || typeof hooks !== 'object') return []
+
+  const entries = []
+  for (const eventName of Object.keys(HOOK_EVENT_KEY)) {
+    const groups = hooks[eventName]
+    if (!Array.isArray(groups)) continue
+
+    groups.forEach((group, groupIndex) => {
+      const handlers = Array.isArray(group?.hooks) ? group.hooks : []
+      handlers.forEach((handler, handlerIndex) => {
+        if (!isHelloagentsCommandHandler(handler)) return
+
+        const key = `${hooksPath}:${HOOK_EVENT_KEY[eventName]}:${groupIndex}:${handlerIndex}`
+        entries.push({
+          key,
+          trustedHash: hashNormalizedHookIdentity(
+            buildNormalizedHookIdentity(eventName, group, handler),
+          ),
+          descriptor: buildHookDescriptor(eventName, group, handler),
+        })
+      })
+    })
+  }
+
+  return entries
+}
+
+export function readCodexHookStateSections(text = '') {
+  return collectHookStateSections(text).sections
+}
+
+export function syncManagedCodexHookTrust(configPath, hooksPath, hooksData = safeJson(hooksPath)) {
+  const entries = buildManagedCodexHookTrustEntries(hooksPath, hooksData)
+  if (!entries.length) return cleanupManagedCodexHookTrust(configPath)
+
+  const keySet = new Set(entries.map((entry) => entry.key))
+  const existingText = safeRead(configPath) || ''
+  const existingSections = readCodexHookStateSections(existingText)
+  const enabledByDescriptor = new Map()
+
+  for (const section of existingSections) {
+    if (!keySet.has(section.key) || section.enabled !== false) continue
+    const matchingEntry = entries.find((entry) => entry.key === section.key)
+    if (matchingEntry) enabledByDescriptor.set(matchingEntry.descriptor, false)
+  }
+
+  const cleanedText = removeHookStateSections(
+    existingText,
+    (section) => section.managed || keySet.has(section.key),
+  )
+
+  const nextEntries = entries.map((entry) => ({
+    ...entry,
+    enabled: enabledByDescriptor.get(entry.descriptor),
+  }))
+
+  const nextText = appendHookStateBlocks(cleanedText, nextEntries)
+  if (normalizeLineEndings(nextText) === normalizeLineEndings(existingText)) return false
+
+  safeWrite(configPath, nextText)
+  return true
+}
+
+export function cleanupManagedCodexHookTrust(configPath) {
+  const existingText = safeRead(configPath)
+  if (!existingText) return false
+
+  const nextText = removeHookStateSections(existingText, (section) => section.managed)
+  if (normalizeLineEndings(nextText) === normalizeLineEndings(existingText)) return false
+
+  if (nextText.trim()) safeWrite(configPath, nextText)
+  else removeIfExists(configPath)
+  return true
+}

package/scripts/cli-codex.mjs

@@ -1,8 +1,8 @@
 import { join, dirname } from 'node:path';
 import { existsSync } from 'node:fs';
 import {
-  ensureDir, safeRead, safeWrite, removeIfExists,
-  readJsonOrThrow, copyEntries,
+  ensureDir, safeJson, safeRead, safeWrite, removeIfExists,
+  readJsonOrThrow,
   createLink, removeLink, injectMarkedContent, removeMarkedContent,
   cleanSettingsHooks, loadHooksWithCliEntry, mergeSettingsHooks,
 } from './cli-utils.mjs';
@@ -12,6 +12,7 @@ import {
   CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   CODEX_PLUGIN_CONFIG_HEADER,
   installCodexManagedTopLevelConfig,
+  installCodexManagedTuiConfig,
   isManagedCodexBackupInstruction,
   isManagedCodexGoalsFeature,
   isManagedCodexModelInstruction,
@@ -20,12 +21,17 @@ import {
   readCodexGoalsFeatureLine,
   readLegacyCodexHooksFeatureLine,
   removeCodexGoalsFeatureConfig,
+  removeCodexManagedTuiConfig,
   removeLegacyManagedCodexHooksFeatureConfig,
   removeCodexPluginConfig,
   restoreCodexGoalsFeatureConfig,
   restoreCodexTopLevelConfig,
   upsertCodexPluginConfig,
 } from './cli-codex-config.mjs';
+import {
+  cleanupManagedCodexHookTrust,
+  syncManagedCodexHookTrust,
+} from './cli-codex-hooks-state.mjs';
 import {
   readTopLevelTomlLine,
   readTopLevelTomlBlock,
@@ -132,11 +138,14 @@ function writeCodexRuntimeCarrier(filePath, bootstrapPath, settings) {
 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);
+  const hooksPath = join(home, '.codex', CODEX_HOOKS_BASENAME);
+  mergeSettingsHooks(hooksPath, hooksData);
+  syncManagedCodexHookTrust(join(home, '.codex', CODEX_CONFIG_BASENAME), hooksPath, safeJson(hooksPath));
   return true;
 }
 
 function cleanupCodexStandaloneHooks(home) {
+  cleanupManagedCodexHookTrust(join(home, '.codex', CODEX_CONFIG_BASENAME));
   cleanSettingsHooks(join(home, '.codex', CODEX_HOOKS_BASENAME));
 }
 
@@ -160,6 +169,7 @@ function cleanupCodexManagedConfig(configPath, { removePluginConfig = false } =
   if (shouldRestoreCodexGoalsFeature) {
     toml = removeCodexGoalsFeatureConfig(toml);
   }
+  toml = removeCodexManagedTuiConfig(toml);
   if (shouldRemoveLegacyCodexHooksFeature) {
     toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   }
@@ -209,6 +219,7 @@ export function installCodexStandby(home, pkgRoot) {
   toml = installCodexManagedTopLevelConfig(toml, {
     modelInstructionsPath: CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   });
+  toml = installCodexManagedTuiConfig(toml);
   toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   safeWrite(configPath, toml);
   installCodexStandaloneHooks(home, pkgRoot);
@@ -277,20 +288,15 @@ export function installCodexGlobal(home, pkgRoot) {
   removeIfExists(join(codexDir, 'plugins', 'cache', CODEX_MARKETPLACE_NAME, CODEX_PLUGIN_NAME));
 
   ensureDir(join(home, 'plugins'));
-  ensureDir(installedPluginRoot);
+  ensureDir(dirname(installedPluginRoot));
 
   const settings = readCarrierSettings(home);
-  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'),
-    settings,
-  );
+  createLink(pkgRoot, pluginRoot);
+  createLink(pkgRoot, installedPluginRoot);
+  createLink(pkgRoot, join(codexDir, 'helloagents'));
   writeCodexRuntimeCarrier(
-    join(installedPluginRoot, CODEX_RUNTIME_CARRIER),
-    join(installedPluginRoot, 'bootstrap.md'),
+    join(pkgRoot, CODEX_RUNTIME_CARRIER),
+    join(pkgRoot, 'bootstrap.md'),
     settings,
   );
   const homeCarrierPath = join(codexDir, CODEX_RUNTIME_CARRIER);
@@ -304,6 +310,7 @@ export function installCodexGlobal(home, pkgRoot) {
   toml = installCodexManagedTopLevelConfig(toml, {
     modelInstructionsPath: CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH,
   });
+  toml = installCodexManagedTuiConfig(toml);
   toml = removeLegacyManagedCodexHooksFeatureConfig(toml);
   toml = upsertCodexPluginConfig(toml);
   safeWrite(configPath, toml);

package/scripts/cli-doctor-codex.mjs

@@ -9,6 +9,11 @@ import {
   readCodexHooksFeatureLine,
   readLegacyCodexHooksFeatureLine,
 } from './cli-codex-config.mjs'
+import {
+  buildManagedCodexHookTrustEntries,
+  readCodexHookStateSections,
+} from './cli-codex-hooks-state.mjs'
+import { getStableRuntimeRoot } from './cli-runtime-root.mjs'
 import { buildRuntimeCarrier } from './cli-runtime-carrier.mjs'
 import { readTopLevelTomlLine } from './cli-toml.mjs'
 import { loadHooksWithCliEntry, safeJson, safeRead } from './cli-utils.mjs'
@@ -101,6 +106,8 @@ function appendCodexStandbyIssues(runtime, issues, checks) {
   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.standaloneHooks && !checks.managedHookTrust) issues.push(buildDoctorIssue(runtime, 'standby-hook-trust-missing', 'standby `config.toml` 缺少 HelloAGENTS hooks trust', 'Standby `config.toml` is missing HelloAGENTS hook trust metadata'))
+  if (checks.standaloneHooks && checks.managedHookTrust && !checks.managedHookTrustMatch) issues.push(buildDoctorIssue(runtime, 'standby-hook-trust-drift', 'standby hooks trust 与当前 hooks 定义不一致', 'Standby hook trust metadata differs from the current hooks definition'))
   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'))
   }
@@ -109,9 +116,11 @@ function appendCodexStandbyIssues(runtime, issues, checks) {
 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` 与当前全局模式规则不一致', 'Global `~/.codex/AGENTS.md` differs from the current global rules'))
-  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.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 stable runtime 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.pluginRootLink) issues.push(buildDoctorIssue(runtime, 'global-plugin-root-link-drift', 'global 插件根目录未链接到稳定运行根目录', 'Global plugin root does not link to the stable runtime root'))
+  if (checks.pluginCache && !checks.pluginCacheLink) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-link-drift', 'global 插件缓存未链接到稳定运行根目录', 'Global plugin cache does not link to the stable runtime root'))
   if (checks.pluginRoot && !checks.pluginCarrierMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-carrier-drift', 'global 插件根目录中的 AGENTS.md 与当前全局模式规则不一致', 'Global plugin AGENTS.md differs from the current global rules'))
   if (checks.pluginCache && !checks.pluginCacheCarrierMatch) issues.push(buildDoctorIssue(runtime, 'global-plugin-cache-carrier-drift', 'global 插件缓存中的 AGENTS.md 与当前全局模式规则不一致', 'Global plugin cache AGENTS.md differs from the current global rules'))
   if (!checks.marketplaceEntry) issues.push(buildDoctorIssue(runtime, 'global-marketplace-missing', 'global marketplace 条目缺失', 'Global marketplace entry is missing'))
@@ -123,9 +132,10 @@ function appendCodexGlobalIssues(runtime, issues, checks, pluginVersion, cacheVe
   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 (checks.standaloneHooks && !checks.managedHookTrust) issues.push(buildDoctorIssue(runtime, 'global-hook-trust-missing', 'global `config.toml` 缺少 HelloAGENTS hooks trust', 'Global `config.toml` is missing HelloAGENTS hook trust metadata'))
+  if (checks.standaloneHooks && checks.managedHookTrust && !checks.managedHookTrustMatch) issues.push(buildDoctorIssue(runtime, 'global-hook-trust-drift', 'global hooks trust 与当前 hooks 定义不一致', 'Global hook trust metadata differs from the current hooks definition'))
   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) {
@@ -133,7 +143,10 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
   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 runtimeRoot = safeRealTarget(getStableRuntimeRoot(runtime.home)) || normalizePath(getStableRuntimeRoot(runtime.home))
   const homeLinkTarget = safeRealTarget(join(codexDir, 'helloagents'))
+  const pluginRootTarget = safeRealTarget(pluginRoot)
+  const pluginCacheTarget = safeRealTarget(pluginCacheRoot)
   const expectedHomeCarrier = (detectedMode === 'global' || (detectedMode === 'none' && trackedMode === 'global'))
     ? 'bootstrap.md'
     : 'bootstrap-lite.md'
@@ -141,6 +154,12 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
   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 expectedHookTrust = buildManagedCodexHookTrustEntries(join(codexDir, 'hooks.json'), codexHooks)
+  const managedHookTrust = new Map(
+    readCodexHookStateSections(codexConfig)
+      .filter((section) => section.managed)
+      .map((section) => [section.key, section.trustedHash]),
+  )
   const hooksFeatureLine = readCodexHooksFeatureLine(codexConfig)
   const goalsFeatureLine = readCodexGoalsFeatureLine(codexConfig)
   const legacyHooksFeatureLine = readLegacyCodexHooksFeatureLine(codexConfig)
@@ -151,7 +170,7 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
       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)),
+      globalHomeLink: homeLinkTarget === runtimeRoot,
       modelInstructionsFile: !!modelInstructionsLine,
       modelInstructionsPathMatch: !!modelInstructionsLine && normalizePath(modelInstructionsLine).includes(`"${CODEX_MANAGED_MODEL_INSTRUCTIONS_PATH}"`),
       codexNotify: codexConfig.includes('codex-notify'),
@@ -162,8 +181,12 @@ function buildCodexChecks(runtime, settings, trackedMode, detectedMode) {
       legacyCodexHooksFeature: Boolean(legacyHooksFeatureLine),
       standaloneHooks: JSON.stringify(codexHooks.hooks || {}).includes('helloagents'),
       standaloneHooksMatch: managedHooksMatch(codexHooks.hooks || {}, expectedHooks),
+      managedHookTrust: expectedHookTrust.every((entry) => managedHookTrust.has(entry.key)),
+      managedHookTrustMatch: expectedHookTrust.every((entry) => managedHookTrust.get(entry.key) === entry.trustedHash),
       pluginRoot: existsSync(pluginRoot),
       pluginCache: existsSync(pluginCacheRoot),
+      pluginRootLink: pluginRootTarget === runtimeRoot,
+      pluginCacheLink: pluginCacheTarget === runtimeRoot,
       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),

package/scripts/cli-host-detect.mjs

@@ -6,6 +6,7 @@ import {
   CODEX_PLUGIN_KEY,
   CODEX_PLUGIN_NAME,
 } from './cli-codex.mjs'
+import { getStableRuntimeRoot } from './cli-runtime-root.mjs'
 import { safeJson, safeRead } from './cli-utils.mjs'
 
 const HOST_ALIASES = new Map([
@@ -68,19 +69,18 @@ function detectCodexMode(home) {
   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 runtimeRoot = normalizePath(getStableRuntimeRoot(home))
   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)
-    || codexHomeLinkTarget === globalPluginRoot
   ) {
     return 'global'
   }
   if (
-    (existsSync(codexHomeLink) && codexHomeLinkTarget !== globalPluginRoot)
+    (existsSync(codexHomeLink) && codexHomeLinkTarget === runtimeRoot)
     || hasHelloagentsMarker(join(codexDir, 'AGENTS.md'))
     || codexConfig.includes('codex-notify')
     || codexConfig.includes('HelloAGENTS')

package/scripts/cli-lifecycle.mjs

@@ -59,14 +59,18 @@ function clearTrackedHostMode(settings, host) {
   delete settings.host_install_modes[host]
 }
 
-function setAllTrackedHostModes(settings, mode) {
-  settings.host_install_modes = Object.fromEntries(HOSTS.map((host) => [host, mode]))
-}
-
 function clearAllTrackedHostModes(settings) {
   settings.host_install_modes = {}
 }
 
+function syncTrackedHostMode(settings, host, result, mode) {
+  if (!result?.skipped && result?.ok !== false) {
+    setTrackedHostMode(settings, host, mode)
+    return
+  }
+  clearTrackedHostMode(settings, host)
+}
+
 export function normalizeHost(value = '') {
   return normalizeLifecycleHost(value)
 }
@@ -157,8 +161,11 @@ export function switchMode(newMode) {
     runtime.ok(runtime.msg(`当前已是 ${newMode} 模式，正在刷新安装`, `Already in ${newMode} mode, refreshing installation`))
   }
 
-  installAllHosts(runtime, newMode)
-  setAllTrackedHostModes(config, newMode)
+  const results = installAllHosts(runtime, newMode)
+  clearAllTrackedHostModes(config)
+  for (const host of HOSTS) {
+    syncTrackedHostMode(config, host, results?.[host], newMode)
+  }
   writeSettings(config)
   runtime.printInstallMsg(newMode, isRefresh ? 'refresh' : 'switch')
 }
@@ -229,7 +236,7 @@ export function runScopedLifecycle(action, rawArgs) {
       writeSettings(settings)
     }
   } else if (!result.skipped) {
-    setTrackedHostMode(settings, host, mode)
+    syncTrackedHostMode(settings, host, result, mode)
     writeSettings(settings)
   }
 }

package/scripts/cli-messages.mjs

@@ -87,7 +87,7 @@ HelloAGENTS v${pkgVersion} — The orchestration kernel for AI CLIs
 ${msg('安装', 'Install')}:
   npm install -g helloagents  ${msg('（安装命令并同步稳定运行根目录；CLI 部署需显式执行 helloagents install ...）', '(installs the command and syncs the stable runtime root; deploy to CLIs explicitly with helloagents install ...)')}
   HELLOAGENTS=codex:global npm install -g helloagents
-  helloagents-js.cmd         ${msg('（受管宿主配置的跨平台稳定入口）', '(cross-platform stable entrypoint for managed host configs)')}
+  helloagents-js             ${msg('（受管宿主配置的跨平台稳定入口）', '(cross-platform stable entrypoint for managed host configs)')}
 
 ${msg('模式切换', 'Mode switching')}:
   helloagents --global     ${msg('全局模式（自动尝试 Claude/Gemini 插件或扩展；Codex 自动装原生本地插件）', 'Global mode (auto-attempts Claude/Gemini plugins or extensions; native local plugin auto-install for Codex)')}

package/scripts/cli-utils.mjs

@@ -35,6 +35,7 @@ export function copyEntries(sourceRoot, targetRoot, entries) {
 export function createLink(target, linkPath) {
   removeLink(linkPath);
   try {
+    ensureDir(dirname(linkPath));
     symlinkSync(target, linkPath, IS_WIN ? 'junction' : 'dir');
     return true;
   } catch { return false; }
@@ -132,9 +133,9 @@ export function cleanSettingsHooks(settingsPath, cleanPermissions = false) {
 
 function rewriteHookCommandToCli(command = '', pathVar = '') {
   const replacements = new Map([
-    [`node "${pathVar}/scripts/notify.mjs"`, 'helloagents-js.cmd notify'],
-    [`node "${pathVar}/scripts/guard.mjs"`, 'helloagents-js.cmd guard'],
-    [`node "${pathVar}/scripts/ralph-loop.mjs"`, 'helloagents-js.cmd ralph-loop'],
+    [`node "${pathVar}/scripts/notify.mjs"`, 'helloagents-js notify'],
+    [`node "${pathVar}/scripts/guard.mjs"`, 'helloagents-js guard'],
+    [`node "${pathVar}/scripts/ralph-loop.mjs"`, 'helloagents-js ralph-loop'],
   ]);
 
   let next = command;

package/scripts/delivery-gate.mjs

@@ -5,6 +5,7 @@
  * or when the plan artifacts are incomplete enough that delivery is not trustworthy.
  */
 import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
 import { getAdvisorEvidenceStatus } from './advisor-state.mjs'
 import { getCloseoutEvidenceStatus } from './closeout-state.mjs'
 import { getAdvisorRequirement, getVisualValidationRequirement } from './plan-contract.mjs'
@@ -129,11 +130,15 @@ function collectGateIssues(planEntries, verificationStatus, reviewStatus, adviso
   return issues
 }
 
-function main() {
-  let data = {}
+function readStdinJson() {
   try {
-    data = JSON.parse(readFileSync(0, 'utf-8'))
-  } catch {}
+    return JSON.parse(readFileSync(0, 'utf-8'))
+  } catch {
+    return {}
+  }
+}
+
+export function evaluateDeliveryGate(data = {}) {
   const cwd = data.cwd || process.cwd()
   const workflowOptions = { payload: data }
   const snapshot = getWorkflowSnapshot(cwd, workflowOptions)
@@ -146,8 +151,7 @@ function main() {
     ...workflowOptions,
   })
   if (gatePlans.length === 0) {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }))
-    return
+    return { suppressOutput: true }
   }
 
   const advisorRequirements = gatePlans.map((entry) => getAdvisorRequirement(entry.contract))
@@ -177,15 +181,20 @@ function main() {
 
   const issues = collectGateIssues(gatePlans, verificationStatus, reviewStatus, advisorStatus, visualStatus, closeoutStatus)
   if (issues.length === 0) {
-    process.stdout.write(JSON.stringify({ suppressOutput: true }))
-    return
+    return { suppressOutput: true }
   }
 
-  process.stdout.write(JSON.stringify({
+  return {
     decision: 'block',
     reason: buildDeliveryBlockReason(issues, recommendation, buildDeliveryGateHint(cwd, workflowOptions)),
     suppressOutput: true,
-  }))
+  }
 }
 
-main()
+function main() {
+  process.stdout.write(JSON.stringify(evaluateDeliveryGate(readStdinJson())))
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main()
+}