@cjhyy/code-shell-core 0.8.13 → 0.9.0

package/dist/tool-system/builtin/install-capability.js

@@ -28,6 +28,7 @@ import { resolveExecutable } from "../../utils/exec.js";
 const SAFE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
 const SAFE_PLUGIN_SEGMENT_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$/;
 const SAFE_SKILL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const SAFE_OVERRIDE_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,99}$/;
 const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]{0,127}$/;
 const HEADER_NAME_RE = /^[!#$%&'*+.^_`|~0-9A-Za-z-]{1,128}$/;
 const MCP_TOOL_NAME_RE = /^[^\s\u0000-\u001F\u007F]{1,256}$/;
@@ -338,10 +339,13 @@ function isSafeRemoteUrl(raw) {
         return false;
     return ["localhost", "127.0.0.1", "::1", "[::1]"].includes(url.hostname.toLowerCase());
 }
-async function installMarketplacePlugin(args, deps) {
+async function installMarketplacePlugin(args, ctx, deps) {
     if (args.scope !== undefined && args.scope !== "user") {
         return "Error: marketplace plugins currently install at user scope; omit scope or use scope='user'.";
     }
+    if (ctx?.settingsScope !== "full") {
+        return "Error: this host isolates user settings; marketplace plugins cannot be installed.";
+    }
     const plugin = safePluginSegment(args.plugin);
     const marketplace = safePluginSegment(args.marketplace);
     if (!plugin)
@@ -440,6 +444,9 @@ async function mutateMarketplacePlugin(args, ctx, deps) {
     if (!deps.listInstalled().some((candidate) => candidate.key === installKey)) {
         return `Error: plugin ${installKey} is not installed.`;
     }
+    if ((action === "update" || action === "uninstall") && ctx?.settingsScope !== "full") {
+        return "Error: this host isolates user settings; marketplace plugins cannot be changed.";
+    }
     if (action === "update") {
         const refreshed = await deps.refreshMarketplace(marketplace);
         if (!refreshed.ok) {
@@ -474,12 +481,15 @@ async function mutateMarketplacePlugin(args, ctx, deps) {
     if (args.scope !== undefined && args.scope !== "project" && args.scope !== "user") {
         return "Error: plugin enable/disable scope must be `project` or `user`.";
     }
-    if (scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; use project scope.";
     }
     const manager = deps.makeSettingsManager(cwd, scope === "user" ? "full" : "project");
     const enabled = action === "enable";
     if (scope === "project") {
+        if (!SAFE_OVERRIDE_NAME_RE.test(plugin)) {
+            return "Error: project-scoped plugin overrides do not support dots in plugin names; use user scope.";
+        }
         manager.saveProjectSetting(`capabilityOverrides.plugins.${plugin}`, enabled ? "on" : "off", cwd);
     }
     else {
@@ -670,12 +680,16 @@ async function mutateProjectSkills(args, ctx, deps) {
     if (args.scope !== undefined && args.scope !== "project" && args.scope !== "user") {
         return "Error: Skill enable/disable scope must be `project` or `user`.";
     }
-    if (scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; use project scope.";
     }
     const manager = deps.makeSettingsManager(cwd, scope === "user" ? "full" : "project");
     const enabled = action === "enable";
     if (scope === "project") {
+        const unsafe = skills.filter((skill) => !SAFE_OVERRIDE_NAME_RE.test(skill));
+        if (unsafe.length > 0) {
+            return `Error: project-scoped Skill overrides do not support dots in names: ${unsafe.join(", ")}.`;
+        }
         for (const skill of skills) {
             manager.saveProjectSetting(`capabilityOverrides.skills.${skill}`, enabled ? "on" : "off", cwd);
         }
@@ -806,7 +820,7 @@ async function installMcpServer(args, ctx, deps) {
     if (!resolved.ok)
         return `Error: ${resolved.error}`;
     const scope = resolved.scope;
-    if (scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; install the MCP server at local or project scope.";
     }
     const built = buildMcpConfig(args);
@@ -927,7 +941,7 @@ function mcpDetailLines(name, scope, config) {
 }
 function listMcpServers(ctx, deps) {
     const cwd = ctx?.cwd ?? process.cwd();
-    const full = !ctx?.settingsScope || ctx.settingsScope === "full";
+    const full = ctx?.settingsScope === "full";
     const manager = deps.makeSettingsManager(cwd, full ? "full" : "project");
     const scopes = full
         ? ["local", "project", "user"]
@@ -953,7 +967,7 @@ function inspectMcpServer(args, ctx, deps) {
     const resolved = mcpScope(args);
     if (!resolved.ok)
         return `Error: ${resolved.error}`;
-    if (resolved.scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (resolved.scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; user MCP configuration is unavailable.";
     }
     const manager = deps.makeSettingsManager(cwd, resolved.scope === "user" ? "full" : "project");
@@ -980,7 +994,7 @@ async function mutateMcpServer(args, ctx, deps) {
     const resolved = mcpScope(args);
     if (!resolved.ok)
         return `Error: ${resolved.error}`;
-    if (resolved.scope === "user" && ctx?.settingsScope && ctx.settingsScope !== "full") {
+    if (resolved.scope === "user" && ctx?.settingsScope !== "full") {
         return "Error: this host isolates user settings; use local or project scope.";
     }
     const manager = deps.makeSettingsManager(cwd, resolved.scope === "user" ? "full" : "project");
@@ -1044,7 +1058,7 @@ export async function installCapabilityWithDeps(args, ctx, deps) {
     }
     if (action === "install") {
         if (args.kind === "plugin")
-            return installMarketplacePlugin(args, deps);
+            return installMarketplacePlugin(args, ctx, deps);
         if (args.kind === "skill")
             return installGithubSkills(args, ctx, deps);
         return installMcpServer(args, ctx, deps);

package/dist/tool-system/builtin/settings-changed.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Process-host invalidation bridge for built-ins that persist settings-like
+ * resources outside the renderer. Desktop wires one sink that forwards the
+ * existing agent/settingsChanged notification; headless hosts may leave it
+ * unset and pick the change up on their next settings load.
+ */
+export type SettingsChangedSink = () => void;
+export declare function setSettingsChangedSink(sink: SettingsChangedSink | null): void;
+export declare function notifySettingsChanged(): void;

package/dist/tool-system/builtin/settings-changed.js

@@ -0,0 +1,18 @@
+/**
+ * Process-host invalidation bridge for built-ins that persist settings-like
+ * resources outside the renderer. Desktop wires one sink that forwards the
+ * existing agent/settingsChanged notification; headless hosts may leave it
+ * unset and pick the change up on their next settings load.
+ */
+let settingsChangedSink = null;
+export function setSettingsChangedSink(sink) {
+    settingsChangedSink = sink;
+}
+export function notifySettingsChanged() {
+    try {
+        settingsChangedSink?.();
+    }
+    catch {
+        // Persistence already succeeded. Host invalidation is best-effort.
+    }
+}

package/dist/tool-system/builtin/write.js

@@ -28,14 +28,16 @@ export async function writeTool(args, ctx) {
     const cwd = ctx?.cwd ?? process.cwd();
     const filePath = isAbsolute(rawPath) ? rawPath : resolve(cwd, rawPath);
     try {
-        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd);
-        const beforeMkdir = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        const roots = ctx?.workspace?.roots.map((root) => root.path);
+        const digest = ctx?.workspace?.rootsDigest;
+        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd, roots, digest);
+        const beforeMkdir = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeMkdir)
             return { ok: false, error: beforeMkdir.error };
         await mkdir(dirname(beforeMkdir.resolvedPath), { recursive: true });
         // mkdir may have crossed an existing symlink in a missing parent chain;
         // resolve again immediately before opening the final file.
-        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath);
+        const beforeWrite = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeWrite)
             return { ok: false, error: beforeWrite.error };
         await writeFileNoFollow(beforeWrite.resolvedPath, content);

package/dist/tool-system/context.d.ts

@@ -189,6 +189,7 @@ export interface SubAgentSpawnResult {
  */
 export interface ToolVisibilityContext {
     cwd: string;
+    workspace?: import("../workspace/workspace-context.js").WorkspaceContext;
     hasGoal: boolean;
     /** Resolved Session identity for per-session extension-tool visibility. */
     sessionId?: string;
@@ -227,10 +228,16 @@ export interface ToolContext {
     cwd: string;
     /**
      * True when this call belongs to an external Agent Runtime rather than the
-     * native Engine loop. Async handoff tools use this to keep their result on
-     * the current turn instead of queueing a wake-up only the Engine can consume.
+     * native Engine loop.
      */
     externalRuntime?: boolean;
+    /**
+     * The external-runtime host can route notificationQueue completions back into
+     * this business Session as an injected continuation turn. Async tools must
+     * require this capability before detaching work: `externalRuntime` alone says
+     * who owns the turn, not whether anybody can deliver a later result.
+     */
+    externalRuntimeBackgroundDelivery?: boolean;
     /**
      * Active digital-human profile's portable memory root. Present only when
      * the resolved WorkspaceProfile enables portableMemory for this run.
@@ -456,7 +463,9 @@ export interface ToolContext {
      * switcher. Undefined outside hosts that can switch this conversation's
      * session workspace.
      */
-    workspace?: import("./workspace-bridge.js").WorkspaceBridge;
+    workspaceBridge?: import("./workspace-bridge.js").WorkspaceBridge;
+    /** Immutable roots authorized for this run. */
+    workspace?: import("../workspace/workspace-context.js").WorkspaceContext;
     /** Host panel discovery/focus bridge. Undefined in non-Desktop/headless engines. */
     panels?: import("./panel-bridge.js").PanelHostBridge;
     /**

package/dist/tool-system/executor.js

@@ -319,7 +319,7 @@ export class ToolExecutor {
             const target = isAbsolutePath(raw) ? raw : resolvePath(this.toolCtx.cwd, raw);
             call = {
                 ...call,
-                args: attachFinalWritePathSnapshot(call.args, target, this.toolCtx.cwd),
+                args: attachFinalWritePathSnapshot(call.args, target, this.toolCtx.cwd, this.toolCtx.workspace?.roots.map((root) => root.path), this.toolCtx.workspace?.rootsDigest),
             };
         }
         const pathPolicyError = await this.enforceDeclaredPathPolicy(toolDef, call.args);

package/dist/tool-system/path-policy.d.ts

@@ -42,10 +42,14 @@ export interface PathClassification {
     reason: string;
     /** Resolved absolute path (with symlinks followed when possible). */
     resolvedPath: string;
+    /** Canonical workspace root containing resolvedPath, when one matched. */
+    matchedRoot?: string;
 }
 export interface ClassifyOptions {
     /** Absolute path of the active workspace (Engine.cwd). */
     workspaceRoot: string;
+    /** Complete authorized root set. Omitted preserves legacy single-root behavior. */
+    workspaceRoots?: readonly string[];
     /** "read" or "write" — different defaults for sensitive paths. */
     operation: PathOperation;
 }
@@ -53,20 +57,24 @@ export interface FinalWritePathSnapshot {
     resolvedPath: string;
     workspacePath: string;
     insideWorkspace: boolean;
+    matchedRoot?: string;
+    rootsDigest?: string;
 }
 export type PathApprovalScope = "once" | "session" | "project";
 /** Test seam: clear the in-memory session grants. */
 export declare function _resetSessionPathGrants(): void;
 export declare function openSessionPathApprovals(sessionId: string): void;
 export declare function clearSessionPathApprovals(sessionId: string): void;
+/** Revoke only grants that point into a root removed from a live project. */
+export declare function clearSessionPathApprovalsUnderRoot(sessionId: string, root: string): void;
 /**
  * Capture the concrete target approved by the executor's first path-policy
  * pass. The snapshot is carried on the internal args object via a symbol, so
  * it cannot collide with an LLM-supplied schema property or leak into logs.
  */
-export declare function attachFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string): Record<string, unknown>;
-export declare function getFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string): FinalWritePathSnapshot;
-export declare function revalidateFinalWritePath(filePath: string, workspaceRoot: string, approved: FinalWritePathSnapshot): {
+export declare function attachFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string, workspaceRoots?: readonly string[], rootsDigest?: string): Record<string, unknown>;
+export declare function getFinalWritePathSnapshot(args: Record<string, unknown>, filePath: string, workspaceRoot: string, workspaceRoots?: readonly string[], rootsDigest?: string): FinalWritePathSnapshot;
+export declare function revalidateFinalWritePath(filePath: string, workspaceRoot: string, approved: FinalWritePathSnapshot, workspaceRoots?: readonly string[], rootsDigest?: string): {
     resolvedPath: string;
 } | {
     error: string;

package/dist/tool-system/path-policy.js

@@ -33,8 +33,9 @@ import { constants, realpathSync, existsSync, readFileSync, writeFileSync, mkdir
 import { open } from "node:fs/promises";
 import { homedir } from "node:os";
 import { randomUUID } from "node:crypto";
-import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from "node:path";
+import { dirname, join, relative, sep } from "node:path";
 import { readInstalledPlugins } from "../plugins/installedPlugins.js";
+import { canonicalPath } from "../workspace/canonical-key.js";
 const FINAL_WRITE_PATH_SNAPSHOT = Symbol("codeshell.finalWritePathSnapshot");
 /**
  * Default sensitive path patterns. These are evaluated AFTER home-expansion
@@ -291,6 +292,20 @@ export function clearSessionPathApprovals(sessionId) {
     closedPathApprovalSessions.add(sessionId);
     askChains.delete(sessionId);
 }
+/** Revoke only grants that point into a root removed from a live project. */
+export function clearSessionPathApprovalsUnderRoot(sessionId, root) {
+    const grants = sessionPathGrants.get(sessionId);
+    if (!grants)
+        return;
+    const canonicalRoot = safeRealpath(root);
+    for (const grant of [...grants]) {
+        const grantPath = safeRealpath(grant.prefix);
+        if (isInsideDir(grantPath, canonicalRoot))
+            grants.delete(grant);
+    }
+    if (grants.size === 0)
+        sessionPathGrants.delete(sessionId);
+}
 /**
  * Best-effort resolution. realpath fails when the path doesn't exist yet —
  * the common case for Write creating a new file. We walk up to the nearest
@@ -303,47 +318,28 @@ export function clearSessionPathApprovals(sessionId) {
  * would be misclassified as outside-workspace.
  */
 function safeRealpath(p) {
-    const abs = isAbsolute(p) ? p : resolvePath(process.cwd(), p);
-    // Walk up to the nearest existing ancestor.
-    let candidate = abs;
-    const segments = [];
-    // Cap the walk so a pathological input can't spin forever.
-    for (let i = 0; i < 64; i++) {
-        try {
-            const resolved = realpathSync(candidate);
-            if (segments.length === 0)
-                return resolved;
-            return resolvePath(resolved, ...segments.reverse());
-        }
-        catch {
-            const parent = dirname(candidate);
-            if (parent === candidate) {
-                // Reached root without finding anything that exists — return the
-                // original absolute form so the caller still has a usable path.
-                return abs;
-            }
-            segments.push(candidate.slice(parent.length + (parent.endsWith(sep) ? 0 : 1)));
-            candidate = parent;
-        }
-    }
-    return abs;
+    return canonicalPath(p);
 }
 /**
  * Capture the concrete target approved by the executor's first path-policy
  * pass. The snapshot is carried on the internal args object via a symbol, so
  * it cannot collide with an LLM-supplied schema property or leak into logs.
  */
-export function attachFinalWritePathSnapshot(args, filePath, workspaceRoot) {
+export function attachFinalWritePathSnapshot(args, filePath, workspaceRoot, workspaceRoots, rootsDigest) {
     const resolvedPath = safeRealpath(filePath);
     const workspacePath = safeRealpath(workspaceRoot);
+    const roots = (workspaceRoots?.length ? workspaceRoots : [workspaceRoot]).map(safeRealpath);
+    const matchedRoot = roots.find((root) => isInsideDir(resolvedPath, root));
     const snapshot = {
         resolvedPath,
         workspacePath,
-        insideWorkspace: isInsideDir(resolvedPath, workspacePath),
+        insideWorkspace: matchedRoot !== undefined,
+        matchedRoot,
+        rootsDigest,
     };
     return { ...args, [FINAL_WRITE_PATH_SNAPSHOT]: snapshot };
 }
-export function getFinalWritePathSnapshot(args, filePath, workspaceRoot) {
+export function getFinalWritePathSnapshot(args, filePath, workspaceRoot, workspaceRoots, rootsDigest) {
     const carried = args[FINAL_WRITE_PATH_SNAPSHOT];
     if (carried && typeof carried === "object") {
         return carried;
@@ -353,19 +349,32 @@ export function getFinalWritePathSnapshot(args, filePath, workspaceRoot) {
     // read-to-write interval with a second check before its writeFile.
     const resolvedPath = safeRealpath(filePath);
     const workspacePath = safeRealpath(workspaceRoot);
+    const roots = (workspaceRoots?.length ? workspaceRoots : [workspaceRoot]).map(safeRealpath);
+    const matchedRoot = roots.find((root) => isInsideDir(resolvedPath, root));
     return {
         resolvedPath,
         workspacePath,
-        insideWorkspace: isInsideDir(resolvedPath, workspacePath),
+        insideWorkspace: matchedRoot !== undefined,
+        matchedRoot,
+        rootsDigest,
     };
 }
-export function revalidateFinalWritePath(filePath, workspaceRoot, approved) {
+export function revalidateFinalWritePath(filePath, workspaceRoot, approved, workspaceRoots, rootsDigest) {
     const currentPath = safeRealpath(filePath);
     const currentWorkspace = safeRealpath(workspaceRoot);
     const sameTarget = normPath(currentPath) === normPath(approved.resolvedPath);
     const sameWorkspace = normPath(currentWorkspace) === normPath(approved.workspacePath);
-    const crossedWorkspaceBoundary = approved.insideWorkspace && !isInsideDir(currentPath, currentWorkspace);
-    if (crossedWorkspaceBoundary || !sameTarget || !sameWorkspace) {
+    const currentRoots = (workspaceRoots?.length ? workspaceRoots : [workspaceRoot]).map(safeRealpath);
+    const currentMatchedRoot = currentRoots.find((root) => isInsideDir(currentPath, root));
+    const crossedWorkspaceBoundary = approved.insideWorkspace && currentMatchedRoot === undefined;
+    const changedMatchedRoot = approved.matchedRoot !== undefined &&
+        normPath(currentMatchedRoot ?? "") !== normPath(approved.matchedRoot);
+    const changedRootsDigest = approved.rootsDigest !== undefined && rootsDigest !== approved.rootsDigest;
+    if (crossedWorkspaceBoundary ||
+        changedMatchedRoot ||
+        changedRootsDigest ||
+        !sameTarget ||
+        !sameWorkspace) {
         const reason = crossedWorkspaceBoundary
             ? "final write path resolved outside the workspace after approval"
             : "final write path changed after approval";
@@ -620,11 +629,13 @@ export function classifyPath(rawPath, opts) {
     }
     const expanded = expandTilde(rawPath);
     const resolved = safeRealpath(expanded);
-    const workspace = safeRealpath(opts.workspaceRoot);
+    const workspaceRoots = opts.workspaceRoots?.length ? opts.workspaceRoots : [opts.workspaceRoot];
+    const workspaces = workspaceRoots.map((root) => safeRealpath(root));
     const sensitiveDir = matchSensitiveDir(resolved);
     const sensitiveFile = matchSensitiveFile(resolved);
     const sensitiveLabel = sensitiveDir ?? sensitiveFile;
-    const insideWorkspace = isInsideDir(resolved, workspace);
+    const matchedRoot = workspaces.find((workspace) => isInsideDir(resolved, workspace));
+    const insideWorkspace = matchedRoot !== undefined;
     // Registered Skill resources are managed runtime inputs. Their SKILL.md is
     // already readable through the Skill builtin; allow its contained reference
     // files through the ordinary Read tool as well. A credential-shaped basename
@@ -675,7 +686,12 @@ export function classifyPath(rawPath, opts) {
         };
     }
     if (insideWorkspace) {
-        return { decision: "allow", reason: "inside workspace", resolvedPath: resolved };
+        return {
+            decision: "allow",
+            reason: "inside workspace",
+            resolvedPath: resolved,
+            matchedRoot,
+        };
     }
     // Outside workspace: ask for both read and write. The conservative bias
     // matches the plan's leaning answer to Q1 — ask on sensitive reads, deny
@@ -732,7 +748,11 @@ export async function enforcePathPolicyWithApproval(filePath, operation, ctx) {
     // who chose full access still got prompted for project-external reads.
     if (ctx.permissionMode === "bypassPermissions")
         return null;
-    const c = classifyPath(filePath, { workspaceRoot: ctx.cwd, operation });
+    const c = classifyPath(filePath, {
+        workspaceRoot: ctx.cwd,
+        workspaceRoots: ctx.workspace?.roots.map((root) => root.path),
+        operation,
+    });
     if (c.decision === "allow")
         return null;
     if (c.decision === "deny") {

package/dist/types.d.ts

@@ -188,6 +188,10 @@ export interface SessionWorkspace {
         createdBy: "codeshell";
     };
 }
+export interface SessionProjectBinding {
+    projectId: string;
+    mainRootId: string;
+}
 export interface ContextUsageAnchor {
     promptTokens: number;
     messageCount: number;
@@ -231,6 +235,8 @@ export interface SessionState {
     cwd: string;
     /** Current main/worktree execution pointer. Absent only on legacy state.json files. */
     workspace?: SessionWorkspace;
+    /** Stable Desktop project identity. Absent on legacy/no-repo sessions. */
+    project?: SessionProjectBinding;
     startedAt: number;
     model: string;
     provider: string;
@@ -747,6 +753,11 @@ export interface ClientDefaults {
     timeout?: number;
     /** Max retry attempts for transient errors. Default 3. */
     retryMaxAttempts?: number;
+    /**
+     * Optional HTTP transport override. Primarily used by embedders and tests
+     * that need an isolated transport without mutating process-global fetch.
+     */
+    fetch?: typeof globalThis.fetch;
     /**
      * Provider-agnostic image clarity level. Drives the renderer-side
      * downscale (long-edge cap: low→~1024 / standard→~1568 / high→~2576)

package/dist/workspace/canonical-key.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Resolve a path through symlinks without requiring the leaf to exist.
+ * Missing suffixes are appended to the nearest existing realpathed ancestor.
+ */
+export declare function canonicalPath(input: string): string;
+/** Stable comparison key for project roots and workspace containment decisions. */
+export declare function canonicalKey(input: string): string;

package/dist/workspace/canonical-key.js

@@ -0,0 +1,39 @@
+import { realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, parse, resolve } from "node:path";
+const CASE_INSENSITIVE_PLATFORM = process.platform === "darwin" || process.platform === "win32";
+/**
+ * Resolve a path through symlinks without requiring the leaf to exist.
+ * Missing suffixes are appended to the nearest existing realpathed ancestor.
+ */
+export function canonicalPath(input) {
+    const absolute = isAbsolute(input) ? resolve(input) : resolve(process.cwd(), input);
+    let candidate = absolute;
+    const suffix = [];
+    for (let depth = 0; depth < 64; depth += 1) {
+        try {
+            const existing = realpathSync(candidate);
+            const joined = suffix.length > 0 ? resolve(existing, ...suffix) : resolve(existing);
+            return trimTrailingSeparators(joined);
+        }
+        catch {
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return trimTrailingSeparators(absolute);
+            suffix.unshift(basename(candidate));
+            candidate = parent;
+        }
+    }
+    return trimTrailingSeparators(absolute);
+}
+/** Stable comparison key for project roots and workspace containment decisions. */
+export function canonicalKey(input) {
+    const normalized = canonicalPath(input);
+    return CASE_INSENSITIVE_PLATFORM ? normalized.toLocaleLowerCase("en-US") : normalized;
+}
+function trimTrailingSeparators(input) {
+    const root = parse(input).root;
+    let end = input.length;
+    while (end > root.length && (input[end - 1] === "/" || input[end - 1] === "\\"))
+        end -= 1;
+    return input.slice(0, end);
+}

package/dist/workspace/workspace-context.d.ts

@@ -0,0 +1,26 @@
+import { canonicalKey, canonicalPath } from "./canonical-key.js";
+export { canonicalKey, canonicalPath };
+export type ProjectId = string;
+export type ProjectRootId = string;
+export interface ProjectRootContext {
+    id: ProjectRootId;
+    path: string;
+    role: "primary" | "secondary";
+}
+export interface WorkspaceContext {
+    version: 1;
+    projectId: ProjectId;
+    projectRevision: number;
+    sessionMainRootId: ProjectRootId;
+    roots: ProjectRootContext[];
+    rootsDigest: string;
+}
+export type WorkspaceContextInput = Omit<WorkspaceContext, "version" | "rootsDigest">;
+export declare function computeWorkspaceRootsDigest(roots: readonly ProjectRootContext[]): string;
+export declare function createWorkspaceContext(input: WorkspaceContextInput): WorkspaceContext;
+export declare function validateWorkspaceContext(value: unknown): WorkspaceContext;
+/** Compatibility context for callers that only possess one cwd. It is never persisted as a binding. */
+export declare function legacySingleRootWorkspace(cwd: string): WorkspaceContext;
+export declare function workspacePrimaryRoot(context: WorkspaceContext): ProjectRootContext;
+/** Paths present in the previous run-scoped root set but absent from the next one. */
+export declare function removedWorkspaceRootPaths(previous: Pick<WorkspaceContext, "roots">, next: Pick<WorkspaceContext, "roots">): string[];

package/dist/workspace/workspace-context.js

@@ -0,0 +1,112 @@
+import { createHash } from "node:crypto";
+import { isAbsolute, relative, sep } from "node:path";
+import { canonicalKey, canonicalPath } from "./canonical-key.js";
+export { canonicalKey, canonicalPath };
+function requireIdentifier(value, label) {
+    if (typeof value !== "string" || value.length === 0 || value.length > 512) {
+        throw new Error(`invalid WorkspaceContext ${label}`);
+    }
+    return value;
+}
+function containsPath(parent, child) {
+    if (parent === child)
+        return true;
+    const rel = relative(parent, child);
+    return rel !== "" && rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+}
+export function computeWorkspaceRootsDigest(roots) {
+    const keys = roots.map((root) => canonicalKey(root.path)).sort();
+    return createHash("sha256").update(keys.join("\0"), "utf8").digest("hex");
+}
+function validateRoots(roots, sessionMainRootId) {
+    if (roots.length === 0 || roots.length > 256) {
+        throw new Error("WorkspaceContext roots must contain between 1 and 256 entries");
+    }
+    const ids = new Set();
+    const normalized = roots.map((root, index) => {
+        if (!root || typeof root !== "object") {
+            throw new Error(`invalid WorkspaceContext root at index ${index}`);
+        }
+        const id = requireIdentifier(root.id, `roots[${index}].id`);
+        if (ids.has(id))
+            throw new Error(`duplicate root id: ${id}`);
+        ids.add(id);
+        if (typeof root.path !== "string" || root.path.length === 0 || root.path.length > 16_384) {
+            throw new Error(`invalid WorkspaceContext roots[${index}].path`);
+        }
+        if (!isAbsolute(root.path)) {
+            throw new Error(`WorkspaceContext root path must be absolute: ${root.path}`);
+        }
+        if (root.role !== "primary" && root.role !== "secondary") {
+            throw new Error(`invalid WorkspaceContext roots[${index}].role`);
+        }
+        return { id, path: root.path, role: root.role };
+    });
+    const primary = normalized.filter((root) => root.role === "primary");
+    if (primary.length !== 1 || primary[0]?.id !== sessionMainRootId) {
+        throw new Error("WorkspaceContext must have exactly one primary matching sessionMainRootId");
+    }
+    const keys = normalized.map((root) => canonicalKey(root.path));
+    for (let left = 0; left < keys.length; left += 1) {
+        for (let right = left + 1; right < keys.length; right += 1) {
+            if (containsPath(keys[left], keys[right]) || containsPath(keys[right], keys[left])) {
+                throw new Error(`WorkspaceContext roots overlap: ${normalized[left].path} and ${normalized[right].path}`);
+            }
+        }
+    }
+    return normalized;
+}
+export function createWorkspaceContext(input) {
+    const projectId = requireIdentifier(input.projectId, "projectId");
+    const sessionMainRootId = requireIdentifier(input.sessionMainRootId, "sessionMainRootId");
+    if (!Number.isSafeInteger(input.projectRevision) || input.projectRevision < 1) {
+        throw new Error("invalid WorkspaceContext projectRevision");
+    }
+    const roots = validateRoots(input.roots, sessionMainRootId);
+    return {
+        version: 1,
+        projectId,
+        projectRevision: input.projectRevision,
+        sessionMainRootId,
+        roots,
+        rootsDigest: computeWorkspaceRootsDigest(roots),
+    };
+}
+export function validateWorkspaceContext(value) {
+    if (!value || typeof value !== "object")
+        throw new Error("invalid WorkspaceContext");
+    const candidate = value;
+    if (candidate.version !== 1)
+        throw new Error("invalid WorkspaceContext version");
+    const created = createWorkspaceContext({
+        projectId: candidate.projectId,
+        projectRevision: candidate.projectRevision,
+        sessionMainRootId: candidate.sessionMainRootId,
+        roots: candidate.roots,
+    });
+    if (candidate.rootsDigest !== created.rootsDigest) {
+        throw new Error("WorkspaceContext rootsDigest does not match roots");
+    }
+    return created;
+}
+/** Compatibility context for callers that only possess one cwd. It is never persisted as a binding. */
+export function legacySingleRootWorkspace(cwd) {
+    const path = canonicalPath(cwd);
+    const keyDigest = createHash("sha256").update(canonicalKey(path), "utf8").digest("hex");
+    return createWorkspaceContext({
+        projectId: `legacy-${keyDigest}`,
+        projectRevision: 1,
+        sessionMainRootId: "legacy-root",
+        roots: [{ id: "legacy-root", path, role: "primary" }],
+    });
+}
+export function workspacePrimaryRoot(context) {
+    return context.roots.find((root) => root.id === context.sessionMainRootId);
+}
+/** Paths present in the previous run-scoped root set but absent from the next one. */
+export function removedWorkspaceRootPaths(previous, next) {
+    const nextKeys = new Set(next.roots.map((root) => canonicalKey(root.path)));
+    return previous.roots
+        .filter((root) => !nextKeys.has(canonicalKey(root.path)))
+        .map((root) => root.path);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cjhyy/code-shell-core",
-  "version": "0.8.13",
+  "version": "0.9.0",
   "description": "Core engine for code-shell — agent orchestration, tool execution, hooks, protocol. UI-agnostic.",
   "type": "module",
   "main": "./dist/index.js",