@cjhyy/code-shell-core 0.6.0-rc.9 → 0.7.0

package/dist/engine/engine.js

@@ -23,7 +23,7 @@ import { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend, Int
 import { HookRegistry } from "../hooks/registry.js";
 import { wrapHookMessages } from "../hooks/inject.js";
 import { createGoalStopHook } from "../hooks/goal-stop-hook.js";
-import { normalizeGoal, resolveGoalSetAt, resolveMaxTurns, resolveMaxStopBlocks, } from "./goal.js";
+import { normalizeGoal, resolveGoalSetAt, resolveMaxTurns, resolveMaxStopBlocks, isSameGoalInstance, } from "./goal.js";
 import { loadPluginHooks } from "../plugins/loadPluginHooks.js";
 import { pluginAgentDirs } from "../plugins/installer/loadPluginAgents.js";
 import { patchOrphanedToolUses } from "./patch-orphaned-tools.js";
@@ -34,34 +34,35 @@ import { PLAN_MODE_ALLOWED_TOOLS } from "../tool-system/plan-mode-allowlist.js";
 import { PromptComposer } from "../prompt/composer.js";
 import { SessionManager } from "../session/session-manager.js";
 import { ModelFacade } from "./model-facade.js";
-import { logger, setCurrentSid, runWithSid, getCurrentSid } from "../logging/logger.js";
+import { logger, runWithSid, getCurrentSid } from "../logging/logger.js";
 import { recordSessionStart, recordSessionEnd } from "../logging/session-recorder.js";
 import { sanitizeContent, sanitizeTaskString } from "../logging/sanitize-messages.js";
 import { TurnLoop } from "./turn-loop.js";
 import { MCPManager } from "../tool-system/mcp-manager.js";
 import { SettingsManager, userHome } from "../settings/manager.js";
-import { CredentialStore } from "../credentials/store.js";
+import { getCredentialAccess } from "../credentials/access.js";
 import { isFeatureEnabled, resolveFeatureFlags, } from "../settings/feature-flags.js";
-import { effectiveDisabledList, effectiveBuiltinLists, } from "../capability-control/overlay.js";
+import { effectiveDisabledList, effectiveBuiltinLists } from "../capability-control/overlay.js";
 import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
 import { FileHistory } from "../session/file-history.js";
 import { patchBackupTargets } from "../tool-system/builtin/apply-patch/backup-targets.js";
 import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
-import { resolveAgentPreset, resolveBuiltinToolNames, } from "../preset/index.js";
+import { resolveAgentPreset, resolveBuiltinToolNames } from "../preset/index.js";
 import { ModelPool } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
 import { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
-import { parseTaskWithImages } from "./parse-task.js";
-import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, collectAttachedImagePaths, } from "./image-policy.js";
-import { tryCompressImages } from "./image-compression.js";
 import { buildSessionTitle } from "./session-title.js";
-import { capabilitiesFor } from "../llm/capabilities/index.js";
 import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
 import { runDreamConsolidation } from "../services/dream-consolidation.js";
-import { join, isAbsolute } from "node:path";
+import { buildRunUserMessageContent, prepareRunImageInput } from "./run-image-input.js";
+import { join } from "node:path";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+const CACHE_READ_DROP_MIN_PREVIOUS_TOKENS = 100;
+const CACHE_READ_DROP_MAX_CURRENT_TOKENS = 64;
+const CACHE_READ_DROP_RATIO = 0.1;
+const CACHE_READ_DIAGNOSTIC_MAX_SESSIONS = 256;
 /**
  * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
  * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
@@ -129,7 +130,7 @@ export function resolveChildLlm(modelKey, pool, parentLlm) {
  * Names in `disabledAgents` are filtered out so the LLM never sees them.
  */
 /**
- * Resolve the working directory for a run. Precedence:
+ * Resolve the working directory for a run. Precedence for legacy sessions:
  *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
  *
  * The session-cwd tier is what stops a project-bound session from being
@@ -265,6 +266,7 @@ export class Engine {
      * LLM response arrives.
      */
     ctxOverheadBySid = new Map();
+    lastCacheReadBySid = new Map();
     /**
      * Step-gap steering queue (per sessionId, in-memory). Host pushes user
      * messages here via enqueueSteer while a run is in flight; the turn loop
@@ -445,6 +447,7 @@ export class Engine {
                 new ToolRegistry({
                     builtinTools: resolveBuiltinToolNames({
                         preset: this.preset.name,
+                        host: config.builtinToolHost,
                         enabledBuiltinTools: builtinLists.enabledBuiltinTools,
                         disabledBuiltinTools: builtinLists.disabledBuiltinTools,
                     }),
@@ -635,6 +638,10 @@ export class Engine {
     setBrowserBridge(bridge) {
         this.config.browserBridge = bridge;
     }
+    /** Inject the host-backed workspace bridge after construction. */
+    setWorkspaceBridge(bridge) {
+        this.config.workspaceBridge = bridge;
+    }
     /**
      * Queue a user message to be spliced into the in-flight run for `sessionId`
      * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
@@ -648,7 +655,7 @@ export class Engine {
      * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
      * entry. A blank id is tolerated but means the entry can't be revoked.
      */
-    enqueueSteer(sessionId, text, id = "", clientMessageId) {
+    enqueueSteer(sessionId, text, id = "", clientMessageId, attachments) {
         const q = this.steerQueueBySid.get(sessionId) ?? [];
         const entryId = id || `steer-${q.length}`;
         if (!sessionId)
@@ -660,12 +667,13 @@ export class Engine {
                 sessionId,
                 id: entryId,
                 clientMessageId,
+                attachmentCount: attachments?.length ?? 0,
                 activeRunSessionId: activeRunSessionId ?? null,
                 queueLength: q.length,
             });
             return { accepted: false, id: entryId };
         }
-        const next = enqueueSteerItem(q, entryId, text, clientMessageId);
+        const next = enqueueSteerItem(q, entryId, text, clientMessageId, attachments);
         if (next === q)
             return { accepted: false, id: entryId }; // blank text dropped
         this.steerQueueBySid.set(sessionId, next);
@@ -673,6 +681,7 @@ export class Engine {
             sessionId,
             id: entryId,
             clientMessageId,
+            attachmentCount: attachments?.length ?? 0,
             activeRunSessionId,
             queueLength: next.length,
         });
