@cjhyy/code-shell-core 0.5.0-rc.1 → 0.5.0-rc.2

package/dist/engine/engine.js

@@ -7,22 +7,32 @@ import { ToolExecutor } from "../tool-system/executor.js";
 import { InvestigationGuard } from "../tool-system/investigation-guard.js";
 import { TaskGuard } from "../tool-system/task-guard.js";
 import { readLastTodoSnapshot } from "../tool-system/builtin/task.js";
+import { agentToolDefWithTypes } from "../tool-system/builtin/agent.js";
+import { BUILTIN_TOOL_GUARDS } from "../tool-system/builtin/index.js";
+import { asyncAgentRegistry } from "../tool-system/builtin/agent-registry.js";
+import { notificationQueue, buildNotificationMessage, } from "../tool-system/builtin/agent-notifications.js";
 import { PermissionClassifier, HeadlessApprovalBackend, AutoApprovalBackend, InteractiveApprovalBackend, getInteractiveApprovalBackend, } from "../tool-system/permission.js";
 import { HookRegistry } from "../hooks/registry.js";
 import { wrapHookMessages } from "../hooks/inject.js";
+import { createGoalStopHook } from "../hooks/goal-stop-hook.js";
+import { normalizeGoal } from "./goal.js";
 import { loadPluginHooks } from "../plugins/loadPluginHooks.js";
+import { pluginAgentDirs } from "../plugins/installer/loadPluginAgents.js";
 import { patchOrphanedToolUses } from "./patch-orphaned-tools.js";
 import { runShellHook, shellHookMatches } from "../hooks/shell-runner.js";
 import { ContextManager } from "../context/manager.js";
