@michelj/context-guard 0.4.4 → 0.6.2

package/bin/context-guard-skill.js

@@ -12,8 +12,15 @@ 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",
@@ -26,7 +33,10 @@ function usage() {
 Usage:
   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:
@@ -51,12 +61,11 @@ function expandHome(inputPath) {
 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_HOME", folder: ".claude", hooksFile: "settings.json" }
+  claude: { env: "CLAUDE_CONFIG_DIR", legacyEnv: "CLAUDE_HOME", folder: ".claude", hooksFile: "settings.json" }
 };
 
 function platformHome(platform) {
-  const spec = PLATFORM_SPECS[platform];
-  return path.resolve(expandHome(process.env[spec.env] || path.join(os.homedir(), spec.folder)));
+  return platformHomeBySpec(PLATFORM_SPECS[platform]);
 }
 
 function platformTargets(platform) {
@@ -70,17 +79,32 @@ function platformTargets(platform) {
   };
 }
 
+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;
+    }
+  }
+  return detectedPython;
+}
+
 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]) || fs.existsSync(platformHomeBySpec(spec)))
+    .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] || path.join(os.homedir(), spec.folder)));
+  return path.resolve(expandHome(process.env[spec.env] || process.env[spec.legacyEnv] || path.join(os.homedir(), spec.folder)));
 }
 
 function parseInstallArgs(args) {
@@ -147,7 +171,7 @@ function parseInstallArgs(args) {
   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));
@@ -186,46 +210,48 @@ 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 hookCommand(skillTarget, event, platform) {
   const hookScript = path.join(skillTarget, "scripts", "context_guard_hook.py");
   const encodedHookScript = JSON.stringify(hookScript);
-  const pythonCommand = process.platform === "win32" ? "python" : "python3";
-  return `${pythonCommand} ${encodedHookScript} ${event} --platform ${platform}`;
+  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) {
@@ -257,7 +283,7 @@ function cursorHooks(skillTarget) {
     hooks[cursorEvent] = [{
       type: "command",
       command: hookCommand(skillTarget, normalizedEvent, "cursor"),
-      timeout: 10
+      timeout: normalizedEvent === "session-start" ? 20 : 10
     }];
   }
   return { version: 1, hooks };
@@ -268,9 +294,10 @@ function mergeHooks(existing, incoming) {
   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);
   }
@@ -290,40 +317,132 @@ function mergeCursorHooks(existing, incoming) {
   return merged;
 }
 
-function writeConfigFile(target, value, label, dryRun) {
-  if (dryRun) {
-    console.log(`[context-guard-skill] would install ${label} to ${target}`);
-    return;
+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}`);
   }
-  fs.mkdirSync(path.dirname(target), { recursive: true });
-  if (fs.existsSync(target)) {
-    const backupPath = `${target}.bak-${new Date().toISOString().replace(/[:.]/g, "-")}`;
-    fs.copyFileSync(target, backupPath);
-    console.log(`[context-guard-skill] backed up ${label}: ${backupPath}`);
+  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.`);
+    }
   }
-  fs.writeFileSync(target, `${JSON.stringify(value, null, 2)}\n`);
-  console.log(`[context-guard-skill] installed ${label}: ${target}`);
+  return value;
 }
 
-function readObject(target) {
-  if (!fs.existsSync(target)) return {};
-  const value = JSON.parse(fs.readFileSync(target, "utf8"));
-  return value && typeof value === "object" && !Array.isArray(value) ? value : {};
-}
+const CLAUDE_EVENTS = ["SessionStart", "SubagentStart", "UserPromptSubmit", "PreToolUse", "PermissionRequest", "PostToolUse", "PostToolUseFailure", "PreCompact", "PostCompact", "SubagentStop", "Stop", "StopFailure", "SessionEnd"];
 
