@cjhyy/code-shell-core 0.8.20 → 0.9.0

package/dist/engine/engine.js

@@ -9,6 +9,7 @@ import { modelEntriesFromConnections } from "./model-connections-pool.js";
 import { cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "../session/usage.js";
 import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
 import { RunEnvironmentResolver } from "./run-environment.js";
+import { legacySingleRootWorkspace } from "../workspace/workspace-context.js";
 import { asyncAgentRegistry } from "../tool-system/builtin/agent-registry.js";
 import { skillToolDef } from "../tool-system/builtin/skill.js";
 import { backgroundShellManager } from "../runtime/background-shell.js";
@@ -21,7 +22,8 @@ import { runShellHook, shellHookMatches } from "../hooks/shell-runner.js";
 import { ContextManager } from "../context/manager.js";
 import { CONTEXT_PACKAGE_MAX_OUTPUT_TOKENS, buildAnchoredSummaryMessage, buildContextPackagePromptFromSerialized, estimateTokens, groupMessagesByApiRound, serializeContextPackageMessages, clampContextRatios as clampContextRatiosImpl, } from "../context/compaction.js";
 import { PromptComposer } from "../prompt/composer.js";
-import { SessionManager, assertSafeSessionId, isEphemeralSessionState, sessionsRoot, } from "../session/session-manager.js";
+import { SessionManager, isEphemeralSessionState, sessionsRoot, } from "../session/session-manager.js";
+import { createAuthorizedSessionMessageService, migrateOwnedSessionMainRoot, releaseOwnedSessionWorkspace, SessionWorkspaceAuthorityTracker, setOwnedSessionWorkspace, } from "./engine-workspace-authority.js";
 import { createRunUsageAccounting, wireRunModelFacade } from "./run-accounting.js";
 import { logger, runWithSid } from "../logging/logger.js";
 import { recordSessionStart } from "../logging/session-recorder.js";
@@ -198,6 +200,7 @@ export class Engine {
     lastMessages;
     lastSessionId;
     compactedMessagesBySession = new Map();
+    workspaceAuthorities = new SessionWorkspaceAuthorityTracker();
     /**
      * SIDs whose ctx-bar seed we've already emitted in this process. The seed
      * is a rough char/4 estimate; only useful before the first real
@@ -260,6 +263,7 @@ export class Engine {
      * writers are additionally fenced by SessionManager's persisted revision CAS.
      */
     runInProgress = false;
+    disposed = false;
     agentControlStateListener;
     agentDirectionsDeliveredListener;
     /** Permission update requested while runInProgress. Applied in run() finally. */
@@ -404,8 +408,7 @@ export class Engine {
             throw new ConfigError("EngineConfig.composition is mutually exclusive with modules");
         }
         // Single composition fact source for every module contribution.
-        this.composition =
-            config.composition ?? compileComposition({ modules: config.modules ?? [] });
+        this.composition = config.composition ?? compileComposition({ modules: config.modules ?? [] });
         this.toolCatalog = compositionToolCatalog(this.composition);
         this.toolGuards = new Map(this.toolCatalog.flatMap((tool) => tool.exposure.availability
             ? [[tool.definition.name, tool.exposure.availability]]
@@ -941,6 +944,8 @@ export class Engine {
      * policy (for example ChatSession's FIFO queue).
      */
     async run(task, options) {
+        if (this.disposed)
+            throw new Error("Engine has been disposed");
         if (this.runInProgress) {
             throw new Error("Engine.run() cannot start while another run is in progress");
         }
@@ -987,12 +992,16 @@ export class Engine {
             resolveBehaviorProfile: (kind, mode) => this.resolveBehaviorProfile(kind, mode),
             configPermissionMode: this.config.permissionMode,
             configCwd: this.config.cwd,
+            configWorkspaceContext: this.config.workspaceContext,
             settings: this.getSettingsManager(),
             processCwd: process.cwd(),
         });
         if (!workspaceResolved.ok)
             return workspaceResolved.result;
-        const { sessionKind, sessionWorkspaceProfile, profile, profileParams, runPermissionMode, runPlanMode, cwd, profileState: { workspaceProfile: runWorkspaceProfile, sessionProfileOverrides, profileMemoryDir, }, } = workspaceResolved.resolution;
+        const { sessionKind, sessionWorkspaceProfile, profile, profileParams, runPermissionMode, runPlanMode, cwd, workspaceContext, authoritativeWorkspaceContext, profileState: { workspaceProfile: runWorkspaceProfile, sessionProfileOverrides, profileMemoryDir, }, } = workspaceResolved.resolution;
+        if (options?.sessionId) {
+            this.workspaceAuthorities.remember(options.sessionId, workspaceContext);
+        }
         /** Structured results the profile's run services report; keyed per profile contract. */
         let profileReportedResults;
         // Wrap the caller's onStream so we can intercept `task_update`
@@ -1018,6 +1027,7 @@ export class Engine {
             llm: this.config.llm,
             sessionId: options?.sessionId,
             attachments: options?.attachments,
+            workspaceContext,
         });
         if (!imageInput.ok)
             return imageInput.result;
@@ -1039,6 +1049,7 @@ export class Engine {
         const toolCtx = await this.wireRunSandboxToolContext({
             options,
             cwd,
+            workspaceContext,
             runPermissionMode,
             runPlanMode,
             profile,
@@ -1080,6 +1091,12 @@ export class Engine {
             cwd,
             sessionKind,
             sessionWorkspaceProfile,
+            projectBinding: authoritativeWorkspaceContext
+                ? {
+                    projectId: workspaceContext.projectId,
+                    mainRootId: workspaceContext.sessionMainRootId,
+                }
+                : undefined,
             ...(options?.sessionBrief ? { sessionBrief: options.sessionBrief } : {}),
             llmModel: this.config.llm.model,
             llmProvider: this.config.llm.provider,
@@ -1181,6 +1198,7 @@ export class Engine {
                 options,
                 session,
                 cwd,
+                workspaceContext,
                 toolCtx,
                 profile,
                 profileParams,
@@ -1463,66 +1481,12 @@ export class Engine {
     }
     /** Attach a closed-set, host-routed Session message sender to this run. */
     attachSessionMessageService(toolCtx, session, options) {
-        const sourceSessionId = session.state.sessionId;
-        const sourceRoot = this.sessionManager.readSessionMainRoot(sourceSessionId);
-        if (!sourceRoot)
-            return;
-        if (!this.sessionMessageRouter)
-            return;
-        const catalog = [];
-        const seen = new Set();
-        const rawTargets = Array.isArray(options?.sessionMessageTargets)
-            ? [...options.sessionMessageTargets]
-            : [];
-        for (const raw of rawTargets.slice(0, 100)) {
-            if (!raw || typeof raw !== "object" || Array.isArray(raw))
-                continue;
-            const candidate = raw;
-            const sessionId = typeof candidate.sessionId === "string" ? candidate.sessionId : "";
-            try {
-                assertSafeSessionId(sessionId);
-            }
-            catch {
-                continue;
-            }
-            if (seen.has(sessionId))
-                continue;
-            if (candidate.workspaceRoot !== sourceRoot)
-                continue;
-            const title = typeof candidate.title === "string" ? candidate.title.trim() : "";
-            if (!title || title.length > 512)
-                continue;
-            const workspaceProfile = typeof candidate.workspaceProfile === "string"
-                ? candidate.workspaceProfile.trim().slice(0, 256)
-                : "";
-            seen.add(sessionId);
-            catalog.push({
-                sessionId,
-                title,
-                workspaceRoot: sourceRoot,
-                ...(workspaceProfile ? { workspaceProfile } : {}),
-            });
-        }
-        const targets = catalog.filter((target) => target.sessionId !== sourceSessionId);
-        toolCtx.sessionMessages = {
-            targets,
-            send: async ({ targetSessionId, message }) => {
-                const target = targets.find((candidate) => candidate.sessionId === targetSessionId);
-                if (!target)
-                    throw new Error("target Session is not in the host-authorized project list");
-                if (!message.trim())
-                    throw new Error("message is required");
-                if (message.length > 48_000)
-                    throw new Error("message exceeds 48000 characters");
-                await this.sessionMessageRouter({
-                    sourceSessionId,
-                    target,
-                    message,
-                    catalog,
-                });
-                return target;
-            },
-        };
+        toolCtx.sessionMessages = createAuthorizedSessionMessageService({
+            sessionManager: this.sessionManager,
+            router: this.sessionMessageRouter,
+            sourceSessionId: session.state.sessionId,
+            rawTargets: options?.sessionMessageTargets,
+        });
     }
     /**
      * Await the parallel prompt/context assembly (LLM client handshake, system
@@ -1656,12 +1620,13 @@ export class Engine {
      * lazily via `getSession` because it is opened after this wiring runs.
      */
     async wireRunSandboxToolContext(args) {
-        const { options, cwd, runPermissionMode, runPlanMode, profile, profileParams, sessionProfileOverrides, profileMemoryDir, getSession, reportResult, } = args;
+        const { options, cwd, workspaceContext, runPermissionMode, runPlanMode, profile, profileParams, sessionProfileOverrides, profileMemoryDir, getSession, reportResult, } = args;
         // Resolve before constructing the child spawner: a parent sandbox may come
         // solely from project/user settings rather than config.sandbox, while a
         // child intentionally skips project settings. Passing the complete
         // effective config is what makes undefined role sandbox mean inherit.
-        const sandboxConfig = this.runEnvironmentResolver.resolveSandboxConfig(cwd);
+        const sandboxRun = { cwd, workspaceContext };
+        const sandboxConfig = this.runEnvironmentResolver.resolveSandboxConfig(sandboxRun);
         // Build the per-Engine ToolContext that will be threaded through every
         // tool call. Replaces the old module-level singleton setters used by
         // built-ins and product capabilities.
@@ -1670,6 +1635,7 @@ export class Engine {
             parentSandbox: sandboxConfig,
             presetName: this.preset.name,
             cwd,
+            workspaceContext,
             permissionMode: runPermissionMode,
             modelPool: this.modelPool,
             parentStream: options?.onStream,
@@ -1696,7 +1662,7 @@ export class Engine {
         //
         // Backend is cached per runtime/engine so the capability probe runs once
         // per (mode, cwd) instead of every turn.
-        const sandboxBackend = await this.runEnvironmentResolver.resolveSandbox(cwd);
+        const sandboxBackend = await this.runEnvironmentResolver.resolveSandbox(sandboxRun);
         // Observability: surface what sandbox actually applied this run — the
         // configured mode vs the resolved backend (auto may downgrade to off when
         // no OS backend is available) + the network policy. Without this you can't
@@ -1720,6 +1686,7 @@ export class Engine {
                 ? sandboxBackend
                 : { ...sandboxBackend, network: sandboxConfig.network },
             cwd,
+            workspace: workspaceContext,
             shellEnv: this.runEnvironmentResolver.readShellEnv(cwd),
             profile,
             profileParams,
@@ -1976,7 +1943,7 @@ export class Engine {
      * this method — only the composer and tool defs cross back out.
      */
     async wireRunTooling(args) {
-        const { options, session, cwd, toolCtx, profile, profileParams, runWorkspaceProfile, profileMemoryDir, sessionProfileOverrides, runPlanMode, } = args;
+        const { options, session, cwd, workspaceContext, toolCtx, profile, profileParams, runWorkspaceProfile, profileMemoryDir, sessionProfileOverrides, runPlanMode, } = args;
         const visibilityExplicitGoal = normalizeGoal(options?.goal);
         const visibilityLifecycle = session.state.goalLifecycle;
         const visibilityStoredGoal = visibilityLifecycle && isGoalLifecycleCurrent(visibilityLifecycle)
@@ -1995,6 +1962,7 @@ export class Engine {
         const profileCanUseSkills = !runAllowedToolNames || runAllowedToolNames.has(skillToolDef.name);
         const promptComposer = new PromptComposer(buildPromptComposerConfig({
             cwd,
+            workspace: workspaceContext,
             model: this.config.llm.model,
             preset: this.preset,
             customSystemPrompt: profile?.disableInstructions
@@ -2157,6 +2125,7 @@ export class Engine {
                     llm: this.config.llm,
                     sessionId: sid,
                     attachments: item.attachments,
+                    workspaceContext: toolCtx.workspace,
                 });
                 if (!steerImageInput.ok) {
                     throw new Error(steerImageInput.result.text);
@@ -2526,6 +2495,27 @@ export class Engine {
     getConfig() {
         return this.config;
     }
+    /** Release Engine-local registrations after its owning ChatSession is replaced. */
+    async dispose() {
+        if (this.disposed)
+            return;
+        if (this.runInProgress)
+            throw new Error("Engine cannot be disposed while a run is in progress");
+        this.disposed = true;
+        try {
+            const mcp = this.runtime?.mcpPool ?? this.mcpManager;
+            await mcp?.unregisterOwner(this);
+        }
+        finally {
+            this.hooks.clear();
+            this.settingsHookHandles = [];
+            this.workspaceAuthorities.clear();
+            this.steerQueueBySid.clear();
+            this.compactedMessagesBySession.clear();
+            this.agentDefsCache = undefined;
+            this.lastContextManager = undefined;
+        }
+    }
     /**
      * Config hot-reload "layer 2": merge a disk-default config patch into this
      * ALREADY-RUNNING session's `this.config`, reload settings hooks, and
@@ -2797,40 +2787,30 @@ export class Engine {
         }
         return had;
     }
-    /**
-     * Persist a workspace pointer through the Engine that owns the live bundle.
-     * Host-side workspace actions use this RPC-facing seam so advancing the disk
-     * revision also rebases the active run before its next progress write.
-     */
     setSessionWorkspace(sessionId, workspace) {
-        if (!sessionId || !this.sessionManager.exists(sessionId))
-            return null;
-        try {
-            const stateRevision = this.sessionManager.setSessionWorkspace(sessionId, workspace);
-            if (this.activeRunSession?.state.sessionId === sessionId) {
-                Object.assign(this.activeRunSession.state, { workspace, stateRevision });
-            }
-            return workspace;
-        }
-        catch {
-            return null;
-        }
+        return setOwnedSessionWorkspace({
+            sessionManager: this.sessionManager,
+            activeState: this.activeRunSession?.state,
+            sessionId,
+            workspace,
+        });
+    }
+    migrateSessionMainRoot(sessionId, project, mainRoot) {
+        return migrateOwnedSessionMainRoot({
+            sessionManager: this.sessionManager,
+            activeState: this.activeRunSession?.state,
+            authorities: this.workspaceAuthorities,
+            sessionId,
+            project,
+            mainRoot,
+        });
     }
-    /**
-     * Reset a session's workspace pointer back to its main root. If the session is
-     * actively running, mutate that live SessionBundle first so the run's next
-     * saveState cannot resurrect a stale worktree pointer.
-     */
     releaseSessionWorkspace(sessionId) {
-        if (!sessionId || !this.sessionManager.exists(sessionId))
-            return null;
-        const mainRoot = this.sessionManager.readSessionMainRoot(sessionId) ??
-            (this.activeRunSession?.state.sessionId === sessionId
-                ? this.activeRunSession.state.cwd
-                : undefined);
-        if (!mainRoot)
-            return null;
-        return this.setSessionWorkspace(sessionId, { root: mainRoot, kind: "main" });
+        return releaseOwnedSessionWorkspace({
+            sessionManager: this.sessionManager,
+            activeState: this.activeRunSession?.state,
+            sessionId,
+        });
     }
     injectContext(sessionId, content) {
         const session = this.sessionManager.resume(sessionId);
@@ -3295,7 +3275,10 @@ export class Engine {
             const service = value({
                 isSubAgent: this.config.isSubAgent === true,
                 settings: this.getSettingsManager(),
-                resolveSandbox: (cwd) => this.runEnvironmentResolver.resolveSandbox(cwd),
+                resolveSandbox: (cwd) => this.runEnvironmentResolver.resolveSandbox({
+                    cwd,
+                    workspaceContext: legacySingleRootWorkspace(cwd),
+                }),
                 readShellEnv: (cwd) => this.runEnvironmentResolver.readShellEnv(cwd),
                 getSessionManager: () => this.sessionManager,
             });
@@ -3311,7 +3294,7 @@ export class Engine {
             capabilityServices,
             askUser: this.config.askUser,
             browser: this.config.browserBridge,
-            workspace: this.config.workspaceBridge,
+            workspaceBridge: this.config.workspaceBridge,
             panels: this.config.panelBridge,
             injectCredentialToBrowser: this.config.injectCredentialToBrowser,
             isSubAgent: this.config.isSubAgent === true,

package/dist/engine/input-attachments.d.ts

@@ -9,5 +9,6 @@ export interface InputAttachmentContext {
 export interface BuildInputAttachmentContextOptions {
     includeImageBytes?: boolean;
     expectedSessionId?: string;
+    workspaceRoots?: readonly string[];
 }
 export declare function buildInputAttachmentContext(attachments: readonly InputAttachmentMeta[] | undefined, cwd: string, options?: BuildInputAttachmentContextOptions): Promise<InputAttachmentContext>;

package/dist/engine/input-attachments.js

@@ -113,7 +113,11 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
             });
             continue;
         }
-        const policy = classifyPath(resolved, { workspaceRoot: cwdReal, operation: "read" });
+        const policy = classifyPath(resolved, {
+            workspaceRoot: cwdReal,
+            workspaceRoots: options.workspaceRoots,
+            operation: "read",
+        });
         if (policy.decision !== "allow") {
             errors.push(`attachment ${id === "(unknown)" ? displayPath : id} blocked by path policy: ${policy.reason}`);
             diagnostics.push({
@@ -141,7 +145,7 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
             continue;
         }
         if (attachment.kind === "directory" || info.isDirectory()) {
-            const tree = await directoryTree(realPath, cwdReal).catch((err) => ({
+            const tree = await directoryTree(realPath, policy.matchedRoot ?? cwdReal).catch((err) => ({
                 lines: [`(directory tree unavailable: ${err.message})`],
                 truncated: true,
                 entryCount: 0,

package/dist/engine/run-environment.d.ts

@@ -2,6 +2,7 @@ import type { CredentialAccess } from "../credentials/access.js";
 import { type SandboxBackend, type SandboxConfig } from "../tool-system/sandbox/index.js";
 import type { EngineRuntime } from "./runtime.js";
 import type { EngineConfig } from "./types.js";
+import type { WorkspaceContext } from "../workspace/workspace-context.js";
 type EnvironmentSettings = {
     get(): unknown;
     getForScope(scope: "user" | "project", cwd?: string): unknown;
@@ -13,14 +14,18 @@ export interface RunEnvironmentResolverDeps {
     runtime?: Pick<EngineRuntime, "resolveSandbox">;
     resolveBackend?: (config: SandboxConfig, cwd: string) => Promise<SandboxBackend>;
 }
+export interface RunEnvironmentInput {
+    cwd: string;
+    workspaceContext: WorkspaceContext;
+}
 export declare class RunEnvironmentResolver {
     private readonly deps;
     private readonly sandboxCache;
     private readonly resolveBackend;
     constructor(deps: RunEnvironmentResolverDeps);
-    resolveSandboxConfig(cwd: string): SandboxConfig;
-    resolveSandbox(cwd: string): Promise<SandboxBackend>;
-    resolve(cwd: string): Promise<{
+    resolveSandboxConfig(run: RunEnvironmentInput): SandboxConfig;
+    resolveSandbox(run: RunEnvironmentInput): Promise<SandboxBackend>;
+    resolve(run: RunEnvironmentInput): Promise<{
         sandbox: SandboxBackend;
         sandboxConfig: SandboxConfig;
         shellEnv?: Record<string, string>;

package/dist/engine/run-environment.js

@@ -1,6 +1,28 @@
-import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
+import { expandPath, resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
 import { resolveSandboxConfig } from "./sandbox-config.js";
 import { sandboxCacheKey } from "./sandbox-cache-key.js";
+import { canonicalKey, canonicalPath } from "../workspace/canonical-key.js";
+function appendWorkspaceRoots(config, run) {
+    const writableRoots = [];
+    const seen = new Set();
+    // Key configured roots after placeholder expansion so `${workspace}` wins
+    // over the equivalent primary path. Keep the first spelling and order.
+    for (const root of config.writableRoots) {
+        const key = canonicalKey(expandPath(root, run.cwd));
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        writableRoots.push(root);
+    }
+    for (const root of run.workspaceContext.roots) {
+        const key = canonicalKey(root.path);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        writableRoots.push(canonicalPath(root.path));
+    }
+    return { ...config, writableRoots };
+}
 export class RunEnvironmentResolver {
     deps;
     sandboxCache = new Map();
@@ -9,7 +31,8 @@ export class RunEnvironmentResolver {
         this.deps = deps;
         this.resolveBackend = deps.resolveBackend ?? resolveSandboxBackend;
     }
-    resolveSandboxConfig(cwd) {
+    resolveSandboxConfig(run) {
+        const { cwd } = run;
         const config = this.deps.config();
         let projectSandbox;
         let globalSandbox;
@@ -24,10 +47,11 @@ export class RunEnvironmentResolver {
         catch {
             // Missing settings fall through to the run default.
         }
-        return resolveSandboxConfig(config.sandbox, projectSandbox, globalSandbox, config.headless === true);
+        return appendWorkspaceRoots(resolveSandboxConfig(config.sandbox, projectSandbox, globalSandbox, config.headless === true), run);
     }
-    resolveSandbox(cwd) {
-        const config = this.resolveSandboxConfig(cwd);
+    resolveSandbox(run) {
+        const { cwd } = run;
+        const config = this.resolveSandboxConfig(run);
         if (this.deps.runtime)
             return this.deps.runtime.resolveSandbox(config, cwd);
         const key = sandboxCacheKey(config, cwd);
@@ -42,9 +66,10 @@ export class RunEnvironmentResolver {
         }
         return cached;
     }
-    async resolve(cwd) {
-        const sandboxConfig = this.resolveSandboxConfig(cwd);
-        const backend = await this.resolveSandbox(cwd);
+    async resolve(run) {
+        const { cwd } = run;
+        const sandboxConfig = this.resolveSandboxConfig(run);
+        const backend = await this.resolveSandbox(run);
         return {
             sandbox: backend.name === "off" ? backend : { ...backend, network: sandboxConfig.network },
             sandboxConfig,

package/dist/engine/run-image-input.d.ts

@@ -18,5 +18,6 @@ export declare function prepareRunImageInput(args: {
     llm: Pick<LLMConfig, "provider" | "providerKind" | "model">;
     sessionId?: string;
     attachments?: readonly InputAttachmentMeta[];
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
 }): Promise<PrepareRunImageInputResult>;
 export declare function buildRunUserMessageContent(parsedTask: ParsedTask, cwd: string, taskText: string): string | ContentBlock[];

package/dist/engine/run-image-input.js

@@ -38,6 +38,7 @@ export async function prepareRunImageInput(args) {
         attachmentContext = await buildInputAttachmentContext(args.attachments, cwd, {
             includeImageBytes: cap.supportsVision,
             expectedSessionId: sessionId,
+            workspaceRoots: args.workspaceContext?.roots.map((root) => root.path),
         });
     }
     catch (err) {

package/dist/engine/run-session-open.d.ts

@@ -1,4 +1,4 @@
-import type { Message, SessionKind } from "../types.js";
+import type { Message, SessionKind, SessionProjectBinding } from "../types.js";
 import type { SessionBundle, SessionManager } from "../session/session-manager.js";
 import type { ParsedTask } from "./parse-task.js";
 import type { buildRunUserMessageContent } from "./run-image-input.js";
@@ -13,6 +13,7 @@ export interface OpenRunSessionArgs {
     cwd: string;
     sessionKind: SessionKind;
     sessionWorkspaceProfile: string | undefined;
+    projectBinding?: SessionProjectBinding;
     /** Standing brief resent by the host each turn until the Session persists it. */
     sessionBrief?: string;
     llmModel: string;

package/dist/engine/run-session-open.js

@@ -30,6 +30,9 @@ export function openRunSession(args) {
     if (options?.sessionId && args.sessionManager.exists(options.sessionId)) {
         resumedFromDisk = true;
         session = args.sessionManager.resumeForRun(options.sessionId);
+        if (!session.state.project && args.projectBinding) {
+            args.sessionManager.saveStateOrUpdateFields(session.state, { project: args.projectBinding });
+        }
         const cachedCompacted = args.cachedCompactedMessages;
         messages = cachedCompacted ? [...cachedCompacted] : session.transcript.toMessages();
         // If the previous run was Ctrl+C'd or crashed between an assistant
@@ -114,6 +117,9 @@ export function openRunSession(args) {
         // Cold start: shape (2) reuses the host-supplied sid; shape (3)
         // lets sessionManager generate one with nanoid.
         session = args.sessionManager.create(args.cwd, args.llmModel, args.llmProvider, options?.sessionId, args.isSubAgent ? getCurrentSid() : undefined, args.isSubAgent ? "subagent" : args.origin, args.sessionKind, options?.ephemeral === true);
+        if (args.projectBinding) {
+            args.sessionManager.saveStateOrUpdateFields(session.state, { project: args.projectBinding });
+        }
         const userMsg = { role: "user", content: args.userMessageContent };
         claimClientMessageId(session, options?.clientMessageId, "submit");
         if (args.parsedTask.hasImages)

package/dist/engine/run-setup.d.ts

@@ -16,6 +16,7 @@ export declare function resolveRunProfileState(args: {
 }): RunProfileState;
 export interface RunPromptComposerConfigInput {
     cwd: ComposerOptions["cwd"];
+    workspace: ComposerOptions["workspace"];
     /** Standing brief persisted on the Session (see SessionState.sessionBrief). */
     sessionBrief?: ComposerOptions["sessionBrief"];
     model: ComposerOptions["model"];

package/dist/engine/run-setup.js

@@ -23,9 +23,10 @@ export function resolveRunProfileState(args) {
 }
 /** Build the prompt-composer options for a run without capturing the Engine facade. */
 export function buildPromptComposerConfig(args) {
-    const { cwd, model, preset, customSystemPrompt, appendSystemPrompt, responseLanguage, userProfile, workspaceProfile, sessionBrief, profileMemoryDir, instructionCompatFileNames, instructionBoundaryFinder, disabledSkills, disabledPlugins, skillAllowlist, memoriesMaxAgeDays, memoryCurrentProjectOnly, disableInstructions, disableMemoryContext, disableCapabilityContext, disableSourcesContext, goalToolState, capabilityPromptSections, dynamicContextProviders, getSettingsManager, toolCatalog, } = args;
+    const { cwd, workspace, model, preset, customSystemPrompt, appendSystemPrompt, responseLanguage, userProfile, workspaceProfile, sessionBrief, profileMemoryDir, instructionCompatFileNames, instructionBoundaryFinder, disabledSkills, disabledPlugins, skillAllowlist, memoriesMaxAgeDays, memoryCurrentProjectOnly, disableInstructions, disableMemoryContext, disableCapabilityContext, disableSourcesContext, goalToolState, capabilityPromptSections, dynamicContextProviders, getSettingsManager, toolCatalog, } = args;
     return {
         cwd,
+        workspace,
         model,
         preset,
         customSystemPrompt,

package/dist/engine/run-tooling.d.ts

@@ -29,6 +29,7 @@ export declare function buildRunToolContext(args: {
     agentDefinitions: ToolContext["agentDefinitions"];
     sandbox: ToolContext["sandbox"];
     cwd: string;
+    workspace: ToolContext["workspace"];
     shellEnv: ToolContext["shellEnv"];
     profile: RunBehaviorProfile | undefined;
     profileParams: Readonly<Record<string, unknown>>;
@@ -73,6 +74,7 @@ export declare function connectRunMcp(args: {
  */
 export interface ToolVisibilityInputs {
     cwd: string;
+    workspace?: ToolContext["workspace"];
     hasGoal: boolean;
     sessionId?: string;
     settingsScope?: SettingsScope;

package/dist/engine/run-tooling.js

@@ -28,6 +28,7 @@ export function buildRunToolContext(args) {
         // properties and survive the spread. Off keeps network undefined.
         sandbox: args.sandbox,
         cwd: args.cwd,
+        workspace: args.workspace,
         shellEnv: args.shellEnv,
         // TodoWrite reads this to push task_update events independently
         // of its return value, so the UI's pinned task panel refreshes
@@ -166,6 +167,7 @@ export async function connectRunMcp(args) {
 export function buildToolVisibility(inputs) {
     return {
         cwd: inputs.cwd,
+        ...(inputs.workspace ? { workspace: inputs.workspace } : {}),
         hasGoal: inputs.hasGoal,
         ...(inputs.sessionId ? { sessionId: inputs.sessionId } : {}),
         ...(inputs.settingsScope ? { settingsScope: inputs.settingsScope } : {}),
@@ -186,6 +188,7 @@ export function assembleRunToolDefs(args) {
     const guardCwd = args.guardCwd;
     const toolVisibility = buildToolVisibility({
         cwd: guardCwd,
+        workspace: toolCtx.workspace,
         hasGoal: args.hasRunnableGoal,
         sessionId: toolCtx.sessionId,
         settingsScope: args.settingsScope,

package/dist/engine/run-types.d.ts

@@ -87,6 +87,8 @@ export declare const ISOLATED_TASK_SYSTEM_PROMPT = "# Isolated Task Boundary\n\n
 export declare const ISOLATED_TASK_PROFILE: RunBehaviorProfile;
 export interface EngineRunOptions {
     cwd?: string;
+    /** Trusted run-scoped root authorization. Protocol hosts must strip untrusted values. */
+    workspaceContext?: import("../workspace/workspace-context.js").WorkspaceContext;
     onStream?: StreamCallback;
     signal?: AbortSignal;
     sessionId?: string;

package/dist/engine/run-workspace.d.ts

@@ -11,6 +11,7 @@ import type { SettingsManager } from "../settings/manager.js";
 import type { EngineConfig, EngineResult } from "./types.js";
 import type { EngineRunOptions, RunBehaviorProfile } from "./run-types.js";
 import { type RunProfileState } from "./run-setup.js";
+import { type WorkspaceContext } from "../workspace/workspace-context.js";
 /**
  * Resolve the working directory for a run. Precedence for legacy sessions:
  *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
@@ -30,6 +31,9 @@ export interface RunWorkspaceResolution {
     runPermissionMode: NonNullable<EngineConfig["permissionMode"]>;
     runPlanMode: boolean;
     cwd: string;
+    workspaceContext: WorkspaceContext;
+    /** False only for the compatibility context synthesized from a lone cwd. */
+    authoritativeWorkspaceContext: boolean;
     profileState: RunProfileState;
 }
 export type ResolveRunWorkspaceResult = {
@@ -41,10 +45,11 @@ export type ResolveRunWorkspaceResult = {
 };
 export declare function resolveRunWorkspace(args: {
     options: EngineRunOptions | undefined;
-    sessionManager: Pick<SessionManager, "exists" | "readSessionKind" | "readSessionWorkspaceProfile" | "resolveSessionWorkspaceForResume" | "readSessionMainRoot">;
+    sessionManager: Pick<SessionManager, "exists" | "readSessionKind" | "readSessionWorkspaceProfile" | "resolveSessionWorkspaceForResume" | "readSessionMainRoot" | "readSessionProjectBinding">;
     resolveBehaviorProfile: (sessionKind: string, behaviorMode: string | undefined) => RunBehaviorProfile | undefined;
     configPermissionMode: EngineConfig["permissionMode"];
     configCwd: string | undefined;
+    configWorkspaceContext: WorkspaceContext | undefined;
     settings: SettingsManager;
     processCwd: string;
 }): Promise<ResolveRunWorkspaceResult>;