+import { estimateTokens } from "../context/compaction.js";
+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 } from "../logging/logger.js";
+import { logger, setCurrentSid, 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 } from "../settings/manager.js";
+import { SettingsManager, userHome } from "../settings/manager.js";
+import { effectiveDisabledList, effectiveBuiltinLists } from "../capability-control/overlay.js";
 import { FileHistory } from "../session/file-history.js";
 import { defaultSandboxConfig, resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
 import { resolveAgentPreset, resolveBuiltinToolNames, } from "../preset/index.js";
@@ -33,31 +43,112 @@ 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, } 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 } from "node:path";
 import { homedir } from "node:os";
 import { 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
+ * compat flag off only drops the same-named .md (CLAUDE.md / AGENTS.md); the
+ * .claude/ subdir, *.local.md and rules/ are intentionally NOT linked.
+ * undefined (instructions omitted) means both stay on — backward compatible.
+ */
+export function compatFileNamesFrom(instructions) {
+    const names = [];
+    if (instructions?.compatClaude !== false)
+        names.push("CLAUDE.md");
+    if (instructions?.compatCodex !== false)
+        names.push("AGENTS.md");
+    return names;
+}
+/**
+ * True when two LLMConfigs name the SAME client identity — i.e. building a
+ * client from either would talk to the same model on the same endpoint with the
+ * same shaping. Used by resolveAuxClient to de-dup the aux client against the
+ * active model WITHOUT collapsing two distinct pool keys that merely share a
+ * `model` NAME but differ in reasoning/maxTokens/baseUrl/provider. Compares the
+ * fields that actually change request behavior; apiKey is intentionally NOT
+ * compared (two keys with the same endpoint+model but different credentials
+ * still produce equivalent aux work and don't warrant a second client). The
+ * reasoning object is compared by normalized JSON since it's a small
+ * discriminated union.
+ */
+function sameLlmIdentity(a, b) {
+    return (a.model === b.model &&
+        (a.baseUrl ?? undefined) === (b.baseUrl ?? undefined) &&
+        (a.provider ?? undefined) === (b.provider ?? undefined) &&
+        (a.providerKind ?? undefined) === (b.providerKind ?? undefined) &&
+        (a.maxTokens ?? undefined) === (b.maxTokens ?? undefined) &&
+        JSON.stringify(a.reasoning ?? null) === JSON.stringify(b.reasoning ?? null));
+}
+// Re-export the config hot-reload patch builder from here so the protocol
+// server (and tests) can import it alongside Engine without reaching into the
+// settings/ subtree directly. The implementation lives in settings/ to keep
+// engine.ts from growing and to sit next to personalizationFrom it composes.
+export { diskDefaultsFrom } from "../settings/disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
- * - `modelKey` set + present in pool → that model's config (over parent base).
+ * - `modelKey` set + present in pool → that model's config (pure entry-derived
+ *   identity; the parent's llm is NOT consulted).
  * - otherwise (no key, no pool, or key miss) → the parent's llm unchanged.
  * Key miss is a soft fallback, NOT an error: a stale agent definition must not
  * crash the spawn.
+ *
+ * ClientDefaults (temperature/timeout/etc.) are inherited from the parent
+ * Engine directly via EngineConfig.clientDefaults — they do not flow through
+ * this helper because they're not part of LLMConfig anymore.
  */
 export function resolveChildLlm(modelKey, pool, parentLlm) {
     if (modelKey && pool?.has(modelKey)) {
-        const resolved = pool.resolveLLMConfig(modelKey, parentLlm);
+        const resolved = pool.resolveLLMConfig(modelKey);
         if (resolved)
             return resolved;
     }
     return parentLlm;
 }
-/** Load reusable sub-agent role definitions from <cwd>/.code-shell/agents. */
-export function loadAgentDefinitionsForCwd(cwd) {
-    return AgentDefinitionRegistry.loadFromDir(`${cwd}/.code-shell/agents`);
+/**
+ * Load reusable sub-agent role definitions, merging:
+ *   1. project-level  <cwd>/.code-shell/agents/*.md   (ships built-ins)
+ *   2. user-level     ~/.code-shell/agents/*.md        (user wins on name)
+ * Names in `disabledAgents` are filtered out so the LLM never sees them.
+ */
+export function loadAgentDefinitionsForCwd(cwd, disabledAgents = [], disabledPlugins = []) {
+    const home = homedir();
+    // Increasing priority; loadFromDirs is last-dir-wins. ORDER ENCODES POLICY:
+    // user (cross-project personal default, lowest) → plugins (reusable baseline)
+    // → project (highest). A repo's in-tree agent therefore overrides a same-named
+    // user agent. This REVERSES the previous user>project behavior (spec §7.2);
+    // the descriptor's shadowedSources surfaces the override so the UI can warn.
+    return AgentDefinitionRegistry.loadFromDirs([
+        { dir: `${home}/.code-shell/agents`, source: "user" },
+        ...pluginAgentDirs(disabledPlugins),
+        // No project context (no-project bucket): cwd is "". Skip the project
+        // source rather than synthesizing "/.code-shell/agents" at the FS root,
+        // which silently resolves to nothing and drops every project-level
+        // (built-in) agent from the list.
+        ...(cwd ? [{ dir: `${cwd}/.code-shell/agents`, source: "project" }] : []),
+    ], disabledAgents);
 }
 const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel"];
+/**
+ * #7: apply a project's per-turn builtin capability override to a tool list.
+ * A builtin marked `off` for the current cwd is HIDDEN from the turn's tool
+ * list (matching how skills/plugins/agents `off` apply mid-session). `on` /
+ * `inherit` / absent keep the tool — we can't re-add a tool the ctor-frozen
+ * registry omitted, but `on` for a tool already present is a no-op. Pure +
+ * exported so it's unit-testable without a full run() turn.
+ */
+export function applyBuiltinOverrideVisibility(tools, override) {
+    if (!override)
+        return tools;
+    return tools.filter((t) => override[t.name] !== "off");
+}
 /**
  * Compute a child Engine's tool scope.
  * - `allowlist` set → child enabled = allowlist minus nested-agent tools
@@ -78,16 +169,38 @@ export function resolveChildToolScope(allowlist, parentDisabled, parentEnabled)
 }
 export class Engine {
     config;
+    // Resolved per-session preset. Set in the ctor; re-resolved by
+    // refreshRuntimeConfig on a preset hot-reload so the next-turn PromptComposer
+    // picks up the new preset's system prompt / behavior (#2). NOT readonly for
+    // that reason. NOTE: the toolRegistry's builtin tool SET is still ctor-frozen
+    // and is NOT rebuilt on reload — a preset change that alters the builtin tool
+    // set only takes effect on session restart (logged in refreshRuntimeConfig).
     preset;
     toolRegistry;
     hooks;
     sessionManager;
     mcpManager;
     modelPool;
+    /**
+     * Handles for the settings-sourced hook handlers registered by
+     * registerSettingsHooks(), so reloadHooks() can unregister exactly those
+     * (and nothing else — plugin hooks, goal/builtin hooks are untouched) before
+     * re-registering from fresh settings. Without this, a reload would
+     * accumulate duplicate settings-hook handlers that all fire per event.
+     */
+    settingsHookHandles = [];
+    /**
+     * Highest config-reload version applied so far. refreshRuntimeConfig drops
+     * any payload whose version is <= this, so out-of-order reload deliveries
+     * (multiple quick settings saves) can't let an older config clobber a newer
+     * one.
+     */
+    lastAppliedConfigVersion = 0;
     /** Memoized sub-agent role registry, keyed by the cwd it was loaded from. */
     agentDefsCache;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     runtime;
+    sandboxCache = new Map();
     /** Active permission mode for this Engine instance. */
     permissionMode;
     /** True when permissionMode === "plan". */
@@ -96,6 +209,13 @@ export class Engine {
     // don't re-read 6+ JSON files on every /model, /login, etc. The manager
     // handles its own cache invalidation in saveUserSetting().
     settingsManager;
+    /**
+     * Cached auxiliary-task LLM client, keyed by the models[].key it was built
+     * from. Background calls (memory extraction, auto-dream) reuse it across
+     * runs so we don't redo the provider handshake every session. Invalidated
+     * implicitly: a changed auxModelKey produces a different cache key.
+     */
+    auxClientCache;
     // Live state from the current/most-recent run, retained for /compact and
     // for live-mutating PermissionClassifier on permission-mode switch.
     lastContextManager;
@@ -158,12 +278,47 @@ export class Engine {
         }
         const entries = settings.hooks ?? [];
         for (const entry of entries) {
-            this.hooks.register(entry.event, async (ctx) => {
+            const event = entry.event;
+            const handler = async (ctx) => {
                 if (!shellHookMatches(entry, ctx))
                     return {};
                 return runShellHook(entry, ctx);
-            }, 50, `shell:${entry.event}:${entry.command.slice(0, 32)}`);
+            };
+            this.hooks.register(event, handler, 50, `shell:${entry.event}:${entry.command.slice(0, 32)}`);
+            // Track the (event, handler) so reloadHooks() can unregister exactly
+            // these settings-sourced handlers without touching plugin/goal/code hooks.
+            this.settingsHookHandles.push({ event, handler });
+        }
+    }
+    /**
+     * Re-apply settings.hooks onto the live HookRegistry after a settings
+     * change (config hot-reload layer 2). Surgical: removes ONLY the
+     * settings-sourced handlers this Engine previously registered (tracked in
+     * settingsHookHandles by identity) and re-runs registerSettingsHooks() from
+     * fresh disk settings. Plugin hooks (registered once at construction at
+     * priority 80) and goal/builtin/SDK-config hooks are never touched.
+     *
+     * The SettingsManager cache is invalidated first so the re-read reflects the
+     * latest settings.json on disk (mirrors freshSettings()'s load() semantics).
+     * Sub-agents never register settings hooks, so this is a no-op for them.
+     */
+    reloadHooks() {
+        if (this.config.isSubAgent === true)
+            return;
+        // Drop the previously-registered settings handlers by identity.
+        for (const { event, handler } of this.settingsHookHandles) {
+            this.hooks.unregister(event, handler);
         }
+        this.settingsHookHandles = [];
+        // Force the next get() to re-read disk so reloaded hooks reflect the
+        // newest settings.json, not a stale merged cache.
+        try {
+            this.getSettingsManager().invalidate();
+        }
+        catch {
+            // best-effort; registerSettingsHooks below tolerates read failures
+        }
+        this.registerSettingsHooks();
     }
     constructor(config) {
         this.config = config;
@@ -173,11 +328,26 @@ export class Engine {
         this.permissionMode = config.permissionMode ?? "acceptEdits";
         this.planMode = this.permissionMode === "plan";
         this.preset = resolveAgentPreset(config.preset);
+        // Fold the project's capabilityOverrides.builtin overlay over the global
+        // enabled/disabled builtin lists so a project can force-enable a
+        // globally-disabled builtin tool or force-disable a globally-enabled one
+        // (tri-state). Mirrors readDisabledLists for skills/plugins/agents; no cwd
+        // / no overlay → the config lists pass through unchanged (zero regression).
+        //
+        // #7: this builds the ctor-FROZEN builtin tool SET in the registry — a
+        // mid-session project override can't rebuild it. To make a builtin `off`
+        // toggle apply mid-session, run()'s per-turn tool-list assembly re-reads
+        // readBuiltinOverride(cwd) and HIDES `off` builtins from the turn's tool
+        // list (see the allToolDefs filter). `on` here can force-enable a
+        // globally-disabled builtin INTO the frozen set at construction; the
+        // 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: config.enabledBuiltinTools,
-                disabledBuiltinTools: config.disabledBuiltinTools,
+                enabledBuiltinTools: builtinLists.enabledBuiltinTools,
+                disabledBuiltinTools: builtinLists.disabledBuiltinTools,
             }),
         });
         this.hooks = new HookRegistry();