-function installHooks(platform, skillTarget, hooksTarget, dryRun) {
+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);
+  const existing = readObject(hooksTarget, platform);
   if (platform === "cursor") {
-    writeConfigFile(hooksTarget, mergeCursorHooks(existing, cursorHooks(skillTarget)), "hooks", dryRun);
-    return;
+    return mergeCursorHooks(existing, cursorHooks(skillTarget));
   }
   const rawIncoming = JSON.parse(fs.readFileSync(sourceHooksPath, "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);
-  const merged = mergeHooks(existing, incoming);
-  writeConfigFile(hooksTarget, merged, platform === "claude" ? "settings hooks" : "hooks", dryRun);
+  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}`);
+    }
+  }
+  if (dryRun) {
+    for (const entry of plan) console.log(`[context-guard-skill] would install ${entry.kind}: ${entry.target}`);
+    return;
+  }
+
+  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}`);
+      }
+    }
+  }
+  for (const entry of plan) console.log(`[context-guard-skill] installed ${entry.kind}: ${entry.target}`);
 }
 
 function install(args) {
@@ -332,32 +451,126 @@ function install(args) {
   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;
-    copySkill(skillTarget, options.dryRun);
+    plan.push({ target: skillTarget, kind: "skill" });
     if (options.withHooks) {
+      const hooks = plannedHooks(platform, skillTarget, hooksTarget);
       if (platform === "codex" && configTarget) {
-        migrateHooksFeatureConfig(configTarget, options.dryRun);
+        const content = migratedHooksFeatureConfig(configTarget);
+        if (content !== null) plan.push({ target: configTarget, kind: "config", content });
       }
-      installHooks(platform, skillTarget, hooksTarget, options.dryRun);
+      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}`);
   }
-  for (const command of ["python3", "python"]) {
-    const result = spawnSync(command, [pythonScript, ...args], { stdio: "inherit" });
-    if (result.error && result.error.code === "ENOENT") continue;
-    if (result.error) fail(result.error.message);
-    process.exit(result.status === null ? 1 : result.status);
-  }
-  fail("Python 3 is required; neither `python3` nor `python` was found.");
+  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);
 }
 
 const [command, ...rest] = process.argv.slice(2);
@@ -365,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

@@ -18,7 +18,7 @@ if (!isGlobalInstall && !autoInstall) {
 }
 
 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}`);

package/hooks.json

@@ -7,8 +7,8 @@
           {
             "type": "command",
             "command": "python3 ./scripts/context_guard_hook.py session-start --platform codex",
-            "timeout": 10,
-            "statusMessage": "Initializing context folder"
+            "timeout": 20,
+            "statusMessage": "Checking Session context"
           }
         ]
       }
@@ -37,6 +37,70 @@
         ]
       }
     ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash|exec_command|shell|run_shell_command|apply_patch|Edit|Write|mcp__.*(write|edit|delete|move).*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py pre-tool-use --platform codex",
+            "timeout": 20,
+            "statusMessage": "Checking tool scope"
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py permission-request --platform codex",
+            "timeout": 10,
+            "statusMessage": "Checking Context Guard node scope"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash|exec_command|shell|run_shell_command|apply_patch|Edit|Write|mcp__.*(write|edit|delete|move).*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py post-tool-use --platform codex",
+            "timeout": 20,
+            "statusMessage": "Recording tool result"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py pre-compact --platform codex",
+            "timeout": 10,
+            "statusMessage": "Saving Context Guard plan state"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py post-compact --platform codex",
+            "timeout": 10,
+            "statusMessage": "Restoring Context Guard map state"
+          }
+        ]
+      }
+    ],
     "SubagentStop": [
       {
         "hooks": [
@@ -44,7 +108,7 @@
             "type": "command",
             "command": "python3 ./scripts/context_guard_hook.py subagent-stop --platform codex",
             "timeout": 10,
-            "statusMessage": "Reminder: write sessions/bugs/tasks if this turn mattered"
+            "statusMessage": "Recording subagent stop"
           }
         ]
       }
@@ -56,7 +120,19 @@
             "type": "command",
             "command": "python3 ./scripts/context_guard_hook.py stop --platform codex",
             "timeout": 10,
-            "statusMessage": "Reminder: write sessions/bugs/tasks if this turn mattered"
+            "statusMessage": "Checking Map archive and plan completion"
+          }
+        ]
+      }
+    ],
+    "Interrupt": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ./scripts/context_guard_hook.py interrupt --platform codex",
+            "timeout": 3,
+            "statusMessage": "Saving interrupted Context Guard state"
           }
         ]
       }

package/licenses/JSONParse-MIT.txt

@@ -0,0 +1,24 @@
+The MIT License
+
+Copyright (c) 2012 Tim Caswell
+
+Permission is hereby granted, free of charge,
+to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to
+deal in the Software without restriction, including
+without limitation the rights to use, copy, modify,
+merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom
+the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice
+shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR
+ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.