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

package/dist/engine/engine.js

@@ -7,21 +7,29 @@ import { ToolExecutor } from "../tool-system/executor.js";
 import { InvestigationGuard } from "../tool-system/investigation-guard.js";
 import { TaskGuard } from "../tool-system/task-guard.js";
 import { readLastTodoSnapshot } from "../tool-system/builtin/task.js";
-import { agentToolDefWithTypes } from "../tool-system/builtin/agent.js";
+import { 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 { addCumulativeUsage, cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "./session-usage.js";
+import { enqueueSteerItem, consumeSteerItems, removeSteerItem, } from "./steer-queue.js";
+import { resolveSandboxConfig } from "./sandbox-config.js";
+import { sandboxCacheKey } from "./sandbox-cache-key.js";
 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 } from "./goal.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 } from "../context/compaction.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";
@@ -32,26 +40,28 @@ import { sanitizeContent, sanitizeTaskString } from "../logging/sanitize-message
 import { TurnLoop } from "./turn-loop.js";
 import { MCPManager } from "../tool-system/mcp-manager.js";
 import { SettingsManager, userHome } from "../settings/manager.js";
-import { effectiveDisabledList, effectiveBuiltinLists } from "../capability-control/overlay.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 { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
-import { parseTaskWithImages, } from "./parse-task.js";
-import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, } from "./image-policy.js";
+import { parseTaskWithImages } from "./parse-task.js";
+import { enforceImagePolicy, byteLengthFromBase64, dropOversizedImages, collectAttachedImagePaths, } from "./image-policy.js";
 import { tryCompressImages } from "./image-compression.js";
 import { buildSessionTitle } from "./session-title.js";
 import { capabilitiesFor } from "../llm/capabilities/index.js";
 import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
 import { runDreamConsolidation } from "../services/dream-consolidation.js";
-import { join } from "node:path";
-import { homedir } from "node:os";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync, } from "node:fs";
+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
@@ -118,8 +128,25 @@ export function resolveChildLlm(modelKey, pool, parentLlm) {
  *   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 = []) {
-    const home = homedir();
+    // 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
@@ -135,7 +162,7 @@ export function loadAgentDefinitionsForCwd(cwd, disabledAgents = [], disabledPlu
         ...(cwd ? [{ dir: `${cwd}/.code-shell/agents`, source: "project" }] : []),
     ], disabledAgents);
 }
