triflux 9.7.0 → 9.7.1

package/bin/triflux.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // triflux CLI — setup, doctor, version
 import { copyFileSync, existsSync, readFileSync, readSync, writeFileSync, mkdirSync, chmodSync, readdirSync, unlinkSync, statSync, openSync, closeSync } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, basename } from "path";
 import { homedir } from "os";
 import { execSync, execFileSync, spawn } from "child_process";
 import { fileURLToPath } from "url";
@@ -24,6 +24,7 @@ import {
   SYNC_MAP, SKILL_ALIASES, REQUIRED_CODEX_PROFILES, LEGACY_CODEX_MODELS,
   syncAliasedSkillDir, hasProfileSection, replaceProfileSection,
   ensureCodexProfiles, getVersion, cleanupStaleSkills, DEPRECATED_SKILLS,
+  extractManagedHookFilename, getManagedRegistryHooks, ensureHooksInSettings,
 } from "../scripts/setup.mjs";
 
 const PKG_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
@@ -941,6 +942,37 @@ function addDoctorCheck(report, entry) {
   report.checks.push(entry);
 }
 
+function toHookCoverageName(fileName, fallbackId = "") {
+  if (typeof fileName === "string" && fileName.trim()) {
+    return basename(fileName).replace(/\.mjs$/i, "");
+  }
+  return String(fallbackId || "").replace(/^tfx-/, "");
+}
+
+function computeHookCoverage(settings, managedHooks) {
+  const coverage = {
+    total: managedHooks.length,
+    registered: 0,
+    missing: [],
+  };
+
+  const hooksByEvent = settings?.hooks && typeof settings.hooks === "object" ? settings.hooks : {};
+  for (const spec of managedHooks) {
+    const eventEntries = Array.isArray(hooksByEvent[spec.event]) ? hooksByEvent[spec.event] : [];
+    const found = eventEntries.some((entry) =>
+      Array.isArray(entry?.hooks) &&
+      entry.hooks.some((hook) => extractManagedHookFilename(hook?.command) === spec.fileName),
+    );
+    if (found) {
+      coverage.registered++;
+      continue;
+    }
+    coverage.missing.push(toHookCoverageName(spec.fileName, spec.id));
+  }
+
+  return coverage;
+}
+
 function formatPathForDisplay(filePath) {
   const value = String(filePath || "").replace(/\\/g, "/");
   const homePath = homedir().replace(/\\/g, "/");
@@ -1046,6 +1078,7 @@ async function cmdDoctor(options = {}) {
     mode: reset ? "reset" : fix ? "fix" : "check",
     checks: [],
     actions: [],
+    hook_coverage: { total: 0, registered: 0, missing: [] },
     issue_count: 0,
   };
 
@@ -2091,6 +2124,93 @@ async function cmdDoctor(options = {}) {
     }
   }
 