@@ -189,7 +359,10 @@ export class Engine {
         // overhead multiplied across sub-agents outweighs the value, and
         // dispatched tasks should run with minimal surface area.
         if (config.isSubAgent !== true) {
-            loadPluginHooks(this.hooks);
+            // disabledPlugins suppresses a plugin's hooks too (not just its
+            // Skill-tool entries) — see loadPluginHooks. readDisabledLists reads
+            // the same settings the prompt composer / tool context use.
+            loadPluginHooks(this.hooks, this.readDisabledLists().disabledPlugins);
         }
         // settings.hooks → shell-command wrappers. Chain order:
         // plugin (80) → shell (50) → code (default 0).
@@ -264,7 +437,7 @@ export class Engine {
                         const entry = this.modelPool.switch(match.key);
                         this.config = {
                             ...this.config,
-                            llm: this.modelPool.toLLMConfig(entry, this.config.llm),
+                            llm: this.modelPool.toLLMConfig(entry),
                         };
                     }
                 }
@@ -275,6 +448,27 @@ export class Engine {
                 // use /model to switch between the provider's available models.
                 this.autoPopulatePool(this.config.llm.apiKey, this.config.llm.baseUrl);
             }
+            // Carry image-attachment settings + sampling temperature into
+            // clientDefaults. Both are cross-model knobs — they apply to whatever
+            // model is currently active and survive hot-switches. (Pre-cleanup
+            // these were merged into llm.imageDetail / llm.temperature; that path
+            // is gone because hot-switching now rotates llm wholesale.)
+            const imageSettings = settings.images;
+            const modelBlock = settings.model;
+            const nextDefaults = { ...(this.config.clientDefaults ?? {}) };
+            let defaultsChanged = false;
+            if (imageSettings?.detail && nextDefaults.imageDetail !== imageSettings.detail) {
+                nextDefaults.imageDetail = imageSettings.detail;
+                defaultsChanged = true;
+            }
+            if (typeof modelBlock?.temperature === "number" &&
+                nextDefaults.temperature !== modelBlock.temperature) {
+                nextDefaults.temperature = modelBlock.temperature;
+                defaultsChanged = true;
+            }
+            if (defaultsChanged) {
+                this.config = { ...this.config, clientDefaults: nextDefaults };
+            }
         }
         catch {
             // Settings not available — pool stays empty
@@ -315,7 +509,7 @@ export class Engine {
             const entry = this.modelPool.switch(defaultEntry.key);
             this.config = {
                 ...this.config,
-                llm: this.modelPool.toLLMConfig(entry, this.config.llm),
+                llm: this.modelPool.toLLMConfig(entry),
             };
         }
     }
