@sayansr26/agent-os 0.5.3 → 0.6.1

package/src/claude-setup.mjs

@@ -1,81 +1,12 @@
 /**
- * The two Claude Code settings that are not rules and not a plugin.
+ * The Claude Code settings that are not rules and not the plugin: git write
+ * protection, the todo tools flag, and the task-tracking rule.
  *
- * Both are written at PROJECT scope only — `.claude/settings.json` and the
- * project's `CLAUDE.md`. Nothing here touches `~/.claude/`: a project setup
- * tool that edits the machine's global config is overreach, and the point is
- * that the setup travels with the repository.
+ * The logic lives in the plugin (`skills/init/scripts/settings.mjs`) so that
+ * `/agent-os:init` inside Claude Code and `agent-os init` in a terminal write
+ * exactly the same thing. This module is the CLI's door to it.
  */
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { write } from "./source.mjs";
-
-export const TODO_ENV = "CLAUDE_CODE_ENABLE_TODO_TOOLS";
-
-export const TASK_RULE = `- **Always track work with the task tool (TaskCreate / TaskUpdate).** Any request
-  with more than one step gets a task list before work starts: one task per
-  deliverable, marked \`in_progress\` when started and \`completed\` only when
-  verified. Keep it current as scope changes, including work delegated to
-  subagents, so I can see what is done, running and left at any moment.`;
-
-/**
- * Turn on the todo tools in project settings, preserving every other key.
- * Returns "added" | "present" | "conflict" | "invalid".
- */
-export function ensureTodoEnv(root, { dry = false } = {}) {
-  const rel = ".claude/settings.json";
-  const p = join(root, rel);
-  let settings = {};
-  if (existsSync(p)) {
-    try { settings = JSON.parse(readFileSync(p, "utf8")); }
-    catch { return { status: "invalid", rel }; }
-  }
-  const env = settings.env || {};
-  const current = env[TODO_ENV];
-
-  // "true" and "1" are both truthy to Claude Code; an existing truthy value is
-  // the user's choice and is left alone rather than normalised.
-  if (current !== undefined) {
-    const on = current === "1" || current === "true" || current === true;
-    return { status: on ? "present" : "conflict", rel, current };
-  }
-
-  settings.env = { ...env, [TODO_ENV]: "1" };
-  if (!dry) write(root, rel, JSON.stringify(settings, null, 2) + "\n");
-  return { status: "added", rel };
-}
-
-/**
- * Put the task-tracking rule in CLAUDE.md if it is not already there.
- * Never creates CLAUDE.md — that file is the project's own always-loaded
- * context, and inventing one from a CLI is how a project ends up with a stub
- * nobody owns. Returns "added" | "present" | "no-file".
- */
-export function ensureTaskRule(root, { dry = false } = {}) {
-  const rel = "CLAUDE.md";
-  const p = join(root, rel);
-  if (!existsSync(p)) return { status: "no-file", rel };
-
-  const text = readFileSync(p, "utf8");
-  if (/TaskCreate/.test(text)) return { status: "present", rel };
-
-  // Prefer the operator-preferences section if the project keeps one, so the
-  // rule lands with the other instructions about how to work rather than
-  // orphaned at the bottom of the file.
-  const heading = text.match(/^##\s+Operator preferences\s*$/m);
-  let next;
-  if (heading) {
-    const start = heading.index + heading[0].length;
-    const rest = text.slice(start);
-    const nextHeading = rest.search(/^##\s+/m);
-    const end = nextHeading === -1 ? text.length : start + nextHeading;
-    const before = text.slice(0, end).replace(/\s*$/, "");
-    next = `${before}\n\n${TASK_RULE}\n\n${text.slice(end)}`;
-  } else {
-    next = `${text.replace(/\s*$/, "")}\n\n## Working agreement\n\n${TASK_RULE}\n`;
-  }
-  next = next.replace(/\n{4,}/g, "\n\n\n");
-
-  if (!dry) write(root, rel, next);
-  return { status: "added", rel, section: heading ? "Operator preferences" : "Working agreement" };
-}
+export {
+  TODO_ENV, TASK_RULE, GIT_DENY, userDir, paths,
+  mergeSettings, addTaskRule, applyScope, describe,
+} from "../plugins/agent-os/skills/init/scripts/settings.mjs";

package/src/cli.mjs

@@ -5,8 +5,10 @@ import { join } from "node:path";
 import { detect, summarise, TOOLS } from "./detect.mjs";
 import { load, write, readIfExists, matches, BANNER, DIR } from "./source.mjs";
 import { adopt } from "./adopt.mjs";
-import { installPlugin, MARKETPLACE, MARKETPLACE_NAME, PLUGIN } from "./plugin.mjs";
-import { ensureTodoEnv, ensureTaskRule, TODO_ENV } from "./claude-setup.mjs";
+import { ensurePlugin, MARKETPLACE_NAME, PLUGIN, PLUGINS } from "./plugin.mjs";
+import { setupState, describeState } from "../plugins/agent-os/skills/init/scripts/state.mjs";
+import { applyScope, describe } from "./claude-setup.mjs";
+import { createInterface } from "node:readline/promises";
 import { compile, TARGETS } from "./targets.mjs";
 
 const bold = (s) => `\x1b[1m${s}\x1b[0m`;
@@ -15,12 +17,14 @@ const dim = (s) => `\x1b[2m${s}\x1b[0m`;
 const USAGE = `
 ${bold("agent-os")} — one source of truth for AI coding agent config
 
-  agent-os init      detect your tools, create .agent-os/, compile
+  agent-os init      set up a fresh project, or repair and update an existing one
   agent-os sync      recompile after editing .agent-os/
   agent-os check     verify nothing drifted (exit 1 if it has) — for CI
   agent-os detect    list which tools this project is set up for
   agent-os audit     inspect the project's context layer and report findings
   agent-os memory    inspect and health-check every memory store
+  agent-os settings  preview git write protection + task tools for Claude Code
+                     (--scope project|user|both, --apply to write)
 
   Without a global install, prefix any of these with
   ${dim("npx @sayansr26/agent-os")}
@@ -29,7 +33,11 @@ Options
   --root <dir>   project directory (default: cwd)
   --dry-run      print what would change, write nothing
   --force        overwrite files agent-os did not generate (it refuses by default)
-  --no-plugin    skip installing the Claude Code plugin during init
+  --no-plugin    skip installing or updating the Claude Code plugins during init
+  --no-auto-route
+                 init: install agent-os but not the auto-route model router
+  --global       init: also write ~/.claude settings without asking
+  --no-global    init: leave ~/.claude alone
 `;
 
 function scaffold(root, found) {
@@ -116,6 +124,13 @@ export async function main(argv) {
     return;
   }
 
+  if (cmd === "settings") {
+    const i = argv.indexOf("--scope");
+    runScript("plugins/agent-os/skills/init/scripts/settings.mjs",
+      ["--root", root, "--scope", i === -1 ? "both" : argv[i + 1], ...(argv.includes("--apply") ? ["--apply"] : [])]);
+    return;
+  }
+
   if (cmd === "memory") {
     runScript("plugins/agent-os/skills/memory/scripts/memory.mjs", argv.includes("--stale") ? [root, "--stale"] : [root]);
     return;
@@ -123,14 +138,28 @@ export async function main(argv) {
 
   let adopted = new Set();
 
+  let before = null;
   if (cmd === "init") {
     console.log(`\n${bold("agent-os init")}  ${root}\n`);
+    // Decide fresh vs repair before touching anything, and say which, so a
+    // second run on a set-up project reads as a repair rather than a re-init.
+    before = setupState(root);
+    for (const l of describeState(before)) console.log(`  ${l}`);
+    console.log({
+      fresh: `\n  ${dim("Fresh setup: creating everything.")}`,
+      repair: `\n  ${dim("Existing setup: fixing the items marked MISSING, leaving the rest as it is.")}`,
+      healthy: `\n  ${dim("Setup is complete: re-syncing and checking the plugin for updates.")}`,
+    }[before.status]);
+    console.log("");
     console.log(summarise(found));
+    const hadSource = existsSync(join(root, DIR));
     const { present, taken } = scaffold(root, found);
     adopted = taken.paths;
     if (taken.from.length) {
       console.log(`\n  adopted into ${DIR}/ ${dim("— your existing files are now the source")}`);
       for (const f of taken.from) console.log(`    ${f}`);
+    } else if (hadSource) {
+      console.log(`\n  kept ${DIR}/ ${dim("— already the source; nothing re-scaffolded")}`);
     } else {
       console.log(`\n  created ${DIR}/ ${dim("(config.json, AGENTS.md, rules/example.md)")}`);
     }
@@ -214,36 +243,58 @@ Pick one:
     if (cmd === "init" && targets.includes("claude-code")) {
       console.log(`\n${bold("Claude Code setup")}\n`);
 
-      const e = ensureTodoEnv(root, { dry });
-      const eMsg = {
-        added: `  ${e.rel}  ${dim(`env.${TODO_ENV} = "1"`)}`,
-        present: `  ${e.rel}  ${dim(`env.${TODO_ENV} already set`)}`,
-        conflict: `  ${e.rel}  ${dim(`env.${TODO_ENV} is "${e.current}" — left as you set it`)}`,
-        invalid: `  ${e.rel}  ${dim("is not valid JSON — left alone, fix it and re-run")}`,
-      }[e.status];
-      console.log(eMsg);
-
-      const t = ensureTaskRule(root, { dry });
-      const tMsg = {
-        added: `  ${t.rel}  ${dim(`task-tracking rule added under ${t.section}`)}`,
-        present: `  ${t.rel}  ${dim("task-tracking rule already there")}`,
-        "no-file": `  ${t.rel}  ${dim("absent — run /agent-os:init inside Claude Code to build it")}`,
-      }[t.status];
-      console.log(tMsg);
+      // Project scope always: it travels with the repo. User scope protects
+      // every other project on the machine too, so it is asked once rather
+      // than assumed — unless --global / --no-global already answered.
+      for (const l of describe(applyScope("project", root, { dry }), { dry })) console.log(`  ${l}`);
+
+      let global = argv.includes("--global") ? true : argv.includes("--no-global") ? false : null;
+      if (global === null && !dry && process.stdin.isTTY && process.stdout.isTTY) {
+        console.log("");
+        for (const l of describe(applyScope("user", root, { dry: true }), { dry: true })) console.log(`  ${l}`);
+        const rl = createInterface({ input: process.stdin, output: process.stdout });
+        const a = (await rl.question(`\n  Apply the same to ~/.claude (every project on this machine)? [Y/n] `)).trim().toLowerCase();
+        rl.close();
+        global = a === "" || a === "y" || a === "yes";
+      }
+      if (global) {
+        console.log("");
+        for (const l of describe(applyScope("user", root, { dry }), { dry })) console.log(`  ${l}`);
+      } else if (global === null) {
+        console.log(`\n  ${dim("~/.claude left alone (not a terminal). To protect every project:")}`);
+        console.log(`  ${dim("npx @sayansr26/agent-os settings --scope user --apply")}`);
+      }
     }
 
     if (cmd === "init" && targets.includes("claude-code") && !argv.includes("--no-plugin")) {
-      console.log(`\n${bold("Claude Code plugin")} ${dim(`${PLUGIN}@${MARKETPLACE_NAME}`)}\n`);
-      const r = installPlugin({ dry });
-      for (const line of r.done) console.log(`  ${dim(line)}`);
-      if (r.ok && r.reason === "installed") {
-        console.log(`\n  installed at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`);
-        console.log(`  ${dim("restart Claude Code, or /reload-plugins, then run /agent-os:init")}`);
-      } else if (!r.ok) {
-        console.log("");
-        for (const line of r.hint) console.log(`  ${line}`);
+      // Both come from the same marketplace, so it is added or refreshed once:
+      // by the first plugin whose run gets that far.
+      let refresh = true;
+      for (const plugin of PLUGINS.filter((p) => p === PLUGIN || !argv.includes(`--no-${p}`))) {
+        console.log(`\n${bold("Claude Code plugin")} ${dim(`${plugin}@${MARKETPLACE_NAME}`)}\n`);
+        const r = ensurePlugin({ root, dry, plugin, refresh });
+        if (r.done.length || r.reason === "no-cli") refresh = false;
+        for (const line of r.done) console.log(`  ${dim(line)}`);
+        if (r.ok) console.log({
+          installed: `\n  installed ${r.to || ""} at project scope ${dim("— .claude/settings.json, so it travels with the repo")}`,
+          updated: `\n  updated ${r.from} → ${r.to}`,
+          current: `\n  already the latest (${r.to})`,
+          "dry-run": `\n  ${dim(r.from ? `installed: ${r.from} — would refresh and update` : "not installed — would install")}`,
+        }[r.reason]);
+        for (const line of r.hint) console.log(`  ${r.ok ? dim(line) : line}`);
+        if (r.reason === "installed" || r.reason === "updated")
+          console.log(`  ${dim("restart Claude Code, or /reload-plugins, to load it")}`);
+      }
+      console.log(`\n  ${dim("--no-plugin skips this; --no-auto-route skips only the model router")}`);
+    }
+
+    if (cmd === "init" && !dry) {
+      const after = setupState(root);
+      console.log(`\n${bold("Result")}  ${before.status} → ${after.status}`);
+      if (after.missing.length) {
+        console.log(dim("  still to do:"));
+        for (const i of after.missing) console.log(`    ${i.label}  → ${i.fix}`);
       }
-      console.log(`\n  ${dim("--no-plugin skips this")}`);
     }
     console.log("");
     return;

package/src/plugin.mjs

@@ -1,23 +1,46 @@
 /**
- * Install the Claude Code half of agent-os during `init`.
+ * Install or update the Claude Code half of agent-os during `init`.
  *
  * The CLI compiles rules for every tool. Claude Code additionally gets the
- * agents, skills, per-agent memory and session hook, which ship as a plugin —
- * so `init` should install it rather than printing two slash commands and
- * hoping. `claude plugin ...` with `--yes` is the documented automation path.
+ * agents, skills, per-agent memory and hooks, which ship as a plugin, and
+ * auto-route, a mod that picks the model and effort per turn. Both live in
+ * this repo's marketplace. `init` brings each to the latest version whatever
+ * state it finds:
  *
- * Everything here is best effort and reversible: if the `claude` CLI is not on
- * PATH, or a command fails, `init` reports it and carries on. The rules are the
- * part that must not depend on this.
+ *   not installed        marketplace add + install, at project scope
+ *   installed, disabled  enable
+ *   installed            refresh the marketplace, then update
+ *
+ * An installed plugin is never left behind: Claude Code pins the cached
+ * version, so a project installed once stays on that version until something
+ * updates it — which is how a project ended up running 0.4.1 hooks.
+ *
+ * Every command runs with the project as its working directory, so project
+ * scope means *this* project even with --root. Best effort throughout: if the
+ * `claude` CLI is missing or a command fails, `init` reports it and carries
+ * on. The rules are the part that must not depend on this.
  */
 import { spawnSync } from "node:child_process";
+import { readFileSync, realpathSync } from "node:fs";
+import { cmpVersion } from "../plugins/agent-os/skills/init/scripts/state.mjs";
 
 export const MARKETPLACE = "sayansr26/agent-os";
 export const MARKETPLACE_NAME = "sayan-plugins";
 export const PLUGIN = "agent-os";
+// Installed by `init` in this order; each can be skipped with --no-<name>.
+export const PLUGINS = [PLUGIN, "auto-route"];
+const idOf = (plugin) => `${plugin}@${MARKETPLACE_NAME}`;
 
-const run = (args) =>
-  spawnSync("claude", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+const run = (args, cwd) =>
+  spawnSync("claude", args, { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 120000 });
+const json = (r) => { try { return JSON.parse(r.stdout); } catch { return null; } };
+const real = (p) => { try { return realpathSync(p); } catch { return p; } };
+/** The version this package ships for a plugin, from its plugin.json. */
+const bundled = (plugin) => {
+  try { return JSON.parse(readFileSync(new URL(`../plugins/${plugin}/.claude-plugin/plugin.json`, import.meta.url), "utf8")).version || null; }
+  catch { return null; }
+};
+const tail = (r) => (r.stderr || r.stdout || String(r.error || "")).trim().split("\n").slice(-3);
 
 /** Is the Claude Code CLI usable from here? */
 export function claudeAvailable() {
@@ -25,50 +48,83 @@ export function claudeAvailable() {
   return !r.error && r.status === 0;
 }
 
+/** This project's install of a plugin, per `claude plugin list --json`, or null. */
+export function installed(root, plugin = PLUGIN) {
+  const list = json(run(["plugin", "list", "--json"], root));
+  if (!Array.isArray(list)) return null;
+  const mine = list.filter((p) => p.id === idOf(plugin) &&
+    (p.scope === "user" || (p.projectPath && real(p.projectPath) === real(root))));
+  return mine.find((p) => p.scope === "project" || p.scope === "local") || mine[0] || null;
+}
+
 /**
- * Add the marketplace and install the plugin at project scope, so the setup
- * travels with the repository instead of living on one machine.
+ * Bring a plugin to the latest version for this project.
+ * Returns { ok, reason, from, to, done, hint } with reason one of
+ * "installed" | "updated" | "current" | "dry-run" | "no-cli" | "failed".
+ * `refresh: false` skips the marketplace step when an earlier call this run
+ * already added or updated it.
  */
-export function installPlugin({ dry = false, scope = "project" } = {}) {
-  const steps = [
-    ["marketplace", ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]],
-    ["plugin", ["plugin", "install", `${PLUGIN}@${MARKETPLACE_NAME}`, "--scope", scope, "--yes"]],
-  ];
-
+export function ensurePlugin({ root = process.cwd(), dry = false, scope = "project", plugin = PLUGIN, refresh = true } = {}) {
+  const ID = idOf(plugin);
   if (!claudeAvailable())
     return {
-      ok: false,
-      reason: "no-cli",
-      done: [],
+      ok: false, reason: "no-cli", done: [],
       hint: [
-        "The `claude` CLI is not on PATH, so the plugin was not installed.",
-        "Inside Claude Code, run:",
-        `  /plugin marketplace add ${MARKETPLACE}`,
-        `  /plugin install ${PLUGIN}@${MARKETPLACE_NAME}`,
+        ...(refresh ? [
+          "The `claude` CLI is not on PATH, so the plugin was not installed or updated.",
+          "Inside Claude Code, run:",
+          `  /plugin marketplace add ${MARKETPLACE}`,
+        ] : []),
+        `  /plugin install ${ID}     (or /plugin update ${ID} if it is already there)`,
       ],
     };
 
+  const before = installed(root, plugin);
+  const steps = [];
+  if (refresh) {
+    const markets = json(run(["plugin", "marketplace", "list", "--json"], root));
+    const haveMarket = Array.isArray(markets) && markets.some((m) => m.name === MARKETPLACE_NAME);
+    steps.push(haveMarket
+      ? ["plugin", "marketplace", "update", MARKETPLACE_NAME]
+      : ["plugin", "marketplace", "add", MARKETPLACE, "--scope", scope]);
+  }
+  if (!before) steps.push(["plugin", "install", ID, "--scope", scope, "--yes"]);
+  else {
+    if (before.enabled === false) steps.push(["plugin", "enable", ID, "--scope", before.scope]);
+    steps.push(["plugin", "update", ID, "--scope", before.scope, "--yes"]);
+  }
+
   if (dry)
-    return { ok: true, reason: "dry-run", done: steps.map(([, a]) => `claude ${a.join(" ")}`), hint: [] };
+    return { ok: true, reason: "dry-run", from: before?.version || null, done: steps.map((a) => `claude ${a.join(" ")}`), hint: [] };
 
   const done = [];
-  for (const [what, args] of steps) {
-    const r = run(args);
+  for (const args of steps) {
+    const r = run(args, root);
     if (r.status !== 0) {
-      const err = (r.stderr || r.stdout || "").trim().split("\n").slice(-3).join("\n");
       return {
-        ok: false,
-        reason: what,
-        done,
+        ok: false, reason: "failed", from: before?.version || null, done,
         hint: [
           `\`claude ${args.join(" ")}\` failed:`,
-          ...err.split("\n").map((l) => `  ${l}`),
-          "The rules above were still written. Install the plugin by hand inside",
-          `Claude Code: /plugin install ${PLUGIN}@${MARKETPLACE_NAME}`,
+          ...tail(r).map((l) => `  ${l}`),
+          "The rules and settings above were still written. Inside Claude Code:",
+          before ? `  /plugin update ${ID}, then /reload-plugins` : `  /plugin install ${ID}`,
         ],
       };
     }
     done.push(`claude ${args.join(" ")}`);
   }
-  return { ok: true, reason: "installed", done, hint: [] };
+
+  const after = installed(root, plugin);
+  const to = after?.version || null;
+  const from = before?.version || null;
+  const want = bundled(plugin);
+  const hint = [];
+  // The marketplace serves what is pushed to GitHub; this package may be newer.
+  if (to && want && cmpVersion(to, want) < 0)
+    hint.push(`Marketplace still serves ${plugin} ${to}; this agent-os ships ${want}. It updates once ${MARKETPLACE} is pushed.`);
+  return {
+    ok: true,
+    reason: !before ? "installed" : from !== to ? "updated" : "current",
+    from, to, done, hint,
+  };
 }

package/src/selftest.mjs

@@ -8,6 +8,12 @@ import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
 const PKG = join(fileURLToPath(new URL(".", import.meta.url)), "..");
+// Every child inherits this, so nothing here can ever touch the real ~/.claude.
+const HOME = mkdtempSync(join(tmpdir(), "agent-os-home-"));
+process.env.CLAUDE_CONFIG_DIR = HOME;
+const PLUGIN = join(PKG, "plugins/agent-os");
+const node = (script, args, opts = {}) =>
+  spawnSync(process.execPath, [join(PLUGIN, script), ...args], { encoding: "utf8", ...opts });
 const cli = (args, cwd) => spawnSync(process.execPath, [join(PKG, "bin/agent-os.mjs"), ...args, "--root", cwd], { encoding: "utf8" });
 let fail = 0;
 const ok = (c, m) => { console.log(`  ${c ? "ok  " : "FAIL"} ${m}`); if (!c) fail++; };
@@ -85,15 +91,21 @@ try {
     ok(existsSync(join(r2, ".agent-os/rules/theming.md")), "existing .claude/rules/ are adopted");
     ok(!existsSync(join(r2, ".agent-os/rules/example.md")), "no example.md when real rules were adopted");
     ok(!existsSync(join(r2, ".claude/rules/example.md")), "no example.md compiled into the project");
-    ok(!i.stdout.includes("Claude Code plugin"), "--no-plugin skips the plugin install");
+    ok(!i.stdout.includes("--no-plugin skips this"), "--no-plugin skips the plugin install");
 
     // init offers the plugin when not told otherwise; --dry-run proves the
     // commands without running them against the machine's real config.
     const r4 = mkdtempSync(join(tmpdir(), "agent-os-plug-"));
     const pi = cli(["init", "--dry-run"], r4);
-    ok(pi.stdout.includes("Claude Code plugin"), "init sets up the Claude Code plugin by default");
+    ok(pi.stdout.includes("--no-plugin skips this"), "init sets up the Claude Code plugin by default");
+    ok(pi.stdout.includes("SETUP  FRESH"), "init on an empty project reports a fresh setup");
     ok(/marketplace add sayansr26\/agent-os|plugin marketplace add|not on PATH/.test(pi.stdout),
        "init names the marketplace step or says why it could not run it");
+    ok(pi.stdout.includes("auto-route@sayan-plugins"), "init sets up auto-route by default");
+    ok((pi.stdout.match(/marketplace add/g) || []).length <= 1, "the marketplace is added once, not per plugin");
+    const na = cli(["init", "--dry-run", "--no-auto-route"], r4);
+    ok(!/install auto-route@sayan-plugins/.test(na.stdout) && /install agent-os@sayan-plugins/.test(na.stdout),
+       "--no-auto-route keeps agent-os and skips auto-route");
     rmSync(r4, { recursive: true, force: true });
 
     // A hand-written file at a generated path must survive a sync.
@@ -129,6 +141,20 @@ try {
     ok(st.env.CLAUDE_CODE_ENABLE_TODO_TOOLS === "1", "todo tools enabled in project settings");
     ok(st.env.FOO === "bar", "existing env keys preserved");
     ok(st.permissions?.deny?.[0] === "Bash(git push *)", "existing permissions preserved");
+    ok(st.permissions.deny.length === 42, "git write protection merged into project settings, no duplicate push rule");
+    ok(!existsSync(join(HOME, "settings.json")), "without --global (and no terminal) ~/.claude is left alone");
+    ok(!existsSync(join(r5, ".claude/settings.json.agent-os.bak")), "no backup litter inside the project");
+
+    const again = cli(["init", "--no-plugin", "--global"], r5).stdout;
+    ok(again.includes("SETUP  REPAIR") && again.includes("MISSING ~/.claude/settings.json git write protection"),
+       "init on a set-up project reports a repair and names what is missing");
+    ok(again.includes("kept .agent-os/"), "repair keeps the existing source instead of re-scaffolding");
+    const us = JSON.parse(readFileSync(join(HOME, "settings.json"), "utf8"));
+    ok(us.permissions.deny.includes("Bash(git commit *)") && us.env.CLAUDE_CODE_ENABLE_TODO_TOOLS === "1",
+       "--global writes git protection and task tools to ~/.claude/settings.json");
+    ok(readFileSync(join(HOME, "CLAUDE.md"), "utf8").includes("TaskCreate"), "--global adds the task rule to ~/.claude/CLAUDE.md");
+    cli(["init", "--no-plugin", "--global"], r5);
+    ok(JSON.parse(readFileSync(join(HOME, "settings.json"), "utf8")).permissions.deny.length === 42, "second --global run adds nothing");
 
     const cm = readFileSync(join(r5, "CLAUDE.md"), "utf8");
     ok(cm.includes("TaskCreate / TaskUpdate"), "task-tracking rule added to CLAUDE.md");
@@ -155,13 +181,51 @@ try {
     rmSync(r6, { recursive: true, force: true });
   }
 
+  console.log("\n  plugin hooks");
+  {
+    const r7 = mkdtempSync(join(tmpdir(), "agent-os-hooks-"));
+    const mem = join(r7, ".claude/agent-memory/agent-os-feature-cartographer");
+    mkdirSync(mem, { recursive: true });
+    for (const f of ["billing", "orders", "search"]) mkdirSync(join(r7, "src/features", f), { recursive: true });
+    writeFileSync(join(mem, "_architecture.md"), "# Architecture\n");
+    writeFileSync(join(mem, "billing.md"), "---\nmapped: 2026-01-01\nentry: src/features/billing/index.ts\n---\n# billing\n");
+    writeFileSync(join(mem, "MEMORY.md"), "- billing — src/features/billing — mapped 2026-01-01\n");
+    mkdirSync(join(r7, ".agent-os/rules"), { recursive: true });
+    writeFileSync(join(r7, ".agent-os/rules/api.md"), '---\npaths:\n  - "src/**"\n---\n\nSource body.\n');
+    mkdirSync(join(r7, ".claude/rules"), { recursive: true });
+    writeFileSync(join(r7, ".claude/rules/api.md"), "---\n---\n\n<!-- agent-os: generated from .agent-os/ — edit the source -->\nEdited in place.\n");
+    const env = { ...process.env, CLAUDE_PROJECT_DIR: r7 };
+
+    const start = node("hooks/session-resume.mjs", [], { cwd: r7, env }).stdout;
+    ok(start.includes("agent-os is active") && start.includes("agent-os:feature-cartographer"), "session start announces the agents");
+    ok(start.includes("Mapped: 1 of 3 features") && start.includes("billing"), "session start says what is mapped");
+
+    const run = `selftest-${process.pid}-${Date.now()}`;
+    const edit = (file, session = run) => node("hooks/pre-edit.mjs", [], {
+      env, input: JSON.stringify({ session_id: session, cwd: r7, tool_input: { file_path: join(r7, file) } }),
+    }).stdout;
+    const denied = edit(".claude/rules/api.md");
+    ok(denied.includes('"deny"') && denied.includes(".agent-os/rules/api.md"), "edit to a generated rule is blocked, source named");
+    ok(edit("src/features/orders/a.ts").includes("no cartographer map"), "first edit to an unmapped feature reminds");
+    ok(edit("src/features/orders/b.ts") === "", "reminder shows once per feature per session");
+    ok(edit("src/features/billing/a.ts") === "", "mapped feature stays silent");
+    ok(edit("src/lib/x.ts") === "", "non-feature path stays silent");
+
+    mkdirSync(join(mem, ".claude/agent-memory"), { recursive: true });
+    const audit = node("skills/init/scripts/audit.mjs", [r7]).stdout;
+    ok(/api\.md was edited in place/.test(audit), "audit flags a generated rule that drifted from its source");
+    ok(audit.includes("folder inside agent memory"), "audit flags a nested folder in agent memory");
+    ok(audit.includes("1 of 3 (33%)"), "audit reports map coverage, not just that a folder exists");
+    rmSync(r7, { recursive: true, force: true });
+  }
+
   console.log("\n  merge, not overwrite");
   writeFileSync(join(root, "opencode.json"), JSON.stringify({ model: "anthropic/x", instructions: ["KEEP.md"] }, null, 2));
   cli(["sync"], root);
   const oc = JSON.parse(read("opencode.json"));
   ok(oc.model === "anthropic/x", "existing keys preserved");
   ok(oc.instructions.includes("KEEP.md"), "existing instructions preserved");
-} finally { rmSync(root, { recursive: true, force: true }); }
+} finally { rmSync(root, { recursive: true, force: true }); rmSync(HOME, { recursive: true, force: true }); }
 
 console.log(`\n${fail ? `FAILED (${fail})` : "PASSED"}\n`);
 process.exit(fail ? 1 : 0);