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

package/dist/engine/engine.js

@@ -7,57 +7,175 @@ 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 { applyDynamicToolDef } from "./dynamic-tool-defs.js";
+import { getMergedCatalog } from "../model-catalog/index.js";
+import { modelEntriesFromConnections } from "./model-connections-pool.js";
+import { resolveAuxKey } from "./aux-key.js";
+import { foldRunUsage } from "./session-usage.js";
+import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
+import { resolveSandboxConfig } from "./sandbox-config.js";
+import { sandboxCacheKey } from "./sandbox-cache-key.js";
+import { BUILTIN_TOOL_GUARDS } from "../tool-system/builtin/index.js";
+import { asyncAgentRegistry } from "../tool-system/builtin/agent-registry.js";
+import { backgroundShellManager } from "../runtime/background-shell.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, resolveGoalSetAt, resolveMaxTurns, resolveMaxStopBlocks, } 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, clampContextRatios as clampContextRatiosImpl, } 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 { CredentialStore } from "../credentials/store.js";
+import { isFeatureEnabled, resolveFeatureFlags, } from "../settings/feature-flags.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 { defaultSandboxConfig, resolveSandboxBackend, } from "../tool-system/sandbox/index.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 { ModelPool } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
-import { ProviderCatalog } from "../llm/provider-catalog.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
 import { detectProviderFromApiKey, buildModelPool, } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
 import { parseTaskWithImages, } from "./parse-task.js";
+import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, collectAttachedImagePaths, } from "./image-policy.js";
+import { tryCompressImages } from "./image-compression.js";
+import { buildSessionTitle } from "./session-title.js";
 import { capabilitiesFor } from "../llm/capabilities/index.js";
 import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+import { runDreamConsolidation } from "../services/dream-consolidation.js";
