chainlesschain 0.162.166 → 0.162.168

package/src/lib/lsp/__tests__/lsp-server-registry.test.js

@@ -11,6 +11,7 @@ import {
   resolveServer,
   resolveBin,
   probeServers,
+  describeServer,
   registerLanguageServer,
   _resetPluginServers,
   _deps,
@@ -126,3 +127,29 @@ describe("probeServers", () => {
     expect(ids).toContain("typescript-language-server");
   });
 });
+
+describe("describeServer", () => {
+  it("names the builtin server for a language even when not installed", () => {
+    existsFor([]); // nothing on PATH
+    const ts = describeServer("typescript");
+    expect(ts.id).toBe("typescript-language-server");
+    expect(ts.bins).toContain("typescript-language-server");
+    // Independent of install state — it describes the EXPECTED server.
+    expect(describeServer("python").id).toBe("pyright");
+    expect(describeServer("go").id).toBe("gopls");
+  });
+
+  it("returns null for an unsupported language", () => {
+    expect(describeServer("cobol")).toBe(null);
+    expect(describeServer(undefined)).toBe(null);
+  });
+
+  it("prefers a registered plugin server over the builtin", () => {
+    registerLanguageServer({
+      languageId: "typescript",
+      command: "my-ts-lsp",
+      id: "plugin-ts",
+    });
+    expect(describeServer("typescript").id).toBe("plugin-ts");
+  });
+});

package/src/lib/lsp/code-intelligence.js

@@ -64,7 +64,11 @@ export class CodeIntelligence {
       /* plugin LSP contributions are best-effort */
     }
     this.manager =
-      opts.manager || new LSPManager({ projectRoot: opts.projectRoot });
+      opts.manager ||
+      new LSPManager({
+        projectRoot: opts.projectRoot,
+        ...(opts.lspOptions || {}),
+      });
     this._ownsManager = !opts.manager;
     // One-shot callers (the `cc code-intel` CLI) spawn a cold server per run and
     // must wait for the project to load before querying; the long-lived agent

package/src/lib/lsp/lsp-server-registry.js

