mindgraph-mcp 0.13.5 → 0.14.1

package/dist/cli.js

@@ -26,13 +26,1434 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// src/codegraph.ts
+function normalizePath(path6) {
+  return path6.replaceAll("\\", "/").replace(/^\.\//, "");
+}
+function normalizeSignature(signature) {
+  return signature.replace(/\s+/g, " ").trim();
+}
+function languageFromPath(path6) {
+  const extension = (0, import_node_path2.extname)(path6).toLowerCase();
+  return {
+    ".c": "c",
+    ".cc": "cpp",
+    ".cpp": "cpp",
+    ".go": "go",
+    ".java": "java",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".kt": "kotlin",
+    ".py": "python",
+    ".rb": "ruby",
+    ".rs": "rust",
+    ".swift": "swift",
+    ".ts": "typescript",
+    ".tsx": "typescript"
+  }[extension] ?? "unknown";
+}
+function asNode(hit) {
+  return hit.node ?? hit;
+}
+function toCandidate(node) {
+  if (!node.filePath || !node.kind || !(node.qualifiedName || node.name)) return null;
+  return {
+    path: normalizePath(node.filePath),
+    language: node.language ?? languageFromPath(node.filePath),
+    kind: node.kind,
+    qualifiedName: node.qualifiedName ?? node.name ?? "",
+    signature: node.signature ?? null,
+    startLine: node.startLine ?? 1,
+    endLine: node.endLine ?? node.startLine ?? 1
+  };
+}
+function normalizeRemote(remote) {
+  const trimmed = remote.trim();
+  if (!trimmed) return null;
+  const scp = /^(?:[^@]+@)?([^:]+):(.+)$/.exec(trimmed);
+  if (scp && !trimmed.includes("://")) {
+    return `${scp[1].toLowerCase()}/${scp[2].replace(/\.git$/, "")}`;
+  }
+  try {
+    const url = new URL(trimmed);
+    const pathname = url.pathname.replace(/\/$/, "").replace(/\.git$/, "");
+    return `${url.host.toLowerCase()}${pathname}`;
+  } catch {
+    return null;
+  }
+}
+function pathContains(root, candidate) {
+  const child = (0, import_node_path2.relative)(root, candidate);
+  return child === "" || child !== ".." && !child.startsWith(`..${import_node_path2.sep}`) && !(0, import_node_path2.isAbsolute)(child);
+}
+function nearestExistingDirectory(candidate) {
+  let current = (0, import_node_path2.resolve)(candidate);
+  for (; ; ) {
+    if ((0, import_node_fs2.existsSync)(current)) {
+      try {
+        return (0, import_node_fs2.statSync)(current).isDirectory() ? current : (0, import_node_path2.dirname)(current);
+      } catch {
+      }
+    }
+    const parent = (0, import_node_path2.dirname)(current);
+    if (parent === current) return current;
+    current = parent;
+  }
+}
+function findWorkspaceFile(start, explicit) {
+  if (explicit) return (0, import_node_path2.resolve)(start, explicit);
+  let current = (0, import_node_path2.resolve)(start);
+  for (; ; ) {
+    const candidate = (0, import_node_path2.join)(current, ".mindgraph", "workspace.json");
+    if ((0, import_node_fs2.existsSync)(candidate)) return candidate;
+    const parent = (0, import_node_path2.dirname)(current);
+    if (parent === current) return void 0;
+    current = parent;
+  }
+}
+async function runProcess(executable, args, timeoutMs, env, cwd) {
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = (0, import_node_child_process.spawn)(executable, args, {
+      cwd,
+      env,
+      stdio: ["ignore", "pipe", "pipe"],
+      windowsHide: true
+    });
+    const stdout = [];
+    const stderr = [];
+    let outputBytes = 0;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill("SIGTERM");
+      setTimeout(() => child.kill("SIGKILL"), 250).unref();
+    }, timeoutMs);
+    timer.unref();
+    const collect = (target) => (chunk) => {
+      outputBytes += chunk.length;
+      if (outputBytes > MAX_OUTPUT_BYTES) {
+        child.kill("SIGTERM");
+        return;
+      }
+      target.push(chunk);
+    };
+    child.stdout.on("data", collect(stdout));
+    child.stderr.on("data", collect(stderr));
+    child.on("error", (cause) => {
+      clearTimeout(timer);
+      const error = new Error(cause.message);
+      error.kind = cause.code === "ENOENT" ? "absent" : "command_failed";
+      rejectPromise(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (timedOut) {
+        const error = new Error(`command timed out after ${timeoutMs}ms`);
+        error.kind = "timeout";
+        rejectPromise(error);
+        return;
+      }
+      if (outputBytes > MAX_OUTPUT_BYTES) {
+        const error = new Error("codegraph output exceeded 5 MiB");
+        error.kind = "command_failed";
+        rejectPromise(error);
+        return;
+      }
+      if (code !== 0) {
+        const error = new Error(Buffer.concat(stderr).toString("utf8").trim());
+        error.kind = "command_failed";
+        error.exitCode = code;
+        rejectPromise(error);
+        return;
+      }
+      resolvePromise(Buffer.concat(stdout).toString("utf8"));
+    });
+  });
+}
+function repositoryIdentityKey(repository) {
+  return { v: 1, kind: "repository", repo_id: repository.repoId };
+}
+function codeRefIdentityKey(ref) {
+  if (ref.kind === "file") {
+    return {
+      v: 1,
+      kind: "file",
+      repo_id: ref.repoId,
+      path: ref.path
+    };
+  }
+  return {
+    v: 1,
+    kind: "symbol",
+    repo_id: ref.repoId,
+    language: ref.language,
+    symbol_kind: ref.kind,
+    qualified_name: ref.qualifiedName,
+    disambiguator: {
+      signature: ref.signature ?? "",
+      path: ref.path,
+      start_line: ref.startLine,
+      end_line: ref.endLine
+    }
+  };
+}
+var import_node_child_process, import_node_fs2, import_promises, import_node_os2, import_node_path2, import_node_crypto, DEFAULT_TIMEOUT_MS, DEFAULT_STATUS_TTL_MS, MAX_OUTPUT_BYTES, CodegraphAdapter;
+var init_codegraph = __esm({
+  "src/codegraph.ts"() {
+    "use strict";
+    import_node_child_process = require("child_process");
+    import_node_fs2 = require("fs");
+    import_promises = require("fs/promises");
+    import_node_os2 = require("os");
+    import_node_path2 = require("path");
+    import_node_crypto = require("crypto");
+    DEFAULT_TIMEOUT_MS = 5e3;
+    DEFAULT_STATUS_TTL_MS = 6e4;
+    MAX_OUTPUT_BYTES = 5 * 1024 * 1024;
+    CodegraphAdapter = class {
+      timeoutMs;
+      statusTtlMs;
+      env;
+      cwd;
+      workspaceFile;
+      now;
+      identityCache = /* @__PURE__ */ new Map();
+      statusCache = /* @__PURE__ */ new Map();
+      constructor(options = {}) {
+        this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.statusTtlMs = options.statusTtlMs ?? DEFAULT_STATUS_TTL_MS;
+        this.env = options.env ?? process.env;
+        this.cwd = options.cwd ?? process.cwd();
+        this.workspaceFile = findWorkspaceFile(
+          this.cwd,
+          options.workspaceFile ?? this.env.MINDGRAPH_WORKSPACE_FILE
+        );
+        this.now = options.now ?? Date.now;
+      }
+      async resolveRepository(repo, fallbackSpaceUid) {
+        const configured = await this.resolveRepositories(fallbackSpaceUid);
+        const selected = repo && configured.find((candidate) => candidate.repoId === repo) || repo && configured.find(
+          (candidate) => candidate.repoRoot === repo || (0, import_node_path2.basename)(candidate.repoRoot) === repo
+        ) || (!repo ? [...configured].sort((a, b) => b.repoRoot.length - a.repoRoot.length).find((candidate) => pathContains(candidate.repoRoot, this.cwd)) : void 0) || (!repo && configured.length === 1 ? configured[0] : void 0);
+        if (selected) {
+          return !repo && this.env.MINDGRAPH_REPO_ID ? this.resolveRepositoryIdentity(
+            selected.repoRoot,
+            this.env.MINDGRAPH_REPO_ID,
+            selected.spaceUid
+          ) : selected;
+        }
+        const requestedRoot = repo || this.env.MINDGRAPH_REPO_ROOT || this.cwd;
+        const requestedPath = await (0, import_promises.realpath)((0, import_node_path2.resolve)(this.cwd, requestedRoot)).catch(
+          () => (0, import_node_path2.resolve)(this.cwd, requestedRoot)
+        );
+        const repoRoot = await this.gitRoot(requestedPath) ?? requestedPath;
+        return this.resolveRepositoryIdentity(
+          repoRoot,
+          this.env.MINDGRAPH_REPO_ID,
+          this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+        );
+      }
+      async resolveRepositories(fallbackSpaceUid) {
+        return Promise.all(
+          this.configuredRepositories().map(
+            (repository) => this.resolveRepositoryIdentity(
+              repository.repoRoot,
+              repository.repoId,
+              repository.spaceUid || this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+            )
+          )
+        );
+      }
+      async resolveRepositoryIdentity(root, explicitRepoId, spaceUid) {
+        const repoRoot = await (0, import_promises.realpath)(root).catch(() => (0, import_node_path2.resolve)(root));
+        const cacheKey = `${repoRoot}\0${explicitRepoId ?? ""}\0${spaceUid ?? ""}`;
+        const cached = this.identityCache.get(cacheKey);
+        if (cached) return cached;
+        const pending = this.loadRepositoryIdentity(repoRoot, explicitRepoId, spaceUid);
+        this.identityCache.set(cacheKey, pending);
+        return pending;
+      }
+      async loadRepositoryIdentity(repoRoot, explicitRepoId, spaceUid) {
+        const remote = await runProcess(
+          "git",
+          ["-C", repoRoot, "config", "--get", "remote.origin.url"],
+          Math.min(this.timeoutMs, 2e3),
+          this.env
+        ).catch(() => "");
+        const repoId = explicitRepoId || normalizeRemote(remote) || await this.persistedRepositoryId(repoRoot);
+        return {
+          repoId,
+          repoRoot,
+          spaceUid
+        };
+      }
+      async persistedRepositoryId(repoRoot) {
+        const rawCommonDir = await runProcess(
+          "git",
+          ["-C", repoRoot, "rev-parse", "--git-common-dir"],
+          Math.min(this.timeoutMs, 2e3),
+          this.env
+        ).catch(() => "");
+        if (!rawCommonDir.trim()) {
+          return `local:${(0, import_node_path2.basename)(repoRoot)}`;
+        }
+        const commonDir = (0, import_node_path2.resolve)(repoRoot, rawCommonDir.trim());
+        const identityDir = (0, import_node_path2.join)(commonDir, "mindgraph");
+        const identityFile = (0, import_node_path2.join)(identityDir, "repository-id");
+        try {
+          const existing = (0, import_node_fs2.readFileSync)(identityFile, "utf8").trim();
+          if (existing) return existing;
+        } catch {
+        }
+        (0, import_node_fs2.mkdirSync)(identityDir, { recursive: true, mode: 448 });
+        const generated = (0, import_node_crypto.randomUUID)();
+        try {
+          (0, import_node_fs2.writeFileSync)(identityFile, `${generated}
+`, {
+            encoding: "utf8",
+            flag: "wx",
+            mode: 384
+          });
+          return generated;
+        } catch (cause) {
+          if (cause.code !== "EEXIST") throw cause;
+          const winner = (0, import_node_fs2.readFileSync)(identityFile, "utf8").trim();
+          if (!winner) throw new Error(`empty repository identity file: ${identityFile}`);
+          return winner;
+        }
+      }
+      async gitRoot(candidate) {
+        const start = nearestExistingDirectory(candidate);
+        const raw = await runProcess(
+          "git",
+          ["-C", start, "rev-parse", "--show-toplevel"],
+          Math.min(this.timeoutMs, 2e3),
+          this.env
+        ).catch(() => "");
+        return raw.trim() ? (0, import_node_path2.resolve)(start, raw.trim()) : void 0;
+      }
+      async availability(repository) {
+        const cached = this.statusCache.get(repository.repoRoot);
+        if (cached && cached.expiresAt > this.now()) return cached.availability;
+        try {
+          const status = await this.runJson([
+            "status",
+            repository.repoRoot,
+            "-j"
+          ]);
+          const caveats = [];
+          let availability;
+          if (status.worktreeMismatch != null) {
+            availability = {
+              available: false,
+              reason: "wrong_index",
+              stale: false,
+              caveats: ["the index belongs to a different worktree"],
+              lastIndexed: status.lastIndexed
+            };
+          } else if (!status.initialized || status.index?.state !== "complete") {
+            availability = {
+              available: false,
+              reason: "index_incomplete",
+              stale: false,
+              caveats: [
+                !status.initialized ? "codegraph is not initialized for this repository" : `codegraph index state is ${status.index?.state ?? "unknown"}`
+              ],
+              lastIndexed: status.lastIndexed
+            };
+          } else {
+            const pending = (status.pendingChanges?.added ?? 0) + (status.pendingChanges?.modified ?? 0) + (status.pendingChanges?.removed ?? 0);
+            if (pending > 0) caveats.push(`${pending} worktree changes are not indexed`);
+            if ((status.index?.pendingRefs ?? 0) > 0) {
+              caveats.push(`${status.index?.pendingRefs} references remain pending`);
+            }
+            if (status.index?.reindexRecommended) caveats.push("codegraph recommends reindexing");
+            availability = {
+              available: true,
+              stale: caveats.length > 0,
+              caveats,
+              lastIndexed: status.lastIndexed
+            };
+          }
+          this.statusCache.set(repository.repoRoot, {
+            status,
+            availability,
+            expiresAt: this.now() + this.statusTtlMs
+          });
+          return availability;
+        } catch (cause) {
+          const failure = cause;
+          return {
+            available: false,
+            reason: failure.kind ?? "command_failed",
+            stale: false,
+            caveats: [failure.message || "codegraph status failed"]
+          };
+        }
+      }
+      async resolveRefs(refs, options = {}) {
+        const normalized = refs.map(
+          (ref) => typeof ref === "string" ? { symbol: ref } : ref
+        );
+        const results = await Promise.all(
+          normalized.map(async (ref) => {
+            const repository2 = await this.repositoryForRef(
+              ref,
+              options.repo,
+              options.fallbackSpaceUid
+            );
+            const availability2 = await this.availability(repository2);
+            if (!availability2.available) {
+              return {
+                ref,
+                repository: repository2,
+                availability: availability2,
+                candidates: [],
+                error: availability2.reason
+              };
+            }
+            return {
+              ...await this.resolveOne(ref, repository2),
+              repository: repository2,
+              availability: availability2
+            };
+          })
+        );
+        const repositories = [
+          ...new Map(
+            results.flatMap(
+              (result) => result.repository ? [[result.repository.repoRoot, result.repository]] : []
+            )
+          ).values()
+        ];
+        const repository = repositories[0] ?? await this.resolveRepository(options.repo, options.fallbackSpaceUid);
+        if (repositories.length === 0) repositories.push(repository);
+        const availabilities = results.flatMap(
+          (result) => result.availability ? [result.availability] : []
+        );
+        const availability = availabilities.length === 0 ? await this.availability(repository) : {
+          available: availabilities.every((item) => item.available),
+          reason: availabilities.find((item) => !item.available)?.reason,
+          stale: availabilities.some((item) => item.stale),
+          caveats: [
+            ...new Set(availabilities.flatMap((item) => item.caveats))
+          ]
+        };
+        return { repository, repositories, availability, results };
+      }
+      async repositoryForRef(ref, defaultRepo, fallbackSpaceUid) {
+        if (ref.repo || defaultRepo) {
+          return this.resolveRepository(ref.repo || defaultRepo, fallbackSpaceUid);
+        }
+        if (ref.path) {
+          const requested = (0, import_node_path2.isAbsolute)(ref.path) ? (0, import_node_path2.resolve)(ref.path) : (0, import_node_path2.resolve)(this.cwd, ref.path);
+          const absolute = await (0, import_promises.realpath)(requested).catch(() => requested);
+          const configured = await this.resolveRepositories(fallbackSpaceUid);
+          const defining = [...configured].sort((a, b) => b.repoRoot.length - a.repoRoot.length).find((candidate) => pathContains(candidate.repoRoot, absolute));
+          if (defining) {
+            return this.env.MINDGRAPH_REPO_ID && pathContains(defining.repoRoot, this.cwd) ? this.resolveRepositoryIdentity(
+              defining.repoRoot,
+              this.env.MINDGRAPH_REPO_ID,
+              defining.spaceUid
+            ) : defining;
+          }
+          const gitRoot = await this.gitRoot(absolute);
+          if (gitRoot) {
+            return this.resolveRepositoryIdentity(
+              gitRoot,
+              this.env.MINDGRAPH_REPO_ID,
+              this.env.MINDGRAPH_CODE_SPACE_UID || fallbackSpaceUid
+            );
+          }
+        }
+        return this.resolveRepository(void 0, fallbackSpaceUid);
+      }
+      async expand(resolved, limit = 20) {
+        const repository = {
+          repoId: resolved.repoId,
+          repoRoot: resolved.repoRoot
+        };
+        const availability = await this.availability(repository);
+        if (!availability.available) {
+          return { availability, callers: [], callees: [], truncated: false };
+        }
+        const cap = Math.min(Math.max(limit, 1), 20);
+        const [callers, callees] = await Promise.all([
+          this.related("callers", resolved, cap + 1),
+          this.related("callees", resolved, cap + 1)
+        ]);
+        return {
+          availability,
+          callers: callers.slice(0, cap),
+          callees: callees.slice(0, cap),
+          truncated: callers.length > cap || callees.length > cap
+        };
+      }
+      async affected(resolved, limit = 50) {
+        const repository = {
+          repoId: resolved.repoId,
+          repoRoot: resolved.repoRoot
+        };
+        const availability = await this.availability(repository);
+        if (!availability.available) {
+          return { availability, affected: [], truncated: false };
+        }
+        const cap = Math.min(Math.max(limit, 1), 50);
+        const raw = await this.runJson([
+          "impact",
+          "-p",
+          resolved.repoRoot,
+          "-j",
+          "-d",
+          "2",
+          resolved.qualifiedName
+        ]);
+        const refs = (raw.affected ?? []).map((node) => ({
+          path: node.filePath,
+          line: node.startLine,
+          symbol: node.qualifiedName ?? node.name,
+          kind: node.kind
+        }));
+        const resolvedRefs = await this.resolveRelatedRefs(refs.slice(0, cap + 1), repository);
+        return {
+          availability,
+          affected: resolvedRefs.slice(0, cap),
+          truncated: refs.length > cap
+        };
+      }
+      configuredRepositories() {
+        const configured = [];
+        if (this.workspaceFile && (0, import_node_fs2.existsSync)(this.workspaceFile)) {
+          try {
+            const parsed = JSON.parse(
+              (0, import_node_fs2.readFileSync)(this.workspaceFile, "utf8")
+            );
+            if (parsed.v === 1 && Array.isArray(parsed.repositories)) {
+              const configDirectory = (0, import_node_path2.dirname)(this.workspaceFile);
+              const base = (0, import_node_path2.basename)(configDirectory) === ".mindgraph" ? (0, import_node_path2.dirname)(configDirectory) : configDirectory;
+              for (const repository of parsed.repositories) {
+                if (!repository || typeof repository.root !== "string") continue;
+                configured.push({
+                  repoId: typeof repository.repo_id === "string" ? repository.repo_id : void 0,
+                  repoRoot: (0, import_node_path2.resolve)(base, repository.root),
+                  spaceUid: typeof repository.space_uid === "string" ? repository.space_uid : void 0
+                });
+              }
+            }
+          } catch {
+          }
+        }
+        const raw = this.env.MINDGRAPH_CODE_REPOS;
+        if (raw) {
+          try {
+            const parsed = JSON.parse(raw);
+            for (const [repoId, config] of Object.entries(parsed)) {
+              configured.push({
+                repoId,
+                repoRoot: (0, import_node_path2.resolve)(
+                  this.cwd,
+                  typeof config === "string" ? config : config.root
+                ),
+                spaceUid: typeof config === "string" ? void 0 : config.space_uid
+              });
+            }
+          } catch {
+          }
+        }
+        return [
+          ...new Map(
+            configured.map((repository) => [repository.repoRoot, repository])
+          ).values()
+        ];
+      }
+      async resolveOne(ref, repository) {
+        const search = ref.symbol || ref.path;
+        if (!search || ref.line !== void 0 && (!Number.isInteger(ref.line) || ref.line < 1)) {
+          return { ref, candidates: [], error: "invalid_ref" };
+        }
+        try {
+          const args = ["query", "-p", repository.repoRoot, "-j", "-l", "50"];
+          if (ref.kind) args.push("-k", ref.kind);
+          args.push(search);
+          const hits = await this.runJson(args);
+          let candidates = hits.map(asNode).map(toCandidate).filter((item) => item !== null);
+          if (ref.path) {
+            const absolutePath = (0, import_node_path2.isAbsolute)(ref.path) ? await (0, import_promises.realpath)(ref.path).catch(() => ref.path) : void 0;
+            const wanted = normalizePath(
+              absolutePath ? (0, import_node_path2.relative)(repository.repoRoot, absolutePath) : ref.path
+            );
+            candidates = candidates.filter((candidate) => candidate.path === wanted);
+          }
+          if (ref.language) {
+            candidates = candidates.filter(
+              (candidate) => candidate.language.toLowerCase() === ref.language?.toLowerCase()
+            );
+          }
+          if (ref.kind) {
+            candidates = candidates.filter(
+              (candidate) => candidate.kind.toLowerCase() === ref.kind?.toLowerCase()
+            );
+          }
+          if (ref.symbol) {
+            const exact = candidates.filter((candidate) => {
+              const tail = candidate.qualifiedName.split(/::|\.|#/).at(-1);
+              return candidate.qualifiedName === ref.symbol || tail === ref.symbol;
+            });
+            if (exact.length > 0) candidates = exact;
+          }
+          if (ref.signature) {
+            const signature = normalizeSignature(ref.signature);
+            candidates = candidates.filter(
+              (candidate) => candidate.signature !== null && normalizeSignature(candidate.signature) === signature
+            );
+          }
+          if (ref.line !== void 0) {
+            candidates = candidates.filter(
+              (candidate) => candidate.startLine <= ref.line && candidate.endLine >= ref.line
+            );
+            if (candidates.length > 1) {
+              const narrowest = Math.min(
+                ...candidates.map((candidate) => candidate.endLine - candidate.startLine)
+              );
+              const narrowed = candidates.filter(
+                (candidate) => candidate.endLine - candidate.startLine === narrowest
+              );
+              if (narrowed.length === 1) candidates = narrowed;
+            }
+          }
+          if (candidates.length !== 1) {
+            return {
+              ref,
+              candidates,
+              error: candidates.length === 0 ? "not_found" : "ambiguous"
+            };
+          }
+          return {
+            ref,
+            candidates,
+            resolved: {
+              repoId: repository.repoId,
+              repoRoot: repository.repoRoot,
+              ...candidates[0]
+            }
+          };
+        } catch (cause) {
+          const failure = cause;
+          return {
+            ref,
+            candidates: [],
+            error: failure.kind ?? "command_failed"
+          };
+        }
+      }
+      async related(action, resolved, limit) {
+        const raw = await this.runJson([
+          action,
+          "-p",
+          resolved.repoRoot,
+          "-j",
+          "-l",
+          String(limit),
+          resolved.qualifiedName
+        ]);
+        const refs = (raw[action] ?? []).map((node) => ({
+          path: node.filePath,
+          line: node.startLine,
+          symbol: node.qualifiedName ?? node.name,
+          kind: node.kind
+        }));
+        return this.resolveRelatedRefs(refs, {
+          repoId: resolved.repoId,
+          repoRoot: resolved.repoRoot
+        });
+      }
+      async resolveRelatedRefs(refs, repository) {
+        const results = await Promise.all(refs.map((ref) => this.resolveOne(ref, repository)));
+        const seen = /* @__PURE__ */ new Set();
+        return results.flatMap((result) => result.resolved ? [result.resolved] : []).filter((result) => {
+          const key = `${result.path}:${result.qualifiedName}:${result.startLine}`;
+          if (seen.has(key)) return false;
+          seen.add(key);
+          return true;
+        });
+      }
+      async runJson(args) {
+        const candidates = [
+          this.env.MINDGRAPH_CODEGRAPH_BIN,
+          "codegraph",
+          (0, import_node_path2.resolve)((0, import_node_os2.homedir)(), ".local", "bin", "codegraph")
+        ].filter((candidate, index, all) => {
+          return Boolean(candidate) && all.indexOf(candidate) === index;
+        });
+        let lastFailure;
+        for (const executable of candidates) {
+          try {
+            const stdout = await runProcess(
+              executable,
+              args,
+              this.timeoutMs,
+              this.env,
+              this.cwd
+            );
+            return JSON.parse(stdout);
+          } catch (cause) {
+            const failure = cause;
+            lastFailure = failure;
+            if (failure.kind !== "absent") throw failure;
+          }
+        }
+        throw lastFailure ?? Object.assign(new Error("codegraph executable not found"), {
+          kind: "absent"
+        });
+      }
+    };
+  }
+});
+
+// src/error-detail.ts
+function errorDetail(e) {
+  if (e instanceof import_mindgraph.MindGraphError && e.body !== void 0) {
+    const detail = typeof e.body === "string" ? e.body : JSON.stringify(e.body);
+    return `${e.message} \u2014 ${detail}`;
+  }
+  return e instanceof Error ? e.message : String(e);
+}
+var import_mindgraph;
+var init_error_detail = __esm({
+  "src/error-detail.ts"() {
+    "use strict";
+    import_mindgraph = require("mindgraph");
+  }
+});
+
+// src/code-tool.ts
+async function handleCodeTool(client2, args, adapter = new CodegraphAdapter()) {
+  const codeClient = client2;
+  const action = args.action;
+  const refs = Array.isArray(args.code_refs) ? args.code_refs : [];
+  const anchorUids = Array.isArray(args.anchor_uids) ? args.anchor_uids : [];
+  const agentId = typeof args.agent_id === "string" ? args.agent_id : "mcp";
+  const fallbackSpaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : `space:agent:${agentId}`;
+  const options = {
+    repo: typeof args.repo === "string" ? args.repo : void 0,
+    fallbackSpaceUid
+  };
+  const limit = typeof args.limit === "number" ? args.limit : void 0;
+  try {
+    switch (action) {
+      case "anchor": {
+        if (refs.length === 0) return err("missing_code_refs", "code_refs is required for anchor");
+        const resolution = await adapter.resolveRefs(refs, options);
+        const resolved = resolution.results.flatMap(
+          (result) => result.resolved && result.repository ? [{ ref: result.resolved, repository: result.repository }] : []
+        );
+        const unresolved = resolution.results.filter((result) => !result.resolved);
+        if (resolved.length === 0) {
+          return ok({ ...resolution, anchors: [], wrote: false });
+        }
+        const missingSpace = resolved.find(
+          ({ repository }) => typeof args.repo_space_uid !== "string" && !repository.spaceUid
+        );
+        if (missingSpace) {
+          return err(
+            "missing_repository_space",
+            `repo_space_uid, a workspace space_uid, or MINDGRAPH_CODE_SPACE_UID is required for ${missingSpace.repository.repoId}`
+          );
+        }
+        const repositoryAnchors = /* @__PURE__ */ new Map();
+        for (const { repository } of resolved) {
+          if (repositoryAnchors.has(repository.repoRoot)) continue;
+          const spaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : repository.spaceUid;
+          const anchored = await anchorRepository(
+            codeClient,
+            repository,
+            spaceUid,
+            agentId
+          );
+          repositoryAnchors.set(repository.repoRoot, {
+            ...anchored,
+            repository
+          });
+        }
+        const anchors = [];
+        for (const { ref, repository } of resolved) {
+          const repositoryAnchor = repositoryAnchors.get(repository.repoRoot);
+          if (!repositoryAnchor.uid) continue;
+          const spaceUid = typeof args.repo_space_uid === "string" ? args.repo_space_uid : repository.spaceUid;
+          const anchor = await anchorCodeRef(
+            codeClient,
+            ref,
+            repositoryAnchor.uid,
+            spaceUid,
+            agentId
+          );
+          anchors.push(anchor);
+        }
+        return ok({
+          availability: resolution.availability,
+          repository: repositoryAnchors.values().next().value,
+          repositories: [...repositoryAnchors.values()],
+          anchors,
+          unresolved,
+          wrote: anchors.some((anchor) => anchor.created)
+        });
+      }
+      case "recall": {
+        const materialized = new Set(anchorUids);
+        let resolution;
+        if (refs.length > 0) {
+          resolution = await adapter.resolveRefs(refs, options);
+          for (const result of resolution.results) {
+            if (!result.resolved) continue;
+            const uid = await resolveMaterializedUid(codeClient, result.resolved, agentId);
+            if (uid) materialized.add(uid);
+          }
+        }
+        if (materialized.size === 0) {
+          return ok({
+            availability: resolution?.availability,
+            anchors: [],
+            context: [],
+            unresolved: resolution?.results.filter((result) => !result.resolved) ?? []
+          });
+        }
+        const context = await Promise.all(
+          [...materialized].map(async (uid) => ({
+            anchor_uid: uid,
+            graph: await codeClient.traverse({
+              action: "neighborhood",
+              start_uid: uid,
+              depth: 2,
+              max_nodes: Math.min(limit ?? 20, 20)
+            })
+          }))
+        );
+        return ok({
+          availability: resolution?.availability,
+          anchors: [...materialized],
+          context,
+          unresolved: resolution?.results.filter((result) => !result.resolved) ?? []
+        });
+      }
+      case "expand": {
+        const target = await resolveSingleTarget(
+          codeClient,
+          adapter,
+          refs,
+          anchorUids,
+          options
+        );
+        if ("error" in target) return target.error;
+        const expanded = await adapter.expand(target.ref, limit);
+        const joined = await joinMaterialized(
+          codeClient,
+          [...expanded.callers, ...expanded.callees],
+          agentId,
+          Math.min(limit ?? 20, 20)
+        );
+        return ok({ anchor: target.ref, ...expanded, materialized: joined });
+      }
+      case "affected": {
+        const targetUid = typeof args.task_uid === "string" ? args.task_uid : typeof args.execution_uid === "string" ? args.execution_uid : void 0;
+        let graphContext;
+        const graphRefs = [];
+        if (targetUid) {
+          graphContext = await codeClient.traverse({
+            action: "neighborhood",
+            start_uid: targetUid,
+            depth: 2,
+            max_nodes: 50
+          });
+          graphRefs.push(
+            ...await codeRefsFromGraphContext(codeClient, adapter, graphContext)
+          );
+        }
+        if (refs.length > 0 || anchorUids.length > 0) {
+          const target = await resolveSingleTarget(
+            codeClient,
+            adapter,
+            refs,
+            anchorUids,
+            options
+          );
+          if ("error" in target) return target.error;
+          graphRefs.unshift(target.ref);
+        }
+        const unique = uniqueRefs(graphRefs);
+        if (unique.length === 0) {
+          return ok({
+            target_uid: targetUid,
+            graph_context: graphContext,
+            affected: [],
+            degradation: "no materialized code anchors were attached"
+          });
+        }
+        const impacts = await Promise.all(
+          unique.map(async (ref) => ({ anchor: ref, ...await adapter.affected(ref, limit) }))
+        );
+        const structural = uniqueRefs(impacts.flatMap((impact) => impact.affected));
+        const joined = await joinMaterialized(
+          codeClient,
+          structural,
+          agentId,
+          Math.min(limit ?? 50, 50)
+        );
+        return ok({
+          target_uid: targetUid,
+          graph_context: graphContext,
+          impacts,
+          materialized: joined
+        });
+      }
+      default:
+        return err("unknown_action", `unknown mindgraph_code action: ${action}`);
+    }
+  } catch (cause) {
+    return err("code_tool_failed", errorDetail(cause));
+  }
+}
+async function attachCodeRefsToToolResult(client2, result, args, adapter) {
+  if (result.isError || !Array.isArray(args.code_refs) || args.code_refs.length === 0) {
+    return result;
+  }
+  const original = JSON.parse(result.content[0]?.text ?? "null");
+  const targetUids = primaryUids(original);
+  if (targetUids.length === 0) {
+    return ok({
+      result: original,
+      code_anchors: {
+        wrote: false,
+        caveat: "the write response exposed no primary UID to attach"
+      }
+    });
+  }
+  const anchorResult = await handleCodeTool(
+    client2,
+    {
+      action: "anchor",
+      code_refs: args.code_refs,
+      repo: args.repo,
+      repo_space_uid: args.repo_space_uid,
+      agent_id: args.agent_id
+    },
+    adapter
+  );
+  const anchors = JSON.parse(anchorResult.content[0]?.text ?? "null");
+  if (!anchorResult.isError) {
+    const codeClient = client2;
+    const anchorUids = (anchors.anchors ?? []).flatMap(
+      (anchor) => anchor.uid ? [anchor.uid] : []
+    );
+    for (const targetUid of targetUids) {
+      for (const anchorUid of anchorUids) {
+        await codeClient.entity({
+          action: "relate",
+          source_uid: targetUid,
+          target_uid: anchorUid,
+          edge_type: args.action === "lesson" ? "ABOUT" : "RELEVANT_TO",
+          agent_id: args.agent_id
+        });
+      }
+    }
+  }
+  return ok({ result: original, code_anchors: anchors });
+}
+async function anchorRepository(client2, repository, spaceUid, agentId) {
+  return client2.entity({
+    action: "create",
+    label: repository.repoId,
+    props: {
+      entity_type: "repository",
+      canonical_name: repository.repoId,
+      identifiers: { repo_id: repository.repoId }
+    },
+    identity: {
+      namespace: "external.code",
+      key_version: 1,
+      key: repositoryIdentityKey(repository)
+    },
+    identity_space_uid: spaceUid,
+    agent_id: agentId
+  });
+}
+async function anchorCodeRef(client2, ref, repositoryUid, spaceUid, agentId) {
+  const response = await client2.entity({
+    action: "create",
+    label: ref.qualifiedName,
+    props: {
+      entity_type: ref.kind === "file" ? "code_file" : "code_symbol",
+      canonical_name: ref.qualifiedName,
+      identifiers: {
+        repo_id: ref.repoId,
+        path: ref.path,
+        qualified_name: ref.qualifiedName
+      },
+      attributes: { code_ref: storedCodeRef(ref) }
+    },
+    identity: {
+      namespace: "external.code",
+      key_version: 1,
+      key: codeRefIdentityKey(ref)
+    },
+    identity_space_uid: spaceUid,
+    agent_id: agentId
+  });
+  if (response.uid) {
+    await client2.entity({
+      action: "relate",
+      source_uid: response.uid,
+      target_uid: repositoryUid,
+      edge_type: "PART_OF",
+      agent_id: agentId
+    });
+  }
+  return { ...response, ref };
+}
+async function resolveMaterializedUid(client2, ref, agentId) {
+  const response = await client2.entity({
+    action: "resolve_identity",
+    identity: {
+      namespace: "external.code",
+      key_version: 1,
+      key: codeRefIdentityKey(ref)
+    },
+    agent_id: agentId
+  });
+  return response.status === "existing" ? response.uid : void 0;
+}
+async function codeRefFromAnchor(client2, adapter, uid) {
+  const node = await client2.getNode(uid);
+  const attributes = node.props?.attributes;
+  if (!attributes || typeof attributes !== "object") return void 0;
+  const codeRef = attributes.code_ref;
+  if (!isStoredCodeRef(codeRef)) return void 0;
+  const repository = await adapter.resolveRepository(codeRef.repoId);
+  return { ...codeRef, repoRoot: repository.repoRoot };
+}
+async function resolveSingleTarget(client2, adapter, refs, anchorUids, options) {
+  if (refs.length > 1 || anchorUids.length > 1) {
+    return { error: err("ambiguous_target", "expand/affected accepts exactly one code target") };
+  }
+  if (anchorUids.length === 1) {
+    const ref = await codeRefFromAnchor(client2, adapter, anchorUids[0]);
+    return ref ? { ref } : { error: err("invalid_anchor", "anchor UID does not contain a typed code_ref") };
+  }
+  if (refs.length !== 1) {
+    return { error: err("missing_code_ref", "one code_ref or anchor_uid is required") };
+  }
+  const resolution = await adapter.resolveRefs(refs, options);
+  const result = resolution.results[0];
+  if (!result.resolved) {
+    return {
+      error: ok({
+        availability: resolution.availability,
+        result,
+        wrote: false
+      })
+    };
+  }
+  return { ref: result.resolved };
+}
+async function joinMaterialized(client2, refs, agentId, limit) {
+  const joined = [];
+  for (const ref of uniqueRefs(refs).slice(0, limit)) {
+    const uid = await resolveMaterializedUid(client2, ref, agentId);
+    if (!uid) continue;
+    joined.push({
+      ref,
+      anchor_uid: uid,
+      graph: await client2.traverse({
+        action: "neighborhood",
+        start_uid: uid,
+        depth: 2,
+        max_nodes: 20
+      })
+    });
+  }
+  return joined;
+}
+async function codeRefsFromGraphContext(client2, adapter, context) {
+  const uids = /* @__PURE__ */ new Set();
+  collectUids(context, uids);
+  if (uids.size === 0) return [];
+  const nodes = client2.getNodesBatch ? await client2.getNodesBatch([...uids]) : await Promise.all([...uids].map((uid) => client2.getNode(uid).catch(() => void 0)));
+  const stored = nodes.flatMap((node) => {
+    if (!node) return [];
+    const attributes = node.props?.attributes;
+    if (!attributes || typeof attributes !== "object") return [];
+    const codeRef = attributes.code_ref;
+    return isStoredCodeRef(codeRef) ? [codeRef] : [];
+  });
+  return Promise.all(
+    stored.map(async (ref) => {
+      const repository = await adapter.resolveRepository(ref.repoId);
+      return { ...ref, repoRoot: repository.repoRoot };
+    })
+  );
+}
+function collectUids(value, uids) {
+  if (Array.isArray(value)) {
+    value.forEach((item) => collectUids(item, uids));
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [key, child] of Object.entries(value)) {
+    if (typeof child === "string" && ["uid", "node_uid", "neighbor_uid", "from_uid", "to_uid"].includes(key)) {
+      uids.add(child);
+    } else {
+      collectUids(child, uids);
+    }
+  }
+}
+function isStoredCodeRef(value) {
+  if (!value || typeof value !== "object") return false;
+  const ref = value;
+  return typeof ref.repoId === "string" && typeof ref.path === "string" && typeof ref.language === "string" && typeof ref.kind === "string" && typeof ref.qualifiedName === "string" && (typeof ref.signature === "string" || ref.signature === null) && typeof ref.startLine === "number" && typeof ref.endLine === "number";
+}
+function storedCodeRef(ref) {
+  const { repoRoot: _localOnly, ...stored } = ref;
+  return stored;
+}
+function uniqueRefs(refs) {
+  const seen = /* @__PURE__ */ new Set();
+  return refs.filter((ref) => {
+    const key = `${ref.repoId}:${ref.path}:${ref.qualifiedName}:${ref.signature ?? ""}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+function primaryUids(value) {
+  if (!value || typeof value !== "object") return [];
+  const object2 = value;
+  const keys = [
+    "uid",
+    "claim_uid",
+    "goal_uid",
+    "project_uid",
+    "milestone_uid",
+    "decision_uid",
+    "task_uid",
+    "plan_uid",
+    "step_uid",
+    "execution_uid",
+    "lesson_uid"
+  ];
+  return [
+    ...new Set(
+      keys.flatMap((key) => typeof object2[key] === "string" ? [object2[key]] : [])
+    )
+  ];
+}
+var ok, err, CODE_TOOL;
+var init_code_tool = __esm({
+  "src/code-tool.ts"() {
+    "use strict";
+    init_error_detail();
+    init_codegraph();
+    ok = (data) => ({
+      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+    });
+    err = (code, message, details) => ({
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: message, code, details }, null, 2)
+        }
+      ],
+      isError: true
+    });
+    CODE_TOOL = {
+      name: "mindgraph_code",
+      description: "Resolve typed code references through the local codegraph index and join them to persistent MindGraph memory/work. anchor creates exact repository/code anchors; recall reads attached graph context; expand reads callers/callees; affected reads impact for a code ref or Task/Execution. Ambiguous refs return candidates without writing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: {
+            type: "string",
+            enum: ["anchor", "recall", "expand", "affected"]
+          },
+          code_refs: {
+            type: "array",
+            maxItems: 50,
+            items: {
+              oneOf: [
+                { type: "string" },
+                {
+                  type: "object",
+                  properties: {
+                    repo: { type: "string" },
+                    path: { type: "string" },
+                    line: { type: "integer", minimum: 1 },
+                    symbol: { type: "string" },
+                    kind: { type: "string" },
+                    language: { type: "string" },
+                    signature: { type: "string" }
+                  },
+                  additionalProperties: false
+                }
+              ]
+            }
+          },
+          anchor_uids: {
+            type: "array",
+            maxItems: 50,
+            items: { type: "string" },
+            description: "Already-materialized code anchor UIDs (codegraph is not required for recall)"
+          },
+          repo: {
+            type: "string",
+            description: "Configured repository id or repository root"
+          },
+          repo_space_uid: {
+            type: "string",
+            description: "Writable shared Project/repository Space for new anchors"
+          },
+          task_uid: { type: "string" },
+          execution_uid: { type: "string" },
+          limit: { type: "integer", minimum: 1, maximum: 50 },
+          agent_id: { type: "string" }
+        },
+        required: ["action"]
+      },
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      }
+    };
+  }
+});
+
+// src/sync-tool.ts
+function safePath(root, candidate) {
+  const absolute = import_node_path5.default.resolve(root, candidate);
+  const relative2 = import_node_path5.default.relative(root, absolute);
+  if (relative2.startsWith("..") || import_node_path5.default.isAbsolute(relative2)) {
+    throw new Error(`path escapes repository root: ${candidate}`);
+  }
+  return absolute;
+}
+function markdownFiles(target) {
+  if (!import_node_fs5.default.existsSync(target)) return [];
+  const stat = import_node_fs5.default.statSync(target);
+  if (stat.isFile()) return target.endsWith(".md") ? [target] : [];
+  if (!stat.isDirectory()) return [];
+  return import_node_fs5.default.readdirSync(target, { withFileTypes: true }).flatMap((entry) => markdownFiles(import_node_path5.default.join(target, entry.name)));
+}
+function fileDescriptor(root, absolute) {
+  const content = import_node_fs5.default.readFileSync(absolute, "utf8");
+  return {
+    logical_path: import_node_path5.default.relative(root, absolute).split(import_node_path5.default.sep).join("/"),
+    content_hash: import_node_crypto4.default.createHash("sha256").update(content).digest("hex"),
+    bytes: Buffer.byteLength(content),
+    content
+  };
+}
+async function handleSyncTool(client2, args) {
+  try {
+    const action = String(args.action || "");
+    const context = args.invocation_context || {};
+    const adapter = new CodegraphAdapter({
+      cwd: context.cwd || process.cwd()
+    });
+    const requestedRepo = typeof args.repo === "string" ? args.repo : typeof args.repo_id === "string" ? args.repo_id : context.repoId;
+    const repository = await adapter.resolveRepository(requestedRepo);
+    const root = repository.repoRoot;
+    const repoId = repository.repoId;
+    const provider = String(args.provider || "claude_project");
+    const remote = client2;
+    if (action === "scan") {
+      const repositories = args.workspace === true ? await adapter.resolveRepositories() : [repository];
+      const requested = Array.isArray(args.paths) && args.paths.length > 0 ? args.paths.map(String) : [".claude/agent-memory", "memory"];
+      const scans = [];
+      for (const selected of repositories) {
+        scans.push(
+          await scanRepository(
+            remote,
+            selected,
+            requested,
+            provider,
+            args.agent_id
+          )
+        );
+      }
+      if (args.workspace === true) {
+        return ok2({
+          provider,
+          workspace: true,
+          repositories: scans,
+          one_way: "files_to_graph"
+        });
+      }
+      return ok2(scans[0]);
+    }
+    const request = {
+      ...args,
+      provider,
+      repo_id: repoId
+    };
+    delete request.invocation_context;
+    delete request.paths;
+    delete request.repo;
+    delete request.workspace;
+    if (action === "begin" && !request.content) {
+      if (!request.logical_path) {
+        return err2("missing_field", "logical_path is required for begin");
+      }
+      const file = fileDescriptor(
+        root,
+        safePath(root, String(request.logical_path))
+      );
+      request.content = file.content;
+      request.content_hash ||= file.content_hash;
+    }
+    if (action === "status" && request.logical_path && request.file_present !== false) {
+      const absolute = safePath(root, String(request.logical_path));
+      request.file_present = import_node_fs5.default.existsSync(absolute);
+      if (request.file_present && !request.content_hash) {
+        request.content_hash = fileDescriptor(root, absolute).content_hash;
+      }
+    }
+    return ok2(await remote.memorySync(request));
+  } catch (error) {
+    return err2("sync_failed", errorDetail(error));
+  }
+}
+async function scanRepository(remote, repository, requested, provider, agentId) {
+  const files = [
+    ...new Set(
+      requested.flatMap(
+        (candidate) => markdownFiles(safePath(repository.repoRoot, candidate))
+      )
+    )
+  ].sort();
+  const results = [];
+  for (const absolute of files) {
+    const file = fileDescriptor(repository.repoRoot, absolute);
+    const status = await remote.memorySync({
+      action: "scan",
+      provider,
+      repo_id: repository.repoId,
+      logical_path: file.logical_path,
+      content_hash: file.content_hash,
+      file_present: true,
+      agent_id: agentId
+    });
+    results.push({
+      logical_path: file.logical_path,
+      content_hash: file.content_hash,
+      bytes: file.bytes,
+      status
+    });
+  }
+  return {
+    repo_id: repository.repoId,
+    root: ".",
+    files: results
+  };
+}
+var import_node_crypto4, import_node_fs5, import_node_path5, ok2, err2, SYNC_TOOL;
+var init_sync_tool = __esm({
+  "src/sync-tool.ts"() {
+    "use strict";
+    import_node_crypto4 = __toESM(require("crypto"));
+    import_node_fs5 = __toESM(require("fs"));
+    import_node_path5 = __toESM(require("path"));
+    init_codegraph();
+    init_error_detail();
+    ok2 = (data) => ({
+      content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
+    });
+    err2 = (code, message) => ({
+      content: [{ type: "text", text: JSON.stringify({ code, error: message }) }],
+      isError: true
+    });
+    SYNC_TOOL = {
+      name: "mindgraph_sync",
+      description: "Transactional one-way project memory-file sync. scan/status are reads; begin/record/finalize/abandon are writes. Discovery and hashing are automatic; semantic assertions are deliberately supplied through record. This never writes graph state back to files.",
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: true
+      },
+      inputSchema: {
+        type: "object",
+        properties: {
+          action: {
+            type: "string",
+            enum: ["scan", "begin", "record", "finalize", "status", "abandon"]
+          },
+          paths: { type: "array", items: { type: "string" } },
+          workspace: {
+            type: "boolean",
+            description: "For scan only: fan out across repositories explicitly listed in .mindgraph/workspace.json"
+          },
+          repo: {
+            type: "string",
+            description: "Configured repository id, name, or root"
+          },
+          logical_path: { type: "string" },
+          content: { type: "string" },
+          content_hash: { type: "string" },
+          source_uid: { type: "string" },
+          execution_uid: { type: "string" },
+          assertion_fingerprint: { type: "string" },
+          planned_fingerprints: { type: "array", items: { type: "string" } },
+          current_fingerprints: { type: "array", items: { type: "string" } },
+          source_selector: { type: "object" },
+          capture_type: {
+            type: "string",
+            enum: ["lesson", "journal", "claim", "decision", "risk"]
+          },
+          label: { type: "string" },
+          summary: { type: "string" },
+          props: { type: "object" },
+          expected_execution_version: { type: "integer", minimum: 1 },
+          baseline_version: { type: "integer", minimum: 1 },
+          repo_space_uid: { type: "string" },
+          repo_id: { type: "string" },
+          provider: { type: "string", enum: ["claude_project", "explicit"] },
+          file_present: { type: "boolean" },
+          agent_id: { type: "string" },
+          invocation_context: {
+            type: "object",
+            description: "Adapter-owned; hooks replace forged or absent values.",
+            properties: {
+              harness: { type: "string" },
+              harnessSessionId: { type: "string" },
+              harnessTurnId: { type: "string" },
+              cwd: { type: "string" },
+              repoId: { type: "string" },
+              branch: { type: "string" },
+              commit: { type: "string" },
+              worktreeState: { type: "string" },
+              model: { type: "string" },
+              injectedBy: { type: "string" }
+            }
+          }
+        },
+        required: ["action"]
+      }
+    };
+  }
+});
+
 // src/tools.ts
-function ok(data) {
+function toolsForProfile(profile = process.env.MINDGRAPH_PROFILE || "general") {
+  if (profile === "coding") return TOOLS;
+  return TOOLS.filter(
+    (tool) => tool.name !== "mindgraph_code" && tool.name !== "mindgraph_sync"
+  );
+}
+function ok3(data) {
   return {
     content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
   };
 }
-function err(message) {
+function err3(message) {
   return {
     content: [{ type: "text", text: JSON.stringify({ error: message }) }],
     isError: true
@@ -40,29 +1461,53 @@ function err(message) {
 }
 async function handleTool(client2, name, args) {
   try {
+    let result;
     switch (name) {
       case "mindgraph_capture":
-        return await handleCapture(client2, args);
+        result = await handleCapture(client2, args);
+        break;
       case "mindgraph_reason":
-        return await handleReason(client2, args);
+        result = await handleReason(client2, args);
+        break;
       case "mindgraph_commit":
-        return await handleCommit(client2, args);
+        result = await handleCommit(client2, args);
+        break;
       case "mindgraph_plan":
-        return await handlePlan(client2, args);
+        result = await handlePlan(client2, args);
+        break;
       case "mindgraph_retrieve":
-        return await handleRetrieve(client2, args);
+        result = await handleRetrieve(client2, args);
+        break;
       case "mindgraph_ingest":
-        return await handleIngest(client2, args);
+        result = await handleIngest(client2, args);
+        break;
       case "mindgraph_synthesize":
-        return await handleSynthesize(client2, args);
+        result = await handleSynthesize(client2, args);
+        break;
       case "mindgraph_ontology":
-        return await handleOntology(client2, args);
+        result = await handleOntology(client2, args);
+        break;
+      case "mindgraph_code":
+        result = await handleCodeTool(client2, args);
+        break;
+      case "mindgraph_sync":
+        result = await handleSyncTool(client2, args);
+        break;
       default:
-        return err(`Unknown tool: ${name}`);
+        result = err3(`Unknown tool: ${name}`);
     }
+    const action = typeof args.action === "string" ? args.action : "";
+    const attach = name === "mindgraph_capture" || name === "mindgraph_commit" && action !== "get_open_decisions" || name === "mindgraph_plan" && ![
+      "get_plan",
+      "get_executions",
+      "get_pending",
+      "get_assessments",
+      "resume_work",
+      "heartbeat"
+    ].includes(action);
+    return attach ? await attachCodeRefsToToolResult(client2, result, args) : result;
   } catch (e) {
-    const message = e instanceof Error ? e.message : String(e);
-    return err(message);
+    return err3(errorDetail(e));
   }
 }
 async function handleCapture(client2, args) {
@@ -71,6 +1516,12 @@ async function handleCapture(client2, args) {
     label,
     summary,
     content,
+    session_uid,
+    work_uid,
+    execution_uid,
+    idempotency_key,
+    supersedes_uid,
+    summarizes_uids,
     entity_type,
     source_uid,
     mood,
@@ -81,12 +1532,30 @@ async function handleCapture(client2, args) {
     agent_id
   } = args;
   switch (action) {
+    case "lesson":
+      return ok3(
+        await client2.distill({
+          label,
+          output_type: "lesson",
+          summary,
+          confidence,
+          salience,
+          session_uid,
+          work_uid,
+          execution_uid,
+          idempotency_key,
+          supersedes_uid,
+          summarizes_uids,
+          props,
+          agent_id
+        })
+      );
     case "journal": {
-      if (!content) return err("content is required for action=journal");
+      if (!content) return err3("content is required for action=journal");
       const journalProps = { content };
       if (mood) journalProps.mood = mood;
       if (tags) journalProps.tags = tags;
-      return ok(await client2.journal(label, journalProps, { agent_id }));
+      return ok3(await client2.journal(label, journalProps, { agent_id }));
     }
     case "entity": {
       const type = entity_type || "concept";
@@ -94,22 +1563,22 @@ async function handleCapture(client2, args) {
       if (summary) entityProps.description = summary;
       switch (type) {
         case "person":
-          return ok(await client2.findOrCreatePerson(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreatePerson(label, entityProps, agent_id));
         case "organization":
-          return ok(await client2.findOrCreateOrganization(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateOrganization(label, entityProps, agent_id));
         case "nation":
-          return ok(await client2.findOrCreateNation(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateNation(label, entityProps, agent_id));
         case "event":
-          return ok(await client2.findOrCreateEvent(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateEvent(label, entityProps, agent_id));
         case "place":
-          return ok(await client2.findOrCreatePlace(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreatePlace(label, entityProps, agent_id));
         case "concept":
         default:
-          return ok(await client2.findOrCreateConcept(label, entityProps, agent_id));
+          return ok3(await client2.findOrCreateConcept(label, entityProps, agent_id));
       }
     }
     case "observation":
-      return ok(
+      return ok3(
         await client2.capture({
           action: "observation",
           label,
@@ -121,7 +1590,7 @@ async function handleCapture(client2, args) {
         })
       );
     case "source":
-      return ok(
+      return ok3(
         await client2.capture({
           action: "source",
           label,
@@ -133,7 +1602,7 @@ async function handleCapture(client2, args) {
         })
       );
     case "snippet":
-      return ok(
+      return ok3(
         await client2.capture({
           action: "snippet",
           label,
@@ -146,7 +1615,7 @@ async function handleCapture(client2, args) {
         })
       );
     case "concept":
-      return ok(
+      return ok3(
         await client2.structure({
           action: "concept",
           label,
@@ -158,7 +1627,7 @@ async function handleCapture(client2, args) {
         })
       );
     default:
-      return err(`Unknown capture action: ${action}`);
+      return err3(`Unknown capture action: ${action}`);
   }
 }
 async function handleReason(client2, args) {
@@ -176,20 +1645,30 @@ async function handleReason(client2, args) {
     agent_id
   } = args;
   if (action === "claim") {
-    const claimObj = claim || (label ? { label, confidence } : null);
-    if (!claimObj) return err("claim object or label is required for action=claim");
-    return ok(
+    const claimObj = claim ? {
+      label: claim.label,
+      confidence: claim.confidence,
+      ...claim.content ? { props: { content: claim.content } } : {}
+    } : label ? { label, confidence } : null;
+    if (!claimObj) return err3("claim object or label is required for action=claim");
+    return ok3(
       await client2.argue({
         claim: claimObj,
-        evidence,
-        warrant,
+        evidence: evidence?.map((e) => ({
+          label: e.label,
+          ...e.description ? { props: { description: e.description } } : {}
+        })),
+        warrant: warrant ? {
+          label: warrant.label,
+          ...warrant.content ? { props: { content: warrant.content } } : {}
+        } : void 0,
         argument,
         agent_id
       })
     );
   }
-  if (!label) return err(`label is required for action=${action}`);
-  return ok(
+  if (!label) return err3(`label is required for action=${action}`);
+  return ok3(
     await client2.inquire({
       action,
       label,
@@ -222,8 +1701,8 @@ async function handleCommit(client2, args) {
     case "goal":
     case "project":
     case "milestone":
-      if (!label) return err(`label is required for action=${action}`);
-      return ok(
+      if (!label) return err3(`label is required for action=${action}`);
+      return ok3(
         await client2.commit({
           action,
           label,
@@ -236,15 +1715,15 @@ async function handleCommit(client2, args) {
         })
       );
     case "open_decision":
-      if (!label) return err("label is required for open_decision");
-      return ok(await client2.openDecision(label, { summary, props, agent_id }));
+      if (!label) return err3("label is required for open_decision");
+      return ok3(await client2.openDecision(label, { summary, props, agent_id }));
     case "add_option":
-      if (!decision_uid) return err("decision_uid is required for add_option");
-      if (!label) return err("label is required for add_option");
-      return ok(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
+      if (!decision_uid) return err3("decision_uid is required for add_option");
+      if (!label) return err3("label is required for add_option");
+      return ok3(await client2.addOption(decision_uid, label, { summary, props, agent_id }));
     case "add_constraint":
-      if (!decision_uid) return err("decision_uid is required for add_constraint");
-      return ok(
+      if (!decision_uid) return err3("decision_uid is required for add_constraint");
+      return ok3(
         await client2.deliberate({
           action: "add_constraint",
           label,
@@ -255,9 +1734,9 @@ async function handleCommit(client2, args) {
         })
       );
     case "resolve_decision":
-      if (!decision_uid) return err("decision_uid is required for resolve_decision");
-      if (!chosen_option_uid) return err("chosen_option_uid is required for resolve_decision");
-      return ok(
+      if (!decision_uid) return err3("decision_uid is required for resolve_decision");
+      if (!chosen_option_uid) return err3("chosen_option_uid is required for resolve_decision");
+      return ok3(
         await client2.resolveDecision(decision_uid, chosen_option_uid, {
           summary,
           props,
@@ -269,9 +1748,9 @@ async function handleCommit(client2, args) {
         })
       );
     case "get_open_decisions":
-      return ok(await client2.getOpenDecisions());
+      return ok3(await client2.getOpenDecisions());
     default:
-      return err(`Unknown commit action: ${action}`);
+      return err3(`Unknown commit action: ${action}`);
   }
 }
 async function handlePlan(client2, args) {
@@ -281,8 +1760,41 @@ async function handlePlan(client2, args) {
     summary,
     plan_uid,
     task_uid,
+    step_uid,
+    session_uid,
+    goal_uid,
     target_uid,
+    execution_uid,
+    executor_uid,
+    affordance_uid,
+    produces_node_uid,
+    filter_plan_uid,
+    depends_on_uids,
+    related_uids,
     status,
+    task_status,
+    step_status,
+    execution_status,
+    expected_version,
+    lease_epoch,
+    lease_ttl_secs,
+    idempotency_key,
+    allow_takeover,
+    release_lease,
+    override_reason,
+    scope_uids,
+    limit,
+    confidence,
+    salience,
+    input_snapshot,
+    output_snapshot,
+    side_effects,
+    outcome,
+    error,
+    next_action,
+    checkpoint_summary,
+    test_summary,
+    produces_node_uids,
     props,
     agent_id
   } = args;
@@ -293,25 +1805,120 @@ async function handlePlan(client2, args) {
     case "add_step":
     case "update_status":
     case "get_plan":
-      return ok(
+    case "resume_work":
+    case "claim_task":
+    case "heartbeat":
+    case "start_iteration":
+    case "checkpoint_iteration":
+    case "block_task":
+    case "complete_task":
+    case "abandon_iteration":
+      return ok3(
         await client2.plan({
           action,
           label,
           summary,
+          confidence,
+          salience,
+          goal_uid,
           plan_uid,
           task_uid,
+          step_uid,
+          session_uid,
+          target_uid,
+          depends_on_uids,
+          related_uids,
           status,
+          task_status,
+          step_status,
+          execution_status,
+          execution_uid,
+          expected_version,
+          lease_epoch,
+          lease_ttl_secs,
+          idempotency_key,
+          allow_takeover,
+          release_lease,
+          override_reason,
+          scope_uids,
+          limit,
+          input_snapshot,
+          output_snapshot,
+          side_effects,
+          outcome,
+          error,
+          next_action,
+          checkpoint_summary,
+          test_summary,
+          produces_node_uids,
           props,
           agent_id
         })
       );
     // Execution tracking
     case "start_execution":
-      return ok(await client2.execution({ action: "start", task_uid, agent_id }));
+      return ok3(
+        await client2.execution({
+          action: "start",
+          label,
+          summary,
+          confidence,
+          salience,
+          plan_uid,
+          executor_uid,
+          affordance_uid,
+          related_uids,
+          input_snapshot,
+          props,
+          agent_id
+        })
+      );
     case "complete_execution":
-      return ok(await client2.execution({ action: "complete", task_uid, agent_id }));
+      return ok3(
+        await client2.execution({
+          action: "complete",
+          execution_uid,
+          produces_node_uid,
+          output_snapshot,
+          side_effects,
+          outcome,
+          props,
+          agent_id
+        })
+      );
     case "fail_execution":
-      return ok(await client2.execution({ action: "fail", task_uid, agent_id }));
+      return ok3(
+        await client2.execution({
+          action: "fail",
+          execution_uid,
+          output_snapshot,
+          side_effects,
+          outcome,
+          error,
+          props,
+          agent_id
+        })
+      );
+    case "register_agent":
+      return ok3(
+        await client2.execution({
+          action: "register_agent",
+          label,
+          summary,
+          confidence,
+          salience,
+          props,
+          agent_id
+        })
+      );
+    case "get_executions":
+      return ok3(
+        await client2.execution({
+          action: "get_executions",
+          filter_plan_uid,
+          agent_id
+        })
+      );
     // Governance — read-only from MCP by design (C33). The write actions were
     // removed rather than repaired: `resolve_approval` here also sent
     // `task_uid` where the server requires `approval_uid`, and never sent
@@ -319,12 +1926,12 @@ async function handlePlan(client2, args) {
     // DENIED every approval an agent tried to resolve. Wiring that correctly
     // would have meant building a working self-approval path — the hole itself.
     case "get_pending":
-      return ok(await client2.governance({ action: "get_pending", agent_id }));
+      return ok3(await client2.governance({ action: "get_pending", agent_id }));
     // Procedures (merged from mindgraph_action)
     case "create_flow":
     case "add_affordance":
     case "add_control":
-      return ok(
+      return ok3(
         await client2.procedure({
           action,
           label,
@@ -335,7 +1942,7 @@ async function handlePlan(client2, args) {
         })
       );
     case "add_procedure_step":
-      return ok(
+      return ok3(
         await client2.procedure({
           action: "add_step",
           label,
@@ -347,7 +1954,7 @@ async function handlePlan(client2, args) {
       );
     // Risk assessment (merged from mindgraph_action)
     case "assess_risk":
-      return ok(
+      return ok3(
         await client2.risk({
           action: "assess",
           label,
@@ -358,7 +1965,7 @@ async function handlePlan(client2, args) {
         })
       );
     case "get_assessments":
-      return ok(
+      return ok3(
         await client2.risk({
           action: "get_assessments",
           target_uid,
@@ -366,7 +1973,7 @@ async function handlePlan(client2, args) {
         })
       );
     default:
-      return err(`Unknown plan action: ${action}`);
+      return err3(`Unknown plan action: ${action}`);
   }
 }
 async function handleRetrieve(client2, args) {
@@ -395,8 +2002,8 @@ async function handleRetrieve(client2, args) {
   } = args;
   switch (action) {
     case "context":
-      if (!query) return err("query is required for context retrieval");
-      return ok(
+      if (!query) return err3("query is required for context retrieval");
+      return ok3(
         await client2.retrieveContext({
           query,
           node_limit: limit,
@@ -409,8 +2016,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "text":
-      if (!query) return err("query is required for text search");
-      return ok(
+      if (!query) return err3("query is required for text search");
+      return ok3(
         await client2.retrieve({
           action: "text",
           query,
@@ -421,8 +2028,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "semantic":
-      if (!query) return err("query is required for semantic search");
-      return ok(
+      if (!query) return err3("query is required for semantic search");
+      return ok3(
         await client2.retrieve({
           action: "semantic",
           query,
@@ -433,8 +2040,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "hybrid":
-      if (!query) return err("query is required for hybrid search");
-      return ok(
+      if (!query) return err3("query is required for hybrid search");
+      return ok3(
         await client2.retrieve({
           action: "hybrid",
           query,
@@ -446,17 +2053,17 @@ async function handleRetrieve(client2, args) {
       );
     // Structured queries
     case "active_goals":
-      return ok(await client2.getGoals());
+      return ok3(await client2.getGoals());
     case "open_questions":
-      return ok(await client2.getOpenQuestions());
+      return ok3(await client2.getOpenQuestions());
     case "weak_claims":
-      return ok(await client2.getWeakClaims());
+      return ok3(await client2.getWeakClaims());
     case "pending_approvals":
-      return ok(await client2.getPendingApprovals());
+      return ok3(await client2.getPendingApprovals());
     case "unresolved_contradictions":
-      return ok(await client2.getContradictions());
+      return ok3(await client2.getContradictions());
     case "stale_derivations":
-      return ok(
+      return ok3(
         await client2.retrieve({
           action: "stale_derivations",
           limit,
@@ -464,7 +2071,7 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "preferences":
-      return ok(
+      return ok3(
         await client2.retrieve({
           action: "preferences",
           ...query ? { query, k: limit } : {},
@@ -473,8 +2080,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "layer":
-      if (!layer) return err("layer is required for layer retrieval");
-      return ok(
+      if (!layer) return err3("layer is required for layer retrieval");
+      return ok3(
         await client2.retrieve({
           action: "layer",
           layer,
@@ -483,7 +2090,7 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "recent":
-      return ok(
+      return ok3(
         await client2.retrieve({
           action: "recent",
           limit,
@@ -495,7 +2102,7 @@ async function handleRetrieve(client2, args) {
       );
     // Document inventory
     case "document_index":
-      return ok(
+      return ok3(
         await client2.getNodes({
           node_type: "Document",
           limit: limit ?? 100
@@ -503,8 +2110,8 @@ async function handleRetrieve(client2, args) {
       );
     // Graph traversal
     case "chain":
-      if (!start_uid) return err("start_uid is required for chain traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for chain traversal");
+      return ok3(
         await client2.traverse({
           action: "chain",
           start_uid,
@@ -515,8 +2122,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "neighborhood":
-      if (!start_uid) return err("start_uid is required for neighborhood traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for neighborhood traversal");
+      return ok3(
         await client2.traverse({
           action: "neighborhood",
           start_uid,
@@ -529,9 +2136,9 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "path":
-      if (!start_uid) return err("start_uid is required for path traversal");
-      if (!end_uid) return err("end_uid is required for path traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for path traversal");
+      if (!end_uid) return err3("end_uid is required for path traversal");
+      return ok3(
         await client2.traverse({
           action: "path",
           start_uid,
@@ -545,8 +2152,8 @@ async function handleRetrieve(client2, args) {
         })
       );
     case "subgraph":
-      if (!start_uid) return err("start_uid is required for subgraph traversal");
-      return ok(
+      if (!start_uid) return err3("start_uid is required for subgraph traversal");
+      return ok3(
         await client2.traverse({
           action: "subgraph",
           start_uid,
@@ -559,7 +2166,7 @@ async function handleRetrieve(client2, args) {
         })
       );
     default:
-      return err(`Unknown retrieve action: ${action}`);
+      return err3(`Unknown retrieve action: ${action}`);
   }
 }
 async function handleIngest(client2, args) {
@@ -588,7 +2195,7 @@ async function handleIngest(client2, args) {
   const targetsOntology = Array.isArray(layers) && layers.includes("ontology");
   const cognitiveLayers = targetsOntology ? layers.filter((layer) => layer !== "ontology") : layers;
   if (targetsOntology && !ontology_schema_id) {
-    return err(
+    return err3(
       "layers included 'ontology' but no ontology_schema_id was supplied. Typed Layer-7 extraction is driven by ontology_schema_id, not by the layers list \u2014 pass the schema id, or drop 'ontology' from layers."
     );
   }
@@ -596,8 +2203,8 @@ async function handleIngest(client2, args) {
   const ontologyOnly = targetsOntology && forwardedLayers === void 0;
   switch (action) {
     case "chunk":
-      if (!content) return err("content is required for chunk ingestion");
-      return ok(
+      if (!content) return err3("content is required for chunk ingestion");
+      return ok3(
         await client2.ingestChunk({
           content,
           label: title,
@@ -611,8 +2218,8 @@ async function handleIngest(client2, args) {
         })
       );
     case "document":
-      if (!content) return err("content is required for document ingestion");
-      return ok(
+      if (!content) return err3("content is required for document ingestion");
+      return ok3(
         await client2.ingestDocument({
           content,
           title,
@@ -631,8 +2238,8 @@ async function handleIngest(client2, args) {
         })
       );
     case "session":
-      if (!content) return err("content is required for session ingestion");
-      return ok(
+      if (!content) return err3("content is required for session ingestion");
+      return ok3(
         await client2.ingestSession({
           content,
           title,
@@ -649,11 +2256,11 @@ async function handleIngest(client2, args) {
       );
     case "job_status":
       if (job_id) {
-        return ok(await client2.getJob(job_id));
+        return ok3(await client2.getJob(job_id));
       }
-      return ok(await client2.listJobs());
+      return ok3(await client2.listJobs());
     default:
-      return err(`Unknown ingest action: ${action}`);
+      return err3(`Unknown ingest action: ${action}`);
   }
 }
 async function handleSynthesize(client2, args) {
@@ -661,19 +2268,19 @@ async function handleSynthesize(client2, args) {
   switch (action) {
     case "signals":
       if (!project_uid)
-        return err("project_uid is required for action='signals'");
-      return ok(
+        return err3("project_uid is required for action='signals'");
+      return ok3(
         await client2.signals(project_uid, { signals, target_types })
       );
     case "run":
       if (!project_uid)
-        return err("project_uid is required for action='run'");
-      return ok(await client2.runSynthesis(project_uid));
+        return err3("project_uid is required for action='run'");
+      return ok3(await client2.runSynthesis(project_uid));
     case "job_status":
-      if (!job_id) return err("job_id is required for action='job_status'");
-      return ok(await client2.getJob(job_id));
+      if (!job_id) return err3("job_id is required for action='job_status'");
+      return ok3(await client2.getJob(job_id));
     default:
-      return err(`Unknown synthesize action: ${action}`);
+      return err3(`Unknown synthesize action: ${action}`);
   }
 }
 async function handleOntology(client2, args) {
@@ -701,18 +2308,18 @@ async function handleOntology(client2, args) {
   } = args;
   switch (action) {
     case "schemas":
-      return ok(await client2.listOntologySchemas());
+      return ok3(await client2.listOntologySchemas());
     case "schema":
-      if (!schema_id) return err("schema_id is required for action='schema'");
-      return ok(await client2.getOntologySchema(schema_id));
+      if (!schema_id) return err3("schema_id is required for action='schema'");
+      return ok3(await client2.getOntologySchema(schema_id));
     case "query": {
-      if (!query) return err("query is required for action='query'");
+      if (!query) return err3("query is required for action='query'");
       if (!schema_id) {
-        return err(
+        return err3(
           "schema_id is required for action='query' (use action='schemas' to find the active schema)"
         );
       }
-      return ok(
+      return ok3(
         await client2.queryOntology({
           query,
           schema_id,
@@ -725,8 +2332,8 @@ async function handleOntology(client2, args) {
       );
     }
     case "search":
-      if (!query) return err("query is required for action='search'");
-      return ok(
+      if (!query) return err3("query is required for action='search'");
+      return ok3(
         await client2.searchDomainObjects(query, {
           schema_id,
           object_types,
@@ -734,18 +2341,18 @@ async function handleOntology(client2, args) {
         })
       );
     case "objects":
-      if (!schema_id) return err("schema_id is required for action='objects'");
-      return ok(
+      if (!schema_id) return err3("schema_id is required for action='objects'");
+      return ok3(
         await client2.listDomainObjects({ schema_id, object_type, limit })
       );
     case "object":
-      if (!uid) return err("uid is required for action='object'");
-      return ok(await client2.getDomainObject(uid));
+      if (!uid) return err3("uid is required for action='object'");
+      return ok3(await client2.getDomainObject(uid));
     case "object_context":
-      if (!uid) return err("uid is required for action='object_context'");
-      return ok(await client2.getDomainObjectContext(uid, depth));
+      if (!uid) return err3("uid is required for action='object_context'");
+      return ok3(await client2.getDomainObjectContext(uid, depth));
     case "proposals":
-      return ok(
+      return ok3(
         await client2.listOntologyProposals({
           status: status ?? "pending",
           schema_id,
@@ -754,21 +2361,21 @@ async function handleOntology(client2, args) {
         })
       );
     case "proposal":
-      if (!proposal_id) return err("proposal_id is required for action='proposal'");
-      return ok(await client2.getOntologyProposal(proposal_id));
+      if (!proposal_id) return err3("proposal_id is required for action='proposal'");
+      return ok3(await client2.getOntologyProposal(proposal_id));
     case "approve":
-      if (!proposal_id) return err("proposal_id is required for action='approve'");
-      return ok(await client2.approveOntologyProposal(proposal_id, { feedback }));
+      if (!proposal_id) return err3("proposal_id is required for action='approve'");
+      return ok3(await client2.approveOntologyProposal(proposal_id, { feedback }));
     case "reject":
-      if (!proposal_id) return err("proposal_id is required for action='reject'");
-      return ok(await client2.rejectOntologyProposal(proposal_id, reason));
+      if (!proposal_id) return err3("proposal_id is required for action='reject'");
+      return ok3(await client2.rejectOntologyProposal(proposal_id, reason));
     case "link": {
       if (!from_uid || !to_uid || !relation_type) {
-        return err(
+        return err3(
           "from_uid, to_uid, and relation_type are required for action='link'"
         );
       }
-      return ok(
+      return ok3(
         await client2.linkDomainObjects({
           from_uid,
           to_uid,
@@ -779,11 +2386,11 @@ async function handleOntology(client2, args) {
       );
     }
     case "extract": {
-      if (!schema_id) return err("schema_id is required for action='extract'");
+      if (!schema_id) return err3("schema_id is required for action='extract'");
       if (!source_uids?.length) {
-        return err("source_uids is required for action='extract'");
+        return err3("source_uids is required for action='extract'");
       }
-      return ok(
+      return ok3(
         await client2.extractOntology({
           ontology_schema_id: schema_id,
           source_uids
@@ -791,23 +2398,34 @@ async function handleOntology(client2, args) {
       );
     }
     default:
-      return err(`Unknown ontology action: ${action}`);
+      return err3(`Unknown ontology action: ${action}`);
   }
 }
-var TOOLS;
+var TOOLS, INVOCATION_CONTEXT_SCHEMA;
 var init_tools = __esm({
   "src/tools.ts"() {
     "use strict";
+    init_error_detail();
+    init_code_tool();
+    init_sync_tool();
     TOOLS = [
       {
         name: "mindgraph_capture",
-        description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, 'concept' for abstract ideas. Use 'journal' for quick personal notes, preferences, reflections, moods \u2014 anything subjective or informal. Prefer 'entity'/'observation' for objective facts, 'journal' for personal notes.",
+        description: "Capture knowledge into the graph. Use 'entity' for people/orgs/places/events/nations/concepts (auto-deduplicates \u2014 safe to call even if already exists), 'observation' for factual statements, 'source' for documents/URLs, 'snippet' for quotes from a source, and 'concept' for abstract ideas. Use 'journal' for quick personal notes and 'lesson' for a durable learning attributable to a session or source nodes. Prefer 'entity'/'observation' for objective facts, 'journal' for informal notes, and 'lesson' only for reusable knowledge.",
         inputSchema: {
           type: "object",
           properties: {
             action: {
               type: "string",
-              enum: ["entity", "observation", "source", "snippet", "concept", "journal"],
+              enum: [
+                "entity",
+                "observation",
+                "source",
+                "snippet",
+                "concept",
+                "journal",
+                "lesson"
+              ],
               description: "Type of knowledge to capture"
             },
             label: {
@@ -822,6 +2440,31 @@ var init_tools = __esm({
               type: "string",
               description: "Journal content/body text (for action=journal)"
             },
+            session_uid: {
+              type: "string",
+              description: "Session UID that produced a lesson (for action=lesson)"
+            },
+            work_uid: {
+              type: "string",
+              description: "Durable Task/work UID this capture is relevant to"
+            },
+            execution_uid: {
+              type: "string",
+              description: "Material Execution that produced the lesson"
+            },
+            idempotency_key: {
+              type: "string",
+              description: "Stable retry key for an intentional capture"
+            },
+            supersedes_uid: {
+              type: "string",
+              description: "Earlier capture corrected or superseded by this one"
+            },
+            summarizes_uids: {
+              type: "array",
+              items: { type: "string" },
+              description: "Source node UIDs the lesson was learned from (for action=lesson)"
+            },
             entity_type: {
               type: "string",
               enum: ["person", "organization", "place", "event", "nation", "concept"],
@@ -856,6 +2499,32 @@ var init_tools = __esm({
               type: "object",
               description: "Type-specific properties (e.g. birth_date for person, coordinates for place)"
             },
+            code_refs: {
+              type: "array",
+              items: {
+                oneOf: [
+                  { type: "string" },
+                  {
+                    type: "object",
+                    properties: {
+                      repo: { type: "string" },
+                      path: { type: "string" },
+                      line: { type: "integer", minimum: 1 },
+                      symbol: { type: "string" },
+                      kind: { type: "string" },
+                      language: { type: "string" },
+                      signature: { type: "string" }
+                    }
+                  }
+                ]
+              },
+              description: "Typed code targets to anchor and attach to the captured node"
+            },
+            repo: { type: "string", description: "Configured repository id or root" },
+            repo_space_uid: {
+              type: "string",
+              description: "Writable shared repository/Project Space for new code anchors"
+            },
             agent_id: {
               type: "string",
               description: "Agent identity"
@@ -1029,6 +2698,16 @@ var init_tools = __esm({
               type: "object",
               description: "Type-specific properties (e.g. status, priority, deadline, horizon for goals)"
             },
+            code_refs: {
+              type: "array",
+              items: { oneOf: [{ type: "string" }, { type: "object" }] },
+              description: "Typed code targets to anchor and attach to the created commitment"
+            },
+            repo: { type: "string", description: "Configured repository id or root" },
+            repo_space_uid: {
+              type: "string",
+              description: "Writable shared repository/Project Space for new code anchors"
+            },
             agent_id: {
               type: "string",
               description: "Agent identity"
@@ -1039,7 +2718,7 @@ var init_tools = __esm({
       },
       {
         name: "mindgraph_plan",
-        description: "Agent-level task management, governance, and procedural knowledge. Use 'create_plan'/'create_task'/'add_step' for task breakdowns, 'update_status' for progress, 'get_plan' to review. Use 'create_flow'/'add_procedure_step'/'add_affordance'/'add_control' for workflows and procedures. Use 'assess_risk'/'get_assessments' for risk analysis. Use 'get_pending' to read the governance approval queue \u2014 approvals are granted by a person in the MindGraph dashboard, never from here, so wait for one rather than trying to clear it. Prefer mindgraph_commit for user goals/projects; use this for agent-managed execution.",
+        description: "Authoritative durable engineering work and execution evidence. Use create_task/create_plan/add_step for work that must survive sessions; resume_work for the deterministic bounded brief; claim_task + heartbeat for the fenced lease; and start_iteration/checkpoint_iteration/block_task/complete_task/abandon_iteration for idempotent material attempts. Every composite write needs task version, Session, lease epoch, and an idempotency key. Use the harness-native todo list only for local coordination; never maintain the same authoritative Task in both systems.",
         inputSchema: {
           type: "object",
           properties: {
@@ -1051,9 +2730,19 @@ var init_tools = __esm({
                 "add_step",
                 "update_status",
                 "get_plan",
+                "resume_work",
+                "claim_task",
+                "heartbeat",
+                "start_iteration",
+                "checkpoint_iteration",
+                "block_task",
+                "complete_task",
+                "abandon_iteration",
                 "start_execution",
                 "complete_execution",
                 "fail_execution",
+                "register_agent",
+                "get_executions",
                 // C33: governance WRITES are deliberately not exposed here.
                 // `create_policy` let a model author the rules it is judged by;
                 // `request_approval` + `resolve_approval` let it raise and then
@@ -1081,30 +2770,189 @@ var init_tools = __esm({
             },
             plan_uid: {
               type: "string",
-              description: "Plan UID (for add_step, get_plan)"
+              description: "Plan UID (for create_plan execution link, add_step, get_plan)"
             },
             task_uid: {
               type: "string",
-              description: "Task/step UID (for update_status, execution actions)"
+              description: "Task UID (for create_plan and graph-managed work actions)"
+            },
+            step_uid: {
+              type: "string",
+              description: "PlanStep UID for an iteration/checkpoint"
+            },
+            session_uid: {
+              type: "string",
+              description: "Durable Session UID that owns the task lease"
+            },
+            goal_uid: {
+              type: "string",
+              description: "Goal UID targeted by a task or plan"
             },
             target_uid: {
               type: "string",
-              description: "Parent flow/step UID or target node (for procedure/risk actions)"
+              description: "Task/plan/step UID for update_status, or parent/target node for procedure and risk actions"
+            },
+            execution_uid: {
+              type: "string",
+              description: "Execution UID (required for complete_execution/fail_execution)"
+            },
+            executor_uid: {
+              type: "string",
+              description: "Agent node UID that executed the work"
+            },
+            affordance_uid: {
+              type: "string",
+              description: "Affordance invoked by start_execution"
+            },
+            produces_node_uid: {
+              type: "string",
+              description: "Node produced by a completed execution"
+            },
+            filter_plan_uid: {
+              type: "string",
+              description: "Restrict get_executions to one plan"
+            },
+            depends_on_uids: {
+              type: "array",
+              items: { type: "string" },
+              description: "Plan-step UIDs that an added step depends on"
+            },
+            related_uids: {
+              type: "array",
+              items: { type: "string" },
+              description: "Target node UIDs to link to created work or an execution"
             },
             status: {
               type: "string",
               description: "New status value (for update_status)"
             },
+            task_status: {
+              type: "string",
+              description: "Task status requested by a checkpoint or abandon action"
+            },
+            step_status: {
+              type: "string",
+              description: "PlanStep status requested by a checkpoint"
+            },
+            execution_status: {
+              type: "string",
+              enum: ["completed", "failed", "abandoned"],
+              description: "Terminal Execution status for checkpoint_iteration"
+            },
+            expected_version: {
+              type: "number",
+              description: "Current Task node version used as the optimistic fence"
+            },
+            lease_epoch: {
+              type: "number",
+              description: "Current monotonic task-lease epoch"
+            },
+            lease_ttl_secs: {
+              type: "number",
+              minimum: 1,
+              description: "Requested server-time lease lifetime (default 300s)"
+            },
+            idempotency_key: {
+              type: "string",
+              description: "Caller-stable key required for every composite work mutation"
+            },
+            allow_takeover: {
+              type: "boolean",
+              description: "Governed claim override for a live lease owned by another agent"
+            },
+            release_lease: {
+              type: "boolean",
+              description: "Explicitly release or retain the lease after block/abandon/checkpoint"
+            },
+            override_reason: {
+              type: "string",
+              description: "Explicit completion reason when no terminal Execution evidence exists"
+            },
+            scope_uids: {
+              type: "array",
+              items: { type: "string" },
+              description: "Ordinary target UIDs that bound deterministic resume selection"
+            },
+            limit: {
+              type: "number",
+              minimum: 1,
+              maximum: 1,
+              description: "Resume returns one authoritative Task"
+            },
+            input_snapshot: {
+              type: "object",
+              description: "Structured inputs captured when an execution starts"
+            },
+            output_snapshot: {
+              type: "object",
+              description: "Structured outputs captured when an execution completes or fails"
+            },
+            outcome: {
+              type: "string",
+              description: "Execution outcome"
+            },
+            error: {
+              type: "string",
+              description: "Execution error detail (for fail_execution)"
+            },
+            side_effects: {
+              type: "array",
+              items: { type: "string" },
+              description: "Observable side effects of the execution"
+            },
+            next_action: {
+              type: "string",
+              description: "Recommended next action retained on terminal Execution evidence"
+            },
+            checkpoint_summary: {
+              type: "string",
+              description: "Bounded material-attempt checkpoint summary"
+            },
+            test_summary: {
+              type: "string",
+              description: "Test commands/results retained on the Execution"
+            },
+            produces_node_uids: {
+              type: "array",
+              items: { type: "string" },
+              description: "Nodes produced by checkpoint_iteration"
+            },
+            confidence: {
+              type: "number",
+              minimum: 0,
+              maximum: 1
+            },
+            salience: {
+              type: "number",
+              minimum: 0,
+              maximum: 1
+            },
             props: {
               type: "object",
               description: "Additional properties (e.g. likelihood, impact, mitigation for risks)"
             },
+            code_refs: {
+              type: "array",
+              items: { oneOf: [{ type: "string" }, { type: "object" }] },
+              description: "Typed code targets to anchor and attach to created work or execution"
+            },
+            repo: { type: "string", description: "Configured repository id or root" },
+            repo_space_uid: {
+              type: "string",
+              description: "Writable shared repository/Project Space for new code anchors"
+            },
             agent_id: {
               type: "string",
               description: "Agent identity"
             }
           },
           required: ["action"]
+        },
+        annotations: {
+          readOnlyHint: false,
+          destructiveHint: false,
+          idempotentHint: false,
+          openWorldHint: true
         }
       },
       {
@@ -1479,8 +3327,33 @@ var init_tools = __esm({
           },
           required: ["action"]
         }
-      }
+      },
+      SYNC_TOOL,
+      CODE_TOOL
     ];
+    INVOCATION_CONTEXT_SCHEMA = {
+      type: "object",
+      description: "Adapter-owned invocation context. Models should omit it; compatible hooks replace forged or absent values. cwd is consumed locally and never sent to the API.",
+      properties: {
+        harness: { type: "string", enum: ["claude-code", "codex", "generic"] },
+        harnessSessionId: { type: "string" },
+        harnessTurnId: { type: "string" },
+        cwd: { type: "string" },
+        repoId: { type: "string" },
+        branch: { type: "string" },
+        commit: { type: "string" },
+        worktreeState: { type: "string", enum: ["clean", "dirty"] },
+        model: { type: "string" },
+        injectedBy: { type: "string", enum: ["hook", "mcp-process", "caller"] }
+      }
+    };
+    for (const tool of TOOLS) {
+      if (tool.name === "mindgraph_retrieve") continue;
+      const schema = tool.inputSchema;
+      if (schema.properties && !schema.properties.invocation_context) {
+        schema.properties.invocation_context = INVOCATION_CONTEXT_SCHEMA;
+      }
+    }
   }
 });
 
@@ -1530,10 +3403,10 @@ async function handleGeneratedTool(client2, desc, args) {
     switch (desc.maps_to) {
       case "search": {
         const query = args.query;
-        if (!query) return err2(`query is required for ${desc.name}`);
+        if (!query) return err4(`query is required for ${desc.name}`);
         const limit = typeof args.limit === "number" ? args.limit : void 0;
         const filters = Array.isArray(args.filters) ? args.filters : void 0;
-        return ok2(
+        return ok4(
           await ontologyClient.searchDomainObjects(query, {
             schema_id: desc.schema_id,
             object_types: [desc.object_type],
@@ -1544,33 +3417,33 @@ async function handleGeneratedTool(client2, desc, args) {
       }
       case "object": {
         const uid = args.uid;
-        if (!uid) return err2(`uid is required for ${desc.name}`);
-        return ok2(await ontologyClient.getDomainObject(uid, {
+        if (!uid) return err4(`uid is required for ${desc.name}`);
+        return ok4(await ontologyClient.getDomainObject(uid, {
           schema_id: desc.schema_id,
           object_type: desc.object_type
         }));
       }
       case "object_context": {
         const uid = args.uid;
-        if (!uid) return err2(`uid is required for ${desc.name}`);
+        if (!uid) return err4(`uid is required for ${desc.name}`);
         const depth = typeof args.depth === "number" ? args.depth : void 0;
-        return ok2(await ontologyClient.getDomainObjectContext(uid, depth, {
+        return ok4(await ontologyClient.getDomainObjectContext(uid, depth, {
           schema_id: desc.schema_id,
           object_type: desc.object_type
         }));
       }
       case "related": {
         const uid = args.uid;
-        if (!uid) return err2(`uid is required for ${desc.name}`);
+        if (!uid) return err4(`uid is required for ${desc.name}`);
         if (!desc.relation || !desc.entry_role || !desc.far_type) {
-          return err2(`invalid related descriptor: ${desc.name}`);
+          return err4(`invalid related descriptor: ${desc.name}`);
         }
         if (!ontologyClient.queryRelatedDomainObjects) {
-          return err2(
+          return err4(
             "related ontology tools require a graph-aware version of the mindgraph SDK"
           );
         }
-        return ok2(await ontologyClient.queryRelatedDomainObjects({
+        return ok4(await ontologyClient.queryRelatedDomainObjects({
           schema_id: desc.schema_id,
           entry_type: desc.object_type,
           uid,
@@ -1585,9 +3458,9 @@ async function handleGeneratedTool(client2, desc, args) {
       }
       case "structured_query": {
         const select = args.select;
-        if (!select) return err2(`select is required for ${desc.name}`);
+        if (!select) return err4(`select is required for ${desc.name}`);
         if (!ontologyClient.queryDomainStructured) {
-          return err2(
+          return err4(
             "structured ontology tools require a graph-aware version of the mindgraph SDK"
           );
         }
@@ -1598,23 +3471,23 @@ async function handleGeneratedTool(client2, desc, args) {
         for (const field of STRUCTURED_QUERY_PASSTHROUGH) {
           if (args[field] !== void 0) request[field] = args[field];
         }
-        return ok2(await ontologyClient.queryDomainStructured(request));
+        return ok4(await ontologyClient.queryDomainStructured(request));
       }
       default:
-        return err2(`unknown generated tool mapping: ${desc.maps_to}`);
+        return err4(`unknown generated tool mapping: ${desc.maps_to}`);
     }
   } catch (e) {
-    return err2(e instanceof Error ? e.message : String(e));
+    return err4(e instanceof Error ? e.message : String(e));
   }
 }
-var ok2, err2, CACHE_TTL_MS, FAILURE_COOLDOWN_MS, cache, retryNotBefore, EMPTY, DuplicateGeneratedToolError, STRUCTURED_QUERY_PASSTHROUGH;
+var ok4, err4, CACHE_TTL_MS, FAILURE_COOLDOWN_MS, cache, retryNotBefore, EMPTY, DuplicateGeneratedToolError, STRUCTURED_QUERY_PASSTHROUGH;
 var init_generated_tools = __esm({
   "src/generated-tools.ts"() {
     "use strict";
-    ok2 = (data) => ({
+    ok4 = (data) => ({
       content: [{ type: "text", text: JSON.stringify(data, null, 2) }]
     });
-    err2 = (message) => ({
+    err4 = (message) => ({
       content: [{ type: "text", text: JSON.stringify({ error: message }) }],
       isError: true
     });
@@ -1644,7 +3517,7 @@ function isTransientStatus(status) {
   return status === 408 || status === 425 || status === 429 || status >= 500;
 }
 function sleep(ms) {
-  return new Promise((resolve) => setTimeout(resolve, ms));
+  return new Promise((resolve2) => setTimeout(resolve2, ms));
 }
 function headers(apiKey, orgId) {
   const value = {
@@ -1660,6 +3533,52 @@ function unsupportedResponse(status, body) {
   const lower = body.toLowerCase();
   return lower.includes("unknown governance action") || lower.includes("unknown action") || lower.includes("invalid_governance_action");
 }
+function toolMutability(toolName, action) {
+  if (toolName === "mindgraph_retrieve") return "read";
+  if (toolName === "mindgraph_plan") {
+    return action && PLAN_READ_ACTIONS.has(action) ? "read" : "write";
+  }
+  if (toolName === "mindgraph_ingest") {
+    return action === "job_status" ? "read" : "write";
+  }
+  if (toolName === "mindgraph_synthesize") {
+    return action === "signals" ? "read" : "write";
+  }
+  if (toolName === "mindgraph_code") {
+    return action === "anchor" ? "write" : "read";
+  }
+  if (toolName === "mindgraph_sync") {
+    return action === "scan" || action === "status" ? "read" : "write";
+  }
+  if (toolName === "mindgraph_ontology") {
+    return action && ONTOLOGY_READ_ACTIONS.has(action) ? "read" : "write";
+  }
+  if (/_(search|get|context|related|query)$/.test(toolName) && toolName !== "mindgraph_capture") {
+    return "read";
+  }
+  return "write";
+}
+function governanceTarget(toolName, args) {
+  const action = typeof args.action === "string" ? args.action : void 0;
+  const targetUids = /* @__PURE__ */ new Set();
+  for (const field of UID_FIELDS) {
+    const value = args[field];
+    if (typeof value === "string" && value.length > 0) targetUids.add(value);
+  }
+  for (const field of UID_ARRAY_FIELDS) {
+    const value = args[field];
+    if (!Array.isArray(value)) continue;
+    for (const uid of value) {
+      if (typeof uid === "string" && uid.length > 0) targetUids.add(uid);
+    }
+  }
+  return {
+    tool_name: toolName,
+    ...action ? { action } : {},
+    mutability: toolMutability(toolName, action),
+    target_uids: [...targetUids]
+  };
+}
 async function checkMcpGovernance(toolName, args, config) {
   if (config.disabled) return { allowed: true };
   if (capability === "unsupported") {
@@ -1682,7 +3601,7 @@ async function checkMcpGovernance(toolName, args, config) {
             action: "check",
             act: "tool_invoke",
             agent_id: String(args.agent_id || config.agentId),
-            target: { tool_name: toolName },
+            target: governanceTarget(toolName, args),
             context: { adapter: "mindgraph-mcp", ...config.context },
             tier: "checkpoint"
           })
@@ -1769,7 +3688,7 @@ async function checkMcpGovernance(toolName, args, config) {
     message: verdict === "conditional" ? `Approval is required${policy ? ` by policy ${policy}` : ""}${approvalUid ? ` (approval ${approvalUid})` : ""}` : `Denied by MindGraph governance${policy ? ` policy ${policy}` : ""}`
   };
 }
-var capability, UNSUPPORTED_LEASE_MS, unsupportedUntil, unsupportedLogged, DEFAULT_RETRY_DELAYS_MS, KNOWN_DUTIES;
+var capability, UNSUPPORTED_LEASE_MS, unsupportedUntil, unsupportedLogged, DEFAULT_RETRY_DELAYS_MS, KNOWN_DUTIES, PLAN_READ_ACTIONS, ONTOLOGY_READ_ACTIONS, UID_FIELDS, UID_ARRAY_FIELDS;
 var init_governance = __esm({
   "src/governance.ts"() {
     "use strict";
@@ -1779,6 +3698,59 @@ var init_governance = __esm({
     unsupportedLogged = false;
     DEFAULT_RETRY_DELAYS_MS = [150, 600];
     KNOWN_DUTIES = /* @__PURE__ */ new Set(["log", "require_approval"]);
+    PLAN_READ_ACTIONS = /* @__PURE__ */ new Set([
+      "get_plan",
+      "get_executions",
+      "get_pending",
+      "get_assessments",
+      "resume_work"
+    ]);
+    ONTOLOGY_READ_ACTIONS = /* @__PURE__ */ new Set([
+      "list_schemas",
+      "get_schema",
+      "query",
+      "search_objects",
+      "list_objects",
+      "get_object",
+      "get_context",
+      "list_proposals",
+      "get_proposal"
+    ]);
+    UID_FIELDS = [
+      "uid",
+      "source_uid",
+      "session_uid",
+      "work_uid",
+      "goal_uid",
+      "project_uid",
+      "task_uid",
+      "plan_uid",
+      "step_uid",
+      "target_uid",
+      "execution_uid",
+      "executor_uid",
+      "affordance_uid",
+      "produces_node_uid",
+      "filter_plan_uid",
+      "parent_uid",
+      "decision_uid",
+      "chosen_option_uid",
+      "governed_uid",
+      "approval_uid",
+      "requires_plan_uid",
+      "start_uid",
+      "end_uid"
+    ];
+    UID_ARRAY_FIELDS = [
+      "related_uids",
+      "depends_on_uids",
+      "summarizes_uids",
+      "informs_uid",
+      "target_uids",
+      "anchor_uids",
+      "scope_uids",
+      "produces_node_uids"
+    ];
   }
 });
 
@@ -1902,14 +3874,14 @@ async function main() {
     `MindGraph MCP server v0.7.1 running on stdio (${BASE_URL})`
   );
 }
-var import_server, import_stdio, import_types, import_mindgraph, API_KEY, BASE_URL, AGENT_ID, ORG_ID, client, INSTRUCTIONS, server, GOVERNANCE_CONFIG, PROMPTS;
+var import_server, import_stdio, import_types, import_mindgraph2, API_KEY, BASE_URL, AGENT_ID, ORG_ID, PROFILE, HARNESS, client, INSTRUCTIONS, server, GOVERNANCE_CONFIG, PROMPTS;
 var init_src = __esm({
   "src/index.ts"() {
     "use strict";
     import_server = require("@modelcontextprotocol/sdk/server/index.js");
     import_stdio = require("@modelcontextprotocol/sdk/server/stdio.js");
     import_types = require("@modelcontextprotocol/sdk/types.js");
-    import_mindgraph = require("mindgraph");
+    import_mindgraph2 = require("mindgraph");
     init_tools();
     init_generated_tools();
     init_governance();
@@ -1918,13 +3890,15 @@ var init_src = __esm({
     BASE_URL = process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud";
     AGENT_ID = process.env.MINDGRAPH_AGENT_ID || "mcp";
     ORG_ID = process.env.MINDGRAPH_ORG_ID;
+    PROFILE = process.env.MINDGRAPH_PROFILE || "general";
+    HARNESS = process.env.MINDGRAPH_HARNESS || "generic";
     if (!API_KEY) {
       console.error(
         "Error: MINDGRAPH_API_KEY environment variable is required.\nGet your API key at https://mindgraph.cloud/dashboard/keys\nOr run: npx mindgraph-mcp init"
       );
       process.exit(1);
     }
-    client = new import_mindgraph.MindGraph({
+    client = new import_mindgraph2.MindGraph({
       baseUrl: BASE_URL,
       apiKey: API_KEY,
       orgId: ORG_ID,
@@ -1933,7 +3907,7 @@ var init_src = __esm({
       // window where npm may still resolve the preceding SDK declaration file.
       telemetrySurface: "mcp"
     });
-    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph (7 tools).
+    INSTRUCTIONS = `You have access to a persistent knowledge graph via MindGraph, plus any ontology tools generated by the active schema.
 
 ## #1 RULE: Go straight to the user's topic
 
@@ -1996,22 +3970,42 @@ Capture knowledge when the user shares something worth remembering:
 - Questions to track \u2192 \`mindgraph_reason\` action "open_question"
 - Goals or projects \u2192 \`mindgraph_commit\` action "goal"/"project"
 - Decisions \u2192 \`mindgraph_commit\` action "open_decision"
+- Durable engineering work that must survive sessions/harnesses \u2192 \`mindgraph_plan\`
+- Typed code anchors, attached memory/work, callers/callees, or impact \u2192 \`mindgraph_code\`
+- Reusable learning from a material attempt \u2192 \`mindgraph_capture\` action "lesson"
 - Long-form content \u2192 \`mindgraph_ingest\`
 - Cross-document synthesis over a project corpus \u2192 \`mindgraph_synthesize\` (action "signals" for structural signals; action "run" to spawn a synthesis job that writes Article nodes)
 
 ## Tool tips
 
+- Use the harness todo list to organize only the current harness's local execution. Use \`mindgraph_plan\` when work is authoritative across sessions/harnesses, needs graph relationships or evidence, or must be visible to other agents. Do not maintain the same item in both.
+- If a local harness task remains unfinished and should become authoritative outside that local list, promote it once with a stable idempotency key when the graph-managed composite actions are available; otherwise do not copy it.
 - \`capture\`: "entity"/"observation" for facts, "journal" for personal/informal
 - \`reason\`: "claim" when evidence exists, "open_question"/"hypothesis" otherwise
 - \`retrieve\`: "context" returns graph nodes only by default \u2014 set include_chunks=true for source text
 - \`retrieve\`: "context" (FTS default) \u2192 "semantic" (conceptual fallback) \u2192 "hybrid" (both)
 - \`retrieve\`: "neighborhood"/"chain"/"path"/"subgraph" for graph exploration
+- \`code\`: pass path + symbol + signature when names are overloaded; ambiguity never writes
 - Confidence: 0.9+ for facts, 0.5-0.8 for uncertain, <0.5 for speculation
 - Don't narrate tool usage \u2014 capture naturally as part of conversation`;
+    if (PROFILE === "coding") {
+      INSTRUCTIONS += `
+
+## Coding profile
+
+- Use mindgraph_sync for explicit, one-way project memory-file imports. It discovers and hashes files, but you deliberately map durable assertions with record; it never writes graph state back to files.
+- Capture corrections, decisions with rationale, fixes that survived meaningful failed attempts, durable invariants/preferences, and blockers with evidence.
+- Do not capture routine mechanics, transient command output, facts cheaply derivable from code, unsupported speculation as high-confidence lessons, or completion without evidence.
+- Adapter context is owned by ${HARNESS}; omit invocation_context because hooks replace it.`;
+    } else {
+      INSTRUCTIONS = INSTRUCTIONS.split("\n").filter(
+        (line) => !line.includes("mindgraph_code") && !line.includes("`code`") && !line.includes("Typed code anchors")
+      ).join("\n");
+    }
     server = new import_server.Server(
       {
         name: "mindgraph",
-        version: "0.13.5"
+        version: "0.14.1"
       },
       {
         capabilities: {
@@ -2024,7 +4018,7 @@ Capture knowledge when the user shares something worth remembering:
     );
     server.setRequestHandler(import_types.ListToolsRequestSchema, async () => {
       const generated = await getGeneratedTools(client);
-      return { tools: [...TOOLS, ...generated.tools] };
+      return { tools: [...toolsForProfile(PROFILE), ...generated.tools] };
     });
     GOVERNANCE_CONFIG = {
       baseUrl: BASE_URL,
@@ -2229,30 +4223,683 @@ ${conversation}`
 });
 
 // src/cli.ts
-var fs = __toESM(require("fs"));
-var path = __toESM(require("path"));
-var os = __toESM(require("os"));
-var crypto = __toESM(require("crypto"));
+var fs5 = __toESM(require("fs"));
+var path5 = __toESM(require("path"));
+var os4 = __toESM(require("os"));
+var crypto4 = __toESM(require("crypto"));
 var import_child_process = require("child_process");
+var import_mindgraph3 = require("mindgraph");
+
+// src/hook-env.ts
+var import_node_fs = __toESM(require("fs"));
+var import_node_os = __toESM(require("os"));
+var import_node_path = __toESM(require("path"));
+function hookEnvPath(dir) {
+  return import_node_path.default.join(dir || import_node_path.default.join(import_node_os.default.homedir(), ".mindgraph"), "hooks.json");
+}
+function loadHookEnv(dir) {
+  try {
+    const raw = import_node_fs.default.readFileSync(hookEnvPath(dir), "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+      baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : void 0,
+      apiKey: typeof parsed.apiKey === "string" ? parsed.apiKey : void 0
+    };
+  } catch {
+    return {};
+  }
+}
+function saveHookEnv(env, dir) {
+  const file = hookEnvPath(dir);
+  import_node_fs.default.mkdirSync(import_node_path.default.dirname(file), { recursive: true });
+  const existing = loadHookEnv(dir);
+  const merged = {
+    baseUrl: env.baseUrl ?? existing.baseUrl,
+    apiKey: env.apiKey ?? existing.apiKey
+  };
+  import_node_fs.default.writeFileSync(file, `${JSON.stringify(merged, null, 2)}
+`, {
+    mode: 384
+  });
+  import_node_fs.default.chmodSync(file, 384);
+  return file;
+}
+
+// src/cli-args.ts
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  let command = "serve";
+  let apiKey = process.env.MINDGRAPH_API_KEY;
+  let baseUrl = process.env.MINDGRAPH_BASE_URL;
+  let scope = "project";
+  let projectDir;
+  let harness;
+  let hooks = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case "--api-key":
+        apiKey = args[++i];
+        break;
+      case "--base-url":
+        baseUrl = args[++i];
+        break;
+      case "--scope": {
+        const value = args[++i];
+        if (value !== "user" && value !== "project") {
+          throw new Error("--scope must be user or project");
+        }
+        scope = value;
+        break;
+      }
+      case "--project-dir":
+        projectDir = args[++i];
+        break;
+      case "--harness":
+        harness = args[++i];
+        break;
+      case "--hooks":
+        hooks = true;
+        break;
+      case "--owner":
+        ++i;
+        break;
+      case "--help":
+      case "-h":
+        command = "help";
+        break;
+      default:
+        if (!arg.startsWith("-")) {
+          command = arg;
+        }
+        break;
+    }
+  }
+  return { command, apiKey, baseUrl, scope, projectDir, harness, hooks };
+}
+
+// src/claude-hooks.ts
+var import_node_crypto2 = __toESM(require("crypto"));
+var import_node_fs3 = __toESM(require("fs"));
+var import_node_os3 = __toESM(require("os"));
+var import_node_path3 = __toESM(require("path"));
+var import_node_child_process2 = require("child_process");
+init_codegraph();
+function defaultLedger(sessionId) {
+  return {
+    harness: "claude-code",
+    harnessSessionId: sessionId,
+    materialToolCalls: 0,
+    mutatingOperations: 0,
+    memoryWritten: false,
+    iterationCheckpointed: false,
+    stopNudged: false,
+    nativeTasksCreated: 0,
+    nativeTasksTerminal: 0,
+    baselineWorktree: "unknown",
+    updatedAt: Date.now()
+  };
+}
+function runtimeDir(options) {
+  return options.runtimeDir || process.env.MINDGRAPH_RUNTIME_DIR || import_node_path3.default.join(import_node_os3.default.homedir(), ".mindgraph", "runtime");
+}
+function ledgerPath(sessionId, options) {
+  const key = import_node_crypto2.default.createHash("sha256").update(`claude-code\0${sessionId}`).digest("hex");
+  return import_node_path3.default.join(runtimeDir(options), `${key}.json`);
+}
+function waitBriefly(ms) {
+  Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+function withLedger(sessionId, options, update) {
+  const file = ledgerPath(sessionId, options);
+  import_node_fs3.default.mkdirSync(import_node_path3.default.dirname(file), { recursive: true, mode: 448 });
+  try {
+    import_node_fs3.default.chmodSync(import_node_path3.default.dirname(file), 448);
+  } catch {
+  }
+  const lock = `${file}.lock`;
+  let lockFd;
+  for (let attempt = 0; attempt < 50; attempt++) {
+    try {
+      lockFd = import_node_fs3.default.openSync(lock, "wx", 384);
+      break;
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      try {
+        if (Date.now() - import_node_fs3.default.statSync(lock).mtimeMs > 1e4) import_node_fs3.default.unlinkSync(lock);
+      } catch {
+      }
+      waitBriefly(10);
+    }
+  }
+  if (lockFd === void 0) {
+    return update(defaultLedger(sessionId));
+  }
+  try {
+    let ledger = defaultLedger(sessionId);
+    try {
+      ledger = {
+        ...ledger,
+        ...JSON.parse(import_node_fs3.default.readFileSync(file, "utf8"))
+      };
+    } catch {
+    }
+    const result = update(ledger);
+    ledger.updatedAt = Date.now();
+    const temporary = `${file}.${process.pid}.${import_node_crypto2.default.randomUUID()}.tmp`;
+    import_node_fs3.default.writeFileSync(temporary, `${JSON.stringify(ledger)}
+`, { mode: 384 });
+    import_node_fs3.default.renameSync(temporary, file);
+    try {
+      import_node_fs3.default.chmodSync(file, 384);
+    } catch {
+    }
+    return result;
+  } finally {
+    import_node_fs3.default.closeSync(lockFd);
+    try {
+      import_node_fs3.default.unlinkSync(lock);
+    } catch {
+    }
+  }
+}
+function readLedger(sessionId, options) {
+  return withLedger(sessionId, options, (ledger) => ({ ...ledger }));
+}
+function gitValue(cwd, args) {
+  try {
+    return (0, import_node_child_process2.execFileSync)("git", ["-C", cwd, ...args], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 750
+    }).trim();
+  } catch {
+    return void 0;
+  }
+}
+function worktreeState(cwd) {
+  const status = gitValue(cwd, ["status", "--porcelain"]);
+  return status === void 0 ? "unknown" : status ? "dirty" : "clean";
+}
+async function invocationContext(input, options) {
+  const repository = await new CodegraphAdapter({
+    cwd: input.cwd,
+    workspaceFile: options.workspaceFile
+  }).resolveRepository();
+  return {
+    harness: "claude-code",
+    harnessSessionId: input.session_id,
+    cwd: input.cwd,
+    repoId: repository.repoId,
+    branch: gitValue(input.cwd, ["branch", "--show-current"]),
+    commit: gitValue(input.cwd, ["rev-parse", "HEAD"]),
+    worktreeState: worktreeState(input.cwd),
+    model: input.model,
+    injectedBy: "hook"
+  };
+}
+function object(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+}
+function responsePayload(value) {
+  const direct = object(value);
+  if (!direct) return void 0;
+  if (Array.isArray(direct.content)) {
+    for (const item of direct.content) {
+      const block = object(item);
+      if (block?.type === "text" && typeof block.text === "string") {
+        try {
+          const parsed = JSON.parse(block.text);
+          const payload = object(parsed);
+          if (payload) return payload;
+        } catch {
+        }
+      }
+    }
+  }
+  return direct;
+}
+function number(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function string(value) {
+  return typeof value === "string" && value ? value : void 0;
+}
+function boundedBrief(brief) {
+  const encoded = JSON.stringify(brief, null, 2);
+  const capped = encoded.length <= 9e3 ? encoded : `${encoded.slice(0, 8900)}
+\u2026[bounded work brief truncated]`;
+  return [
+    "MindGraph durable work brief (authoritative across sessions/harnesses):",
+    capped,
+    "Use the harness todo list only for local execution details; do not duplicate this durable Task there."
+  ].join("\n");
+}
+async function repositoryScopeUids(input, client2, options, agentId) {
+  if (!client2.entity) return [];
+  const adapter = new CodegraphAdapter({
+    cwd: input.cwd,
+    workspaceFile: options.workspaceFile
+  });
+  const configured = await adapter.resolveRepositories();
+  const repositories = configured.length > 0 ? configured : [await adapter.resolveRepository()];
+  const resolved = await Promise.all(
+    repositories.map(
+      (repository) => client2.entity({
+        action: "resolve_identity",
+        identity: {
+          namespace: "external.code",
+          key_version: 1,
+          key: repositoryIdentityKey(repository)
+        },
+        agent_id: agentId
+      }).catch(() => void 0)
+    )
+  );
+  return [
+    ...new Set(
+      resolved.flatMap((response) => {
+        const payload = object(response);
+        return payload?.status === "existing" && string(payload.uid) ? [string(payload.uid)] : [];
+      })
+    )
+  ];
+}
+async function sessionStart(input, client2, options) {
+  const agentId = options.agentId || process.env.MINDGRAPH_AGENT_ID || "claude-code";
+  const opened = object(
+    await client2.session({
+      action: "open",
+      label: `Claude Code ${input.session_id}`,
+      harness: "claude-code",
+      harness_session_id: input.session_id,
+      model: input.model,
+      agent_id: agentId
+    })
+  );
+  const sessionUid = string(opened?.uid);
+  const scopeUids = await repositoryScopeUids(input, client2, options, agentId);
+  let brief = object(
+    await client2.plan({
+      action: "resume_work",
+      session_uid: sessionUid,
+      ...scopeUids.length > 0 ? { scope_uids: scopeUids } : {},
+      agent_id: agentId
+    })
+  );
+  const task = object(brief?.task);
+  const lease = object(brief?.lease);
+  if (sessionUid && string(task?.uid) && number(task?.version)) {
+    try {
+      const claimed = object(
+        await client2.plan({
+          action: "claim_task",
+          task_uid: task.uid,
+          session_uid: sessionUid,
+          expected_version: task.version,
+          idempotency_key: `session-start:${input.session_id}:${task.uid}:${lease?.lease_epoch || 0}`,
+          agent_id: agentId
+        })
+      );
+      brief = object(
+        await client2.plan({
+          action: "resume_work",
+          task_uid: task.uid,
+          session_uid: sessionUid,
+          ...scopeUids.length > 0 ? { scope_uids: scopeUids } : {},
+          agent_id: agentId
+        })
+      );
+      if (brief && claimed) brief.claim = claimed;
+    } catch {
+    }
+  }
+  withLedger(input.session_id, options, (ledger) => {
+    ledger.sessionUid = sessionUid;
+    ledger.baselineWorktree = worktreeState(input.cwd);
+    const selectedTask = object(brief?.task);
+    const selectedLease = object(brief?.lease) || object(brief?.claim);
+    const executions = Array.isArray(brief?.recent_executions) ? brief?.recent_executions : [];
+    const latest = object(executions[0]);
+    ledger.taskUid = string(selectedTask?.uid);
+    ledger.taskVersion = number(selectedTask?.version);
+    ledger.leaseEpoch = number(selectedLease?.lease_epoch);
+    ledger.leaseExpiresAt = number(selectedLease?.lease_expires_at);
+    ledger.executionUid = string(object(brief?.active_execution)?.uid) || string(latest?.uid);
+    return void 0;
+  });
+  return {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: boundedBrief(brief || { status: "no_eligible_work" })
+    }
+  };
+}
+async function preTool(input, options) {
+  const original = { ...input.tool_input || {} };
+  const ledger = readLedger(input.session_id, options);
+  const updatedInput = {
+    ...original,
+    invocation_context: await invocationContext(input, options)
+  };
+  if (ledger.sessionUid) updatedInput.session_uid = ledger.sessionUid;
+  if (ledger.taskUid && updatedInput.task_uid === void 0) {
+    updatedInput.task_uid = ledger.taskUid;
+  }
+  if (ledger.taskUid && input.tool_name?.includes("mindgraph_capture") && updatedInput.work_uid === void 0) {
+    updatedInput.work_uid = ledger.taskUid;
+  }
+  if (ledger.executionUid && updatedInput.execution_uid === void 0) {
+    updatedInput.execution_uid = ledger.executionUid;
+  }
+  if (ledger.leaseEpoch !== void 0 && updatedInput.lease_epoch === void 0) {
+    updatedInput.lease_epoch = ledger.leaseEpoch;
+  }
+  if (ledger.taskVersion !== void 0 && updatedInput.expected_version === void 0) {
+    updatedInput.expected_version = ledger.taskVersion;
+  }
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      updatedInput
+    }
+  };
+}
+async function postTool(input, client2, options) {
+  const name = input.tool_name || "";
+  const args = input.tool_input || {};
+  const action = string(args.action);
+  const payload = responsePayload(input.tool_response);
+  const nowSeconds = (options.now || (() => Date.now() / 1e3))();
+  let heartbeat;
+  withLedger(input.session_id, options, (ledger) => {
+    ledger.materialToolCalls += 1;
+    if (["Edit", "Write", "NotebookEdit"].includes(name) || name === "Bash" && action !== "read") {
+      ledger.mutatingOperations += 1;
+    }
+    if (name.includes("mindgraph_capture") && !payload?.error) {
+      ledger.memoryWritten = true;
+    }
+    if (name.includes("mindgraph_plan")) {
+      if (action === "start_iteration" && !payload?.error) {
+        ledger.executionUid = string(payload?.execution_uid) || ledger.executionUid;
+      }
+      if (["checkpoint_iteration", "block_task", "complete_task", "abandon_iteration"].includes(
+        action || ""
+      ) && !payload?.error) {
+        ledger.iterationCheckpointed = true;
+        if (action !== "block_task") ledger.executionUid = void 0;
+      }
+      ledger.taskVersion = number(payload?.task_version) || number(payload?.version) || ledger.taskVersion;
+      ledger.leaseEpoch = number(payload?.lease_epoch) || ledger.leaseEpoch;
+      ledger.leaseExpiresAt = number(payload?.lease_expires_at) || ledger.leaseExpiresAt;
+    }
+    if (ledger.taskUid && ledger.sessionUid && ledger.taskVersion !== void 0 && ledger.leaseEpoch !== void 0 && ledger.leaseExpiresAt !== void 0 && ledger.leaseExpiresAt - nowSeconds <= 60) {
+      heartbeat = {
+        taskUid: ledger.taskUid,
+        sessionUid: ledger.sessionUid,
+        taskVersion: ledger.taskVersion,
+        leaseEpoch: ledger.leaseEpoch
+      };
+    }
+    return void 0;
+  });
+  if (heartbeat) {
+    try {
+      const response = object(
+        await client2.plan({
+          action: "heartbeat",
+          task_uid: heartbeat.taskUid,
+          session_uid: heartbeat.sessionUid,
+          expected_version: heartbeat.taskVersion,
+          lease_epoch: heartbeat.leaseEpoch,
+          idempotency_key: `hook-heartbeat:${input.session_id}:${heartbeat.taskUid}:${Math.floor(nowSeconds / 60)}`,
+          agent_id: options.agentId || "claude-code"
+        })
+      );
+      withLedger(input.session_id, options, (ledger) => {
+        ledger.leaseExpiresAt = number(response?.lease_expires_at) || ledger.leaseExpiresAt;
+        return void 0;
+      });
+    } catch {
+    }
+  }
+  return {};
+}
+function stop(input, options) {
+  if (input.stop_hook_active) return {};
+  return withLedger(input.session_id, options, (ledger) => {
+    const changed = ledger.mutatingOperations >= 2 || ledger.baselineWorktree !== "unknown" && worktreeState(input.cwd) !== ledger.baselineWorktree;
+    const substantial = Boolean(ledger.executionUid) || changed;
+    if (!substantial || ledger.iterationCheckpointed || ledger.memoryWritten || ledger.stopNudged) {
+      return {};
+    }
+    ledger.stopNudged = true;
+    return {
+      decision: "block",
+      reason: "Substantial work is still uncheckpointed. Checkpoint the active iteration, capture one durable lesson/decision/risk, or explicitly state that nothing durable changed. If a local harness task should become authoritative outside this list, promote it once with a stable idempotency key; otherwise do not copy it."
+    };
+  });
+}
+async function sessionEnd(input, client2, options) {
+  const ledger = readLedger(input.session_id, options);
+  if (ledger.executionUid && ledger.taskUid && ledger.sessionUid && ledger.taskVersion !== void 0 && ledger.leaseEpoch !== void 0) {
+    try {
+      await client2.plan({
+        action: "abandon_iteration",
+        task_uid: ledger.taskUid,
+        execution_uid: ledger.executionUid,
+        session_uid: ledger.sessionUid,
+        expected_version: ledger.taskVersion,
+        lease_epoch: ledger.leaseEpoch,
+        release_lease: true,
+        summary: `Claude Code SessionEnd: ${input.reason || "interrupted"}`,
+        idempotency_key: `session-end:${input.session_id}:${ledger.executionUid}`,
+        agent_id: options.agentId || "claude-code"
+      });
+    } catch {
+    }
+  }
+  if (ledger.sessionUid) {
+    try {
+      await client2.session({
+        action: "close",
+        session_uid: ledger.sessionUid,
+        agent_id: options.agentId || "claude-code"
+      });
+    } catch {
+    }
+  }
+  return {};
+}
+async function runClaudeHook(input, client2, options = {}) {
+  switch (input.hook_event_name) {
+    case "SessionStart":
+      return sessionStart(input, client2, options);
+    case "PreToolUse":
+      if (!input.tool_name?.startsWith("mcp__mindgraph__")) return {};
+      return preTool(input, options);
+    case "PostToolUse":
+      return postTool(input, client2, options);
+    case "TaskCreated":
+      withLedger(input.session_id, options, (ledger) => {
+        ledger.nativeTasksCreated += 1;
+        return void 0;
+      });
+      return {};
+    case "TaskCompleted":
+      withLedger(input.session_id, options, (ledger) => {
+        ledger.nativeTasksTerminal += 1;
+        return void 0;
+      });
+      return {};
+    case "Stop":
+      return stop(input, options);
+    case "SessionEnd":
+      return sessionEnd(input, client2, options);
+    default:
+      return {};
+  }
+}
+async function readHookInput(stream = process.stdin) {
+  const chunks = [];
+  for await (const chunk of stream) {
+    chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+  }
+  return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+
+// src/hook-installer.ts
+var import_node_fs4 = __toESM(require("fs"));
+var import_node_os4 = __toESM(require("os"));
+var import_node_path4 = __toESM(require("path"));
+var import_node_crypto3 = __toESM(require("crypto"));
+var OWNER_MARKER = "--owner mindgraph";
+var RUNNER_RELATIVE = ".mindgraph/bin/mindgraph-hook.cjs";
+var COMMAND = `node "$HOME/${RUNNER_RELATIVE}" hook --harness claude-code --owner mindgraph`;
+function installHookRunner(sourceFile, homeDir) {
+  const target = import_node_path4.default.join(homeDir || import_node_os4.default.homedir(), RUNNER_RELATIVE);
+  import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(target), { recursive: true });
+  import_node_fs4.default.copyFileSync(sourceFile, target);
+  return target;
+}
+function uninstallHookRunner(homeDir) {
+  try {
+    import_node_fs4.default.rmSync(import_node_path4.default.join(homeDir || import_node_os4.default.homedir(), RUNNER_RELATIVE));
+  } catch {
+  }
+}
+function settingsPath(scope, projectDir = process.cwd()) {
+  return scope === "user" ? import_node_path4.default.join(import_node_os4.default.homedir(), ".claude", "settings.json") : import_node_path4.default.join(projectDir, ".claude", "settings.json");
+}
+function readSettings(file) {
+  if (!import_node_fs4.default.existsSync(file)) return {};
+  return JSON.parse(import_node_fs4.default.readFileSync(file, "utf8"));
+}
+function ownedHook(timeout) {
+  return {
+    type: "command",
+    command: COMMAND,
+    timeout,
+    statusMessage: "Syncing MindGraph session context"
+  };
+}
+function desiredEntries() {
+  return {
+    SessionStart: [
+      {
+        matcher: "startup|resume|clear|compact|fork",
+        hooks: [ownedHook(20)]
+      }
+    ],
+    PreToolUse: [
+      {
+        matcher: "mcp__mindgraph__.*",
+        hooks: [ownedHook(3)]
+      }
+    ],
+    PostToolUse: [{ matcher: ".*", hooks: [ownedHook(5)] }],
+    TaskCreated: [{ hooks: [ownedHook(3)] }],
+    TaskCompleted: [{ hooks: [ownedHook(3)] }],
+    Stop: [{ hooks: [ownedHook(5)] }],
+    SessionEnd: [{ hooks: [ownedHook(8)] }]
+  };
+}
+function hookCommand(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return void 0;
+  const command = value.command;
+  return typeof command === "string" ? command : void 0;
+}
+function entryHasOwnedHook(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const hooks = value.hooks;
+  return Array.isArray(hooks) && hooks.some((hook) => hookCommand(hook)?.includes(OWNER_MARKER));
+}
+function writeSettings(file, settings) {
+  import_node_fs4.default.mkdirSync(import_node_path4.default.dirname(file), { recursive: true });
+  const temporary = `${file}.${process.pid}.${import_node_crypto3.default.randomUUID()}.tmp`;
+  import_node_fs4.default.writeFileSync(temporary, `${JSON.stringify(settings, null, 2)}
+`, {
+    mode: 384
+  });
+  import_node_fs4.default.renameSync(temporary, file);
+}
+function installClaudeHooks(scope, projectDir = process.cwd()) {
+  const file = settingsPath(scope, projectDir);
+  const settings = readSettings(file);
+  const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? settings.hooks : {};
+  let added = 0;
+  for (const [event, wanted] of Object.entries(desiredEntries())) {
+    const current = Array.isArray(hooks[event]) ? [...hooks[event]] : [];
+    for (const entry of wanted) {
+      if (!current.some(entryHasOwnedHook)) {
+        current.push(entry);
+        added += 1;
+      }
+    }
+    hooks[event] = current;
+  }
+  settings.hooks = hooks;
+  writeSettings(file, settings);
+  return { path: file, added };
+}
+function uninstallClaudeHooks(scope, projectDir = process.cwd()) {
+  const file = settingsPath(scope, projectDir);
+  if (!import_node_fs4.default.existsSync(file)) return { path: file, removed: 0 };
+  const settings = readSettings(file);
+  const hooks = settings.hooks && typeof settings.hooks === "object" && !Array.isArray(settings.hooks) ? settings.hooks : {};
+  let removed = 0;
+  for (const [event, value] of Object.entries(hooks)) {
+    if (!Array.isArray(value)) continue;
+    const retainedEntries = [];
+    for (const rawEntry of value) {
+      if (!rawEntry || typeof rawEntry !== "object" || Array.isArray(rawEntry)) {
+        retainedEntries.push(rawEntry);
+        continue;
+      }
+      const entry = { ...rawEntry };
+      if (!Array.isArray(entry.hooks)) {
+        retainedEntries.push(entry);
+        continue;
+      }
+      const retainedHooks = entry.hooks.filter((hook) => {
+        const owned = hookCommand(hook)?.includes(OWNER_MARKER) || false;
+        if (owned) removed += 1;
+        return !owned;
+      });
+      if (retainedHooks.length > 0) {
+        entry.hooks = retainedHooks;
+        retainedEntries.push(entry);
+      }
+    }
+    if (retainedEntries.length > 0) hooks[event] = retainedEntries;
+    else delete hooks[event];
+  }
+  settings.hooks = hooks;
+  writeSettings(file, settings);
+  return { path: file, removed };
+}
+
+// src/cli.ts
 function getClaudeDesktopConfigPath() {
   switch (process.platform) {
     case "darwin":
-      return path.join(
-        os.homedir(),
+      return path5.join(
+        os4.homedir(),
         "Library",
         "Application Support",
         "Claude",
         "claude_desktop_config.json"
       );
     case "win32":
-      return path.join(
-        process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming"),
+      return path5.join(
+        process.env.APPDATA || path5.join(os4.homedir(), "AppData", "Roaming"),
         "Claude",
         "claude_desktop_config.json"
       );
     case "linux":
-      return path.join(
-        os.homedir(),
+      return path5.join(
+        os4.homedir(),
         ".config",
         "Claude",
         "claude_desktop_config.json"
@@ -2262,16 +4909,16 @@ function getClaudeDesktopConfigPath() {
   }
 }
 function readJsonFile(filePath) {
-  if (!fs.existsSync(filePath)) return {};
-  const content = fs.readFileSync(filePath, "utf-8");
+  if (!fs5.existsSync(filePath)) return {};
+  const content = fs5.readFileSync(filePath, "utf-8");
   return JSON.parse(content);
 }
 function writeJsonFile(filePath, data) {
-  const dir = path.dirname(filePath);
-  if (!fs.existsSync(dir)) {
-    fs.mkdirSync(dir, { recursive: true });
+  const dir = path5.dirname(filePath);
+  if (!fs5.existsSync(dir)) {
+    fs5.mkdirSync(dir, { recursive: true });
   }
-  fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+  fs5.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
 }
 function getMcpServerEntry(apiKey, baseUrl) {
   const env = { MINDGRAPH_API_KEY: apiKey };
@@ -2301,7 +4948,16 @@ function installClaudeDesktop(apiKey, baseUrl) {
   console.log("Restart Claude Desktop to activate.");
 }
 function installClaudeCode(apiKey, baseUrl) {
-  const envArgs = [`--env`, `MINDGRAPH_API_KEY=${apiKey}`];
+  const envArgs = [
+    `--env`,
+    `MINDGRAPH_API_KEY=${apiKey}`,
+    "--env",
+    "MINDGRAPH_PROFILE=coding",
+    "--env",
+    "MINDGRAPH_HARNESS=claude-code",
+    "--env",
+    "MINDGRAPH_AGENT_ID=claude-code"
+  ];
   if (baseUrl) {
     envArgs.push("--env", `MINDGRAPH_BASE_URL=${baseUrl}`);
   }
@@ -2331,7 +4987,7 @@ function installClaudeCode(apiKey, baseUrl) {
 }
 function uninstallClaudeDesktop() {
   const configPath = getClaudeDesktopConfigPath();
-  if (!fs.existsSync(configPath)) {
+  if (!fs5.existsSync(configPath)) {
     console.log("Claude Desktop config not found. Nothing to remove.");
     return;
   }
@@ -2358,7 +5014,7 @@ function uninstallClaudeCode() {
 }
 function printStatus() {
   const desktopPath = getClaudeDesktopConfigPath();
-  if (fs.existsSync(desktopPath)) {
+  if (fs5.existsSync(desktopPath)) {
     const config = readJsonFile(desktopPath);
     const servers = config.mcpServers;
     if (servers && "mindgraph" in servers) {
@@ -2376,6 +5032,36 @@ function printStatus() {
     `MINDGRAPH_BASE_URL: ${process.env.MINDGRAPH_BASE_URL || "https://api.mindgraph.cloud (default)"}`
   );
 }
+function withHooksFlag() {
+  return process.argv.includes("--hooks");
+}
+function finishCodeInstall(apiKey, baseUrl, withHooks) {
+  if (withHooks) {
+    const runner = installHookRunner(__filename);
+    console.log(`Installed pinned hook runner at ${runner}`);
+    const result = installClaudeHooks("user");
+    console.log(
+      `Installed ${result.added} MindGraph Claude Code hook entries in ${result.path}`
+    );
+    const envPath = saveHookEnv({ apiKey, baseUrl });
+    console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
+  } else {
+    console.log(
+      "Tip: run with --hooks (or run install-hooks) to add the Claude Code session hooks \u2014 work-brief injection, provenance, reflection checkpoint."
+    );
+  }
+  printCodegraphStatus();
+}
+function printCodegraphStatus() {
+  try {
+    (0, import_child_process.execFileSync)("codegraph", ["--version"], { stdio: "pipe" });
+    console.log("Code intelligence: codegraph detected \u2014 anchors and structural recall are enabled.");
+  } catch {
+    console.log(
+      "Optional: enable code intelligence by installing codegraph (https://github.com/colbymchenry/codegraph) and running `codegraph init` in your repositories. Without it, memory and work tools still function; code anchoring degrades gracefully."
+    );
+  }
+}
 function printUsage() {
   console.log(`
 mindgraph-mcp \u2014 MCP server for MindGraph knowledge graphs
@@ -2384,14 +5070,19 @@ USAGE:
   mindgraph-mcp                  Start the MCP server (stdio transport)
   mindgraph-mcp init             Interactive setup for Claude Desktop
   mindgraph-mcp install          Install into Claude Desktop config
-  mindgraph-mcp install-code     Install into Claude Code
+  mindgraph-mcp install-code     Install into Claude Code (--hooks: + session hooks)
   mindgraph-mcp uninstall        Remove from Claude Desktop config
   mindgraph-mcp uninstall-code   Remove from Claude Code
+  mindgraph-mcp install-hooks --harness claude-code [--scope user|project]
+  mindgraph-mcp uninstall-hooks --harness claude-code [--scope user|project]
   mindgraph-mcp status           Show installation status
 
 OPTIONS:
   --api-key <key>     MindGraph API key (or set MINDGRAPH_API_KEY env var)
   --base-url <url>    Custom API base URL (default: https://api.mindgraph.cloud)
+  --scope <scope>     Hook settings scope: project (default) or user
+  --project-dir <dir> Project root for project-scoped hooks
+  --harness <name>    Hook harness (currently claude-code)
   --help, -h          Show this help message
 
 EXAMPLES:
@@ -2407,38 +5098,11 @@ EXAMPLES:
 Get your API key at: https://mindgraph.cloud/dashboard/keys
 `);
 }
-function parseArgs(argv) {
-  const args = argv.slice(2);
-  let command = "serve";
-  let apiKey = process.env.MINDGRAPH_API_KEY;
-  let baseUrl = process.env.MINDGRAPH_BASE_URL;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    switch (arg) {
-      case "--api-key":
-        apiKey = args[++i];
-        break;
-      case "--base-url":
-        baseUrl = args[++i];
-        break;
-      case "--help":
-      case "-h":
-        command = "help";
-        break;
-      default:
-        if (!arg.startsWith("-")) {
-          command = arg;
-        }
-        break;
-    }
-  }
-  return { command, apiKey, baseUrl };
-}
 var DASHBOARD_URL = process.env.MINDGRAPH_DASHBOARD_URL || "https://mindgraph.cloud";
 var POLL_INTERVAL = 2e3;
 var POLL_TIMEOUT = 10 * 60 * 1e3;
 function generateCode() {
-  return crypto.randomBytes(32).toString("hex");
+  return crypto4.randomBytes(32).toString("hex");
 }
 function openBrowser(url) {
   try {
@@ -2475,7 +5139,7 @@ async function pollForKey(code) {
     } catch (e) {
       if (e instanceof Error && e.message.includes("Session")) throw e;
     }
-    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL));
+    await new Promise((resolve2) => setTimeout(resolve2, POLL_INTERVAL));
   }
   throw new Error("Timed out waiting for authorization.");
 }
@@ -2485,7 +5149,7 @@ async function interactiveInit(baseUrl) {
     input: process.stdin,
     output: process.stdout
   });
-  const ask = (q) => new Promise((resolve) => rl.question(q, resolve));
+  const ask = (q) => new Promise((resolve2) => rl.question(q, resolve2));
   console.log("\nMindGraph MCP Server Setup\n");
   console.log("  1. Sign in via browser (recommended)");
   console.log("  2. Enter API key manually");
@@ -2532,10 +5196,12 @@ async function interactiveInit(baseUrl) {
       break;
     case "2":
       installClaudeCode(apiKey, baseUrl);
+      finishCodeInstall(apiKey, baseUrl, withHooksFlag());
       break;
     case "3":
       installClaudeDesktop(apiKey, baseUrl);
       installClaudeCode(apiKey, baseUrl);
+      finishCodeInstall(apiKey, baseUrl, withHooksFlag());
       break;
     default:
       console.error("Invalid choice.");
@@ -2544,7 +5210,7 @@ async function interactiveInit(baseUrl) {
   console.log("\nDone! Your knowledge graph is now connected.");
 }
 async function main2() {
-  const { command, apiKey, baseUrl } = parseArgs(process.argv);
+  const { command, apiKey, baseUrl, scope, projectDir, harness, hooks } = parseArgs(process.argv);
   switch (command) {
     case "help":
       printUsage();
@@ -2569,6 +5235,7 @@ async function main2() {
         process.exit(1);
       }
       installClaudeCode(apiKey, baseUrl);
+      finishCodeInstall(apiKey, baseUrl, withHooksFlag());
       break;
     case "uninstall":
       uninstallClaudeDesktop();
@@ -2576,6 +5243,64 @@ async function main2() {
     case "uninstall-code":
       uninstallClaudeCode();
       break;
+    case "install-hooks": {
+      if ((harness || "claude-code") !== "claude-code") {
+        throw new Error("only --harness claude-code is available in this release");
+      }
+      const runner = installHookRunner(__filename);
+      console.log(`Installed pinned hook runner at ${runner}`);
+      const result = installClaudeHooks(scope, projectDir);
+      console.log(
+        `Installed ${result.added} MindGraph Claude Code hook entries in ${result.path}`
+      );
+      if (apiKey || baseUrl) {
+        const envPath = saveHookEnv({ apiKey, baseUrl });
+        console.log(`Saved hook connection settings to ${envPath} (mode 600)`);
+      } else {
+        console.log(
+          "Note: hooks resolve MINDGRAPH_API_KEY/MINDGRAPH_BASE_URL from the environment or ~/.mindgraph/hooks.json \u2014 pass --api-key/--base-url to persist them now."
+        );
+      }
+      break;
+    }
+    case "uninstall-hooks": {
+      if ((harness || "claude-code") !== "claude-code") {
+        throw new Error("only --harness claude-code is available in this release");
+      }
+      uninstallHookRunner();
+      const result = uninstallClaudeHooks(scope, projectDir);
+      console.log(
+        `Removed ${result.removed} MindGraph Claude Code hooks from ${result.path}`
+      );
+      break;
+    }
+    case "hook": {
+      const stored = loadHookEnv();
+      const hookApiKey = apiKey ?? stored.apiKey;
+      const hookBaseUrl = baseUrl ?? stored.baseUrl;
+      if (!hookApiKey) {
+        process.stdout.write("{}\n");
+        break;
+      }
+      try {
+        const input = await readHookInput();
+        const client2 = new import_mindgraph3.MindGraph({
+          baseUrl: hookBaseUrl || "https://api.mindgraph.cloud",
+          apiKey: hookApiKey,
+          orgId: process.env.MINDGRAPH_ORG_ID,
+          maxRetries: 0,
+          telemetrySurface: "mcp"
+        });
+        const output = await runClaudeHook(input, client2, {
+          agentId: process.env.MINDGRAPH_AGENT_ID || "claude-code"
+        });
+        process.stdout.write(`${JSON.stringify(output)}
+`);
+      } catch {
+        process.stdout.write("{}\n");
+      }
+      break;
+    }
     case "status":
       printStatus();
       break;