+  // ── Hook Coverage (hook-registry vs settings.json) ──
+  section("Hook Coverage");
+  {
+    const registryPath = join(PKG_ROOT, "hooks", "hook-registry.json");
+    const settingsPath = join(CLAUDE_DIR, "settings.json");
+    const managedHooks = getManagedRegistryHooks(registryPath);
+
+    if (managedHooks.length === 0) {
+      addDoctorCheck(report, {
+        name: "hook-coverage",
+        status: "invalid",
+        total: 0,
+        registered: 0,
+        missing: [],
+        fix: "hook-registry.json을 확인하세요.",
+      });
+      warn("hook-registry.json에서 관리 대상 훅을 찾지 못했습니다.");
+      issues++;
+    } else {
+      let settings = {};
+      if (existsSync(settingsPath)) {
+        try {
+          settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+        } catch (error) {
+          const unreadableCoverage = {
+            total: managedHooks.length,
+            registered: 0,
+            missing: managedHooks.map((spec) => toHookCoverageName(spec.fileName, spec.id)),
+          };
+          report.hook_coverage = unreadableCoverage;
+          addDoctorCheck(report, {
+            name: "hook-coverage",
+            status: "invalid",
+            total: unreadableCoverage.total,
+            registered: unreadableCoverage.registered,
+            missing: unreadableCoverage.missing,
+            fix: "settings.json 문법을 수정하거나 tfx setup을 다시 실행하세요.",
+          });
+          fail(`settings.json 파싱 실패: ${error.message}`);
+          issues++;
+          settings = null;
+        }
+      }
+
+      if (settings) {
+        let coverage = computeHookCoverage(settings, managedHooks);
+
+        if (coverage.missing.length > 0 && fix) {
+          const hookFixResult = ensureHooksInSettings({ settingsPath, registryPath });
+          if (hookFixResult.ok) {
+            if (hookFixResult.changed) {
+              ok(`누락 훅 ${hookFixResult.added.length}개 자동 등록됨`);
+            } else {
+              info("누락 훅 자동 등록: 변경 사항 없음");
+            }
+            try {
+              const fixedSettings = JSON.parse(readFileSync(settingsPath, "utf8"));
+              coverage = computeHookCoverage(fixedSettings, managedHooks);
+            } catch (error) {
+              warn(`자동 등록 후 settings.json 재검증 실패: ${error.message}`);
+            }
+          } else {
+            warn(`누락 훅 자동 등록 실패: ${hookFixResult.reason || "unknown_error"}`);
+          }
+        }
+
+        report.hook_coverage = coverage;
+        const coverageStatus = coverage.missing.length === 0 ? "ok" : "issues";
+        addDoctorCheck(report, {
+          name: "hook-coverage",
+          status: coverageStatus,
+          total: coverage.total,
+          registered: coverage.registered,
+          missing: coverage.missing,
+          ...(coverage.missing.length > 0 ? { fix: "tfx doctor --fix 또는 tfx setup" } : {}),
+        });
+
+        if (coverage.missing.length === 0) {
+          ok(`Hook Coverage: ${coverage.registered}/${coverage.total} registered`);
+        } else {
+          fail(`Missing hooks: ${coverage.missing.join(", ")}`);
+          issues += coverage.missing.length;
+        }
+      }
+    }
+  }
+
   // 결과
   console.log(`\n  ${LINE}`);
   if (issues === 0) {

package/hooks/hook-manager.mjs

@@ -12,16 +12,16 @@
 //
 // Claude 대화에서 AskUserQuestion으로 UI를 제공하며 내부적으로 이 명령들을 호출합니다.
 
-import { readFileSync, writeFileSync, existsSync, copyFileSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
+import { PLUGIN_ROOT } from "./lib/resolve-root.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const HOME = process.env.HOME || process.env.USERPROFILE || "";
 const SETTINGS_PATH = join(HOME, ".claude", "settings.json");
 const BACKUP_PATH = join(HOME, ".claude", "settings.hooks-backup.json");
 const REGISTRY_PATH = join(__dirname, "hook-registry.json");
-const ORCHESTRATOR_PATH = join(__dirname, "hook-orchestrator.mjs");
 
 // ── 유틸리티 ────────────────────────────────────────────────
 
@@ -105,9 +105,9 @@ function normalizeCmd(cmd) {
 }
 
 function resolveVars(cmd) {
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || __dirname.replace(/[\\/]hooks$/, "");
   return cmd
-    .replace(/\$\{PLUGIN_ROOT\}/g, pluginRoot)
+    .replace(/\$\{PLUGIN_ROOT\}/g, PLUGIN_ROOT)
+    .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, PLUGIN_ROOT)
     .replace(/\$\{HOME\}/g, HOME)
     .replace(/\$HOME\b/g, HOME);
 }
@@ -171,7 +171,8 @@ function apply() {
 
   // 오케스트레이터 명령 생성
   const nodeExe = getNodeExe();
-  const orchestratorCmd = `"${nodeExe}" "${ORCHESTRATOR_PATH}"`;
+  const orchestratorPath = "${CLAUDE_PLUGIN_ROOT}/hooks/hook-orchestrator.mjs";
+  const orchestratorCmd = `"${nodeExe}" "${orchestratorPath}"`;
 
   // 모든 이벤트를 하나의 오케스트레이터로 통합
   const newHooks = {};

package/hooks/hook-orchestrator.mjs

@@ -23,6 +23,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFileSync } from "node:child_process";
+import { PLUGIN_ROOT } from "./lib/resolve-root.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REGISTRY_PATH =
@@ -50,10 +51,10 @@ function loadRegistry() {
 // ── 경로 변수 치환 ──────────────────────────────────────────
 function resolveCommand(cmd) {
   const home = process.env.HOME || process.env.USERPROFILE || "";
-  const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT || __dirname.replace(/[\\/]hooks$/, "");
 
   return cmd
-    .replace(/\$\{PLUGIN_ROOT\}/g, pluginRoot)
+    .replace(/\$\{PLUGIN_ROOT\}/g, PLUGIN_ROOT)
+    .replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, PLUGIN_ROOT)
     .replace(/\$\{HOME\}/g, home)
     .replace(/\$HOME\b/g, home);
 }

package/hooks/hook-registry.json

@@ -155,7 +155,7 @@
         "matcher": "*",
         "command": "${HOME}/Desktop/Projects/cli/session-vault/scripts/start_hook.sh",
         "priority": 100,
-        "enabled": true,
+        "enabled": false,
         "timeout": 10,
         "blocking": false,
         "description": "세션 볼트 로깅 시작"
@@ -179,7 +179,7 @@
         "matcher": "*",
         "command": "${HOME}/Desktop/Projects/cli/session-vault/scripts/export_hook.sh",
         "priority": 100,
-        "enabled": true,
+        "enabled": false,
         "timeout": 30,
         "blocking": false,
         "description": "세션 트랜스크립트 내보내기"
@@ -190,7 +190,7 @@
         "matcher": "*",
         "command": "powershell -NoProfile -WindowStyle Hidden -ExecutionPolicy Bypass -File \"${HOME}/.claude/scripts/mcp-cleanup.ps1\"",
         "priority": 100,
-        "enabled": true,
+        "enabled": false,
         "timeout": 8,
         "blocking": false,
         "description": "MCP 고아 프로세스 정리"

package/hooks/lib/resolve-root.mjs

@@ -0,0 +1,59 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const BREADCRUMB_PATH = join(homedir(), ".claude", "scripts", ".tfx-pkg-root");
+
+function normalizeCandidate(candidate) {
+  if (typeof candidate !== "string") return null;
+  const value = candidate.trim();
+  if (!value) return null;
+  return value;
+}
+
+function isValidPluginRoot(candidate) {
+  const root = normalizeCandidate(candidate);
+  if (!root) return false;
+  return existsSync(join(root, "hooks", "hook-orchestrator.mjs"));
+}
+
+function toPluginRootFromUrl(url) {
+  if (typeof url !== "string" || !url) return null;
+  try {
+    const sourceDir = dirname(fileURLToPath(url));
+    const hookScoped = sourceDir.match(/^(.*?)[\\/]hooks(?:[\\/].*)?$/);
+    if (hookScoped?.[1]) return hookScoped[1];
+    return resolve(sourceDir, "..");
+  } catch {
+    return null;
+  }
+}
+
+function readBreadcrumbRoot() {
+  if (!existsSync(BREADCRUMB_PATH)) return null;
+  try {
+    return normalizeCandidate(readFileSync(BREADCRUMB_PATH, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+export function resolvePluginRoot(callerUrl) {
+  const breadcrumbRoot = readBreadcrumbRoot();
+  if (isValidPluginRoot(breadcrumbRoot)) return breadcrumbRoot;
+
+  const envRoot = normalizeCandidate(process.env.CLAUDE_PLUGIN_ROOT);
+  if (isValidPluginRoot(envRoot)) return envRoot;
+
+  const callerFallback = toPluginRootFromUrl(callerUrl);
+  if (isValidPluginRoot(callerFallback)) return callerFallback;
+
+  const moduleFallback = toPluginRootFromUrl(import.meta.url) || process.cwd();
+  process.stderr.write(
+    `[resolve-root] warning: failed to resolve plugin root from breadcrumb/env/caller; fallback=${moduleFallback}\n`
+  );
+  return moduleFallback;
+}
+
+export const PLUGIN_ROOT = resolvePluginRoot(import.meta.url);

package/hooks/pipeline-stop.mjs

@@ -6,20 +6,23 @@
 // 파이프라인이 없으면 정상 종료를 허용한다.
 
 import { existsSync } from "node:fs";
-import { join } from "node:path";
-import { fileURLToPath } from "node:url";
+import { PLUGIN_ROOT } from "./lib/resolve-root.mjs";
 
 let getPipelineStateDbPath;
+let ensurePipelineTable;
+let listPipelineStates;
 try {
-  const stateModule = await import("../hub/pipeline/state.mjs");
-  getPipelineStateDbPath = stateModule.getPipelineStateDbPath;
+  ({
+    getPipelineStateDbPath,
+    ensurePipelineTable,
+    listPipelineStates,
+  } = await import("../hub/pipeline/state.mjs"));
 } catch {
   // hub/pipeline 모듈 없으면 훅 무동작
   process.exit(0);
 }
 
-const PROJECT_ROOT = fileURLToPath(new URL("..", import.meta.url));
-const HUB_DB_PATH = getPipelineStateDbPath(PROJECT_ROOT);
+const HUB_DB_PATH = getPipelineStateDbPath(PLUGIN_ROOT);
 const TERMINAL = new Set(["complete", "failed"]);
 
 async function checkActivePipelines() {
@@ -27,14 +30,6 @@ async function checkActivePipelines() {
 
   try {
     const { default: Database } = await import("better-sqlite3");
-    const { ensurePipelineTable, listPipelineStates } = await import(
-      join(
-        process.env.CLAUDE_PLUGIN_ROOT || PROJECT_ROOT,
-        "hub",
-        "pipeline",
-        "state.mjs"
-      )
-    );
 
     const db = new Database(HUB_DB_PATH, { readonly: true });
     ensurePipelineTable(db);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "9.7.0",
+  "version": "9.7.1",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {

package/scripts/run.cjs

@@ -1,62 +1,79 @@
-#!/usr/bin/env node
-"use strict";
-
-const { execFileSync } = require("child_process");
-const { existsSync, readFileSync } = require("fs");
-const { dirname, isAbsolute, join, resolve } = require("path");
-
-function resolvePluginRoot() {
-  if (process.env.CLAUDE_PLUGIN_ROOT) return process.env.CLAUDE_PLUGIN_ROOT;
-  return dirname(__dirname);
-}
-
-function resolveTargetPath(rawTarget) {
-  if (!rawTarget || typeof rawTarget !== "string") return null;
-
-  const pluginRoot = resolvePluginRoot();
-  const trimmed = rawTarget.trim();
-
-  if (trimmed.startsWith("${CLAUDE_PLUGIN_ROOT}/")) {
-    return join(pluginRoot, trimmed.replace("${CLAUDE_PLUGIN_ROOT}/", ""));
-  }
-
-  if (trimmed.startsWith("/scripts/")) {
-    return join(pluginRoot, trimmed.replace(/^\/+/, ""));
-  }
-
-  if (isAbsolute(trimmed)) return trimmed;
-  return resolve(process.cwd(), trimmed);
-}
-
-const targetArg = process.argv[2];
-if (!targetArg) {
-  process.exit(0);
-}
-
-const targetPath = resolveTargetPath(targetArg);
-if (!targetPath || !existsSync(targetPath)) {
-  process.exit(0);
-}
-
-const stdinBuffer = (() => {
-  try {
-    return readFileSync(0);
-  } catch {
-    return Buffer.alloc(0);
-  }
-})();
-
-try {
-  execFileSync(process.execPath, [targetPath, ...process.argv.slice(3)], {
-    env: process.env,
-    stdio: ["pipe", "inherit", "inherit"],
-    input: stdinBuffer,
-    windowsHide: true
-  });
-  process.exit(0);
-} catch (error) {
-  if (typeof error?.status === "number") {
-    process.exit(error.status);
-  }
-  process.exit(0);
-}
+#!/usr/bin/env node
+"use strict";
+
+const { execFileSync } = require("child_process");
+const { existsSync, readFileSync } = require("fs");
+const { dirname, isAbsolute, join, resolve } = require("path");
+const { homedir } = require("os");
+
+function isValidPluginRoot(candidate) {
+  return typeof candidate === "string"
+    && candidate.trim().length > 0
+    && existsSync(join(candidate.trim(), "hooks", "hook-orchestrator.mjs"));
+}
+
+function resolvePluginRoot() {
+  const breadcrumb = join(homedir(), ".claude", "scripts", ".tfx-pkg-root");
+  if (existsSync(breadcrumb)) {
+    try {
+      const value = readFileSync(breadcrumb, "utf8").trim();
+      if (isValidPluginRoot(value)) return value;
+    } catch {
+      // breadcrumb 읽기 실패 시 다음 fallback
+    }
+  }
+
+  if (isValidPluginRoot(process.env.CLAUDE_PLUGIN_ROOT)) return process.env.CLAUDE_PLUGIN_ROOT;
+  return dirname(__dirname);
+}
+
+function resolveTargetPath(rawTarget) {
+  if (!rawTarget || typeof rawTarget !== "string") return null;
+
+  const pluginRoot = resolvePluginRoot();
+  const trimmed = rawTarget.trim();
+
+  if (trimmed.startsWith("${CLAUDE_PLUGIN_ROOT}/")) {
+    return join(pluginRoot, trimmed.replace("${CLAUDE_PLUGIN_ROOT}/", ""));
+  }
+
+  if (trimmed.startsWith("/scripts/")) {
+    return join(pluginRoot, trimmed.replace(/^\/+/, ""));
+  }
+
+  if (isAbsolute(trimmed)) return trimmed;
+  return resolve(process.cwd(), trimmed);
+}
+
+const targetArg = process.argv[2];
+if (!targetArg) {
+  process.exit(0);
+}
+
+const targetPath = resolveTargetPath(targetArg);
+if (!targetPath || !existsSync(targetPath)) {
+  process.exit(0);
+}
+
+const stdinBuffer = (() => {
+  try {
+    return readFileSync(0);
+  } catch {
+    return Buffer.alloc(0);
+  }
+})();
+
+try {
+  execFileSync(process.execPath, [targetPath, ...process.argv.slice(3)], {
+    env: process.env,
+    stdio: ["pipe", "inherit", "inherit"],
+    input: stdinBuffer,
+    windowsHide: true
+  });
+  process.exit(0);
+} catch (error) {
+  if (typeof error?.status === "number") {
+    process.exit(error.status);
+  }
+  process.exit(0);
+}

package/scripts/setup.mjs

@@ -5,7 +5,7 @@
 // - skills/를 ~/.claude/skills/에 동기화
 
 import { copyFileSync, mkdirSync, readFileSync, writeFileSync, readdirSync, existsSync, chmodSync, unlinkSync, rmSync } from "fs";
-import { join, dirname } from "path";
+import { join, dirname, basename } from "path";
 import { homedir } from "os";
 import { spawn, execFileSync } from "child_process";
 import { fileURLToPath } from "url";
@@ -412,13 +412,253 @@ function ensureCodexProfiles() {
   }
 }
 
+const WINDOWS_DEFAULT_NODE_PATH = "C:/Program Files/nodejs/node.exe";
+const MANAGED_HOOK_FILENAMES = new Set([
+  "safety-guard.mjs",
+  "agent-route-guard.mjs",
+  "cross-review-tracker.mjs",
+  "error-context.mjs",
+  "keyword-detector.mjs",
+  "pipeline-stop.mjs",
+  "subagent-verifier.mjs",
+]);
+
+function toForwardPath(value) {
+  return String(value || "").replace(/\\/g, "/");
+}
+
+function quotePath(value) {
+  return `"${toForwardPath(value)}"`;
+}
+
+function normalizeCommand(value) {
+  return toForwardPath(value).replace(/\s+/g, " ").trim();
+}
+
+function extractManagedHookFilename(command) {
+  if (typeof command !== "string") return null;
+  const matches = command.match(/[A-Za-z0-9._-]+\.mjs/g) || [];
+  for (const match of matches) {
+    const fileName = basename(match);
+    if (MANAGED_HOOK_FILENAMES.has(fileName)) return fileName;
+  }
+  return null;
+}
+
+function isValidManagedHookRoot(candidateRoot) {
+  if (typeof candidateRoot !== "string" || !candidateRoot.trim()) return false;
+  const root = candidateRoot.trim();
+  if (!existsSync(join(root, "hooks", "hook-registry.json"))) return false;
+  if (!existsSync(join(root, "scripts", "run.cjs"))) return false;
+  if (!existsSync(join(root, "scripts", "keyword-detector.mjs"))) return false;
+
+  for (const fileName of MANAGED_HOOK_FILENAMES) {
+    if (!existsSync(join(root, "hooks", fileName))) return false;
+  }
+
+  return true;
+}
+
+function resolveHookPluginRoot() {
+  const envRoot = process.env.PLUGIN_ROOT || process.env.CLAUDE_PLUGIN_ROOT;
+  if (isValidManagedHookRoot(envRoot)) {
+    return toForwardPath(envRoot.trim());
+  }
+
+  try {
+    const npmCmd = process.platform === "win32" ? "npm.cmd" : "npm";
+    const npmGlobalRoot = execFileSync(npmCmd, ["root", "-g"], {
+      encoding: "utf8",
+      timeout: 5000,
+      stdio: ["ignore", "pipe", "ignore"],
+      windowsHide: true,
+    }).trim();
+    const npmPluginRoot = npmGlobalRoot ? join(npmGlobalRoot, "triflux") : "";
+    if (isValidManagedHookRoot(npmPluginRoot)) {
+      return toForwardPath(npmPluginRoot);
+    }
+  } catch {
+    // npm global root 조회 실패 시 로컬 패키지 루트를 fallback으로 사용
+  }
+
+  return toForwardPath(PLUGIN_ROOT);
+}
+
+function resolveManagedNodePath() {
+  if (process.platform === "win32" && existsSync(WINDOWS_DEFAULT_NODE_PATH)) {
+    return toForwardPath(WINDOWS_DEFAULT_NODE_PATH);
+  }
+  return toForwardPath(process.execPath || "node");
+}
+
+function buildManagedHookCommand(fileName, { pluginRoot, nodePath }) {
+  if (fileName === "keyword-detector.mjs") {
+    const runScript = join(pluginRoot, "scripts", "run.cjs");
+    const detectorScript = join(pluginRoot, "scripts", "keyword-detector.mjs");
+    return `${quotePath(nodePath)} ${quotePath(runScript)} ${quotePath(detectorScript)}`;
+  }
+  const hookPath = join(pluginRoot, "hooks", fileName);
+  return `${quotePath(nodePath)} ${quotePath(hookPath)}`;
+}
+
+function getManagedRegistryHooks(registryPath = join(PLUGIN_ROOT, "hooks", "hook-registry.json")) {
+  if (!existsSync(registryPath)) return [];
+
+  let registry;
+  try {
+    registry = JSON.parse(readFileSync(registryPath, "utf8"));
+  } catch {
+    return [];
+  }
+
+  const hooks = [];
+  for (const [event, eventEntries] of Object.entries(registry.events || {})) {
+    if (!Array.isArray(eventEntries)) continue;
+
+    for (const eventEntry of eventEntries) {
+      if (!eventEntry || eventEntry.enabled === false || eventEntry.source !== "triflux") continue;
+      const fileName = extractManagedHookFilename(eventEntry.command);
+      if (!fileName) continue;
+
+      hooks.push({
+        id: String(eventEntry.id || fileName.replace(/\.mjs$/i, "")),
+        event: String(event),
+        matcher: String(eventEntry.matcher || "*"),
+        fileName,
+        timeout: Number.isFinite(eventEntry.timeout) ? eventEntry.timeout : undefined,
+        blocking: typeof eventEntry.blocking === "boolean" ? eventEntry.blocking : undefined,
+        priority: Number.isFinite(eventEntry.priority) ? eventEntry.priority : undefined,
+      });
+    }
+  }
+
+  return hooks;
+}
+
+function ensureHooksInSettings({
+  settingsPath = join(homedir(), ".claude", "settings.json"),
+  registryPath = join(PLUGIN_ROOT, "hooks", "hook-registry.json"),
+  pluginRoot = resolveHookPluginRoot(),
+  nodePath = resolveManagedNodePath(),
+} = {}) {
+  const managedHooks = getManagedRegistryHooks(registryPath);
+  if (managedHooks.length === 0) {
+    return {
+      ok: false,
+      changed: false,
+      total: 0,
+      added: [],
+      reason: "registry_unavailable",
+    };
+  }
+
+  let settings = {};
+  if (existsSync(settingsPath)) {
+    try {
+      settings = JSON.parse(readFileSync(settingsPath, "utf8"));
+    } catch (error) {
+      return {
+        ok: false,
+        changed: false,
+        total: managedHooks.length,
+        added: [],
+        reason: `settings_parse_failed:${error.message}`,
+      };
+    }
+  }
+  if (!settings.hooks || typeof settings.hooks !== "object") settings.hooks = {};
+
+  const added = [];
+  for (const hookSpec of managedHooks) {
+    if (!Array.isArray(settings.hooks[hookSpec.event])) settings.hooks[hookSpec.event] = [];
+    const eventEntries = settings.hooks[hookSpec.event];
+    const expectedCommand = buildManagedHookCommand(hookSpec.fileName, { pluginRoot, nodePath });
+    const expectedNormalizedCommand = normalizeCommand(expectedCommand);
+
+    // 중복 체크: (1) 정확한 command 일치 또는 (2) 같은 파일명의 훅이 이미 등록됨
+    const hasSameMatcherAndCommand = eventEntries.some((entry) =>
+      entry?.matcher === hookSpec.matcher &&
+      Array.isArray(entry.hooks) &&
+      entry.hooks.some((hook) => {
+        if (normalizeCommand(hook?.command) === expectedNormalizedCommand) return true;
+        // pluginRoot가 달라도 같은 훅 파일이면 중복으로 판단
+        const existingFileName = extractManagedHookFilename(hook?.command);
+        return existingFileName === hookSpec.fileName;
+      }),
+    );
+    if (hasSameMatcherAndCommand) continue;
+
+    const hookEntry = {
+      type: "command",
+      command: expectedCommand,
+    };
+    if (Number.isFinite(hookSpec.timeout)) hookEntry.timeout = hookSpec.timeout;
+    if (typeof hookSpec.blocking === "boolean") hookEntry.blocking = hookSpec.blocking;
+    if (Number.isFinite(hookSpec.priority)) hookEntry.priority = hookSpec.priority;
+
+    const matcherEntry = eventEntries.find(
+      (entry) => entry?.matcher === hookSpec.matcher && Array.isArray(entry.hooks),
+    );
+    if (matcherEntry) {
+      matcherEntry.hooks.push(hookEntry);
+    } else {
+      eventEntries.push({ matcher: hookSpec.matcher, hooks: [hookEntry] });
+    }
+
+    added.push({
+      id: hookSpec.id,
+      event: hookSpec.event,
+      matcher: hookSpec.matcher,
+      fileName: hookSpec.fileName,
+    });
+  }
+
+  if (added.length === 0) {
+    return {
+      ok: true,
+      changed: false,
+      total: managedHooks.length,
+      added: [],
+    };
+  }
+
+  let backupPath = null;
+  try {
+    if (existsSync(settingsPath)) {
+      backupPath = `${settingsPath}.bak.${Date.now()}`;
+      copyFileSync(settingsPath, backupPath);
+    } else {
+      const settingsDir = dirname(settingsPath);
+      if (!existsSync(settingsDir)) mkdirSync(settingsDir, { recursive: true });
+    }
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+  } catch (error) {
+    return {
+      ok: false,
+      changed: false,
+      total: managedHooks.length,
+      added,
+      backupPath,
+      reason: `settings_write_failed:${error.message}`,
+    };
+  }
+
+  return {
+    ok: true,
+    changed: true,
+    total: managedHooks.length,
+    added,
+    backupPath,
+  };
+}
+
 export {
   replaceProfileSection, hasProfileSection, escapeRegExp, detectDevMode,
   SYNC_MAP, BREADCRUMB_PATH, PLUGIN_ROOT, CLAUDE_DIR,
   SKILL_ALIASES, REQUIRED_CODEX_PROFILES,
   DEPRECATED_SKILLS, LEGACY_CODEX_MODELS,
   buildAliasedSkillContent, syncAliasedSkillDir, getVersion, ensureCodexProfiles,
-  cleanupStaleSkills,
+  cleanupStaleSkills, extractManagedHookFilename, getManagedRegistryHooks, ensureHooksInSettings,
 };
 
 function runMcpGuardAudit() {
@@ -877,6 +1117,12 @@ if (settingsChanged) {
   }
 }
 
+// ── hook-registry 기반 누락 훅 자동 등록 ──
+{
+  const hookEnsureResult = ensureHooksInSettings();
+  if (hookEnsureResult.changed) synced++;
+}
+
 // ── Stale PID 파일 정리 (hub 좀비 방지) ──
 
 const HUB_PID_FILE = join(CLAUDE_DIR, "cache", "tfx-hub", "hub.pid");