@cursor/july 0.1.103 → 0.1.105

package/src/internal/session-engine.ts

@@ -37,6 +37,17 @@ import {
   isCursorHostedFilesAvailable,
   isCursorUserStoreFilesAvailable,
 } from "../files-backends/cursor-hosted.js";
+import {
+  type FileSystem,
+  isFileSystemToolAlias,
+  isMutatingFileSystemTool,
+  localFileSystem,
+  resolveFileSystemTools,
+  resolveHostHarnessToolOptions,
+  tempFs,
+  unionFs,
+  writeWorkspaceFilesToRoot,
+} from "../filesystem.js";
 import { storageKeysForArchitecture } from "../storage.js";
 import {
   type AgentProject,
@@ -69,6 +80,7 @@ import {
   type PendingAuth,
   type ReceiveInput,
   type ResolvedAgent,
+  type RootContext,
   type RunnerSubagent,
   type RunnerTurnRequest,
   type SendMessageFn,
@@ -124,6 +136,17 @@ import { describeError } from "./describe-error.js";
 import { isDevMode } from "./dev-mode.js";
 import { type EventLogMemoryStats, EventLogStore } from "./event-log.js";
 import { TurnEventMapper } from "./event-mapper.js";
+import {
+  applyWebScratchUpdate,
+  ingestHostAgentToolsScratch,
+  remapScratchPaths,
+} from "./filesystem/scratch.js";
+import {
+  fileSystemTool,
+  hostFileToolsFromAuthored,
+  rootFileToolsFromAuthored,
+  synthesizeFileSystemTools,
+} from "./filesystem/tools.js";
 import { selectFrameworkStorageDefinition } from "./framework-storage-selection.js";
 import { createHostFilesApi } from "./host-files.js";
 import { createHostKvApi } from "./host-kv.js";
@@ -179,14 +202,19 @@ import { resolveAgentV2Hosting } from "./v2-hosting.js";
 import {
   buildAgentsMdContent,
   buildCloudMemorySection,
+  buildCloudSessionWorkspaceSection,
   buildCloudWorkspaceSection,
   ensureOwnGitRoot,
   isNestedInGitRepo,
   materializeWorkspace,
   SERVER_TOOLS_MCP_SERVER_NAME,
-  writeWorkspaceFiles,
 } from "./workspace.js";
-import { syncWorkspaceToStore } from "./workspace-sync.js";
+import {
+  syncSessionWorkspaceFiles,
+  syncWorkspaceToStore,
+  WorkspaceFileRefusal,
+  wipeSessionWorkspace,
+} from "./workspace-sync.js";
 
 export const HTTP_CHANNEL_ID = "http";
 export { SCHEDULE_CHANNEL_PREFIX } from "./prompt-context.js";
@@ -200,6 +228,7 @@ interface CloudStoreTarget {
   mountPath: string;
   skillsPrefix: string;
   workspacePrefix: string;
+  sessionWorkspacePrefix: (sessionId: string) => string;
   label: string;
 }
 
@@ -510,6 +539,15 @@ export class SessionEngine {
   private readonly cloudCostBackfillDone = new Set<string>();
   /** Deduped in-flight cloud cost backfills, keyed by session id. */
   private readonly cloudCostBackfill = new Map<string, Promise<void>>();
+  /** Per-session FileSystem handle cache (not a tree snapshot). */
+  private readonly sessionRoots = new Map<string, FileSystem>();
+  /** In-flight factory resolves, so the first turn and a racing callTool share one handle. */
+  private readonly sessionRootInflight = new Map<string, Promise<FileSystem>>();
+  /** Per-turn `unionFs({ "/": authored, "/tmp": tempFs() })`. Dropped at end of turn. */
+  private readonly turnRoots = new Map<
+    string,
+    { root: FileSystem; cwd: string }
+  >();
 
   constructor(options: SessionEngineOptions) {
     this.project = options.project;
@@ -1793,6 +1831,261 @@ export class SessionEngine {
     return this.interrupt(existing.sessionId);
   }
 
+  private hasRootOverride(): boolean {
+    return this.project.agent.root !== undefined;
+  }
+
+  /**
+   * FileSystem for this turn or `callTool`. Authored `root` (static or
+   * factory) is cached per session when `cache` is set; unscoped
+   * `callTool` passes the invocation id and does not cache, so factories
+   * cannot share one tree across callers. A static handle is used as
+   * authored — every session sees that same object. Host-default agents
+   * get `localFileSystem` against the harness cwd — same path verbs as
+   * the Cursor SDK natives, always through the synthesized tools.
+   */
+  private async resolveFileSystem(options: {
+    sessionId: string;
+    continuationKey?: string;
+    cache: boolean;
+    cwd: string;
+  }): Promise<FileSystem> {
+    const authored = this.project.agent.root;
+    if (authored === undefined) {
+      return localFileSystem({ cwd: options.cwd });
+    }
+    const authoredRoot = await this.resolveAuthoredFileSystem(options);
+    if (options.cache) {
+      const existing = this.turnRoots.get(options.sessionId);
+      if (existing !== undefined) {
+        return existing.root;
+      }
+    }
+    const root = unionFs({
+      "/": authoredRoot,
+      "/tmp": tempFs(),
+    });
+    if (options.cache && this.isTurnRunning(options.sessionId)) {
+      this.turnRoots.set(options.sessionId, { root, cwd: options.cwd });
+    }
+    return root;
+  }
+
+  private async resolveAuthoredFileSystem(options: {
+    sessionId: string;
+    continuationKey?: string;
+    cache: boolean;
+  }): Promise<FileSystem> {
+    const authored = this.project.agent.root;
+    if (authored === undefined) {
+      throw new Error("resolveAuthoredFileSystem requires an authored root");
+    }
+    if (options.cache) {
+      const cached = this.sessionRoots.get(options.sessionId);
+      if (cached !== undefined) {
+        return cached;
+      }
+      const inflight = this.sessionRootInflight.get(options.sessionId);
+      if (inflight !== undefined) {
+        return inflight;
+      }
+    }
+    const resolve = async (): Promise<FileSystem> => {
+      if (typeof authored !== "function") {
+        return authored;
+      }
+      const host = this.hostForSession(
+        options.cache ? options.sessionId : undefined
+      );
+      const ctx: RootContext = {
+        sessionId: options.sessionId,
+        agentName: this.project.agent.name,
+        ...(options.continuationKey === undefined
+          ? {}
+          : { continuationKey: options.continuationKey }),
+        host: { files: host.files, reminders: host.reminders },
+      };
+      return await authored(ctx);
+    };
+    if (!options.cache) {
+      return resolve();
+    }
+    const pending = resolve();
+    this.sessionRootInflight.set(options.sessionId, pending);
+    try {
+      const resolved = await pending;
+      this.sessionRoots.set(options.sessionId, resolved);
+      return resolved;
+    } finally {
+      this.sessionRootInflight.delete(options.sessionId);
+    }
+  }
+
+  private dropTurnFileSystem(sessionId: string): void {
+    this.turnRoots.delete(sessionId);
+  }
+
+  private async prepareScratchToolInput(options: {
+    sessionId?: string;
+    input: Record<string, unknown>;
+  }): Promise<Record<string, unknown>> {
+    if (options.sessionId === undefined) {
+      return options.input;
+    }
+    const turn = this.turnRoots.get(options.sessionId);
+    if (turn === undefined) {
+      return options.input;
+    }
+    await ingestHostAgentToolsScratch({
+      cwd: turn.cwd,
+      root: turn.root,
+    });
+    return remapScratchPaths(options.input, turn.cwd);
+  }
+
+  private withTurnScratchTools(
+    tools: DiscoveredTool[],
+    sessionId: string
+  ): DiscoveredTool[] {
+    const turn = this.turnRoots.get(sessionId);
+    if (turn === undefined) {
+      return tools;
+    }
+    return tools.map((tool) => {
+      const execute = tool.definition.execute;
+      if (typeof execute !== "function") {
+        return tool;
+      }
+      return {
+        ...tool,
+        definition: {
+          ...tool.definition,
+          execute: async (input, ctx) => {
+            const remapped = await this.prepareScratchToolInput({
+              sessionId,
+              input:
+                input !== null &&
+                typeof input === "object" &&
+                !Array.isArray(input)
+                  ? (input as Record<string, unknown>)
+                  : {},
+            });
+            return execute(remapped as never, ctx);
+          },
+        },
+      };
+    });
+  }
+
+  private async nativeFileSystemOutcome(options: {
+    toolName: string;
+    input: unknown;
+    callId: string;
+    sessionId?: string;
+    continuationKey?: string;
+    cwd: string;
+    dryRun?: boolean;
+  }): Promise<ToolCallOutcome | undefined> {
+    const { toolName, input, callId } = options;
+    if (!isFileSystemToolAlias(toolName)) {
+      return undefined;
+    }
+    // Same policy the authored callTool path asks: a dry-run write is
+    // answered by the host. Native edit/delete used to return before
+    // decideToolCall and persist through the FileSystem.
+    const decision = decideToolCall({
+      dryRun: options.dryRun === true,
+      effect: isMutatingFileSystemTool(toolName) ? "write" : "read",
+      input,
+    });
+    if (decision.kind === "answer") {
+      return {
+        callId,
+        toolName,
+        isError: false,
+        result: decision.result,
+        durationMs: 0,
+        sessionId: options.sessionId,
+      };
+    }
+    const root = await this.resolveFileSystem({
+      sessionId: options.sessionId ?? callId,
+      continuationKey: options.continuationKey,
+      cache: options.sessionId !== undefined,
+      cwd: options.cwd,
+    });
+    const rawArgs =
+      input !== null && typeof input === "object" && !Array.isArray(input)
+        ? (input as Record<string, unknown>)
+        : {};
+    const args = await this.prepareScratchToolInput({
+      sessionId: options.sessionId,
+      input: rawArgs,
+    });
+    const tool = fileSystemTool(root, toolName, args);
+    const execute = tool?.definition.execute;
+    if (tool === undefined || typeof execute !== "function") {
+      // A resolved root owns this native name. Falling through would let
+      // an authored lookalike run, or surface UnknownToolError after we
+      // already advertised the FileSystem tool.
+      return {
+        callId,
+        toolName,
+        isError: true,
+        result: {
+          status: "error",
+          error: { message: `FileSystem cannot handle ${toolName}` },
+        },
+        durationMs: 0,
+        sessionId: options.sessionId,
+        errorMessage: `FileSystem cannot handle ${toolName}`,
+      };
+    }
+    const validation = validateToolInput(tool.definition.inputSchema, args);
+    if (!validation.ok) {
+      return {
+        callId,
+        toolName,
+        isError: true,
+        result: {
+          status: "error",
+          error: { message: validation.message },
+        },
+        durationMs: 0,
+        sessionId: options.sessionId,
+        errorMessage: validation.message,
+      };
+    }
+    try {
+      const value = await execute(
+        validation.value as never,
+        {
+          toolCallId: callId,
+          workspaceDir: options.cwd,
+        } as never
+      );
+      return {
+        callId,
+        toolName,
+        isError: false,
+        result: normalizeToolResult(value),
+        durationMs: 0,
+        sessionId: options.sessionId,
+      };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        callId,
+        toolName,
+        isError: true,
+        result: { status: "error", error: { message } },
+        durationMs: 0,
+        sessionId: options.sessionId,
+        errorMessage: message,
+      };
+    }
+  }
+
   /**
    * Local harness cwd for a session: per-send override, else the shared
    * `agent.local.workspaceDir`, else `<agent.local.cwd>/<sessionId>`, else
@@ -1840,19 +2133,22 @@ export class SessionEngine {
     if (
       workspaceDir === undefined ||
       agent.runtime !== "local" ||
+      this.hasRootOverride() ||
       this.runner.prewarm === undefined
     ) {
       return;
     }
     const startedAt = Date.now();
     try {
+      const harness = resolveHostHarnessToolOptions(agent.allowedTools);
       const outcome = await this.runner.prewarm({
         workspaceDir,
         runnerStateDir: join(this.stateRoot, "runner"),
         sandbox: agent.local?.sandbox === true,
-        ...(agent.allowedTools === undefined
+        ...(harness.tools === undefined ? {} : { tools: harness.tools }),
+        ...(harness.disallowedTools === undefined
           ? {}
-          : { tools: agent.allowedTools }),
+          : { disallowedTools: harness.disallowedTools }),
         // No session yet, so auth'd connections are omitted rather than
         // warmed without an identity; the per-send flag still has to match
         // the turns' requests or the warmed executor is one no turn asks for.
@@ -1942,41 +2238,53 @@ export class SessionEngine {
         // cwd is overridden (e.g. a PR worktree). A/B variant instruction
         // overlays are applied via agentForSession.
         const agent = this.agentForSession(record);
-        await materializeWorkspace({
-          agent,
-          workspaceDir,
-          seed: isFirstTurn,
-          stateRoot: this.stateRoot,
-        });
-        this.materializedWorkspaces.add(sessionId);
-        // Must precede the carrier: the harness resolves rules, skills,
-        // `mcp.json` and hooks from its git root, so a workspace nested in an
-        // outer repo would load that repo's hooks instead of the ones written
-        // just below. Only for directories this session owns — a borrowed
-        // checkout or worktree keeps its own root.
-        if (!this.hasBorrowedWorkspace(record)) {
-          await ensureOwnGitRoot(harnessCwd);
+        if (!this.hasRootOverride()) {
+          await materializeWorkspace({
+            agent,
+            workspaceDir,
+            seed: isFirstTurn,
+            stateRoot: this.stateRoot,
+          });
+          this.materializedWorkspaces.add(sessionId);
+          // Must precede the carrier: the harness resolves rules, skills,
+          // `mcp.json` and hooks from its git root, so a workspace nested in an
+          // outer repo would load that repo's hooks instead of the ones written
+          // just below. Only for directories this session owns — a borrowed
+          // checkout or worktree keeps its own root.
+          if (!this.hasBorrowedWorkspace(record)) {
+            await ensureOwnGitRoot(harnessCwd);
+          }
+          await this.materializeNudgeCarrier(record, harnessCwd);
         }
-        await this.materializeNudgeCarrier(record, harnessCwd);
         // Baseline before the agent can run, so a follow-up that arrives and
         // drains before the first tool boundary still counts as an increase.
         await this.baselineDeliveredNudges(record);
         const pendingFiles = record.pendingWorkspaceFiles;
         const pendingImages = record.pendingImages;
-        if (
-          pendingFiles !== undefined &&
-          Object.keys(pendingFiles).length > 0
-        ) {
-          await writeWorkspaceFiles(harnessCwd, pendingFiles);
+        const runtime = resolveSessionRuntime({
+          agentRuntime: agent.runtime,
+          cloudOverride: record.cloudOverride,
+        });
+        const hasPendingFiles =
+          pendingFiles !== undefined && Object.keys(pendingFiles).length > 0;
+        if (hasPendingFiles && runtime !== "cloud") {
+          const root = await this.resolveFileSystem({
+            sessionId,
+            continuationKey: record.continuationKey ?? undefined,
+            cache: true,
+            cwd: harnessCwd,
+          });
+          await writeWorkspaceFilesToRoot(root, pendingFiles);
         }
         if (
-          (pendingFiles !== undefined &&
-            Object.keys(pendingFiles).length > 0) ||
+          (hasPendingFiles && runtime !== "cloud") ||
           (pendingImages !== undefined && pendingImages.length > 0)
         ) {
           await this.updateRecord(sessionId, (current) => ({
             ...current,
             pendingWorkspaceFiles:
+              hasPendingFiles &&
+              runtime !== "cloud" &&
               current.pendingWorkspaceFiles === pendingFiles
                 ? undefined
                 : current.pendingWorkspaceFiles,
@@ -2004,6 +2312,14 @@ export class SessionEngine {
           instructionsInvisibleToHarness,
           emit,
           async (update) => {
+            const turn = this.turnRoots.get(sessionId);
+            if (turn !== undefined) {
+              update = await applyWebScratchUpdate({
+                cwd: turn.cwd,
+                root: turn.root,
+                update,
+              });
+            }
             mapper.handleUpdate(update);
             // Yield so the HTTP NDJSON writer can flush tool start/result
             // events while sibling parallel tools are still executing.
@@ -2039,6 +2355,7 @@ export class SessionEngine {
         outcome = { status: "error", errorMessage: describeError(error) };
       } finally {
         permit.release();
+        this.dropTurnFileSystem(sessionId);
         this.approvals.cancelSession(sessionId, "deny");
         this.auths.cancelSession(sessionId, "deny");
         await this.clearPendingApprovals(sessionId);
@@ -2135,6 +2452,7 @@ export class SessionEngine {
               data: { message: outcome.errorMessage ?? "task failed" },
             }
       );
+      await this.wipeCloudSessionWorkspace(sessionId);
     } else {
       await this.appendEvent(sessionId, {
         type: "session.waiting",
@@ -2189,6 +2507,68 @@ export class SessionEngine {
     );
   }
 
+  /**
+   * Replace this session's store prefix with the pending `workspaceFiles`.
+   * Undefined when the write did not land; the prompt must not name the
+   * mount, matching ensureCloudWorkspaceSynced.
+   */
+  private async syncCloudSessionWorkspaceFiles(
+    store: CloudStoreTarget,
+    sessionId: string,
+    files: NonNullable<SessionRecord["pendingWorkspaceFiles"]>
+  ): Promise<{ dir: string; relPaths: string[] } | undefined> {
+    const workspacePrefix = store.sessionWorkspacePrefix(sessionId);
+    try {
+      const relPaths = await syncSessionWorkspaceFiles({
+        sink: store.sink,
+        files,
+        workspacePrefix,
+      });
+      return {
+        dir: `${store.mountPath}/${workspacePrefix}`,
+        relPaths,
+      };
+    } catch (error) {
+      this.logger(
+        `[workspace] ${store.label} session files sync failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+      if (error instanceof WorkspaceFileRefusal) {
+        await this.clearPendingWorkspaceFiles(sessionId, files);
+      }
+      return undefined;
+    }
+  }
+
+  private async wipeCloudSessionWorkspace(sessionId: string): Promise<void> {
+    const store = this.cloudStore();
+    if (store === undefined) {
+      return;
+    }
+    try {
+      await wipeSessionWorkspace({
+        sink: store.sink,
+        workspacePrefix: store.sessionWorkspacePrefix(sessionId),
+      });
+    } catch (error) {
+      this.logger(
+        `[workspace] ${store.label} session files wipe failed: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+
+  private async clearPendingWorkspaceFiles(
+    sessionId: string,
+    pending: NonNullable<SessionRecord["pendingWorkspaceFiles"]>
+  ): Promise<void> {
+    await this.updateRecord(sessionId, (current) => ({
+      ...current,
+      pendingWorkspaceFiles:
+        current.pendingWorkspaceFiles === pending
+          ? undefined
+          : current.pendingWorkspaceFiles,
+    }));
+  }
+
   /**
    * With files authored, every first cloud turn re-copies the authored
    * bytes and the memo only dedupes concurrent first turns. The mount is
@@ -2241,6 +2621,8 @@ export class SessionEngine {
       mountPath: DEPLOYMENT_STORE_MOUNT_PATH,
       skillsPrefix: agentStoreKeys.skillsPrefix(),
       workspacePrefix: agentStoreKeys.workspacePrefix(),
+      sessionWorkspacePrefix: (sessionId: string) =>
+        agentStoreKeys.sessionWorkspacePrefix(sessionId),
       label: "deployment store",
     };
     if (v2Hosting.kind === "cursor-managed") {
@@ -2263,6 +2645,11 @@ export class SessionEngine {
         mountPath: USER_STORE_MOUNT_PATH,
         skillsPrefix: agentStoreKeys.userSkillsPrefix(this.project.name),
         workspacePrefix: agentStoreKeys.userWorkspacePrefix(this.project.name),
+        sessionWorkspacePrefix: (sessionId: string) =>
+          agentStoreKeys.userSessionWorkspacePrefix(
+            this.project.name,
+            sessionId
+          ),
         label: "user store",
       };
     }
@@ -2291,6 +2678,17 @@ export class SessionEngine {
     // allowlist, and a restriction that silently does not apply is worse
     // than a refused turn. Non-local agents already fail discovery; this
     // guards hybrid agents' per-send cloud sessions.
+    //
+    // Factory roots omit `allowedTools` at discovery (the live handle is
+    // resolved per session). The allowlist guard below therefore never
+    // fires for `defineAgent({ root: (ctx) => … })` with omitted `tools`,
+    // and a per-send `cloud` attach would skip the virtual-root allowlist
+    // and run unrestricted on a VM. Any authored root refuses non-local turns.
+    if (runtime !== "local" && this.hasRootOverride()) {
+      throw new Error(
+        `Agent "${agent.name}" declares root, which cannot be served on ${runtime} turns. Refusing the session rather than running it against the host VM.`
+      );
+    }
     if (runtime !== "local" && agent.allowedTools !== undefined) {
       throw new Error(
         `Agent "${agent.name}" declares a built-in tool allowlist (tools), which cannot be enforced on ${runtime} turns. Refusing the session rather than running it unrestricted.`
@@ -2319,6 +2717,48 @@ export class SessionEngine {
             override: record.cloudOverride,
           })
         : undefined;
+    const authoredRoot = this.hasRootOverride();
+    const root =
+      runtime === "local"
+        ? await this.resolveFileSystem({
+            sessionId: record.sessionId,
+            continuationKey: record.continuationKey ?? undefined,
+            cache: true,
+            cwd: this.harnessCwd(record),
+          })
+        : undefined;
+    const harnessTools =
+      runtime === "local" && root !== undefined
+        ? authoredRoot
+          ? {
+              tools: resolveFileSystemTools({
+                root,
+                tools: agent.allowedTools,
+              }),
+            }
+          : resolveHostHarnessToolOptions(agent.allowedTools)
+        : undefined;
+    const fileTools =
+      root === undefined
+        ? []
+        : synthesizeFileSystemTools(
+            root,
+            authoredRoot
+              ? rootFileToolsFromAuthored(agent.allowedTools)
+              : hostFileToolsFromAuthored(agent.allowedTools)
+          );
+    // Host-default keeps native SemanticSearch (the host index).
+    // `localFileSystem.search` is empty, so synthesizing would
+    // replace a working index with an empty custom tool.
+    const synthesized =
+      root === undefined
+        ? []
+        : this.withTurnScratchTools(
+            authoredRoot
+              ? fileTools
+              : fileTools.filter((tool) => tool.name !== "SemanticSearch"),
+            record.sessionId
+          );
     let turnPrompt = prompt;
     if (isFirstTurn) {
       const contextBlock = buildSessionContextBlock({
@@ -2331,34 +2771,39 @@ export class SessionEngine {
       });
       turnPrompt = `${contextBlock}\n\n${prompt}`;
     }
-    if (isFirstTurn) {
-      if (runtime === "cloud") {
-        // Cloud VMs have no materialized workspace: ship the full context,
-        // including agent tool script bodies. Authored skills and workspace
-        // seeds land on the store mount (skills for native discovery, seeds
-        // for the model's file tools), and on hosted deployments the shared
-        // memory journal is on that mount too — say where. When the turn
-        // carries the session-bound server-tool MCP endpoint, the preamble
-        // catalogs server tools under that MCP server name *before* the
-        // agent-tool "write the script if missing" recipe, so a model told
-        // to "use <server tool>" calls MCP instead of inventing a .sh.
-        const preamble = buildAgentsMdContent(agent, {
+    if (runtime === "cloud") {
+      // Cloud VMs have no materialized workspace: ship the full context,
+      // including agent tool script bodies. Authored skills and workspace
+      // seeds land on the store mount (skills for native discovery, seeds
+      // for the model's file tools), per-turn workspaceFiles land under
+      // the session prefix, and on hosted deployments the shared memory
+      // journal is on that mount too — say where. When the turn carries
+      // the session-bound server-tool MCP endpoint, the preamble catalogs
+      // server tools under that MCP server name *before* the agent-tool
+      // "write the script if missing" recipe, so a model told to "use
+      // <server tool>" calls MCP instead of inventing a .sh.
+      const hosted = isCursorHostedFilesAvailable();
+      const store =
+        hosted || isCursorUserStoreFilesAvailable()
+          ? this.cloudStore()
+          : undefined;
+      let preamble = "";
+      const sections: string[] = [];
+      const pending = record.pendingWorkspaceFiles;
+      if (isFirstTurn) {
+        preamble = buildAgentsMdContent(agent, {
           includeScripts: true,
           serverToolsMcpName:
             this.cloudServerToolsConnection === undefined
               ? undefined
               : SERVER_TOOLS_MCP_SERVER_NAME,
         });
-        const hosted = isCursorHostedFilesAvailable();
-        // Synced whenever a store is reachable, not just when skills or
-        // seeds exist: removing the last one has to delete its store copies
-        // too.
-        const store =
-          hosted || isCursorUserStoreFilesAvailable()
-            ? this.cloudStore()
-            : undefined;
-        let sections = "";
-        if (store !== undefined) {
+      }
+      if (store !== undefined) {
+        if (isFirstTurn) {
+          // Synced whenever a store is reachable, not just when skills or
+          // seeds exist: removing the last one has to delete its store copies
+          // too.
           const [, seedsSynced] = await Promise.all([
             this.ensureCloudSkillsSynced(store),
             this.ensureCloudWorkspaceSynced(store),
@@ -2366,25 +2811,63 @@ export class SessionEngine {
           // Only name the mount when the bytes landed; a failed sync must
           // not send the model looking for files that are not there.
           if (seedsSynced && agent.seedFiles.length > 0) {
-            const dir = `${store.mountPath}/${store.workspacePrefix}`;
-            sections += `\n\n${buildCloudWorkspaceSection(dir)}`;
+            sections.push(
+              buildCloudWorkspaceSection(
+                `${store.mountPath}/${store.workspacePrefix}`
+              )
+            );
           }
         }
-        if (hosted) {
-          sections += `\n\n${buildCloudMemorySection(this.project.name)}`;
+        if (pending !== undefined && Object.keys(pending).length > 0) {
+          const synced = await this.syncCloudSessionWorkspaceFiles(
+            store,
+            record.sessionId,
+            pending
+          );
+          if (synced !== undefined) {
+            sections.push(
+              buildCloudSessionWorkspaceSection(synced.dir, synced.relPaths)
+            );
+            await this.clearPendingWorkspaceFiles(record.sessionId, pending);
+          }
         }
-        turnPrompt = `${preamble}${sections}\n\n${turnPrompt}`;
-      } else if (runtime === "local" && instructionsInvisibleToHarness) {
-        // Local workspace whose AGENTS.md the harness will not load. With a
-        // borrowed harness cwd, agent tool scripts live only in the durable
-        // scaffold dir — embed bodies like cloud. Otherwise the catalog can
-        // reference on-disk paths under the harness cwd. Grokbot turns are
-        // excluded: their instructions ride the request's `instructions`
-        // field into the Sand system prompt instead.
-        const includeScripts = this.hasBorrowedWorkspace(record);
-        const preamble = buildAgentsMdContent(agent, { includeScripts });
-        turnPrompt = `${preamble}\n\n${turnPrompt}`;
+      } else if (pending !== undefined && Object.keys(pending).length > 0) {
+        await this.clearPendingWorkspaceFiles(record.sessionId, pending);
+      }
+      if (isFirstTurn && hosted) {
+        sections.push(buildCloudMemorySection(this.project.name));
       }
+      if (preamble !== "" || sections.length > 0) {
+        turnPrompt = [preamble, ...sections, turnPrompt]
+          .filter((part) => part !== "")
+          .join("\n\n");
+      }
+    } else if (isFirstTurn && runtime === "local" && authoredRoot) {
+      // Virtual roots skip materialize, so AGENTS.md never lands on disk.
+      // Ship the same preamble the borrowed-cwd local path uses.
+      const preamble = buildAgentsMdContent(
+        { ...agent, tools: [...agent.tools, ...synthesized] },
+        { includeScripts: true }
+      );
+      const workspaceInfo = `<user_info>\nWorkspace Path: /\n</user_info>`;
+      turnPrompt =
+        preamble === ""
+          ? `${workspaceInfo}\n\n${turnPrompt}`
+          : `${workspaceInfo}\n\n${preamble}\n\n${turnPrompt}`;
+    } else if (
+      isFirstTurn &&
+      runtime === "local" &&
+      instructionsInvisibleToHarness
+    ) {
+      // Local workspace whose AGENTS.md the harness will not load. With a
+      // borrowed harness cwd, agent tool scripts live only in the durable
+      // scaffold dir — embed bodies like cloud. Otherwise the catalog can
+      // reference on-disk paths under the harness cwd. Grokbot turns are
+      // excluded: their instructions ride the request's `instructions`
+      // field into the Sand system prompt instead.
+      const includeScripts = this.hasBorrowedWorkspace(record);
+      const preamble = buildAgentsMdContent(agent, { includeScripts });
+      turnPrompt = `${preamble}\n\n${turnPrompt}`;
     }
     return {
       sessionId: record.sessionId,
@@ -2392,9 +2875,18 @@ export class SessionEngine {
         ? {}
         : { sdkAgentId: record.sdkAgentId }),
       workspaceDir: this.harnessCwd(record),
-      sandbox: this.project.agent.local?.sandbox === true,
-      ...(runtime === "local" && agent.allowedTools !== undefined
-        ? { tools: agent.allowedTools }
+      sandbox: authoredRoot
+        ? false
+        : this.project.agent.local?.sandbox === true,
+      ...(runtime === "local" && harnessTools !== undefined
+        ? {
+            ...(harnessTools.tools === undefined
+              ? {}
+              : { tools: harnessTools.tools }),
+            ...(harnessTools.disallowedTools === undefined
+              ? {}
+              : { disallowedTools: harnessTools.disallowedTools }),
+          }
         : {}),
       runnerStateDir: join(this.stateRoot, "runner"),
       prompt: turnPrompt,
@@ -2418,7 +2910,13 @@ export class SessionEngine {
         : {}),
       customTools:
         runtime === "local"
-          ? await this.buildCustomTools(record, agent, turnId, emit)
+          ? await this.buildCustomTools(
+              record,
+              agent,
+              turnId,
+              emit,
+              synthesized
+            )
           : {},
       mcpServers: this.buildMcpServers(
         runtime,
@@ -2712,7 +3210,8 @@ export class SessionEngine {
     record: SessionRecord,
     agent: ResolvedAgent,
     turnId: string,
-    emit: (payload: SessionEventPayload) => void
+    emit: (payload: SessionEventPayload) => void,
+    extraTools: DiscoveredTool[] = []
   ): Promise<Record<string, SDKCustomTool>> {
     const tools: Record<string, SDKCustomTool> = {};
     const register = (tool: ResolvedAgent["tools"][number]): void => {
@@ -2742,7 +3241,7 @@ export class SessionEngine {
         },
       };
     };
-    for (const tool of agent.tools) {
+    for (const tool of [...agent.tools, ...extraTools]) {
       if (tool.execution !== "server") {
         continue;
       }
@@ -3682,6 +4181,27 @@ export class SessionEngine {
     const session = identity.session;
     let workspaceDir = identity.workspaceDir;
     let scratchDir = identity.scratchDir;
+    if (
+      isFileSystemToolAlias(toolName) &&
+      identity.busy &&
+      record !== undefined &&
+      isMutatingFileSystemTool(toolName)
+    ) {
+      throw new SessionBusyError(record.sessionId);
+    }
+    const native = await this.nativeFileSystemOutcome({
+      toolName,
+      input,
+      callId,
+      sessionId: record?.sessionId,
+      continuationKey:
+        record?.continuationKey ?? session.continuationKey ?? undefined,
+      cwd: workspaceDir,
+      dryRun: record?.dryRun === true,
+    });
+    if (native !== undefined) {
+      return native;
+    }
     let tool = this.project.agent.tools.find((t) => t.name === toolName);
     if (
       tool === undefined &&
@@ -3783,7 +4303,10 @@ export class SessionEngine {
       record !== undefined &&
       identity.busy &&
       this.materializedWorkspaces.has(record.sessionId);
-    if (record === undefined || workspaceUnavailable || !turnMaterialized) {
+    if (
+      !this.hasRootOverride() &&
+      (record === undefined || workspaceUnavailable || !turnMaterialized)
+    ) {
       await materializeWorkspace({
         agent: this.project.agent,
         workspaceDir:
@@ -4745,9 +5268,8 @@ export class SessionEngine {
     }
     const record = await this.sessions.get(sessionId);
     const sdkAgentId =
-      (record?.sdkAgentId !== undefined && record.sdkAgentId.startsWith("bc-")
-        ? record.sdkAgentId
-        : undefined) ?? cloudSdkAgentIdFromEvents(events);
+      (record?.sdkAgentId?.startsWith("bc-") ? record.sdkAgentId : undefined) ??
+      cloudSdkAgentIdFromEvents(events);
     if (sdkAgentId === undefined) {
       return;
     }