tmuxclihook 0.4.0 → 0.5.0

package/README.md

@@ -12,6 +12,10 @@ tmuxclihook
 # 检查 npm registry 并将全局安装更新到最新版
 tmuxclihook update
 
+# hooks 健康明细（非交互）：每个 CLI 的完整性、判定真源、注册路径、漂移警告
+# 可选参数 claude|codex|opencode 只看一个；exit 1 = 有缺失或漂移
+tmuxclihook check
+
 # 查看版本 / 帮助（version、--version、-v 与 help、--help、-h 等价）
 tmuxclihook --version
 tmuxclihook --help
@@ -39,7 +43,7 @@ hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `T
 | 菜单项 | 说明 |
 |--------|------|
 | 环境检查 | 侦测 tmux(≥3.1) / jq / bash(任意版本) / node(≥18)，显示 `✓ ready`、`✗ missing`、`⚠ outdated`，并在确认后安全修复。检测到 cc-switch（`~/.cc-switch/cc-switch.db`）时追加 sqlite3 项 |
-| 侦测 AI CLI | 扫描 Claude Code / Codex / opencode，显示版本、最低版本和 hooks 状态；不自动安装或升级 AI CLI。cc-switch 环境下 Claude Code 的 hooks 状态由 bash 侧 `install-claude-hooks.sh check`（sqlite 真源）判定 |
+| 侦测 AI CLI | 扫描 Claude Code / Codex / opencode，显示版本、最低版本和 hooks 健康明细（判定真源、缺失原因、注册路径、漂移警告，见下节）；不自动安装或升级 AI CLI。判定全部走 bash 侧 wrapper `check --json`（cc-switch 模式在 bash 内查 sqlite 真源），TUI 只渲染 |
 | 安装 hooks | 选工具（claude/codex/opencode/全部）→ 调 `scripts/install-<tool>-hooks.sh`（路径随当前 source 解析） |
 | 卸载 hooks | 对称卸载本插件 hooks，保留其他工具注册的 hook |
 | 修复 hooks | 完整性检查 → 缺失则重装 |
@@ -47,6 +51,27 @@ hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `T
 | source 管理 | 查看当前生效 source（来源 + 失效警告）；设置本地仓库路径用于开发调试；清除持久化配置恢复默认 |
 | 完整卸载插件 | 停止 Codex monitor、清除聚合状态 `@ai_all_status`、清理历史遗留软链（不删仓库）；`.tmux.conf` 删声明与 `tmux kill-server` 因破坏性仅打印手动指引 |
 
+### hooks 健康明细与漂移收敛
+
+`tmuxclihook check`（子命令）与 TUI「侦测 AI CLI」共用同一份 bash 侧明细：每个 wrapper 的 `check --json` 模式输出单行 JSON（status / 判定真源 mode / 逐事件 registered+alive / opencode plugin 结构指纹 / suppress 标记 / drift）。默认 `check`（无 `--json`）输出逐字节不变（`ok`/`missing` + exit code），TUI 与 tmux 自修复的既有契约不受影响。
+
+**漂移（drift）**：hooks 指向其他安装源但脚本仍存活（典型场景：本地调试切 source 后、volta 换路径后旧包仍可用）。此时功能未坏、check 仍判 `ok`，但 `tmuxclihook check` 与 TUI 会给出 ⚠ 警告并列出旧路径。漂移参照系是**执行中的 wrapper 自身路径**——`tmuxclihook`/TUI 经当前 source 调 wrapper，警告即「已装 hooks 不是当前 source 写的」。
+
+**发现漂移后的收敛（策略不对称）**：
+
+| 配置 | 收敛代价 | 方式 |
+|------|---------|------|
+| Claude Code hooks | 无（install 幂等强收敛） | TUI 选择即收敛 |
+| Codex hooks | 重写 `hooks.json` 使 `trusted_hash` 失效，需重新 Trust all | TUI 显式确认后收敛（`TMUX_AI_FORCE_INSTALL=1` 旁路 no-op 门禁） |
+| opencode plugin | 无信任代价（整文件重写） | TUI 确认后收敛 |
+| `.tmux.conf` 声明 | 无 | 复用「tmux 集成」的原地替换 + 重载 |
+
+非交互场景下 `tmuxclihook check` 只报告并 exit 1，收敛动作需回 TUI（或手动跑对应 `install-<tool>-hooks.sh`；codex 记得带 `TMUX_AI_FORCE_INSTALL=1`）。
+
+### Esc 导航
+
+clack 0.7 只把 ctrl+c 映射为取消（Esc 默认无效果），安装器在 TUI 内把 Esc 转译为合成取消：**主菜单 Esc 退出**、子菜单 Esc 返回主菜单、确认/输入框 Esc 取消。spinner 期间 Esc 静默（避免误触硬退出）；ctrl+c 行为不变。
+
 ### cc-switch 模式（Claude Code）
 
 检测到 `~/.cc-switch/cc-switch.db` 时，Claude Code hooks 的装/卸/修/状态检查全部指向其通用配置（db `settings` 表 `common_config_claude`）——`switch` 命令启动 claude 时会把通用配置合并进实例配置，`~/.claude/settings.json` 与实例文件都会被 cc-switch 覆盖，直接写它们不持久。写入用与 cc-switch 自身一致的 `json_patch` 原子更新，他人 hook 与配置其他字段保留。注意：cc-switch GUI 运行中会把内存缓存写回 db，安装前建议先退出 GUI（脚本会警告）；不经 `switch` 直接运行的 `claude` 读不到 db 里的 hooks。

package/bin/cli.js

@@ -14,10 +14,12 @@ import { checkEnv, detectClis, interactiveShell } from '../src/detect.js';
 import { planBrewRemediation, runBrewAction } from '../src/env.js';
 import { installHooks, uninstallHooks, repairHooks } from '../src/hooks.js';
 import { checkSymlink, checkTmuxConf } from '../src/symlink.js';