@@ -334,6 +528,13 @@ export class Engine {
     setAskUser(fn) {
         this.config.askUser = fn;
     }
+    /**
+     * Whether this engine runs unattended (no interactive human). Used by the
+     * in-process AgentServer to decide whether to wire an interactive askUser.
+     */
+    isHeadless() {
+        return this.config.headless === true;
+    }
     /**
      * Run a task from start to finish.
      */
@@ -352,6 +553,16 @@ export class Engine {
             if (event.type === "task_update") {
                 latestTodos = event.tasks;
             }
+            // Persist goal progress so replay/history shows how many rounds the
+            // goal ran. Display-only — toMessages() ignores this type, so it never
+            // re-enters the LLM context.
+            if (event.type === "goal_progress") {
+                session.transcript.append("goal_progress", {
+                    status: event.status,
+                    round: event.round,
+                    ...(event.gaps ? { gaps: event.gaps } : {}),
+                });
+            }
             userOnStream?.(event);
         };
         if (options)
@@ -398,6 +609,67 @@ export class Engine {
                     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
@@ -439,7 +711,11 @@ export class Engine {
                 const { enabled: childEnabled, disabled: childDisabled } = resolveChildToolScope(req.toolAllowlist, this.config.disabledBuiltinTools, this.config.enabledBuiltinTools);
                 const childLlm = resolveChildLlm(req.model, this.modelPool, this.config.llm);
                 const child = new Engine({
-                    llm: { ...childLlm, retryMaxAttempts: 2 },
+                    llm: childLlm,
+                    // Inherit parent's runtime knobs (temperature, image detail, timeouts)
+                    // but cap sub-agent retries at 2 — they're short-lived and we'd
+                    // rather surface failures than burn a 9 s exponential backoff loop.
+                    clientDefaults: { ...(this.config.clientDefaults ?? {}), retryMaxAttempts: 2 },
                     cwd,
                     permissionMode: this.config.permissionMode,
                     preset: this.preset.name,
@@ -449,10 +725,14 @@ export class Engine {
                     appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt]
                         .filter(Boolean)
                         .join("\n\n") || undefined,
+                    responseLanguage: this.config.responseLanguage,
+                    userProfile: this.config.userProfile,
+                    instructions: this.config.instructions,
                     maxTurns: req.maxTurns,
                     maxContextTokens: this.config.maxContextTokens ?? 200_000,
                     sessionStorageDir: this.config.sessionStorageDir,
                     headless: this.config.headless,
+                    readOnlySession: req.readOnlySession,
                     sandbox: this.config.sandbox,
                     // Subagents inherit the parent's scope: a child runs in the same
                     // cwd/session, so it should see the same config layers the parent did.
@@ -504,11 +784,11 @@ export class Engine {
         // `auto` mode handles its own downgrade with a one-time warning
         // inside resolveSandboxBackend; explicit modes do not.
         //
-        // Backend is cached on EngineRuntime (when available) so the
-        // capability probe runs once per (mode, cwd) instead of every turn.
+        // Backend is cached per runtime/engine so the capability probe runs once
+        // per (mode, cwd) instead of every turn.
         const sandboxBackend = this.runtime
             ? await this.runtime.resolveSandbox(sandboxConfig, cwd)
-            : await resolveSandboxBackend(sandboxConfig, cwd);
+            : await this.resolveSandboxWithoutRuntime(sandboxConfig, cwd);
         // sessionId is filled in after the session bundle is resolved below
         // (the session may be cold-started or resumed). Until then this is
         // intentionally shaped as a mutable local; we treat it as immutable
@@ -570,9 +850,8 @@ export class Engine {
         let messages;
         if (options?.sessionId && this.sessionManager.exists(options.sessionId)) {
             session = this.sessionManager.resume(options.sessionId);
-            messages = this.compactedMessagesBySession.get(options.sessionId)
-                ? [...this.compactedMessagesBySession.get(options.sessionId)]
-                : session.transcript.toMessages();
+            const cachedCompacted = this.compactedMessagesBySession.get(options.sessionId);
+            messages = cachedCompacted ? [...cachedCompacted] : session.transcript.toMessages();
             // If the previous run was Ctrl+C'd or crashed between an assistant
             // tool_use and the matching tool_result being persisted, the
             // loaded sequence is invalid for OpenAI (which 400s on dangling
@@ -604,7 +883,7 @@ export class Engine {
         else {
             // 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);
+            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);
             // Save first user message as session summary — text only. The summary
@@ -730,7 +1009,7 @@ export class Engine {
                 }
             }
             // Kick off LLM client creation early (network handshake)
-            const llmClientPromise = createLLMClient(this.config.llm);
+            const llmClientPromise = createLLMClient(this.config.llm, this.config.clientDefaults);
             const mode = this.config.permissionMode ?? "acceptEdits";
             const { rules: defaultRules, backend: approvalBackend } = this.buildPermissionConfig(mode, cwd);
             const permission = new PermissionClassifier(defaultRules, mode, approvalBackend);
@@ -751,8 +1030,12 @@ export class Engine {
             }
             const toolExecutor = new ToolExecutor(this.toolRegistry, permission, this.hooks);
             const investigationGuard = new InvestigationGuard();
-            if (this.config.headless)
+            if (this.config.readOnlySession) {
+                investigationGuard.setPolicy("read-only-review");
+            }
+            else if (this.config.headless) {
                 investigationGuard.setSoftMode(true);
+            }
             toolExecutor.setInvestigationGuard(investigationGuard);
             toolExecutor.setTaskGuard(new TaskGuard(() => latestTodos));
             // Wire abort signal for cascading cancellation + per-Engine ToolContext
@@ -769,6 +1052,9 @@ export class Engine {
                 preset: this.preset,
                 customSystemPrompt: this.config.customSystemPrompt,
                 appendSystemPrompt: this.config.appendSystemPrompt,
+                responseLanguage: this.config.responseLanguage,
+                userProfile: this.config.userProfile,
+                instructionOptions: { compatFileNames: compatFileNamesFrom(this.config.instructions) },
                 disabledSkills,
                 disabledPlugins,
             });
@@ -791,27 +1077,58 @@ export class Engine {
             //   1. createLLMClient — network handshake (started earlier)
             //   2. buildSystemPrompt — includes git status (3 execSync calls)
             //   3. buildSystemContext — reads environment context
-            const allToolDefs = this.toolRegistry.getToolDefinitions();
-            // In plan mode, only expose read-only tools so the model won't attempt writes
-            const planModeAllowed = new Set([
-                "EnterPlanMode",
-                "ExitPlanMode",
-                "Read",
-                "Glob",
-                "Grep",
-                "WebSearch",
-                "WebFetch",
-                "AskUserQuestion",
-                "Agent",
-                "ToolSearch",
-                "TaskCreate",
-                "TaskUpdate",
-                "TaskList",
-                "TaskGet",
-                "Bash", // Bash is included but executor filters non-read-only commands
-            ]);
+            // Inject the live available-agent-types listing into the Agent tool's
+            // description. The registry is per-engine (loaded from .code-shell/agents
+            // for this cwd), so it can't live in the static tool def — without this
+            // the model never learns the reusable roles exist and spawns nameless
+            // ad-hoc agents instead (the Core A/B/C incident).
+            // The Agent tool is always available: with configured roles, an omitted
+            // agent_type falls back to one of them (see resolveAgentTypeOverrides); with
+            // no roles configured it runs a true ephemeral agent, so workflows that need
+            // sub-agents (e.g. superpowers) work in any project.
+            // Availability guard (tool-visibility): a gated builtin (WebSearch needs a
+            // search provider, GenerateImage needs an OpenAI provider) is hidden from
+            // the toolDefs the model sees when its credential isn't configured for this
+            // cwd. Recomputed every message, so configuring a key takes effect on the
+            // NEXT message without a restart. Tools with no guard entry are always kept.
+            const guardCwd = toolCtx.cwd;
+            // #7: per-turn project builtin override. The toolRegistry's builtin tool
+            // SET is ctor-frozen (and may be shared via runtime), so a mid-session
+            // project override of a builtin can't rebuild the registry. But the tool
+            // LIST handed to the LLM is assembled fresh every turn, so we apply the
+            // override here: a builtin marked `off` for this cwd is HIDDEN from the
+            // turn's tool list (matching how skills/plugins/agents `off` apply
+            // mid-session via readDisabledLists). `on`/`inherit` keep whatever the
+            // registry already has — we can't re-add a tool the frozen registry omits,
+            // but `on` for a tool already present is a no-op (it stays). This makes a
+            // builtin toggle take effect on the NEXT message, like other capability
+            // kinds, without touching the registry.
+            const builtinOverride = this.readBuiltinOverride(guardCwd);
+            // Turn `off` from a prompt-visibility filter into a real execution gate:
+            // collect the builtin tool names the override marks `off` and hand them to
+            // the executor (via the shared toolCtx the executor already holds a
+            // reference to, set at setContext above) so it rejects a call to a hidden
+            // builtin instead of running it from the still-populated registry.
+            if (builtinOverride) {
+                const registryNames = new Set(this.toolRegistry.getToolDefinitions().map((t) => t.name));
+                const disabledBuiltins = new Set(Object.keys(builtinOverride).filter((name) => builtinOverride[name] === "off" && registryNames.has(name)));
+                toolCtx.disabledBuiltins = disabledBuiltins;
+            }
+            const allToolDefs = applyBuiltinOverrideVisibility(this.toolRegistry.getToolDefinitions(), builtinOverride)
+                .filter((t) => {
+                const guard = BUILTIN_TOOL_GUARDS.get(t.name);
+                return guard ? guard(guardCwd) : true;
+            })
+                .map((t) => t.name === "Agent"
+                ? { ...t, description: agentToolDefWithTypes(toolCtx.agentDefinitions).description }
+                : t);
+            // In plan mode, only expose read-only/planning tools so the model won't
+            // attempt writes. Shared with executor.ts's execution gate via
+            // PLAN_MODE_ALLOWED_TOOLS so what the model SEES and what the executor
+            // RUNS can't drift apart. (Bash is in the set; the executor additionally
+            // gates Bash to read-only commands at call time.)
             const toolDefs = this.planMode
-                ? allToolDefs.filter((t) => planModeAllowed.has(t.name))
+                ? allToolDefs.filter((t) => PLAN_MODE_ALLOWED_TOOLS.has(t.name))
                 : allToolDefs;
             const [llmClient, systemPrompt, systemContext] = await Promise.all([
                 llmClientPromise,
@@ -848,8 +1165,15 @@ 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.
+            const auxSummaryClient = await this.resolveAuxClient(llmClient);
             contextManager.setSummarizeFn(async (prompt) => {
-                const summaryResponse = await llmClient.createMessage({
+                const summaryResponse = await auxSummaryClient.createMessage({
                     systemPrompt: "You are a conversation summarizer. Be concise and factual.",
                     messages: [{ role: "user", content: prompt }],
                     tools: [],
@@ -857,7 +1181,7 @@ export class Engine {
                     // 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.
-                    thinking: "disabled",
+                    reasoning: { mode: "off" },
                 });
                 return summaryResponse.text;
             });
@@ -873,14 +1197,14 @@ export class Engine {
             // tracker so session_end.cost reflects only the user-facing turns and
             // turns/requestCount stay aligned.
             modelFacade.summarize = async (sysPrompt, userMsg) => {
-                const resp = await llmClient.createMessage({
+                const resp = await auxSummaryClient.createMessage({
                     systemPrompt: sysPrompt,
                     messages: [{ role: "user", content: userMsg }],
                     tools: [],
                     maxTokens: 256,
                     recordUsage: false,
                     // Auxiliary call — see contextManager.setSummarizeFn above.
-                    thinking: "disabled",
+                    reasoning: { mode: "off" },
                 });
                 logger.debug("summarize.call", {
                     sysPromptLen: sysPrompt.length,
@@ -895,7 +1219,7 @@ export class Engine {
                 return resp.text;
             };
             // File history: auto-backup before Write/Edit
-            const sessionDir = join(this.config.sessionStorageDir ?? join(homedir(), ".code-shell", "sessions"), session.state.sessionId);
+            const sessionDir = join(this.config.sessionStorageDir ?? join(userHome(), ".code-shell", "sessions"), session.state.sessionId);
             const fileHistory = FileHistory.loadFromDir(sessionDir);
             this.hooks.register("on_tool_start", async (context) => {
                 const toolName = context.data?.toolName;
@@ -911,6 +1235,24 @@ export class Engine {
                 task,
                 model: this.config.llm.model,
             });
+            // 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 reuses `llmClient` — the
+            // same model this session is talking to (per design).
+            // 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).
+            const normalizedGoal = normalizeGoal(options?.goal ?? this.config.goal);
+            let goalHookHandler = null;
+            if (normalizedGoal && this.config.isSubAgent !== true) {
+                goalHookHandler = createGoalStopHook({
+                    goal: normalizedGoal,
+                    llm: llmClient,
+                    log: logger,
+                });
+                this.hooks.register("on_stop", goalHookHandler, 0, "goal-stop");
+            }
             // Surface compaction events to the UI so the user knows when context was trimmed.
             // Buffer the most recent event so TurnLoop can drain it and emit the
             // post_compact hook on the next turn (ContextManager itself doesn't
@@ -947,6 +1289,9 @@ export class Engine {
                 maxToolCallsPerTurn: this.config.maxToolCallsPerTurn ?? 10,
                 onStream: options?.onStream,
                 signal: options?.signal,
+                // Goal mode: the active goal is surfaced to the on_stop handler via
+                // ctx.data.goal; the GoalStopHook (registered above) judges it.
+                goal: normalizedGoal,
                 // Heartbeat: flush turnCount + tokens to state.json after every turn
                 // so external observers (other CLI processes, /sid, the session list)
                 // see live progress instead of a stale snapshot from the last
@@ -965,7 +1310,59 @@ export class Engine {
                     this.sessionManager.saveState(session.state);
                 },
             });
-            const result = await turnLoop.run(messages);
+            let result;
+            try {
+                result = await turnLoop.run(messages);
+                // ── Wait for background sub-agents, then summarize ───────────────
+                // run_in_background sub-agents outlive the turn that spawned them. The
+                // main agent must not resolve while ITS OWN background agents are still
+                // working — otherwise their results land in the notification queue with
+                // nobody to drain them and the run looks "done" while work is in flight
+                // (the s-mpvf4rsj-bb6e4639 bug). We block here until none of this
+                // session's background agents are running, then drain ALL their results
+                // and feed them back as one more turn so the agent summarizes.
+                //
+                // Top-level only: a sub-agent must never wait on grandchildren (and
+                // nested agents are disabled anyway). `signal` aborts the wait.
+                const sid = session.state.sessionId;
+                const isTopLevel = this.config.isSubAgent !== true;
+                if (isTopLevel) {
+                    let aborted = options?.signal?.aborted === true;
+                    while (!aborted && asyncAgentRegistry.hasRunningForSession(sid)) {
+                        aborted = await this.waitForBackgroundAgentChange(sid, options?.signal);
+                    }
+                    // Drain everything that came back — including partial results when the
+                    // user aborted with one agent still stuck. Nothing already returned is
+                    // lost: it's injected into the transcript either way.
+                    const pending = notificationQueue.drainAll(sid);
+                    if (pending.length > 0) {
+                        const injected = {
+                            role: "user",
+                            content: `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`,
+                        };
+                        if (aborted) {
+                            // Aborted: preserve the results in context (transcript + messages)
+                            // but do NOT spin up another LLM turn — the user cancelled, and a
+                            // fresh turn would just be killed by the same signal. The next
+                            // user message in this session will see these results in history.
+                            session.transcript.appendMessage(injected.role, injected.content);
+                            result = { ...result, messages: [...result.messages, injected] };
+                        }
+                        else {
+                            // All background agents finished: one more turn so the agent reads
+                            // every result and summarizes. turnCount keeps accumulating, so
+                            // maxTurns still bounds runaway re-summarization.
+                            result = await turnLoop.run([...result.messages, injected]);
+                        }
+                    }
+                }
+            }
+            finally {
+                // Run-scoped: drop the GoalStopHook so a later goal-less send on this
+                // long-lived engine doesn't keep blocking stops.
+                if (goalHookHandler)
+                    this.hooks.unregister("on_stop", goalHookHandler);
+            }
             this.lastMessages = result.messages;
             this.compactedMessagesBySession.set(session.state.sessionId, this.stripUserContextMessage(result.messages, userContextMsg));
             logger.info("engine.done", {
@@ -992,6 +1389,31 @@ export class Engine {
             // transcript, save a session summary, and conditionally trigger
             // auto-dream consolidation. Doesn't block the Engine result.
             void this.runMemoryPipeline(session.transcript, session.state.sessionId, cwd, llmClient);
+            // Fire-and-forget session title generation — only after the FIRST turn.
+            // Reuses the already-resolved auxSummaryClient (aux model, cheap). Best-
+            // effort: failures never touch the run result. The renderer writes the
+            // title into the sidebar on receipt of the session_title stream event.
+            {
+                const messageEvents = session.transcript.getEvents("message");
+                const userMsgEvents = messageEvents.filter((e) => e.data.role === "user");
+                const userMsgCount = userMsgEvents.length;
+                const onStream = options?.onStream;
+                if (userMsgCount === 1 && onStream && result.text) {
+                    const rawContent = userMsgEvents[0]?.data?.content;
+                    const firstUserText = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent ?? "");
+                    void buildSessionTitle(auxSummaryClient, firstUserText, result.text)
+                        .then((title) => {
+                        if (title) {
+                            onStream({
+                                type: "session_title",
+                                sessionId: session.state.sessionId,
+                                title,
+                            });
+                        }
+                    })
+                        .catch(() => { });
+                }
+            }
             // Update session state. Persist the raw terminal reason as the status so
             // callers can distinguish user-cancelled (aborted_streaming) from real
             // failures (model_error, prompt_too_long, ...) — previously every
@@ -1035,8 +1457,69 @@ export class Engine {
      * task. Extracts durable memories from the transcript, saves a session
      * summary, and conditionally triggers auto-dream consolidation.
      */
-    async runMemoryPipeline(transcript, sessionId, cwd, llmClient) {
+    /**
+     * Resolve the LLM client for background/auxiliary work (memory extraction,
+     * auto-dream). When settings.auxModelKey names a valid pool model, build (and
+     * cache) a dedicated client for it so per-turn book-keeping runs on a cheap
+     * fast model instead of the expensive primary. Falls back to `fallback` (the
+     * active run's client) when unset, unknown, or on any build failure — aux
+     * work is best-effort and must never break a run.
+     */
+    async resolveAuxClient(fallback) {
+        let auxKey;
+        try {
+            // Re-read from disk: settings may have been changed by the desktop
+            // (a separate process) since this worker last cached them. This runs
+            // once per run on the post-run background path, so the cost is fine.
+            const sm = this.getSettingsManager();
+            sm.invalidate();
+            auxKey = sm.get().auxModelKey;
+        }
+        catch {
+            return fallback;
+        }
+        if (!auxKey)
+            return fallback;
+        // Don't spin up a second client when the aux key resolves to the SAME
+        // client config as this engine's active model. Compare FULL LLM IDENTITY
+        // (model + reasoning + maxTokens + baseUrl + provider/providerKind) against
+        // this engine's own per-session config.llm — NOT a separately-tracked active
+        // key, and NOT just the model NAME. Two distinct pool keys can share the same
+        // `model` string yet differ in reasoning/maxOutputTokens/baseUrl/apiKey/
+        // providerKey; de-duping on the name alone would wrongly route the user's
+        // chosen aux entry onto the primary's config. config.llm is isolated per
+        // session and always set for a real run, so this is correct even for desktop
+        // worker sessions built with a shared runtime (which never explicitly
+        // switchModel, so the old activeModelKey field was undefined and defeated the
+        // de-dup), AND immune to another session mutating the shared pool's activeKey.
+        const entry = this.modelPool.get(auxKey);
+        if (entry && sameLlmIdentity(this.modelPool.toLLMConfig(entry), this.config.llm)) {
+            return fallback;
+        }
+        if (this.auxClientCache?.key === auxKey)
+            return this.auxClientCache.client;
+        if (!entry) {
+            logger.warn("engine.aux_model_missing", { auxModelKey: auxKey });
+            return fallback;
+        }
+        try {
+            const client = await createLLMClient(this.modelPool.toLLMConfig(entry), this.config.clientDefaults);
+            this.auxClientCache = { key: auxKey, client };
+            return client;
+        }
+        catch (err) {
+            logger.warn("engine.aux_model_build_failed", {
+                auxModelKey: auxKey,
+                error: err.message,
+            });
+            return fallback;
+        }
+    }
+    async runMemoryPipeline(transcript, sessionId, cwd, primaryClient) {
         try {
+            // Background calls run on the auxiliary model when configured, so memory
+            // book-keeping doesn't burn the expensive primary model every turn.
+            const llmClient = await this.resolveAuxClient(primaryClient);
             // Only run memory extraction for substantive sessions. The previous
             // threshold of 4 user+assistant messages was low enough that two-line
             // exchanges ("what's the time?" / "noon") triggered a full LLM
@@ -1069,7 +1552,7 @@ export class Engine {
                         tools: [],
                         maxTokens: 1024,
                         recordUsage: false,
-                        thinking: "disabled",
+                        reasoning: { mode: "off" },
                     });
                     return resp.text;
                 },
@@ -1103,117 +1586,20 @@ export class Engine {
      * bailed before the first LLM call (e.g. registry missing the tools).
      */
     async runDreamLoop(opts) {
-        const MAX_TURNS = 8;
-        const MAX_WRITES = 10;
-        const MEMORY_TOOL_NAMES = ["MemoryList", "MemoryRead", "MemorySave", "MemoryDelete"];
-        const memoryTools = MEMORY_TOOL_NAMES
-            .map((n) => this.toolRegistry.getTool(n))
-            .filter((t) => t != null);
-        if (memoryTools.length < MEMORY_TOOL_NAMES.length) {
-            logger.warn("memory.auto_dream_missing_tools", {
-                sessionId: opts.sessionId,
-                found: memoryTools.map((t) => t.name),
-            });
-            return false;
-        }
-        // Strip RegisteredTool down to the shape createMessage expects.
-        const toolDefs = memoryTools.map((t) => ({
-            name: t.name,
-            description: t.description,
-            inputSchema: t.inputSchema,
-        }));
-        const toolCtx = {
-            ...this.buildToolContext(),
-            cwd: opts.projectDir ?? process.cwd(),
-        };
-        const messages = [{ role: "user", content: opts.userPrompt }];
-        let writeBudget = MAX_WRITES;
-        for (let turn = 0; turn < MAX_TURNS; turn++) {
-            const resp = await opts.llmClient.createMessage({
-                systemPrompt: opts.systemPrompt,
-                messages,
-                tools: toolDefs,
-                maxTokens: 2048,
-                recordUsage: false,
-                thinking: "disabled",
-            });
-            if (resp.toolCalls.length === 0) {
-                logger.info("memory.auto_dream_finished", {
-                    sessionId: opts.sessionId,
-                    turn,
-                    finalText: resp.text.slice(0, 500),
-                });
-                return true;
-            }
-            // Echo the assistant turn back into the conversation so subsequent
-            // turns see the tool_use ids they need to reference.
-            const assistantContent = [];
-            if (resp.text)
-                assistantContent.push({ type: "text", text: resp.text });
-            for (const tc of resp.toolCalls) {
-                assistantContent.push({
-                    type: "tool_use",
-                    id: tc.id,
-                    name: tc.toolName,
-                    input: tc.args,
-                });
-            }
-            messages.push({ role: "assistant", content: assistantContent });
-            // Dispatch every tool call requested in this turn.
-            const toolResults = [];
-            for (const tc of resp.toolCalls) {
-                const result = await this.dispatchDreamTool(tc, toolCtx, () => {
-                    if (writeBudget <= 0)
-                        return false;
-                    writeBudget--;
-                    return true;
-                });
-                toolResults.push({
-                    type: "tool_result",
-                    tool_use_id: tc.id,
-                    content: result,
-                });
-            }
-            messages.push({ role: "user", content: toolResults });
-        }
-        logger.warn("memory.auto_dream_hit_turn_cap", {
+        // The loop body now lives in services/dream-consolidation.ts so it can
+        // also be driven from the desktop host's manual "整理 / Dream" trigger.
+        // The orchestrator built systemPrompt/userPrompt from this engine's
+        // MemoryManager already; runDreamConsolidation rebuilds them from the same
+        // projectDir, so passing them here would be redundant — we just hand it the
+        // tool registry + a memory-scoped tool context.
+        const { ran } = await runDreamConsolidation({
+            llmClient: opts.llmClient,
+            toolRegistry: this.toolRegistry,
+            toolContext: this.buildToolContext(),
+            projectDir: opts.projectDir,
             sessionId: opts.sessionId,
-            maxTurns: MAX_TURNS,
         });
-        return true;
-    }
-    /**
-     * Execute one memory tool call inside the dream loop. Enforces the two
-     * dream-loop invariants the prompt also states:
-     *   - Only the 4 memory tools are dispatchable.
-     *   - Save/Delete in "user" scope is refused (returned as a tool error)
-     *     because dream runs without an interactive permission backend.
-     */
-    async dispatchDreamTool(tc, ctx, consumeWriteBudget) {
-        const allowed = new Set(["MemoryList", "MemoryRead", "MemorySave", "MemoryDelete"]);
-        if (!allowed.has(tc.toolName)) {
-            return `Error: tool "${tc.toolName}" is not available in the dream loop`;
-        }
-        const isWrite = tc.toolName === "MemorySave" || tc.toolName === "MemoryDelete";
-        if (isWrite) {
-            const scope = tc.args?.scope;
-            if (scope !== "dream") {
-                return (`Error: dream loop may only write to scope "dream", got "${scope}". ` +
-                    `User-scope changes require interactive permission, which is not available here.`);
-            }
-            if (!consumeWriteBudget()) {
-                return "Error: dream write budget exhausted — stop calling write tools and summarize instead.";
-            }
-        }
-        try {
-            const result = await this.toolRegistry.executeTool(tc.toolName, tc.args, { ctx });
-            if (result.isError)
-                return result.error ?? `Error executing ${tc.toolName}`;
-            return result.result ?? "";
-        }
-        catch (err) {
-            return `Error executing ${tc.toolName}: ${err.message}`;
-        }
+        return ran;
     }
     getToolRegistry() {
         return this.toolRegistry;
@@ -1229,7 +1615,10 @@ export class Engine {
      */
     switchModel(key) {
         const entry = this.modelPool.switch(key);
-        const nextLlm = this.modelPool.toLLMConfig(entry, this.config.llm);
+        // LLMConfig is pure model identity now — rotate it wholesale. Cross-model
+        // runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail) live on
+        // this.config.clientDefaults and survive the switch untouched.
+        const nextLlm = this.modelPool.toLLMConfig(entry);
         this.config = { ...this.config, llm: nextLlm };
         this.persistActiveModel(entry, nextLlm);
         return entry;
@@ -1245,7 +1634,11 @@ export class Engine {
      */
     persistActiveModel(entry, llm) {
         try {
-            const dir = join(homedir(), ".code-shell");
+            // userHome() (not raw homedir()) so a test that sets process.env.HOME to
+            // a tmpdir gets its writes isolated too — the SettingsManager reader
+            // already honors HOME; the writer must match or tests pollute the real
+            // ~/.code-shell/settings.json (this happened: an A-key/model-a leak).
+            const dir = join(userHome(), ".code-shell");
             const file = join(dir, "settings.json");
             mkdirSync(dir, { recursive: true });
             let existing = {};
@@ -1303,6 +1696,83 @@ export class Engine {
     getConfig() {
         return this.config;
     }
+    /**
+     * Config hot-reload "layer 2": merge a disk-default config patch into this
+     * ALREADY-RUNNING session's `this.config`, reload settings hooks, and
+     * incrementally connect any newly-added MCP servers. Applied at the next
+     * turn boundary — an in-flight turn is NOT interrupted: it keeps using the
+     * PromptComposer it was built with, and the next turn rebuilds the composer
+     * from the freshly-merged config (composer is rebuilt per-turn).
+     *
+     * `version` is a monotonic counter from the server: stale (<=last applied)
+     * payloads are dropped so out-of-order reload deliveries can't let an older
+     * config clobber a newer one (Q5).
+     *
+     * MCP: only connects (idempotent — already-connected servers are skipped);
+     * never disconnects, so an in-flight tool call on an existing server is
+     * never severed (Q3). Removed servers are deferred to the next session
+     * rebuild. If mcpManager isn't built yet (no MCP run has happened), the
+     * new servers will be connected on the next run via the existing per-run
+     * connectAll path — so we skip the connect here.
+     *
+     * Preset (#2): a preset hot-reload re-resolves `this.preset` so the next-turn
+     * PromptComposer picks up the new preset's system prompt / behavior — that's
+     * the main user-visible preset effect and it IS hot. The toolRegistry's
+     * builtin tool SET, however, is ctor-frozen (and may be shared via runtime):
+     * it is NOT rebuilt here. So a preset change that alters the builtin tool set
+     * (e.g. general → terminal-coding adds LSP/Brief) only takes effect on the
+     * next session restart; we log a warning when that case is detected.
+     *
+     * disk-default-vs-slice caveat (#8): the patch carries pure DISK-default
+     * values (preset/customSystemPrompt/appendSystemPrompt/responseLanguage/
+     * userProfile — see diskDefaultsFrom). Spreading them here OVERRIDES any
+     * per-request slice override of the same field. This is correct for the
+     * desktop host today (its per-request slice only carries permissionMode+cwd,
+     * which are excluded from the disk patch). A future host that sets
+     * slice.preset (or the other prompt fields) per-request MUST exclude those
+     * from the reload patch — or track per-request overrides separately — or this
+     * reload will clobber them back to disk values.
+     */
+    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
+        // (rebuilt per turn from this.preset) reflects the new preset's system
+        // prompt / behavior. Only when the preset actually changed.
+        if (patch.preset !== undefined && patch.preset !== prevPresetName) {
+            const nextPreset = resolveAgentPreset(this.config.preset);
+            // 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(",");
+            if (prevTools !== nextTools) {
+                logger.warn("engine.preset_reload.tool_set_change_needs_restart", {
+                    from: prevPresetName,
+                    to: nextPreset.name,
+                    note: "preset system prompt hot-reloaded; builtin tool-set change takes effect on session restart",
+                });
+            }
+            this.preset = nextPreset;
+        }
+        this.reloadHooks();
+        if (patch.mcpServers && this.mcpManager) {
+            const added = {};
+            for (const [name, cfg] of Object.entries(patch.mcpServers)) {
+                if (!(name in prevServers))
+                    added[name] = cfg;
+            }
+            if (Object.keys(added).length > 0) {
+                // connectAll is idempotent (skips already-connected); fire-and-forget
+                // so a slow server handshake never blocks the reload call.
+                void this.mcpManager.connectAll(added);
+            }
+        }
+        this.lastAppliedConfigVersion = version;
+    }
     /**
      * Inject context into a session's transcript without triggering a LLM turn.
      * The injected content appears as an assistant message so the LLM can see it
@@ -1332,7 +1802,6 @@ export class Engine {
         if (!this.lastContextManager || !sessionId) {
             return { before: 0, after: 0, strategy: "none (no active session)" };
         }
-        const { estimateTokens } = require("../context/compaction.js");
         const sourceMessages = this.compactedMessagesBySession.get(sessionId) ??
             this.sessionManager.resume(sessionId).transcript.toMessages();
         const before = estimateTokens(sourceMessages);
@@ -1477,22 +1946,128 @@ export class Engine {
             this.planMode = value;
         }
     }
+    /**
+     * Block until a background agent's state changes (finishes / its result is
+     * enqueued) or `signal` aborts. Resolves `true` if aborted, `false` on a
+     * change. The caller re-checks `hasRunningForSession` after each wake, so a
+     * spurious wake (another session's agent) just loops again.
+     *
+     * Subscribes to BOTH the registry AND the notification queue — and that's
+     * load-bearing, not belt-and-suspenders. A completing agent calls
+     * `markCompleted` (registry notify) and only THEN `enqueue` (queue notify),
+     * as two separate statements. If we woke on the registry notify alone, the
+     * loop could re-check, see no running agents, and `drainAll` BEFORE the
+     * result was enqueued — silently losing the last agent's output. Waking on
+     * the queue notify guarantees the item is already in the bucket. But a
+     * *cancelled* agent marks-but-never-enqueues (by design), so we also need
+     * the registry notify or a final cancel would hang the wait forever. Hence
+     * both. Subscribe-before-await closes the check/wait race either way.
+     */
+    waitForBackgroundAgentChange(_sessionId, signal) {
+        if (signal?.aborted)
+            return Promise.resolve(true);
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (aborted) => {
+                if (settled)
+                    return;
+                settled = true;
+                unsubRegistry();
+                unsubQueue();
+                signal?.removeEventListener("abort", onAbort);
+                resolve(aborted);
+            };
+            const onAbort = () => finish(true);
+            const unsubRegistry = asyncAgentRegistry.subscribe(() => finish(false));
+            const unsubQueue = notificationQueue.subscribe(() => finish(false));
+            signal?.addEventListener("abort", onAbort, { once: true });
+        });
+    }
     /**
      * Sub-agent role registry for the given cwd, memoized per-cwd so the
      * directory is read once rather than every turn. A new cwd (e.g. via
      * run({ cwd })) reloads.
      */
     getAgentDefinitions(cwd) {
-        if (this.agentDefsCache?.cwd !== cwd) {
-            this.agentDefsCache = { cwd, reg: loadAgentDefinitionsForCwd(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) {
+            this.agentDefsCache = {
+                cwd,
+                disabledKey,
+                reg: loadAgentDefinitionsForCwd(cwd, disabledAgents, disabledPlugins),
+            };
         }
         return this.agentDefsCache.reg;
     }
+    /**
+     * Read settings.disabledAgents, folded with the project's
+     * capabilityOverrides.agents overlay for `cwd`. Unlike disabledSkills,
+     * sub-agents do NOT skip this — a disabled role must stay invisible
+     * everywhere. The overlay lets a project force-enable a globally-disabled
+     * role or force-disable a globally-enabled one (tri-state); read UNMERGED
+     * (getForScope) so inherit survives. No cwd / no overlay → baseline
+     * unchanged. Mirrors readDisabledLists (skills/plugins).
+     */
+    readDisabledAgents(cwd) {
+        try {
+            const sm = this.getSettingsManager();
+            const settings = sm.get();
+            const baseline = Array.isArray(settings.disabledAgents) ? settings.disabledAgents : [];
+            const overrides = cwd
+                ? sm.getForScope("project", cwd).capabilityOverrides
+                : undefined;
+            return effectiveDisabledList(baseline, overrides?.agents);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Read the project's capabilityOverrides.builtin bucket for `cwd`, read
+     * UNMERGED (getForScope) so tri-state inherit survives. Sub-agents skip the
+     * overlay (minimal surface, same as readDisabledLists) — their builtin lists
+     * are already narrowed by resolveChildToolScope. No cwd / error → undefined,
+     * so the caller's baseline builtin lists pass through unchanged.
+     */
+    readBuiltinOverride(cwd) {
+        if (this.config.isSubAgent === true || !cwd)
+            return undefined;
+        try {
+            const overrides = this.getSettingsManager().getForScope("project", cwd)
+                .capabilityOverrides;
+            return overrides?.builtin;
+        }
+        catch {
+            return undefined;
+        }
+    }
     /**
      * Build a base ToolContext for this Engine. Used by run() (which then
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
      * by tests that want a ToolContext without a full run() cycle.
      */
+    resolveSandboxWithoutRuntime(config, cwd) {
+        const key = `${config.mode}:${cwd}`;
+        let cached = this.sandboxCache.get(key);
+        if (!cached) {
+            cached = resolveSandboxBackend(config, cwd);
+            // Mirror EngineRuntime.resolveSandbox: don't cache a rejection, or an
+            // explicit-mode probe that throws stays sticky until process restart even
+            // after the user fixes the config.
+            cached.catch(() => {
+                if (this.sandboxCache.get(key) === cached)
+                    this.sandboxCache.delete(key);
+            });
+            this.sandboxCache.set(key, cached);
+        }
+        return cached;
+    }
     buildToolContext() {
         const { disabledSkills, disabledPlugins } = this.readDisabledLists();
         return {
@@ -1525,10 +2100,20 @@ export class Engine {
             return { disabledSkills: [], disabledPlugins: [] };
         }
         try {
-            const settings = this.getSettingsManager().get();
+            const sm = this.getSettingsManager();
+            const settings = sm.get();
+            // Fold the project capabilityOverrides over the global baseline so a
+            // project can force-enable a globally-disabled skill/plugin or vice
+            // versa. Read the project overlay UNMERGED (getForScope), not the merged
+            // get(), so tri-state inheritance survives. No cwd / no overlay → the
+            // baseline is returned unchanged (zero regression).
+            const cwd = this.config.cwd;
+            const overrides = cwd
+                ? sm.getForScope("project", cwd).capabilityOverrides
+                : undefined;
             return {
-                disabledSkills: settings.disabledSkills ?? [],
-                disabledPlugins: settings.disabledPlugins ?? [],
+                disabledSkills: effectiveDisabledList(settings.disabledSkills ?? [], overrides?.skills),
+                disabledPlugins: effectiveDisabledList(settings.disabledPlugins ?? [], overrides?.plugins),
             };
         }
         catch {