@@ -709,6 +718,13 @@ export class Engine {
         });
         return drained;
     }
+    /** Put failed steer preparation back ahead of messages queued while it was being prepared. */
+    restoreSteer(sessionId, items) {
+        if (items.length === 0)
+            return;
+        const queued = this.steerQueueBySid.get(sessionId) ?? [];
+        this.steerQueueBySid.set(sessionId, [...items, ...queued]);
+    }
     /** Wire the cookie→browser injection callback (InjectCredential tool). Same
      *  post-construction injection model as setBrowserBridge. */
     setInjectCredential(fn) {
@@ -735,20 +751,45 @@ export class Engine {
      * Run a task from start to finish.
      */
     async run(task, options) {
-        // When the caller omits cwd but is resuming an existing session, recover
-        // that session's bound cwd from disk so a project-bound session keeps
-        // loading its own agents/settings/memory even if the host's UI repo
-        // selection has drifted to null. Only probe on omission — an explicit cwd
-        // always wins, and a fresh session has nothing to recover.
-        const sessionCwd = options?.cwd === undefined && options?.sessionId
-            ? this.sessionManager.readCwd(options.sessionId)
+        const workspaceResume = options?.sessionId && this.sessionManager.exists(options.sessionId)
+            ? await this.sessionManager.resolveSessionWorkspaceForResume(options.sessionId)
             : undefined;
-        const cwd = resolveRunCwd({
-            optionCwd: options?.cwd,
-            sessionCwd,
-            configCwd: this.config.cwd,
-            processCwd: process.cwd(),
-        });
+        if (workspaceResume && !workspaceResume.ok) {
+            return {
+                text: `ERROR: ${workspaceResume.message}`,
+                reason: "completed",
+                sessionId: options.sessionId,
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            };
+        }
+        if (workspaceResume?.ok &&
+            workspaceResume.reason === "worktree_missing_branch_gone" &&
+            workspaceResume.message) {
+            return {
+                text: workspaceResume.message,
+                reason: "completed",
+                sessionId: options.sessionId,
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            };
+        }
+        // Existing P1 sessions resolve cwd from SessionWorkspace, even if the host
+        // passes a stale cwd. Legacy sessions without workspace keep the historical
+        // explicit-cwd precedence for backward compatibility.
+        const workspaceCwd = workspaceResume?.ok && workspaceResume.reason !== "legacy" ? workspaceResume.cwd : undefined;
+        const sessionCwd = workspaceCwd === undefined && options?.cwd === undefined && options?.sessionId
+            ? workspaceResume?.ok
+                ? workspaceResume.cwd
+                : this.sessionManager.readCwd(options.sessionId)
+            : undefined;
+        const cwd = workspaceCwd ??
+            resolveRunCwd({
+                optionCwd: options?.cwd,
+                sessionCwd,
+                configCwd: this.config.cwd,
+                processCwd: process.cwd(),
+            });
         // Wrap the caller's onStream so we can intercept `task_update`
         // events emitted by TodoWrite and keep an in-engine snapshot.
         // TaskGuard reads this snapshot at turn end to decide whether to
@@ -776,115 +817,16 @@ export class Engine {
         };
         if (options)
             options.onStream = wrappedOnStream;
-        // ── P2-6: image input ─────────────────────────────────────────────
-        // Parse `<codeshell-image>` blocks out of the raw task string before
-        // any other gate looks at it. Two concerns:
-        //   1. The noise detector below sees the raw base64 as gibberish and
-        //      would reject the whole turn — split images out first so it
-        //      only inspects the prose portion.
-        //   2. Models that don't accept vision must be refused immediately,
-        //      with the image bytes intact for the user to retry on another
-        //      model. Silent text-only fallback was the failure mode this
-        //      gate is here to prevent.
-        let parsedTask;
-        try {
-            parsedTask = parseTaskWithImages(task);
-        }
-        catch (err) {
-            const msg = err.message;
-            logger.warn("engine.run.image_parse_failed", { error: msg });
-            return {
-                text: `ERROR: image attachment is malformed (${msg}). Drop the image and try again, or re-attach it.`,
-                reason: "image_error",
-                sessionId: options?.sessionId ?? "image-parse-failed",
-                turnCount: 0,
-                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-            };
-        }
-        if (parsedTask.hasImages) {
-            const cap = capabilitiesFor((this.config.llm.providerKind ?? this.config.llm.provider), this.config.llm.model);
-            if (!cap.supportsVision) {
-                logger.warn("engine.run.vision_not_supported", {
-                    provider: this.config.llm.provider,
-                    model: this.config.llm.model,
-                    imageCount: parsedTask.images.length,
-                });
-                return {
-                    text: `ERROR: model "${this.config.llm.model}" does not accept image input. ` +
-                        `Switch to a vision-capable model (e.g. gpt-4o, claude-sonnet, gemini-1.5-pro) and resend.`,
-                    reason: "image_error",
-                    sessionId: options?.sessionId ?? "vision-not-supported",
-                    turnCount: 0,
-                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-                };
-            }
-            // Size gate. Hosts (desktop renderer, TUI) are expected to
-            // pre-compress to IMAGE_TARGETS — if they didn't, we fail the turn
-            // fast with a clear message instead of letting the OpenAI client
-            // grind through three 16-second "Connection error" retries on a
-            // 4 MB body. See `image-policy.ts` for the rationale and limits.
-            let verdict = enforceImagePolicy(parsedTask.images);
-            if (!verdict.ok && verdict.code === "image_too_large") {
-                // One image blew the per-image cap. Try the engine-side
-                // compressor (jimp-backed when installed; no-op otherwise) so
-                // TUI / MCP paths that lack a host-side resize don't fail
-                // outright on a screenshot they could have rescaled. The
-                // re-check below is what decides whether we proceed.
-                const compressed = await tryCompressImages(parsedTask.images);
-                if (compressed.anyCompressed) {
-                    parsedTask.images = compressed.images;
-                    logger.info("engine.run.image_compressed", {
-                        before: verdict.offender?.bytes,
-                        after: compressed.images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
-                    });
-                    verdict = enforceImagePolicy(parsedTask.images);
-                }
-            }
-            // After compression, anything still over the per-image cap is
-            // dropped with a textual placeholder instead of failing the
-            // turn (TODO-week.md #9e). The "5MB brick session" failure
-            // mode from Claude Code (research doc §A) was the case where a
-            // poisoned image entered history and every subsequent request
-            // re-sent it; placeholders keep history clean while letting
-            // the rest of the turn run.
-            if (!verdict.ok && verdict.code === "image_too_large") {
-                const drop = dropOversizedImages(parsedTask.images);
-                if (drop.droppedCount > 0) {
-                    parsedTask.images = drop.kept;
-                    parsedTask.hasImages = drop.kept.length > 0;
-                    parsedTask.text = drop.placeholder + "\n\n" + parsedTask.text;
-                    logger.warn("engine.run.image_dropped", {
-                        droppedCount: drop.droppedCount,
-                        keptCount: drop.kept.length,
-                    });
-                    verdict = enforceImagePolicy(parsedTask.images);
-                }
-            }
-            if (!verdict.ok) {
-                // Cumulative / count caps can't be rescued by per-image
-                // dropping (well — too_many_images could trim by FIFO, but
-                // that's a bigger UX call than we want to make silently).
-                // Refuse the turn with the policy message.
-                logger.warn("engine.run.image_policy_failed", {
-                    code: verdict.code,
-                    imageCount: verdict.totals.imageCount,
-                    totalBytes: verdict.totals.totalBytes,
-                    offender: verdict.offender,
-                });
-                return {
-                    text: `ERROR: ${verdict.message}`,
-                    reason: "image_error",
-                    sessionId: options?.sessionId ?? `image-policy-${verdict.code}`,
-                    turnCount: 0,
-                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-                };
-            }
-        }
-        // For downstream noise-detection + transcript persistence we want the
-        // *text* portion only — base64 bytes count as "noise" by the heuristic
-        // and would also bloat the transcript by megabytes per image. Image
-        // bytes ride in parsedTask.images and re-enter the message tree below.
-        const taskText = parsedTask.hasImages ? parsedTask.text : task;
+        const imageInput = await prepareRunImageInput({
+            task,
+            cwd,
+            llm: this.config.llm,
+            sessionId: options?.sessionId,
+            attachments: options?.attachments,
+        });
+        if (!imageInput.ok)
+            return imageInput.result;
+        const { parsedTask, taskText } = imageInput;
         const noise = detectPastedNoise(taskText);
         if (noise.isNoise) {
             const hint = `Your input looks like pasted terminal output (${noise.reason}). ` +
@@ -946,6 +888,7 @@ export class Engine {
                     preset: this.preset.name,
                     enabledBuiltinTools: childEnabled,
                     disabledBuiltinTools: childDisabled,
+                    builtinToolHost: this.config.builtinToolHost,
                     customSystemPrompt: this.config.customSystemPrompt,
                     appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt].filter(Boolean).join("\n\n") ||
                         undefined,
@@ -1013,23 +956,7 @@ export class Engine {
             },
             sessionExists: (sessionId) => this.sessionManager.exists(sessionId),
         };
-        // Priority: config.sandbox → project settings.sandbox → global → per-run
-        // default. Read UNMERGED per-scope (getForScope) so a project that wrote no
-        // sandbox genuinely follows global, rather than inheriting global's mode and
-        // looking like it set one. Fixes "项目级配了不生效" + the scope model.
-        let projectSandbox;
-        let globalSandbox;
-        try {
-            const sm = this.getSettingsManager();
-            if (this.config.isSubAgent !== true) {
-                projectSandbox = sm.getForScope("project", cwd).sandbox;
-            }
-            globalSandbox = sm.getForScope("user").sandbox;
-        }
-        catch {
-            // settings unavailable → fall through to per-run default
-        }
-        const sandboxConfig = resolveSandboxConfig(this.config.sandbox, projectSandbox, globalSandbox, this.config.headless === true);
+        const sandboxConfig = this.resolveSandboxConfigForCwd(cwd);
         // A2: explicit sandbox modes (seatbelt, bwrap) must fail closed
         // per standard §S4. resolveSandboxBackend throws when an explicit
         // mode is unavailable on this host; we let it propagate. The
@@ -1070,12 +997,16 @@ export class Engine {
                 ? sandboxBackend
                 : { ...sandboxBackend, network: sandboxConfig.network },
             cwd,
+            shellEnv: this.readShellEnv(cwd),
             // TodoWrite reads this to push task_update events independently
             // of its return value, so the UI's pinned task panel refreshes
             // immediately rather than after the LLM next surfaces the
             // snapshot. wrappedOnStream snoops the same channel to keep
             // latestTodos current for TaskGuard.
             streamCallback: options?.onStream,
+            setCwd(nextCwd) {
+                toolCtx.cwd = nextCwd;
+            },
         };
         logger.info("engine.run", {
             task: taskText.slice(0, 200),
@@ -1084,40 +1015,7 @@ export class Engine {
             preset: this.preset.name,
             imageCount: parsedTask.images.length,
         });
-        // Compose the user-turn payload once so resume + cold paths agree on
-        // shape. With images, content becomes a ContentBlock[] holding one
-        // text block (when prose is present) followed by one image block per
-        // attachment — the provider-specific clients translate this to OpenAI
-        // `image_url` or Anthropic `{type:image, source:base64}` downstream.
-        // When an attached image came from a workspace FILE (the desktop composer's
-        // path-attach flow sets ParsedImage.name = the absolute path), surface that
-        // path to the model as text. The image bytes still ride along for vision,
-        // but tools that operate on files — GenerateImage(referenceImages),
-        // Read, etc. — need the on-disk path, not just the pixels. Without this the
-        // path the composer already knew was silently dropped, and the model would
-        // answer "图片没落到项目文件夹，找不到路径" (the seedance 图生图 dead-end).
-        // Only names that resolve to an existing file qualify; a pasted screenshot
-        // whose name is just "screenshot.png" is not a path and is left out.
-        const attachedPaths = collectAttachedImagePaths(parsedTask.images, (name) => (isAbsolute(name) ? name : join(cwd, name)), existsSync);
-        const pathHint = attachedPaths.length > 0
-            ? `\n\n<attached-image-paths>\n${attachedPaths.join("\n")}\n</attached-image-paths>\n` +
-                `(上面附带的图片在工作区的真实路径，如需把它们作为工具输入（例如 GenerateImage 的 referenceImages、图生图参考图），直接使用这些路径。)`
-            : "";
-        const userMessageContent = parsedTask.hasImages
-            ? [
-                ...(parsedTask.text || pathHint
-                    ? [{ type: "text", text: `${parsedTask.text}${pathHint}` }]
-                    : []),
-                ...parsedTask.images.map((img) => ({
-                    type: "image",
-                    source: {
-                        type: "base64",
-                        media_type: img.mime,
-                        data: img.base64,
-                    },
-                })),
-            ]
-            : taskText;
+        const userMessageContent = buildRunUserMessageContent(parsedTask, cwd, taskText);
         // Create or resume session.
         //
         // Three valid shapes:
@@ -1134,6 +1032,7 @@ export class Engine {
         let session;
         let messages;
         let freshImageMessage;
+        let resumedFromDisk = false;
         const claimedClientMessageIds = new Set();
         const claimClientMessageId = (bundle, clientMessageId, source) => {
             if (!clientMessageId)
@@ -1151,6 +1050,7 @@ export class Engine {
             return true;
         };
         if (options?.sessionId && this.sessionManager.exists(options.sessionId)) {
+            resumedFromDisk = true;
             session = this.sessionManager.resume(options.sessionId);
             const cachedCompacted = this.compactedMessagesBySession.get(options.sessionId);
             messages = cachedCompacted ? [...cachedCompacted] : session.transcript.toMessages();
@@ -1233,28 +1133,22 @@ export class Engine {
         // with this value so `/undo` reverts exactly this turn's file changes.
         // (Both resume and cold-start paths converge here.)
         session.state.turnSeq = (session.state.turnSeq ?? 0) + 1;
-        // Stamp the resolved session id for downstream logging.
-        //
-        // `setCurrentSid` updates the module-level fallback so any code path
-        // running outside an ALS scope (bootstrap, /sid before a run starts)
-        // still sees the latest sid.
-        //
-        // The real isolation comes from wrapping the rest of `run` in
-        // `runWithSid(sid, async () => { ... })`: every `getCurrentSid()`
-        // call inside that closure — including those inside `await`ed child
-        // Engine.run() calls — reads sid from this scope's
-        // AsyncLocalStorage binding, not the module global. Sibling Engines
-        // running concurrently each get their own scope; an `enterSid` inside
-        // a child mutates that child's scope only and doesn't leak back to
-        // the parent's chain after `await child.run(...)` returns.
-        setCurrentSid(session.state.sessionId);
         // B2 / Gate 1: stamp the resolved sid onto the tool context so
         // session-scoped side effects (background-agent completion
         // notifications) attribute to the right session. toolCtx is created
         // before the session bundle is resolved (see ~line 635), so this is
         // the first point we can set it. After this assignment treat the
-        // field as immutable for the rest of the run.
+        // field follows the latest successfully injected user intent for the rest
+        // of the run, so tools launched after a steer attribute their side effects
+        // to that steer rather than this original submit.
         toolCtx.sessionId = session.state.sessionId;
+        toolCtx.originClientMessageId = options?.clientMessageId;
+        toolCtx.recordExternalFileChanges = (record) => {
+            session.transcript.append("external_file_changes", { ...record });
+        };
+        toolCtx.setSessionWorkspace = (workspace) => {
+            session.state.workspace = workspace;
+        };
         return runWithSid(session.state.sessionId, async () => {
             recordSessionStart(session.state.sessionId, {
                 // Strip <codeshell-image> base64 payloads before they reach
@@ -1265,7 +1159,7 @@ export class Engine {
                 model: this.config.llm.model,
                 provider: this.config.llm.provider,
                 permissionMode: this.config.permissionMode ?? "acceptEdits",
-                resumed: !!options?.sessionId,
+                resumed: resumedFromDisk,
             });
             // Session-level hook: fired once per Engine.run() entry, regardless of
             // cold-start vs resume. Handlers can return `messages` to inject a
@@ -1275,7 +1169,8 @@ export class Engine {
             const sessionStartHook = await this.emitHook("on_session_start", {
                 sessionId: session.state.sessionId,
                 cwd,
-                resumed: !!options?.sessionId,
+                resumed: resumedFromDisk,
+                source: resumedFromDisk ? "resume" : "startup",
             });
             // Per-turn hook: fired every time a new user prompt enters the loop.
             // Equivalent to CC's UserPromptSubmit. Handlers can inject lightweight
@@ -1289,7 +1184,7 @@ export class Engine {
                 // and silently leaking attachment bytes through hooks is the kind of
                 // exfiltration risk a curious user-installed shell hook shouldn't carry.
                 prompt: taskText,
-                resumed: !!options?.sessionId,
+                resumed: resumedFromDisk,
             });
             // updatedPrompt: handler rewrote the user's prompt text. Replace the
             // last user message we just pushed (cold-start: line ~511; resume:
@@ -1307,22 +1202,49 @@ export class Engine {
                     messages[lastIdx] = { role: "user", content: promptSubmitHook.updatedPrompt };
                 }
             }
-            // Rough token estimate of the full prompt so the UI's ctx bar isn't 0%
-            // before the first real usage_update arrives. The authoritative count
+            const contextManager = new ContextManager({
+                maxTokens: this.resolveMaxContextTokens(),
+                // Drop undefined fields so they don't clobber ContextManager defaults
+                // (spread of `{x: undefined}` would override the default with undefined).
+                ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
+            });
+            this.lastContextManager = contextManager;
+            const persistedContextAnchor = session.state.contextUsageAnchor;
+            const contextAnchorCompatible = persistedContextAnchor !== undefined &&
+                (persistedContextAnchor.provider === undefined ||
+                    persistedContextAnchor.provider === this.config.llm.provider) &&
+                (persistedContextAnchor.model === undefined ||
+                    persistedContextAnchor.model === this.config.llm.model) &&
+                (persistedContextAnchor.messageCount <= messages.length ||
+                    persistedContextAnchor.estimateAtAnchor !== undefined);
+            if (contextAnchorCompatible) {
+                contextManager.seedActualUsage(persistedContextAnchor);
+            }
+            // Best-effort token estimate of the full prompt so the UI's ctx bar isn't
+            // 0% before the first real usage_update arrives. The authoritative count
             // comes from `usage.promptTokens` after the first LLM response — this is
-            // just a display-friendly approximation for the first frame.
+            // just a display-friendly approximation for the first frame, annotated
+            // with source/confidence so consumers don't treat heuristics as truth.
             //
             // Only seed once per (process, sid). On subsequent turns the UI already
-            // shows the previous turn's accurate ctx; overwriting it with this rough
-            // char/4 estimate would make the bar visibly drop on every submit.
+            // shows the previous turn's accurate ctx; overwriting it with a fresh
+            // best-effort estimate would make the bar visibly drop on every submit.
             const sid = session.state.sessionId;
             const needsCtxSeed = !this.ctxSeedSent.has(sid);
-            const roughPromptTokens = needsCtxSeed
-                ? messages.reduce((sum, m) => {
-                    const text = typeof m.content === "string" ? m.content : JSON.stringify(m.content);
-                    return sum + Math.ceil(text.length / 4);
-                }, 0)
-                : 0;
+            const ctxSeed = needsCtxSeed
+                ? (() => {
+                    const checked = contextManager.checkLimits(messages);
+                    return {
+                        tokens: checked.tokens,
+                        source: checked.promptTokensSource,
+                        confidence: checked.promptTokensConfidence,
+                    };
+                })()
+                : {
+                    tokens: 0,
+                    source: "heuristic_estimate",
+                    confidence: "low",
+                };
             if (needsCtxSeed)
                 this.ctxSeedSent.add(sid);
             // Tell the client the sid *now* instead of waiting for run() to resolve.
@@ -1331,7 +1253,9 @@ export class Engine {
             options?.onStream?.({
                 type: "session_started",
                 sessionId: sid,
-                promptTokens: roughPromptTokens,
+                promptTokens: ctxSeed.tokens,
+                promptTokensSource: ctxSeed.source,
+                promptTokensConfidence: ctxSeed.confidence,
             });
             // Replay the last TodoWrite snapshot on resume so the UI's pinned
             // task panel re-hydrates without the LLM needing to call TodoWrite
@@ -1358,12 +1282,14 @@ export class Engine {
             // in this same session don't re-prompt. Headless/auto backends skip
             // this — they don't prompt, so there are no project rules to persist.
             if (approvalBackend instanceof InteractiveApprovalBackend) {
-                approvalBackend.setCwd(cwd);
-                approvalBackend.setOnProjectRules((rules) => {
-                    // Prepend the *full* accumulated list of session-saved project rules
-                    // so user approvals win over defaults and earlier approvals aren't
-                    // dropped when later ones come in.
-                    permission.reconfigure(mode, approvalBackend, [...rules, ...defaultRules]);
+                approvalBackend.setSessionContext(session.state.sessionId, {
+                    cwd,
+                    onProjectRules: (rules) => {
+                        // Prepend the *full* accumulated list of session-saved project rules
+                        // so user approvals win over defaults and earlier approvals aren't
+                        // dropped when later ones come in.
+                        permission.reconfigure(mode, approvalBackend, [...rules, ...defaultRules]);
+                    },
                 });
             }
             const toolExecutor = new ToolExecutor(this.toolRegistry, permission, this.hooks);
@@ -1379,13 +1305,6 @@ export class Engine {
             // Wire abort signal for cascading cancellation + per-Engine ToolContext
             toolExecutor.setSignal(options?.signal);
             toolExecutor.setContext(toolCtx);
-            const contextManager = new ContextManager({
-                maxTokens: this.resolveMaxContextTokens(),
-                // Drop undefined fields so they don't clobber ContextManager defaults
-                // (spread of `{x: undefined}` would override the default with undefined).
-                ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
-            });
-            this.lastContextManager = contextManager;
             const { disabledSkills, disabledPlugins } = this.readDisabledLists();
             const promptComposer = new PromptComposer({
                 cwd,
@@ -1447,6 +1366,7 @@ export class Engine {
                     (normalizeGoal(options?.goal) !== undefined ||
                         session.state.activeGoal !== undefined ||
                         normalizeGoal(this.config.goal) !== undefined),
+                settingsScope: this.config.settingsScope ?? "project",
             };
             toolCtx.toolVisibility = toolVisibility;
             // #7: per-turn project builtin override. The toolRegistry's builtin tool
@@ -1664,17 +1584,20 @@ export class Engine {
             // Goal mode: register a GoalStopHook for the lifetime of THIS run so the
             // turn loop keeps going until the session model judges the goal met.
             // Registered per-run (and cleared in `finally`) so a later goal-less
-            // send doesn't inherit a stale goal. The judge runs on `auxSummaryClient`
-            // — the same cheap aux model used for summarize/compaction — not the
-            // (potentially expensive) session model: "is this goal met?" is a classic
-            // aux-tier task, and a goal run can invoke the judge up to maxStopBlocks
-            // times.
+            // send doesn't inherit a stale goal. The judge runs on the primary
+            // session client; auxSummaryClient remains dedicated to low-consequence
+            // summaries/titles and retains defaults.auxText routing/fallback behavior.
             // Normalize the raw goal (string | GoalConfig) once at the run boundary;
             // everything inward uses the GoalConfig. normalizeGoal() returns undefined
             // when there's effectively no goal (empty objective).
             //
             // PERSISTENT GOAL (CC /goal style): a goal set on one send survives across
-            // later sends and manual interrupts until met or cleared. Resolution:
+            // later sends and manual interrupts until met or cleared. Goal completion
+            // is a high-consequence decision, so V1 routes it to the primary session
+            // client, which is the model expected to interpret the supplied execution
+            // evidence. defaults.auxText remains in force for summaries, titles and
+            // other auxiliary work through auxSummaryClient.
+            // Resolution:
             //   1. options.goal — this send explicitly sets/replaces the goal.
             //   2. session.state.activeGoal — a goal set on an earlier send.
             //   3. config.goal — engine-level default (rare; e.g. headless).
@@ -1683,7 +1606,15 @@ export class Engine {
             // bare send with no options.goal inherits the stored active goal so the
             // model keeps working toward it — that's what makes it persistent.
             const explicitGoal = normalizeGoal(options?.goal);
-            const storedGoal = this.config.isSubAgent !== true ? session.state.activeGoal : undefined;
+            let storedGoal = this.config.isSubAgent !== true ? session.state.activeGoal : undefined;
+            // Defense in depth: a stale whole-state writer may have restored the
+            // activeGoal field after this exact goal instance was force-terminated.
+            // Refuse to arm it and converge the live bundle before hook registration.
+            if (storedGoal && isSameGoalInstance(storedGoal, session.state.goalTerminal)) {
+                session.state.activeGoal = undefined;
+                storedGoal = undefined;
+                this.sessionManager.saveState(session.state);
+            }
             if (explicitGoal && this.config.isSubAgent !== true) {
                 const replaced = !!storedGoal && storedGoal.objective !== explicitGoal.objective;
                 // Stamp WHEN this goal was set so the judge can anchor relative deadlines
@@ -1692,7 +1623,14 @@ export class Engine {
                 // or changed objective gets a fresh stamp; re-sending the SAME objective
                 // keeps the original anchor (the goal continues, the user didn't restate a
                 // new deadline). User input never carries setAtMs, so we set it here.
-                explicitGoal.setAtMs = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
+                const resolvedSetAt = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
+                // A user explicitly re-starting the same objective creates a new goal
+                // instance. Avoid a same-millisecond collision with its old tombstone.
+                explicitGoal.setAtMs =
+                    session.state.goalTerminal?.objective === explicitGoal.objective &&
+                        session.state.goalTerminal.setAtMs === resolvedSetAt
+                        ? resolvedSetAt + 1
+                        : resolvedSetAt;
                 session.state.activeGoal = explicitGoal;
                 this.sessionManager.saveState(session.state);
                 options?.onStream?.({
@@ -1702,18 +1640,27 @@ export class Engine {
                 });
             }
             const normalizedGoal = explicitGoal ?? storedGoal ?? normalizeGoal(this.config.goal);
+            // Snapshot the persisted goal identity owned by THIS run. Terminal
+            // cleanup compares against this immutable copy so an old run cannot
+            // delete a replacement goal installed while it was finishing.
+            const persistedRunGoal = normalizedGoal && isSameGoalInstance(session.state.activeGoal, normalizedGoal)
+                ? { ...normalizedGoal }
+                : undefined;
             let goalHookHandler = null;
+            let goalJudgeContext;
             if (normalizedGoal && this.config.isSubAgent !== true) {
                 goalHookHandler = createGoalStopHook({
                     goal: normalizedGoal,
-                    llm: auxSummaryClient,
+                    llm: llmClient,
                     log: logger,
+                    getJudgeContext: () => goalJudgeContext,
                     // Clear the persisted active goal the moment the judge says it's met,
                     // so a later bare send doesn't re-inherit a satisfied goal. The hook
                     // calls this from inside its met branch (single source of truth for
                     // "goal achieved"); engine owns the persistence side-effect.
                     onMet: () => {
-                        if (session.state.activeGoal) {
+                        if (persistedRunGoal &&
+                            isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
                             session.state.activeGoal = undefined;
                             this.sessionManager.saveState(session.state);
                         }
@@ -1723,7 +1670,7 @@ export class Engine {
                     // in-RAM session are untouched) actually stops the judge. Reads disk
                     // via readActiveGoal — authoritative and independent of which session
                     // instance the run closure holds.
-                    isGoalActive: (sid) => this.sessionManager.readActiveGoal(sid) !== undefined,
+                    isGoalActive: (sid) => isSameGoalInstance(this.sessionManager.readActiveGoal(sid), normalizedGoal),
                 });
                 this.hooks.register("on_stop", goalHookHandler, 0, "goal-stop");
                 // Expose for clearGoal() mid-run. Already guarded by isSubAgent above.
@@ -1755,14 +1702,45 @@ export class Engine {
                     return info;
                 },
                 consumeSteer: (source) => this.consumeSteer(sid, source),
+                restoreSteer: (items) => this.restoreSteer(sid, items),
+                buildSteerUserMessageContent: async (item) => {
+                    const steerImageInput = await prepareRunImageInput({
+                        task: item.text,
+                        cwd,
+                        llm: this.config.llm,
+                        sessionId: sid,
+                        attachments: item.attachments,
+                    });
+                    if (!steerImageInput.ok) {
+                        throw new Error(steerImageInput.result.text);
+                    }
+                    return buildRunUserMessageContent(steerImageInput.parsedTask, cwd, steerImageInput.taskText);
+                },
                 claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
+                releaseClientMessageId: (clientMessageId) => {
+                    claimedClientMessageIds.delete(clientMessageId);
+                },
+                setOriginClientMessageId: (clientMessageId) => {
+                    toolCtx.originClientMessageId = clientMessageId;
+                },
                 recordCumulativeUsage,
+                recordCacheReadDiagnostics: (usage) => {
+                    this.recordCacheReadDiagnostics(sid, usage);
+                },
+                recordContextUsageAnchor: (anchor) => {
+                    session.state.contextUsageAnchor = {
+                        ...anchor,
+                        provider: this.config.llm.provider,
+                        model: this.config.llm.model,
+                    };
+                },
                 // Clear the persisted goal for a self-reported completion / confirmed
                 // cancel. Clears the in-RAM session's activeGoal (so THIS run's later
                 // turns don't re-arm) AND persists it, and drops the in-flight stop
                 // hook so nothing re-blocks the stop we're about to return.
                 clearPersistedGoal: () => {
-                    if (session.state.activeGoal !== undefined) {
+                    if (persistedRunGoal &&
+                        isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
                         session.state.activeGoal = undefined;
                         this.sessionManager.saveState(session.state);
                     }
@@ -1772,6 +1750,9 @@ export class Engine {
                             this.activeGoalHook = null;
                     }
                 },
+                updateGoalJudgeContext: (context) => {
+                    goalJudgeContext = context;
+                },
                 ctxOverheadStore: {
                     get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
                     set: (s, n) => {
@@ -1796,6 +1777,7 @@ export class Engine {
                 onStream: options?.onStream,
                 signal: options?.signal,
                 freshImageMessages: freshImageMessage ? [freshImageMessage] : undefined,
+                volatileContextMessages: dynamicContextMsg ? [dynamicContextMsg] : undefined,
                 // Goal mode: the active goal is surfaced to the on_stop handler via
                 // ctx.data.goal; the GoalStopHook (registered above) judges it.
                 goal: normalizedGoal,
@@ -1816,6 +1798,8 @@ export class Engine {
                     options?.onStream?.({
                         type: "usage_update",
                         promptTokens: cumulative.cumulativePromptTokens,
+                        promptTokensSource: "session_cumulative",
+                        promptTokensConfidence: "high",
                         cumulativePromptTokens: cumulative.cumulativePromptTokens,
                         cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
                         cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
@@ -1841,9 +1825,31 @@ export class Engine {
             // only — sub-agents don't carry user-clearable persistent goals.
             if (this.config.isSubAgent !== true)
                 this.activeRunSession = session;
+            const applyGoalTermination = (termination) => {
+                if (!termination || !persistedRunGoal)
+                    return;
+                // Record the terminal identity even when a newer goal has already
+                // replaced it. Only clear activeGoal when it is still the run's goal.
+                session.state.goalTerminal = {
+                    objective: persistedRunGoal.objective,
+                    setAtMs: persistedRunGoal.setAtMs,
+                    reason: termination,
+                    terminatedAtMs: Date.now(),
+                };
+                if (isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
+                    session.state.activeGoal = undefined;
+                }
+                this.sessionManager.saveState(session.state);
+                if (goalHookHandler) {
+                    this.hooks.unregister("on_stop", goalHookHandler);
+                    if (this.activeGoalHook === goalHookHandler)
+                        this.activeGoalHook = null;
+                }
+            };
             let result;
             try {
                 result = await turnLoop.run(messages);
+                applyGoalTermination(result.goalTermination);
                 // ── Headless: drain background sub-agents before resolving ───────
                 // Unified background-work model (2026-06-17): the engine NO LONGER parks
                 // every run waiting on background work. Background work (sub-agents,
@@ -1905,6 +1911,7 @@ export class Engine {
                             break;
                         }
                         result = await turnLoop.run([...result.messages, injected]);
+                        applyGoalTermination(result.goalTermination);
                     }
                 }
             }
@@ -1924,7 +1931,8 @@ export class Engine {
                 this.hooks.unregister("on_tool_start", fileHistoryHandler);
             }
             this.lastMessages = result.messages;
-            this.compactedMessagesBySession.set(session.state.sessionId, this.stripUserContextMessage(result.messages, userContextMsg));
+            const cachedMessages = this.stripInjectedContextMessages(result.messages, userContextMsg, dynamicContextMsg);
+            this.compactedMessagesBySession.set(session.state.sessionId, cachedMessages);
             logger.info("engine.done", {
                 sessionId: session.state.sessionId,
                 reason: result.reason,
@@ -2355,7 +2363,6 @@ export class Engine {
     refreshRuntimeConfig(patch, version) {
         if (version <= this.lastAppliedConfigVersion)
             return;
-        const prevServers = this.config.mcpServers ?? {};
         const prevPresetName = this.preset.name;
         this.config = { ...this.config, ...patch };
         // #2: re-resolve the prompt-affecting preset so the next-turn PromptComposer
@@ -2366,11 +2373,17 @@ export class Engine {
             // The builtin tool SET is ctor-frozen and may be shared via runtime — we
             // do NOT rebuild it here. If the new preset implies a different builtin
             // tool set, that part of the change only lands on session restart.
-            const prevTools = resolveBuiltinToolNames({ preset: prevPresetName })
+            const prevTools = resolveBuiltinToolNames({
+                preset: prevPresetName,
+                host: this.config.builtinToolHost,
+            })
                 .slice()
                 .sort()
                 .join(",");
-            const nextTools = resolveBuiltinToolNames({ preset: nextPreset.name })
+            const nextTools = resolveBuiltinToolNames({
+                preset: nextPreset.name,
+                host: this.config.builtinToolHost,
+            })
                 .slice()
                 .sort()
                 .join(",");
@@ -2457,6 +2470,41 @@ export class Engine {
         }
         return had;
     }
+    /**
+     * 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.readCwd(sessionId) ??
+            (this.activeRunSession?.state.sessionId === sessionId
+                ? this.activeRunSession.state.cwd
+                : undefined);
+        if (!mainRoot)
+            return null;
+        const workspace = { root: mainRoot, kind: "main" };
+        if (this.activeRunSession?.state.sessionId === sessionId) {
+            this.activeRunSession.state.workspace = workspace;
+        }
+        try {
+            const bundle = this.activeRunSession?.state.sessionId === sessionId
+                ? this.activeRunSession
+                : this.sessionManager.resume(sessionId);
+            bundle.state.workspace = workspace;
+            this.sessionManager.saveState(bundle.state);
+        }
+        catch {
+            try {
+                this.sessionManager.setSessionWorkspace(sessionId, workspace);
+            }
+            catch {
+                return null;
+            }
+        }
+        return workspace;
+    }
     injectContext(sessionId, content) {
         const session = this.sessionManager.resume(sessionId);
         session.transcript.appendMessage("assistant", content);
@@ -2539,11 +2587,39 @@ export class Engine {
             strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
         };
     }
-    stripUserContextMessage(messages, userContextMsg) {
+    stripInjectedContextMessages(messages, userContextMsg, dynamicContextMsg) {
+        const withoutDynamicContext = dynamicContextMsg
+            ? messages.filter((msg) => msg !== dynamicContextMsg)
+            : [...messages];
         if (!userContextMsg || messages[0] !== userContextMsg) {
-            return [...messages];
+            return withoutDynamicContext;
+        }
+        return withoutDynamicContext.slice(1);
+    }
+    recordCacheReadDiagnostics(sessionId, usage) {
+        const current = usage.cacheReadTokens;
+        if (current === undefined || !Number.isFinite(current))
+            return;
+        const previous = this.lastCacheReadBySid.get(sessionId);
+        this.lastCacheReadBySid.delete(sessionId);
+        this.lastCacheReadBySid.set(sessionId, current);
+        if (this.lastCacheReadBySid.size > CACHE_READ_DIAGNOSTIC_MAX_SESSIONS) {
+            const oldestSessionId = this.lastCacheReadBySid.keys().next().value;
+            if (oldestSessionId !== undefined)
+                this.lastCacheReadBySid.delete(oldestSessionId);
+        }
+        if (previous === undefined || previous < CACHE_READ_DROP_MIN_PREVIOUS_TOKENS)
+            return;
+        const dropRatio = previous > 0 ? current / previous : 1;
+        if (current <= CACHE_READ_DROP_MAX_CURRENT_TOKENS && dropRatio <= CACHE_READ_DROP_RATIO) {
+            logger.warn("engine.cache_read_drop", {
+                sessionId,
+                previousCacheReadTokens: previous,
+                currentCacheReadTokens: current,
+                dropRatio,
+                hint: "Prompt cache read tokens dropped sharply. Check for changed cacheable prefix, stale dynamic context in history, tool/schema changes, or provider cache eviction.",
+            });
         }
-        return messages.slice(1);
     }
     getSettingsManager() {
         if (!this.settingsManager) {
@@ -2575,10 +2651,10 @@ export class Engine {
     buildPermissionConfig(mode, cwd) {
         const rules = [...this.preset.defaultPermissionRules];
         // Memory tools: dream scope is the LLM's own workspace, so save/delete
-        // there go through without prompting. user-scope save/delete fall through
-        // to the tool's permissionDefault ("ask"), forcing the user to confirm
-        // any modification of memories they own. Read tools are listed in the
-        // tool definition as permissionDefault: "allow" — no rule needed here.
+        // there go through without prompting. user-scope save/delete have no
+        // explicit allow rule here, so default-mode classifier fallback asks the
+        // user to confirm modifications. RegisteredTool.permissionDefault is only
+        // UI/metadata and is not read by the classifier.
         rules.push({
             tool: "MemorySave",
             argsPattern: { scope: "^dream$" },
@@ -2837,6 +2913,25 @@ export class Engine {
         }
         return cached;
     }
+    resolveSandboxConfigForCwd(cwd) {
+        // Priority: config.sandbox → project settings.sandbox → global → per-run
+        // default. Read UNMERGED per-scope (getForScope) so a project that wrote no
+        // sandbox genuinely follows global, rather than inheriting global's mode and
+        // looking like it set one. Fixes "项目级配了不生效" + the scope model.
+        let projectSandbox;
+        let globalSandbox;
+        try {
+            const sm = this.getSettingsManager();
+            if (this.config.isSubAgent !== true) {
+                projectSandbox = sm.getForScope("project", cwd).sandbox;
+            }
+            globalSandbox = sm.getForScope("user").sandbox;
+        }
+        catch {
+            // settings unavailable → fall through to per-run default
+        }
+        return resolveSandboxConfig(this.config.sandbox, projectSandbox, globalSandbox, this.config.headless === true);
+    }
     /**
      * Build the shell env layered onto the Bash tool / background shells (see
      * mergeShellEnv). Three user-configured sources, merged lowest → highest:
@@ -2894,7 +2989,7 @@ export class Engine {
             // the host user's credentials (same isolation contract as top-level env).
             // Placed below settings.env so an explicit `env` entry can still override.
             const credScope = (this.config.settingsScope ?? "project") === "full" ? "full" : "project";
-            layer(new CredentialStore(cwd).envExposures(credScope));
+            layer(getCredentialAccess().envExposures(cwd, credScope));
             layer(settings.env); // top-level env (global ⊕ project) wins
         }
         catch {
@@ -2931,9 +3026,34 @@ export class Engine {
             return undefined;
         }
     }
+    readWorktreeBranchPrefix(cwd) {
+        if (this.config.isSubAgent === true || !cwd)
+            return undefined;
+        try {
+            const settings = this.getSettingsManager().get();
+            return settings.worktree?.branchPrefix;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async resolveWorktreeSetupSandbox(cwd) {
+        if (!cwd)
+            return undefined;
+        const sandboxConfig = this.resolveSandboxConfigForCwd(cwd);
+        const sandboxBackend = this.runtime
+            ? await this.runtime.resolveSandbox(sandboxConfig, cwd)
+            : await this.resolveSandboxWithoutRuntime(sandboxConfig, cwd);
+        return sandboxBackend.name === "off"
+            ? sandboxBackend
+            : { ...sandboxBackend, network: sandboxConfig.network };
+    }
+    readWorktreeSetupShellEnv(cwd) {
+        return this.readShellEnv(cwd);
+    }
     buildToolContext() {
         const { disabledSkills, disabledPlugins } = this.readDisabledLists();
-        return {
+        const ctx = {
             shellEnv: this.readShellEnv(this.config.cwd),
             cwd: this.config.cwd ?? process.cwd(),
             llmConfig: this.config.llm,
@@ -2941,6 +3061,7 @@ export class Engine {
             toolRegistry: this.toolRegistry,
             askUser: this.config.askUser,
             browser: this.config.browserBridge,
+            workspace: this.config.workspaceBridge,
             injectCredentialToBrowser: this.config.injectCredentialToBrowser,
             isSubAgent: this.config.isSubAgent === true,
             // Credential tools narrow their disk reads to this scope: a project/
@@ -2961,6 +3082,10 @@ export class Engine {
             // opts out via config. Otherwise allowed.
             allowBackgroundShells: this.config.isSubAgent === true ? false : this.config.allowBackgroundShells !== false,
         };
+        ctx.setCwd = (cwd) => {
+            ctx.cwd = cwd;
+        };
+        return ctx;
     }
     /**
      * Read settings.disabledSkills + settings.disabledPlugins in a single