@@ -232,3 +232,17 @@ export function probeServers(projectRoot) {
 export function supportedExtensions() {
   return Object.keys(EXTENSION_LANGUAGE).sort();
 }
+
+/**
+ * Describe the server that WOULD serve a languageId, whether or not its binary
+ * is installed — the first plugin candidate, else the builtin. Unlike
+ * `resolveServer` (which returns null when nothing is on PATH), this names the
+ * expected server so a doctor / status view can say *what to install*. Returns
+ * `{ id, bins }` or null for an unsupported language.
+ */
+export function describeServer(languageId) {
+  const candidates = [...(pluginServers.get(languageId) || [])];
+  if (BUILTIN_SERVERS[languageId]) candidates.push(BUILTIN_SERVERS[languageId]);
+  const def = candidates[0];
+  return def ? { id: def.id, bins: [...def.bins] } : null;
+}

package/src/lib/lsp/workspace-roots.js

@@ -0,0 +1,115 @@
+/**
+ * workspace-roots — pure helpers for multi-root LSP workspaces (P2 LSP slice,
+ * CLAUDE_CODE_CLI_INCREMENTAL_GAP_ANALYSIS_2026-07-12 §"LSP 与 Code Review").
+ *
+ * A session started with `--add-dir` works across several project roots, but
+ * `code_intelligence` always keyed its shared language-server pool on the cwd
+ * alone — a query for a file living in an additional root spawned (or reused)
+ * the WRONG project's server, and `workspace_symbols` could only ever see the
+ * cwd project. These helpers make root selection explicit and testable:
+ *
+ *  - `workspaceRootsFor(cwd, additionalDirectories)` — the deduped, resolved
+ *    root list (cwd first, mirroring the roots the system prompt advertises).
+ *  - `pickRootForFile(file, roots)` — the root that CONTAINS the file
+ *    (deepest match wins so nested roots resolve to the more specific
+ *    project); falls back to the first root (cwd) for out-of-root files,
+ *    which is the pre-multi-root behavior.
+ *  - `mergeWorkspaceSymbolResults(results, roots)` — fold per-root
+ *    `workspaceSymbols` outcomes into one: available when ANY root answered,
+ *    symbols concatenated in root order and stamped with their `root` so
+ *    same-named symbols from different projects stay unambiguous.
+ *
+ * Pure + IO-free (path math only) so agent-core can consume them without any
+ * new export surface of its own.
+ */
+
+import path from "node:path";
+
+/** Case-fold for prefix comparison on case-insensitive filesystems. */
+function fold(p) {
+  return process.platform === "win32" ? p.toLowerCase() : p;
+}
+
+/**
+ * Resolved, deduped workspace roots — cwd first, then each additional
+ * directory. Non-string/empty entries are dropped; never returns empty (falls
+ * back to process.cwd()).
+ */
+export function workspaceRootsFor(cwd, additionalDirectories) {
+  const out = [];
+  const seen = new Set();
+  const push = (dir) => {
+    if (typeof dir !== "string" || dir.trim() === "") return;
+    const resolved = path.resolve(dir);
+    const key = fold(resolved);
+    if (seen.has(key)) return;
+    seen.add(key);
+    out.push(resolved);
+  };
+  push(cwd || process.cwd());
+  for (const d of Array.isArray(additionalDirectories)
+    ? additionalDirectories
+    : []) {
+    push(d);
+  }
+  if (out.length === 0) out.push(path.resolve(process.cwd()));
+  return out;
+}
+
+/**
+ * The workspace root that contains `file` — deepest containing root wins
+ * (nested roots resolve to the more specific project). Files outside every
+ * root fall back to the FIRST root (cwd), preserving the single-root
+ * behavior byte-for-byte.
+ */
+export function pickRootForFile(file, roots) {
+  const list = Array.isArray(roots) && roots.length > 0 ? roots : null;
+  if (!list) return path.resolve(process.cwd());
+  if (typeof file !== "string" || file.trim() === "") return list[0];
+  const f = fold(path.resolve(file));
+  let best = null;
+  for (const root of list) {
+    const r = fold(path.resolve(root));
+    if (f === r || f.startsWith(r + path.sep)) {
+      if (best === null || r.length > fold(best).length) {
+        best = path.resolve(root);
+      }
+    }
+  }
+  return best || list[0];
+}
+
+/**
+ * Merge per-root `workspaceSymbols` results (same order as `roots`).
+ * Any available root makes the merged result available; each symbol is
+ * stamped with its `root`. All-unavailable folds the reasons together so the
+ * caller still sees WHY (first reason wins the summary, all are listed).
+ */
+export function mergeWorkspaceSymbolResults(results, roots = []) {
+  const list = Array.isArray(results) ? results : [];
+  const symbols = [];
+  const reasons = [];
+  let anyAvailable = false;
+  for (let i = 0; i < list.length; i++) {
+    const r = list[i];
+    if (r && r.available) {
+      anyAvailable = true;
+      for (const s of Array.isArray(r.symbols) ? r.symbols : []) {
+        symbols.push(roots[i] ? { ...s, root: roots[i] } : s);
+      }
+    } else if (r) {
+      reasons.push(
+        roots[i]
+          ? `${roots[i]}: ${r.reason || "unavailable"}`
+          : r.reason || "unavailable",
+      );
+    }
+  }
+  if (!anyAvailable) {
+    return {
+      available: false,
+      reason: reasons.join("; ") || "language server unavailable",
+    };
+  }
+  return { available: true, symbols };
+}

package/src/lib/runtime-checkup.js

@@ -437,6 +437,39 @@ export function checkDuplicateSkills(entries = []) {
   return out;
 }
 
+/**
+ * LSP READINESS: languages the project actually contains but for which no
+ * language server is installed — the silent reason `code_intelligence` /
+ * `cc code-intel` quietly degrades to plain text search. Unlike
+ * `checkPluginsAndLsp` (live server health) this is a STATIC install-gap check a
+ * separate `cc doctor` process can compute without any server running: it
+ * correlates source files present with `resolveServer` availability. Only
+ * present-but-missing languages warn; installed languages produce nothing (no
+ * noise). Each `languages` entry: `{ languageId, fileCount, available, serverId,
+ * exampleBin }`.
+ */
+export function checkLspReadiness(languages = []) {
+  const out = [];
+  for (const l of languages) {
+    if (!l || !l.languageId) continue;
+    const fileCount = Number(l.fileCount) || 0;
+    if (fileCount <= 0 || l.available) continue;
+    const server = l.serverId || `a ${l.languageId} language server`;
+    const install = l.exampleBin ? ` (e.g. install ${l.exampleBin})` : "";
+    out.push(
+      finding(
+        "lsp-server-missing",
+        "lsp",
+        "warn",
+        `${fileCount} ${l.languageId} file(s) present but no language server installed${install}`,
+        `install ${server} for real code-intelligence, or ignore to keep text-search fallback`,
+        { ref: l.languageId, fileCount, serverId: l.serverId || null },
+      ),
+    );
+  }
+  return out;
+}
+
 /** Plugins / LSP servers reported unhealthy or dead. */
 export function checkPluginsAndLsp(plugins = []) {
   const out = [];

package/src/lib/settings-hook-events.cjs

@@ -47,7 +47,15 @@ function withDeliveryId(event, payload, { sessionId, traceId, parentId } = {}) {
       /* best-effort — recording must not break the turn */
     }
   }
-  return { ...payload, event_id: env.event_id };
+  // trace_id/parent_id are stamped onto the DELIVERED payload only when the
+  // caller actually threaded them (agent-core context) — absent they are
+  // omitted entirely, keeping every legacy payload byte-identical.
+  return {
+    ...payload,
+    event_id: env.event_id,
+    ...(env.trace_id ? { trace_id: env.trace_id } : {}),
+    ...(env.parent_id ? { parent_id: env.parent_id } : {}),
+  };
 }
 
 /**
@@ -178,6 +186,159 @@ function runSessionStartHooks(settingsHooks, { source, cwd, sessionId } = {}) {
   return { additionalContext: aggregateContext(outcome.results) };
 }
 
+/**
+ * CwdChanged settings hooks (observe + context injection). Fired when the
+ * working directory changes mid-session (`/cd`) — a distinct lifecycle event
+ * (Claude-Code-parity extension) automation can react to (re-audit trust of the
+ * new dir, reload a per-dir tool config, …). Observe-only: a cwd change never
+ * gates flow, so any `block` decision is ignored and only emitted context is
+ * returned. No-op (byte-unchanged) without a registered CwdChanged hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runCwdChangedHooks(
+  settingsHooks,
+  { oldCwd, newCwd, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "CwdChanged", newCwd || "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const payload = withDeliveryId(
+    "CwdChanged",
+    {
+      hook_event_name: "CwdChanged",
+      old_cwd: oldCwd || null,
+      cwd: newCwd || cwd || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd: newCwd || cwd,
+    event: "CwdChanged",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * WorktreeCreate settings hooks (observe + context injection). Fired right after
+ * `cc agent --worktree` carves a fresh isolated git worktree — a hook can react
+ * (register the worktree with an external tracker, seed per-branch tooling,
+ * warm a build cache). The matcher target is the branch name, so a regex matcher
+ * can scope to a branch pattern. Observe-only: worktree setup already succeeded,
+ * so a `block` decision is ignored and only emitted context is returned. No-op
+ * (byte-unchanged) without a registered WorktreeCreate hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runWorktreeCreateHooks(
+  settingsHooks,
+  { worktreePath, branch, baseSha, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "WorktreeCreate", branch || "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const payload = withDeliveryId(
+    "WorktreeCreate",
+    {
+      hook_event_name: "WorktreeCreate",
+      worktree_path: worktreePath || null,
+      branch: branch || null,
+      base_sha: baseSha || null,
+      cwd: cwd || worktreePath || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd: cwd || worktreePath,
+    event: "WorktreeCreate",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * WorktreeRemove settings hooks (observe + context injection). Fired when a
+ * `cc agent --worktree` session finishes and its worktree is torn down (or when
+ * a `keep` decision leaves it in place — `removed` distinguishes the two) — a
+ * hook can react (unregister the worktree, prune a per-branch cache, notify CI).
+ * Matcher target is the branch name. Observe-only: teardown already happened, so
+ * a `block` decision is ignored and only emitted context is returned. No-op
+ * (byte-unchanged) without a registered WorktreeRemove hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runWorktreeRemoveHooks(
+  settingsHooks,
+  { worktreePath, branch, removed, reason, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "WorktreeRemove", branch || "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const payload = withDeliveryId(
+    "WorktreeRemove",
+    {
+      hook_event_name: "WorktreeRemove",
+      worktree_path: worktreePath || null,
+      branch: branch || null,
+      removed: removed === true,
+      reason: reason || null,
+      cwd: cwd || worktreePath || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd: cwd || worktreePath,
+    event: "WorktreeRemove",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
+/**
+ * InstructionsLoaded settings hooks (observe + context injection). Fired once at
+ * session start after the project-instruction block (cc.md / CLAUDE.md / AGENTS.md
+ * hierarchy + `.claude/rules/*`) is composed into the system prompt — a hook can
+ * react to WHICH instruction files are authoritative this session (audit them,
+ * warn on an unexpected local override, load a companion tool config). The
+ * caller passes the EXACT loaded set; this producer trims each entry to
+ * `{path, scope, truncated}` (never the file CONTENT — a hook that wants content
+ * reads the path). Observe-only: instructions are already loaded, so a `block`
+ * decision is ignored and only emitted context is returned. No-op (byte-unchanged)
+ * without a registered InstructionsLoaded hook.
+ * @returns {{ additionalContext:string|null }}
+ */
+function runInstructionsLoadedHooks(
+  settingsHooks,
+  { files, cwd, sessionId } = {},
+) {
+  if (!settingsHooks) return { additionalContext: null };
+  const matched = collectHooks(settingsHooks, "InstructionsLoaded", "");
+  const { sync } = partitionAsyncHooks(matched);
+  if (sync.length === 0) return { additionalContext: null };
+  const list = Array.isArray(files) ? files : [];
+  const payload = withDeliveryId(
+    "InstructionsLoaded",
+    {
+      hook_event_name: "InstructionsLoaded",
+      files: list.map((f) => ({
+        path: f?.path || null,
+        scope: f?.scope || null,
+        truncated: f?.truncated === true,
+      })),
+      count: list.length,
+      cwd: cwd || null,
+      session_id: sessionId || null,
+    },
+    { sessionId },
+  );
+  const outcome = runHooks(sync, payload, {
+    cwd,
+    event: "InstructionsLoaded",
+  });
+  return { additionalContext: aggregateContext(outcome.results) };
+}
+
 /**
  * Generic observe-only fire (SessionEnd / Stop / PreCompact). Returns the raw
  * runHooks outcome so callers can read a block reason; never gates flow here.
@@ -190,7 +351,7 @@ function runObserveHooks(
   settingsHooks,
   event,
   payload = {},
-  { cwd, matchTarget } = {},
+  { cwd, matchTarget, traceId, parentId } = {},
 ) {
   if (!settingsHooks) return { decision: "continue", results: [] };
   const matched = collectHooks(settingsHooks, event, matchTarget || "");
@@ -198,14 +359,23 @@ function runObserveHooks(
   if (sync.length === 0) return { decision: "continue", results: [] };
   return runHooks(
     sync,
-    withDeliveryId(event, { hook_event_name: event, cwd, ...payload }),
+    withDeliveryId(
+      event,
+      { hook_event_name: event, cwd, ...payload },
+      { traceId, parentId },
+    ),
     { cwd, event },
   );
 }
 
 module.exports = {
+  withDeliveryId,
   runUserPromptSubmitHooks,
   runSessionStartHooks,
+  runCwdChangedHooks,
+  runWorktreeCreateHooks,
+  runWorktreeRemoveHooks,
+  runInstructionsLoadedHooks,
   runObserveHooks,
   aggregateContext,
   partitionAsyncHooks,

package/src/lib/settings-hooks.cjs

@@ -49,6 +49,10 @@ const HOOK_EVENTS = Object.freeze([
   "PreCompact",
   "Notification",
   "PermissionRequest",
+  "CwdChanged",
+  "WorktreeCreate",
+  "WorktreeRemove",
+  "InstructionsLoaded",
 ]);
 
 /**

package/src/lib/shell-approval.js

@@ -24,6 +24,13 @@ import {
   APPROVAL_RISK as RISK,
   APPROVAL_DECISION as DECISION,
 } from "@chainlesschain/session-core";
+import {
+  classifyCodeAcquisition,
+  hasGlobalInstall,
+  applyRiskFloor,
+  recordInstallCommandAudit,
+  resolveInstallPolicy,
+} from "./install-command-policy.js";
 
 export const SHELL_TO_RISK = {
   allow: RISK.LOW,
@@ -37,13 +44,49 @@ export async function evaluateShellCommandWithApproval({
   sessionId = null,
   approvalGate = null,
   shellPolicyOptions = {},
+  installPolicy = null,
 } = {}) {
   const shellPolicy = sharedShellPolicy.evaluateShellCommandPolicy(
     command,
     shellPolicyOptions,
   );
 
-  const riskLevel = SHELL_TO_RISK[shellPolicy.decision] || RISK.MEDIUM;
+  let riskLevel = SHELL_TO_RISK[shellPolicy.decision] || RISK.MEDIUM;
+
+  // Unified install-command classification (OPT-IN via installPolicy). A package
+  // install (npm/pip/winget/brew/…) fetches and runs third-party code, so it is
+  // a distinct, auditable permission type regardless of which tool does it. When
+  // a riskFloor is configured it RAISES (never lowers) the risk before gating;
+  // audit records the attempt. Absent/disabled → nothing runs, byte-unchanged.
+  // Explicit policy wins; otherwise self-activate from env (CC_INSTALL_AUDIT /
+  // CC_INSTALL_RISK_FLOOR) so the real run_shell path picks it up with no extra
+  // wiring. Both unset → disabled → the block below is skipped, byte-unchanged.
+  const effectiveInstallPolicy =
+    installPolicy || resolveInstallPolicy({ env: process.env });
+  let install = null;
+  if (effectiveInstallPolicy && effectiveInstallPolicy.enabled) {
+    const cls = classifyCodeAcquisition(command);
+    if (cls.flagged) {
+      install = cls;
+      if (effectiveInstallPolicy.riskFloor) {
+        riskLevel = applyRiskFloor(riskLevel, effectiveInstallPolicy.riskFloor);
+      }
+      if (effectiveInstallPolicy.audit) {
+        recordInstallCommandAudit(
+          {
+            command,
+            shellDecision: shellPolicy.decision,
+            riskLevel,
+            installs: cls.installs,
+            remoteExec: cls.remoteExec,
+            global: hasGlobalInstall(cls),
+            sessionId,
+          },
+          effectiveInstallPolicy.auditOpts || {},
+        );
+      }
+    }
+  }
 
   // Hard-blocked rules bypass the gate entirely — the gate tier cannot
   // up-authorize them.
@@ -56,6 +99,7 @@ export async function evaluateShellCommandWithApproval({
       shellPolicy,
       riskLevel,
       policy: null,
+      install,
     };
   }
 
@@ -69,6 +113,7 @@ export async function evaluateShellCommandWithApproval({
       shellPolicy,
       riskLevel,
       policy: null,
+      install,
     };
   }
 
@@ -87,6 +132,7 @@ export async function evaluateShellCommandWithApproval({
     shellPolicy,
     riskLevel,
     policy: gateResult.policy,
+    install,
     // Explainability passthrough (autoMode.decisions wrapper attaches these):
     // which gate rule fired and why — surfaced in the permission chain.
     gateReason: gateResult.reason ?? null,

package/src/lib/sub-agent-context.js

@@ -87,6 +87,10 @@ export class SubAgentContext {
     // restricts run_skill/list_skills in this context's loop to those skills.
     this.skillAllowlist =
       options.skillAllowlist != null ? options.skillAllowlist : null;
+    // Hook-envelope tracing: the spawning run's id — this child loop stamps it
+    // as parent_id on every settings-hook payload it fires (its own runId
+    // becomes the trace_id). null → top-level semantics (no parent).
+    this._hookParentTraceId = options.hookParentTraceId || null;
     this.cwd = options.cwd || process.cwd();
     this.status = "active";
     this.result = null;
@@ -98,6 +102,10 @@ export class SubAgentContext {
     this._worktreePath = null;
     this._worktreeBranch = null;
     this._repoDir = this.cwd;
+    // Optional worktree creation options (large-monorepo): { sparsePaths,
+    // symlinkDirectories } — only materialize the needed packages and reuse
+    // approved dep dirs. null → full checkout (byte-identical default).
+    this._worktreeOptions = options.worktreeOptions || null;
 
     // ── Isolated state ──────────────────────────────────────────────
     // Independent message history — never shared with parent
@@ -254,6 +262,7 @@ export class SubAgentContext {
           this.cwd = wtPath;
           return this._runCore(userPrompt, loopOptions);
         },
+        this._worktreeOptions || {},
       );
 
       // Annotate result with worktree info + diff preview
@@ -328,6 +337,10 @@ export class SubAgentContext {
       subAgentContract: this.subAgentContract,
       // Skill allow-list restricting run_skill/list_skills in this loop.
       skillAllowlist: this.skillAllowlist,
+      // Parent trace for hook envelopes (absent → key omitted, no parent_id).
+      ...(this._hookParentTraceId
+        ? { hookParentTraceId: this._hookParentTraceId }
+        : {}),
       ...loopOptions,
     };
     if (this.iterationBudget) {

package/src/repl/add-dir.js

@@ -61,10 +61,68 @@ export function resolveAddDir(input, { cwd, existing = [], deps } = {}) {
  */
 export function formatAddDirRoots(cwd, extraRoots) {
   const extras = Array.isArray(extraRoots) ? extraRoots : [];
-  const lines = [`Working roots (${1 + extras.length}):`, `  ${cwd}  (primary)`];
+  const lines = [
+    `Working roots (${1 + extras.length}):`,
+    `  ${cwd}  (primary)`,
+  ];
   for (const r of extras) lines.push(`  ${r}`);
   if (extras.length === 0) {
     lines.push("  (no extra roots — add one with /add-dir <dir>)");
   }
   return lines.join("\n");
 }
