@cjhyy/code-shell-core 0.6.0-rc.8 → 0.7.0-beta.1

package/dist/engine/engine.js

@@ -11,7 +11,7 @@ import { applyDynamicToolDef } from "./dynamic-tool-defs.js";
 import { getMergedCatalog } from "../model-catalog/index.js";
 import { modelEntriesFromConnections } from "./model-connections-pool.js";
 import { resolveAuxKey } from "./aux-key.js";
-import { foldRunUsage } from "./session-usage.js";
+import { addCumulativeUsage, cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "./session-usage.js";
 import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
 import { resolveSandboxConfig } from "./sandbox-config.js";
 import { sandboxCacheKey } from "./sandbox-cache-key.js";
@@ -34,26 +34,27 @@ 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 { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
-import { parseTaskWithImages, } from "./parse-task.js";
+import { parseTaskWithImages } from "./parse-task.js";
+import { buildInputAttachmentContext } from "./input-attachments.js";
 import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, collectAttachedImagePaths, } from "./image-policy.js";
 import { tryCompressImages } from "./image-compression.js";
 import { buildSessionTitle } from "./session-title.js";
@@ -61,7 +62,7 @@ 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 { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 /**
  * 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
@@ -440,13 +441,16 @@ export class Engine {
         // per-turn path can only hide, not add, so a freshly-`on`'d builtin not in
         // the set needs a session restart to appear.
         const builtinLists = effectiveBuiltinLists(config.enabledBuiltinTools ?? [], config.disabledBuiltinTools ?? [], this.readBuiltinOverride(config.cwd));
-        this.toolRegistry = config.runtime?.toolRegistry ?? new ToolRegistry({
-            builtinTools: resolveBuiltinToolNames({
-                preset: this.preset.name,
-                enabledBuiltinTools: builtinLists.enabledBuiltinTools,
-                disabledBuiltinTools: builtinLists.disabledBuiltinTools,
-            }),
-        });
+        this.toolRegistry =
+            config.runtime?.toolRegistry ??
+                new ToolRegistry({
+                    builtinTools: resolveBuiltinToolNames({
+                        preset: this.preset.name,
+                        host: config.builtinToolHost,
+                        enabledBuiltinTools: builtinLists.enabledBuiltinTools,
+                        disabledBuiltinTools: builtinLists.disabledBuiltinTools,
+                    }),
+                });
         this.hooks = new HookRegistry();
         // Installed-plugin hooks — declared in each plugin's hooks/hooks.json.
         // Registered first (priority 80) so user-authored hooks at lower
@@ -633,27 +637,52 @@ 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 +
      * resend). General-purpose: any host path (UI 引导, future agent coordination,
-     * external triggers) can call it. If no run is active for the session the
-     * message simply waits in the queue and is consumed when that session next
-     * runs (rare race; host normally only steers while busy). No-op on blank text.
+     * external triggers) can call it. If no run is active for this session, reject
+     * without queueing so the host can downgrade to a normal run immediately.
+     * No-op on blank text.
      *
      * `id` is the host's stable queue-entry id. It rides through to the
      * `steer_injected` event (so the host can match the injected bubble back to
      * 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 = "") {
-        if (!sessionId)
-            return;
+    enqueueSteer(sessionId, text, id = "", clientMessageId) {
         const q = this.steerQueueBySid.get(sessionId) ?? [];
-        const next = enqueueSteerItem(q, id || `steer-${q.length}`, text);
+        const entryId = id || `steer-${q.length}`;
+        if (!sessionId)
+            return { accepted: false, id: entryId };
+        const activeRunSessionId = this.activeRunSession?.state.sessionId;
+        const active = this.activeTurnLoop !== null && activeRunSessionId === sessionId;
+        if (!active) {
+            logger.info("steer.enqueue.idle_rejected", {
+                sessionId,
+                id: entryId,
+                clientMessageId,
+                activeRunSessionId: activeRunSessionId ?? null,
+                queueLength: q.length,
+            });
+            return { accepted: false, id: entryId };
+        }
+        const next = enqueueSteerItem(q, entryId, text, clientMessageId);
         if (next === q)
-            return; // blank text dropped
+            return { accepted: false, id: entryId }; // blank text dropped
         this.steerQueueBySid.set(sessionId, next);
+        logger.info("steer.enqueue.accepted", {
+            sessionId,
+            id: entryId,
+            clientMessageId,
+            activeRunSessionId,
+            queueLength: next.length,
+        });
+        return { accepted: true, id: entryId };
     }
     /**
      * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
@@ -670,12 +699,20 @@ export class Engine {
         return removed;
     }
     /** Drain + clear the steer queue for a session (turn loop consumes per step). */
-    consumeSteer(sessionId) {
+    consumeSteer(sessionId, source = "normal_step") {
         const q = this.steerQueueBySid.get(sessionId);
         if (!q || q.length === 0)
             return [];
         const { drained, rest } = consumeSteerItems(q);
         this.steerQueueBySid.set(sessionId, rest);
+        logger.info("steer.consume.drained", {
+            sessionId,
+            source,
+            count: drained.length,
+            ids: drained.map((item) => item.id),
+            clientMessageIds: drained.flatMap((item) => item.clientMessageId ? [item.clientMessageId] : []),
+            queueLength: rest.length,
+        });
         return drained;
     }
     /** Wire the cookie→browser injection callback (InjectCredential tool). Same
@@ -704,20 +741,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
@@ -770,8 +832,32 @@ export class Engine {
                 usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
             };
         }
+        const cap = capabilitiesFor((this.config.llm.providerKind ?? this.config.llm.provider), this.config.llm.model);
+        const attachmentContext = await buildInputAttachmentContext(options?.attachments, cwd, {
+            includeImageBytes: cap.supportsVision,
+            expectedSessionId: options?.sessionId,
+        });
+        if (attachmentContext.errors.length > 0) {
+            const detail = attachmentContext.errors.join("; ");
+            logger.warn("engine.run.input_attachment_failed", { error: detail });
+            return {
+                text: `ERROR: input attachment could not be read (${detail}). Re-attach it or choose a path inside the workspace.`,
+                reason: "image_error",
+                sessionId: options?.sessionId ?? "input-attachment-failed",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            };
+        }
+        if (attachmentContext.text || attachmentContext.hasStructuredImageAttachments) {
+            parsedTask = {
+                text: [parsedTask.text, attachmentContext.text].filter(Boolean).join("\n\n"),
+                images: [...parsedTask.images, ...attachmentContext.images],
+                hasImages: parsedTask.hasImages ||
+                    attachmentContext.images.length > 0 ||
+                    attachmentContext.hasStructuredImageAttachments,
+            };
+        }
         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,
@@ -853,7 +939,7 @@ export class Engine {
         // *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 taskText = parsedTask.text;
         const noise = detectPastedNoise(taskText);
         if (noise.isNoise) {
             const hint = `Your input looks like pasted terminal output (${noise.reason}). ` +
@@ -915,10 +1001,10 @@ 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,
+                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt].filter(Boolean).join("\n\n") ||
+                        undefined,
                     responseLanguage: this.config.responseLanguage,
                     userProfile: this.config.userProfile,
                     instructions: this.config.instructions,
@@ -983,23 +1069,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
@@ -1040,12 +1110,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),
@@ -1103,7 +1177,26 @@ export class Engine {
         // call) instead of a try/catch on resume.
         let session;
         let messages;
+        let freshImageMessage;
+        let resumedFromDisk = false;
+        const claimedClientMessageIds = new Set();
+        const claimClientMessageId = (bundle, clientMessageId, source) => {
+            if (!clientMessageId)
+                return true;
+            if (claimedClientMessageIds.has(clientMessageId) ||
+                bundle.transcript.hasClientMessageId(clientMessageId)) {
+                logger.info("engine.client_message.duplicate_ignored", {
+                    sessionId: bundle.state.sessionId,
+                    clientMessageId,
+                    source,
+                });
+                return false;
+            }
+            claimedClientMessageIds.add(clientMessageId);
+            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();
@@ -1126,8 +1219,31 @@ export class Engine {
             }
             // Append new user message
             const userMsg = { role: "user", content: userMessageContent };
+            if (!claimClientMessageId(session, options?.clientMessageId, "submit")) {
+                const usage = session.state.tokenUsage ?? {
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    totalTokens: 0,
+                };
+                return {
+                    text: "",
+                    reason: "completed",
+                    sessionId: session.state.sessionId,
+                    turnCount: session.state.turnCount ?? 0,
+                    usage: {
+                        promptTokens: usage.promptTokens ?? 0,
+                        completionTokens: usage.completionTokens ?? 0,
+                        totalTokens: usage.totalTokens ?? 0,
+                    },
+                };
+            }
+            if (parsedTask.hasImages)
+                freshImageMessage = userMsg;
             messages.push(userMsg);
-            session.transcript.appendMessage("user", userMessageContent, { injected: options?.injected === true });
+            session.transcript.appendMessage("user", userMessageContent, {
+                injected: options?.injected === true,
+                clientMessageId: options?.clientMessageId,
+            });
             // Flush "active" status to disk immediately. resume() set it in memory
             // (session-manager.ts), but without this write the on-disk state.json
             // still shows the previous run's terminal reason — so any external
@@ -1139,13 +1255,20 @@ export class Engine {
             // Cold start: shape (2) reuses the host-supplied sid; shape (3)
             // lets sessionManager generate one with nanoid.
             session = this.sessionManager.create(cwd, this.config.llm.model, this.config.llm.provider, options?.sessionId, this.config.isSubAgent === true ? getCurrentSid() : undefined, this.config.isSubAgent === true ? "subagent" : this.config.origin);
-            messages = [{ role: "user", content: userMessageContent }];
-            session.transcript.appendMessage("user", userMessageContent);
+            const userMsg = { role: "user", content: userMessageContent };
+            claimClientMessageId(session, options?.clientMessageId, "submit");
+            if (parsedTask.hasImages)
+                freshImageMessage = userMsg;
+            messages = [userMsg];
+            session.transcript.appendMessage("user", userMessageContent, {
+                clientMessageId: options?.clientMessageId,
+            });
             // Save first user message as session summary — text only. The summary
             // shows up in the session list; "[image]" is more informative than a
             // truncated `[object Object]` when the prompt was purely visual.
             const summarySrc = parsedTask.hasImages
-                ? parsedTask.text || `[image${parsedTask.images.length > 1 ? `s × ${parsedTask.images.length}` : ""}]`
+                ? parsedTask.text ||
+                    `[image${parsedTask.images.length > 1 ? `s × ${parsedTask.images.length}` : ""}]`
                 : taskText;
             session.state.summary = summarySrc.slice(0, 80).replace(/\n/g, " ");
             this.sessionManager.saveState(session.state);
@@ -1156,21 +1279,6 @@ 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
@@ -1178,6 +1286,9 @@ export class Engine {
         // the first point we can set it. After this assignment treat the
         // field as immutable for the rest of the run.
         toolCtx.sessionId = session.state.sessionId;
+        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
@@ -1188,7 +1299,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
@@ -1198,7 +1309,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
@@ -1212,7 +1324,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:
@@ -1230,22 +1342,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.
@@ -1254,7 +1393,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
@@ -1281,12 +1422,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);
@@ -1302,13 +1445,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,
@@ -1370,6 +1506,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
@@ -1483,26 +1620,27 @@ export class Engine {
             // run would be evaluated fresh and might get a different replacement
             // string than the one already in the message, breaking idempotency.
             contextManager.initReplacementStateFromMessages(messages);
-            // Summarization (context-compaction + tool-result summaries) are auxiliary
-            // calls — route them to the configured aux model so they don't burn the
-            // expensive primary model every turn (same rationale as runMemoryPipeline).
-            // Resolved once here (not per-call) so the magnetic-disk settings re-read
-            // in resolveAuxClient stays off the compaction hot path. Falls back to the
-            // primary client when no aux model is configured.
+            // Two summarizers with DIFFERENT quality needs:
+            //
+            // 1. Context-compaction summary (setSummarizeFn) → PRIMARY model. This
+            //    condenses many rounds into the running summary that REPLACES the real
+            //    history; a dropped decision makes the conversation "forget" and poisons
+            //    every subsequent turn. It fires only near the compact ratio (~0.85), so
+            //    it's infrequent — quality far outweighs the occasional extra cost of a
+            //    primary-model call. (Manual /compact uses the primary for the same
+            //    reason; see forceCompact.)
+            //
+            // 2. Tool-use one-liner summaries (modelFacade.summarize below) → AUX model.
+            //    These are tiny throwaway outputs ("Wrote design doc") fired every turn;
+            //    that high-frequency, low-stakes chore is exactly what aux is for.
             const auxSummaryClient = await this.resolveAuxClient(llmClient);
-            contextManager.setSummarizeFn(async (prompt) => {
-                const summaryResponse = await auxSummaryClient.createMessage({
-                    systemPrompt: "You are a conversation summarizer. Be concise and factual.",
-                    messages: [{ role: "user", content: prompt }],
-                    tools: [],
-                    maxTokens: 1024,
-                    // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
-                    // this flips thinking off (~3x faster, fewer tokens); on every other
-                    // OpenAI-compatible provider the field is ignored.
-                    reasoning: { mode: "off" },
-                });
-                return summaryResponse.text;
-            });
+            Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
+            const recordCumulativeUsage = (usage) => {
+                const next = addCumulativeUsage(session.state, usage);
+                Object.assign(session.state, next);
+                return next;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordCumulativeUsage));
             // Create components (requires resolved llmClient).
             const modelFacade = new ModelFacade(llmClient, session.transcript);
             // Session-cumulative usage baseline: the LLM client is recreated per run
@@ -1676,7 +1814,16 @@ export class Engine {
                     pendingCompactInfo = null;
                     return info;
                 },
-                consumeSteer: () => this.consumeSteer(sid),
+                consumeSteer: (source) => this.consumeSteer(sid, source),
+                claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
+                recordCumulativeUsage,
+                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
@@ -1715,6 +1862,7 @@ export class Engine {
                 maxToolCallsPerTurn: this.config.maxToolCallsPerTurn ?? 25,
                 onStream: options?.onStream,
                 signal: options?.signal,
+                freshImageMessages: freshImageMessage ? [freshImageMessage] : 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,
@@ -1727,16 +1875,25 @@ export class Engine {
                     // baseline + this run's running total (idempotent per boundary,
                     // accumulates across runs; carries cacheRead/cacheCreation too).
                     session.state.tokenUsage = foldRunUsage(usageBaseline, modelFacade.getUsage());
-                    // Surface the session-cumulative cache counts to the UI (the "本会话
-                    // 累计命中率" tooltip). Separate from turn-loop's per-response
-                    // usage_update (which drives the live context reading).
-                    const cum = session.state.tokenUsage;
+                    // Surface the whole-session monotonic cache counts to the UI.
+                    // Separate from turn-loop's authoritative per-response emit (which
+                    // drives the live context reading and single-turn metric).
+                    const cumulative = normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage);
+                    const cumulativeHitRate = cumulativeCacheHitRate(cumulative);
                     options?.onStream?.({
                         type: "usage_update",
-                        promptTokens: cum.promptTokens,
-                        sessionPromptTokens: cum.promptTokens,
-                        sessionCacheReadTokens: cum.cacheReadTokens ?? 0,
-                        sessionCacheCreationTokens: cum.cacheCreationTokens ?? 0,
+                        promptTokens: cumulative.cumulativePromptTokens,
+                        promptTokensSource: "session_cumulative",
+                        promptTokensConfidence: "high",
+                        cumulativePromptTokens: cumulative.cumulativePromptTokens,
+                        cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                        cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                        ...(cumulativeHitRate !== undefined
+                            ? { cumulativeCacheHitRate: cumulativeHitRate }
+                            : {}),
+                        sessionPromptTokens: cumulative.cumulativePromptTokens,
+                        sessionCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                        sessionCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
                     });
                     if (this.config.costStore) {
                         session.state.costState = this.config.costStore.serialize();
@@ -1940,6 +2097,28 @@ export class Engine {
      * active run's client) when unset, unknown, or on any build failure — aux
      * work is best-effort and must never break a run.
      */
+    /**
+     * Build the SummarizeFn used for context compaction. Extracted so both the
+     * run path and forceCompact share one definition of the summarization call.
+     */
+    buildSummarizeFn(auxSummaryClient, recordCumulativeUsage) {
+        return async (prompt) => {
+            const summaryResponse = await auxSummaryClient.createMessage({
+                systemPrompt: "You are a conversation summarizer. Be concise and factual.",
+                messages: [{ role: "user", content: prompt }],
+                tools: [],
+                maxTokens: 1024,
+                // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
+                // this flips thinking off (~3x faster, fewer tokens); on every other
+                // OpenAI-compatible provider the field is ignored.
+                reasoning: { mode: "off" },
+            });
+            if (summaryResponse.usage) {
+                recordCumulativeUsage?.(summaryResponse.usage);
+            }
+            return summaryResponse.text;
+        };
+    }
     async resolveAuxClient(fallback) {
         let auxKey;
         try {
@@ -2005,7 +2184,9 @@ export class Engine {
             // extraction, which then padded the memory store with low-signal
             // entries. 8 messages is roughly "more than a single back-and-forth"
             // — substantive enough to be worth a durable note.
-            const messages = transcript.toMessages().filter((m) => m.role === "user" || m.role === "assistant");
+            const messages = transcript
+                .toMessages()
+                .filter((m) => m.role === "user" || m.role === "assistant");
             if (messages.length < 8)
                 return;
             // Memory orchestrator + dream-loop calls are auxiliary LLM calls
@@ -2107,10 +2288,8 @@ export class Engine {
         return entry;
     }
     /**
-     * Zero a session's cumulative token/cache usage on disk. Called on a model
-     * switch: a different model has its own prompt cache, so the accumulated
-     * cache-hit stats from the prior model are no longer meaningful. The next
-     * run's baseline (snapshotted from state.tokenUsage) then starts from zero.
+     * Zero the legacy/model-scoped token/cache usage window on disk. The
+     * whole-session cumulative counters are intentionally left alone.
      */
     resetSessionUsage(sessionId) {
         const zero = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
@@ -2182,7 +2361,9 @@ export class Engine {
             try {
                 chmodSync(file, 0o600);
             }
-            catch { /* best-effort */ }
+            catch {
+                /* best-effort */
+            }
         }
         catch (err) {
             logger.warn(`persistActiveModel failed: ${err.message}`);
@@ -2243,7 +2424,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
@@ -2254,8 +2434,20 @@ 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 }).slice().sort().join(",");
-            const nextTools = resolveBuiltinToolNames({ preset: nextPreset.name }).slice().sort().join(",");
+            const prevTools = resolveBuiltinToolNames({
+                preset: prevPresetName,
+                host: this.config.builtinToolHost,
+            })
+                .slice()
+                .sort()
+                .join(",");
+            const nextTools = resolveBuiltinToolNames({
+                preset: nextPreset.name,
+                host: this.config.builtinToolHost,
+            })
+                .slice()
+                .sort()
+                .join(",");
             if (prevTools !== nextTools) {
                 logger.warn("engine.preset_reload.tool_set_change_needs_restart", {
                     from: prevPresetName,
@@ -2339,6 +2531,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);
@@ -2354,14 +2581,13 @@ export class Engine {
      * Force context compaction on a session.
      * Returns token stats before/after.
      */
-    forceCompact(sessionId) {
+    async forceCompact(sessionId) {
         const effectiveSessionId = sessionId ?? this.lastSessionId;
         if (!effectiveSessionId) {
             return { before: 0, after: 0, strategy: "none (no active session)" };
         }
         const session = this.sessionManager.resume(effectiveSessionId);
-        const sourceMessages = this.compactedMessagesBySession.get(effectiveSessionId) ??
-            session.transcript.toMessages();
+        const sourceMessages = this.compactedMessagesBySession.get(effectiveSessionId) ?? session.transcript.toMessages();
         const before = estimateTokens(sourceMessages);
         let contextManager = this.lastContextManager;
         if (!contextManager || this.lastSessionId !== effectiveSessionId) {
@@ -2373,7 +2599,45 @@ export class Engine {
             contextManager.initReplacementStateFromMessages(sourceMessages);
             this.lastContextManager = contextManager;
         }
-        const compacted = contextManager.manage(sourceMessages);
+        // Manual /compact emits its UI boundary at the protocol layer from the
+        // final before/after result. Capture the tier here, but avoid reusing a
+        // stale run callback retained on lastContextManager, which could otherwise
+        // double-emit.
+        let compactStrategy;
+        contextManager.setOnCompact((info) => {
+            if (info.after < info.before)
+                compactStrategy = info.strategy;
+        });
+        // Manual /compact = maximum compaction NOW. The automatic ladder waits for
+        // compactAtRatio (0.85 * window), so on a 1M-window model an 800k text-only
+        // conversation sits under the gate and manage() only runs a no-op micro.
+        // Wire a summarizeFn (the run path does this per-run; a cold forceCompact on
+        // a resumed-but-never-run session has none) and call forceSummarize, which
+        // ignores the ratio gate and always summarizes (falling back to snip/window).
+        //
+        // Use the PRIMARY model, not the aux model. Automatic background compaction
+        // routes to aux to keep the high-frequency path cheap, but summarization is
+        // a high-fidelity task (drop a decision and the conversation "forgets"), and
+        // a manual /compact is a low-frequency, user-initiated request for quality.
+        // The aux model is sized for tiny outputs (titles, memory extraction), so
+        // downgrading the one compaction the user explicitly asked for is backwards.
+        try {
+            const primaryClient = await createLLMClient(this.config.llm, this.config.clientDefaults);
+            Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
+            const recordCompactUsage = (usage) => {
+                const next = addCumulativeUsage(session.state, usage);
+                Object.assign(session.state, next);
+                this.sessionManager.saveState(session.state);
+                return next;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(primaryClient, recordCompactUsage));
+        }
+        catch (err) {
+            logger.warn("engine.force_compact_client_failed", {
+                error: err.message,
+            });
+        }
+        const compacted = await contextManager.forceSummarize(sourceMessages);
         const after = estimateTokens(compacted);
         this.compactedMessagesBySession.set(effectiveSessionId, compacted);
         this.lastSessionId = effectiveSessionId;
@@ -2381,7 +2645,7 @@ export class Engine {
         return {
             before,
             after,
-            strategy: before === after ? "no compaction needed" : "compacted",
+            strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
         };
     }
     stripUserContextMessage(messages, userContextMsg) {
@@ -2420,10 +2684,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$" },
@@ -2475,7 +2739,11 @@ export class Engine {
                 backend = interactive;
             }
             else {
-                backend = new HeadlessApprovalBackend(mode === "bypassPermissions" ? "approve-all" : mode === "dontAsk" ? "deny-all" : "deny-all");
+                backend = new HeadlessApprovalBackend(mode === "bypassPermissions"
+                    ? "approve-all"
+                    : mode === "dontAsk"
+                        ? "deny-all"
+                        : "deny-all");
             }
         }
         return { rules, backend };
@@ -2517,7 +2785,8 @@ export class Engine {
      * rule set buildPermissionConfig does, without constructing a backend.
      */
     getPermissionRules() {
-        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd()).rules;
+        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd())
+            .rules;
     }
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
@@ -2604,12 +2873,8 @@ export class Engine {
     getAgentDefinitions(cwd) {
         const disabledAgents = this.readDisabledAgents(cwd);
         const disabledPlugins = this.readDisabledLists().disabledPlugins;
-        const disabledKey = [...disabledAgents, "::", ...disabledPlugins]
-            .slice()
-            .sort()
-            .join(" ");
-        if (this.agentDefsCache?.cwd !== cwd ||
-            this.agentDefsCache.disabledKey !== disabledKey) {
+        const disabledKey = [...disabledAgents, "::", ...disabledPlugins].slice().sort().join(" ");
+        if (this.agentDefsCache?.cwd !== cwd || this.agentDefsCache.disabledKey !== disabledKey) {
             this.agentDefsCache = {
                 cwd,
                 disabledKey,
@@ -2681,6 +2946,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:
@@ -2738,7 +3022,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 {
@@ -2775,9 +3059,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,
@@ -2785,6 +3094,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/
@@ -2805,6 +3115,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