tmuxclihook 0.5.1 → 0.5.3

package/README.md

@@ -12,7 +12,7 @@ tmuxclihook
 # 按当前安装方式（npm/volta）检查并更新到最新版
 tmuxclihook update
 
-# 升级并直接删除不生效的另一份安装（默认会交互确认）
+# 删除不生效的另一份安装；已是最新时也会执行清理（默认交互确认）
 tmuxclihook update --prune
 
 # hooks 健康明细（非交互）：每个 CLI 的完整性、判定真源、注册路径、漂移警告
@@ -37,11 +37,11 @@ npm start
 
 hooks 安装、tmux 集成写入的路径由「source」决定：环境变量 `TMUXCLIHOOK_SOURCE` > 持久化配置 `~/.config/tmuxclihook/config.json`（TUI「source 管理」菜单写入）> 包内自带 scripts/（生产默认）> 仓库根 scripts/（`cd installer && npm start` 时的开发回落）。见下方「source 管理」一节。
 
-`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本相同则不做修改。需要升级时，它按 PATH 上第一个可执行的 `tmuxclihook` 判断当前生效的安装方式：入口位于 `$VOLTA_HOME/bin/`（默认 `~/.volta/bin/`）或 volta 的 packages 镜像内时，只执行 `volta install tmuxclihook@latest`；其余入口（npm 全局、nvm/fnm 等 node 工具链目录）只执行 `npm install -g tmuxclihook@latest`。不会同时写入两套安装。网络查询或安装失败时命令以非零状态退出。
+`tmuxclihook update` 会显示当前版本，通过 `npm view tmuxclihook version` 查询最新版；版本相同则不做任何安装（若显式传入 `--prune`，仍会执行一次非生效副本检测与清理）。需要升级时，它按 PATH 上第一个可执行的 `tmuxclihook` 判断当前生效的安装方式：入口位于 `$VOLTA_HOME/bin/`（默认 `~/.volta/bin/`）或 volta 的 packages 镜像内时，只执行 `volta install tmuxclihook@latest`；其余入口（npm 全局、nvm/fnm 等 node 工具链目录）只执行 `npm install -g tmuxclihook@latest`。不会同时写入两套安装。网络查询或安装失败时命令以非零状态退出。
 
 安装完成后会按 PATH 自检实际生效版本。若生效入口不是 volta、自检仍未反映新版，且本机可执行 volta，则补执行一次 `volta install tmuxclihook@latest` 作为兜底并复检；仍不一致时打印警告（不影响退出码）。
 
-升级确认成功后，update 会检查另一套安装（volta packages 镜像或当前 npm 全局 prefix）是否还留有副本。发现副本时：TTY 下询问是否删除（默认不删）；非交互环境只打印警告；`--prune` 跳过询问直接删除。删除前会校验该副本未被任何 hooks 与 `~/.tmux.conf` 引用——任一检查无法确认就保留并提示先重装 hooks。**生效入口永远不删**，清理失败不影响升级结果。也可以手动收敛：卸载不再使用的那份（`npm uninstall -g tmuxclihook` 或 `volta uninstall tmuxclihook`），再从生效入口重新安装 hooks。
+升级成功，或版本已是最新且显式传入 `--prune` 时，update 会检查另一套安装（volta packages 镜像或当前 npm 全局 prefix）是否还留有副本。发现副本时：TTY 下询问是否删除（默认不删）；非交互环境只打印警告；`--prune` 跳过询问直接删除。删除前会校验该副本未被任何 hooks 与 `~/.tmux.conf` 引用——任一检查无法确认就保留并提示先重装 hooks。**生效入口永远不删**，清理失败不影响升级结果。也可以手动收敛：卸载不再使用的那份（`npm uninstall -g tmuxclihook` 或 `volta uninstall tmuxclihook`），再从生效入口重新安装 hooks。
 
 ## 功能
 
@@ -79,7 +79,14 @@ clack 0.7 只把 ctrl+c 映射为取消（Esc 默认无效果），安装器在
 
 ### 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。
+检测到 `~/.cc-switch/cc-switch.db` 时，Claude Code hooks 的装/卸/修/状态检查改走 cc-switch 的共享配置。真源位置随 cc-switch 版本自动切换（判定规则与 cc-switch CLI 的 `detectSharedConfigMode` 一致，`CC_SWITCH_SHARED_SOURCE=live|legacy` 可显式覆盖）：
+
+| cc-switch 版本 | 判定 | hooks 真源 / 写入目标 |
+|---|---|---|
+| 4.0.2+（live） | `PRAGMA user_version >= 20` | `~/.claude/settings.json` |
+| 旧版（legacy） | `user_version < 20` 或读不到 | db `settings` 表 `common_config_claude` |
+
+live 模式以 `~/.claude/settings.json` 为共享配置真源（cc-switch 4.0.2 起不再读库里的 `common_config_claude`），写入用与文件模式相同的原子合并，他人 hook 与配置其他字段保留；legacy 模式用与 cc-switch 自身一致的 `json_patch` 更新 db。注意：cc-switch GUI 运行中会把内存缓存写回真源，安装前建议先退出 GUI（脚本会警告）；legacy 模式下不经 `switch` 直接运行的 `claude` 读不到 db 里的 hooks。
 
 ## Source 管理（生产默认 / 本地调试切换）
 

package/bin/cli.js

@@ -31,6 +31,7 @@ import { setSource, clearSource, getPersistedSource, originLabel } from '../src/
 import { enableEscapeCancel, setSpinnerActive } from '../src/esc.js';
 import { note, padDisplay } from '../src/tui.js';
 import { updatePackage, CURRENT_VERSION } from '../src/update.js';
+import { HELP_TEXT } from '../src/help.js';
 
 const OK = '✓';
 const NO = '✗';
@@ -505,17 +506,7 @@ if (arg === 'update') {
 } else if (arg === '--version' || arg === '-v' || arg === 'version') {
   console.log(`tmuxclihook v${CURRENT_VERSION}`);
 } else if (arg === '--help' || arg === '-h' || arg === 'help') {
-  console.log(
-    'tmuxclihook — tmux-ai-status 交互式安装器\n' +
-    '\n' +
-    '用法：\n' +
-    '  tmuxclihook              打开交互式 TUI 安装器\n' +
-    '  tmuxclihook check        hooks 健康明细（可跟 claude|codex|opencode；exit 1 = 有缺失或漂移）\n' +
-    '  tmuxclihook update       按当前安装方式（npm/volta）检查并更新到最新版本\n' +
-    '  tmuxclihook update --prune  升级后直接删除不生效的另一份安装（默认交互确认）\n' +
-    '  tmuxclihook version      显示版本（--version / -v 等价）\n' +
-    '  tmuxclihook help         显示本帮助（--help / -h 等价）',
-  );
+  console.log(HELP_TEXT);
 } else {
   main().catch((err) => {
     console.error(err);

package/package.json

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

package/scripts/adapters/claude.sh

@@ -119,28 +119,54 @@ _claude_count_registered() {  # $1=输入 JSON 文件 → stdout 事件数（jq
 }
 
 # ─── cc-switch 通用配置支持 ───
-# `switch` 命令启动 claude 时把 ~/.cc-switch/cc-switch.db 的通用配置（settings 表
-# common_config_claude，JSON）深合并进实例 settings.json（provider meta 均
-# commonConfigEnabled=true）。~/.claude/settings.json 与实例文件都会被 cc-switch
-# 覆盖，通用配置是 hooks 的唯一持久真源。检测到 cc-switch 时装/卸/完整性只操作
-# 该库；sqlite3 缺失等一切门禁不过 → 整体回退传统文件模式。
+# `switch` 命令启动 claude 时把「共享配置」深合并进实例 settings.json
+# （provider meta 均 commonConfigEnabled=true）。~/.claude/settings.json 与实例
+# 文件都会被 cc-switch 覆盖，共享配置才是 hooks 的唯一持久真源。
+#
+# 共享配置的真源位置随 cc-switch 版本变化（规则与 cc-switch CLI 的
+# detectSharedConfigMode 保持一致）：
+#   - legacy（< 4.0.2 / db PRAGMA user_version < 20）：
+#       真源 = db settings 表的 common_config_claude（JSON）
+#   - live（4.0.2+ / user_version >= 20）：
+#       真源 = ~/.claude/settings.json —— 4.0.2 起 cc-switch 不再读库里的
+#       common_config_claude（仅作迁移快照），所以新机器上写库等于写进死信。
+#   - CC_SWITCH_SHARED_SOURCE=live|legacy 可显式覆盖（cc-switch 同款逃生阀）
+# 门禁不过（db/表/sqlite3 缺失）→ none，整体回退传统文件模式。
 
 _ccswitch_db() { printf '%s\n' "${HOME}/.cc-switch/cc-switch.db"; }
 
-# 门禁：db 存在 && sqlite3 可用 && settings 表可查。不要求 key 存在
-# （从未编辑过通用配置的用户由 install 的 upsert 建行；若此处要求 key，
-# 会静默回退文件模式 → 实例永不含 hooks + 自修复空转）。
-_ccswitch_active() {
-    local db
+# live 模式真源：cc-switch 硬编码 $HOME/.claude/settings.json，
+# 不随 CLAUDE_CONFIG_DIR 变化（后者指向的是 switch 实例目录）。
+_ccswitch_live_file() { printf '%s\n' "${HOME}/.claude/settings.json"; }
+
+# 输出 live|legacy|none；恒返回 0（调用方无需容忍失败分支）。
+_ccswitch_mode() {
+    local db override version
     db="$(_ccswitch_db)"
-    [ -f "$db" ] || return 1
-    command -v sqlite3 >/dev/null 2>&1 || return 1
-    sqlite3 -readonly "$db" \
+    if [ ! -f "$db" ] || ! command -v sqlite3 >/dev/null 2>&1; then
+        printf 'none\n'
+        return 0
+    fi
+    if ! sqlite3 -readonly "$db" \
         "SELECT 1 FROM sqlite_master WHERE type='table' AND name='settings'" 2>/dev/null \
-        | grep -q 1
+        | grep -q 1; then
+        printf 'none\n'
+        return 0
+    fi
+    override=$(printf '%s' "${CC_SWITCH_SHARED_SOURCE:-}" | tr '[:upper:]' '[:lower:]')
+    case "$override" in
+        live|legacy) printf '%s\n' "$override"; return 0 ;;
+    esac
+    # 读不到版本（空/非数字）按 legacy——与 cc-switch CLI 的 null → legacy 一致
+    version=$(sqlite3 -readonly "$db" "PRAGMA user_version" 2>/dev/null | tr -cd '0-9')
+    if [ -n "$version" ] && [ "$version" -ge 20 ]; then
+        printf 'live\n'
+    else
+        printf 'legacy\n'
+    fi
 }
 
-# cc-switch GUI 运行中会把内存缓存的通用配置全量写回 db（实测发生过），警告不阻塞。
+# cc-switch GUI 运行中会把内存缓存的共享配置全量写回真源（实测发生过），警告不阻塞。
 _ccswitch_warn_gui() {
     if pgrep -ix "cc-switch" >/dev/null 2>&1 \
        || pgrep -f "cc-switch.app/Contents/MacOS" >/dev/null 2>&1; then
@@ -190,13 +216,22 @@ ON CONFLICT(key) DO UPDATE SET value = json_patch(settings.value, json($(_sqlquo
 # 存活提取内联在本函数（jq + test），不依赖 lib-install-hooks.sh——本函数同时被
 # 事件路径（lib-tmux-ai-status.sh）与 install wrapper（lib-install-hooks.sh）两个上下文调用。
 adapter_check_integrity() {
-    local src registered ev p ok_events=""
-    if _ccswitch_active; then
-        _ccswitch_dump_common src || return 1
-    else
-        [ -f "$ADAPTER_HOOKS_FILE" ] || return 1
-        src="$ADAPTER_HOOKS_FILE"
-    fi
+    local mode src="" tmp="" registered ev p ok_events=""
+    mode=$(_ccswitch_mode)
+    case "$mode" in
+        live)
+            src=$(_ccswitch_live_file)
+            [ -f "$src" ] || return 1
+            ;;
+        legacy)
+            _ccswitch_dump_common tmp || return 1
+            src="$tmp"
+            ;;
+        *)
+            [ -f "$ADAPTER_HOOKS_FILE" ] || return 1
+            src="$ADAPTER_HOOKS_FILE"
+            ;;
+    esac
     registered=$(_claude_count_registered "$src")
     if [ "${registered:-0}" -ge 10 ]; then
         while IFS=$'\t' read -r ev p; do
@@ -212,9 +247,7 @@ adapter_check_integrity() {
             select(($scripts | length) > 0) |
             $scripts[] | "\($e)\t\(.)"' "$src" 2>/dev/null)
     fi
-    if [ "$src" != "$ADAPTER_HOOKS_FILE" ]; then
-        rm -f "$src"
-    fi
+    [ -z "$tmp" ] || rm -f "$tmp"
     [ "${registered:-0}" -ge 10 ] || return 1
     for ev in SessionStart SessionEnd UserPromptSubmit PreToolUse PostToolUse PostToolUseFailure PermissionRequest Notification Stop StopFailure; do
         case ",$ok_events," in *",$ev,"*) ;; *) return 1 ;; esac
@@ -229,20 +262,38 @@ 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
+    local source_mode src="" tmp="" pairs rows line ev p a
+    source_mode=$(_ccswitch_mode)
+    case "$source_mode" in
+        live)
+            src=$(_ccswitch_live_file)
+            [ -f "$src" ] || src=""
+            ;;
+        legacy)
+            if ! _ccswitch_dump_common tmp; then
+                printf '{"mode":"ccswitch","events":{},"plugin":null,"registeredPaths":[]}\n'
+                return 0
+            fi
+            src="$tmp"
+            ;;
+        *)
+            if [ -f "$ADAPTER_HOOKS_FILE" ]; then src="$ADAPTER_HOOKS_FILE"; fi
+            ;;
+    esac
     if [ -z "$src" ]; then
-        printf '{"mode":"%s","events":{},"plugin":null,"registeredPaths":[]}\n' "$mode"
+        case "$source_mode" in
+            live) source_mode="ccswitch-live" ;;
+            legacy) source_mode="ccswitch" ;;
+            *) source_mode="file" ;;
+        esac
+        printf '{"mode":"%s","events":{},"plugin":null,"registeredPaths":[]}\n' "$source_mode"
         return 0
     fi
+    case "$source_mode" in
+        live) source_mode="ccswitch-live" ;;
+        legacy) source_mode="ccswitch" ;;
+        *) source_mode="file" ;;
+    esac
     # TSV：event\tscript（不去重、保留零事件——计数与去重交给下游 jq 聚合）
     pairs=$(jq -r '.hooks as $h |
         ["SessionStart","SessionEnd","UserPromptSubmit","PreToolUse","PostToolUse",
@@ -250,9 +301,7 @@ adapter_check_detail() {
         $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
+    [ -z "$tmp" ] || rm -f "$tmp"
     # TSV：event\tscript\talive(0|1)。bash 3.2 无关联数组，逐行展开后由 jq 一次聚合。
     rows=""
     while IFS= read -r line; do
@@ -264,7 +313,7 @@ adapter_check_detail() {
     done <<EOF
 $pairs
 EOF
-    jq -R -s --arg mode "$mode" --arg events "$_CLAUDE_EVENTS" '
+    jq -R -s --arg mode "$source_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 (
@@ -279,68 +328,90 @@ EOF
     ' <<<"$rows"
 }
 
-# 安装：合并式更新，保留他人（masko 等）注册的 hook。cc-switch 模式只写库
-# （~/.claude/settings.json 与实例文件都会被 cc-switch 覆盖，写了也不持久）。
+# 安装：合并式更新，保留他人（masko 等）注册的 hook。
+# legacy 模式只写库（~/.claude/settings.json 与实例文件都会被旧版 cc-switch 覆盖）；
+# live 模式（4.0.2+）写 ~/.claude/settings.json —— 新版 cc-switch 以它为共享真源，
+# 实例 settings 在 switch/漂移收敛时从该文件重新派生。
 adapter_install_hooks() {
     _install_require_jq
-    if _ccswitch_active; then
-        local tmp merged hooks_patch full_doc
-        _ccswitch_warn_gui
-        _ccswitch_dump_common tmp || return 1
-        merged=$(_claude_apply_merge "$tmp")
-        rm -f "$tmp"
-        hooks_patch=$(jq -c '{hooks: (.hooks // {})}' <<<"$merged")
-        full_doc=$(jq -c . <<<"$merged")
-        _ccswitch_upsert_hooks "$hooks_patch" "$full_doc" || return 1
-        echo "Claude hooks installed to cc-switch common config: $(_ccswitch_db)"
-        echo "Events: $_CLAUDE_EVENTS"
-        return 0
-    fi
-    [ -f "$ADAPTER_HOOKS_FILE" ] || _install_atomic_write '{}' "$ADAPTER_HOOKS_FILE"
-    local updated
-    updated=$(_claude_apply_merge "$ADAPTER_HOOKS_FILE")
-    _install_atomic_write "$updated" "$ADAPTER_HOOKS_FILE"
-    echo "Claude hooks installed to $ADAPTER_HOOKS_FILE"
+    local mode target updated
+    mode=$(_ccswitch_mode)
+    case "$mode" in
+        legacy)
+            local tmp merged hooks_patch full_doc
+            _ccswitch_warn_gui
+            _ccswitch_dump_common tmp || return 1
+            merged=$(_claude_apply_merge "$tmp")
+            rm -f "$tmp"
+            hooks_patch=$(jq -c '{hooks: (.hooks // {})}' <<<"$merged")
+            full_doc=$(jq -c . <<<"$merged")
+            _ccswitch_upsert_hooks "$hooks_patch" "$full_doc" || return 1
+            echo "Claude hooks installed to cc-switch common config (legacy): $(_ccswitch_db)"
+            echo "Events: $_CLAUDE_EVENTS"
+            return 0
+            ;;
+        live)
+            _ccswitch_warn_gui
+            target=$(_ccswitch_live_file)
+            ;;
+        *)
+            target="$ADAPTER_HOOKS_FILE"
+            ;;
+    esac
+    [ -f "$target" ] || _install_atomic_write '{}' "$target"
+    updated=$(_claude_apply_merge "$target")
+    _install_atomic_write "$updated" "$target"
+    echo "Claude hooks installed to $target"
     echo "Events: $_CLAUDE_EVENTS"
 }
 
 # 卸载：单次 jq pipeline 移除所有指向本插件的 hooks，保留他人条目。
-# cc-switch 模式：剥离前后对照生成 patch（被清空的事件键置 null = RFC 7396 删键），
+# legacy 模式：剥离前后对照生成 patch（被清空的事件键置 null = RFC 7396 删键），
 # 顶层其他字段（model/env/…）由 json_patch 天然保留。
+# live 模式：与文件模式同一套原子写（真源就是 ~/.claude/settings.json）。
 adapter_uninstall_hooks() {
     _install_require_jq
-    if _ccswitch_active; then
-        local tmp stripped cur_hooks final_hooks patch managed top_patch
-        _ccswitch_warn_gui
-        _ccswitch_dump_common tmp || return 1
-        cur_hooks=$(jq -c '.hooks // {}' "$tmp")
-        # 已无本插件条目 → no-op（否则会把保留的他人 hook 重写一遍）
-        managed=$(jq '[to_entries[] | select(.value | any(.hooks[]?.command | contains("tmux-ai-status")))] | length' <<<"$cur_hooks")
-        if [ "${managed:-0}" -eq 0 ]; then
+    local mode target updated
+    mode=$(_ccswitch_mode)
+    case "$mode" in
+        legacy)
+            local tmp stripped cur_hooks final_hooks patch managed top_patch
+            _ccswitch_warn_gui
+            _ccswitch_dump_common tmp || return 1
+            cur_hooks=$(jq -c '.hooks // {}' "$tmp")
+            # 已无本插件条目 → no-op（否则会把保留的他人 hook 重写一遍）
+            managed=$(jq '[to_entries[] | select(.value | any(.hooks[]?.command | contains("tmux-ai-status")))] | length' <<<"$cur_hooks")
+            if [ "${managed:-0}" -eq 0 ]; then
+                rm -f "$tmp"
+                echo "Claude hooks: nothing to uninstall (cc-switch common config)"
+                return 0
+            fi
+            stripped=$(_claude_apply_strip "$tmp")
+            final_hooks=$(jq -c '.hooks // {}' <<<"$stripped")
             rm -f "$tmp"
-            echo "Claude hooks: nothing to uninstall (cc-switch common config)"
-            return 0
-        fi
-        stripped=$(_claude_apply_strip "$tmp")
-        final_hooks=$(jq -c '.hooks // {}' <<<"$stripped")
-        rm -f "$tmp"
-        patch=$(jq -cn --argjson cur "$cur_hooks" --argjson fin "$final_hooks" '
-            reduce ($cur | keys[]) as $k ({};
-                if ($fin | has($k)) then .[$k] = $fin[$k] else .[$k] = null end)')
-        if [ "$patch" = "{}" ]; then
-            echo "Claude hooks: nothing to uninstall (cc-switch common config)"
+            patch=$(jq -cn --argjson cur "$cur_hooks" --argjson fin "$final_hooks" '
+                reduce ($cur | keys[]) as $k ({};
+                    if ($fin | has($k)) then .[$k] = $fin[$k] else .[$k] = null end)')
+            if [ "$patch" = "{}" ]; then
+                echo "Claude hooks: nothing to uninstall (cc-switch common config)"
+                return 0
+            fi
+            # patch 是事件级键，需包一层 {hooks: …} 才是顶层 patch（json_patch 只动 hooks）
+            top_patch=$(jq -cn --argjson p "$patch" '{hooks: $p}')
+            _ccswitch_upsert_hooks "$top_patch" "$top_patch" || return 1
+            echo "Claude hooks uninstalled from cc-switch common config (legacy)"
             return 0
-        fi
-        # patch 是事件级键，需包一层 {hooks: …} 才是顶层 patch（json_patch 只动 hooks）
-        local top_patch
-        top_patch=$(jq -cn --argjson p "$patch" '{hooks: $p}')
-        _ccswitch_upsert_hooks "$top_patch" "$top_patch" || return 1
-        echo "Claude hooks uninstalled from cc-switch common config"
-        return 0
-    fi
-    [ -f "$ADAPTER_HOOKS_FILE" ] || { echo "Claude hooks: nothing to uninstall"; return 0; }
-    local updated
-    updated=$(_claude_apply_strip "$ADAPTER_HOOKS_FILE")
-    _install_atomic_write "$updated" "$ADAPTER_HOOKS_FILE"
-    echo "Claude hooks uninstalled from $ADAPTER_HOOKS_FILE"
+            ;;
+        live)
+            _ccswitch_warn_gui
+            target=$(_ccswitch_live_file)
+            ;;
+        *)
+            target="$ADAPTER_HOOKS_FILE"
+            ;;
+    esac
+    [ -f "$target" ] || { echo "Claude hooks: nothing to uninstall"; return 0; }
+    updated=$(_claude_apply_strip "$target")
+    _install_atomic_write "$updated" "$target"
+    echo "Claude hooks uninstalled from $target"
 }

package/src/adapters-meta.js

@@ -29,8 +29,9 @@ function buildTools(scriptsDir) {
       installer: join(scriptsDir, 'install-claude-hooks.sh'),
       hookMarker: 'tmux-ai-status',
       minHookCount: 10,
-      // cc-switch 存在时 hooks 真源在其 db（通用配置），文件判定失效 → 由 bash 侧
-      // wrapper check 判定（内部走 sqlite）；非 cc-switch 环境仍走本地文件计数。
+      // cc-switch 存在时 hooks 真源随版本变化（4.0.2+ live = ~/.claude/settings.json，
+      // 旧版 legacy = db 通用配置），文件判定失效 → 由 bash 侧 wrapper check 判定
+      // （内部按 db user_version 选真源）；非 cc-switch 环境仍走本地文件计数。
       checkViaWrapper: true,
       ccSwitchDb: join(HOME, '.cc-switch', 'cc-switch.db'),
     },

package/src/check-detail.js

@@ -11,7 +11,8 @@ const WARN = '⚠';
 
 const MODE_LABEL = {
   file: '配置文件',
-  ccswitch: 'cc-switch db（通用配置）',
+  'ccswitch-live': 'cc-switch 4.0+（~/.claude/settings.json）',
+  ccswitch: 'cc-switch 旧版 db（通用配置）',
   plugin: 'opencode plugin 文件',
   unknown: '未知',
 };

package/src/detect.js

@@ -82,7 +82,8 @@ export async function checkEnv({ probeCommand = probe } = {}) {
     pkg: 'node',
   }));
 
-  // sqlite3：仅 cc-switch 环境需要（hooks 真源在其 db 通用配置，装/卸/检查走 sqlite）
+  // sqlite3：cc-switch 环境用于读 db PRAGMA user_version 判定 live/legacy 真源；
+  // legacy 模式（真源在 db 通用配置）的装/卸/检查还依赖它写入。
   const ccSwitchDb = join(homedir(), '.cc-switch', 'cc-switch.db');
   if (existsSync(ccSwitchDb)) {
     const sqlite3 = await probeCommand('sqlite3', ['--version'], /(\d+\.\d+)/);

package/src/help.js

@@ -0,0 +1,31 @@
+// `tmuxclihook help` 的静态文案。独立成模块是为了让测试可以直接 import，
+// 而不必加载 bin/cli.js（入口文件顶层会执行参数分支，未知参数会启动 TUI）。
+const COMMAND_WIDTH = 26;
+
+function line(command, description) {
+  return `  ${command.padEnd(COMMAND_WIDTH)}  ${description}`;
+}
+
+export const HELP_TEXT = [
+  'tmuxclihook — tmux-ai-status 交互式安装器',
+  '',
+  '命令行：',
+  line('tmuxclihook', '打开交互式 TUI 安装器'),
+  line('tmuxclihook check', 'hooks 健康明细（可跟 claude|codex|opencode；exit 1 = 有缺失或漂移）'),
+  line('tmuxclihook update', '按当前安装方式（npm/volta）检查并更新到最新版本'),
+  line('tmuxclihook update --prune', '更新后删除不生效的另一份安装；已是最新时也会执行清理'),
+  line('tmuxclihook version', '显示版本（--version / -v 等价）'),
+  line('tmuxclihook help', '显示本帮助（--help / -h 等价）'),
+  '',
+  'tmux 快捷键（插件加载后生效）：',
+  line('prefix + I', '打开交互式 TUI 安装器'),
+  line('prefix + C-h', '安装 Claude Code hooks'),
+  line('prefix + C-u', '卸载 Claude Code hooks'),
+  line('prefix + M-h', '安装 Codex hooks'),
+  line('prefix + M-u', '卸载 Codex hooks'),
+  line('prefix + C-p', '安装 opencode plugin'),
+  line('prefix + M-p', '卸载 opencode plugin'),
+  line('prefix + r', '重载配置（含本插件初始化）'),
+  '',
+  'prefix 默认是 Ctrl+b；若你在 tmux 配置中改过 prefix，以你的配置为准。',
+].join('\n');

package/src/update.js

@@ -290,6 +290,26 @@ function warnNotEffective(log, result) {
   log.error(`If you use volta, run: volta install ${PACKAGE_NAME}@latest`);
 }
 
+// 清理非生效副本，并在实际删除过副本后复检生效入口。升级成功路径与
+// 「已是最新 + --prune」路径共用，避免两处逻辑漂移。清理失败只记录日志，
+// 不影响 update 的返回值。
+async function reconcileStaleCopies({
+  source, env, run, log, prune, isTTY, confirm,
+  checkHooks, checkTmuxConf, detectStale, verify, expectedVersion,
+}) {
+  try {
+    const removed = await cleanupStale({
+      source, env, run, log, prune, isTTY, confirm, checkHooks, checkTmuxConf, detectStale,
+    });
+    if (removed && verify) {
+      const after = await verify(expectedVersion, env);
+      if (after.status !== 'ok') warnNotEffective(log, after);
+    }
+  } catch (err) {
+    log.error(`Cleanup skipped: ${err}`);
+  }
+}
+
 // volta 安装路径：当 PATH 上的生效入口来自 volta（shim 或 packages 镜像）
 // 时，升级只能走 `volta install`——`npm install -g` 只写 node 工具链目录，
 // 不会更新 volta 的 packages 镜像。此函数现在是 volta 分支的唯一升级动作，
@@ -346,6 +366,20 @@ export async function updatePackage(options = {}) {
 
   if (currentVersion === latestVersion) {
     log.log('Already up to date.');
+
+    // 版本已最新：绝不安装；仅显式 --prune 时收敛非生效副本。
+    // 未传 --prune 时保持历史行为：不探测来源、不清理、直接返回。
+    if (cleanup && prune) {
+      const effectiveSource = typeof detectSource === 'function'
+        ? detectSource(env)
+        : 'unknown';
+      await reconcileStaleCopies({
+        source: effectiveSource, env, run, log, prune, isTTY, confirm,
+        checkHooks, checkTmuxConf, detectStale, verify,
+        expectedVersion: latestVersion,
+      });
+    }
+
     return true;
   }
 
@@ -394,18 +428,11 @@ export async function updatePackage(options = {}) {
 
   // 升级已确认成功后再收敛历史副本；清理失败不影响升级结果，也不改变退出码。
   if (cleanup && result.status === 'ok') {
-    try {
-      const removed = await cleanupStale({
-        source, env, run, log, prune, isTTY, confirm, checkHooks, checkTmuxConf, detectStale,
-      });
-      // 删过东西就再确认一次生效入口，避免误删导致命令不可用。
-      if (removed && verify) {
-        const after = await verify(latestVersion, env);
-        if (after.status !== 'ok') warnNotEffective(log, after);
-      }
-    } catch (err) {
-      log.error(`Cleanup skipped: ${err}`);
-    }
+    await reconcileStaleCopies({
+      source, env, run, log, prune, isTTY, confirm,
+      checkHooks, checkTmuxConf, detectStale, verify,
+      expectedVersion: latestVersion,
+    });
   }
 
   return true;