@michelj/context-guard 0.4.3 → 0.6.1

package/bin/context-guard-skill.js

@@ -12,26 +12,37 @@ const sourceHooksPath = path.join(packageRoot, "hooks.json");
 const pythonScript = path.join(sourceSkillDir, "scripts", "context_guard.py");
 const skillInstallEntries = [
   "SKILL.md",
+  "roles.md",
+  "Coordinator.md",
+  "Executor.md",
+  "Tester.md",
   "README.md",
   "README.zh-CN.md",
+  "THIRD_PARTY_NOTICES.md",
+  "licenses",
+  "bin",
   "agents",
+  "prototype",
   "references",
-  "scripts",
-  "tests"
+  "scripts"
 ];
 
 function usage() {
   console.log(`Context Guard Skill
 
 Usage:
-  context-guard install [--target <dir>] [--with-hooks] [--hooks-target <file>] [--config-target <file>]
+  context-guard install [--platform auto|all|codex|cursor|claude] [--no-hooks]
+                        [--target <dir>] [--hooks-target <file>] [--config-target <file>]
+  context-guard doctor [--platform auto|all|codex|cursor|claude] [--root <project>]
+                       [--target <dir>] [--hooks-target <file>] [--config-target <file>] [--json]
   context-guard path
+  context-guard sync ensure|status|pull|prepare|checkpoint|finish [args...]
   context-guard <context_guard.py command> [args...]
 
 Examples:
   npx @michelj/context-guard install
-  npx @michelj/context-guard install --with-hooks
-  npx @michelj/context-guard show-roadmap --root /path/to/project
+  npx @michelj/context-guard install --platform all
+  npx @michelj/context-guard init --root /path/to/project
 `);
 }
 
@@ -47,34 +58,68 @@ function expandHome(inputPath) {
   return inputPath;
 }
 
