chainlesschain 0.162.165 → 0.162.167

package/src/lib/protocol-replay.js

@@ -0,0 +1,153 @@
+/**
+ * Offline protocol replay — the last open pure item of P1-9 ("离线协议回放") in
+ * docs/CLAUDE_CODE_IDE_INCREMENTAL_GAP_ANALYSIS_2026-07-13.md.
+ *
+ * [[event-seq-replay.js]] replays for TRANSPORT reliability (re-send a gap over a
+ * lossy socket). This module replays for PROTOCOL COMPAT: take a recorded
+ * stream-json session and a negotiation context (server offer × client offer) and
+ * answer two offline questions no live peer is needed for —
+ *
+ *   1. REPLAY: what would these frames look like on the wire under THIS
+ *      negotiation? (fields whose feature did not survive negotiation are
+ *      stripped, exactly as the live emitter's field-gate would strip them.)
+ *   2. AUDIT: does a recorded session OBEY a claimed negotiation, i.e. does any
+ *      frame carry a negotiable wire field the negotiation gated OFF? A vN-only
+ *      client must never receive a vN+1 field; a recording that violates that is
+ *      a compat bug this catches deterministically, offline, in CI.
+ *
+ * The set of gateable wire fields ({seq, trace_id, tool_use_id}) is projected
+ * from the ONE canonical [[capability-manifest.js]] via `toFieldGate()` — it can
+ * NOT drift from the negotiated feature list. All non-negotiable frame fields
+ * (type, content, tool name, …) always pass through untouched.
+ *
+ * PURE + deterministic: no fs / process / clock / RNG. The `digest` lets a golden
+ * recording be pinned so any change to negotiation/gating that alters wire output
+ * fails a byte/hash compare (same anti-drift philosophy as the capability doc).
+ */
+
+import { createHash } from "node:crypto";
+import {
+  negotiateProtocol,
+  applyNegotiationToGate,
+} from "./capability-negotiation.js";
+import { toFieldGate } from "./capability-manifest.js";
+
+/** Negotiable wire field names ({seq, trace_id, tool_use_id}), single-sourced. */
+export const GATEABLE_FIELDS = Object.freeze(
+  [...new Set(Object.values(toFieldGate()))].sort(),
+);
+
+/**
+ * Run negotiation and fold it into a per-field gate the replay/audit read.
+ * On an incompatible (ok:false) negotiation the gate stays empty → every gateable
+ * field is treated as OFF (fail-closed safe baseline).
+ *
+ * @param {object} params
+ * @param {object} params.server  server offer {protocolVersion,minProtocolVersion,features}
+ * @param {object|null} [params.client]  client offer, or null/undefined = legacy peer
+ * @returns {{negotiation:object, gate:object, enabledFields:string[], gatedFields:string[]}}
+ */
+export function gateFromNegotiation({ server = {}, client = null } = {}) {
+  const negotiation = negotiateProtocol(server, client ?? null);
+  const gate = applyNegotiationToGate(negotiation, {});
+  const enabledFields = GATEABLE_FIELDS.filter((f) => gate[f] === true);
+  const gatedFields = GATEABLE_FIELDS.filter((f) => gate[f] !== true);
+  return { negotiation, gate, enabledFields, gatedFields };
+}
+
+/**
+ * Strip from a single frame every gateable wire field the gate has OFF, exactly
+ * as the live emitter would; all other fields pass through in original order.
+ * Returns a shallow copy — the input frame is never mutated.
+ *
+ * @param {object} frame
+ * @param {object} gate  {seq?:boolean, trace_id?:boolean, tool_use_id?:boolean}
+ * @returns {object}
+ */
+export function replayFrame(frame, gate = {}) {
+  if (!frame || typeof frame !== "object") return frame;
+  const out = {};
+  for (const [k, v] of Object.entries(frame)) {
+    if (GATEABLE_FIELDS.includes(k) && gate[k] !== true) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Replay a recorded session under a negotiation → the frames as they'd appear on
+ * the wire (gated-off fields stripped) plus a deterministic digest.
+ *
+ * @param {object[]} frames  recorded stream-json frames
+ * @param {{server:object, client?:object|null}} ctx  negotiation context
+ * @returns {{negotiation:object, gate:object, enabledFields:string[],
+ *            gatedFields:string[], frames:object[], digest:string}}
+ */
+export function replaySession(frames, ctx = {}) {
+  const { negotiation, gate, enabledFields, gatedFields } =
+    gateFromNegotiation(ctx);
+  const emitted = (Array.isArray(frames) ? frames : []).map((f) =>
+    replayFrame(f, gate),
+  );
+  return {
+    negotiation,
+    gate,
+    enabledFields,
+    gatedFields,
+    frames: emitted,
+    digest: sessionDigest(emitted),
+  };
+}
+
+/**
+ * Audit a recorded session against a claimed negotiation WITHOUT stripping:
+ * report every frame that carries a gateable wire field the negotiation gated
+ * OFF (a forward-compat violation — a field a peer at the agreed version must not
+ * have received). Fail-closed: `ok` is true only when there are zero violations.
+ *
+ * @param {object[]} frames
+ * @param {{server:object, client?:object|null}} ctx
+ * @returns {{ok:boolean, violations:Array<{index:number, field:string, type:(string|null)}>, gate:object, gatedFields:string[]}}
+ */
+export function auditRecordedSession(frames, ctx = {}) {
+  const { gate, gatedFields } = gateFromNegotiation(ctx);
+  const violations = [];
+  (Array.isArray(frames) ? frames : []).forEach((frame, index) => {
+    if (!frame || typeof frame !== "object") return;
+    for (const field of GATEABLE_FIELDS) {
+      if (
+        gate[field] !== true &&
+        Object.prototype.hasOwnProperty.call(frame, field)
+      ) {
+        violations.push({
+          index,
+          field,
+          type: typeof frame.type === "string" ? frame.type : null,
+        });
+      }
+    }
+  });
+  return { ok: violations.length === 0, violations, gate, gatedFields };
+}
+
+/** Recursively key-sort a value so JSON.stringify is order-independent. */
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const k of Object.keys(value).sort()) out[k] = canonical(value[k]);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Deterministic sha256 over a frame sequence (key-order independent) so a golden
+ * recording can be pinned and diffed. Pure.
+ * @param {object[]} frames
+ * @returns {string} 64-hex digest
+ */
+export function sessionDigest(frames) {
+  const body = (Array.isArray(frames) ? frames : []).map(canonical);
+  return createHash("sha256").update(JSON.stringify(body)).digest("hex");
+}

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

@@ -178,6 +178,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.
@@ -206,6 +359,10 @@ function runObserveHooks(
 module.exports = {
   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/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;
+}

package/src/repl/agent-repl.js

@@ -1045,6 +1045,7 @@ export async function startAgentRepl(options = {}) {
   // `undefined` so the runtime default-on path — and CC_PROJECT_MEMORY=0 — keep
   // their existing behaviour byte-identically.
   const _leanNoProjectMemory = options.projectMemory === false;
+  let _loadedReplInstructions = null;
   let _replBaseSystem = composeSystemPrompt(
     buildSystemPrompt(process.cwd(), {
       additionalDirectories,
@@ -1054,6 +1055,9 @@ export async function startAgentRepl(options = {}) {
       systemPrompt: options.systemPrompt,
       appendSystemPrompt: options.appendSystemPrompt,
       projectMemory: _leanNoProjectMemory ? false : undefined,
+      onInstructionsLoaded: (loaded) => {
+        _loadedReplInstructions = loaded;
+      },
     },
   );
   let _activeOutputStyle = null; // { name, body }
@@ -1088,6 +1092,25 @@ export async function startAgentRepl(options = {}) {
     // best-effort — no output style
   }
 
+  // settings.json InstructionsLoaded hooks (observe-only): fire once with the
+  // exact loaded instruction file set so a hook can audit which cc.md/CLAUDE.md/
+  // AGENTS.md/rules are authoritative this session. Best-effort; no-op when
+  // project memory is off or no hook is registered.
+  if (_settingsHooks && _loadedReplInstructions) {
+    try {
+      const { runInstructionsLoadedHooks } =
+        await import("../lib/settings-hook-events.cjs");
+      const ctx = runInstructionsLoadedHooks(_settingsHooks, {
+        files: _loadedReplInstructions.files,
+        cwd: process.cwd(),
+        sessionId,
+      }).additionalContext;
+      if (ctx) messages.push({ role: "system", content: ctx });
+    } catch (_err) {
+      // best-effort
+    }
+  }
+
   // settings.json SessionStart hooks → inject session context (observe-only).
   if (_settingsHooks) {
     try {
@@ -1267,6 +1290,23 @@ export async function startAgentRepl(options = {}) {
     }
   }
 
+  // Seed connected MCP servers with the startup workspace roots when the session
+  // began with extra `--add-dir` roots — otherwise `roots/list` would only ever
+  // return the cwd until the first mid-session /add-dir. No-op (byte-unchanged)
+  // when there are no extra roots. Best-effort.
+  if (additionalDirectories.length > 0) {
+    try {
+      const { workspaceRootDirs, notifyMcpRootsChanged } =
+        await import("./add-dir.js");
+      notifyMcpRootsChanged(
+        [_adhocMcp?.mcpClient, _bundleMcpClient],
+        workspaceRootDirs(process.cwd(), additionalDirectories),
+      );
+    } catch {
+      /* best-effort — root advertisement must not block session startup */
+    }
+  }
+
   // Apply bundle approval policy to this session (after both gate and sessionId are ready)
   if (_bundleResolved?.approvalPolicy?.default && _approvalGate && sessionId) {
     try {
@@ -2382,8 +2422,12 @@ export async function startAgentRepl(options = {}) {
     if (trimmed === "/add-dir" || trimmed.startsWith("/add-dir ")) {
       const arg = trimmed.slice("/add-dir".length).trim();
       try {
-        const { resolveAddDir, formatAddDirRoots } =
-          await import("./add-dir.js");
+        const {
+          resolveAddDir,
+          formatAddDirRoots,
+          workspaceRootDirs,
+          notifyMcpRootsChanged,
+        } = await import("./add-dir.js");
         if (!arg) {
           logger.log(
             "\n" +
@@ -2417,6 +2461,14 @@ export async function startAgentRepl(options = {}) {
             messages[0].content = _activeOutputStyle
               ? `${_replBaseSystem}\n\n${_activeOutputStyle.body}`
               : _replBaseSystem;
+            // The workspace root LIST changed — advertise it to connected MCP
+            // servers and fire notifications/roots/list_changed so they re-query
+            // roots/list (Claude-Code 2.1.203 parity, same as /cd but with an
+            // explicit new root, not just a cwd-derived change).
+            notifyMcpRootsChanged(
+              [_adhocMcp?.mcpClient, _bundleMcpClient],
+              workspaceRootDirs(process.cwd(), additionalDirectories),
+            );
             logger.log(chalk.green(`Added working root: ${res.dir}`));
           }
         }
@@ -3002,9 +3054,11 @@ export async function startAgentRepl(options = {}) {
         logger.info(`cwd: ${process.cwd()}`);
       } else {
         try {
+          const oldCwd = process.cwd();
           const expanded = target.replace(/^~(?=$|[\\/])/, os.homedir());
           process.chdir(path.resolve(process.cwd(), expanded));
-          logger.log(chalk.green(`cwd → ${process.cwd()}`));
+          const newCwd = process.cwd();
+          logger.log(chalk.green(`cwd → ${newCwd}`));
           // MCP roots derive from cwd — tell connected servers to re-query
           // roots/list (Claude-Code 2.1.203 change-notification parity).
           for (const c of [_adhocMcp?.mcpClient, _bundleMcpClient]) {
@@ -3016,6 +3070,34 @@ export async function startAgentRepl(options = {}) {
               }
             }
           }
+          // CwdChanged settings hooks (lifecycle-event parity): the working dir
+          // just changed, so fire CwdChanged with old→new cwd — a hook can
+          // observe/react (re-audit the new dir's trust, reload per-dir config).
+          // Observe-only (a cwd change never gates flow); best-effort; no-op
+          // (byte-unchanged) without a registered CwdChanged hook.
+          if (_settingsHooks && oldCwd !== newCwd) {
+            try {
+              const { runCwdChangedHooks, dispatchAsyncHooks } =
+                await import("../lib/settings-hook-events.cjs");
+              const payload = { oldCwd, newCwd, sessionId };
+              runCwdChangedHooks(_settingsHooks, payload);
+              if (!_asyncHookSupervisor) {
+                const { AsyncHookSupervisor } =
+                  await import("../lib/async-hook-supervisor.cjs");
+                _asyncHookSupervisor = new AsyncHookSupervisor({
+                  persistStats: true,
+                });
+              }
+              dispatchAsyncHooks(
+                _settingsHooks,
+                "CwdChanged",
+                { old_cwd: oldCwd, cwd: newCwd, session_id: sessionId || null },
+                { cwd: newCwd, supervisor: _asyncHookSupervisor },
+              );
+            } catch {
+              /* CwdChanged firing is best-effort */
+            }
+          }
         } catch (err) {
           logger.error(`/cd failed: ${err.message}`);
         }