+import { checkToolDetail, renderToolDetail, summarizeDetails } from '../src/check-detail.js';
 import { ensureTmuxIntegration, reloadTmux } from '../src/tmuxconf.js';
 import { stopMonitor, clearAggregateStatus, removeSymlinks } from '../src/purge.js';
 import {
   TOOLS,
+  toolById,
   repoExists,
   REPO_ROOT,
   TMUX_ENTRY,
@@ -26,12 +28,24 @@ import {
   refreshSource,
 } from '../src/adapters-meta.js';
 import { setSource, clearSource, getPersistedSource, originLabel } from '../src/source.js';
+import { enableEscapeCancel, setSpinnerActive } from '../src/esc.js';
 import { note, padDisplay } from '../src/tui.js';
 import { updatePackage, CURRENT_VERSION } from '../src/update.js';
 
 const OK = '✓';
 const NO = '✗';
 
+// p.spinner 的包装：spinner 活跃期间 esc.js 不把 Esc 转译为 ctrl+c
+// （否则 Esc 会在 spinner 期间触发 block() 的 process.exit 硬退出）。
+function spinner(...args) {
+  const s = p.spinner(...args);
+  const start = s.start.bind(s);
+  const stop = s.stop.bind(s);
+  s.start = (...a) => { setSpinnerActive(true); return start(...a); };
+  s.stop = (...a) => { setSpinnerActive(false); return stop(...a); };
+  return s;
+}
+
 function renderEnvResults(results, title = '环境依赖') {
   const lines = results.map((result) => {
     const mark = result.status === 'ready' ? OK : result.status === 'outdated' ? '⚠' : NO;
@@ -41,7 +55,7 @@ function renderEnvResults(results, title = '环境依赖') {
 }
 
 async function doctor() {
-  const s = p.spinner();
+  const s = spinner();
   s.start('检查环境依赖');
   const results = await checkEnv();
   s.stop('环境检查完成');
@@ -101,14 +115,14 @@ async function doctor() {
     const entry = entryByKey.get(key);
     if (!entry) continue;
 
-    const s2 = p.spinner();
+    const s2 = spinner();
     s2.start(entry.command);
     const result = await runBrewAction(entry.action, entry.pkg);
     if (result.ok) s2.stop(`${OK} ${entry.name} 修复命令执行完成`);
     else s2.stop(`${NO} ${entry.name} 修复失败: ${result.output}`);
   }
 
-  const verifySpinner = p.spinner();
+  const verifySpinner = spinner();
   verifySpinner.start('重新检查环境依赖');
   const finalResults = await checkEnv();
   verifySpinner.stop('环境复检完成');
@@ -122,7 +136,7 @@ async function doctor() {
 }
 
 async function detectCliMenu() {
-  const s = p.spinner();
+  const s = spinner();
   s.start('侦测已安装的 AI CLI');
   const rows = await detectClis();
   s.stop('侦测完成');
@@ -131,10 +145,88 @@ async function detectCliMenu() {
     if (!r.installed) return `  ${NO} ${padDisplay(r.label, 14)} 未安装`;
     const verMark = r.meetsMin ? OK : '⚠';
     const minNote = r.minVersion && !r.meetsMin ? ` (需 ≥ ${r.minVersion})` : '';
-    const hookNote = r.hooksInstalled ? '已装 hooks' : '未装 hooks';
-    return `  ${verMark} ${padDisplay(r.label, 14)} v${r.version}${minNote}  ${hookNote}`;
+    return `  ${verMark} ${padDisplay(r.label, 14)} v${r.version}${minNote}`;
   });
   note(lines.join('\n'), 'AI CLI');
+
+  // 逐工具 hooks 明细（判定在 bash 侧 check --json，这里只渲染——缺失原因、
+  // 判定真源、注册路径、漂移）。未安装的 CLI 跳过（wrapper 判 missing 无意义）。
+  const details = [];
+  for (const r of rows) {
+    if (!r.installed) continue;
+    const tool = toolById(r.id);
+    if (!tool) continue;
+    const d = await checkToolDetail(tool);
+    details.push(d);
+    note(renderToolDetail(d).join('\n'), `${r.label} hooks 明细`);
+  }
+
+  await offerDriftConvergence(details);
+}
+
+// 漂移收敛入口：检测（check --json 的 drift 字段 + .tmux.conf 的 pointsToCurrent）
+// 与收敛分离。收敛策略不对称——claude 无代价直接收敛；codex 重写即 trusted_hash
+// 失效，必须显式确认；opencode 重写无信任代价，确认一次即可。
+async function offerDriftConvergence(details) {
+  const driftTools = details.filter((d) => d.status !== 'unknown' && d.drift?.drifted);
+  const conf = checkTmuxConf();
+  const confStale = conf.exists && conf.referenced && !conf.pointsToCurrent;
+
+  const options = driftTools.map((d) => ({
+    value: `tool:${d.tool}`,
+    label: `${d.label} hooks 收敛到当前 source`,
+    hint: `旧路径 ${(d.drift.stale || []).join(', ')}`,
+  }));
+  if (confStale) {
+    options.push({ value: 'tmuxconf', label: '.tmux.conf 加载声明更新为当前 source' });
+  }
+  if (options.length === 0) return;
+
+  options.push({ value: '__skip__', label: '← 暂不处理' });
+  p.log.warn('检测到部分配置指向其他安装源（漂移）。功能仍可用，但新安装/自修复只会收敛当前 source。');
+  const sel = await p.select({
+    message: '选择要收敛的项（Esc 跳过）',
+    options,
+  });
+  if (p.isCancel(sel) || sel === '__skip__') return;
+
+  if (sel === 'tmuxconf') {
+    await confirmAndApplyTmuxIntegration(conf);
+    return;
+  }
+
+  const id = sel.slice('tool:'.length);
+  await convergeDrift(id);
+  // 收敛后复检闭环
+  const tool = toolById(id);
+  if (tool) {
+    const d = await checkToolDetail(tool);
+    note(renderToolDetail(d).join('\n'), `${d.label} 收敛后状态`);
+  }
+}
+
+async function convergeDrift(id) {
+  if (id === 'codex') {
+    const go = await p.confirm({
+      message: '重写 ~/.codex/hooks.json 会使 trusted_hash 失效，下次启动 codex 需在 TUI 点 "Trust all and continue" 授信一次。继续收敛？',
+    });
+    if (p.isCancel(go) || !go) { p.log.info('已取消'); return; }
+  } else if (id === 'opencode') {
+    const go = await p.confirm({
+      message: '将重写 plugin 文件指向当前 source（本地插件无需重新授信）。继续收敛？',
+    });
+    if (p.isCancel(go) || !go) { p.log.info('已取消'); return; }
+  }
+  // claude 无代价（install 本就幂等强收敛），选择即确认
+  const r = await installHooks(id, { force: true });
+  if (r.ok) {
+    p.log.success(`${OK} ${id} hooks 已收敛到当前 source`);
+    if (id === 'codex') p.log.warn('下次启动 codex 时选择 "Trust all and continue" 授信一次。');
+    if (r.output) p.log.message(r.output.trim());
+  } else {
+    p.log.error(`${NO} ${id} 收敛失败`);
+    p.log.error(r.output || '未知错误');
+  }
 }
 
 async function pickTool(message) {
@@ -155,7 +247,7 @@ async function runHookAction(action, verb) {
   if (!sel) { p.log.info('返回主菜单'); return; }
   const ids = sel === '__all__' ? TOOLS.map((t) => t.id) : [sel];
   for (const id of ids) {
-    const s = p.spinner();
+    const s = spinner();
     s.start(`${verb} ${id} hooks`);
     const r = await action(id);
     if (r.ok) {
@@ -317,6 +409,9 @@ async function purgeMenu() {
 
 async function main() {
   p.intro('tmux-ai-status 安装器');
+  // clack 0.7 只认 ctrl+c 取消；启用 Esc → 合成 ctrl+c 的转译后，
+  // 主菜单 Esc 退出、子菜单 Esc 返回、confirm/text Esc 取消全部真实生效。
+  enableEscapeCancel();
 
   note(currentSourceLines().join('\n'), 'source 状态');
 
@@ -328,10 +423,10 @@ async function main() {
 
   while (true) {
     const choice = await p.select({
-      message: '选择操作（Esc 在子菜单返回主页面）',
+      message: '选择操作（Esc 退出；子菜单 Esc 返回本菜单）',
       options: [
         { value: 'doctor', label: '环境检查', hint: 'tmux / jq / bash / node' },
-        { value: 'detect', label: '侦测 AI CLI', hint: '版本 + hooks 状态' },
+        { value: 'detect', label: '侦测 AI CLI', hint: '版本 + hooks 明细 + 漂移' },
         { value: 'install', label: '安装 hooks' },
         { value: 'uninstall', label: '卸载 hooks' },
         { value: 'repair', label: '修复 hooks', hint: '完整性检查 + 缺失重装' },
@@ -341,11 +436,9 @@ async function main() {
         { value: 'exit', label: '退出' },
       ],
     });
-    // 主菜单是顶层：Esc（isCancel）不退出程序，留在主菜单；退出仅走「退出」项。
-    if (p.isCancel(choice)) {
-      p.log.info('已在主菜单（退出请选「退出」项）');
-      continue;
-    }
+    // 主菜单是顶层：Esc 经 esc.js 转译为合成 ctrl+c → isCancel，与「退出」项等价
+    // （outro 在循环后统一输出）。子菜单 isCancel → 返回主菜单的既有语义同时被激活。
+    if (p.isCancel(choice)) break;
     if (choice === 'exit') break;
 
     try {
@@ -365,6 +458,37 @@ async function main() {
   p.outro('完成');
 }
 
+// tmuxclihook check [claude|codex|opencode] — hooks 健康明细（非交互）。
+// 判定全在 bash 侧 check --json，这里渲染；末尾附 bash 判不了的两项全局信息
+// （.tmux.conf 加载声明指向、当前 source）。有缺失/漂移/无法判定 → exitCode 1。
+async function runCheckCommand(only) {
+  let tools = TOOLS;
+  if (only) {
+    const t = toolById(only);
+    if (!t) {
+      console.error(`未知工具: ${only}（可选 claude|codex|opencode）`);
+      process.exitCode = 1;
+      return;
+    }
+    tools = [t];
+  }
+  const details = [];
+  for (const t of tools) {
+    const d = await checkToolDetail(t);
+    details.push(d);
+    console.log(`${d.label} hooks：`);
+    console.log(renderToolDetail(d).join('\n'));
+  }
+  const conf = checkTmuxConf();
+  console.log('.tmux.conf：');
+  console.log(`  ${confStatusLine(conf)}`);
+  console.log('source：');
+  for (const line of currentSourceLines()) console.log(line);
+
+  const s = summarizeDetails(details);
+  if (s.hasMissing || s.hasDrift || s.hasError) process.exitCode = 1;
+}
+
 const arg = process.argv[2];
 if (arg === 'update') {
   updatePackage().then((ok) => {
@@ -373,6 +497,11 @@ if (arg === 'update') {
     console.error(err);
     process.exitCode = 1;
   });
+} else if (arg === 'check') {
+  runCheckCommand(process.argv[3]).catch((err) => {
+    console.error(err);
+    process.exitCode = 1;
+  });
 } else if (arg === '--version' || arg === '-v' || arg === 'version') {
   console.log(`tmuxclihook v${CURRENT_VERSION}`);
 } else if (arg === '--help' || arg === '-h' || arg === 'help') {
@@ -381,6 +510,7 @@ if (arg === 'update') {
     '\n' +
     '用法：\n' +
     '  tmuxclihook              打开交互式 TUI 安装器\n' +
+    '  tmuxclihook check        hooks 健康明细（可跟 claude|codex|opencode；exit 1 = 有缺失或漂移）\n' +
     '  tmuxclihook update       检查并更新到 npm 最新版本\n' +
     '  tmuxclihook version      显示版本（--version / -v 等价）\n' +
     '  tmuxclihook help         显示本帮助（--help / -h 等价）',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmuxclihook",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "交互式 TUI 安装器：环境侦测、AI CLI 侦测、tmux-ai-status hooks 装/卸/修、TPM 软链校验",
   "type": "module",
   "bin": {

package/scripts/adapters/claude.sh

@@ -13,6 +13,8 @@
 #   ADAPTER_HOLD_UNMATCHED_PERMISSION "true"|"false" 无请求 ID 时是否保守保持审批态
 #   ADAPTER_INSTALLER         install 脚本绝对路径（供自修复/TUI 调用）
 #   adapter_check_integrity() hooks 是否完整注册本插件（返回 0=完整）
+#   adapter_check_detail()    check --json 明细 JSON 片段（可选实现；仅 install wrapper
+#                             的 check --json 上下文调用，失败输出降级片段不报错）
 #   adapter_install_hooks()   安装 hooks（合并式，保留他人 hook）
 #   adapter_uninstall_hooks() 卸载本插件 hooks
 #
@@ -220,6 +222,63 @@ adapter_check_integrity() {
     return 0
 }
 
+# 明细检查（仅 install wrapper 的 check --json 调用；事件热路径不触达）。
+# stdout 输出单行紧凑 JSON 片段 {"mode":...,"events":{...},"plugin":null,"registeredPaths":[...]}，
+# 由 lib-install-hooks.sh 的 _wrapper_check_json 拼装 tool/status/suppress/drift。
+# 数据源与存活口径（逐条 command test -x）与 adapter_check_integrity 完全一致；
+# status 判定仍由 integrity 本体独立给出，两者永不发散。
+# 任何失败（jq 失败/配置缺失）输出空 events 的降级片段，不 exit 非 0。
+adapter_check_detail() {
+    local mode="file" src="" pairs rows line ev p a
+    if _ccswitch_active; then
+        mode="ccswitch"
+        if ! _ccswitch_dump_common src; then
+            printf '{"mode":"ccswitch","events":{},"plugin":null,"registeredPaths":[]}\n'
+            return 0
+        fi
+    elif [ -f "$ADAPTER_HOOKS_FILE" ]; then
+        src="$ADAPTER_HOOKS_FILE"
+    fi
+    if [ -z "$src" ]; then
+        printf '{"mode":"%s","events":{},"plugin":null,"registeredPaths":[]}\n' "$mode"
+        return 0
+    fi
+    # TSV：event\tscript（不去重、保留零事件——计数与去重交给下游 jq 聚合）
+    pairs=$(jq -r '.hooks as $h |
+        ["SessionStart","SessionEnd","UserPromptSubmit","PreToolUse","PostToolUse",
+         "PostToolUseFailure","PermissionRequest","Notification","Stop","StopFailure"] as $events |
+        $events[] as $e |
+        $h[$e][]?.hooks[]?.command // empty |
+        select(contains("tmux-ai-status")) | split(" ")[0] | "\($e)\t\(.)"' "$src" 2>/dev/null)
+    if [ "$src" != "$ADAPTER_HOOKS_FILE" ]; then
+        rm -f "$src"
+    fi
+    # TSV：event\tscript\talive(0|1)。bash 3.2 无关联数组，逐行展开后由 jq 一次聚合。
+    rows=""
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        ev="${line%%$'\t'*}"
+        p="${line#*$'\t'}"
+        if [ -x "$p" ]; then a=1; else a=0; fi
+        rows="${rows}${ev}"$'\t'"${p}"$'\t'"${a}"$'\n'
+    done <<EOF
+$pairs
+EOF
+    jq -R -s --arg mode "$mode" --arg events "$_CLAUDE_EVENTS" '
+        (reduce ($events | split(" ")[]) as $e
+            ({}; .[$e] = {registered: 0, alive: 0, scriptPaths: []})) as $base
+        | reduce (split("\n") | .[] | select(length > 0) | split("\t")) as $r (
+            $base;
+            .[$r[0]] = {
+                registered: (.[$r[0]].registered + 1),
+                alive: (.[$r[0]].alive + ($r[2] | tonumber)),
+                scriptPaths: ((.[$r[0]].scriptPaths + [$r[1]]) | unique)
+            })
+        | {mode: $mode, events: ., plugin: null,
+           registeredPaths: ([.[] | .scriptPaths[]] | unique)}
+    ' <<<"$rows"
+}
+
 # 安装：合并式更新，保留他人（masko 等）注册的 hook。cc-switch 模式只写库
 # （~/.claude/settings.json 与实例文件都会被 cc-switch 覆盖，写了也不持久）。
 adapter_install_hooks() {

package/scripts/adapters/codex.sh

@@ -74,6 +74,45 @@ adapter_check_integrity() {
 _CODEX_EVENTS="SessionStart UserPromptSubmit PreToolUse PermissionRequest PostToolUse Stop"
 _CODEX_LEGACY_TOML="${CODEX_HOME:-$HOME/.codex}/hooks.toml"
 
+# 明细检查（仅 install wrapper 的 check --json 调用；与 claude adapter 同构）。
+# 差异：无 cc-switch 分支（hooks.json 即文件真源，mode 恒 file）、6 事件、
+# 匹配串为 "tmux-ai-status codex"。失败输出空 events 降级片段，不 exit 非 0。
+adapter_check_detail() {
+    local src="$ADAPTER_HOOKS_FILE" pairs rows line ev p a
+    if [ ! -f "$src" ]; then
+        printf '{"mode":"file","events":{},"plugin":null,"registeredPaths":[]}\n'
+        return 0
+    fi
+    pairs=$(jq -r '.hooks as $h |
+        ["SessionStart","UserPromptSubmit","PreToolUse","PermissionRequest","PostToolUse","Stop"] as $events |
+        $events[] as $e |
+        $h[$e][]?.hooks[]?.command // empty |
+        select(contains("tmux-ai-status codex")) | split(" ")[0] | "\($e)\t\(.)"' "$src" 2>/dev/null)
+    rows=""
+    while IFS= read -r line; do
+        [ -n "$line" ] || continue
+        ev="${line%%$'\t'*}"
+        p="${line#*$'\t'}"
+        if [ -x "$p" ]; then a=1; else a=0; fi
+        rows="${rows}${ev}"$'\t'"${p}"$'\t'"${a}"$'\n'
+    done <<EOF
+$pairs
+EOF
+    jq -R -s --arg mode "file" --arg events "$_CODEX_EVENTS" '
+        (reduce ($events | split(" ")[]) as $e
+            ({}; .[$e] = {registered: 0, alive: 0, scriptPaths: []})) as $base
+        | reduce (split("\n") | .[] | select(length > 0) | split("\t")) as $r (
+            $base;
+            .[$r[0]] = {
+                registered: (.[$r[0]].registered + 1),
+                alive: (.[$r[0]].alive + ($r[2] | tonumber)),
+                scriptPaths: ((.[$r[0]].scriptPaths + [$r[1]]) | unique)
+            })
+        | {mode: $mode, events: ., plugin: null,
+           registeredPaths: ([.[] | .scriptPaths[]] | unique)}
+    ' <<<"$rows"
+}
+
 # 从每个事件数组剔除本插件 group（command 含 tmux-ai-status），事件/hooks 清空后删键。
 _codex_strip_managed() {
     jq '
@@ -99,12 +138,14 @@ _codex_read_existing() {
 # 安装：改写 hooks.json（剥离旧 managed group 后为每事件追加本插件 group），保留他人 hook。
 # no-op if valid：事件齐全且脚本存活时不改写——重写即 trusted_hash 失效（command 路径
 # 变化 → codex 启动要重新 Trust all），跨安装源重复安装因此保持既有授信。
+# TMUX_AI_FORCE_INSTALL=1 旁路 no-op 门禁（漂移收敛专用：hooks 指向其他安装源但脚本
+# 仍存活时 integrity 恒过，普通 install 永远收敛不了；代价由调用方确认 re-trust）。
 # 清理旧 hooks.toml（0.144 不再读取）。trust 无法在 bash 复现，靠用户首启 codex TUI 授信。
 adapter_install_hooks() {
     _install_require_jq
     mkdir -p "$(dirname "$ADAPTER_HOOKS_FILE")" 2>/dev/null || true
     [ -f "$_CODEX_LEGACY_TOML" ] && rm -f "$_CODEX_LEGACY_TOML" && echo "移除旧 hooks.toml（0.144 不再读取）"
-    if adapter_check_integrity; then
+    if adapter_check_integrity && [ -z "${TMUX_AI_FORCE_INSTALL:-}" ]; then
         echo "Codex hooks already installed and valid at $ADAPTER_HOOKS_FILE (no-op, trust preserved)"
         return 0
     fi

package/scripts/adapters/opencode.sh

@@ -56,6 +56,32 @@ adapter_check_integrity() {
     grep -q 'request_id: p.requestID' "$ADAPTER_HOOKS_FILE" 2>/dev/null
 }
 
+# 明细检查（仅 install wrapper 的 check --json 调用）。plugin 模型无逐事件注册数，
+# 明细为 integrity 五段判定拆成的布尔 + HOOK_SCRIPT 提取与存活。失败输出降级片段。
+adapter_check_detail() {
+    local exists="false" marker="false" script="" alive="false"
+    local pa="false" qa="false" pr="false" rid="false"
+    if [ -f "$ADAPTER_HOOKS_FILE" ]; then
+        exists="true"
+        if grep -q "$_OPENCODE_MARKER" "$ADAPTER_HOOKS_FILE" 2>/dev/null; then marker="true"; fi
+        script=$(sed -n 's/^const HOOK_SCRIPT = "\(.*\)"$/\1/p' "$ADAPTER_HOOKS_FILE" 2>/dev/null | head -n 1)
+        if [ -n "$script" ] && [ -x "$script" ]; then alive="true"; fi
+        if grep -q 'case "permission.asked"' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then pa="true"; fi
+        if grep -q 'case "question.asked"' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then qa="true"; fi
+        if grep -q 'case "permission.replied"' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then pr="true"; fi
+        if grep -q 'request_id: p.requestID' "$ADAPTER_HOOKS_FILE" 2>/dev/null; then rid="true"; fi
+    fi
+    jq -cn --arg path "$ADAPTER_HOOKS_FILE" --argjson exists "$exists" --argjson marker "$marker" \
+        --arg script "$script" --argjson alive "$alive" \
+        --argjson pa "$pa" --argjson qa "$qa" --argjson pr "$pr" --argjson rid "$rid" '
+        {mode: "plugin", events: {},
+         plugin: {path: $path, exists: $exists, marker: $marker,
+                  hookScript: $script, hookScriptAlive: $alive,
+                  structure: {permissionAsked: $pa, questionAsked: $qa,
+                              permissionReplied: $pr, requestId: $rid}},
+         registeredPaths: (if ($script | length) > 0 then [$script] else [] end)}'
+}
+
 # 生成 plugin 文件内容。$1 = tmux-ai-status 绝对路径。
 _opencode_plugin_content() {
     local hook_script="$1"
@@ -149,8 +175,9 @@ EOF
 
 # 安装：写出/覆盖 plugin 文件。整文件替换（非合并）——同目录下他人 plugin 文件不受影响。
 # no-op if valid：文件完整且 HOOK_SCRIPT 存活时不重写（避免跨安装源无谓覆盖）。
+# TMUX_AI_FORCE_INSTALL=1 旁路 no-op 门禁（漂移收敛专用；重写无需重新授信）。
 adapter_install_hooks() {
-    if adapter_check_integrity; then
+    if adapter_check_integrity && [ -z "${TMUX_AI_FORCE_INSTALL:-}" ]; then
         echo "opencode plugin already installed and valid at $ADAPTER_HOOKS_FILE (no-op)"
         return 0
     fi

package/scripts/install-claude-hooks.sh

@@ -1,11 +1,13 @@
 #!/bin/bash
 # install-claude-hooks.sh — Claude Code hooks 安装/卸载/检查 wrapper
-# 用法: install-claude-hooks.sh [install|uninstall|check|auto]
+# 用法: install-claude-hooks.sh [install|uninstall|check [--json]|auto]
 #
 # 薄 wrapper：source 公共骨架 + claude adapter，dispatch 到 adapter_install_hooks /
 # adapter_uninstall_hooks。实际逻辑在 scripts/adapters/claude.sh。
 # check：输出 ok/missing（exit 0/1），供 TUI 侦测在 cc-switch 模式下走 bash 侧
 # 完整性判定（sqlite 真源），与非 cc-switch 的文件判定共用同一真相。
+# check --json：单行紧凑明细 JSON（mode/events/plugin/registeredPaths/suppress/drift），
+# 同样 exit 0/1，供 tmuxclihook check 子命令与 TUI 渲染（见 lib-install-hooks.sh）。
 # auto：tmux 入口加载时的自动安装——存在卸载意图标记（suppressed-claude）时不装。
 # 显式 uninstall 成功写标记、显式 install 成功清标记（见 lib-install-hooks.sh）。
 
@@ -22,7 +24,9 @@ case "${1:-install}" in
         _hooks_suppress_write claude
         ;;
     check)
-        if adapter_check_integrity; then
+        if [ "${2:-}" = "--json" ]; then
+            _wrapper_check_json claude
+        elif adapter_check_integrity; then
             echo ok
         else
             echo missing

package/scripts/install-codex-hooks.sh

@@ -1,10 +1,11 @@
 #!/bin/bash
 # install-codex-hooks.sh — Codex CLI hooks 安装/卸载/检查 wrapper（需 codex ≥ 0.144）
-# 用法: install-codex-hooks.sh [install|uninstall|check]
+# 用法: install-codex-hooks.sh [install|uninstall|check [--json]]
 #
 # 薄 wrapper：source 公共骨架 + codex adapter，dispatch 到 adapter_install_hooks /
 # adapter_uninstall_hooks。实际逻辑在 scripts/adapters/codex.sh。
 # check：输出 ok/missing（exit 0/1），供 TUI 侦测走 bash 侧完整性判定。
+# check --json：单行紧凑明细 JSON（mode/events/suppress/drift），同样 exit 0/1。
 # 显式 uninstall 成功写标记、显式 install 成功清标记（见 lib-install-hooks.sh）。
 
 set -o errexit
@@ -20,7 +21,9 @@ case "${1:-install}" in
         _hooks_suppress_write codex
         ;;
     check)
-        if adapter_check_integrity; then
+        if [ "${2:-}" = "--json" ]; then
+            _wrapper_check_json codex
+        elif adapter_check_integrity; then
             echo ok
         else
             echo missing

package/scripts/install-opencode-hooks.sh

@@ -1,10 +1,11 @@
 #!/bin/bash
 # install-opencode-hooks.sh — opencode plugin 安装/卸载/检查 wrapper
-# 用法: install-opencode-hooks.sh [install|uninstall|check]
+# 用法: install-opencode-hooks.sh [install|uninstall|check [--json]]
 #
 # 薄 wrapper：source 公共骨架 + opencode adapter，dispatch 到 adapter_install_hooks /
 # adapter_uninstall_hooks。实际逻辑在 scripts/adapters/opencode.sh。
 # check：输出 ok/missing（exit 0/1），供 TUI 侦测走 bash 侧完整性判定。
+# check --json：单行紧凑明细 JSON（mode/plugin/suppress/drift），同样 exit 0/1。
 # 显式 uninstall 成功写标记、显式 install 成功清标记（见 lib-install-hooks.sh）。
 
 set -o errexit
@@ -20,7 +21,9 @@ case "${1:-install}" in
         _hooks_suppress_write opencode
         ;;
     check)
-        if adapter_check_integrity; then
+        if [ "${2:-}" = "--json" ]; then
+            _wrapper_check_json opencode
+        elif adapter_check_integrity; then
             echo ok
         else
             echo missing

package/scripts/lib-install-hooks.sh

@@ -37,3 +37,41 @@ _hooks_suppress_write() {
     date +%s > "$(_hooks_suppress_file "$1")" 2>/dev/null || true
 }
 _hooks_suppress_clear() { rm -f "$(_hooks_suppress_file "$1")" 2>/dev/null || true; }
+
+# --- check --json：完整性明细 JSON（wrapper 专用，事件热路径不触达）---
+# stdout = 单行紧凑 JSON；exit code 与默认 check 一致（ok→0 / missing→1）。
+# status 判定复用 adapter_check_integrity 本体（同一真源，与 ok/missing 永不发散）；
+# suppress 在 wrapper 层判定（adapter 双上下文不依赖本文件，见各 adapter 头注释）；
+# drift 参照系 = 执行中 wrapper 自身的 _LIB_DIR：Node 侧经 execa 调用的正是其解析出的
+# SCRIPTS_DIR 下的 wrapper，故 _LIB_DIR 即当前 source 的 scripts dir；手动用旧 source
+# 的 wrapper 跑 check 得到「相对该 source 无漂移」也是正确语义（它正是那个源的收敛执行者）。
+_wrapper_check_json() {  # $1=tool id
+    local tool="$1" status="missing" detail suppress
+    if ! command -v jq >/dev/null 2>&1; then
+        printf '{"tool":"%s","status":"missing","mode":"unknown","suppress":false,"events":{},"plugin":null,"registeredPaths":[],"drift":{"drifted":false,"expected":"","currentScriptsDir":"%s","stale":[]},"error":"jq not found"}\n' "$tool" "$_LIB_DIR"
+        exit 1
+    fi
+    detail=$(adapter_check_detail 2>/dev/null) || detail=""
+    [ -n "$detail" ] || detail='{}'
+    if adapter_check_integrity >/dev/null 2>&1; then
+        status="ok"
+    fi
+    if [ -f "$(_hooks_suppress_file "$tool")" ]; then
+        suppress="true"
+    else
+        suppress="false"
+    fi
+    jq -cn --arg tool "$tool" --arg status "$status" --argjson detail "$detail" \
+        --argjson suppress "$suppress" --arg dir "$_LIB_DIR" '
+        ($detail + {tool: $tool, status: $status, suppress: $suppress})
+        | .drift = {
+            expected: ($dir + "/tmux-ai-status"),
+            currentScriptsDir: $dir,
+            stale: (($detail.registeredPaths // [])
+                    | map(select(. != ($dir + "/tmux-ai-status")) ) | unique)
+          }
+        | .drift.drifted = ((.drift.stale | length) > 0)'
+    if [ "$status" != "ok" ]; then
+        exit 1
+    fi
+}

package/scripts/lib-tmux-ai-status.sh

@@ -604,6 +604,13 @@ _maybe_repair_hooks() {
     local installer="${ADAPTER_INSTALLER}"
     if ! _check_hooks_integrity; then
         _ai_log "REPAIR: hooks integrity check failed, reinstalling (${TOOL_ID:-claude})"
-        [ -x "$installer" ] && "$installer" >/dev/null 2>&1 || true
+        # 浮出提示与 SessionStart 修复路径（tmux-ai-status）对齐：修复不再完全静默。
+        # 本函数仅经 _run_refresh 被 tmux hook 事件触发（run-shell 上下文，不在 AI CLI
+        # 同步 hook 路径）；display-message 无 -p 写 client tty 而非调用方 stdout。
+        if [ -x "$installer" ] && "$installer" >/dev/null 2>&1; then
+            tmux display-message "✓ ${TOOL_ID:-claude} hooks 已自动修复（检测到缺失）" 2>/dev/null || true
+        else
+            tmux display-message "⚠ ${TOOL_ID:-claude} hooks 自动修复失败，请运行 tmuxclihook 检查" 2>/dev/null || true
+        fi
     fi
 }

package/scripts/tmux-ai-status

@@ -29,11 +29,12 @@ _save_pane_id
 _maybe_cleanup_stale
 
 # cc-switch 注入的 provider 标签(launch env,CLI 的 hooks 进程继承)→
-# per-pane option,供 build_all_status 聚合渲染。env 随 CLI 进程定死,幂等
-# 重写无害;非 switch 启动(env 缺失)时显式清除残留,避免换 AI 进程后 pane
-# 显示上一个 provider。
+# per-pane option,供 build_all_status 聚合渲染。**仅 codex 捕获**:claude 的
+# provider 标签由 wrapper 在 CLI 内的 statusline 显示,tmux 状态栏刻意不重复
+# 渲染——claude/opencode 的事件一律走清理分支(顺带清掉同 pane 之前的残留)。
+# codex 无 env(非 switch 启动)同样清理。env 随 CLI 进程定死,幂等重写无害。
 if [ -n "$TMUX_PANE" ]; then
-    if [ -n "$CC_SWITCH_PROVIDER" ]; then
+    if [ "$TOOL_ID" = "codex" ] && [ -n "$CC_SWITCH_PROVIDER" ]; then
         tmux set-option -pt "$TMUX_PANE" @ai_provider "$CC_SWITCH_PROVIDER" 2>/dev/null || true
         if [ -n "$CC_SWITCH_PROVIDER_ID" ]; then
             tmux set-option -pt "$TMUX_PANE" @ai_provider_id "$CC_SWITCH_PROVIDER_ID" 2>/dev/null || true

package/src/check-detail.js

@@ -0,0 +1,159 @@
+// check-detail.js — wrapper `check --json` 的解析、规范化与人类可读渲染
+//
+// `tmuxclihook check` 子命令与 TUI「侦测 AI CLI」明细共用；判定逻辑全在 bash 侧
+// （adapter_check_detail + lib-install-hooks.sh 的 _wrapper_check_json），本模块只做
+// 解析与渲染，不重复实现判定（避免两处真源）。status 永远以 bash 的判定为准。
+import { execa } from 'execa';
+
+const OK = '✓';
+const NO = '✗';
+const WARN = '⚠';
+
+const MODE_LABEL = {
+  file: '配置文件',
+  ccswitch: 'cc-switch db（通用配置）',
+  plugin: 'opencode plugin 文件',
+  unknown: '未知',
+};
+
+function defaultRun(tool) {
+  return execa('bash', [tool.installer, 'check', '--json'], { reject: false, timeout: 15000 });
+}
+
+function baseDetail(tool) {
+  return {
+    ok: false,
+    tool: tool.id,
+    label: tool.label,
+    status: 'unknown',
+    mode: 'unknown',
+    suppress: false,
+    events: {},
+    plugin: null,
+    registeredPaths: [],
+    drift: null,
+    error: null,
+    raw: null,
+  };
+}
+
+// 调某工具 wrapper 的 check --json 并解析规范化。
+// 返回 baseDetail 的超集；status='unknown' 表示 wrapper 输出无法采信
+// （脚本缺失 / 输出非 JSON / jq 缺失的 error JSON），error 字段给出原因。
+// run 可注入供单测（沿用 env.test.js 的依赖注入风格）。
+export async function checkToolDetail(tool, { run } = {}) {
+  const runFn = run || defaultRun;
+  let res;
+  try {
+    res = await runFn(tool);
+  } catch (err) {
+    return { ...baseDetail(tool), error: err.shortMessage || String(err) };
+  }
+  const stdout = String(res.stdout ?? '').trim();
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return {
+      ...baseDetail(tool),
+      error: `wrapper 输出不是合法 JSON（exit ${res.exitCode ?? '?'}）：${stdout.slice(0, 200)}`,
+      raw: stdout,
+    };
+  }
+  if (parsed.error) {
+    return {
+      ...baseDetail(tool),
+      status: parsed.status === 'ok' ? 'ok' : 'unknown',
+      mode: parsed.mode || 'unknown',
+      suppress: Boolean(parsed.suppress),
+      events: parsed.events || {},
+      plugin: parsed.plugin ?? null,
+      registeredPaths: parsed.registeredPaths || [],
+      drift: parsed.drift || null,
+      error: parsed.error,
+      raw: stdout,
+    };
+  }
+  const status = parsed.status === 'ok' ? 'ok' : 'missing';
+  return {
+    ...baseDetail(tool),
+    ok: status === 'ok' && res.exitCode === 0,
+    status,
+    mode: parsed.mode || 'unknown',
+    suppress: Boolean(parsed.suppress),
+    events: parsed.events || {},
+    plugin: parsed.plugin ?? null,
+    registeredPaths: parsed.registeredPaths || [],
+    drift: parsed.drift || null,
+    raw: stdout,
+  };
+}
+
+// 渲染单工具明细为人类可读行。drift 行用 ⚠ 前缀（脚本仍可用，功能未坏，
+// 但指向的安装源不是当前 source——收敛入口在 TUI 侧）。
+export function renderToolDetail(detail) {
+  const lines = [];
+  const modeNote = MODE_LABEL[detail.mode] || detail.mode;
+  if (detail.status === 'ok') {
+    lines.push(`  ${OK} hooks 完整（真源：${modeNote}）`);
+  } else if (detail.status === 'missing') {
+    lines.push(`  ${NO} hooks 缺失或损坏（真源：${modeNote}）`);
+  } else {
+    lines.push(`  ${NO} 无法判定：${detail.error || '未知错误'}`);
+  }
+
+  if (detail.suppress) {
+    lines.push(`  ${WARN} 存在卸载意图标记（suppressed-${detail.tool}）：自动修复已被抑制`);
+  }
+
+  // 逐事件缺失明细（cc-switch/文件模式的 tools）
+  if (detail.status === 'missing') {
+    const broken = [];
+    for (const [ev, e] of Object.entries(detail.events || {})) {
+      if (!e || e.registered === 0) broken.push(`    ${NO} ${ev}：未注册`);
+      else if (e.alive === 0) {
+        broken.push(`    ${NO} ${ev}：脚本不可执行（${(e.scriptPaths || []).join(', ') || '未知路径'}）`);
+      }
+    }
+    if (broken.length > 0) {
+      lines.push('  缺失明细：');
+      lines.push(...broken);
+    }
+  }
+
+  // opencode plugin 明细（无逐事件概念，异常按布尔汇总）
+  if (detail.plugin && detail.status === 'missing') {
+    const pl = detail.plugin;
+    if (!pl.exists) {
+      lines.push(`  ${NO} plugin 文件不存在：${pl.path}`);
+    } else {
+      const marks = [];
+      if (!pl.marker) marks.push('缺本插件标记');
+      if (!pl.hookScriptAlive) marks.push('HOOK_SCRIPT 不可执行');
+      for (const [k, v] of Object.entries(pl.structure || {})) {
+        if (!v) marks.push(`缺结构片段 ${k}`);
+      }
+      if (marks.length > 0) lines.push(`  ${NO} plugin 异常：${marks.join('、')}`);
+    }
+  }
+
+  // 注册路径与漂移
+  if (detail.drift?.drifted) {
+    lines.push(`  ${WARN} 漂移：hooks 指向其他安装源（脚本仍可用，check 仍判完整）`);
+    for (const s of detail.drift.stale || []) lines.push(`      旧路径：${s}`);
+    lines.push(`      当前 source 路径：${detail.drift.expected}`);
+  } else if (detail.status !== 'unknown' && (detail.registeredPaths || []).length > 0) {
+    for (const rp of detail.registeredPaths) lines.push(`  注册路径：${rp}`);
+  }
+
+  return lines;
+}
+
+// 多工具汇总（tmuxclihook check 的 exit code 与 TUI 收敛入口判定用）
+export function summarizeDetails(details) {
+  return {
+    hasMissing: details.some((d) => d.status === 'missing'),
+    hasDrift: details.some((d) => d.drift?.drifted),
+    hasError: details.some((d) => d.status === 'unknown'),
+  };
+}

package/src/esc.js

@@ -0,0 +1,33 @@
+// esc.js — 把 Esc 键转译为合成 ctrl+c
+//
+// clack 0.7 的 Prompt 仅把 \x03（ctrl+c）映射为 cancel（core 的 onKeypress 里
+// 唯一的 cancel 触发是 ch === "\x03"），Esc 默认无任何效果——各子菜单的
+// 「Esc 返回」此前只是文案承诺，从未生效。这里在 stdin 上挂全局 keypress
+// 监听，看到 escape 键就向 stdin 注入合成 \x03，复用 clack 既有且经实测的
+// ctrl+c cancel 路径：主菜单 Esc → isCancel → 退出；子菜单 Esc → isCancel →
+// 返回主菜单；confirm/text Esc → isCancel → 各自的取消分支。
+//
+// spinner 期间不转译（与改动前一致：Esc 静默）。原因：clack 的 block() 给
+// \x03 装了 process.exit(0) 的监听，若在 spinner 期间转译，Esc 会硬退出 TUI
+// 且不恢复 raw mode；ctrl+c 行为不变（仍走该路径，与既有行为一致）。
+
+let spinnerDepth = 0;
+
+export function setSpinnerActive(on) {
+  spinnerDepth += on ? 1 : -1;
+  if (spinnerDepth < 0) spinnerDepth = 0;
+}
+
+// 返回解绑函数（进程退出即回收，正常无需调用；导出以便单测）。
+export function enableEscapeCancel() {
+  const onKeypress = (ch, key) => {
+    if (spinnerDepth === 0 && key?.name === 'escape') {
+      // 直接 emit 合成 keypress（ch='\x03'）：clack 的 onKeypress 以 ch === '\x03'
+      // 判定 cancel，对它来说这与真实 ctrl+c 完全同构。不走 stdin.write——
+      // raw mode（-echo）下向 fd 0 写入不会回环成输入。
+      process.stdin.emit('keypress', '\x03', { name: 'c', ctrl: true, sequence: '\x03' });
+    }
+  };
+  process.stdin.on('keypress', onKeypress);
+  return () => process.stdin.off('keypress', onKeypress);
+}

package/src/hooks.js

@@ -4,13 +4,19 @@ import { existsSync } from 'node:fs';
 import { toolById } from './adapters-meta.js';
 import { hooksInstalledAsync } from './detect.js';
 
-// 安装某工具 hooks（调薄 wrapper install-<tool>-hooks.sh）
-export async function installHooks(id) {
+// 安装某工具 hooks（调薄 wrapper install-<tool>-hooks.sh）。
+// force: 传 TMUX_AI_FORCE_INSTALL=1 旁路 codex/opencode 的 no-op if valid 门禁——
+// 漂移收敛专用（hooks 指向其他安装源但脚本存活时 integrity 恒过，普通 install
+// 永远收敛不了）；codex 重写即 trusted_hash 失效，force 前须由调用方确认代价。
+export async function installHooks(id, { force = false } = {}) {
   const tool = toolById(id);
   if (!tool) return { ok: false, output: `未知工具: ${id}` };
   if (!existsSync(tool.installer)) return { ok: false, output: `找不到安装脚本: ${tool.installer}` };
   try {
-    const { stdout } = await execa('bash', [tool.installer], { timeout: 30000 });
+    const { stdout } = await execa('bash', [tool.installer], {
+      timeout: 30000,
+      env: force ? { TMUX_AI_FORCE_INSTALL: '1' } : undefined,
+    });
     return { ok: true, output: stdout };
   } catch (err) {
     return { ok: false, output: err.stderr || err.shortMessage || String(err) };