-function defaultSkillTarget() {
-  if (process.env.CONTEXT_GUARD_SKILL_TARGET) {
-    return path.resolve(expandHome(process.env.CONTEXT_GUARD_SKILL_TARGET));
-  }
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  return path.join(codexHome, "skills", "context-guard");
+const PLATFORM_SPECS = {
+  codex: { env: "CODEX_HOME", folder: ".codex", hooksFile: "hooks.json", configFile: "config.toml" },
+  cursor: { env: "CURSOR_HOME", folder: ".cursor", hooksFile: "hooks.json" },
+  claude: { env: "CLAUDE_CONFIG_DIR", legacyEnv: "CLAUDE_HOME", folder: ".claude", hooksFile: "settings.json" }
+};
+
+function platformHome(platform) {
+  return platformHomeBySpec(PLATFORM_SPECS[platform]);
+}
+
+function platformTargets(platform) {
+  const home = platformHome(platform);
+  return {
+    target: path.join(home, "skills", "context-guard"),
+    hooksTarget: path.join(home, PLATFORM_SPECS[platform].hooksFile),
+    configTarget: PLATFORM_SPECS[platform].configFile
+      ? path.join(home, PLATFORM_SPECS[platform].configFile)
+      : null
+  };
 }
 
-function defaultHooksTarget() {
-  if (process.env.CONTEXT_GUARD_HOOKS_TARGET) {
-    return path.resolve(expandHome(process.env.CONTEXT_GUARD_HOOKS_TARGET));
+let detectedPython;
+function pythonCommand() {
+  if (detectedPython !== undefined) return detectedPython;
+  const candidates = process.platform === "win32" ? ["python", "python3"] : ["python3", "python"];
+  detectedPython = null;
+  for (const command of candidates) {
+    const probe = spawnSync(command, ["--version"], { encoding: "utf8", windowsHide: true, timeout: 5000 });
+    if (!probe.error && probe.status === 0 && /^Python 3\./m.test(`${probe.stdout || ""}\n${probe.stderr || ""}`)) {
+      detectedPython = command;
+      break;
+    }
   }
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  return path.join(codexHome, "hooks.json");
+  return detectedPython;
 }
 
-function defaultConfigTarget() {
-  const codexHome = process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
-  return path.join(codexHome, "config.toml");
+function selectedPlatforms(requested) {
+  if (requested === "all") return Object.keys(PLATFORM_SPECS);
+  if (requested !== "auto") return [requested];
+  const detected = Object.entries(PLATFORM_SPECS)
+    .filter(([, spec]) => Boolean(process.env[spec.env] || process.env[spec.legacyEnv]) || fs.existsSync(platformHomeBySpec(spec)))
+    .map(([name]) => name);
+  return detected.length ? detected : ["codex"];
+}
+
+function platformHomeBySpec(spec) {
+  return path.resolve(expandHome(process.env[spec.env] || process.env[spec.legacyEnv] || path.join(os.homedir(), spec.folder)));
 }
 
 function parseInstallArgs(args) {
   const options = {
-    target: defaultSkillTarget(),
-    withHooks: false,
-    hooksTarget: defaultHooksTarget(),
-    configTarget: defaultConfigTarget(),
-    configTargetExplicit: false,
+    platform: "auto",
+    target: process.env.CONTEXT_GUARD_SKILL_TARGET
+      ? path.resolve(expandHome(process.env.CONTEXT_GUARD_SKILL_TARGET))
+      : null,
+    withHooks: true,
+    hooksTarget: process.env.CONTEXT_GUARD_HOOKS_TARGET
+      ? path.resolve(expandHome(process.env.CONTEXT_GUARD_HOOKS_TARGET))
+      : null,
+    configTarget: null,
+    targetExplicit: Boolean(process.env.CONTEXT_GUARD_SKILL_TARGET),
+    hooksTargetExplicit: Boolean(process.env.CONTEXT_GUARD_HOOKS_TARGET),
     dryRun: false
   };
 
@@ -84,20 +129,26 @@ function parseInstallArgs(args) {
       const value = args[++i];
       if (!value) fail("--target requires a directory");
       options.target = path.resolve(expandHome(value));
+      options.targetExplicit = true;
+    } else if (arg === "--platform") {
+      const value = String(args[++i] || "").toLowerCase();
+      if (!["auto", "all", ...Object.keys(PLATFORM_SPECS)].includes(value)) {
+        fail("--platform must be auto, all, codex, cursor, or claude");
+      }
+      options.platform = value;
     } else if (arg === "--with-hooks" || arg === "--hooks") {
       options.withHooks = true;
+    } else if (arg === "--no-hooks") {
+      options.withHooks = false;
     } else if (arg === "--hooks-target") {
       const value = args[++i];
       if (!value) fail("--hooks-target requires a file path");
       options.hooksTarget = path.resolve(expandHome(value));
-      if (!options.configTargetExplicit) {
-        options.configTarget = path.join(path.dirname(options.hooksTarget), "config.toml");
-      }
+      options.hooksTargetExplicit = true;
     } else if (arg === "--config-target") {
       const value = args[++i];
       if (!value) fail("--config-target requires a file path");
       options.configTarget = path.resolve(expandHome(value));
-      options.configTargetExplicit = true;
     } else if (arg === "--dry-run") {
       options.dryRun = true;
     } else if (arg === "-h" || arg === "--help") {
@@ -107,10 +158,20 @@ function parseInstallArgs(args) {
       fail(`unknown install option: ${arg}`);
     }
   }
+  if ((options.target || options.hooksTarget || options.configTarget) && options.platform === "all") {
+    fail("custom targets can only be used with one platform");
+  }
+  if (options.targetExplicit && !options.hooksTargetExplicit) {
+    const platform = options.platform === "auto" ? "codex" : options.platform;
+    options.hooksTarget = path.join(path.dirname(options.target), PLATFORM_SPECS[platform].hooksFile);
+  }
+  if (!options.configTarget && options.hooksTarget && (options.platform === "auto" || options.platform === "codex")) {
+    options.configTarget = path.join(path.dirname(options.hooksTarget), "config.toml");
+  }
   return options;
 }
 
-function migrateHooksFeatureConfig(configTarget, dryRun) {
+function migratedHooksFeatureConfig(configTarget) {
   const original = fs.existsSync(configTarget) ? fs.readFileSync(configTarget, "utf8") : "";
   const lines = original ? original.replace(/\r\n/g, "\n").split("\n") : [];
   const sectionStart = lines.findIndex((line) => /^\s*\[features\]\s*(?:#.*)?$/.test(line));
@@ -149,50 +210,59 @@ function migrateHooksFeatureConfig(configTarget, dryRun) {
   }
 
   const next = `${nextLines.join("\n").replace(/\n*$/, "")}\n`;
-  if (next === original.replace(/\r\n/g, "\n")) return;
-  if (dryRun) {
-    console.log(`[context-guard-skill] would enable hooks in ${configTarget}`);
-    return;
-  }
-  fs.mkdirSync(path.dirname(configTarget), { recursive: true });
-  if (fs.existsSync(configTarget)) {
-    const backupPath = `${configTarget}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-    fs.copyFileSync(configTarget, backupPath);
-    console.log(`[context-guard-skill] backed up config: ${backupPath}`);
-  }
-  fs.writeFileSync(configTarget, next);
-  console.log(`[context-guard-skill] enabled hooks: ${configTarget}`);
+  return next === original.replace(/\r\n/g, "\n") ? null : next;
 }
 
-function copySkill(target, dryRun) {
+function copySkill(target) {
   if (!fs.existsSync(path.join(sourceSkillDir, "SKILL.md"))) {
-    fail(`source skill folder is missing: ${sourceSkillDir}`);
+    throw new Error(`source skill folder is missing: ${sourceSkillDir}`);
   }
-  if (dryRun) {
-    console.log(`[context-guard-skill] would install skill to ${target}`);
-    return;
-  }
-  fs.rmSync(target, { recursive: true, force: true });
-  fs.mkdirSync(path.dirname(target), { recursive: true });
   fs.mkdirSync(target, { recursive: true });
   for (const entry of skillInstallEntries) {
     const from = path.join(sourceSkillDir, entry);
     if (!fs.existsSync(from)) continue;
     const to = path.join(target, entry);
-    fs.cpSync(from, to, { recursive: true });
+    const options = entry === "scripts"
+      ? {
+          recursive: true,
+          filter(source) {
+            // Node 18 may pass a namespaced Windows path to this callback.
+            const relative = path.relative(path.toNamespacedPath(from), path.toNamespacedPath(source));
+            if (relative === "") return true;
+            const parts = relative.split(path.sep);
+            return parts[0] !== "cloud"
+              && relative !== "branch_guard.py"
+              && !parts.includes("__pycache__")
+              && !/\.py[co]$/i.test(parts.at(-1));
+          }
+        }
+      : entry === "bin"
+        ? { recursive: true, filter(source) {
+            const relative = path.relative(path.toNamespacedPath(from), path.toNamespacedPath(source));
+            return relative === "" || relative === "context-guard-skill.js";
+          } }
+        : { recursive: true };
+    fs.cpSync(from, to, options);
   }
-  console.log(`[context-guard-skill] installed skill: ${target}`);
 }
 
-function rewriteHookCommands(hooksConfig, skillTarget) {
+function hookCommand(skillTarget, event, platform) {
   const hookScript = path.join(skillTarget, "scripts", "context_guard_hook.py");
   const encodedHookScript = JSON.stringify(hookScript);
+  const python = pythonCommand();
+  if (!python) throw new Error("Python 3 is required before lifecycle hooks can be installed");
+  return `${python} ${encodedHookScript} ${event} --platform ${platform}`;
+}
+
+function rewriteGroupedHookCommands(hooksConfig, skillTarget, platform) {
   const next = JSON.parse(JSON.stringify(hooksConfig));
   for (const groups of Object.values(next.hooks || {})) {
     for (const group of groups || []) {
       for (const hook of group.hooks || []) {
         if (hook.type === "command" && typeof hook.command === "string" && hook.command.includes("context_guard_hook.py")) {
-          hook.command = `python3 ${encodedHookScript} ${hook.command.split(" ").pop()}`;
+          const match = hook.command.match(/context_guard_hook\.py["']?\s+([a-z-]+)/);
+          const event = match ? match[1] : "session-start";
+          hook.command = hookCommand(skillTarget, event, platform);
         }
       }
     }
@@ -200,59 +270,305 @@ function rewriteHookCommands(hooksConfig, skillTarget) {
   return next;
 }
 
+function cursorHooks(skillTarget) {
+  const events = {
+    sessionStart: "session-start",
+    subagentStart: "subagent-start",
+    beforeSubmitPrompt: "user-prompt-submit",
+    subagentStop: "subagent-stop",
+    stop: "stop"
+  };
+  const hooks = {};
+  for (const [cursorEvent, normalizedEvent] of Object.entries(events)) {
+    hooks[cursorEvent] = [{
+      type: "command",
+      command: hookCommand(skillTarget, normalizedEvent, "cursor"),
+      timeout: normalizedEvent === "session-start" ? 20 : 10
+    }];
+  }
+  return { version: 1, hooks };
+}
+
 function mergeHooks(existing, incoming) {
   const merged = existing && typeof existing === "object" ? existing : {};
   merged.hooks = merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {};
   for (const [event, groups] of Object.entries(incoming.hooks || {})) {
     const current = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
-    const withoutOldContextGuard = current.filter((group) => {
-      const hooks = Array.isArray(group && group.hooks) ? group.hooks : [];
-      return !hooks.some((hook) => String(hook.command || "").includes("context_guard_hook.py"));
+    const withoutOldContextGuard = current.flatMap((group) => {
+      const hooks = group.hooks.filter((hook) => !String(hook.command || "").includes("context_guard_hook.py"));
+      if (hooks.length === group.hooks.length) return [group];
+      return hooks.length ? [{ ...group, hooks }] : [];
     });
     merged.hooks[event] = withoutOldContextGuard.concat(groups);
   }
   return merged;
 }
 
-function installHooks(skillTarget, hooksTarget, dryRun) {
+function mergeCursorHooks(existing, incoming) {
+  const merged = existing && typeof existing === "object" ? existing : {};
+  merged.version = merged.version || 1;
+  merged.hooks = merged.hooks && typeof merged.hooks === "object" ? merged.hooks : {};
+  for (const [event, hooks] of Object.entries(incoming.hooks || {})) {
+    const current = Array.isArray(merged.hooks[event]) ? merged.hooks[event] : [];
+    merged.hooks[event] = current
+      .filter((hook) => !String(hook && hook.command || "").includes("context_guard_hook.py"))
+      .concat(hooks);
+  }
+  return merged;
+}
+
+function readObject(target, platform) {
+  if (!fs.existsSync(target)) return {};
+  const object = value => value !== null && typeof value === "object" && !Array.isArray(value);
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(target, "utf8").replace(/^\uFEFF/, ""));
+  } catch (error) {
+    throw new Error(`Cannot read JSON config ${target}: ${error.message}`);
+  }
+  if (!object(value) || (value.hooks !== undefined && !object(value.hooks))) {
+    throw new Error(`Invalid config object or hooks in ${target}; original file was not changed.`);
+  }
+  for (const [event, entries] of Object.entries(value.hooks || {})) {
+    if (!Array.isArray(entries) || entries.some(entry => !object(entry) ||
+      (platform !== "cursor" && (!Array.isArray(entry.hooks) || entry.hooks.some(hook => !object(hook)))))) {
+      throw new Error(`Invalid hook event ${event} in ${target}; original file was not changed.`);
+    }
+  }
+  return value;
+}
+
+const CLAUDE_EVENTS = ["SessionStart", "SubagentStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "PostToolUseFailure", "PreCompact", "PostCompact", "SubagentStop", "Stop", "StopFailure", "SessionEnd"];
+
+function plannedHooks(platform, skillTarget, hooksTarget) {
   if (!fs.existsSync(sourceHooksPath)) {
-    fail(`source hooks file is missing: ${sourceHooksPath}`);
+    throw new Error(`source hooks file is missing: ${sourceHooksPath}`);
+  }
+  const existing = readObject(hooksTarget, platform);
+  if (platform === "cursor") {
+    return mergeCursorHooks(existing, cursorHooks(skillTarget));
   }
   const rawIncoming = JSON.parse(fs.readFileSync(sourceHooksPath, "utf8"));
-  const incoming = rewriteHookCommands(rawIncoming, skillTarget);
-  let existing = {};
-  if (fs.existsSync(hooksTarget)) {
-    existing = JSON.parse(fs.readFileSync(hooksTarget, "utf8"));
+  if (platform === "claude") {
+    for (const [name, source, from, to] of [["PostToolUseFailure", "PostToolUse", "post-tool-use", "post-tool-use-failure"], ["SessionEnd", "Stop", "stop", "session-end"], ["StopFailure", "Interrupt", "interrupt", "stop-failure"]]) {
+      rawIncoming.hooks[name] = JSON.parse(JSON.stringify(rawIncoming.hooks[source]));
+      for (const group of rawIncoming.hooks[name]) for (const hook of group.hooks) hook.command = hook.command.replace(`context_guard_hook.py ${from} `, `context_guard_hook.py ${to} `);
+    }
+    const supported = new Set(CLAUDE_EVENTS);
+    rawIncoming.hooks = Object.fromEntries(Object.entries(rawIncoming.hooks || {}).filter(([event]) => supported.has(event)));
+  }
+  const incoming = rewriteGroupedHookCommands(rawIncoming, skillTarget, platform);
+  return mergeHooks(existing, incoming);
+}
+
+function containsPath(parent, child) {
+  const relative = path.relative(parent, child);
+  return relative === "" || (!relative.startsWith(".." + path.sep) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function applyInstallPlan(plan, dryRun) {
+  for (const entry of plan) {
+    if (containsPath(entry.target, os.homedir())) {
+      throw new Error(`Install destination must not replace the user home or its parent: ${entry.target}`);
+    }
+    if (containsPath(entry.target, sourceSkillDir) || containsPath(sourceSkillDir, entry.target)) {
+      throw new Error(`Install destination overlaps its source package: ${entry.target}`);
+    }
+    const stat = fs.lstatSync(entry.target, { throwIfNoEntry: false });
+    if (stat && (stat.isSymbolicLink() || (entry.kind === "skill" ? !stat.isDirectory() : !stat.isFile()))) {
+      throw new Error(`Invalid install destination: ${entry.target}`);
+    }
+    entry.mode = stat ? stat.mode & 0o777 : 0o600;
+    for (const other of plan) if (entry !== other && containsPath(entry.target, other.target)) {
+      throw new Error(`Overlapping install destinations: ${entry.target} and ${other.target}`);
+    }
   }
-  const merged = mergeHooks(existing, incoming);
   if (dryRun) {
-    console.log(`[context-guard-skill] would install hooks to ${hooksTarget}`);
+    for (const entry of plan) console.log(`[context-guard-skill] would install ${entry.kind}: ${entry.target}`);
     return;
   }
-  fs.mkdirSync(path.dirname(hooksTarget), { recursive: true });
-  if (fs.existsSync(hooksTarget)) {
-    const backupPath = `${hooksTarget}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-    fs.copyFileSync(hooksTarget, backupPath);
-    console.log(`[context-guard-skill] backed up hooks: ${backupPath}`);
+
+  const staged = [];
+  try {
+    // Prepare every replacement before touching existing files. Temporary
+    // siblings allow renames on the same filesystem, including on Windows.
+    for (const entry of plan) {
+      fs.mkdirSync(path.dirname(entry.target), { recursive: true });
+      entry.temp = fs.mkdtempSync(path.join(path.dirname(entry.target), ".context-guard-install-"));
+      entry.next = path.join(entry.temp, "next");
+      entry.previous = path.join(entry.temp, "previous");
+      staged.push(entry);
+      if (entry.kind === "skill") {
+        copySkill(entry.next);
+        // Existing Claude receivers may still reference this absolute prompt path.
+        if (fs.existsSync(path.join(entry.target, "Developer.md"))) {
+          fs.copyFileSync(path.join(entry.next, "Executor.md"), path.join(entry.next, "Developer.md"));
+        }
+      } else fs.writeFileSync(entry.next, entry.content, { mode: entry.mode });
+    }
+    for (const entry of staged) {
+      if (fs.existsSync(entry.target)) {
+        fs.renameSync(entry.target, entry.previous);
+        entry.oldMoved = true;
+      }
+      fs.renameSync(entry.next, entry.target);
+      entry.newMoved = true;
+    }
+  } catch (error) {
+    for (const entry of staged.slice().reverse()) {
+      try {
+        if (entry.newMoved) fs.rmSync(entry.target, { recursive: entry.kind === "skill", force: true });
+        if (entry.oldMoved) fs.renameSync(entry.previous, entry.target);
+      } catch (rollbackError) {
+        entry.preserve = true;
+        console.error(`[context-guard-skill] Recovery needed; kept ${entry.temp}: ${rollbackError.message}`);
+      }
+    }
+    throw error;
+  } finally {
+    for (const entry of staged) {
+      if (entry.preserve) continue;
+      try {
+        // Keep original client configuration as a uniquely named backup only
+        // after a successful replacement. Failed installs restore it instead.
+        if (entry.kind !== "skill" && fs.existsSync(entry.previous)) {
+          const backup = `${entry.target}.bak-${path.basename(entry.temp)}`;
+          fs.renameSync(entry.previous, backup);
+          console.log(`[context-guard-skill] backed up config: ${backup}`);
+        }
+        fs.rmSync(entry.temp, { recursive: true, force: true });
+      } catch (error) {
+        console.warn(`[context-guard-skill] Kept recovery files at ${entry.temp}: ${error.message}`);
+      }
+    }
   }
-  fs.writeFileSync(hooksTarget, `${JSON.stringify(merged, null, 2)}\n`);
-  console.log(`[context-guard-skill] installed hooks: ${hooksTarget}`);
+  for (const entry of plan) console.log(`[context-guard-skill] installed ${entry.kind}: ${entry.target}`);
 }
 
 function install(args) {
   const options = parseInstallArgs(args);
-  copySkill(options.target, options.dryRun);
-  if (options.withHooks) {
-    migrateHooksFeatureConfig(options.configTarget, options.dryRun);
-    installHooks(options.target, options.hooksTarget, options.dryRun);
+  let platforms = selectedPlatforms(options.platform);
+  if ((options.target || options.hooksTarget || options.configTarget) && options.platform === "auto") {
+    platforms = ["codex"];
+  }
+  const plan = [];
+  for (const platform of platforms) {
+    const defaults = platformTargets(platform);
+    const skillTarget = options.target || defaults.target;
+    const hooksTarget = options.hooksTarget || defaults.hooksTarget;
+    const configTarget = options.configTarget || defaults.configTarget;
+    plan.push({ target: skillTarget, kind: "skill" });
+    if (options.withHooks) {
+      const hooks = plannedHooks(platform, skillTarget, hooksTarget);
+      if (platform === "codex" && configTarget) {
+        const content = migratedHooksFeatureConfig(configTarget);
+        if (content !== null) plan.push({ target: configTarget, kind: "config", content });
+      }
+      plan.push({ target: hooksTarget, kind: "hooks", content: `${JSON.stringify(hooks, null, 2)}\n` });
+    }
+  }
+  applyInstallPlan(plan, options.dryRun);
+}
+
+function parseDoctorArgs(args) {
+  const options = { platform: "auto", root: process.cwd(), target: null, hooksTarget: null, configTarget: null, json: false };
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (["--platform", "--root", "--target", "--hooks-target", "--config-target"].includes(arg)) {
+      const value = args[++i];
+      if (!value) fail(`${arg} requires a value`);
+      if (arg === "--platform") {
+        const platform = String(value).toLowerCase();
+        if (!["auto", "all", ...Object.keys(PLATFORM_SPECS)].includes(platform)) fail("--platform must be auto, all, codex, cursor, or claude");
+        options.platform = platform;
+      } else options[{ "--root": "root", "--target": "target", "--hooks-target": "hooksTarget", "--config-target": "configTarget" }[arg]] = path.resolve(expandHome(value));
+    } else if (arg === "--json") options.json = true;
+    else fail(`unknown doctor option: ${arg}`);
+  }
+  if ((options.target || options.hooksTarget || options.configTarget) && options.platform === "all") fail("custom doctor targets can only be used with one platform");
+  return options;
+}
+
+function hookCommands(config, platform, event) {
+  const entries = config?.hooks?.[event];
+  if (!Array.isArray(entries)) return [];
+  if (platform === "cursor") return entries.map(item => item?.command).filter(Boolean);
+  return entries.flatMap(group => (group?.hooks || []).map(item => item?.command)).filter(Boolean);
+}
+
+function doctor(args) {
+  const options = parseDoctorArgs(args);
+  const results = [];
+  const check = (name, ok, detail, required = true) => results.push({ name, ok: Boolean(ok), detail, required });
+  const python = pythonCommand();
+  check("python", python, python ? `${python} is Python 3` : "no working Python 3 interpreter");
+  let platforms = selectedPlatforms(options.platform);
+  if ((options.target || options.hooksTarget || options.configTarget) && options.platform === "auto") platforms = ["codex"];
+  const eventNames = {
+    codex: ["SessionStart", "SubagentStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "PreCompact", "PostCompact", "SubagentStop", "Stop", "Interrupt"],
+    claude: CLAUDE_EVENTS,
+    cursor: ["sessionStart", "subagentStart", "beforeSubmitPrompt", "subagentStop", "stop"]
+  };
+  for (const platform of platforms) {
+    const defaults = platformTargets(platform);
+    const target = options.target || defaults.target;
+    const hooksTarget = options.hooksTarget || defaults.hooksTarget;
+    const configTarget = options.configTarget || defaults.configTarget;
+    const installedLauncher = path.join(target, "bin", "context-guard-skill.js");
+    check(`${platform}.skill`, fs.existsSync(path.join(target, "SKILL.md")) && fs.existsSync(path.join(target, "scripts", "context_guard_hook.py")) && fs.existsSync(installedLauncher), target);
+    check(`${platform}.cli`, fs.existsSync(installedLauncher), installedLauncher);
+    let config = null;
+    try { config = readObject(hooksTarget, platform); } catch (error) { check(`${platform}.hooks`, false, error.message); }
+    if (config) {
+      const missing = eventNames[platform].filter(event => !hookCommands(config, platform, event).some(command => command.includes("context_guard_hook.py") && command.includes(`--platform ${platform}`)));
+      check(`${platform}.hooks`, missing.length === 0, missing.length ? `missing ${missing.join(", ")}` : hooksTarget);
+    }
+    if (platform === "codex" && configTarget) {
+      const text = fs.existsSync(configTarget) ? fs.readFileSync(configTarget, "utf8") : "";
+      check("codex.hooks-feature", /^\s*hooks\s*=\s*true\s*$/m.test(text), configTarget);
+      const probe = spawnSync(process.execPath, [path.join(sourceSkillDir, 'scripts/workbench/hook-status.mjs'), options.root, target], { encoding: 'utf8', windowsHide: true, timeout: 7000 });
+      let native = {}; try { native = JSON.parse(probe.stdout); } catch {}
+      check('codex.hooks-trust', native.trusted, native.unavailable ? 'native trust status unavailable; not ready' : JSON.stringify(native));
+      const crypto = require('crypto');
+      let expected = '', installed = '';
+      try { expected = crypto.createHash('sha256').update(fs.readFileSync(path.join(sourceSkillDir, 'scripts/context_guard_hook.py'))).digest('hex'); installed = crypto.createHash('sha256').update(fs.readFileSync(path.join(target, 'scripts/context_guard_hook.py'))).digest('hex'); } catch {}
+      check('codex.hooks-version', expected && expected === installed, 'installed Hook must match this release');
+      let events = [];
+      try { events = fs.readFileSync(path.join(options.root, '.codex/context/sessions.jsonl'), 'utf8').split('\n').filter(Boolean).map(JSON.parse); } catch {}
+      const current = events.filter(event => event.hook_sha256 === installed && (!process.env.CODEX_THREAD_ID || event.session_id === process.env.CODEX_THREAD_ID));
+      check('codex.hooks-executed', current.length > 0, 'execution evidence for the current installed script');
+      check('codex.context-emitted', current.some(event => event.context_emitted), 'context output emitted; delivery to a model is not observable by doctor');
+    }
+  }
+  const ctx = path.join(options.root, ".codex", "context");
+  let map = null;
+  try { map = JSON.parse(fs.readFileSync(path.join(ctx, "map.json"), "utf8")); } catch {}
+  check("project.map", map?.root?.id || map?.root === null, path.join(ctx, "map.json"));
+  check("project.sessions", fs.existsSync(path.join(ctx, "sessions.jsonl")), path.join(ctx, "sessions.jsonl"));
+  const diagnosticLauncher = platforms.length === 1 ? path.join((options.target || platformTargets(platforms[0]).target), "bin", "context-guard-skill.js") : null;
+  let diagnostic = null;
+  if (diagnosticLauncher && fs.existsSync(diagnosticLauncher)) {
+    const probe = spawnSync(process.execPath, [diagnosticLauncher, "workbench", "--diagnose", "--root", options.root, ...(process.env.CODEX_THREAD_ID ? ["--session", process.env.CODEX_THREAD_ID] : [])], { encoding: "utf8", windowsHide: true, timeout: 7000 });
+    try { diagnostic = JSON.parse(probe.stdout); } catch {}
+  }
+  const runtimeStatus = diagnostic?.runtime?.status || "unknown";
+  check("project.workbench", ["ready", "stopped"].includes(runtimeStatus), diagnostic ? JSON.stringify({ status: runtimeStatus, named: diagnostic.runtime.named, services: diagnostic.runtime.services }) : "diagnosis unavailable", false);
+  const ok = results.every(item => !item.required || item.ok);
+  if (options.json) console.log(JSON.stringify({ ok, results }, null, 2));
+  else {
+    for (const item of results) console.log(`[${item.ok ? "ok" : item.required ? "fail" : "warn"}] ${item.name}: ${item.detail}`);
+    console.log(`[context-guard-skill] doctor: ${ok ? "ready" : "not ready"}`);
   }
+  if (!ok) process.exitCode = 1;
 }
 
 function runPython(args) {
   if (!fs.existsSync(pythonScript)) {
     fail(`context_guard.py is missing: ${pythonScript}`);
   }
-  const result = spawnSync("python3", [pythonScript, ...args], { stdio: "inherit" });
+  const command = pythonCommand();
+  if (!command) fail("Python 3 is required; no working Python 3 interpreter was found (`python`, `python3`).");
+  const result = spawnSync(command, [pythonScript, ...args], { stdio: "inherit", windowsHide: true });
   if (result.error) fail(result.error.message);
   process.exit(result.status === null ? 1 : result.status);
 }
@@ -262,9 +578,14 @@ const [command, ...rest] = process.argv.slice(2);
 if (!command || command === "-h" || command === "--help" || command === "help") {
   usage();
 } else if (command === "install") {
-  install(rest);
+  try { install(rest); } catch (error) { fail(error.message); }
 } else if (command === "path") {
   console.log(sourceSkillDir);
+} else if (command === "doctor") {
+  doctor(rest);
+} else if (["map", "workbench", "memory", "preferences", "sync"].includes(command)) {
+  const result = spawnSync(process.execPath, [path.join(sourceSkillDir, "scripts", "workbench", "cli.mjs"), command, ...rest], { stdio: "inherit", windowsHide: true });
+  process.exit(result.status ?? 1);
 } else {
   runPython([command, ...rest]);
 }

package/bin/postinstall.js

@@ -13,12 +13,12 @@ if (skipInstall) {
 }
 
 if (!isGlobalInstall && !autoInstall) {
-  console.log("[context-guard-skill] package installed. Run `npx @michelj/context-guard install` to install the Codex skill.");
+  console.log("[context-guard-skill] package installed. Run `npx @michelj/context-guard install` to install the skill and hooks for detected clients.");
   process.exit(0);
 }
 
 const cli = path.join(__dirname, "context-guard-skill.js");
-const result = spawnSync(process.execPath, [cli, "install"], { stdio: "inherit" });
+const result = spawnSync(process.execPath, [cli, "install"], { stdio: "inherit", windowsHide: true });
 
 if (result.error) {
   console.warn(`[context-guard-skill] auto install skipped: ${result.error.message}`);