-const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel"];
+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
@@ -238,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();
@@ -247,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
@@ -278,6 +358,10 @@ export class Engine {
         }
         const entries = settings.hooks ?? [];
         for (const entry of entries) {
+            // 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))
@@ -310,6 +394,19 @@ export class Engine {
             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 {
@@ -343,13 +440,15 @@ export class Engine {
         // per-turn path can only hide, not add, so a freshly-`on`'d builtin not in
         // the set needs a session restart to appear.
         const builtinLists = effectiveBuiltinLists(config.enabledBuiltinTools ?? [], config.disabledBuiltinTools ?? [], this.readBuiltinOverride(config.cwd));
-        this.toolRegistry = config.runtime?.toolRegistry ?? new ToolRegistry({
-            builtinTools: resolveBuiltinToolNames({
-                preset: this.preset.name,
-                enabledBuiltinTools: builtinLists.enabledBuiltinTools,
-                disabledBuiltinTools: builtinLists.disabledBuiltinTools,
-            }),
-        });
+        this.toolRegistry =
+            config.runtime?.toolRegistry ??
+                new ToolRegistry({
+                    builtinTools: resolveBuiltinToolNames({
+                        preset: this.preset.name,
+                        enabledBuiltinTools: builtinLists.enabledBuiltinTools,
+                        disabledBuiltinTools: builtinLists.disabledBuiltinTools,
+                    }),
+                });
         this.hooks = new HookRegistry();
         // Installed-plugin hooks — declared in each plugin's hooks/hooks.json.
         // Registered first (priority 80) so user-authored hooks at lower
@@ -362,7 +461,12 @@ export class Engine {
             // disabledPlugins suppresses a plugin's hooks too (not just its
             // Skill-tool entries) — see loadPluginHooks. readDisabledLists reads
             // the same settings the prompt composer / tool context use.
-            loadPluginHooks(this.hooks, this.readDisabledLists().disabledPlugins);
+            // 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).
@@ -378,7 +482,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).
      */
@@ -387,54 +491,45 @@ 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),
@@ -443,9 +538,10 @@ export class Engine {
                 }
             }
             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
@@ -457,8 +553,10 @@ export class Engine {
             const modelBlock = settings.model;
             const nextDefaults = { ...(this.config.clientDefaults ?? {}) };
             let defaultsChanged = false;
-            if (imageSettings?.detail && nextDefaults.imageDetail !== imageSettings.detail) {
-                nextDefaults.imageDetail = imageSettings.detail;
+            // 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" &&
@@ -476,7 +574,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.
      */
@@ -490,7 +588,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.
      */
@@ -528,6 +626,94 @@ 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 this session, reject
+     * without queueing so the host can downgrade to a normal run immediately.
+     * No-op on blank text.
+     *
+     * `id` is the host's stable queue-entry id. It rides through to the
+     * `steer_injected` event (so the host can match the injected bubble back to
+     * the queued draft) and is the handle `unsteer` uses to revoke a still-pending
+     * entry. A blank id is tolerated but means the entry can't be revoked.
+     */
+    enqueueSteer(sessionId, text, id = "", clientMessageId) {
+        const q = this.steerQueueBySid.get(sessionId) ?? [];
+        const entryId = id || `steer-${q.length}`;
+        if (!sessionId)
+            return { accepted: false, id: entryId };
+        const activeRunSessionId = this.activeRunSession?.state.sessionId;
+        const active = this.activeTurnLoop !== null && activeRunSessionId === sessionId;
+        if (!active) {
+            logger.info("steer.enqueue.idle_rejected", {
+                sessionId,
+                id: entryId,
+                clientMessageId,
+                activeRunSessionId: activeRunSessionId ?? null,
+                queueLength: q.length,
+            });
+            return { accepted: false, id: entryId };
+        }
+        const next = enqueueSteerItem(q, entryId, text, clientMessageId);
+        if (next === q)
+            return { accepted: false, id: entryId }; // blank text dropped
+        this.steerQueueBySid.set(sessionId, next);
+        logger.info("steer.enqueue.accepted", {
+            sessionId,
+            id: entryId,
+            clientMessageId,
+            activeRunSessionId,
+            queueLength: next.length,
+        });
+        return { accepted: true, id: entryId };
+    }
+    /**
+     * Revoke a still-pending steer entry (the 撤回 path). Returns true if it was
+     * 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, source = "normal_step") {
+        const q = this.steerQueueBySid.get(sessionId);
+        if (!q || q.length === 0)
+            return [];
+        const { drained, rest } = consumeSteerItems(q);
+        this.steerQueueBySid.set(sessionId, rest);
+        logger.info("steer.consume.drained", {
+            sessionId,
+            source,
+            count: drained.length,
+            ids: drained.map((item) => item.id),
+            clientMessageIds: drained.flatMap((item) => item.clientMessageId ? [item.clientMessageId] : []),
+            queueLength: rest.length,
+        });
+        return drained;
+    }
+    /** Wire the cookie→browser injection callback (InjectCredential tool). Same
+     *  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.
@@ -535,11 +721,34 @@ export class Engine {
     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
@@ -701,6 +910,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
@@ -722,9 +947,8 @@ export class Engine {
                     enabledBuiltinTools: childEnabled,
                     disabledBuiltinTools: childDisabled,
                     customSystemPrompt: this.config.customSystemPrompt,
-                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt]
-                        .filter(Boolean)
-                        .join("\n\n") || undefined,
+                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt].filter(Boolean).join("\n\n") ||
+                        undefined,
                     responseLanguage: this.config.responseLanguage,
                     userProfile: this.config.userProfile,
                     instructions: this.config.instructions,
@@ -733,6 +957,7 @@ export class Engine {
                     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.
@@ -770,12 +995,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
@@ -789,6 +1043,17 @@ export class Engine {
         const sandboxBackend = this.runtime
             ? await this.runtime.resolveSandbox(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
@@ -797,7 +1062,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
@@ -818,10 +1089,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",
@@ -848,6 +1133,23 @@ export class Engine {
         // call) instead of a try/catch on resume.
         let session;
         let messages;
+        let freshImageMessage;
+        const claimedClientMessageIds = new Set();
+        const claimClientMessageId = (bundle, clientMessageId, source) => {
+            if (!clientMessageId)
+                return true;
+            if (claimedClientMessageIds.has(clientMessageId) ||
+                bundle.transcript.hasClientMessageId(clientMessageId)) {
+                logger.info("engine.client_message.duplicate_ignored", {
+                    sessionId: bundle.state.sessionId,
+                    clientMessageId,
+                    source,
+                });
+                return false;
+            }
+            claimedClientMessageIds.add(clientMessageId);
+            return true;
+        };
         if (options?.sessionId && this.sessionManager.exists(options.sessionId)) {
             session = this.sessionManager.resume(options.sessionId);
             const cachedCompacted = this.compactedMessagesBySession.get(options.sessionId);
@@ -871,8 +1173,31 @@ export class Engine {
             }
             // Append new user message
             const userMsg = { role: "user", content: userMessageContent };
+            if (!claimClientMessageId(session, options?.clientMessageId, "submit")) {
+                const usage = session.state.tokenUsage ?? {
+                    promptTokens: 0,
+                    completionTokens: 0,
+                    totalTokens: 0,
+                };
+                return {
+                    text: "",
+                    reason: "completed",
+                    sessionId: session.state.sessionId,
+                    turnCount: session.state.turnCount ?? 0,
+                    usage: {
+                        promptTokens: usage.promptTokens ?? 0,
+                        completionTokens: usage.completionTokens ?? 0,
+                        totalTokens: usage.totalTokens ?? 0,
+                    },
+                };
+            }
+            if (parsedTask.hasImages)
+                freshImageMessage = userMsg;
             messages.push(userMsg);
-            session.transcript.appendMessage("user", userMessageContent);
+            session.transcript.appendMessage("user", userMessageContent, {
+                injected: options?.injected === true,
+                clientMessageId: options?.clientMessageId,
+            });
             // Flush "active" status to disk immediately. resume() set it in memory
             // (session-manager.ts), but without this write the on-disk state.json
             // still shows the previous run's terminal reason — so any external
@@ -884,17 +1209,30 @@ export class Engine {
             // Cold start: shape (2) reuses the host-supplied sid; shape (3)
             // lets sessionManager generate one with nanoid.
             session = this.sessionManager.create(cwd, this.config.llm.model, this.config.llm.provider, options?.sessionId, this.config.isSubAgent === true ? getCurrentSid() : undefined, this.config.isSubAgent === true ? "subagent" : this.config.origin);
-            messages = [{ role: "user", content: userMessageContent }];
-            session.transcript.appendMessage("user", userMessageContent);
+            const userMsg = { role: "user", content: userMessageContent };
+            claimClientMessageId(session, options?.clientMessageId, "submit");
+            if (parsedTask.hasImages)
+                freshImageMessage = userMsg;
+            messages = [userMsg];
+            session.transcript.appendMessage("user", userMessageContent, {
+                clientMessageId: options?.clientMessageId,
+            });
             // Save first user message as session summary — text only. The summary
             // shows up in the session list; "[image]" is more informative than a
             // truncated `[object Object]` when the prompt was purely visual.
             const summarySrc = parsedTask.hasImages
-                ? parsedTask.text || `[image${parsedTask.images.length > 1 ? `s × ${parsedTask.images.length}` : ""}]`
+                ? parsedTask.text ||
+                    `[image${parsedTask.images.length > 1 ? `s × ${parsedTask.images.length}` : ""}]`
                 : taskText;
             session.state.summary = summarySrc.slice(0, 80).replace(/\n/g, " ");
             this.sessionManager.saveState(session.state);
         }
+        // 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
@@ -1043,6 +1381,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();
@@ -1057,6 +1398,14 @@ export class Engine {
                 instructionOptions: { compatFileNames: compatFileNamesFrom(this.config.instructions) },
                 disabledSkills,
                 disabledPlugins,
+                skillAllowlist: this.config.skillAllowlist,
+                memoriesMaxAgeDays: this.readMemoriesConfig()?.maxAge,
+                goalToolState: {
+                    hasGoal: this.config.isSubAgent !== true &&
+                        (normalizeGoal(options?.goal) !== undefined ||
+                            session.state.activeGoal !== undefined ||
+                            normalizeGoal(this.config.goal) !== undefined),
+                },
             });
             // Connect MCP servers (if configured and not already connected).
             // B1: prefer the Runtime-owned MCPManager so all sessions in a
@@ -1071,7 +1420,7 @@ 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)
@@ -1092,6 +1441,14 @@ export class Engine {
             // 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;
+            const toolVisibility = {
+                cwd: guardCwd,
+                hasGoal: this.config.isSubAgent !== true &&
+                    (normalizeGoal(options?.goal) !== undefined ||
+                        session.state.activeGoal !== undefined ||
+                        normalizeGoal(this.config.goal) !== undefined),
+            };
+            toolCtx.toolVisibility = toolVisibility;
             // #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
@@ -1114,14 +1471,45 @@ export class Engine {
                 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;
+                return guard ? guard(toolVisibility) : true;
+            })
+                .filter((t) => {
+                const flag = TOOL_FEATURE_FLAGS.get(t.name);
+                return flag ? isFeatureEnabled(featureFlags, flag) : true;
             })
-                .map((t) => t.name === "Agent"
-                ? { ...t, description: agentToolDefWithTypes(toolCtx.agentDefinitions).description }
-                : t);
+                // 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
@@ -1130,12 +1518,13 @@ export class Engine {
             const toolDefs = this.planMode
                 ? 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) {
@@ -1154,6 +1543,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
@@ -1165,28 +1560,34 @@ export class Engine {
             // run would be evaluated fresh and might get a different replacement
             // string than the one already in the message, breaking idempotency.
             contextManager.initReplacementStateFromMessages(messages);
-            // Summarization (context-compaction + tool-result summaries) are auxiliary
-            // calls — route them to the configured aux model so they don't burn the
-            // expensive primary model every turn (same rationale as runMemoryPipeline).
-            // Resolved once here (not per-call) so the magnetic-disk settings re-read
-            // in resolveAuxClient stays off the compaction hot path. Falls back to the
-            // primary client when no aux model is configured.
+            // Two summarizers with DIFFERENT quality needs:
+            //
+            // 1. Context-compaction summary (setSummarizeFn) → PRIMARY model. This
+            //    condenses many rounds into the running summary that REPLACES the real
+            //    history; a dropped decision makes the conversation "forget" and poisons
+            //    every subsequent turn. It fires only near the compact ratio (~0.85), so
+            //    it's infrequent — quality far outweighs the occasional extra cost of a
+            //    primary-model call. (Manual /compact uses the primary for the same
+            //    reason; see forceCompact.)
+            //
+            // 2. Tool-use one-liner summaries (modelFacade.summarize below) → AUX model.
+            //    These are tiny throwaway outputs ("Wrote design doc") fired every turn;
+            //    that high-frequency, low-stakes chore is exactly what aux is for.
             const auxSummaryClient = await this.resolveAuxClient(llmClient);
-            contextManager.setSummarizeFn(async (prompt) => {
-                const summaryResponse = await auxSummaryClient.createMessage({
-                    systemPrompt: "You are a conversation summarizer. Be concise and factual.",
-                    messages: [{ role: "user", content: prompt }],
-                    tools: [],
-                    maxTokens: 1024,
-                    // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
-                    // this flips thinking off (~3x faster, fewer tokens); on every other
-                    // OpenAI-compatible provider the field is ignored.
-                    reasoning: { mode: "off" },
-                });
-                return summaryResponse.text;
-            });
-            // Create components (requires resolved llmClient)
+            Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
+            const recordCumulativeUsage = (usage) => {
+                const next = addCumulativeUsage(session.state, usage);
+                Object.assign(session.state, next);
+                return next;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordCumulativeUsage));
+            // Create components (requires resolved llmClient).
             const modelFacade = new ModelFacade(llmClient, session.transcript);
+            // Session-cumulative usage baseline: the LLM client is recreated per run
+            // (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();
@@ -1221,14 +1622,39 @@ export class Engine {
             // File history: auto-backup before Write/Edit
             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,
@@ -1238,20 +1664,70 @@ export class Engine {
             // Goal mode: register a GoalStopHook for the lifetime of THIS run so the
             // turn loop keeps going until the session model judges the goal met.
             // Registered per-run (and cleared in `finally`) so a later goal-less
-            // send doesn't inherit a stale goal. The judge reuses `llmClient` — the
-            // same model this session is talking to (per design).
+            // 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).
-            const normalizedGoal = normalizeGoal(options?.goal ?? this.config.goal);
+            //
+            // 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: llmClient,
+                    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
@@ -1278,6 +1754,24 @@ export class Engine {
                     pendingCompactInfo = null;
                     return info;
                 },
+                consumeSteer: (source) => this.consumeSteer(sid, source),
+                claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
+                recordCumulativeUsage,
+                // 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) => {
@@ -1285,10 +1779,23 @@ 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,
+                freshImageMessages: freshImageMessage ? [freshImageMessage] : undefined,
                 // Goal mode: the active goal is surfaced to the on_stop handler via
                 // ctx.data.goal; the GoalStopHook (registered above) judges it.
                 goal: normalizedGoal,
@@ -1298,62 +1805,106 @@ export class Engine {
                 // 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 whole-session monotonic cache counts to the UI.
+                    // Separate from turn-loop's authoritative per-response emit (which
+                    // drives the live context reading and single-turn metric).
+                    const cumulative = normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage);
+                    const cumulativeHitRate = cumulativeCacheHitRate(cumulative);
+                    options?.onStream?.({
+                        type: "usage_update",
+                        promptTokens: cumulative.cumulativePromptTokens,
+                        cumulativePromptTokens: cumulative.cumulativePromptTokens,
+                        cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                        cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                        ...(cumulativeHitRate !== undefined
+                            ? { cumulativeCacheHitRate: cumulativeHitRate }
+                            : {}),
+                        sessionPromptTokens: cumulative.cumulativePromptTokens,
+                        sessionCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                        sessionCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                    });
                     if (this.config.costStore) {
                         session.state.costState = this.config.costStore.serialize();
                     }
                     this.sessionManager.saveState(session.state);
                 },
             });
+            // 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);
-                // ── Wait for background sub-agents, then summarize ───────────────
-                // run_in_background sub-agents outlive the turn that spawned them. The
-                // main agent must not resolve while ITS OWN background agents are still
-                // working — otherwise their results land in the notification queue with
-                // nobody to drain them and the run looks "done" while work is in flight
-                // (the s-mpvf4rsj-bb6e4639 bug). We block here until none of this
-                // session's background agents are running, then drain ALL their results
-                // and feed them back as one more turn so the agent summarizes.
+                // ── 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.
                 //
-                // Top-level only: a sub-agent must never wait on grandchildren (and
-                // nested agents are disabled anyway). `signal` aborts the wait.
+                // 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) {
+                if (isTopLevel && this.isHeadless()) {
                     let aborted = options?.signal?.aborted === true;
-                    while (!aborted && asyncAgentRegistry.hasRunningForSession(sid)) {
-                        aborted = await this.waitForBackgroundAgentChange(sid, options?.signal);
-                    }
-                    // Drain everything that came back — including partial results when the
-                    // user aborted with one agent still stuck. Nothing already returned is
-                    // lost: it's injected into the transcript either way.
-                    const pending = notificationQueue.drainAll(sid);
-                    if (pending.length > 0) {
+                    // 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) {
-                            // Aborted: preserve the results in context (transcript + messages)
-                            // but do NOT spin up another LLM turn — the user cancelled, and a
-                            // fresh turn would just be killed by the same signal. The next
-                            // user message in this session will see these results in history.
-                            session.transcript.appendMessage(injected.role, injected.content);
+                            // 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;
                         }
-                        else {
-                            // All background agents finished: one more turn so the agent reads
-                            // every result and summarizes. turnCount keeps accumulating, so
-                            // maxTurns still bounds runaway re-summarization.
-                            result = await turnLoop.run([...result.messages, injected]);
-                        }
+                        result = await turnLoop.run([...result.messages, injected]);
                     }
                 }
             }
@@ -1362,6 +1913,15 @@ export class Engine {
                 // 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));
@@ -1404,6 +1964,12 @@ export class Engine {
                     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,
@@ -1421,12 +1987,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();
             }
@@ -1459,12 +2022,34 @@ export class Engine {
      */
     /**
      * Resolve the LLM client for background/auxiliary work (memory extraction,
-     * auto-dream). When settings.auxModelKey names a valid pool model, build (and
-     * cache) a dedicated client for it so per-turn book-keeping runs on a cheap
+     * 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.
      */
+    /**
+     * Build the SummarizeFn used for context compaction. Extracted so both the
+     * run path and forceCompact share one definition of the summarization call.
+     */
+    buildSummarizeFn(auxSummaryClient, recordCumulativeUsage) {
+        return async (prompt) => {
+            const summaryResponse = await auxSummaryClient.createMessage({
+                systemPrompt: "You are a conversation summarizer. Be concise and factual.",
+                messages: [{ role: "user", content: prompt }],
+                tools: [],
+                maxTokens: 1024,
+                // Auxiliary call — no need to burn reasoning tokens. On DeepSeek V4
+                // this flips thinking off (~3x faster, fewer tokens); on every other
+                // OpenAI-compatible provider the field is ignored.
+                reasoning: { mode: "off" },
+            });
+            if (summaryResponse.usage) {
+                recordCumulativeUsage?.(summaryResponse.usage);
+            }
+            return summaryResponse.text;
+        };
+    }
     async resolveAuxClient(fallback) {
         let auxKey;
         try {
@@ -1473,7 +2058,9 @@ export class Engine {
             // once per run on the post-run background path, so the cost is fine.
             const sm = this.getSettingsManager();
             sm.invalidate();
-            auxKey = sm.get().auxModelKey;
+            // 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;
@@ -1519,14 +2106,18 @@ export class Engine {
         try {
             // Background calls run on the auxiliary model when configured, so memory
             // book-keeping doesn't burn the expensive primary model every turn.
-            const llmClient = await this.resolveAuxClient(primaryClient);
+            // 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
             // extraction, which then padded the memory store with low-signal
             // entries. 8 messages is roughly "more than a single back-and-forth"
             // — substantive enough to be worth a durable note.
-            const messages = transcript.toMessages().filter((m) => m.role === "user" || m.role === "assistant");
+            const messages = transcript
+                .toMessages()
+                .filter((m) => m.role === "user" || m.role === "assistant");
             if (messages.length < 8)
                 return;
             // Memory orchestrator + dream-loop calls are auxiliary LLM calls
@@ -1558,6 +2149,10 @@ export class Engine {
                 },
                 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);
         }
@@ -1608,10 +2203,10 @@ 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);
@@ -1620,19 +2215,42 @@ export class Engine {
         // 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 the legacy/model-scoped token/cache usage window on disk. The
+     * whole-session cumulative counters are intentionally left alone.
+     */
+    resetSessionUsage(sessionId) {
+        const zero = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        // 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 {
             // userHome() (not raw homedir()) so a test that sets process.env.HOME to
             // a tmpdir gets its writes isolated too — the SettingsManager reader
@@ -1651,28 +2269,31 @@ 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) {
@@ -1708,12 +2329,10 @@ export class Engine {
      * payloads are dropped so out-of-order reload deliveries can't let an older
      * config clobber a newer one (Q5).
      *
-     * MCP: only connects (idempotent — already-connected servers are skipped);
-     * never disconnects, so an in-flight tool call on an existing server is
-     * never severed (Q3). Removed servers are deferred to the next session
-     * rebuild. If mcpManager isn't built yet (no MCP run has happened), the
-     * new servers will be connected on the next run via the existing per-run
-     * connectAll path — so we skip the connect here.
+     * 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
@@ -1747,8 +2366,14 @@ export class Engine {
             // The builtin tool SET is ctor-frozen and may be shared via runtime — we
             // do NOT rebuild it here. If the new preset implies a different builtin
             // tool set, that part of the change only lands on session restart.
-            const prevTools = resolveBuiltinToolNames({ preset: prevPresetName }).slice().sort().join(",");
-            const nextTools = resolveBuiltinToolNames({ preset: nextPreset.name }).slice().sort().join(",");
+            const prevTools = resolveBuiltinToolNames({ preset: prevPresetName })
+                .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,
@@ -1760,16 +2385,17 @@ export class Engine {
         }
         this.reloadHooks();
         if (patch.mcpServers && this.mcpManager) {
-            const added = {};
-            for (const [name, cfg] of Object.entries(patch.mcpServers)) {
-                if (!(name in prevServers))
-                    added[name] = cfg;
-            }
-            if (Object.keys(added).length > 0) {
-                // connectAll is idempotent (skips already-connected); fire-and-forget
-                // so a slow server handshake never blocks the reload call.
-                void this.mcpManager.connectAll(added);
-            }
+            // 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;
     }
@@ -1782,6 +2408,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);
@@ -1794,25 +2469,74 @@ export class Engine {
         }
     }
     /**
-     * Force context compaction on the current session.
+     * Force context compaction on a session.
      * Returns token stats before/after.
      */
-    forceCompact() {
-        const sessionId = this.lastSessionId;
-        if (!this.lastContextManager || !sessionId) {
+    async forceCompact(sessionId) {
+        const effectiveSessionId = sessionId ?? this.lastSessionId;
+        if (!effectiveSessionId) {
             return { before: 0, after: 0, strategy: "none (no active session)" };
         }
-        const sourceMessages = this.compactedMessagesBySession.get(sessionId) ??
-            this.sessionManager.resume(sessionId).transcript.toMessages();
+        const session = this.sessionManager.resume(effectiveSessionId);
+        const sourceMessages = this.compactedMessagesBySession.get(effectiveSessionId) ?? session.transcript.toMessages();
         const before = estimateTokens(sourceMessages);
-        const compacted = this.lastContextManager.manage(sourceMessages);
+        let contextManager = this.lastContextManager;
+        if (!contextManager || this.lastSessionId !== effectiveSessionId) {
+            contextManager = new ContextManager({
+                maxTokens: this.resolveMaxContextTokens(),
+                ...Object.fromEntries(Object.entries(this.resolveContextRatios()).filter(([, v]) => v !== undefined)),
+            });
+            contextManager.setTranscriptPath(session.transcript.getFilePath());
+            contextManager.initReplacementStateFromMessages(sourceMessages);
+            this.lastContextManager = contextManager;
+        }
+        // Manual /compact emits its UI boundary at the protocol layer from the
+        // final before/after result. Capture the tier here, but avoid reusing a
+        // stale run callback retained on lastContextManager, which could otherwise
+        // double-emit.
+        let compactStrategy;
+        contextManager.setOnCompact((info) => {
+            if (info.after < info.before)
+                compactStrategy = info.strategy;
+        });
+        // Manual /compact = maximum compaction NOW. The automatic ladder waits for
+        // compactAtRatio (0.85 * window), so on a 1M-window model an 800k text-only
+        // conversation sits under the gate and manage() only runs a no-op micro.
+        // Wire a summarizeFn (the run path does this per-run; a cold forceCompact on
+        // a resumed-but-never-run session has none) and call forceSummarize, which
+        // ignores the ratio gate and always summarizes (falling back to snip/window).
+        //
+        // Use the PRIMARY model, not the aux model. Automatic background compaction
+        // routes to aux to keep the high-frequency path cheap, but summarization is
+        // a high-fidelity task (drop a decision and the conversation "forgets"), and
+        // a manual /compact is a low-frequency, user-initiated request for quality.
+        // The aux model is sized for tiny outputs (titles, memory extraction), so
+        // downgrading the one compaction the user explicitly asked for is backwards.
+        try {
+            const primaryClient = await createLLMClient(this.config.llm, this.config.clientDefaults);
+            Object.assign(session.state, normalizeCumulativeUsageCounters(session.state, session.state.tokenUsage));
+            const recordCompactUsage = (usage) => {
+                const next = addCumulativeUsage(session.state, usage);
+                Object.assign(session.state, next);
+                this.sessionManager.saveState(session.state);
+                return next;
+            };
+            contextManager.setSummarizeFn(this.buildSummarizeFn(primaryClient, recordCompactUsage));
+        }
+        catch (err) {
+            logger.warn("engine.force_compact_client_failed", {
+                error: err.message,
+            });
+        }
+        const compacted = await contextManager.forceSummarize(sourceMessages);
         const after = estimateTokens(compacted);
-        this.compactedMessagesBySession.set(sessionId, compacted);
+        this.compactedMessagesBySession.set(effectiveSessionId, compacted);
+        this.lastSessionId = effectiveSessionId;
         this.lastMessages = compacted;
         return {
             before,
             after,
-            strategy: before === after ? "no compaction needed" : "compacted",
+            strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
         };
     }
     stripUserContextMessage(messages, userContextMsg) {
@@ -1823,7 +2547,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;
     }
@@ -1875,7 +2599,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);
@@ -1906,7 +2630,11 @@ export class Engine {
                 backend = interactive;
             }
             else {
-                backend = new HeadlessApprovalBackend(mode === "bypassPermissions" ? "approve-all" : mode === "dontAsk" ? "deny-all" : "deny-all");
+                backend = new HeadlessApprovalBackend(mode === "bypassPermissions"
+                    ? "approve-all"
+                    : mode === "dontAsk"
+                        ? "deny-all"
+                        : "deny-all");
             }
         }
         return { rules, backend };
@@ -1930,6 +2658,27 @@ 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.
@@ -1983,6 +2732,30 @@ export class Engine {
             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
@@ -1991,12 +2764,8 @@ export class Engine {
     getAgentDefinitions(cwd) {
         const disabledAgents = this.readDisabledAgents(cwd);
         const disabledPlugins = this.readDisabledLists().disabledPlugins;
-        const disabledKey = [...disabledAgents, "::", ...disabledPlugins]
-            .slice()
-            .sort()
-            .join(" ");
-        if (this.agentDefsCache?.cwd !== cwd ||
-            this.agentDefsCache.disabledKey !== disabledKey) {
+        const disabledKey = [...disabledAgents, "::", ...disabledPlugins].slice().sort().join(" ");
+        if (this.agentDefsCache?.cwd !== cwd || this.agentDefsCache.disabledKey !== disabledKey) {
             this.agentDefsCache = {
                 cwd,
                 disabledKey,
@@ -2053,7 +2822,7 @@ export class Engine {
      * by tests that want a ToolContext without a full run() cycle.
      */
     resolveSandboxWithoutRuntime(config, cwd) {
-        const key = `${config.mode}:${cwd}`;
+        const key = sandboxCacheKey(config, cwd);
         let cached = this.sandboxCache.get(key);
         if (!cached) {
             cached = resolveSandboxBackend(config, cwd);
@@ -2068,20 +2837,129 @@ export class Engine {
         }
         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,
         };
     }
     /**
@@ -2097,27 +2975,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 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 sm = this.getSettingsManager();
-            const settings = sm.get();
-            // Fold the project capabilityOverrides over the global baseline so a
-            // project can force-enable a globally-disabled skill/plugin or vice
-            // versa. Read the project overlay UNMERGED (getForScope), not the merged
-            // get(), so tri-state inheritance survives. No cwd / no overlay → the
-            // baseline is returned unchanged (zero regression).
-            const cwd = this.config.cwd;
-            const overrides = cwd
-                ? sm.getForScope("project", cwd).capabilityOverrides
-                : undefined;
-            return {
-                disabledSkills: effectiveDisabledList(settings.disabledSkills ?? [], overrides?.skills),
-                disabledPlugins: effectiveDisabledList(settings.disabledPlugins ?? [], overrides?.plugins),
-            };
+            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"],
+]);