+import { join, isAbsolute } from "node:path";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+/**
+ * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
+ * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
+ * 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.
+ */
+/**
+ * Resolve the working directory for a run. Precedence:
+ *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
+ *
+ * The session-cwd tier is what stops a project-bound session from being
+ * resumed against the wrong directory: when a host omits options.cwd (e.g. its
+ * sidebar repo selection drifted to null), the session's own recorded cwd is
+ * recovered so the engine still loads THAT project's agents/settings/memory,
+ * not whatever process.cwd() happens to be. Pure so the precedence is testable
+ * without standing up an Engine.
+ */
+export function resolveRunCwd(args) {
+    return args.optionCwd ?? args.sessionCwd ?? args.configCwd ?? args.processCwd;
+}
+export function loadAgentDefinitionsForCwd(cwd, disabledAgents = [], disabledPlugins = []) {
+    // userHome() (not raw homedir(), which bun caches at process start and never
+    // re-reads) so the user-agents dir honors a test's process.env.HOME override
+    // and stays consistent with the rest of the codebase's home resolution.
+    const home = userHome();
+    // 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", "AgentSendInput"];
+/**
+ * #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");
 }
-const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel"];
 /**
  * Compute a child Engine's tool scope.
  * - `allowlist` set → child enabled = allowlist minus nested-agent tools
@@ -78,16 +196,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 +236,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;
@@ -118,7 +265,39 @@ export class Engine {
      * LLM response arrives.
      */
     ctxOverheadBySid = new Map();
+    /**
+     * Step-gap steering queue (per sessionId, in-memory). Host pushes user
+     * messages here via enqueueSteer while a run is in flight; the turn loop
+     * drains it at each step boundary and splices them into the next LLM request
+     * WITHOUT aborting (the 不打断 path, vs cancel+resend). Pure memory, forgotten
+     * on process exit — same model as the credential session-allow set, so
+     * multiple Engines don't interfere and it stays cleanly extractable.
+     */
+    steerQueueBySid = new Map();
     activePermission;
+    /**
+     * The TurnLoop of the in-flight run(), exposed so extendGoalRun() can bump a
+     * running goal's turn/budget ceilings mid-run (TODO 3.1). Null when idle.
+     */
+    activeTurnLoop = null;
+    /**
+     * The goal-stop hook of the in-flight goal run, exposed so clearGoal() can
+     * unregister it mid-run (the closure holds the now-cleared goal and would
+     * otherwise keep re-blocking the stop). Null when no goal run is active.
+     */
+    activeGoalHook = null;
+    /**
+     * The in-flight run's session bundle, held so clearGoal() can wipe the goal
+     * on the SAME instance the run loop is persisting each turn — not a fresh
+     * detached copy from resume(). Without this, a mid-run 清除 clears disk, but
+     * the still-running loop's next saveState(bundle.state) resurrects the goal
+     * (bundle.state.activeGoal was never dropped). A never-completing goal run
+     * (judge keeps returning not_met → continueSession) stays live for a long
+     * time, so this write-back race is the norm, not an edge case, for such runs.
+     * Single-valued like activeTurnLoop — one top-level run per engine at a time.
+     * Null when idle; set at run start, cleared in run's finally.
+     */
+    activeRunSession = null;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens() {
         return this.resolveMaxContextTokens();
@@ -127,6 +306,27 @@ export class Engine {
         const modelEntry = this.modelPool.get();
         return modelEntry?.maxContextTokens ?? this.config.maxContextTokens ?? 200_000;
     }
+    /**
+     * Compaction thresholds from settings.context, clamped so they keep the
+     * required ordering floor < compact < summarize even if the user configures
+     * conflicting values (e.g. summarize below compact). Falls back to the
+     * ContextManager defaults when a field is absent.
+     */
+    resolveContextRatios() {
+        let ctx;
+        try {
+            // Read from SettingsManager (shared across all hosts) rather than
+            // EngineConfig, mirroring readMemoriesConfig — avoids per-host wiring
+            // drift (see memory: personalization host wiring).
+            ctx = this.getSettingsManager().get().context;
+        }
+        catch {
+            return {};
+        }
+        if (!ctx)
+            return {};
+        return clampContextRatiosImpl(ctx);
+    }
     /**
      * Emit a lifecycle hook with isSubAgent auto-merged into data so handlers
      * can skip noisy injections for spawned children. All Engine-side hook
@@ -158,13 +358,65 @@ export class Engine {
         }
         const entries = settings.hooks ?? [];
         for (const entry of entries) {
-            this.hooks.register(entry.event, async (ctx) => {
+            // Soft off-switch (settings hooks UI): the entry stays in the file but
+            // doesn't register. reloadHooks() re-runs this, so toggling is hot.
+            if (entry.disabled === true)
+                continue;
+            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 = [];
+        // Also drop & re-load plugin hooks. Plugin hooks are registered under
+        // `plugin:<name>:<event>` names; without this, disabling a plugin
+        // mid-session left its hooks firing until the next new session (asymmetric
+        // with settings-hook hot-reload). Re-reading readDisabledLists means a
+        // now-disabled plugin's hooks are simply not re-registered.
+        this.hooks.removeByNamePrefix("plugin:");
+        try {
+            const { disabledPlugins, disabledPluginHooks } = this.readDisabledLists();
+            loadPluginHooks(this.hooks, disabledPlugins, disabledPluginHooks);
+        }
+        catch {
+            // best-effort — a plugin-load failure must not break settings reload below
+        }
+        // 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;
         // Wire shared runtime (adapter pattern — null when self-constructing).
@@ -173,11 +425,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 +456,15 @@ 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.
+            // disabledPluginHooks is the per-hook overlay
+            // (capabilityOverrides.pluginHooks); applied at construction, so a
+            // toggle takes effect for NEW sessions (same semantics as
+            // disabledPlugins itself).
+            const { disabledPlugins, disabledPluginHooks } = this.readDisabledLists();
+            loadPluginHooks(this.hooks, disabledPlugins, disabledPluginHooks);
         }
         // settings.hooks → shell-command wrappers. Chain order:
         // plugin (80) → shell (50) → code (default 0).
@@ -205,7 +480,7 @@ export class Engine {
         }
     }
     /**
-     * Load models[] / providers[] from settings into the active ModelPool and
+     * Load modelConnections[] from settings into the active ModelPool and
      * resync this.config.llm with the matching entry. Called from the ctor and
      * from reloadModelPool() (e.g. after onboarding writes new entries to disk).
      */
@@ -214,67 +489,82 @@ export class Engine {
             const sm = this.getSettingsManager();
             sm.invalidate();
             const settings = sm.get();
-            if (settings.models?.length) {
-                for (const m of settings.models) {
-                    this.modelPool.register({
-                        key: m.key,
-                        label: m.label,
-                        provider: m.provider ?? "",
-                        model: m.model,
-                        baseUrl: m.baseUrl,
-                        apiKey: m.apiKey,
-                        maxOutputTokens: m.maxOutputTokens,
-                        maxContextTokens: m.maxContextTokens,
-                        providerKey: m.providerKey,
-                    });
-                }
-                // Build catalog from settings.providers[] and attach to the pool
-                // so model entries can resolve baseUrl/apiKey from their provider.
-                if (settings.providers?.length) {
-                    this.modelPool.setProviderCatalog(new ProviderCatalog(settings.providers));
+            // Unified model catalog (统一模型接入方案 §6): register text
+            // connections from settings.modelConnections[] into the pool — the
+            // catalog-driven instance store is the sole source of model selection.
+            // A connection's instance id becomes its pool key. See
+            // docs/superpowers/specs/2026-06-15-unified-model-catalog-design.md.
+            const connections = settings.modelConnections;
+            if (Array.isArray(connections) && connections.length) {
+                const catalog = getMergedCatalog();
+                const credentials = settings.credentials;
+                for (const entry of modelEntriesFromConnections(connections, (Array.isArray(credentials) ? credentials : []), catalog)) {
+                    this.modelPool.register(entry);
                 }
+            }
+            const hasConnections = Array.isArray(connections) && connections.length > 0;
+            if (hasConnections) {
                 this.modelPool.setCacheDir(defaultCacheDir());
                 this.modelPool.reloadCachedContextWindows();
-                // Resolve active entry. Priority:
-                //   1. settings.activeKey — primary source of truth (new shape).
-                //   2. Match settings.model.name against models[].model — legacy
-                //      pre-activeKey configs and the migration path.
-                // We then switch the pool and write the resolved entry's credentials
-                // into config.llm, so the first run() uses the right endpoint instead
-                // of whatever env-derived fallback repl.ts seeded earlier.
-                // Sub-agents skip the activeKey resync: their llm is chosen by the
-                // parent's resolveChildLlm (per-role model routing). activeKey is the
-                // *user's* current UI model selection and must not clobber a child's
-                // routed model — without this guard a role's `model: flash` is silently
-                // overridden back to whatever the user has active in the foreground.
+                // Resolve the active entry from settings.defaults.text, then switch the
+                // pool and write the resolved entry's credentials into config.llm, so the
+                // first run() uses the right endpoint instead of whatever env-derived
+                // fallback repl.ts seeded earlier.
+                // Sub-agents skip this resync: their llm is chosen by the parent's
+                // resolveChildLlm (per-role model routing). defaults.text is the *user's*
+                // current UI model selection and must not clobber a child's routed model —
+                // without this guard a role's `model: flash` is silently overridden back
+                // to whatever the user has active in the foreground.
                 if (this.config.isSubAgent !== true) {
-                    const activeKey = settings.activeKey;
-                    let match;
-                    if (activeKey) {
-                        match = settings.models.find((m) => m.key === activeKey);
+                    const defaultText = settings.defaults?.text;
+                    // 统一 catalog only:defaults.text 命中则用;否则回退首个已注册连接,
+                    // 避免选未配置模型时静默沿用空种子(旧 bug:抛误导性 OPENAI_API_KEY missing)。
+                    let matchKey;
+                    if (defaultText && this.modelPool.list().some((e) => e.key === defaultText)) {
+                        matchKey = defaultText;
                     }
-                    if (!match) {
-                        const currentModel = this.config.llm.model;
-                        // OpenRouter stores entries as "provider/model-name"; the top-level
-                        // settings.model.name is just "model-name". Match either form.
-                        match = settings.models.find((m) => m.model === currentModel ||
-                            (currentModel && m.model?.endsWith(`/${currentModel}`)));
+                    else {
+                        matchKey = this.modelPool.list()[0]?.key;
                     }
-                    if (match) {
-                        const entry = this.modelPool.switch(match.key);
+                    if (matchKey) {
+                        const entry = this.modelPool.switch(matchKey);
                         this.config = {
                             ...this.config,
-                            llm: this.modelPool.toLLMConfig(entry, this.config.llm),
+                            llm: this.modelPool.toLLMConfig(entry),
                         };
                     }
                 }
             }
             else if (this.config.llm.apiKey) {
-                // Auto-populate pool from the configured API key when models[] is empty.
-                // This lets users who only set model.apiKey (without models[]) still
-                // use /model to switch between the provider's available models.
+                // Auto-populate pool from the configured API key when no
+                // modelConnections[] are configured. This lets users who only have an
+                // env/seed API key still 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;
+            // Migrate legacy "original" → "high" (raw settings may bypass schema).
+            const detail = imageSettings?.detail === "original" ? "high" : imageSettings?.detail;
+            if (detail && nextDefaults.imageDetail !== detail) {
+                nextDefaults.imageDetail = 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
@@ -282,7 +572,7 @@ export class Engine {
     }
     /**
      * Re-read settings and refresh the model pool. Used after onboarding /login
-     * writes new providers[] / models[] to disk so the running engine picks them
+     * writes new modelConnections[] to disk so the running engine picks them
      * up without a process restart. Existing pool entries are kept (re-registering
      * the same key overwrites them), so callers don't need to clear first.
      */
@@ -296,7 +586,7 @@ export class Engine {
         }
     }
     /**
-     * Auto-populate the model pool when settings.models[] is empty but
+     * Auto-populate the model pool when no modelConnections[] are configured but
      * the user has configured an API key. Detects the provider from the
      * key prefix / baseUrl and registers all its known models.
      */
@@ -315,7 +605,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,11 +624,100 @@ export class Engine {
     setAskUser(fn) {
         this.config.askUser = fn;
     }
+    /**
+     * Inject the browser automation bridge after construction (same chicken-and-egg
+     * as setAskUser: the desktop host builds the bridge — which drives a webview —
+     * after the Engine exists). Undefined → the browser_* tools degrade with a
+     * clear "no browser panel" error.
+     */
+    setBrowserBridge(bridge) {
+        this.config.browserBridge = bridge;
+    }
+    /**
+     * Queue a user message to be spliced into the in-flight run for `sessionId`
+     * at the next turn-loop step boundary — the 不打断 steering path (vs cancel +
+     * resend). General-purpose: any host path (UI 引导, future agent coordination,
+     * external triggers) can call it. If no run is active for the session the
+     * message simply waits in the queue and is consumed when that session next
+     * runs (rare race; host normally only steers while busy). No-op on blank text.
+     *
+     * `id` is the host's stable queue-entry id. It rides through to the
+     * `steer_injected` event (so the host can match the injected bubble back to
+     * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
+     * entry. A blank id is tolerated but means the entry can't be revoked.
+     */
+    enqueueSteer(sessionId, text, id = "") {
+        if (!sessionId)
+            return;
+        const q = this.steerQueueBySid.get(sessionId) ?? [];
+        const next = enqueueSteerItem(q, id || `steer-${q.length}`, text);
+        if (next === q)
+            return; // blank text dropped
+        this.steerQueueBySid.set(sessionId, next);
+    }
+    /**
+     * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
+     * removed, false if it was already consumed by the turn loop (can't take it
+     * back — it has been spliced into the run).
+     */
+    unsteer(sessionId, id) {
+        const q = this.steerQueueBySid.get(sessionId);
+        if (!q || q.length === 0)
+            return false;
+        const { list, removed } = removeSteerItem(q, id);
+        if (removed)
+            this.steerQueueBySid.set(sessionId, list);
+        return removed;
+    }
+    /** Drain + clear the steer queue for a session (turn loop consumes per step). */
+    consumeSteer(sessionId) {
+        const q = this.steerQueueBySid.get(sessionId);
+        if (!q || q.length === 0)
+            return [];
+        const { drained, rest } = consumeSteerItems(q);
+        this.steerQueueBySid.set(sessionId, rest);
+        return drained;
+    }
+    /** Wire the cookie→browser injection callback (InjectCredential tool). Same
+     *  post-construction injection model as setBrowserBridge. */
+    setInjectCredential(fn) {
+        this.config.injectCredentialToBrowser = 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;
+    }
+    /**
+     * Probe whether a session already exists on disk (its state/transcript dir is
+     * present). Used by the protocol server to distinguish "resume an existing
+     * session" from "silently create a fresh empty one" — e.g. a cron resume job
+     * whose target session the user deleted must fail loudly, not run its prompt
+     * against a blank session. A stat probe, not a load.
+     */
+    sessionExistsOnDisk(sessionId) {
+        return this.sessionManager.exists(sessionId);
+    }
     /**
      * Run a task from start to finish.
      */
     async run(task, options) {
-        const cwd = options?.cwd ?? this.config.cwd ?? process.cwd();
+        // 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)
+            : undefined;
+        const cwd = 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
@@ -352,6 +731,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 +787,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
@@ -429,6 +879,22 @@ export class Engine {
                 permissionMode: this.config.permissionMode ?? "acceptEdits",
             }),
             spawn: async (req) => {
+                // Anchor this sub-agent in the PARENT transcript at spawn time — before
+                // it runs, so it's recorded whether it later completes, is interrupted,
+                // or still runs. Replay reads these anchors to rebuild sub-agent cards
+                // from sessions/<agentId>/ (agentId === childSid); without it a
+                // backgrounded sub-agent leaves no parent-transcript trace and vanishes
+                // on reopen. Only on a fresh spawn (not a resume/continuation, which
+                // already has its anchor). Guarded so a transcript hiccup never breaks
+                // the spawn.
+                if (!req.resumeSessionId) {
+                    try {
+                        session.transcript.appendSubagent(req.agentId, undefined, req.description);
+                    }
+                    catch {
+                        /* anchor is best-effort; never block the spawn */
+                    }
+                }
                 // No nested agents. Strip Agent / AgentStatus / AgentCancel from the
                 // child's tool pool so the LLM can't spawn grandchildren — matches
                 // Claude Code's ALL_AGENT_DISALLOWED_TOOLS approach. Without this
@@ -439,7 +905,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 +919,15 @@ 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,
+                    skillAllowlist: req.skillAllowlist,
                     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.
@@ -490,12 +965,41 @@ export class Engine {
                 // child.run() establishes its own runWithSid scope internally, so
                 // child log lines route to the child's sid and parent's ALS
                 // binding is unaffected when control returns here.
-                const result = await child.run(req.prompt, { signal: req.signal, onStream: childStream });
-                return result.text;
+                //
+                // agent_id === childSid: cold-start the child UNDER its agentId as the
+                // session id (run() shape (2): a fresh sid the host wants materialized),
+                // so the session persists at sessions/<agentId>/ and AgentSendInput can
+                // later resume it by agentId with no extra id→sid mapping. When
+                // resumeSessionId is set we resume that existing session instead —
+                // run() detects the on-disk session and replays its full transcript
+                // (the CC continuation model; see AgentSendInput).
+                const childSessionId = req.resumeSessionId ?? req.agentId;
+                const result = await child.run(req.prompt, {
+                    signal: req.signal,
+                    onStream: childStream,
+                    sessionId: childSessionId,
+                });
+                return { text: result.text, sessionId: result.sessionId };
             },
+            sessionExists: (sessionId) => this.sessionManager.exists(sessionId),
         };
-        const sandboxConfig = this.config.sandbox ??
-            defaultSandboxConfig(this.config.headless ? "auto" : "off");
+        // 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);
         // 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
@@ -504,11 +1008,22 @@ 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);
+        // Observability: surface what sandbox actually applied this run — the
+        // configured mode vs the resolved backend (auto may downgrade to off when
+        // no OS backend is available) + the network policy. Without this you can't
+        // tell whether shell commands were isolated /网络放没放. One line per run.
+        logger.info("sandbox.resolved", {
+            mode: sandboxConfig.mode,
+            backend: sandboxBackend.name,
+            isolated: sandboxBackend.name !== "off",
+            network: sandboxConfig.network,
+            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
@@ -517,7 +1032,13 @@ export class Engine {
             ...this.buildToolContext(),
             subAgentSpawner,
             agentDefinitions: this.getAgentDefinitions(cwd),
-            sandbox: sandboxBackend,
+            // Stamp the resolved network policy onto the backend the tools see so
+            // Bash can surface "网络 deny" on its result. Shallow-copy (don't mutate
+            // the cached backend) — `wrap`/`hintForBlockedOutput` are plain function
+            // properties and survive the spread. Off keeps network undefined.
+            sandbox: sandboxBackend.name === "off"
+                ? sandboxBackend
+                : { ...sandboxBackend, network: sandboxConfig.network },
             cwd,
             // TodoWrite reads this to push task_update events independently
             // of its return value, so the UI's pinned task panel refreshes
@@ -538,10 +1059,24 @@ export class Engine {
         // text block (when prose is present) followed by one image block per
         // attachment — the provider-specific clients translate this to OpenAI
         // `image_url` or Anthropic `{type:image, source:base64}` downstream.
+        // When an attached image came from a workspace FILE (the desktop composer's
+        // path-attach flow sets ParsedImage.name = the absolute path), surface that
+        // path to the model as text. The image bytes still ride along for vision,
+        // but tools that operate on files — GenerateImage(referenceImages),
+        // Read, etc. — need the on-disk path, not just the pixels. Without this the
+        // path the composer already knew was silently dropped, and the model would
+        // answer "图片没落到项目文件夹，找不到路径" (the seedance 图生图 dead-end).
+        // Only names that resolve to an existing file qualify; a pasted screenshot
+        // whose name is just "screenshot.png" is not a path and is left out.
+        const attachedPaths = collectAttachedImagePaths(parsedTask.images, (name) => (isAbsolute(name) ? name : join(cwd, name)), existsSync);
+        const pathHint = attachedPaths.length > 0
+            ? `\n\n<attached-image-paths>\n${attachedPaths.join("\n")}\n</attached-image-paths>\n` +
+                `(上面附带的图片在工作区的真实路径，如需把它们作为工具输入（例如 GenerateImage 的 referenceImages、图生图参考图），直接使用这些路径。)`
+            : "";
         const userMessageContent = parsedTask.hasImages
             ? [
-                ...(parsedTask.text
-                    ? [{ type: "text", text: parsedTask.text }]
+                ...(parsedTask.text || pathHint
+                    ? [{ type: "text", text: `${parsedTask.text}${pathHint}` }]
                     : []),
                 ...parsedTask.images.map((img) => ({
                     type: "image",
@@ -570,9 +1105,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
@@ -593,7 +1127,7 @@ export class Engine {
             // Append new user message
             const userMsg = { role: "user", content: userMessageContent };
             messages.push(userMsg);
-            session.transcript.appendMessage("user", userMessageContent);
+            session.transcript.appendMessage("user", userMessageContent, { injected: options?.injected === true });
             // Flush "active" status to disk immediately. resume() set it in memory
             // (session-manager.ts), but without this write the on-disk state.json
             // still shows the previous run's terminal reason — so any external
@@ -604,7 +1138,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
@@ -616,6 +1150,12 @@ export class Engine {
             session.state.summary = summarySrc.slice(0, 80).replace(/\n/g, " ");
             this.sessionManager.saveState(session.state);
         }
+        // Bump the conversation-turn counter: this user message starts a new turn.
+        // One user message = one turn, regardless of how many turn-loop iterations
+        // or tool calls it spans. File-history snapshots taken below are tagged
+        // 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
@@ -730,7 +1270,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 +1291,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
@@ -760,6 +1304,9 @@ export class Engine {
             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();
@@ -769,8 +1316,13 @@ 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,
+                skillAllowlist: this.config.skillAllowlist,
+                memoriesMaxAgeDays: this.readMemoriesConfig()?.maxAge,
             });
             // Connect MCP servers (if configured and not already connected).
             // B1: prefer the Runtime-owned MCPManager so all sessions in a
@@ -785,40 +1337,103 @@ export class Engine {
                 else {
                     this.mcpManager = new MCPManager(this.toolRegistry);
                 }
-                await this.mcpManager.connectAll(mcpServers);
+                await this.mcpManager.connectAll(mcpServers, this);
             }
             // Parallelize slow initialization:
             //   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;
+            }
+            // MCP tool exposure is per-SESSION even though the pool/registry are
+            // worker-shared (B1): a server connected by another project's session
+            // registers its tools into the SHARED registry, and without this filter
+            // they leaked into every session (e.g. chrome-devtools tools showing up
+            // in a project that never enabled the plugin). Keep an MCP tool only when
+            // its server is in THIS session's merged config.mcpServers — which
+            // already folds the project's capabilityOverrides. Gated on the config
+            // being present: engines without one (sub-agents, bare tests) have no
+            // MCP tools in their private registries anyway.
+            const allowedMcpServers = new Set(Object.entries(this.config.mcpServers ?? {})
+                .filter(([, c]) => c.enabled !== false)
+                .map(([n]) => n));
+            toolCtx.allowedMcpServers = allowedMcpServers;
+            const mcpVisible = (toolName) => {
+                const reg = this.toolRegistry.getTool(toolName);
+                return reg?.source !== "mcp" || allowedMcpServers.has(reg?.serverName ?? "");
+            };
+            // Feature-flag visibility: a builtin mapped in TOOL_FEATURE_FLAGS is
+            // hidden when its flag resolves to false (default-on flags only hide when
+            // explicitly disabled, so zero regression out of the box). Read once per
+            // turn so flipping a flag in settings takes effect on the NEXT message,
+            // like the other capability kinds.
+            const featureFlags = this.readFeatureFlags();
+            const allToolDefs = applyBuiltinOverrideVisibility(this.toolRegistry.getToolDefinitions(), builtinOverride)
+                .filter((t) => mcpVisible(t.name))
+                .filter((t) => {
+                const guard = BUILTIN_TOOL_GUARDS.get(t.name);
+                return guard ? guard(guardCwd) : true;
+            })
+                .filter((t) => {
+                const flag = TOOL_FEATURE_FLAGS.get(t.name);
+                return flag ? isFeatureEnabled(featureFlags, flag) : true;
+            })
+                // Dynamic per-engine bits the static defs can't carry: the Agent tool's
+                // agent_type enum + listing, and the image/video provider names. See
+                // applyDynamicToolDef — forwarding only the Agent description (dropping
+                // its rebuilt inputSchema) used to strip the agent_type enum, so the
+                // model omitted agent_type and configured roles never applied.
+                .map((t) => applyDynamicToolDef(t, toolCtx.agentDefinitions, guardCwd));
+            // 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([
+            const [llmClient, fullSystemPrompt, dynamicContextMsg] = await Promise.all([
                 llmClientPromise,
+                // System prompt is now the STABLE prefix only — skills + git status moved
+                // out to a trailing per-turn message so they no longer bust the cache.
                 promptComposer.buildSystemPrompt(toolDefs),
-                promptComposer.buildSystemContext(),
+                promptComposer.buildDynamicContextMessage(),
             ]);
-            const fullSystemPrompt = [systemPrompt, systemContext].filter(Boolean).join("\n\n");
             // Prepend userContext (CLAUDE.md) as first message (sync, fast)
             const userContextMsg = promptComposer.buildUserContextMessage();
             if (userContextMsg) {
@@ -837,6 +1452,12 @@ export class Engine {
                 // reminder → user request.
                 messages.splice(messages.length - 1, 0, lifecycleReminder);
             }
+            // Volatile context (skills + git status) goes at the very END — after the
+            // user task — so it sits past the conversation's cache breakpoint. A change
+            // here (new skill, edited file) never invalidates the cached history prefix.
+            if (dynamicContextMsg) {
+                messages.push(dynamicContextMsg);
+            }
             this.lastSessionId = session.state.sessionId;
             this.lastMessages = messages;
             // Wire up LLM summarization for context compaction
@@ -848,8 +1469,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,12 +1485,17 @@ 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;
             });
-            // Create components (requires resolved llmClient)
+            // Create components (requires resolved llmClient).
             const modelFacade = new ModelFacade(llmClient, session.transcript);
+            // Session-cumulative usage baseline: the LLM client is recreated per run
+            // (its getUsage() counts only THIS run), so to accumulate across runs we
+            // capture the persisted total at run start and fold this run's usage onto
+            // it (see foldRunUsage). Snapshot now, before any turn boundary fires.
+            const usageBaseline = { ...session.state.tokenUsage };
             // Wire getOutputTokens for token budget tracking
             modelFacade.getOutputTokens = () => {
                 const usage = llmClient.getUsage();
@@ -873,14 +1506,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,22 +1528,115 @@ 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) => {
+            // Keep a reference so we can unregister in the finally below. Registering an
+            // anonymous handler every run() leaks: unregister matches by handler
+            // identity, so without a stored reference each run stacks another identical
+            // on_tool_start handler that fires (and re-snapshots) on every tool forever.
+            const fileHistoryHandler = async (context) => {
                 const toolName = context.data?.toolName;
                 const args = context.data?.args;
+                // Tag snapshots with the current turn (stamped above before any tool
+                // runs) so turn-level /undo can revert just this user message's edits.
+                const turnSeq = session.state.turnSeq;
                 if ((toolName === "Write" || toolName === "Edit") && args?.file_path) {
-                    fileHistory.saveSnapshot(args.file_path);
+                    const path = args.file_path;
+                    // saveSnapshot returns null when the file does not exist yet — this
+                    // hook runs BEFORE the tool, so a null here means the turn is CREATING
+                    // the file. Record it (idempotent per turn) so /undo can delete it and
+                    // /redo can recreate it.
+                    if (fileHistory.saveSnapshot(path, turnSeq) === null && turnSeq !== undefined) {
+                        fileHistory.recordCreated(path, turnSeq);
+                    }
+                }
+                else if (toolName === "ApplyPatch" && typeof args?.patch === "string") {
+                    // ApplyPatch mutates files too, so /undo must see them. Snapshot every
+                    // existing file the patch updates or deletes (adds have no prior
+                    // content). Resolve relative patch paths against the engine cwd, the
+                    // same base ApplyPatch itself uses.
+                    const cwd = this.config.cwd ?? process.cwd();
+                    for (const target of patchBackupTargets(args.patch, cwd)) {
+                        fileHistory.saveSnapshot(target, turnSeq);
+                    }
                 }
                 return {};
-            }, 100, "file_history_backup");
+            };
+            this.hooks.register("on_tool_start", fileHistoryHandler, 100, "file_history_backup");
             // Hook: agent start
             await this.emitHook("on_agent_start", {
                 sessionId: session.state.sessionId,
                 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 runs on `auxSummaryClient`
+            // — the same cheap aux model used for summarize/compaction — not the
+            // (potentially expensive) session model: "is this goal met?" is a classic
+            // aux-tier task, and a goal run can invoke the judge up to maxStopBlocks
+            // times.
+            // Normalize the raw goal (string | GoalConfig) once at the run boundary;
+            // everything inward uses the GoalConfig. normalizeGoal() returns undefined
+            // when there's effectively no goal (empty objective).
+            //
+            // PERSISTENT GOAL (CC /goal style): a goal set on one send survives across
+            // later sends and manual interrupts until met or cleared. Resolution:
+            //   1. options.goal — this send explicitly sets/replaces the goal.
+            //   2. session.state.activeGoal — a goal set on an earlier send.
+            //   3. config.goal — engine-level default (rare; e.g. headless).
+            // When (1) supplies a goal that differs from the stored one we REPLACE the
+            // persisted active goal (one active goal per session) and announce it. A
+            // bare send with no options.goal inherits the stored active goal so the
+            // model keeps working toward it — that's what makes it persistent.
+            const explicitGoal = normalizeGoal(options?.goal);
+            const storedGoal = this.config.isSubAgent !== true ? session.state.activeGoal : undefined;
+            if (explicitGoal && this.config.isSubAgent !== true) {
+                const replaced = !!storedGoal && storedGoal.objective !== explicitGoal.objective;
+                // Stamp WHEN this goal was set so the judge can anchor relative deadlines
+                // ("做到3点") to the set time, not "now" — else once the clock passes the
+                // deadline the judge could read "3点" as tomorrow's and never stop. A new
+                // or changed objective gets a fresh stamp; re-sending the SAME objective
+                // keeps the original anchor (the goal continues, the user didn't restate a
+                // new deadline). User input never carries setAtMs, so we set it here.
+                explicitGoal.setAtMs = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
+                session.state.activeGoal = explicitGoal;
+                this.sessionManager.saveState(session.state);
+                options?.onStream?.({
+                    type: "goal_set",
+                    objective: explicitGoal.objective,
+                    replaced,
+                });
+            }
+            const normalizedGoal = explicitGoal ?? storedGoal ?? normalizeGoal(this.config.goal);
+            let goalHookHandler = null;
+            if (normalizedGoal && this.config.isSubAgent !== true) {
+                goalHookHandler = createGoalStopHook({
+                    goal: normalizedGoal,
+                    llm: auxSummaryClient,
+                    log: logger,
+                    // Clear the persisted active goal the moment the judge says it's met,
+                    // so a later bare send doesn't re-inherit a satisfied goal. The hook
+                    // calls this from inside its met branch (single source of truth for
+                    // "goal achieved"); engine owns the persistence side-effect.
+                    onMet: () => {
+                        if (session.state.activeGoal) {
+                            session.state.activeGoal = undefined;
+                            this.sessionManager.saveState(session.state);
+                        }
+                    },
+                    // Re-read the persisted goal each turn so a mid-run 清除 (clearGoal
+                    // wrote state.json but this hook's frozen goal copy + the closure's
+                    // in-RAM session are untouched) actually stops the judge. Reads disk
+                    // via readActiveGoal — authoritative and independent of which session
+                    // instance the run closure holds.
+                    isGoalActive: (sid) => this.sessionManager.readActiveGoal(sid) !== undefined,
+                });
+                this.hooks.register("on_stop", goalHookHandler, 0, "goal-stop");
+                // Expose for clearGoal() mid-run. Already guarded by isSubAgent above.
+                this.activeGoalHook = goalHookHandler;
+            }
             // 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
@@ -936,6 +1662,22 @@ export class Engine {
                     pendingCompactInfo = null;
                     return info;
                 },
+                consumeSteer: () => this.consumeSteer(sid),
+                // Clear the persisted goal for a self-reported completion / confirmed
+                // cancel. Clears the in-RAM session's activeGoal (so THIS run's later
+                // turns don't re-arm) AND persists it, and drops the in-flight stop
+                // hook so nothing re-blocks the stop we're about to return.
+                clearPersistedGoal: () => {
+                    if (session.state.activeGoal !== undefined) {
+                        session.state.activeGoal = undefined;
+                        this.sessionManager.saveState(session.state);
+                    }
+                    if (goalHookHandler) {
+                        this.hooks.unregister("on_stop", goalHookHandler);
+                        if (this.activeGoalHook === goalHookHandler)
+                            this.activeGoalHook = null;
+                    }
+                },
                 ctxOverheadStore: {
                     get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
                     set: (s, n) => {
@@ -943,29 +1685,142 @@ export class Engine {
                     },
                 },
             }, {
-                maxTurns: this.config.maxTurns ?? 100,
-                maxToolCallsPerTurn: this.config.maxToolCallsPerTurn ?? 10,
+                // Goal mode raises the turn ceiling: an unattended goal run keeps
+                // getting re-blocked by the stop-hook until it's done, and the 100
+                // interactive default would silently truncate a long objective. The
+                // real backstops are the goal token/time budgets + maxStopBlocks.
+                maxTurns: resolveMaxTurns(this.config.maxTurns, normalizedGoal),
+                // Consecutive stop-block cap: config override > goal.maxStopBlocks >
+                // GOAL_DEFAULT_MAX_STOP_BLOCKS(25). The old hardcoded 8 was too tight
+                // for complex goals that legitimately get re-blocked while advancing.
+                maxStopBlocks: resolveMaxStopBlocks(this.config.maxStopBlocks, normalizedGoal),
+                // 25 (was 10): modern models routinely batch >10 parallel tool calls
+                // (e.g. reading a dozen files at once). At 10 the excess was silently
+                // dropped; the turn loop now also warns the model when it caps, but a
+                // higher ceiling avoids the round-trip in the common case. (B-3)
+                maxToolCallsPerTurn: this.config.maxToolCallsPerTurn ?? 25,
                 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
                 // completed run.
                 onTurnBoundary: (turnCount) => {
                     session.state.turnCount = turnCount;
-                    const u = modelFacade.getUsage();
-                    session.state.tokenUsage = {
-                        promptTokens: u.totalPromptTokens,
-                        completionTokens: u.totalCompletionTokens,
-                        totalTokens: u.totalTokens,
-                    };
+                    // baseline + this run's running total (idempotent per boundary,
+                    // accumulates across runs; carries cacheRead/cacheCreation too).
+                    session.state.tokenUsage = foldRunUsage(usageBaseline, modelFacade.getUsage());
+                    // Surface the session-cumulative cache counts to the UI (the "本会话
+                    // 累计命中率" tooltip). Separate from turn-loop's per-response
+                    // usage_update (which drives the live context reading).
+                    const cum = session.state.tokenUsage;
+                    options?.onStream?.({
+                        type: "usage_update",
+                        promptTokens: cum.promptTokens,
+                        sessionPromptTokens: cum.promptTokens,
+                        sessionCacheReadTokens: cum.cacheReadTokens ?? 0,
+                        sessionCacheCreationTokens: cum.cacheCreationTokens ?? 0,
+                    });
                     if (this.config.costStore) {
                         session.state.costState = this.config.costStore.serialize();
                     }
                     this.sessionManager.saveState(session.state);
                 },
             });
-            const result = await turnLoop.run(messages);
+            // Expose this run's loop for mid-run extension (TODO 3.1). Top-level only —
+            // a sub-agent's loop is its own concern and isn't user-extendable.
+            if (this.config.isSubAgent !== true)
+                this.activeTurnLoop = turnLoop;
+            // Expose this run's session bundle so a mid-run clearGoal() wipes the goal
+            // on the very instance this loop keeps saving (see field doc). Top-level
+            // only — sub-agents don't carry user-clearable persistent goals.
+            if (this.config.isSubAgent !== true)
+                this.activeRunSession = session;
+            let result;
+            try {
+                result = await turnLoop.run(messages);
+                // ── Headless: drain background sub-agents before resolving ───────
+                // Unified background-work model (2026-06-17): the engine NO LONGER parks
+                // every run waiting on background work. Background work (sub-agents,
+                // video polls, shells) ends the turn, yields, and is picked up later by
+                // the server's notification-wakeup path (maybeWakeIdleSession). The
+                // INTERACTIVE path relies on that wakeup + a run-boundary re-check.
+                //
+                // HEADLESS is the exception: a one-shot `engine.run` whose caller takes
+                // `result.text` as THE answer (automation / SDK) has no later turn to
+                // pick up a wakeup — so it must wait, before resolving, until its own
+                // background SUB-AGENTS finish and summarize. Only sub-agents (their
+                // summary IS part of this run's result), NOT shells (a dev server never
+                // exits → would hang headless forever) and NOT video (a long render the
+                // one-shot run shouldn't block on). This replaces the old for(;;) park
+                // (s-mpvf4rsj-bb6e4639 invariant) for the headless case only.
+                const sid = session.state.sessionId;
+                const isTopLevel = this.config.isSubAgent !== true;
+                if (isTopLevel && this.isHeadless()) {
+                    let aborted = options?.signal?.aborted === true;
+                    // Loop: a summarize turn can spawn a NEW background sub-agent; keep
+                    // draining + summarizing until none remain. turnCount accumulates, so
+                    // the turn-loop's maxTurns still bounds runaway re-summarization.
+                    for (;;) {
+                        while (!aborted && asyncAgentRegistry.hasRunningForSession(sid)) {
+                            aborted = await this.waitForBackgroundAgentChange(sid, options?.signal);
+                        }
+                        let pending = notificationQueue.drainAll(sid);
+                        if (aborted && pending.length === 0) {
+                            // Abort race: an agent calls markCompleted (registry notify) and only
+                            // THEN enqueue (queue notify) as two separate statements. If the abort
+                            // fired before that agent's completion `.then` ran, the while above
+                            // exited on `aborted`, this drainAll caught nothing, and a naive
+                            // `break` here would drop the agent's output. Give still-settling
+                            // agents a bounded window to finish enqueuing, then drain once more.
+                            // Each wait is timeout-bounded so a genuinely stuck (never-completing)
+                            // agent can't hang abort cleanup forever — we'd rather lose nothing in
+                            // the common case and not hang in the pathological one.
+                            for (let i = 0; i < 20 && asyncAgentRegistry.hasRunningForSession(sid); i++) {
+                                const changed = await this.waitForBackgroundAgentChangeOrTimeout(sid, 25);
+                                if (!changed)
+                                    break; // timed out with no state change → stop waiting
+                            }
+                            pending = notificationQueue.drainAll(sid);
+                            if (pending.length === 0)
+                                break;
+                        }
+                        else if (pending.length === 0) {
+                            break;
+                        }
+                        const injected = {
+                            role: "user",
+                            content: `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`,
+                        };
+                        if (aborted) {
+                            // Mark injected: a synthetic notification, not the user's own input —
+                            // the disk reader drops it on replay so no phantom user bubble.
+                            session.transcript.appendMessage(injected.role, injected.content, { injected: true });
+                            result = { ...result, messages: [...result.messages, injected] };
+                            break;
+                        }
+                        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);
+                if (this.activeGoalHook === goalHookHandler)
+                    this.activeGoalHook = null;
+                if (this.activeTurnLoop === turnLoop)
+                    this.activeTurnLoop = null;
+                if (this.activeRunSession === session)
+                    this.activeRunSession = null;
+                // Run-scoped too: this handler is re-registered every run(), so it must be
+                // dropped here or it stacks duplicates that re-snapshot on every tool.
+                this.hooks.unregister("on_tool_start", fileHistoryHandler);
+            }
             this.lastMessages = result.messages;
             this.compactedMessagesBySession.set(session.state.sessionId, this.stripUserContextMessage(result.messages, userContextMsg));
             logger.info("engine.done", {
@@ -992,6 +1847,37 @@ 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) {
+                            // Persist the title so it survives a localStorage wipe / disk
+                            // rebuild — it used to live only in the renderer's localStorage
+                            // index. This .then resolves AFTER the saveState below (:1892), so
+                            // it must save again itself rather than rely on that write.
+                            session.state.title = title;
+                            this.sessionManager.saveState(session.state);
+                            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
@@ -999,12 +1885,9 @@ export class Engine {
             // distinction and misled anyone reading state.json.
             session.state.turnCount = turnLoop.currentTurn;
             session.state.status = result.reason;
+            // Session-cumulative (baseline + this run) for persistence...
             const usage = modelFacade.getUsage();
-            session.state.tokenUsage = {
-                promptTokens: usage.totalPromptTokens,
-                completionTokens: usage.totalCompletionTokens,
-                totalTokens: usage.totalTokens,
-            };
+            session.state.tokenUsage = foldRunUsage(usageBaseline, usage);
             if (this.config.costStore) {
                 session.state.costState = this.config.costStore.serialize();
             }
@@ -1035,8 +1918,73 @@ 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.defaults.auxText 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();
+            // Unified store's defaults.auxText (a connection id = pool key) selects
+            // the aux model; resolveAuxKey returns it (or undefined).
+            auxKey = resolveAuxKey(sm.get());
+        }
+        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.
+            // settings.memories.extractionModel (if set + valid) overrides the aux
+            // model specifically for memory extraction (TODO 8.1).
+            const llmClient = await this.resolveExtractionClient(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,12 +2017,16 @@ export class Engine {
                         tools: [],
                         maxTokens: 1024,
                         recordUsage: false,
-                        thinking: "disabled",
+                        reasoning: { mode: "off" },
                     });
                     return resp.text;
                 },
                 runDream: async ({ systemPrompt, userPrompt, projectDir }) => this.runDreamLoop({ systemPrompt, userPrompt, projectDir, llmClient, sessionId }),
                 projectDir: cwd,
+                // settings.memories.maxCount caps memories accepted per extraction;
+                // autoExtract=false turns the extractor off (summaries/dream stay).
+                maxCount: this.readMemoriesConfig()?.maxCount,
+                autoExtract: this.readMemoriesConfig()?.autoExtract,
             });
             await orchestrator.run(plainMessages, sessionId);
         }
@@ -1103,117 +2055,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;
@@ -1222,30 +2077,62 @@ export class Engine {
      * Switch the active model by pool key. Takes effect on the next run() call.
      * Returns the new model entry.
      *
-     * Persists settings.activeKey (and a legacy settings.model.* mirror) so the
+     * Persists settings.defaults.text (= the connection id / pool key) so the
      * next process startup defaults to the same model — without this, switches
      * only live in memory and every restart reverts to the previously persisted
-     * activeKey.
+     * defaults.text.
      */
     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);
+        this.persistActiveModel(entry);
         return entry;
     }
+    /**
+     * Zero a session's cumulative token/cache usage on disk. Called on a model
+     * switch: a different model has its own prompt cache, so the accumulated
+     * cache-hit stats from the prior model are no longer meaningful. The next
+     * run's baseline (snapshotted from state.tokenUsage) then starts from zero.
+     */
+    resetSessionUsage(sessionId) {
+        const zero = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        // If the session is mid-run right now, update its live state so the next
+        // turn-boundary write doesn't re-fold a stale baseline.
+        if (this.activeRunSession?.state.sessionId === sessionId) {
+            this.activeRunSession.state.tokenUsage = { ...zero };
+        }
+        // Persist to disk so a reload / next run picks up the reset.
+        if (this.sessionManager.exists(sessionId)) {
+            try {
+                const bundle = this.sessionManager.resume(sessionId);
+                bundle.state.tokenUsage = { ...zero };
+                this.sessionManager.saveState(bundle.state);
+            }
+            catch {
+                // Session not resumable (never persisted yet) — the in-memory reset
+                // above covers the live case; nothing else to do.
+            }
+        }
+    }
     /**
      * Write the active model selection to ~/.code-shell/settings.json.
      *
-     * We mirror into the legacy settings.model.* block (provider/name/apiKey/
-     * baseUrl) because boot paths in cli/main.ts, repl.ts, run.ts still read it.
-     * The mirror uses resolved llm values (not raw entry.*) so credentials that
-     * live on settings.providers[] flow through correctly — entry.apiKey is
-     * undefined when the entry resolves via providerCatalog.
+     * Persists settings.defaults.text = entry.key (the connection id == pool
+     * key). That is the single field the boot path reads to restore the active
+     * text model on the next startup (see ctor: settings.defaults.text → pool
+     * switch). No legacy activeKey/model.* mirror is written.
      */
-    persistActiveModel(entry, llm) {
+    persistActiveModel(entry) {
         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 = {};
@@ -1258,29 +2145,30 @@ export class Engine {
                     return;
                 }
             }
-            const prevModel = typeof existing.model === "object" && existing.model
-                ? existing.model
+            const prevDefaults = typeof existing.defaults === "object" && existing.defaults
+                ? existing.defaults
                 : {};
             const updated = {
                 ...existing,
-                activeKey: entry.key,
-                model: {
-                    ...prevModel,
-                    provider: llm.provider,
-                    name: entry.model,
-                    apiKey: llm.apiKey,
-                    baseUrl: llm.baseUrl,
-                },
+                defaults: { ...prevDefaults, text: entry.key },
             };
+            // mode 0o600: this writes model.apiKey (plaintext) into settings.json, so
+            // it must be owner-only — same R-1 hardening as SettingsManager/onboarding.
+            // (Third settings.json writer; the R-1 sweep initially missed this one.)
             const tmp = `${file}.${process.pid}.tmp`;
             const payload = JSON.stringify(updated, null, 2) + "\n";
-            writeFileSync(tmp, payload, "utf-8");
+            writeFileSync(tmp, payload, { encoding: "utf-8", mode: 0o600 });
             try {
                 renameSync(tmp, file);
             }
             catch {
-                writeFileSync(file, payload, "utf-8");
+                writeFileSync(file, payload, { encoding: "utf-8", mode: 0o600 });
+            }
+            // mode arg only applies on create; tighten an already-existing file too.
+            try {
+                chmodSync(file, 0o600);
             }
+            catch { /* best-effort */ }
         }
         catch (err) {
             logger.warn(`persistActiveModel failed: ${err.message}`);
@@ -1303,6 +2191,82 @@ 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: reconciles the shared MCP pool against the new disk-default server
+     * set. Added servers connect idempotently; removed/disabled servers are
+     * disconnected and their registered MCP tools are unregistered so plugin
+     * disable takes effect without an Electron restart.
+     *
+     * 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) {
+            // Fire-and-forget reconcile (connect added / disconnect removed servers).
+            // It must NOT surface as an unhandled rejection: a single flaky server
+            // that fails to connect/disconnect during hot-reload would otherwise
+            // crash the host process (or be silently swallowed). Catch + log so the
+            // reconcile is best-effort and the next reload can retry.
+            void this.mcpManager.reconcile(patch.mcpServers, this).catch((err) => {
+                logger.error("engine.mcp_reconcile_failed", {
+                    error: err instanceof Error ? err.message : String(err),
+                    version,
+                });
+            });
+        }
+        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
@@ -1312,6 +2276,55 @@ export class Engine {
      * engine.run() call for this session picks up the injected content
      * instead of a stale snapshot from the previous run.
      */
+    /**
+     * Read a session's persisted active goal WITHOUT resuming it (cheap — reads
+     * only state.json via SessionManager.readActiveGoal). The desktop host calls
+     * this on session load to re-surface the goal block + its Cancel button: a
+     * persistent goal lives only in state.activeGoal and is never replayed from
+     * the transcript, so after a reload of an aborted goal run the UI would
+     * otherwise show nothing (the "goal 还在但页面不显示、取消不了" bug). Returns
+     * undefined when the session is unknown or has no active goal.
+     */
+    getGoal(sessionId) {
+        return this.sessionManager.readActiveGoal(sessionId);
+    }
+    /**
+     * Clear a session's persisted active goal (CC `/goal clear`). Works whether
+     * the session is idle or its goal run is in flight: it wipes
+     * `state.activeGoal` (so the next bare send won't re-inherit it) and, if a
+     * goal hook is currently registered for this engine, unregisters it so an
+     * in-flight run can stop instead of being re-blocked by the now-cleared goal.
+     * Returns true if a goal was actually cleared. Idempotent — clearing a
+     * session with no active goal is a no-op returning false.
+     */
+    clearGoal(sessionId) {
+        if (!this.sessionManager.exists(sessionId))
+            return false;
+        // Prefer the LIVE run's bundle when it's this session: clearing its
+        // in-RAM state.activeGoal is what stops the run loop from writing the goal
+        // back on its next saveState. A fresh resume() copy would be cleared and
+        // persisted, but the running loop's own detached bundle still holds the
+        // goal and resurrects it — the stale-write-back race. Falls back to a
+        // resumed copy when no run of this session is currently in flight.
+        const live = this.activeRunSession && this.activeRunSession.state.sessionId === sessionId
+            ? this.activeRunSession
+            : null;
+        const session = live ?? this.sessionManager.resume(sessionId);
+        const had = session.state.activeGoal !== undefined;
+        if (had) {
+            session.state.activeGoal = undefined;
+            this.sessionManager.saveState(session.state);
+        }
+        // If THIS session's goal run is in flight, drop its stop hook so the
+        // current run can terminate (the closure-held goal would otherwise keep
+        // re-blocking). The run's own `finally` also unregisters; double-unregister
+        // is safe (set delete is idempotent).
+        if (this.activeGoalHook && this.lastSessionId === sessionId) {
+            this.hooks.unregister("on_stop", this.activeGoalHook);
+            this.activeGoalHook = null;
+        }
+        return had;
+    }
     injectContext(sessionId, content) {
         const session = this.sessionManager.resume(sessionId);
         session.transcript.appendMessage("assistant", content);
@@ -1332,7 +2345,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);
@@ -1354,7 +2366,7 @@ export class Engine {
     }
     getSettingsManager() {
         if (!this.settingsManager) {
-            this.settingsManager = new SettingsManager(this.config.cwd, this.config.settingsScope ?? "project");
+            this.settingsManager = new SettingsManager(this.config.cwd, this.config.settingsScope ?? "project", this.config.projectTrusted !== false);
         }
         return this.settingsManager;
     }
@@ -1406,7 +2418,7 @@ export class Engine {
             rules.push({ tool: "Bash", decision: "allow" });
         }
         try {
-            const settingsManager = new SettingsManager(cwd, this.config.settingsScope ?? "project");
+            const settingsManager = new SettingsManager(cwd, this.config.settingsScope ?? "project", this.config.projectTrusted !== false);
             const settings = settingsManager.get();
             if (settings.permissions?.rules?.length) {
                 rules.unshift(...settings.permissions.rules);
@@ -1461,6 +2473,26 @@ export class Engine {
     getPermissionMode() {
         return this.config.permissionMode ?? "acceptEdits";
     }
+    /**
+     * Extend the in-flight run's turn ceiling and/or goal budgets (TODO 3.1 —
+     * 运行中续轮/加预算). No-op (returns null) when no run is active. Lets a user
+     * keep an unattended goal going past its original cap instead of restarting.
+     */
+    extendGoalRun(opts) {
+        if (!this.activeTurnLoop)
+            return null;
+        return this.activeTurnLoop.extend(opts);
+    }
+    /**
+     * The effective permission rules for the current mode + cwd (TODO 5.1) —
+     * preset defaults + mode-derived + settings.permissions.rules, in the same
+     * order the classifier evaluates them. Exposed read-only so `/permissions`
+     * (and any UI) can list what's actually in force. Pure read; builds the same
+     * rule set buildPermissionConfig does, without constructing a backend.
+     */
+    getPermissionRules() {
+        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd()).rules;
+    }
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
      * Also syncs permissionMode to keep both fields consistent.
@@ -1477,36 +2509,275 @@ 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 });
+        });
+    }
+    /**
+     * Like waitForBackgroundAgentChange but with no abort signal and a hard
+     * timeout. Resolves `true` on a registry/queue change, `false` if `timeoutMs`
+     * elapses first. Used only by the headless abort-drain cleanup, where we want
+     * to catch a completing agent's just-about-to-enqueue notification without
+     * risking a permanent hang on an agent that never completes.
+     */
+    waitForBackgroundAgentChangeOrTimeout(_sessionId, timeoutMs) {
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = (changed) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                unsubRegistry();
+                unsubQueue();
+                resolve(changed);
+            };
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            const unsubRegistry = asyncAgentRegistry.subscribe(() => finish(true));
+            const unsubQueue = notificationQueue.subscribe(() => finish(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 = sandboxCacheKey(config, 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;
+    }
+    /**
+     * Build the shell env layered onto the Bash tool / background shells (see
+     * mergeShellEnv). Three user-configured sources, merged lowest → highest:
+     *
+     *   1. project `localEnvironment.env`  — the per-project "local environment"
+     *      panel (DATABASE_URL etc.); the floor, so a project's own panel values
+     *      can be overridden by an explicit top-level `env`.
+     *   2. global top-level `env`          — ~/.code-shell/settings.json; the
+     *      canonical home for API keys (OPENAI_API_KEY) a skill script reads —
+     *      configure once, every project's skills get it.
+     *   3. project top-level `env`         — .code-shell/settings.json; a project
+     *      that wants to override a global key wins.
+     *
+     * Each scope is read UNMERGED so the layering here is the single source of
+     * precedence (getForScope merges nothing). Returns undefined when no layer
+     * contributes a key, so the caller passes it through unchanged for projects
+     * that configure none.
+     *
+     * Sub-agents: a sub-agent is the user's OWN agent doing the user's work
+     * (mirrors Claude Code, where sub-agents inherit the parent environment), so
+     * it now reads the SAME env as the parent. The sub-agent branch is kept as an
+     * explicit seam (`filterSubagentEnv`) rather than removed — a future policy
+     * could narrow what a sub-agent sees (e.g. drop credential secrets) by
+     * changing that one hook; today it passes everything through unchanged.
+     * A no-cwd context still gets nothing (there is genuinely no project to read).
+     *
+     * None of these is filtered through the deny regex (mergeShellEnv): the user
+     * put them there deliberately. The allowlist/deny machinery only guards the
+     * host's process.env from a tainted model exfiltrating it via `env | curl`.
+     */
+    readShellEnv(cwd) {
+        if (!cwd)
+            return undefined;
+        const merged = {};
+        const layer = (env) => {
+            if (!env)
+                return;
+            for (const [k, v] of Object.entries(env)) {
+                if (typeof v === "string")
+                    merged[k] = v;
+            }
+        };
+        try {
+            // The fully-merged settings already apply the scope guard (a 'project'
+            // scope never reads the host ~/.code-shell) and the user < project <
+            // local precedence — so the top-level `env` map read from here is global
+            // values overridden by project values, exactly as specified. We layer
+            // localEnvironment.env *under* it as the floor.
+            const settings = this.getSettingsManager().get();
+            layer(settings.localEnvironment?.env); // floor
+            // Credentials flagged "expose as env var" (Credential.exposeAsEnv). This
+            // is the wiring that was missing — the UI/store recorded the flag but no
+            // code ever injected the secret, so `$FIGMA_TOKEN` was always empty.
+            // Scope mirrors settingsScope so a project-scoped engine never surfaces
+            // 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(settings.env); // top-level env (global ⊕ project) wins
+        }
+        catch {
+            return undefined;
+        }
+        const result = this.config.isSubAgent === true ? this.filterSubagentEnv(merged) : merged;
+        return Object.keys(result).length > 0 ? result : undefined;
+    }
+    /**
+     * Policy seam for what a sub-agent's shell sees. A sub-agent inherits the
+     * parent environment by default (mirrors Claude Code), so this is the
+     * identity function today. It exists so a future policy can narrow the set
+     * (e.g. strip credential `exposeAsEnv` secrets, or allowlist by name) in ONE
+     * place instead of scattering `isSubAgent` checks through readShellEnv.
+     */
+    filterSubagentEnv(env) {
+        return env;
+    }
+    /**
+     * Read the project's `localEnvironment.setupScripts` for this cwd (the raw
+     * per-platform map). Used by EnterWorktree to run setup once in a freshly
+     * created worktree. Returns undefined for sub-agents / no cwd (same minimal
+     * surface as readShellEnv). The platform selection + run live in
+     * git/worktree.ts; this only fetches the configured scripts.
+     */
+    readWorktreeSetupScripts(cwd) {
+        if (this.config.isSubAgent === true || !cwd)
+            return undefined;
+        try {
+            const scoped = this.getSettingsManager().getForScope("project", cwd);
+            return scoped.localEnvironment?.setupScripts;
+        }
+        catch {
+            return undefined;
+        }
+    }
     buildToolContext() {
         const { disabledSkills, disabledPlugins } = this.readDisabledLists();
         return {
+            shellEnv: this.readShellEnv(this.config.cwd),
             cwd: this.config.cwd ?? process.cwd(),
             llmConfig: this.config.llm,
             modelPool: this.modelPool,
             toolRegistry: this.toolRegistry,
             askUser: this.config.askUser,
+            browser: this.config.browserBridge,
+            injectCredentialToBrowser: this.config.injectCredentialToBrowser,
             isSubAgent: this.config.isSubAgent === true,
+            // Credential tools narrow their disk reads to this scope: a project/
+            // isolated engine (SDK-embedded) must not surface the host user's
+            // ~/.code-shell credentials or credentialUse.autoApprove. "full" (the
+            // host-application default) merges user + project as before.
+            settingsScope: this.config.settingsScope ?? "project",
             hooks: this.hooks,
             planMode: this.planMode,
+            permissionMode: this.permissionMode,
             engine: this,
             disabledSkills,
             disabledPlugins,
+            skillAllowlist: this.config.skillAllowlist,
+            backgroundShells: backgroundShellManager,
+            // Sub-agents never start background shells (they're short-lived and
+            // their lifecycle ends with the parent turn); unattended automation
+            // opts out via config. Otherwise allowed.
+            allowBackgroundShells: this.config.isSubAgent === true ? false : this.config.allowBackgroundShells !== false,
         };
     }
     /**
@@ -1522,17 +2793,97 @@ export class Engine {
      */
     readDisabledLists() {
         if (this.config.isSubAgent === true) {
-            return { disabledSkills: [], disabledPlugins: [] };
+            return { disabledSkills: [], disabledPlugins: [], disabledPluginHooks: [] };
         }
+        // Shared folding (capability-control/disabled-lists.ts): project
+        // capabilityOverrides over the global baseline + the no-repo whitelist
+        // inversion. Extracted so the MCP merge consumers (engineFactory /
+        // diskDefaultsFrom) fold identically — see that module's doc.
+        return computeEffectiveDisabledLists(this.getSettingsManager(), this.config.cwd);
+    }
+    /**
+     * Public view of the folded disabled lists, for hosts that need the
+     * EFFECTIVE state (e.g. the protocol server's settings hot-reload rebuilds
+     * the plugin-MCP merge per session — a project-level "on" must override the
+     * global disabledPlugins there too).
+     */
+    getEffectiveDisabledLists() {
+        return this.readDisabledLists();
+    }
+    /**
+     * Public: resolve every known feature flag to its effective boolean (the
+     * settings overlay merged over the compiled-in defaults). Used by the
+     * `config` protocol query so the `/features` command can list flag state.
+     */
+    getFeatureFlags() {
+        return resolveFeatureFlags(this.readFeatureFlags());
+    }
+    /**
+     * Read the merged `settings.featureFlags` overlay for this cwd. Project
+     * settings override user settings via the normal SettingsManager merge.
+     * Returns undefined (→ all defaults) on any read error or for sub-agents,
+     * so a flag check never throws and a child runs with default behavior.
+     */
+    readFeatureFlags() {
+        if (this.config.isSubAgent === true)
+            return undefined;
         try {
             const settings = this.getSettingsManager().get();
-            return {
-                disabledSkills: settings.disabledSkills ?? [],
-                disabledPlugins: settings.disabledPlugins ?? [],
-            };
+            return settings.featureFlags;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Read settings.memories ({ maxCount, maxAge, extractionModel, autoExtract }).
+     * Returns undefined on any error or when absent, so the memory pipeline
+     * falls back to its built-in defaults.
+     */
+    readMemoriesConfig() {
+        try {
+            const settings = this.getSettingsManager().get();
+            return settings.memories;
         }
         catch {
-            return { disabledSkills: [], disabledPlugins: [] };
+            return undefined;
+        }
+    }
+    /**
+     * LLM client for memory extraction (TODO 8.1). Prefers
+     * settings.memories.extractionModel when it names a valid pool model;
+     * otherwise falls back to the aux client (which itself falls back to the
+     * passed primary). Build failures fall back too — extraction is best-effort.
+     */
+    async resolveExtractionClient(primaryClient) {
+        const key = this.readMemoriesConfig()?.extractionModel;
+        if (key) {
+            const entry = this.modelPool.get(key);
+            if (entry) {
+                try {
+                    return await createLLMClient(this.modelPool.toLLMConfig(entry), this.config.clientDefaults);
+                }
+                catch (err) {
+                    logger.warn("engine.extraction_model_build_failed", {
+                        extractionModel: key,
+                        error: err.message,
+                    });
+                }
+            }
+            else {
+                logger.warn("engine.extraction_model_missing", { extractionModel: key });
+            }
         }
+        return this.resolveAuxClient(primaryClient);
     }
 }
+/**
+ * Builtin tool name → the feature flag that gates its visibility. A tool here
+ * is hidden from the LLM when its flag resolves to false. Tools not listed are
+ * unaffected. Kept beside the engine (not in builtin/index) because the flag
+ * read needs the engine's scoped SettingsManager.
+ */
+const TOOL_FEATURE_FLAGS = new Map([
+    ["WebSearch", "web_search"],
+    ["Bash", "shell_tool"],
+]);