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

package/dist/engine/engine.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 { detectPastedNoise } from "../utils/task-sanitizer.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";
@@ -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
@@ -445,6 +446,7 @@ export class Engine {
                 new ToolRegistry({
                     builtinTools: resolveBuiltinToolNames({
                         preset: this.preset.name,
+                        host: config.builtinToolHost,
                         enabledBuiltinTools: builtinLists.enabledBuiltinTools,
                         disabledBuiltinTools: builtinLists.disabledBuiltinTools,
                     }),
@@ -635,6 +637,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 +
@@ -735,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
@@ -801,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,
@@ -884,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}). ` +
@@ -946,6 +1001,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 +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
@@ -1070,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),
@@ -1134,6 +1178,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 +1196,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,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
@@ -1255,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
@@ -1265,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
@@ -1275,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
@@ -1289,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:
@@ -1307,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.
@@ -1331,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
@@ -1358,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);
@@ -1379,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,
@@ -1447,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
@@ -1757,6 +1817,13 @@ export class Engine {
                 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
@@ -1816,6 +1883,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,
@@ -2355,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
@@ -2366,11 +2434,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 +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);
@@ -2575,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$" },
@@ -2837,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:
@@ -2894,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 {
@@ -2931,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,
@@ -2941,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/
@@ -2961,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

package/dist/engine/image-policy.d.ts

@@ -149,6 +149,12 @@ export interface DropOversizedResult {
     droppedCount: number;
 }
 export declare function dropOversizedImages(images: readonly ParsedImage[]): DropOversizedResult;
+export interface ImagePolicyByteInput {
+    name: string;
+    mime: string;
+    bytes: number;
+}
+export declare function enforceImageBytePolicy(images: readonly ImagePolicyByteInput[]): ImagePolicyVerdict;
 export declare function enforceImagePolicy(images: readonly ParsedImage[]): ImagePolicyVerdict;
 /**
  * Collect the workspace file paths of any attached images that came from a