+
+/**
+ * The full workspace root list a session advertises to MCP servers (`roots/list`):
+ * the primary cwd first, then each extra `--add-dir` / `/add-dir` root, all
+ * resolved absolute and de-duplicated (the primary is dropped from the extras if
+ * a caller re-added it). Pure. Mirrors what the system prompt advertises so an
+ * MCP server sees the same roots the model does.
+ *
+ * @param {string} cwd            primary working directory
+ * @param {string[]} extraRoots   additional roots
+ * @returns {string[]}            deduped absolute dirs, primary first
+ */
+export function workspaceRootDirs(cwd, extraRoots) {
+  const primary = nodePath.resolve(cwd);
+  const out = [primary];
+  const seen = new Set([primary]);
+  for (const r of Array.isArray(extraRoots) ? extraRoots : []) {
+    if (!r) continue;
+    const abs = nodePath.resolve(cwd, String(r));
+    if (seen.has(abs)) continue;
+    seen.add(abs);
+    out.push(abs);
+  }
+  return out;
+}
+
+/**
+ * Best-effort broadcast of a changed workspace-root list to every connected MCP
+ * client (via `client.setRoots(dirs)`, which advertises the new list AND fires
+ * `notifications/roots/list_changed` only when it actually changed). Skips
+ * nullish/duplicate clients and any without `setRoots`; a failing client never
+ * disturbs the others or the caller. Returns the number of clients notified.
+ * Claude-Code 2.1.203 roots-change parity for the `/add-dir` (and startup
+ * `--add-dir`) vector, mirroring what `/cd` already does via
+ * `notifyRootsListChanged`.
+ *
+ * @param {Array<object|null|undefined>} clients   MCP clients (may repeat/null)
+ * @param {string[]} dirs                           absolute root dirs
+ * @returns {number}
+ */
+export function notifyMcpRootsChanged(clients, dirs) {
+  let notified = 0;
+  const seen = new Set();
+  for (const c of Array.isArray(clients) ? clients : []) {
+    if (!c || seen.has(c) || typeof c.setRoots !== "function") continue;
+    seen.add(c);
+    try {
+      c.setRoots(dirs);
+      notified += 1;
+    } catch {
+      /* best-effort — one server's failure must not block the rest */
+    }
+  }
+  return notified;
+}