@cjhyy/code-shell-core 0.8.20 → 0.9.1

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

@@ -1,9 +1,9 @@
 /**
  * ConfigTool — read or update project settings.
  */
-import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-import { setDottedSetting } from "../../settings/manager.js";
+import { SettingsManager, setDottedSetting } from "../../settings/manager.js";
 import { enforcePathPolicyWithApproval } from "../path-policy.js";
 export const configToolDef = {
     name: "Config",
@@ -28,7 +28,20 @@ export const configToolDef = {
         required: ["action"],
     },
 };
+const DEFAULT_DEPS = {
+    makeSettingsManager: (cwd, scope) => new SettingsManager(cwd, scope),
+};
+/** Factory so tests can inject a SettingsManager (barrier/fake); production
+ *  uses the default instance-per-call, matching the other builtins. */
+export function makeConfigTool(deps = DEFAULT_DEPS) {
+    return async function configTool(args, ctx) {
+        return runConfigTool(args, ctx, deps);
+    };
+}
 export async function configTool(args, ctx) {
+    return runConfigTool(args, ctx, DEFAULT_DEPS);
+}
+async function runConfigTool(args, ctx, deps) {
     const action = args.action;
     const cwd = ctx?.cwd ?? process.cwd();
     const configPath = join(cwd, ".code-shell", "settings.json");
@@ -52,18 +65,18 @@ export async function configTool(args, ctx) {
             return "Error: 'key' is required for write action.";
         if (value === undefined)
             return "Error: 'value' is required for write action.";
-        // Read or create settings
-        let settings = {};
-        if (existsSync(configPath)) {
-            settings = JSON.parse(readFileSync(configPath, "utf-8"));
-        }
+        // Validate the key BEFORE touching disk, preserving the existing contract
+        // that an unsafe dotted key is rejected without creating settings.json.
+        // setDottedSetting is the same validator saveProjectSetting applies inside
+        // the lock; running it here on a throwaway object only surfaces the error.
         try {
-            setDottedSetting(settings, key, value);
+            setDottedSetting({}, key, value);
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
             return `Error: ${message}`;
         }
+        await deps.beforeWrite?.();
         // Never resurrect a deleted project root: a recursive mkdir of
         // <cwd>/.code-shell would recreate `cwd` itself as an empty shell when the
         // directory has been deleted (e.g. a stale session pointing at a removed
@@ -71,8 +84,40 @@ export async function configTool(args, ctx) {
         if (!existsSync(cwd)) {
             return `Error: project directory does not exist: ${cwd}`;
         }
-        mkdirSync(join(cwd, ".code-shell"), { recursive: true });
-        writeFileSync(configPath, JSON.stringify(settings, null, 2), "utf-8");
+        // Persist through SettingsManager rather than a hand-rolled
+        // read → modify → writeFileSync. That path had no lock and no temp+rename,
+        // so two writers that both read before either wrote each persisted their
+        // own stale snapshot and silently dropped the other's key (the class
+        // documented in utils/file-mutex.ts). saveProjectSetting re-reads inside
+        // the lock, writes atomically, and invalidates the merged cache so a
+        // following read sees this write.
+        //
+        // Side effect worth knowing about on a YAML-configured project:
+        // SettingsManager reads a sibling settings.yaml when settings.json is
+        // absent but always writes back JSON, so the first write folds the YAML
+        // content into a new settings.json and the now-shadowed YAML is left on
+        // disk. That is SettingsManager's established behaviour for every caller,
+        // and it is strictly better than what this tool used to do (write the one
+        // new key and lose the YAML content entirely) — so it is inherited
+        // deliberately rather than special-cased here.
+        //
+        // saveProjectSetting throws on a hostile state dir (a `.code-shell` that is
+        // a file or a link) and on an existing-but-unreadable settings file, where
+        // it refuses to overwrite rather than rewrite from {}. The old hand-rolled
+        // write also threw on those inputs, but let the exception escape; every
+        // other failure in this tool is reported as a string, so convert it here.
+        //
+        // Note the file mode also changed: the old writeFileSync left settings.json
+        // at the umask default (typically 0644), while SettingsManager writes 0600.
+        // settings.json can hold plaintext API keys, so owner-only is the intended
+        // posture — an existing world-readable file is tightened on its next write.
+        try {
+            deps.makeSettingsManager(cwd, "project").saveProjectSetting(key, value, cwd);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return `Error: ${message}`;
+        }
         return `Updated ${key} = ${JSON.stringify(value)}`;
     }
     return `Unknown action: ${action}. Use 'read' or 'write'.`;

package/dist/tool-system/builtin/cron.d.ts

@@ -3,6 +3,7 @@
  */
 import type { ToolDefinition } from "../../types.js";
 import type { ToolContext } from "../context.js";
+import type { CronJob, CreateJobOptions } from "../../automation/scheduler.js";
 export { cronListToolDef } from "./cron-list.definition.js";
 /** Sink notified after a cron job is created/deleted, so the host (Electron
  *  main) can reload+arm the scheduler that actually executes jobs. The worker
@@ -10,6 +11,16 @@ export { cronListToolDef } from "./cron-list.definition.js";
  *  host never learns about an AI-created job until the user opens the UI. */
 type CronChangedSink = () => void;
 export declare function setCronChangedSink(sink: CronChangedSink | null): void;
+export interface CronCreateAuthorityInput extends CreateJobOptions {
+    name: string;
+    schedule: string;
+    prompt: string;
+    /** Current Engine Session, used by Desktop Main as authority even for standalone jobs. */
+    authoritySessionId?: string;
+}
+export type CronCreateAuthority = (input: CronCreateAuthorityInput) => Promise<CronJob>;
+/** Desktop installs a Main-process delegate; other hosts keep the local scheduler path. */
+export declare function setCronCreateAuthority(authority: CronCreateAuthority | null): void;
 export declare const cronCreateToolDef: ToolDefinition;
 export declare function cronCreateTool(args: Record<string, unknown>, context?: ToolContext): Promise<string>;
 export declare const cronDeleteToolDef: ToolDefinition;

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

@@ -17,6 +17,11 @@ function fireCronChanged() {
         // Notifying the host is best-effort; never break the tool on it.
     }
 }
+let cronCreateAuthority = null;
+/** Desktop installs a Main-process delegate; other hosts keep the local scheduler path. */
+export function setCronCreateAuthority(authority) {
+    cronCreateAuthority = authority;
+}
 export const cronCreateToolDef = {
     name: "CronCreate",
     description: "Create a scheduled automation job that runs a prompt on a recurring schedule. " +
@@ -125,15 +130,33 @@ export async function cronCreateTool(args, context) {
     // time (the model never supplies it — getCurrentSid() reads the running
     // Engine's ALS context). Empty/unknown sid → treat as standalone.
     const resumeSessionId = args.continueInSession === true && getCurrentSid() ? getCurrentSid() : undefined;
+    const stableWorkspace = context?.workspace && !context.workspace.projectId.startsWith("legacy-")
+        ? {
+            projectId: context.workspace.projectId,
+            rootId: context.workspace.sessionMainRootId,
+        }
+        : undefined;
     let job;
     try {
-        job = cronScheduler.create(name, schedule, prompt, {
+        const createInput = {
+            name,
+            schedule,
+            prompt,
             ...(timezone !== undefined ? { timezone } : {}),
             ...(cwd !== undefined ? { cwd } : {}),
+            ...(stableWorkspace ?? {}),
             ...(permissionLevel !== undefined ? { permissionLevel } : {}),
             ...(once ? { once: true } : {}),
             ...(resumeSessionId !== undefined ? { resumeSessionId } : {}),
-        });
+            ...(getCurrentSid() ? { authoritySessionId: getCurrentSid() } : {}),
+        };
+        if (cronCreateAuthority) {
+            job = await cronCreateAuthority(createInput);
+        }
+        else {
+            const { name: _name, schedule: _schedule, prompt: _prompt, authoritySessionId: _authoritySessionId, ...createOptions } = createInput;
+            job = cronScheduler.create(name, schedule, prompt, createOptions);
+        }
     }
     catch (err) {
         return `Error: ${err instanceof Error ? err.message : String(err)}`;
@@ -162,12 +185,14 @@ export async function cronDeleteTool(args) {
     const id = args.jobId;
     if (!id)
         return "Error: jobId is required";
+    cronScheduler.loadJobs({ arm: false });
     const deleted = cronScheduler.delete(id);
     if (deleted)
         fireCronChanged();
     return deleted ? `Cron job #${id} deleted.` : `Cron job #${id} not found.`;
 }
 export async function cronListTool(_args) {
+    cronScheduler.loadJobs({ arm: false });
     const jobs = cronScheduler.list();
     if (jobs.length === 0)
         return "No cron jobs scheduled.";

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

@@ -51,8 +51,10 @@ export async function editTool(args, ctx) {
     if (!existsSync(filePath))
         return `Error: File not found: ${filePath}`;
     try {
-        const approvedPath = getFinalWritePathSnapshot(args, filePath, cwd);
-        const beforeRead = 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 beforeRead = revalidateFinalWritePath(filePath, cwd, approvedPath, roots, digest);
         if ("error" in beforeRead)
             return { ok: false, error: beforeRead.error };
         const raw = await readFile(beforeRead.resolvedPath, "utf-8");
@@ -75,7 +77,7 @@ export async function editTool(args, ctx) {
             }
         }
         const updatedLf = replaceAll ? content.split(oldLf).join(newLf) : content.replace(oldLf, newLf);
-        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, applyEol(updatedLf, eol));

package/dist/tool-system/builtin/view-image.js

@@ -39,7 +39,8 @@ export const viewImageToolDef = {
             },
             imageNumber: {
                 type: "number",
-                description: "Image history number N from an earlier [image #N, already provided] placeholder.",
+                description: "Positive image history number N from an earlier [image #N, already provided] " +
+                    "placeholder. Omit this field entirely when path is provided; do not send 0.",
             },
             detail: {
                 type: "string",
@@ -53,7 +54,12 @@ export async function viewImageTool(args, ctx) {
     const rawPath = args.path;
     const rawImageNumber = args.imageNumber;
     const hasPath = typeof rawPath === "string" && rawPath.trim().length > 0;
-    const hasImageNumber = rawImageNumber !== undefined && rawImageNumber !== null;
+    const hasImageNumberInput = rawImageNumber !== undefined && rawImageNumber !== null;
+    // Some tool-calling models materialize every optional numeric property with
+    // a zero sentinel. With a real path, imageNumber: 0 unambiguously means
+    // "unused" because valid history numbers start at 1. Accept that one
+    // compatibility shape while keeping path + a real image number forbidden.
+    const hasImageNumber = hasImageNumberInput && !(hasPath && rawImageNumber === 0);
     if (hasPath === hasImageNumber) {
         return "Error: provide exactly one of path or imageNumber";
     }

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;
@@ -462,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;

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,35 @@
+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;
+/**
+ * Rebase only the Session's primary runtime path while preserving the host's
+ * authoritative project/root identities and the mounted secondary roots.
+ *
+ * A worktree switch changes where the primary root executes; it does not mint
+ * a new project or root id. Rebuilding through createWorkspaceContext also
+ * recomputes rootsDigest and re-runs the overlap/absolute-path validation.
+ */
+export declare function rebaseWorkspacePrimaryRoot(context: WorkspaceContext, primaryPath: string): WorkspaceContext;
+/** 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[];