@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/engine/engine.js

@@ -3,67 +3,59 @@
  */
 import { createLLMClient } from "../llm/client-factory.js";
 import { ToolRegistry } from "../tool-system/registry.js";
-import { ToolExecutor } from "../tool-system/executor.js";
-import { InvestigationGuard } from "../tool-system/investigation-guard.js";
-import { TaskGuard } from "../tool-system/task-guard.js";
+import { queryExtensionModules, registerExtensionModules, } from "../tool-system/capability-module.js";
 import { readLastTodoSnapshot } from "../tool-system/builtin/task.js";
-import { applyDynamicToolDef } from "./dynamic-tool-defs.js";
 import { getMergedCatalog } from "../model-catalog/index.js";
 import { modelEntriesFromConnections } from "./model-connections-pool.js";
-import { resolveAuxKey } from "./aux-key.js";
-import { addTokenUsage, addCumulativeUsage, cumulativeCacheHitRate, foldRunUsage, normalizeCumulativeUsageCounters, } from "./session-usage.js";
+import { 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 { RunEnvironmentResolver } from "./run-environment.js";
+import { BUILTIN_TOOLS, } 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 { notificationQueue } from "../tool-system/builtin/agent-notifications.js";
 import { HookRegistry } from "../hooks/registry.js";
-import { wrapHookMessages } from "../hooks/inject.js";
-import { createGoalStopHook } from "../hooks/goal-stop-hook.js";
-import { normalizeGoal, resolveGoalSetAt, resolveMaxTurns, resolveMaxStopBlocks, isSameGoalInstance, } from "./goal.js";
+import { normalizeGoal, resolveMaxTurns, resolveMaxStopBlocks, goalConfigFromLifecycle, isGoalLifecycleCurrent, isSameGoalVersion, } from "../goal/lifecycle.js";
 import { loadPluginHooks } from "../plugins/loadPluginHooks.js";
 import { pluginAgentDirs } from "../plugins/installer/loadPluginAgents.js";
-import { patchOrphanedToolUses } from "./patch-orphaned-tools.js";
 import { runShellHook, shellHookMatches } from "../hooks/shell-runner.js";
 import { ContextManager } from "../context/manager.js";
-import { estimateTokens, clampContextRatios as clampContextRatiosImpl, } from "../context/compaction.js";
-import { PLAN_MODE_ALLOWED_TOOLS } from "../tool-system/plan-mode-allowlist.js";
+import { CONTEXT_PACKAGE_MAX_OUTPUT_TOKENS, buildContextPackagePromptFromSerialized, estimateTokens, groupMessagesByApiRound, serializeContextPackageMessages, clampContextRatios as clampContextRatiosImpl, } from "../context/compaction.js";
 import { PromptComposer } from "../prompt/composer.js";
-import { SessionManager, } from "../session/session-manager.js";
-import { ModelFacade } from "./model-facade.js";
-import { logger, runWithSid, getCurrentSid } from "../logging/logger.js";
-import { recordSessionStart, recordSessionEnd } from "../logging/session-recorder.js";
-import { sanitizeContent, sanitizeTaskString } from "../logging/sanitize-messages.js";
+import { SessionManager, assertSafeSessionId, isEphemeralSessionState, sessionsRoot, } from "../session/session-manager.js";
+import { createRunUsageAccounting, wireRunModelFacade } from "./run-accounting.js";
+import { logger, runWithSid } from "../logging/logger.js";
+import { recordSessionStart } from "../logging/session-recorder.js";
+import { sanitizeTaskString } from "../logging/sanitize-messages.js";
 import { TurnLoop } from "./turn-loop.js";
-import { MCPManager } from "../tool-system/mcp-manager.js";
 import { SettingsManager, userHome } from "../settings/manager.js";
 import { getCredentialAccess } from "../credentials/access.js";
-import { isFeatureEnabled, resolveFeatureFlags, } from "../settings/feature-flags.js";
-import { effectiveDisabledList, effectiveBuiltinLists } from "../capability-control/overlay.js";
+import { resolveFeatureFlags, } from "../settings/feature-flags.js";
+import { effectiveBuiltinLists, effectiveDisabledList, effectiveProjectOverrides, } from "../capability-control/overlay.js";
 import { computeEffectiveDisabledLists } from "../capability-control/disabled-lists.js";
-import { FileHistory } from "../session/file-history.js";
-import { patchBackupTargets } from "../tool-system/builtin/apply-patch/backup-targets.js";
-import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
+import { registerFileHistoryHook } from "./file-history-hook.js";
 import { resolveAgentPreset, resolveBuiltinToolNames } from "../preset/index.js";
+import { composeDynamicContextProviders, composeCapabilityEngineHooks, composePromptSections, composeToolCatalog, resolveCapabilities, resolveInstructionBoundary, } from "../capabilities/index.js";
 import { ModelPool } from "../llm/model-pool.js";
 import { AgentDefinitionRegistry } from "../agent/agent-definition-registry.js";
 import { defaultCacheDir } from "../llm/model-cache.js";
 import { detectProviderFromApiKey, buildModelPool } from "../onboarding.js";
 import { detectPastedNoise } from "../utils/task-sanitizer.js";
-import { formatFriendlyError } from "./friendly-error.js";
-import { buildSessionTitle } from "./session-title.js";
-import { MemoryOrchestrator } from "../services/memory-orchestrator.js";
-import { runDreamConsolidation } from "../services/dream-consolidation.js";
+import { PromptCacheDiagnosticRecorder, promptCacheDropHint, } from "./prompt-cache-diagnostics.js";
 import { buildRunUserMessageContent, prepareRunImageInput } from "./run-image-input.js";
+import { QUICK_CHAT_RESTRICTED_PROFILE, } from "./run-types.js";
+import { createSubAgentSpawner } from "./subagent-spawner.js";
+import { AuxiliaryPipeline, sameLlmIdentity } from "./auxiliary-pipeline.js";
+import { PermissionController } from "./permission-controller.js";
+import { buildPromptComposerConfig } from "./run-setup.js";
+import { resolveRunWorkspace } from "./run-workspace.js";
+import { openRunSession } from "./run-session-open.js";
+import { buildRunToolContext, buildRunPermissionPipeline, connectRunMcp, assembleRunToolDefs, } from "./run-tooling.js";
+import { createRunContextManager, composeRunSystemPrompt, assembleRunMessages, } from "./run-context.js";
+import { resolveRunGoal, armRunGoalHook, createGoalTerminationApplier, } from "./run-goal.js";
+import { drainHeadlessBackgroundAgents, finalizeRunSuccess, buildRunFailureResult, } from "./run-finalize.js";
 import { join } from "node:path";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-const CACHE_READ_DROP_MIN_PREVIOUS_TOKENS = 100;
-const CACHE_READ_DROP_MAX_CURRENT_TOKENS = 64;
-const CACHE_READ_DROP_RATIO = 0.1;
-const CACHE_READ_DIAGNOSTIC_MAX_SESSIONS = 256;
 /**
  * Build ScanOptions.compatFileNames from the user's instruction compat toggles.
  * Primary file name stays hard-wired to CODESHELL.md (not exposed). Turning a
@@ -79,31 +71,11 @@ export function compatFileNamesFrom(instructions) {
         names.push("AGENTS.md");
     return names;
 }
-/**
- * True when two LLMConfigs name the SAME client identity — i.e. building a
- * client from either would talk to the same model on the same endpoint with the
- * same shaping. Used by resolveAuxClient to de-dup the aux client against the
- * active model WITHOUT collapsing two distinct pool keys that merely share a
- * `model` NAME but differ in reasoning/maxTokens/baseUrl/provider. Compares the
- * fields that actually change request behavior; apiKey is intentionally NOT
- * compared (two keys with the same endpoint+model but different credentials
- * still produce equivalent aux work and don't warrant a second client). The
- * reasoning object is compared by normalized JSON since it's a small
- * discriminated union.
- */
-function sameLlmIdentity(a, b) {
-    return (a.model === b.model &&
-        (a.baseUrl ?? undefined) === (b.baseUrl ?? undefined) &&
-        (a.provider ?? undefined) === (b.provider ?? undefined) &&
-        (a.providerKind ?? undefined) === (b.providerKind ?? undefined) &&
-        (a.maxTokens ?? undefined) === (b.maxTokens ?? undefined) &&
-        JSON.stringify(a.reasoning ?? null) === JSON.stringify(b.reasoning ?? null));
-}
 // Re-export the config hot-reload patch builder from here so the protocol
 // server (and tests) can import it alongside Engine without reaching into the
 // settings/ subtree directly. The implementation lives in settings/ to keep
 // engine.ts from growing and to sit next to personalizationFrom it composes.
-export { diskDefaultsFrom } from "../settings/disk-defaults.js";
+export { diskDefaultsFrom } from "./disk-defaults.js";
 /**
  * Resolve the LLM config for a spawned child Engine.
  * - `modelKey` set + present in pool → that model's config (pure entry-derived
@@ -116,34 +88,16 @@ export { diskDefaultsFrom } from "../settings/disk-defaults.js";
  * Engine directly via EngineConfig.clientDefaults — they do not flow through
  * this helper because they're not part of LLMConfig anymore.
  */
-export function resolveChildLlm(modelKey, pool, parentLlm) {
-    if (modelKey && pool?.has(modelKey)) {
-        const resolved = pool.resolveLLMConfig(modelKey);
-        if (resolved)
-            return resolved;
-    }
-    return parentLlm;
-}
+export { resolveChildLlm, resolveChildToolScope } from "./subagent-spawner.js";
+// resolveRunCwd moved to run-workspace.ts; re-exported here so
+// engine.resolve-cwd.test.ts keeps resolving it from engine.js unchanged.
+export { resolveRunCwd } from "./run-workspace.js";
 /**
  * Load reusable sub-agent role definitions, merging:
  *   1. project-level  <cwd>/.code-shell/agents/*.md   (ships built-ins)
  *   2. user-level     ~/.code-shell/agents/*.md        (user wins on name)
  * Names in `disabledAgents` are filtered out so the LLM never sees them.
  */
-/**
- * Resolve the working directory for a run. Precedence for legacy sessions:
- *   options.cwd  >  resumed session's state.cwd  >  config.cwd  >  process.cwd()
- *
- * The session-cwd tier is what stops a project-bound session from being
- * resumed against the wrong directory: when a host omits options.cwd (e.g. its
- * sidebar repo selection drifted to null), the session's own recorded cwd is
- * recovered so the engine still loads THAT project's agents/settings/memory,
- * not whatever process.cwd() happens to be. Pure so the precedence is testable
- * without standing up an Engine.
- */
-export function resolveRunCwd(args) {
-    return args.optionCwd ?? args.sessionCwd ?? args.configCwd ?? args.processCwd;
-}
 export function loadAgentDefinitionsForCwd(cwd, disabledAgents = [], disabledPlugins = []) {
     // userHome() (not raw homedir(), which bun caches at process start and never
     // re-reads) so the user-agents dir honors a test's process.env.HOME override
@@ -164,7 +118,6 @@ export function loadAgentDefinitionsForCwd(cwd, disabledAgents = [], disabledPlu
         ...(cwd ? [{ dir: `${cwd}/.code-shell/agents`, source: "project" }] : []),
     ], disabledAgents);
 }
-const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel", "AgentSendInput"];
 /**
  * #7: apply a project's per-turn builtin capability override to a tool list.
  * A builtin marked `off` for the current cwd is HIDDEN from the turn's tool
@@ -185,17 +138,6 @@ export function applyBuiltinOverrideVisibility(tools, override) {
  * - `allowlist` undefined → inherit parent enabled/disabled, always with the
  *   nested-agent tools forced into `disabled` (no grandchildren).
  */
-export function resolveChildToolScope(allowlist, parentDisabled, parentEnabled) {
-    if (allowlist) {
-        return {
-            enabled: allowlist.filter((t) => !NESTED_AGENT_TOOLS.includes(t)),
-            disabled: [...NESTED_AGENT_TOOLS],
-        };
-    }
-    const disabled = Array.from(new Set([...(parentDisabled ?? []), ...NESTED_AGENT_TOOLS]));
-    const enabled = parentEnabled?.filter((t) => !NESTED_AGENT_TOOLS.includes(t));
-    return { enabled, disabled };
-}
 export class Engine {
     config;
     // Resolved per-session preset. Set in the ctor; re-resolved by
@@ -205,9 +147,22 @@ export class Engine {
     // and is NOT rebuilt on reload — a preset change that alters the builtin tool
     // set only takes effect on session restart (logged in refreshRuntimeConfig).
     preset;
+    /** Capability-free seed owned by the runtime/host; never mutated by an Engine. */
+    runtimeToolRegistry;
+    /** Engine-local view containing only this Engine's capability modules. */
     toolRegistry;
+    capabilities;
+    toolCatalog;
+    toolGuards;
+    /** Per-turn dynamic definition rewriters contributed by builtin exposures. */
+    toolRewriters;
+    /** Named per-run behavior profiles (core defaults + config + extensions). */
+    behaviorProfiles;
+    capabilityPromptSections;
+    capabilityDynamicContextProviders;
     hooks;
     sessionManager;
+    sessionMessageRouter;
     mcpManager;
     modelPool;
     /**
@@ -229,24 +184,13 @@ export class Engine {
     agentDefsCache;
     /** Shared resources supplied at construction (adapter pattern — null when self-constructed). */
     runtime;
-    sandboxCache = new Map();
-    interactiveBackends = new WeakMap();
-    activeApprovalRouter;
-    /** Active permission mode for this Engine instance. */
-    permissionMode;
-    /** True when permissionMode === "plan". */
-    planMode;
+    runEnvironmentResolver;
+    auxiliaryPipeline;
+    permissionController;
     // Lazy SettingsManager — reused across updateConfig/readSetting so we
     // don't re-read 6+ JSON files on every /model, /login, etc. The manager
     // handles its own cache invalidation in saveUserSetting().
     settingsManager;
-    /**
-     * Cached auxiliary-task LLM client, keyed by the models[].key it was built
-     * from. Background calls (memory extraction, auto-dream) reuse it across
-     * runs so we don't redo the provider handshake every session. Invalidated
-     * implicitly: a changed auxModelKey produces a different cache key.
-     */
-    auxClientCache;
     // Live state from the current/most-recent run, retained for /compact and
     // run-boundary PermissionClassifier replacement/reconfiguration.
     lastContextManager;
@@ -269,7 +213,7 @@ export class Engine {
      * LLM response arrives.
      */
     ctxOverheadBySid = new Map();
-    lastCacheReadBySid = new Map();
+    promptCacheDiagnostics = new PromptCacheDiagnosticRecorder({ maxSessions: 256 });
     /**
      * Step-gap steering queue (per sessionId, in-memory). Host pushes user
      * messages here via enqueueSteer while a run is in flight; the turn loop
@@ -279,7 +223,6 @@ export class Engine {
      * 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.
@@ -291,12 +234,18 @@ export class Engine {
      * otherwise keep re-blocking the stop). Null when no goal run is active.
      */
     activeGoalHook = null;
+    /** Whether activeGoalHook is currently registered (pause detaches it). */
+    activeGoalHookAttached = false;
+    /** Mutable goal view consumed by the running judge after edits/resume. */
+    activeRuntimeGoal = null;
+    /** Mutable terminal snapshot kept in sync with a mid-run objective edit. */
+    activePersistedRunGoal = 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
+     * (bundle.state.goalLifecycle was never rebased). 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.
@@ -306,23 +255,25 @@ export class Engine {
     /**
      * Same-instance run guard. Engine owns single-valued live controls and one
      * HookRegistry, so a second run must not enter until the first has completed
-     * all state persistence and end hooks. This prevents handle contamination and
-     * whole-state saveState overlap only within this Engine instance. It does not
-     * coordinate different Engine instances sharing a sessionId, Workers, or
-     * processes; session-level locking/CAS for those cases is a separate finding.
+     * all state persistence and end hooks. Cross-instance/process whole-state
+     * writers are additionally fenced by SessionManager's persisted revision CAS.
      */
     runInProgress = false;
+    agentControlStateListener;
+    agentDirectionsDeliveredListener;
     /** Permission update requested while runInProgress. Applied in run() finally. */
-    pendingPermissionMode = null;
-    /** Plan update paired with pendingPermissionMode for one atomic boundary apply. */
-    pendingPlanMode = null;
     /** Public accessor so UI/clients can read the resolved per-model window. */
     get maxContextTokens() {
         return this.resolveMaxContextTokens();
     }
     resolveMaxContextTokens() {
-        const modelEntry = this.modelPool.get();
-        return modelEntry?.maxContextTokens ?? this.config.maxContextTokens ?? 200_000;
+        const modelEntry = this.modelPool
+            .list()
+            .find((entry) => sameLlmIdentity(this.modelPool.toLLMConfig(entry), this.config.llm));
+        return (this.config.llm.maxContextTokens ??
+            modelEntry?.maxContextTokens ??
+            this.config.maxContextTokens ??
+            200_000);
     }
     /**
      * Compaction thresholds from settings.context, clamped so they keep the
@@ -440,10 +391,63 @@ export class Engine {
         this.config = config;
         // Wire shared runtime (adapter pattern — null when self-constructing).
         this.runtime = config.runtime ?? null;
-        // Instance-level permission/plan mode fields.
-        this.permissionMode = config.permissionMode ?? "acceptEdits";
-        this.planMode = this.permissionMode === "plan";
-        this.preset = resolveAgentPreset(config.preset);
+        this.runEnvironmentResolver = new RunEnvironmentResolver({
+            config: () => this.config,
+            settings: () => this.getSettingsManager(),
+            credentialAccess: {
+                envExposures: (cwd, scope) => getCredentialAccess().envExposures(cwd, scope),
+            },
+            ...(this.runtime ? { runtime: this.runtime } : {}),
+        });
+        this.capabilities = resolveCapabilities(config.capabilities);
+        this.config = { ...config, capabilities: this.capabilities };
+        this.toolCatalog = composeToolCatalog(BUILTIN_TOOLS, this.capabilities, config.extensionModules ?? []);
+        this.toolGuards = new Map(this.toolCatalog.flatMap((tool) => tool.exposure.availability
+            ? [[tool.definition.name, tool.exposure.availability]]
+            : []));
+        this.toolRewriters = new Map(this.toolCatalog.flatMap((tool) => tool.exposure.rewriteDefinition
+            ? [[tool.definition.name, tool.exposure.rewriteDefinition]]
+            : []));
+        // Behavior profile registry: core defaults first, then host config, then
+        // extension modules — later registrations override earlier ones by id.
+        this.behaviorProfiles = new Map([
+            QUICK_CHAT_RESTRICTED_PROFILE,
+            ...(config.behaviorProfiles ?? []),
+            ...(config.extensionModules ?? []).flatMap((module) => module.behaviorProfiles ?? []),
+        ].map((profile) => [profile.id, profile]));
+        this.capabilityPromptSections = composePromptSections(this.capabilities);
+        this.capabilityDynamicContextProviders = composeDynamicContextProviders(this.capabilities);
+        this.preset = resolveAgentPreset(config.preset, this.capabilities);
+        // Extension catalogTools join the active preset regardless of its name:
+        // presets snapshot their tool lists from the catalogs known at module
+        // load, which can never include extension packages. Visibility stays
+        // gated by each tool's exposure.availability guard.
+        const extensionCatalogTools = (config.extensionModules ?? []).flatMap((module) => [
+            ...(module.catalogTools ?? []),
+        ]);
+        if (extensionCatalogTools.length > 0) {
+            this.preset = {
+                ...this.preset,
+                builtinTools: [
+                    ...this.preset.builtinTools,
+                    ...extensionCatalogTools.map((tool) => tool.definition.name),
+                ],
+                defaultPermissionRules: [
+                    ...this.preset.defaultPermissionRules,
+                    ...extensionCatalogTools.flatMap((tool) => [
+                        ...(tool.exposure.defaultPermissionRules ?? []),
+                    ]),
+                ],
+            };
+        }
+        this.permissionController = new PermissionController({
+            config: () => this.config,
+            updateConfig: (next) => {
+                this.config = next;
+            },
+            presetRules: () => [...this.preset.defaultPermissionRules],
+            runInProgress: () => this.runInProgress,
+        });
         // Fold the project's capabilityOverrides.builtin overlay over the global
         // enabled/disabled builtin lists so a project can force-enable a
         // globally-disabled builtin tool or force-disable a globally-enabled one
@@ -459,16 +463,25 @@ 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 =
+        this.runtimeToolRegistry =
             config.runtime?.toolRegistry ??
                 new ToolRegistry({
                     builtinTools: resolveBuiltinToolNames({
                         preset: this.preset.name,
                         host: config.builtinToolHost,
-                        enabledBuiltinTools: builtinLists.enabledBuiltinTools,
+                        enabledBuiltinTools: [
+                            ...builtinLists.enabledBuiltinTools,
+                            // Extension catalogTools are preset-agnostic (see preset merge
+                            // above); their availability guards gate actual visibility.
+                            ...extensionCatalogTools.map((tool) => tool.definition.name),
+                        ],
                         disabledBuiltinTools: builtinLists.disabledBuiltinTools,
+                        capabilities: this.capabilities,
                     }),
+                    toolCatalog: this.toolCatalog,
                 });
+        this.toolRegistry = this.runtimeToolRegistry.fork();
+        registerExtensionModules(this.toolRegistry, config.extensionModules ?? []);
         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
@@ -489,14 +502,26 @@ export class Engine {
             loadPluginHooks(this.hooks, disabledPlugins, disabledPluginHooks);
         }
         // settings.hooks → shell-command wrappers. Chain order:
-        // plugin (80) → shell (50) → code (default 0).
+        // plugin (80) → shell (50) → capability (20) → SDK code (default 0).
         this.registerSettingsHooks();
+        for (const hook of composeCapabilityEngineHooks(this.capabilities)) {
+            this.hooks.register(hook.event, hook.handler, hook.priority, hook.name);
+        }
         for (const hook of config.hooks ?? []) {
             this.hooks.register(hook.event, hook.handler, hook.priority, hook.name);
         }
-        this.sessionManager = new SessionManager(config.sessionStorageDir);
+        this.sessionManager = new SessionManager(config.sessionStorageDir, this.capabilities
+            .map((capability) => capability.sessionWorkspace)
+            .find((candidate) => candidate !== undefined));
         // Initialize model pool — prefer runtime's shared pool, fall back to self-constructed.
         this.modelPool = config.runtime?.modelPool ?? new ModelPool();
+        this.auxiliaryPipeline = new AuxiliaryPipeline({
+            config: () => this.config,
+            settings: () => this.getSettingsManager(),
+            modelPool: () => this.modelPool,
+            toolRegistry: () => this.toolRegistry,
+            toolContext: () => this.buildToolContext(),
+        });
         if (!config.runtime) {
             this.populateModelPoolFromSettings();
         }
@@ -638,6 +663,10 @@ export class Engine {
     registerCustomTool(definition, executor) {
         this.toolRegistry.registerTool(definition, executor);
     }
+    /** Dispatch a host-installed capability query without teaching core its name. */
+    queryCapability(type, params = {}) {
+        return queryExtensionModules(this.config.extensionModules ?? [], type, params);
+    }
     /**
      * Inject the askUser handler after construction. Used by AgentServer
      * to wire its protocol-backed askUser into an Engine that was created
@@ -646,6 +675,13 @@ export class Engine {
     setAskUser(fn) {
         this.config.askUser = fn;
     }
+    /** Internal child-runtime seam used by the single-writer supervisor. */
+    setAgentControlStateListener(listener) {
+        this.agentControlStateListener = listener;
+    }
+    setAgentDirectionsDeliveredListener(listener) {
+        this.agentDirectionsDeliveredListener = listener;
+    }
     /**
      * Inject the browser automation bridge after construction (same chicken-and-egg
      * as setAskUser: the desktop host builds the bridge — which drives a webview —
@@ -659,6 +695,14 @@ export class Engine {
     setWorkspaceBridge(bridge) {
         this.config.workspaceBridge = bridge;
     }
+    /** Inject the host-backed panel discovery/focus bridge after construction. */
+    setPanelBridge(bridge) {
+        this.config.panelBridge = bridge;
+    }
+    /** Inject the host router used by SendMessageToSession. */
+    setSessionMessageRouter(router) {
+        this.sessionMessageRouter = router;
+    }
     /**
      * 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 +
@@ -754,6 +798,12 @@ export class Engine {
     isHeadless() {
         return this.config.headless === true;
     }
+    get permissionMode() {
+        return this.permissionController.permissionMode;
+    }
+    get planMode() {
+        return this.permissionController.planMode;
+    }
     /**
      * Probe whether a session already exists on disk (its state/transcript dir is
      * present). Used by the protocol server to distinguish "resume an existing
@@ -767,6 +817,121 @@ export class Engine {
     forkSession(sourceSessionId, options) {
         return this.sessionManager.fork(sourceSessionId, options);
     }
+    selectContextPackage(sourceSessionId, range) {
+        return this.sessionManager.selectContextPackage(sourceSessionId, range);
+    }
+    createSummaryFork(sourceSessionId, options) {
+        return this.sessionManager.createSummaryFork(sourceSessionId, options);
+    }
+    /** Summarize a selected transcript package using the configured aux tier. */
+    async summarizeContextPackage(messages, signal, sourceSessionId) {
+        if (messages.length === 0)
+            throw new Error("Cannot summarize an empty context package");
+        const serializedSelection = serializeContextPackageMessages(messages);
+        if (!serializedSelection.hasSummarizableContent) {
+            throw new Error("Cannot summarize an image-only context package without textual or tool facts");
+        }
+        if (sourceSessionId && this.config.costStore) {
+            const persistedCost = this.sessionManager.resume(sourceSessionId).state.costState;
+            if (persistedCost)
+                this.config.costStore.restore(persistedCost);
+        }
+        const primaryClient = await createLLMClient(this.config.llm, this.config.clientDefaults);
+        const resolvedAux = await this.auxiliaryPipeline.resolveAuxClientWithMetadata(primaryClient, this.resolveMaxContextTokens());
+        const client = resolvedAux.client;
+        const systemPrompt = "You package selected conversation context. Be concise, factual, and complete.";
+        const fitsAuxWindow = (conversation, priorSummary) => {
+            const prompt = buildContextPackagePromptFromSerialized(conversation, priorSummary);
+            const requestTokens = estimateTokens([
+                { role: "system", content: systemPrompt },
+                { role: "user", content: prompt },
+            ]);
+            return requestTokens + CONTEXT_PACKAGE_MAX_OUTPUT_TOKENS <= resolvedAux.maxContextTokens;
+        };
+        if (!fitsAuxWindow("x")) {
+            throw new Error(`Auxiliary model context window (${resolvedAux.maxContextTokens}) is too small for the context package template and output reserve`);
+        }
+        // Preserve complete API rounds whenever they fit. If one round alone is
+        // larger than the aux window, split its lossless serialized form and feed
+        // every fragment through the same rolling nine-section merge.
+        const pending = groupMessagesByApiRound(messages).map((group) => serializeContextPackageMessages(group).text);
+        let summary;
+        while (pending.length > 0) {
+            let conversation = "";
+            while (pending.length > 0) {
+                const next = pending[0];
+                const candidate = conversation ? `${conversation}\n${next}` : next;
+                if (fitsAuxWindow(candidate, summary)) {
+                    conversation = candidate;
+                    pending.shift();
+                    continue;
+                }
+                if (conversation)
+                    break;
+                let low = 1;
+                let high = next.length;
+                let fitLength = 0;
+                while (low <= high) {
+                    const middle = Math.floor((low + high) / 2);
+                    if (fitsAuxWindow(next.slice(0, middle), summary)) {
+                        fitLength = middle;
+                        low = middle + 1;
+                    }
+                    else {
+                        high = middle - 1;
+                    }
+                }
+                if (fitLength === 0) {
+                    throw new Error(`Auxiliary model context window (${resolvedAux.maxContextTokens}) cannot fit the rolling context package prompt`);
+                }
+                conversation = next.slice(0, fitLength);
+                const remainder = next.slice(fitLength);
+                if (remainder)
+                    pending[0] = remainder;
+                else
+                    pending.shift();
+                break;
+            }
+            const response = await client.createMessage({
+                systemPrompt,
+                messages: [
+                    {
+                        role: "user",
+                        content: buildContextPackagePromptFromSerialized(conversation, summary),
+                    },
+                ],
+                tools: [],
+                maxTokens: CONTEXT_PACKAGE_MAX_OUTPUT_TOKENS,
+                billingEnabled: true,
+                requestVisible: false,
+                reasoning: { mode: "off" },
+                signal,
+            });
+            if (response.usage && sourceSessionId) {
+                this.sessionManager.recordAuxiliaryUsage(sourceSessionId, response.usage, this.config.costStore?.serialize());
+            }
+            summary = response.text.trim();
+            if (!summary)
+                throw new Error("Context package summary was empty");
+        }
+        return {
+            summary: summary,
+            estimatedTokens: estimateTokens([{ role: "user", content: summary }]),
+        };
+    }
+    /** Restore a cold Engine's configured model from persisted source state without resetting usage. */
+    restoreSessionModel(sessionId) {
+        const state = this.sessionManager.resume(sessionId).state;
+        if (this.config.llm.model === state.model && this.config.llm.provider === state.provider)
+            return;
+        const entry = this.modelPool
+            .list()
+            .find((candidate) => candidate.model === state.model && candidate.provider === state.provider) ?? this.modelPool.list().find((candidate) => candidate.model === state.model);
+        if (!entry) {
+            throw new Error(`Persisted source model is no longer configured: ${state.model}`);
+        }
+        this.config = { ...this.config, llm: this.modelPool.toLLMConfig(entry) };
+    }
     /**
      * Run a task from start to finish. Rejects immediately when this Engine
      * instance already has a run in progress; hosts that want queueing own that
@@ -782,64 +947,51 @@ export class Engine {
         }
         finally {
             try {
-                this.applyPendingPermissionState();
+                this.permissionController.applyPending();
             }
             finally {
                 this.runInProgress = false;
             }
         }
     }
+    /**
+     * Resolve the run's active behavior profile. A profile bound to the
+     * persisted session kind wins (so e.g. a resumed pet session keeps the safe
+     * profile even when the host omits behaviorMode); otherwise the explicit
+     * behaviorMode names a registered profile directly. Explicit unknown modes
+     * and non-work session kinds without an owning profile fail closed: silently
+     * falling back to an unrestricted run would turn a missing extension into a
+     * permission-boundary bypass.
+     */
+    resolveBehaviorProfile(sessionKind, behaviorMode) {
+        const explicitProfile = behaviorMode !== undefined ? this.behaviorProfiles.get(behaviorMode) : undefined;
+        if (behaviorMode !== undefined && !explicitProfile) {
+            throw new Error(`unknown behavior profile: ${behaviorMode}`);
+        }
+        const sessionProfile = [...this.behaviorProfiles.values()].find((profile) => profile.activateForSessionKinds?.includes(sessionKind));
+        if (sessionKind !== "work" && !sessionProfile) {
+            throw new Error(`session kind has no registered behavior profile: ${sessionKind}`);
+        }
+        return sessionProfile ?? explicitProfile;
+    }
     async runExclusive(task, options) {
         // Freeze permission context once, before the first await. Per-turn protocol
         // overrides live only for this run; persistent setPermissionMode/setPlanMode
         // calls made while busy are staged separately and cannot mutate this pair.
-        let runPermissionMode = options?.permissionMode ?? this.config.permissionMode ?? "acceptEdits";
-        if (options?.planMode === true) {
-            runPermissionMode = "plan";
-        }
-        else if (options?.planMode === false && runPermissionMode === "plan") {
-            runPermissionMode = "acceptEdits";
-        }
-        const runPlanMode = runPermissionMode === "plan";
-        const workspaceResume = options?.sessionId && this.sessionManager.exists(options.sessionId)
-            ? await this.sessionManager.resolveSessionWorkspaceForResume(options.sessionId)
-            : undefined;
-        if (workspaceResume && !workspaceResume.ok) {
-            return {
-                text: `ERROR: ${workspaceResume.message}`,
-                reason: "completed",
-                sessionId: options.sessionId,
-                turnCount: 0,
-                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-            };
-        }
-        if (workspaceResume?.ok &&
-            workspaceResume.reason === "worktree_missing_branch_gone" &&
-            workspaceResume.message) {
-            return {
-                text: workspaceResume.message,
-                reason: "completed",
-                sessionId: options.sessionId,
-                turnCount: 0,
-                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
-            };
-        }
-        // Existing P1 sessions resolve cwd from SessionWorkspace, even if the host
-        // passes a stale cwd. Legacy sessions without workspace keep the historical
-        // explicit-cwd precedence for backward compatibility.
-        const workspaceCwd = workspaceResume?.ok && workspaceResume.reason !== "legacy" ? workspaceResume.cwd : undefined;
-        const sessionCwd = workspaceCwd === undefined && options?.cwd === undefined && options?.sessionId
-            ? workspaceResume?.ok
-                ? workspaceResume.cwd
-                : this.sessionManager.readCwd(options.sessionId)
-            : undefined;
-        const cwd = workspaceCwd ??
-            resolveRunCwd({
-                optionCwd: options?.cwd,
-                sessionCwd,
-                configCwd: this.config.cwd,
-                processCwd: process.cwd(),
-            });
+        const workspaceResolved = await resolveRunWorkspace({
+            options,
+            sessionManager: this.sessionManager,
+            resolveBehaviorProfile: (kind, mode) => this.resolveBehaviorProfile(kind, mode),
+            configPermissionMode: this.config.permissionMode,
+            configCwd: this.config.cwd,
+            settings: this.getSettingsManager(),
+            processCwd: process.cwd(),
+        });
+        if (!workspaceResolved.ok)
+            return workspaceResolved.result;
+        const { sessionKind, sessionWorkspaceProfile, profile, profileParams, runPermissionMode, runPlanMode, cwd, profileState: { workspaceProfile: runWorkspaceProfile, sessionProfileOverrides, profileMemoryDir, }, } = workspaceResolved.resolution;
+        /** Structured results the profile's run services report; keyed per profile contract. */
+        let profileReportedResults;
         // 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
@@ -848,23 +1000,13 @@ export class Engine {
         // store is the transcript, but TaskGuard runs in-loop and can't
         // afford a transcript scan per turn.
         let latestTodos = [];
-        const userOnStream = options?.onStream;
-        const wrappedOnStream = (event) => {
-            if (event.type === "task_update") {
-                latestTodos = event.tasks;
-            }
-            // Persist goal progress so replay/history shows how many rounds the
-            // goal ran. Display-only — toMessages() ignores this type, so it never
-            // re-enters the LLM context.
-            if (event.type === "goal_progress") {
-                session.transcript.append("goal_progress", {
-                    status: event.status,
-                    round: event.round,
-                    ...(event.gaps ? { gaps: event.gaps } : {}),
-                });
-            }
-            userOnStream?.(event);
-        };
+        const wrappedOnStream = this.buildWrappedOnStream({
+            userOnStream: options?.onStream,
+            getSession: () => session,
+            setLatestTodos: (todos) => {
+                latestTodos = todos;
+            },
+        });
         if (options)
             options.onStream = wrappedOnStream;
         const imageInput = await prepareRunImageInput({
@@ -891,176 +1033,20 @@ export class Engine {
                 usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
             };
         }
-        // Build the per-Engine ToolContext that will be threaded through every
-        // tool call. Replaces the old module-level singletons (setAskUserFn,
-        // setArenaLLMConfig, setSubAgentConfig, setToolSearchRegistry).
-        const subAgentSpawner = {
-            parentStream: options?.onStream,
-            describe: () => ({
-                cwd,
-                preset: this.preset.name,
-                permissionMode: runPermissionMode,
-            }),
-            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
-                // guard a runaway model could fork-bomb sub-agents (token cost +
-                // background process explosion), and the sid / approval / dock
-                // model assumes a flat parent→children hierarchy. Layered with a
-                // runtime check in agent.ts as defense-in-depth.
-                const { enabled: childEnabled, disabled: childDisabled } = resolveChildToolScope(req.toolAllowlist, this.config.disabledBuiltinTools, this.config.enabledBuiltinTools);
-                const childLlm = resolveChildLlm(req.model, this.modelPool, this.config.llm);
-                const child = new Engine({
-                    llm: childLlm,
-                    // Inherit parent's runtime knobs (temperature, image detail, timeouts)
-                    // but cap sub-agent retries at 2 — they're short-lived and we'd
-                    // rather surface failures than burn a 9 s exponential backoff loop.
-                    clientDefaults: { ...(this.config.clientDefaults ?? {}), retryMaxAttempts: 2 },
-                    cwd,
-                    permissionMode: runPermissionMode,
-                    preset: this.preset.name,
-                    enabledBuiltinTools: childEnabled,
-                    disabledBuiltinTools: childDisabled,
-                    builtinToolHost: this.config.builtinToolHost,
-                    customSystemPrompt: this.config.customSystemPrompt,
-                    appendSystemPrompt: [this.config.appendSystemPrompt, req.appendSystemPrompt].filter(Boolean).join("\n\n") ||
-                        undefined,
-                    responseLanguage: this.config.responseLanguage,
-                    userProfile: this.config.userProfile,
-                    instructions: this.config.instructions,
-                    maxTurns: req.maxTurns,
-                    maxContextTokens: this.config.maxContextTokens ?? 200_000,
-                    sessionStorageDir: this.config.sessionStorageDir,
-                    headless: this.config.headless,
-                    readOnlySession: req.readOnlySession,
-                    skillAllowlist: req.skillAllowlist,
-                    sandbox: this.config.sandbox,
-                    // Subagents inherit the parent's scope: a child runs in the same
-                    // cwd/session, so it should see the same config layers the parent did.
-                    settingsScope: this.config.settingsScope ?? "project",
-                    isSubAgent: true,
-                });
-                // Where the spawned child Engine's stream events go. AgentTool's
-                // background path passes a `streamOverride` (transcriptSink) so the
-                // per-event detail is captured into the agent's transcript instead
-                // of flooding the main feed. Sync calls leave streamOverride unset
-                // and we fall back to the parent UI's onStream so synchronous
-                // sub-agents still render inline.
-                const destStream = req.streamOverride ?? options?.onStream;
-                const childStream = destStream
-                    ? (event) => {
-                        // Filter ctx-bar signals: the bar tracks the main conversation's
-                        // prompt size, and a sub-agent's own session emits would clobber
-                        // it (its sid is new, its messages are tiny, the rough char/4
-                        // seed lands the bar at <1% mid-turn). Sub-agent token accounting
-                        // lives in CostTracker (recordUsage), not the ctx bar.
-                        //
-                        // - session_started: would seed main ctx with sub-agent's prompt
-                        // - usage_update: would overwrite main ctx with sub-agent's prompt
-                        // - context_compact: would reset main ctx to sub-agent's post-compact
-                        //   value AND print a misleading "context compacted" boundary in
-                        //   the main chat (the main session didn't compact).
-                        if (event.type === "usage_update" ||
-                            event.type === "session_started" ||
-                            event.type === "context_compact") {
-                            return;
-                        }
-                        destStream({ ...event, agentId: req.agentId });
-                    }
-                    : undefined;
-                // 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.
-                //
-                // 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, usage: result.usage };
-            },
-            sessionExists: (sessionId) => this.sessionManager.exists(sessionId),
-        };
-        const sandboxConfig = this.resolveSandboxConfigForCwd(cwd);
-        // A2: explicit sandbox modes (seatbelt, bwrap) must fail closed
-        // per standard §S4. resolveSandboxBackend throws when an explicit
-        // mode is unavailable on this host; we let it propagate. The
-        // previous behavior — catching the throw inside the hot turn and
-        // silently downgrading to "off" — was the leak A2 closes. The
-        // `auto` mode handles its own downgrade with a one-time warning
-        // inside resolveSandboxBackend; explicit modes do not.
-        //
-        // Backend is cached per runtime/engine so the capability probe runs once
-        // per (mode, cwd) instead of every turn.
-        const sandboxBackend = this.runtime
-            ? await this.runtime.resolveSandbox(sandboxConfig, cwd)
-            : await 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
-        // after the assignment.
-        const toolCtx = {
-            ...this.buildToolContext(),
-            approvalRouter: options?.approvalRouter ?? this.config.approvalRouter,
-            permissionMode: runPermissionMode,
-            planMode: runPlanMode,
-            subAgentSpawner,
-            agentDefinitions: this.getAgentDefinitions(cwd),
-            // 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 },
+        const toolCtx = await this.wireRunSandboxToolContext({
+            options,
             cwd,
-            shellEnv: this.readShellEnv(cwd),
-            // TodoWrite reads this to push task_update events independently
-            // of its return value, so the UI's pinned task panel refreshes
-            // immediately rather than after the LLM next surfaces the
-            // snapshot. wrappedOnStream snoops the same channel to keep
-            // latestTodos current for TaskGuard.
-            streamCallback: options?.onStream,
-            setCwd(nextCwd) {
-                toolCtx.cwd = nextCwd;
+            runPermissionMode,
+            runPlanMode,
+            profile,
+            profileParams,
+            sessionProfileOverrides,
+            profileMemoryDir,
+            getSession: () => session,
+            reportResult: (key, value) => {
+                (profileReportedResults ??= {})[key] = value;
             },
-        };
+        });
         logger.info("engine.run", {
             task: taskText.slice(0, 200),
             cwd,
@@ -1082,465 +1068,83 @@ export class Engine {
         // surfacing as `[-32603] Session not found: <sid>` on the very first
         // TUI turn. Detection now uses `sessionManager.exists()` (one stat
         // call) instead of a try/catch on resume.
+        // wrappedOnStream (defined before the session opens, executed only after)
+        // closes over `session`, so keep the declaration here and assign from the
+        // opener's result.
         let session;
-        let messages;
-        let freshImageMessage;
-        let resumedFromDisk = false;
-        const claimedClientMessageIds = new Set();
-        const claimClientMessageId = (bundle, clientMessageId, source) => {
-            if (!clientMessageId)
-                return true;
-            if (claimedClientMessageIds.has(clientMessageId) ||
-                bundle.transcript.hasClientMessageId(clientMessageId)) {
-                logger.info("engine.client_message.duplicate_ignored", {
-                    sessionId: bundle.state.sessionId,
-                    clientMessageId,
-                    source,
-                });
-                return false;
-            }
-            claimedClientMessageIds.add(clientMessageId);
-            return true;
-        };
-        if (options?.sessionId && this.sessionManager.exists(options.sessionId)) {
-            resumedFromDisk = true;
-            session = this.sessionManager.resume(options.sessionId);
-            const cachedCompacted = this.compactedMessagesBySession.get(options.sessionId);
-            messages = cachedCompacted ? [...cachedCompacted] : session.transcript.toMessages();
-            // If the previous run was Ctrl+C'd or crashed between an assistant
-            // tool_use and the matching tool_result being persisted, the
-            // loaded sequence is invalid for OpenAI (which 400s on dangling
-            // tool_calls). Patch synthetic tool_results so the next API call
-            // doesn't fail before the turn even starts.
-            const patched = patchOrphanedToolUses(messages);
-            if (patched.gapsPatched > 0) {
-                logger.warn("engine.resume.patched_orphaned_tool_uses", {
-                    sessionId: options.sessionId,
-                    gaps: patched.gapsPatched,
-                    toolResults: patched.toolResultsInjected,
-                });
-            }
-            // Restore cost state from previous session, if the caller injected a store
-            if (session.state.costState && this.config.costStore) {
-                this.config.costStore.restore(session.state.costState);
-            }
-            // Append new user message
-            const userMsg = { role: "user", content: userMessageContent };
-            if (!claimClientMessageId(session, options?.clientMessageId, "submit")) {
-                const usage = session.state.tokenUsage ?? {
-                    promptTokens: 0,
-                    completionTokens: 0,
-                    totalTokens: 0,
-                };
-                return {
-                    text: "",
-                    reason: "completed",
-                    sessionId: session.state.sessionId,
-                    turnCount: session.state.turnCount ?? 0,
-                    usage: {
-                        promptTokens: usage.promptTokens ?? 0,
-                        completionTokens: usage.completionTokens ?? 0,
-                        totalTokens: usage.totalTokens ?? 0,
-                    },
-                };
-            }
-            if (parsedTask.hasImages)
-                freshImageMessage = userMsg;
-            messages.push(userMsg);
-            session.transcript.appendMessage("user", userMessageContent, {
-                injected: options?.injected === true,
-                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
-            // observer (another CLI process, /sid, the session list) would think
-            // the session is still errored/aborted while we're actually running.
-            this.sessionManager.saveState(session.state);
-        }
-        else {
-            // Cold start: shape (2) reuses the host-supplied sid; shape (3)
-            // lets sessionManager generate one with nanoid.
-            session = this.sessionManager.create(cwd, this.config.llm.model, this.config.llm.provider, options?.sessionId, this.config.isSubAgent === true ? getCurrentSid() : undefined, this.config.isSubAgent === true ? "subagent" : this.config.origin);
-            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}` : ""}]`
-                : 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;
-        // B2 / Gate 1: stamp the resolved sid onto the tool context so
-        // session-scoped side effects (background-agent completion
-        // notifications) attribute to the right session. toolCtx is created
-        // before the session bundle is resolved (see ~line 635), so this is
-        // the first point we can set it. After this assignment treat the
-        // field follows the latest successfully injected user intent for the rest
-        // of the run, so tools launched after a steer attribute their side effects
-        // to that steer rather than this original submit.
-        toolCtx.sessionId = session.state.sessionId;
-        toolCtx.originClientMessageId = options?.clientMessageId;
-        toolCtx.recordExternalFileChanges = (record) => {
-            session.transcript.append("external_file_changes", { ...record });
-        };
-        toolCtx.setSessionWorkspace = (workspace) => {
-            session.state.workspace = workspace;
-        };
+        const openedResult = openRunSession({
+            sessionManager: this.sessionManager,
+            options,
+            parsedTask,
+            taskText,
+            userMessageContent,
+            cwd,
+            sessionKind,
+            sessionWorkspaceProfile,
+            ...(options?.sessionBrief ? { sessionBrief: options.sessionBrief } : {}),
+            llmModel: this.config.llm.model,
+            llmProvider: this.config.llm.provider,
+            isSubAgent: this.config.isSubAgent === true,
+            origin: this.config.origin,
+            costStore: this.config.costStore,
+            onAgentDirectionsDelivered: (ids) => this.agentDirectionsDeliveredListener?.(ids),
+            cachedCompactedMessages: options?.sessionId
+                ? this.compactedMessagesBySession.get(options.sessionId)
+                : undefined,
+        });
+        if (!openedResult.ok)
+            return openedResult.result;
+        const { messages, freshImageMessage, resumedFromDisk, claimClientMessageId, releaseClientMessageId, } = openedResult.opened;
+        session = openedResult.opened.session;
+        this.stampRunToolContext(toolCtx, session, options);
         const sessionRun = runWithSid(session.state.sessionId, async () => {
-            recordSessionStart(session.state.sessionId, {
-                // Strip <codeshell-image> base64 payloads before they reach
-                // <repo>/log/. Reader still sees the marker + byte count, just
-                // not the bytes. Transcript persistence keeps the full payload.
-                task: sanitizeTaskString(task),
-                cwd,
-                model: this.config.llm.model,
-                provider: this.config.llm.provider,
-                permissionMode: runPermissionMode,
-                resumed: resumedFromDisk,
-            });
-            // Session-level hook: fired once per Engine.run() entry, regardless of
-            // cold-start vs resume. Handlers can return `messages` to inject a
-            // <system-reminder> at the head of the conversation (between
-            // userContext and the new user prompt). Used by the built-in
-            // superpowers injector to surface the `using-superpowers` ruleset.
-            const sessionStartHook = await this.emitHook("on_session_start", {
-                sessionId: session.state.sessionId,
+            const hookMessages = await this.runSessionStartHooks({
+                session,
+                task,
                 cwd,
-                resumed: resumedFromDisk,
-                source: resumedFromDisk ? "resume" : "startup",
-            }, options?.signal);
-            // Per-turn hook: fired every time a new user prompt enters the loop.
-            // Equivalent to CC's UserPromptSubmit. Handlers can inject lightweight
-            // reminders that should accompany each user turn (e.g. "skills
-            // available — check before acting").
-            const promptSubmitHook = await this.emitHook("user_prompt_submit", {
-                sessionId: session.state.sessionId,
-                // Pass the text-only portion. Handlers reading the prompt for keyword
-                // detection / classification (e.g. superpowers' "did the user ask
-                // about X?") don't gain anything from megabytes of base64 inlined here,
-                // and silently leaking attachment bytes through hooks is the kind of
-                // exfiltration risk a curious user-installed shell hook shouldn't carry.
-                prompt: taskText,
-                resumed: resumedFromDisk,
-            }, options?.signal);
-            // updatedPrompt: handler rewrote the user's prompt text. Replace the
-            // last user message we just pushed (cold-start: line ~511; resume:
-            // line ~500). Original prompt is in the transcript already — we log
-            // the rewrite so audit chains know a hook touched user input.
-            if (typeof promptSubmitHook.updatedPrompt === "string") {
-                const lastIdx = messages.length - 1;
-                const last = messages[lastIdx];
-                if (last && last.role === "user" && typeof last.content === "string") {
-                    logger.info("hook.updated_prompt", {
-                        sessionId: session.state.sessionId,
-                        originalChars: last.content.length,
-                        updatedChars: promptSubmitHook.updatedPrompt.length,
-                    });
-                    messages[lastIdx] = { role: "user", content: promptSubmitHook.updatedPrompt };
-                }
-            }
-            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)),
+                runPermissionMode,
+                resumedFromDisk,
+                options,
+                taskText,
+                messages,
             });
-            this.lastContextManager = contextManager;
-            const persistedContextAnchor = session.state.contextUsageAnchor;
-            const contextAnchorCompatible = persistedContextAnchor !== undefined &&
-                (persistedContextAnchor.provider === undefined ||
-                    persistedContextAnchor.provider === this.config.llm.provider) &&
-                (persistedContextAnchor.model === undefined ||
-                    persistedContextAnchor.model === this.config.llm.model) &&
-                (persistedContextAnchor.messageCount <= messages.length ||
-                    persistedContextAnchor.estimateAtAnchor !== undefined);
-            if (contextAnchorCompatible) {
-                contextManager.seedActualUsage(persistedContextAnchor);
-            }
-            // Best-effort token estimate of the full prompt so the UI's ctx bar isn't
-            // 0% before the first real usage_update arrives. The authoritative count
-            // comes from `usage.promptTokens` after the first LLM response — this is
-            // just a display-friendly approximation for the first frame, annotated
-            // with source/confidence so consumers don't treat heuristics as truth.
-            //
-            // Only seed once per (process, sid). On subsequent turns the UI already
-            // shows the previous turn's accurate ctx; overwriting it with a fresh
-            // best-effort estimate would make the bar visibly drop on every submit.
             const sid = session.state.sessionId;
-            const needsCtxSeed = !this.ctxSeedSent.has(sid);
-            const ctxSeed = needsCtxSeed
-                ? (() => {
-                    const checked = contextManager.checkLimits(messages);
-                    return {
-                        tokens: checked.tokens,
-                        source: checked.promptTokensSource,
-                        confidence: checked.promptTokensConfidence,
-                    };
-                })()
-                : {
-                    tokens: 0,
-                    source: "heuristic_estimate",
-                    confidence: "low",
-                };
-            if (needsCtxSeed)
-                this.ctxSeedSent.add(sid);
-            // Tell the client the sid *now* instead of waiting for run() to resolve.
-            // The user wants `/sid` to work mid-turn; without this, the client only
-            // learns the sid when the run completes.
-            options?.onStream?.({
-                type: "session_started",
-                sessionId: sid,
-                promptTokens: ctxSeed.tokens,
-                promptTokensSource: ctxSeed.source,
-                promptTokensConfidence: ctxSeed.confidence,
-            });
-            // Replay the last TodoWrite snapshot on resume so the UI's pinned
-            // task panel re-hydrates without the LLM needing to call TodoWrite
-            // again. Scans the resumed transcript newest-first (and tolerates
-            // legacy TaskCreate/Update events for sessions recorded against
-            // the pre-2026-05-24 API). New sessions have no transcript yet so
-            // readLastTodoSnapshot returns null and nothing is emitted.
-            if (options?.sessionId) {
-                const snap = readLastTodoSnapshot(session.transcript.getEvents());
-                if (snap && snap.length > 0) {
-                    latestTodos = snap;
-                    options?.onStream?.({ type: "task_update", tasks: snap });
-                }
-            }
-            // Kick off LLM client creation early (network handshake)
-            const llmClientPromise = createLLMClient(this.config.llm, this.config.clientDefaults);
-            // MCP connection below may keep us from awaiting this promise for a while.
-            // Observe rejection immediately so a fast client-init failure cannot become
-            // an unhandledRejection during that gap; Promise.all still receives the
-            // original promise and routes the same error through the lifecycle catch.
-            void llmClientPromise.catch(() => { });
-            const mode = runPermissionMode;
-            this.activeApprovalRouter = toolCtx.approvalRouter;
-            const { rules: defaultRules, backend: approvalBackend } = this.buildPermissionConfig(mode, cwd, toolCtx.approvalRouter);
-            const permission = new PermissionClassifier(defaultRules, mode, approvalBackend);
-            this.activePermission = permission;
-            // If the backend is the interactive one, wire it for project-scope
-            // persistence: it needs cwd to find settings.local.json, and a callback
-            // to apply newly-saved rules to the live classifier so subsequent calls
-            // in this same session don't re-prompt. Headless/auto backends skip
-            // this — they don't prompt, so there are no project rules to persist.
-            if (approvalBackend instanceof InteractiveApprovalBackend) {
-                approvalBackend.setSessionContext(session.state.sessionId, {
-                    cwd,
-                    onProjectRules: (rules) => {
-                        // Prepend the *full* accumulated list of session-saved project rules
-                        // so user approvals win over defaults and earlier approvals aren't
-                        // dropped when later ones come in.
-                        permission.reconfigure(mode, approvalBackend, [...rules, ...defaultRules]);
-                    },
-                });
-            }
-            const toolExecutor = new ToolExecutor(this.toolRegistry, permission, this.hooks);
-            const investigationGuard = new InvestigationGuard();
-            if (this.config.readOnlySession) {
-                investigationGuard.setPolicy("read-only-review");
-            }
-            else if (this.config.headless) {
-                investigationGuard.setSoftMode(true);
-            }
-            toolExecutor.setInvestigationGuard(investigationGuard);
-            toolExecutor.setTaskGuard(new TaskGuard(() => latestTodos));
-            // Wire abort signal for cascading cancellation + per-Engine ToolContext
-            toolExecutor.setSignal(options?.signal);
-            toolExecutor.setContext(toolCtx);
-            const { disabledSkills, disabledPlugins } = this.readDisabledLists();
-            const promptComposer = new PromptComposer({
+            const { contextManager, llmClientPromise, toolExecutor } = this.wireRunContextAndPermission({
+                session,
+                sid,
+                options,
                 cwd,
-                model: this.config.llm.model,
-                preset: this.preset,
-                customSystemPrompt: this.config.customSystemPrompt,
-                appendSystemPrompt: this.config.appendSystemPrompt,
-                responseLanguage: this.config.responseLanguage,
-                userProfile: this.config.userProfile,
-                instructionOptions: { compatFileNames: compatFileNamesFrom(this.config.instructions) },
-                disabledSkills,
-                disabledPlugins,
-                skillAllowlist: this.config.skillAllowlist,
-                memoriesMaxAgeDays: this.readMemoriesConfig()?.maxAge,
-                goalToolState: {
-                    hasGoal: this.config.isSubAgent !== true &&
-                        (normalizeGoal(options?.goal) !== undefined ||
-                            session.state.activeGoal !== undefined ||
-                            normalizeGoal(this.config.goal) !== undefined),
+                toolCtx,
+                runPermissionMode,
+                messages,
+                getLatestTodos: () => latestTodos,
+                setLatestTodos: (todos) => {
+                    latestTodos = todos;
                 },
             });
-            // Connect MCP servers (if configured and not already connected).
-            // B1: prefer the Runtime-owned MCPManager so all sessions in a
-            // worker share one set of connections. Falling back to a
-            // per-Engine instance keeps the null-runtime path (tests, ad-hoc
-            // scripts) working.
-            const mcpServers = this.config.mcpServers ?? {};
-            if (Object.keys(mcpServers).length > 0 && !this.mcpManager) {
-                if (this.runtime) {
-                    this.mcpManager = this.runtime.mcpPool;
-                }
-                else {
-                    this.mcpManager = new MCPManager(this.toolRegistry);
-                }
-                await this.mcpManager.connectAll(mcpServers, this);
-            }
-            // Parallelize slow initialization:
-            //   1. createLLMClient — network handshake (started earlier)
-            //   2. buildSystemPrompt — includes git status (3 execSync calls)
-            //   3. buildSystemContext — reads environment context
-            // Inject the live available-agent-types listing into the Agent tool's
-            // description. The registry is per-engine (loaded from .code-shell/agents
-            // for this cwd), so it can't live in the static tool def — without this
-            // the model never learns the reusable roles exist and spawns nameless
-            // ad-hoc agents instead (the Core A/B/C incident).
-            // The Agent tool is always available: with configured roles, an omitted
-            // agent_type falls back to one of them (see resolveAgentTypeOverrides); with
-            // no roles configured it runs a true ephemeral agent, so workflows that need
-            // sub-agents (e.g. superpowers) work in any project.
-            // Availability guard (tool-visibility): a gated builtin (WebSearch needs a
-            // search provider, GenerateImage needs an OpenAI provider) is hidden from
-            // the toolDefs the model sees when its credential isn't configured for this
-            // cwd. Recomputed every message, so configuring a key takes effect on the
-            // NEXT message without a restart. Tools with no guard entry are always kept.
-            const guardCwd = toolCtx.cwd;
-            const toolVisibility = {
-                cwd: guardCwd,
-                hasGoal: this.config.isSubAgent !== true &&
-                    (normalizeGoal(options?.goal) !== undefined ||
-                        session.state.activeGoal !== undefined ||
-                        normalizeGoal(this.config.goal) !== undefined),
-                settingsScope: this.config.settingsScope ?? "project",
-            };
-            toolCtx.toolVisibility = toolVisibility;
-            // #7: per-turn project builtin override. The toolRegistry's builtin tool
-            // SET is ctor-frozen (and may be shared via runtime), so a mid-session
-            // project override of a builtin can't rebuild the registry. But the tool
-            // LIST handed to the LLM is assembled fresh every turn, so we apply the
-            // override here: a builtin marked `off` for this cwd is HIDDEN from the
-            // turn's tool list (matching how skills/plugins/agents `off` apply
-            // mid-session via readDisabledLists). `on`/`inherit` keep whatever the
-            // registry already has — we can't re-add a tool the frozen registry omits,
-            // but `on` for a tool already present is a no-op (it stays). This makes a
-            // builtin toggle take effect on the NEXT message, like other capability
-            // kinds, without touching the registry.
-            const builtinOverride = this.readBuiltinOverride(guardCwd);
-            // Turn `off` from a prompt-visibility filter into a real execution gate:
-            // collect the builtin tool names the override marks `off` and hand them to
-            // the executor (via the shared toolCtx the executor already holds a
-            // reference to, set at setContext above) so it rejects a call to a hidden
-            // builtin instead of running it from the still-populated registry.
-            if (builtinOverride) {
-                const registryNames = new Set(this.toolRegistry.getToolDefinitions().map((t) => t.name));
-                const disabledBuiltins = new Set(Object.keys(builtinOverride).filter((name) => builtinOverride[name] === "off" && registryNames.has(name)));
-                toolCtx.disabledBuiltins = disabledBuiltins;
-            }
-            // MCP tool exposure is per-SESSION even though the pool/registry are
-            // worker-shared (B1): a server connected by another project's session
-            // registers its tools into the SHARED registry, and without this filter
-            // they leaked into every session (e.g. chrome-devtools tools showing up
-            // in a project that never enabled the plugin). Keep an MCP tool only when
-            // its server is in THIS session's merged config.mcpServers — which
-            // already folds the project's capabilityOverrides. Gated on the config
-            // being present: engines without one (sub-agents, bare tests) have no
-            // MCP tools in their private registries anyway.
-            const allowedMcpServers = new Set(Object.entries(this.config.mcpServers ?? {})
-                .filter(([, c]) => c.enabled !== false)
-                .map(([n]) => n));
-            toolCtx.allowedMcpServers = allowedMcpServers;
-            const mcpVisible = (toolName) => {
-                const reg = this.toolRegistry.getTool(toolName);
-                return reg?.source !== "mcp" || allowedMcpServers.has(reg?.serverName ?? "");
-            };
-            // Feature-flag visibility: a builtin mapped in TOOL_FEATURE_FLAGS is
-            // hidden when its flag resolves to false (default-on flags only hide when
-            // explicitly disabled, so zero regression out of the box). Read once per
-            // turn so flipping a flag in settings takes effect on the NEXT message,
-            // like the other capability kinds.
-            const featureFlags = this.readFeatureFlags();
-            const allToolDefs = applyBuiltinOverrideVisibility(this.toolRegistry.getToolDefinitions(), builtinOverride)
-                .filter((t) => mcpVisible(t.name))
-                .filter((t) => {
-                const guard = BUILTIN_TOOL_GUARDS.get(t.name);
-                return guard ? guard(toolVisibility) : true;
-            })
-                .filter((t) => {
-                const flag = TOOL_FEATURE_FLAGS.get(t.name);
-                return flag ? isFeatureEnabled(featureFlags, flag) : true;
-            })
-                // Dynamic per-engine bits the static defs can't carry: the Agent tool's
-                // agent_type enum + listing, and the image/video provider names. See
-                // applyDynamicToolDef — forwarding only the Agent description (dropping
-                // its rebuilt inputSchema) used to strip the agent_type enum, so the
-                // model omitted agent_type and configured roles never applied.
-                .map((t) => applyDynamicToolDef(t, toolCtx.agentDefinitions, guardCwd));
-            // In plan mode, only expose read-only/planning tools so the model won't
-            // attempt writes. Shared with executor.ts's execution gate via
-            // PLAN_MODE_ALLOWED_TOOLS so what the model SEES and what the executor
-            // RUNS can't drift apart. (Bash is in the set; the executor additionally
-            // gates Bash to read-only commands at call time.)
-            const toolDefs = runPlanMode
-                ? allToolDefs.filter((t) => PLAN_MODE_ALLOWED_TOOLS.has(t.name))
-                : allToolDefs;
-            const [llmClient, fullSystemPrompt, dynamicContextMsg] = await Promise.all([
+            const { promptComposer, toolDefs } = await this.wireRunTooling({
+                options,
+                session,
+                cwd,
+                toolCtx,
+                profile,
+                profileParams,
+                runWorkspaceProfile,
+                profileMemoryDir,
+                sessionProfileOverrides,
+                runPlanMode,
+            });
+            const { llmClient, fullSystemPrompt, dynamicContextMsg, userContextMsg } = await this.assembleRunPrompts({
+                session,
+                messages,
+                hookMessages,
+                promptComposer,
+                toolDefs,
                 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.buildDynamicContextMessage(),
-            ]);
-            // Prepend userContext (CLAUDE.md) as first message (sync, fast)
-            const userContextMsg = promptComposer.buildUserContextMessage();
-            if (userContextMsg) {
-                messages.unshift(userContextMsg);
-            }
-            // Inject hook-supplied reminders just before the most recent user task.
-            // Combined into one <system-reminder> block so a noisy handler chain
-            // doesn't turn into 3+ separate user turns in the API request.
-            const lifecycleReminder = wrapHookMessages([
-                ...(sessionStartHook.messages ?? []),
-                ...(promptSubmitHook.messages ?? []),
-            ]);
-            if (lifecycleReminder) {
-                // messages[length - 1] is the user task we just pushed above. Insert
-                // the reminder immediately before it so the model reads: CLAUDE.md →
-                // 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
-            // Uses a lightweight call without tools
-            contextManager.setTranscriptPath(session.transcript.getFilePath());
-            // Re-derive frozen persistence decisions from the messages we just
-            // loaded. Skipped on cold start (messages == [userContextMsg] only).
-            // Critical for resume — otherwise a result that was persisted last
-            // run would be evaluated fresh and might get a different replacement
-            // string than the one already in the message, breaking idempotency.
-            contextManager.initReplacementStateFromMessages(messages);
-            // Two summarizers with DIFFERENT quality needs:
-            //
+                contextManager,
+                profile,
+                profileParams,
+            });
             // 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
@@ -1556,869 +1160,1061 @@ export class Engine {
             // Auto-compaction runs inside TurnLoop.manageAsync(), after the loop has
             // initialized its run-scoped Goal tracker. The closure is wired before
             // construction but cannot execute until turnLoop.run() starts.
-            let turnLoop;
-            let autoCompactionGoalTermination;
-            let externalRunUsage = {
-                promptTokens: 0,
-                completionTokens: 0,
-                totalTokens: 0,
-                cacheReadTokens: 0,
-                cacheCreationTokens: 0,
-            };
-            let runAccountingFinalized = false;
-            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;
-            };
-            const recordExternalBilledUsage = (usage) => {
-                externalRunUsage = addTokenUsage(externalRunUsage, usage);
-                const cumulative = recordCumulativeUsage(usage);
-                autoCompactionGoalTermination = turnLoop.recordGoalJudgeUsage(usage);
-                if (runAccountingFinalized) {
-                    try {
-                        const latest = this.sessionManager.resume(sid).state;
-                        const lateCumulative = addCumulativeUsage(latest, usage);
-                        this.sessionManager.updateSessionState(sid, {
-                            tokenUsage: addTokenUsage(latest.tokenUsage, usage),
-                            ...lateCumulative,
-                            ...(this.config.costStore
-                                ? {
-                                    costState: this.config.costStore.serialize(),
-                                }
-                                : {}),
-                        });
-                    }
-                    catch (err) {
-                        logger.warn("engine.late_usage_persist_failed", {
-                            sessionId: sid,
-                            error: err instanceof Error ? err.message : String(err),
-                        });
-                    }
-                }
-                return cumulative;
-            };
-            contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordExternalBilledUsage));
-            // Create components (requires resolved llmClient).
-            const modelFacade = new ModelFacade(llmClient, session.transcript);
-            const getRunUsage = () => {
-                const visible = modelFacade.getUsage();
-                return {
-                    ...visible,
-                    totalPromptTokens: visible.totalPromptTokens + externalRunUsage.promptTokens,
-                    totalCompletionTokens: visible.totalCompletionTokens + externalRunUsage.completionTokens,
-                    totalTokens: visible.totalTokens + externalRunUsage.totalTokens,
-                    totalCacheReadTokens: visible.totalCacheReadTokens + (externalRunUsage.cacheReadTokens ?? 0),
-                    totalCacheCreationTokens: visible.totalCacheCreationTokens + (externalRunUsage.cacheCreationTokens ?? 0),
-                };
-            };
-            const callPrimaryModel = modelFacade.call.bind(modelFacade);
-            modelFacade.call = async (...args) => {
-                // A primary-model summary may itself exhaust the Goal budget. Do not
-                // issue the main turn request after that billed sub-call; return control
-                // to TurnLoop, whose existing post-response guard emits and persists the
-                // canonical goal_budget_exhausted termination.
-                if (autoCompactionGoalTermination) {
-                    return {
-                        text: "",
-                        toolCalls: [],
-                        stopReason: "stop",
-                    };
-                }
-                return callPrimaryModel(...args);
-            };
-            // 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 = getRunUsage();
-                return usage.totalCompletionTokens;
-            };
-            // Wire summarize for tool use summaries (uses lightweight call). Keep the
-            // request out of the foreground tracker while billing and reporting it to
-            // the owning session/Goal budget.
-            modelFacade.summarize = async (sysPrompt, userMsg) => {
-                const resp = await auxSummaryClient.createMessage({
-                    systemPrompt: sysPrompt,
-                    messages: [{ role: "user", content: userMsg }],
-                    tools: [],
-                    maxTokens: 256,
-                    billingEnabled: true,
-                    requestVisible: false,
-                    // Auxiliary call — see contextManager.setSummarizeFn above.
-                    reasoning: { mode: "off" },
-                });
-                if (resp.usage)
-                    recordExternalBilledUsage(resp.usage);
-                logger.debug("summarize.call", {
-                    sysPromptLen: sysPrompt.length,
-                    userMsgLen: userMsg.length,
-                    userMsgPreview: userMsg.slice(0, 300),
-                    completionLen: resp.text.length,
-                    completionPreview: resp.text.slice(0, 300),
-                    stopReason: resp.stopReason,
-                    promptTokens: resp.usage?.promptTokens,
-                    completionTokens: resp.usage?.completionTokens,
-                });
-                return resp.text;
-            };
-            // 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);
-            // 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) {
-                    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 {};
-            };
-            this.hooks.register("on_tool_start", fileHistoryHandler, 100, "file_history_backup");
-            // Hook: agent start
-            await this.emitHook("on_agent_start", {
-                sessionId: session.state.sessionId,
+            // Assigned after the callbacks that close over it are constructed; they
+            // cannot run until turnLoop.run(), so definite assignment is intentional.
+            const { turnLoop, applyGoalTermination, goalHookHandler, fileHistoryHook, getRunUsage, recordExternalBilledUsage, accounting, usageBaseline, } = await this.wireRunLoop({
+                session,
+                sid,
                 task,
-                model: this.config.llm.model,
-            }, options?.signal);
-            // Goal mode: register a GoalStopHook for the lifetime of THIS run so the
-            // turn loop keeps going until the session model judges the goal met.
-            // Registered per-run (and cleared in `finally`) so a later goal-less
-            // send doesn't inherit a stale goal. The judge runs on the primary
-            // session client; auxSummaryClient remains dedicated to low-consequence
-            // summaries/titles and retains defaults.auxText routing/fallback behavior.
-            // Normalize the raw goal (string | GoalConfig) once at the run boundary;
-            // everything inward uses the GoalConfig. normalizeGoal() returns undefined
-            // when there's effectively no goal (empty objective).
-            //
-            // PERSISTENT GOAL (CC /goal style): a goal set on one send survives across
-            // later sends and manual interrupts until met or cleared. Goal completion
-            // is a high-consequence decision, so V1 routes it to the primary session
-            // client, which is the model expected to interpret the supplied execution
-            // evidence. defaults.auxText remains in force for summaries, titles and
-            // other auxiliary work through auxSummaryClient.
-            // 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);
-            let storedGoal = this.config.isSubAgent !== true ? session.state.activeGoal : undefined;
-            // Defense in depth: a stale whole-state writer may have restored the
-            // activeGoal field after this exact goal instance was force-terminated.
-            // Refuse to arm it and converge the live bundle before hook registration.
-            if (storedGoal && isSameGoalInstance(storedGoal, session.state.goalTerminal)) {
-                session.state.activeGoal = undefined;
-                storedGoal = undefined;
-                this.sessionManager.saveState(session.state);
-            }
-            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.
-                const resolvedSetAt = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
-                // A user explicitly re-starting the same objective creates a new goal
-                // instance. Avoid a same-millisecond collision with its old tombstone.
-                explicitGoal.setAtMs =
-                    session.state.goalTerminal?.objective === explicitGoal.objective &&
-                        session.state.goalTerminal.setAtMs === resolvedSetAt
-                        ? resolvedSetAt + 1
-                        : resolvedSetAt;
-                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);
-            // Snapshot the persisted goal identity owned by THIS run. Terminal
-            // cleanup compares against this immutable copy so an old run cannot
-            // delete a replacement goal installed while it was finishing.
-            const persistedRunGoal = normalizedGoal && isSameGoalInstance(session.state.activeGoal, normalizedGoal)
-                ? { ...normalizedGoal }
-                : undefined;
-            let goalHookHandler = null;
-            let goalJudgeContext;
-            if (normalizedGoal && this.config.isSubAgent !== true) {
-                goalHookHandler = createGoalStopHook({
-                    goal: normalizedGoal,
-                    llm: llmClient,
-                    log: logger,
-                    getJudgeContext: () => goalJudgeContext,
-                    onJudgeUsage: (usage) => {
-                        // The provider records this request into llmClient.getUsage() and the
-                        // process-wide CostTracker. This separate callback feeds the session
-                        // cumulative cache counters and the live Goal hard-budget tracker.
-                        if (usage)
-                            recordCumulativeUsage(usage);
-                        return turnLoop.recordGoalJudgeUsage(usage);
-                    },
-                    // 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 (persistedRunGoal &&
-                            isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
-                            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) => isSameGoalInstance(this.sessionManager.readActiveGoal(sid), normalizedGoal),
-                });
-                this.hooks.register("on_stop", goalHookHandler, 0, "goal-stop");
-                // Expose for clearGoal() mid-run. Already guarded by isSubAgent above.
-                this.activeGoalHook = goalHookHandler;
-            }
-            // Surface compaction events to the UI so the user knows when context was trimmed.
-            // Buffer the most recent event so TurnLoop can drain it and emit the
-            // post_compact hook on the next turn (ContextManager itself doesn't
-            // know about HookRegistry — the buffer is the seam).
-            let pendingCompactInfo = null;
-            contextManager.setOnCompact((info) => {
-                pendingCompactInfo = info;
-                options?.onStream?.({ type: "context_compact", ...info });
-            });
-            // Run turn loop
-            turnLoop = new TurnLoop({
-                model: modelFacade,
+                cwd,
+                options,
+                toolCtx,
                 toolExecutor,
                 contextManager,
-                hooks: this.hooks,
-                transcript: session.transcript,
-                systemPrompt: fullSystemPrompt,
-                tools: toolDefs,
-                sessionId: sid,
-                isSubAgent: this.config.isSubAgent === true,
-                consumePendingCompactInfo: () => {
-                    const info = pendingCompactInfo;
-                    pendingCompactInfo = null;
-                    return info;
-                },
-                consumeSteer: (source) => this.consumeSteer(sid, source),
-                restoreSteer: (items) => this.restoreSteer(sid, items),
-                buildSteerUserMessageContent: async (item) => {
-                    const steerImageInput = await prepareRunImageInput({
-                        task: item.text,
-                        cwd,
-                        llm: this.config.llm,
-                        sessionId: sid,
-                        attachments: item.attachments,
-                    });
-                    if (!steerImageInput.ok) {
-                        throw new Error(steerImageInput.result.text);
-                    }
-                    return buildRunUserMessageContent(steerImageInput.parsedTask, cwd, steerImageInput.taskText);
-                },
-                claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
-                releaseClientMessageId: (clientMessageId) => {
-                    claimedClientMessageIds.delete(clientMessageId);
-                },
-                setOriginClientMessageId: (clientMessageId) => {
-                    toolCtx.originClientMessageId = clientMessageId;
-                },
-                recordCumulativeUsage,
-                recordCacheReadDiagnostics: (usage) => {
-                    this.recordCacheReadDiagnostics(sid, usage);
-                },
-                recordContextUsageAnchor: (anchor) => {
-                    session.state.contextUsageAnchor = {
-                        ...anchor,
-                        provider: this.config.llm.provider,
-                        model: this.config.llm.model,
-                    };
-                },
-                // Clear the persisted goal for a self-reported completion / confirmed
-                // cancel. Clears the in-RAM session's activeGoal (so THIS run's later
-                // turns don't re-arm) AND persists it, and drops the in-flight stop
-                // hook so nothing re-blocks the stop we're about to return.
-                clearPersistedGoal: () => {
-                    if (persistedRunGoal &&
-                        isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
-                        session.state.activeGoal = undefined;
-                        this.sessionManager.saveState(session.state);
-                    }
-                    if (goalHookHandler) {
-                        this.hooks.unregister("on_stop", goalHookHandler);
-                        if (this.activeGoalHook === goalHookHandler)
-                            this.activeGoalHook = null;
-                    }
-                },
-                updateGoalJudgeContext: (context) => {
-                    goalJudgeContext = context;
-                },
-                ctxOverheadStore: {
-                    get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
-                    set: (s, n) => {
-                        this.ctxOverheadBySid.set(s, n);
-                    },
-                },
-            }, {
-                // 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,
-                volatileContextMessages: dynamicContextMsg ? [dynamicContextMsg] : 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,
-                // Heartbeat: flush turnCount + tokens to state.json after every turn
-                // so external observers (other CLI processes, /sid, the session list)
-                // see live progress instead of a stale snapshot from the last
-                // completed run.
-                onTurnBoundary: (turnCount) => {
-                    session.state.turnCount = turnCount;
-                    // baseline + this run's running total (idempotent per boundary,
-                    // accumulates across runs; carries cacheRead/cacheCreation too).
-                    session.state.tokenUsage = foldRunUsage(usageBaseline, getRunUsage());
-                    // 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,
-                        promptTokensSource: "session_cumulative",
-                        promptTokensConfidence: "high",
-                        cumulativePromptTokens: cumulative.cumulativePromptTokens,
-                        cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
-                        cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
-                        ...(cumulativeHitRate !== undefined
-                            ? { cumulativeCacheHitRate: cumulativeHitRate }
-                            : {}),
-                        sessionPromptTokens: cumulative.cumulativePromptTokens,
-                        sessionCacheReadTokens: cumulative.cumulativeCacheReadTokens,
-                        sessionCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
-                    });
-                    if (this.config.costStore) {
-                        session.state.costState = this.config.costStore.serialize();
-                    }
-                    this.sessionManager.saveState(session.state);
-                },
+                llmClient,
+                auxSummaryClient,
+                fullSystemPrompt,
+                toolDefs,
+                claimClientMessageId,
+                releaseClientMessageId,
+                freshImageMessage,
+                dynamicContextMsg,
             });
-            toolCtx.recordBilledUsage = recordExternalBilledUsage;
-            // 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;
-            const applyGoalTermination = (termination) => {
-                if (!termination || !persistedRunGoal)
-                    return;
-                // Judge prompt overflow ends only this run. The objective is unfinished
-                // and may be resumed after the user reduces fixed judge context, so it
-                // must not get a terminal tombstone or be cleared from activeGoal.
-                if (termination === "judge_prompt_too_large")
-                    return;
-                // Record the terminal identity even when a newer goal has already
-                // replaced it. Only clear activeGoal when it is still the run's goal.
-                session.state.goalTerminal = {
-                    objective: persistedRunGoal.objective,
-                    setAtMs: persistedRunGoal.setAtMs,
-                    reason: termination,
-                    terminatedAtMs: Date.now(),
-                };
-                if (isSameGoalInstance(session.state.activeGoal, persistedRunGoal)) {
-                    session.state.activeGoal = undefined;
-                }
-                this.sessionManager.saveState(session.state);
-                if (goalHookHandler) {
-                    this.hooks.unregister("on_stop", goalHookHandler);
-                    if (this.activeGoalHook === goalHookHandler)
-                        this.activeGoalHook = null;
-                }
-            };
             let result;
             let firstGoalTermination;
             try {
-                result = await turnLoop.run(messages);
-                firstGoalTermination = result.goalTermination;
-                applyGoalTermination(result.goalTermination);
-                // ── Headless: drain background sub-agents before resolving ───────
-                // Unified background-work model (2026-06-17): the engine NO LONGER parks
-                // every run waiting on background work. Background work (sub-agents,
-                // video polls, shells) ends the turn, yields, and is picked up later by
-                // the server's notification-wakeup path (maybeWakeIdleSession). The
-                // INTERACTIVE path relies on that wakeup + a run-boundary re-check.
-                //
-                // HEADLESS is the exception: a one-shot `engine.run` whose caller takes
-                // `result.text` as THE answer (automation / SDK) has no later turn to
-                // pick up a wakeup — so it must wait, before resolving, until its own
-                // background SUB-AGENTS finish and summarize. Only sub-agents (their
-                // summary IS part of this run's result), NOT shells (a dev server never
-                // exits → would hang headless forever) and NOT video (a long render the
-                // one-shot run shouldn't block on). This replaces the old for(;;) park
-                // (s-mpvf4rsj-bb6e4639 invariant) for the headless case only.
-                const sid = session.state.sessionId;
-                const isTopLevel = this.config.isSubAgent !== true;
-                if (isTopLevel && this.isHeadless()) {
-                    let aborted = options?.signal?.aborted === true;
-                    // Loop: a summarize turn can spawn a NEW background sub-agent; keep
-                    // draining + summarizing until none remain. turnCount accumulates, so
-                    // the turn-loop's maxTurns still bounds runaway re-summarization.
-                    for (;;) {
-                        while (!aborted && asyncAgentRegistry.hasRunningForSession(sid)) {
-                            aborted = await this.waitForBackgroundAgentChange(sid, options?.signal);
-                        }
-                        let pending = notificationQueue.drainAll(sid);
-                        if (aborted && pending.length === 0) {
-                            // Abort race: an agent calls markCompleted (registry notify) and only
-                            // THEN enqueue (queue notify) as two separate statements. If the abort
-                            // fired before that agent's completion `.then` ran, the while above
-                            // exited on `aborted`, this drainAll caught nothing, and a naive
-                            // `break` here would drop the agent's output. Give still-settling
-                            // agents a bounded window to finish enqueuing, then drain once more.
-                            // Each wait is timeout-bounded so a genuinely stuck (never-completing)
-                            // agent can't hang abort cleanup forever — we'd rather lose nothing in
-                            // the common case and not hang in the pathological one.
-                            for (let i = 0; i < 20 && asyncAgentRegistry.hasRunningForSession(sid); i++) {
-                                const changed = await this.waitForBackgroundAgentChangeOrTimeout(sid, 25);
-                                if (!changed)
-                                    break; // timed out with no state change → stop waiting
-                            }
-                            pending = notificationQueue.drainAll(sid);
-                            if (pending.length === 0)
-                                break;
-                        }
-                        else if (pending.length === 0) {
-                            break;
-                        }
-                        const injected = {
-                            role: "user",
-                            content: `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`,
-                        };
-                        if (aborted || firstGoalTermination) {
-                            // Mark injected: a synthetic notification, not the user's own input —
-                            // the disk reader drops it on replay so no phantom user bubble.
-                            // A goal termination is also a hard boundary: retain the notification
-                            // for recovery, but never re-enter TurnLoop (which would reset its
-                            // run-scoped goal budget tracker and could overwrite the first reason).
-                            session.transcript.appendMessage(injected.role, injected.content, { injected: true });
-                            result = { ...result, messages: [...result.messages, injected] };
-                            break;
-                        }
-                        result = await turnLoop.run([...result.messages, injected]);
-                        firstGoalTermination ??= result.goalTermination;
-                        applyGoalTermination(result.goalTermination);
-                    }
-                }
+                ({ result, firstGoalTermination } = await this.runTurnLoopWithHeadlessDrain({
+                    turnLoop,
+                    messages,
+                    applyGoalTermination,
+                    session,
+                    options,
+                }));
             }
             finally {
                 // Run-scoped: drop the GoalStopHook so a later goal-less send on this
                 // long-lived engine doesn't keep blocking stops.
                 if (goalHookHandler)
                     this.hooks.unregister("on_stop", goalHookHandler);
-                if (this.activeGoalHook === goalHookHandler)
+                if (this.activeGoalHook === goalHookHandler) {
                     this.activeGoalHook = null;
+                    this.activeGoalHookAttached = false;
+                    this.activeRuntimeGoal = null;
+                    this.activePersistedRunGoal = 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);
+                fileHistoryHook.dispose();
             }
-            this.lastMessages = result.messages;
-            const cachedMessages = this.stripInjectedContextMessages(result.messages, userContextMsg, dynamicContextMsg);
-            this.compactedMessagesBySession.set(session.state.sessionId, cachedMessages);
-            logger.info("engine.done", {
-                sessionId: session.state.sessionId,
-                reason: result.reason,
-                turns: turnLoop.currentTurn,
-                tokens: getRunUsage().totalTokens,
-            });
-            recordSessionEnd(session.state.sessionId, {
-                reason: result.reason,
-                turns: turnLoop.currentTurn,
-                cost: getRunUsage(),
-            });
-            // Session-level hook: fired symmetrically with on_session_start once
-            // the turn loop has resolved (completion, error, or abort). Handlers
-            // are notify-only — any returned messages are dropped because the run
-            // is already over and there's no next turn to inject into.
-            await this.emitHook("on_session_end", {
-                sessionId: session.state.sessionId,
-                reason: result.reason,
+            const finalized = await this.finalizeRun({
+                session,
+                result,
+                firstGoalTermination,
                 turnCount: turnLoop.currentTurn,
-            }, options?.signal);
-            // Fire-and-forget memory pipeline: extract durable memories from the
-            // transcript, save a session summary, and conditionally trigger
-            // auto-dream consolidation. Doesn't block the Engine result.
-            void this.runMemoryPipeline(session.transcript, session.state.sessionId, cwd, llmClient, recordExternalBilledUsage);
-            // Fire-and-forget session title generation — only after the FIRST turn.
-            // Reuses the already-resolved auxSummaryClient (aux model, cheap). Best-
-            // effort: failures never touch the run result. The renderer writes the
-            // title into the sidebar on receipt of the session_title stream event.
-            {
-                const messageEvents = session.transcript.getEvents("message");
-                const userMsgEvents = messageEvents.filter((e) => e.data.role === "user");
-                const userMsgCount = userMsgEvents.length;
-                const onStream = options?.onStream;
-                if (userMsgCount === 1 && onStream && result.text) {
-                    const sessionId = session.state.sessionId;
-                    const rawContent = userMsgEvents[0]?.data?.content;
-                    const firstUserText = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent ?? "");
-                    void buildSessionTitle(auxSummaryClient, firstUserText, result.text, recordExternalBilledUsage)
-                        .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. Read the latest persisted state at callback time and
-                            // merge only title; the completed run's session.state snapshot
-                            // may already be stale after later serial session updates.
-                            this.sessionManager.updateSessionState(sessionId, { title });
-                            onStream({
-                                type: "session_title",
-                                sessionId,
-                                title,
-                            });
-                        }
-                    })
-                        .catch(() => { });
-                }
-            }
-            // Update session state. Persist the raw terminal reason as the status so
-            // callers can distinguish user-cancelled (aborted_streaming) from real
-            // failures (model_error, prompt_too_long, ...) — previously every
-            // non-completed outcome collapsed to "errored", which threw away the
-            // distinction and misled anyone reading state.json.
-            if (session.transcript.flushFailed()) {
-                const failure = session.transcript.getFlushFailure();
-                logger.error("engine.transcript_persistence_failed", {
-                    sessionId: session.state.sessionId,
-                    terminalReason: result.reason,
-                    degraded: true,
-                    ...failure,
-                });
-            }
-            session.state.turnCount = turnLoop.currentTurn;
-            session.state.status = result.reason;
-            // Session-cumulative (baseline + this run) for persistence...
-            const usage = getRunUsage();
-            session.state.tokenUsage = foldRunUsage(usageBaseline, usage);
-            if (this.config.costStore) {
-                session.state.costState = this.config.costStore.serialize();
+                getRunUsage,
+                usageBaseline,
+                userContextMsg,
+                dynamicContextMsg,
+                options,
+                cwd,
+                llmClient,
+                auxSummaryClient,
+                recordExternalBilledUsage,
+                accounting,
+                profile,
+                getProfileReportedResults: () => profileReportedResults,
+            });
+            if (options?.clientMessageId) {
+                this.appendClientRunReceipt(session, options.clientMessageId, finalized);
             }
-            // runInProgress excludes another whole-state writer only on this Engine
-            // instance. A different Engine using the same sessionId can still race
-            // this saveState (including an old run's abort cleanup vs a replacement
-            // Engine); cross-instance/process session serialization is a separate finding.
-            this.sessionManager.saveState(session.state);
-            runAccountingFinalized = true;
-            // Hook: agent end
-            await this.emitHook("on_agent_end", {
-                sessionId: session.state.sessionId,
-                reason: result.reason,
-                turnCount: turnLoop.currentTurn,
-            }, options?.signal);
-            // Emit completion
-            options?.onStream?.({ type: "turn_complete", reason: result.reason });
-            return {
-                text: result.text,
-                reason: result.reason,
-                goalTermination: firstGoalTermination,
-                sessionId: session.state.sessionId,
-                turnCount: turnLoop.currentTurn,
-                usage: {
-                    promptTokens: usage.totalPromptTokens,
-                    completionTokens: usage.totalCompletionTokens,
-                    totalTokens: usage.totalTokens,
-                    cacheReadTokens: usage.totalCacheReadTokens,
-                    cacheCreationTokens: usage.totalCacheCreationTokens,
-                },
-            };
+            return finalized;
         });
         return Promise.resolve(sessionRun).catch((err) => {
-            // The session is already persisted as active before runWithSid starts.
-            // Initialization failures (client creation, MCP connection, prompt/hooks)
-            // therefore need the same terminal lifecycle treatment as turn-loop errors.
-            const error = formatFriendlyError(err);
-            session.state.status = "model_error";
-            this.sessionManager.saveState(session.state);
-            session.transcript.appendError(error, { phase: "initialization" });
-            logger.error("engine.run_lifecycle_failed", {
-                sessionId: session.state.sessionId,
-                error: err instanceof Error ? err.message : String(err),
-            });
-            recordSessionEnd(session.state.sessionId, {
-                reason: "model_error",
-                turns: session.state.turnCount,
+            const failed = buildRunFailureResult({
+                err,
+                session,
+                options,
+                persistFinalRunState: (state) => this.persistFinalRunState(state),
             });
-            options?.onStream?.({ type: "error", error });
-            options?.onStream?.({ type: "turn_complete", reason: "model_error" });
-            const usage = session.state.tokenUsage;
-            return {
-                text: `ERROR: ${error}`,
-                reason: "model_error",
-                sessionId: session.state.sessionId,
-                turnCount: session.state.turnCount,
-                usage: {
-                    promptTokens: usage.promptTokens ?? 0,
-                    completionTokens: usage.completionTokens ?? 0,
-                    totalTokens: usage.totalTokens ?? 0,
-                    cacheReadTokens: usage.cacheReadTokens ?? 0,
-                    cacheCreationTokens: usage.cacheCreationTokens ?? 0,
-                },
-            };
+            if (options?.clientMessageId) {
+                this.appendClientRunReceipt(session, options.clientMessageId, failed);
+            }
+            return failed;
         });
     }
+    /** A receipt write failure must not turn an already finalized model result
+     * into a second synthetic failure (or reject the Engine.run contract). */
+    appendClientRunReceipt(session, clientMessageId, result) {
+        try {
+            session.transcript.appendRunResult(clientMessageId, result);
+        }
+        catch (error) {
+            logger.warn("engine.client_message.receipt_persist_failed", {
+                sessionId: session.state.sessionId,
+                clientMessageId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     /**
-     * Run the end-of-session memory pipeline as a fire-and-forget background
-     * task. Extracts durable memories from the transcript, saves a session
-     * summary, and conditionally triggers auto-dream consolidation.
-     */
-    /**
-     * Resolve the LLM client for background/auxiliary work (memory extraction,
-     * auto-dream). When settings.defaults.auxText names a valid pool model, build
-     * (and cache) a dedicated client for it so per-turn book-keeping runs on a cheap
-     * fast model instead of the expensive primary. Falls back to `fallback` (the
-     * active run's client) when unset, unknown, or on any build failure — aux
-     * work is best-effort and must never break a run.
+     * Terminal success path: forward to {@link finalizeRunSuccess} with the
+     * engine-bound persistence / memory / hook closures filled in. Extracted from
+     * the {@link runExclusive} skeleton so the terminal-state assembly reads as a
+     * single call; behavior is unchanged.
      */
+    finalizeRun(args) {
+        const { session, result, firstGoalTermination, turnCount, getRunUsage, usageBaseline, userContextMsg, dynamicContextMsg, options, cwd, llmClient, auxSummaryClient, recordExternalBilledUsage, accounting, profile, getProfileReportedResults, } = args;
+        return finalizeRunSuccess({
+            session,
+            result,
+            firstGoalTermination,
+            turnCount,
+            getRunUsage,
+            usageBaseline,
+            userContextMsg,
+            dynamicContextMsg,
+            setCompactedMessages: (s, msgs) => this.compactedMessagesBySession.set(s, msgs),
+            setLastMessages: (msgs) => {
+                this.lastMessages = msgs;
+            },
+            options,
+            emitHook: (event, payload, signal) => this.emitHook(event, payload, signal),
+            cwd,
+            llmClient,
+            auxSummaryClient,
+            recordExternalBilledUsage,
+            runMemoryPipeline: (transcript, sessionId, runCwd, client, record) => this.runMemoryPipeline(transcript, sessionId, runCwd, client, record),
+            updatePersistedSessionState: (s, patch) => this.updatePersistedSessionState(s, patch),
+            persistFinalRunState: (state) => this.persistFinalRunState(state),
+            markRunAccountingFinalized: () => accounting.markRunAccountingFinalized(),
+            costStoreSerialize: this.config.costStore
+                ? () => this.config.costStore.serialize()
+                : undefined,
+            profile,
+            getProfileReportedResults,
+        });
+    }
     /**
-     * Build the SummarizeFn used for context compaction. Extracted so both the
-     * run path and forceCompact share one definition of the summarization call.
+     * Build the stream callback that wraps the caller's `onStream`: it snapshots
+     * TodoWrite `task_update` events for TaskGuard and persists `goal_progress`
+     * events to the transcript before delegating. Extracted verbatim from the
+     * {@link runExclusive} skeleton; the todo buffer and (not-yet-open) session
+     * are reached through the `setLatestTodos` / `getSession` accessors.
      */
-    buildSummarizeFn(auxSummaryClient, recordCumulativeUsage) {
-        return async (prompt, signal) => {
-            const summaryResponse = await auxSummaryClient.createMessage({
-                systemPrompt: "You are a conversation summarizer. Be concise and factual.",
-                messages: [{ role: "user", content: prompt }],
-                tools: [],
-                maxTokens: 1024,
-                billingEnabled: true,
-                requestVisible: false,
-                // 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" },
-                signal,
-            });
-            if (summaryResponse.usage) {
-                recordCumulativeUsage?.(summaryResponse.usage);
+    buildWrappedOnStream(args) {
+        const { userOnStream, getSession, setLatestTodos } = args;
+        return (event) => {
+            if (event.type === "task_update") {
+                setLatestTodos(event.tasks);
+            }
+            // Persist goal progress so replay/history shows how many rounds the
+            // goal ran. Display-only — toMessages() ignores this type, so it never
+            // re-enters the LLM context.
+            if (event.type === "goal_progress") {
+                getSession().transcript.append("goal_progress", {
+                    ...(event.goalId ? { goalId: event.goalId } : {}),
+                    status: event.status,
+                    round: event.round,
+                    ...(event.gaps ? { gaps: event.gaps } : {}),
+                });
             }
-            return summaryResponse.text;
+            userOnStream?.(event);
         };
     }
-    async resolveAuxClient(fallback) {
-        let auxKey;
-        try {
-            // Re-read from disk: settings may have been changed by the desktop
-            // (a separate process) since this worker last cached them. This runs
-            // once per run on the post-run background path, so the cost is fine.
-            const sm = this.getSettingsManager();
-            sm.invalidate();
-            // Unified store's defaults.auxText (a connection id = pool key) selects
-            // the aux model; resolveAuxKey returns it (or undefined).
-            auxKey = resolveAuxKey(sm.get());
-        }
-        catch {
-            return fallback;
-        }
-        if (!auxKey)
-            return fallback;
-        // Don't spin up a second client when the aux key resolves to the SAME
-        // client config as this engine's active model. Compare FULL LLM IDENTITY
-        // (model + reasoning + maxTokens + baseUrl + provider/providerKind) against
-        // this engine's own per-session config.llm — NOT a separately-tracked active
-        // key, and NOT just the model NAME. Two distinct pool keys can share the same
-        // `model` string yet differ in reasoning/maxOutputTokens/baseUrl/apiKey/
-        // providerKey; de-duping on the name alone would wrongly route the user's
-        // chosen aux entry onto the primary's config. config.llm is isolated per
-        // session and always set for a real run, so this is correct even for desktop
-        // worker sessions built with a shared runtime (which never explicitly
-        // switchModel, so the old activeModelKey field was undefined and defeated the
-        // de-dup), AND immune to another session mutating the shared pool's activeKey.
-        const entry = this.modelPool.get(auxKey);
-        if (entry && sameLlmIdentity(this.modelPool.toLLMConfig(entry), this.config.llm)) {
-            return fallback;
-        }
-        if (this.auxClientCache?.key === auxKey)
-            return this.auxClientCache.client;
-        if (!entry) {
-            logger.warn("engine.aux_model_missing", { auxModelKey: auxKey });
-            return fallback;
-        }
-        try {
-            const client = await createLLMClient(this.modelPool.toLLMConfig(entry), this.config.clientDefaults);
-            this.auxClientCache = { key: auxKey, client };
-            return client;
-        }
-        catch (err) {
-            logger.warn("engine.aux_model_build_failed", {
-                auxModelKey: auxKey,
-                error: err.message,
+    /**
+     * Run the turn loop once, apply its goal termination, and — for a top-level
+     * headless run only — drain background sub-agents before resolving. Extracted
+     * verbatim from the body of the {@link runExclusive} try block; the cleanup
+     * `finally` stays in the skeleton so the run-scoped hook/loop teardown is
+     * guaranteed regardless of how this method returns or throws.
+     */
+    async runTurnLoopWithHeadlessDrain(args) {
+        const { turnLoop, messages, applyGoalTermination, session, options } = args;
+        let result = await turnLoop.run(messages);
+        let firstGoalTermination = result.goalTermination;
+        applyGoalTermination(result.goalTermination, result.goalTerminationRound);
+        // ── Headless: drain background sub-agents before resolving ───────
+        // Unified background-work model (2026-06-17): the engine NO LONGER parks
+        // every run waiting on background work. Background work (sub-agents,
+        // video polls, shells) ends the turn, yields, and is picked up later by
+        // the server's notification-wakeup path (maybeWakeIdleSession). The
+        // INTERACTIVE path relies on that wakeup + a run-boundary re-check.
+        //
+        // HEADLESS is the exception: a one-shot `engine.run` whose caller takes
+        // `result.text` as THE answer (automation / SDK) has no later turn to
+        // pick up a wakeup — so it must wait, before resolving, until its own
+        // background SUB-AGENTS finish and summarize. Only sub-agents (their
+        // summary IS part of this run's result), NOT shells (a dev server never
+        // exits → would hang headless forever) and NOT video (a long render the
+        // one-shot run shouldn't block on). This replaces the old for(;;) park
+        // (s-mpvf4rsj-bb6e4639 invariant) for the headless case only.
+        const sid = session.state.sessionId;
+        const isTopLevel = this.config.isSubAgent !== true;
+        if (isTopLevel && this.isHeadless()) {
+            result = await drainHeadlessBackgroundAgents({
+                sid,
+                session,
+                signal: options?.signal,
+                initialResult: result,
+                runTurnLoop: (msgs) => turnLoop.run(msgs),
+                applyGoalTermination,
+                waitForBackgroundAgentChange: (s, sig) => this.waitForBackgroundAgentChange(s, sig),
+                waitForBackgroundAgentChangeOrTimeout: (s, ms) => this.waitForBackgroundAgentChangeOrTimeout(s, ms),
+                getFirstGoalTermination: () => firstGoalTermination,
+                setFirstGoalTermination: (t) => {
+                    firstGoalTermination = t;
+                },
             });
-            return fallback;
         }
+        return { result, firstGoalTermination };
     }
-    async runMemoryPipeline(transcript, sessionId, cwd, primaryClient, recordBilledUsage) {
-        try {
-            // Background calls run on the auxiliary model when configured, so memory
-            // book-keeping doesn't burn the expensive primary model every turn.
-            // settings.memories.extractionModel (if set + valid) overrides the aux
-            // model specifically for memory extraction (TODO 8.1).
-            const llmClient = await this.resolveExtractionClient(primaryClient);
-            // Only run memory extraction for substantive sessions. The previous
-            // threshold of 4 user+assistant messages was low enough that two-line
-            // exchanges ("what's the time?" / "noon") triggered a full LLM
-            // 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");
-            if (messages.length < 8)
-                return;
-            // Memory orchestrator + dream-loop calls are auxiliary LLM calls
-            // that don't (and shouldn't) carry image payloads. Sanitize before
-            // stringify so we don't pump a 10 MB base64 string into the
-            // summarization prompt — provider 400s on it, and it leaks bytes
-            // into a downstream cost-tracking path we don't audit as carefully
-            // as the primary turn.
-            const plainMessages = messages.map((m) => {
-                const safe = sanitizeContent(m.content);
-                return {
-                    role: m.role,
-                    content: typeof safe === "string" ? safe : JSON.stringify(safe),
-                };
-            });
-            const orchestrator = new MemoryOrchestrator({
-                callLLM: async (sysPrompt, userMsg) => {
-                    // Use a lightweight auxiliary call (no tools, no streaming, no
-                    // reasoning tokens).
-                    const resp = await llmClient.createMessage({
-                        systemPrompt: sysPrompt,
-                        messages: [{ role: "user", content: userMsg }],
-                        tools: [],
-                        maxTokens: 1024,
-                        billingEnabled: true,
-                        requestVisible: false,
-                        reasoning: { mode: "off" },
-                    });
-                    if (resp.usage)
-                        recordBilledUsage?.(resp.usage);
-                    return resp.text;
-                },
-                runDream: async ({ systemPrompt, userPrompt, projectDir }) => this.runDreamLoop({
-                    systemPrompt,
-                    userPrompt,
-                    projectDir,
-                    llmClient,
-                    sessionId,
-                    recordBilledUsage,
-                }),
-                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);
+    /**
+     * Stamp the resolved session identity and session-scoped side-effect sinks
+     * onto the run's {@link ToolContext}, now that the session bundle is open.
+     * Extracted verbatim from the {@link runExclusive} skeleton.
+     */
+    stampRunToolContext(toolCtx, session, options) {
+        // B2 / Gate 1: stamp the resolved sid onto the tool context so
+        // session-scoped side effects (background-agent completion
+        // notifications) attribute to the right session. toolCtx is created
+        // before the session bundle is resolved (see ~line 635), so this is
+        // the first point we can set it. After this assignment treat the
+        // field follows the latest successfully injected user intent for the rest
+        // of the run, so tools launched after a steer attribute their side effects
+        // to that steer rather than this original submit.
+        toolCtx.sessionId = session.state.sessionId;
+        toolCtx.originClientMessageId = options?.clientMessageId;
+        toolCtx.recordExternalFileChanges = (record) => {
+            session.transcript.append("external_file_changes", { ...record });
+        };
+        toolCtx.setSessionWorkspace = (workspace, persistedRevision) => {
+            // Enter/ExitWorktree passes the revision returned by its in-process
+            // field update. The desktop bridge persists in another process before
+            // returning, so repeat the idempotent workspace update here to obtain a
+            // revision owned by this live bundle.
+            const stateRevision = persistedRevision ??
+                this.sessionManager.setSessionWorkspace(session.state.sessionId, workspace);
+            Object.assign(session.state, { workspace, stateRevision });
+        };
+        if (this.config.isSubAgent !== true &&
+            session.state.kind === "work" &&
+            !isEphemeralSessionState(session.state)) {
+            this.attachSessionMessageService(toolCtx, session, options);
         }
-        catch (err) {
-            // Memory pipeline is best-effort — never surface errors to the user.
-            logger.warn("engine.memory_pipeline_failed", {
+    }
+    /** Attach a closed-set, host-routed Session message sender to this run. */
+    attachSessionMessageService(toolCtx, session, options) {
+        const sourceSessionId = session.state.sessionId;
+        const sourceRoot = this.sessionManager.readSessionMainRoot(sourceSessionId);
+        if (!sourceRoot)
+            return;
+        if (!this.sessionMessageRouter)
+            return;
+        const catalog = [];
+        const seen = new Set();
+        const rawTargets = Array.isArray(options?.sessionMessageTargets)
+            ? [...options.sessionMessageTargets]
+            : [];
+        for (const raw of rawTargets.slice(0, 100)) {
+            if (!raw || typeof raw !== "object" || Array.isArray(raw))
+                continue;
+            const candidate = raw;
+            const sessionId = typeof candidate.sessionId === "string" ? candidate.sessionId : "";
+            try {
+                assertSafeSessionId(sessionId);
+            }
+            catch {
+                continue;
+            }
+            if (seen.has(sessionId))
+                continue;
+            if (candidate.workspaceRoot !== sourceRoot)
+                continue;
+            const title = typeof candidate.title === "string" ? candidate.title.trim() : "";
+            if (!title || title.length > 512)
+                continue;
+            const workspaceProfile = typeof candidate.workspaceProfile === "string"
+                ? candidate.workspaceProfile.trim().slice(0, 256)
+                : "";
+            seen.add(sessionId);
+            catalog.push({
                 sessionId,
-                error: err.message,
+                title,
+                workspaceRoot: sourceRoot,
+                ...(workspaceProfile ? { workspaceProfile } : {}),
             });
         }
+        const targets = catalog.filter((target) => target.sessionId !== sourceSessionId);
+        toolCtx.sessionMessages = {
+            targets,
+            send: async ({ targetSessionId, message }) => {
+                const target = targets.find((candidate) => candidate.sessionId === targetSessionId);
+                if (!target)
+                    throw new Error("target Session is not in the host-authorized project list");
+                if (!message.trim())
+                    throw new Error("message is required");
+                if (message.length > 48_000)
+                    throw new Error("message exceeds 48000 characters");
+                await this.sessionMessageRouter({
+                    sourceSessionId,
+                    target,
+                    message,
+                    catalog,
+                });
+                return target;
+            },
+        };
     }
     /**
-     * Drive the auto-dream tool-call loop.
-     *
-     * Runs the LLM with a whitelisted subset of memory tools (MemoryList,
-     * MemoryRead, MemorySave, MemoryDelete). The loop is intentionally small
-     * and offline:
-     *   - No streaming, no UI events — runs in the background after a session.
-     *   - No permission prompts — UI isn't attached, so we hard-reject any
-     *     attempt to Save/Delete in the "user" scope before dispatching. Dream
-     *     scope is the LLM's workspace and goes through freely.
-     *   - Capped at MAX_TURNS LLM round-trips and MAX_WRITES total
-     *     mutations to bound damage on misbehavior.
-     *
-     * Returns true if the loop ran (with or without writes); false if we
-     * bailed before the first LLM call (e.g. registry missing the tools).
-     */
-    async runDreamLoop(opts) {
-        // The loop body now lives in services/dream-consolidation.ts so it can
-        // also be driven from the desktop host's manual "整理 / Dream" trigger.
-        // The orchestrator built systemPrompt/userPrompt from this engine's
-        // MemoryManager already; runDreamConsolidation rebuilds them from the same
-        // projectDir, so passing them here would be redundant — we just hand it the
-        // tool registry + a memory-scoped tool context.
-        const { ran } = await runDreamConsolidation({
-            llmClient: opts.llmClient,
+     * Await the parallel prompt/context assembly (LLM client handshake, system
+     * prompt, dynamic + user context messages), splice the hook-injected and
+     * context messages into `messages`, publish this run's last-session snapshot,
+     * and prime the {@link ContextManager}'s transcript path + replacement state.
+     * Extracted verbatim from the {@link runExclusive} skeleton.
+     */
+    async assembleRunPrompts(args) {
+        const { session, messages, hookMessages, promptComposer, toolDefs, llmClientPromise, contextManager, profile, profileParams, } = args;
+        const [llmClient, baseSystemPrompt, 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.buildDynamicContextMessage(),
+        ]);
+        const fullSystemPrompt = composeRunSystemPrompt({
+            baseSystemPrompt,
+            profile,
+            profileParams,
+        });
+        const userContextMsg = promptComposer.buildUserContextMessage();
+        assembleRunMessages({
+            messages,
+            userContextMsg,
+            hookMessages,
+            dynamicContextMsg,
+        });
+        this.lastSessionId = session.state.sessionId;
+        this.lastMessages = messages;
+        // Wire up LLM summarization for context compaction
+        // Uses a lightweight call without tools
+        contextManager.setTranscriptPath(session.transcript.getFilePath());
+        // Re-derive frozen persistence decisions from the messages we just
+        // loaded. Skipped on cold start (messages == [userContextMsg] only).
+        // Critical for resume — otherwise a result that was persisted last
+        // run would be evaluated fresh and might get a different replacement
+        // string than the one already in the message, breaking idempotency.
+        contextManager.initReplacementStateFromMessages(messages);
+        // Two summarizers with DIFFERENT quality needs (see the run loop wiring for
+        // the aux-model summarizer set up alongside the ModelFacade).
+        return { llmClient, fullSystemPrompt, dynamicContextMsg, userContextMsg };
+    }
+    /**
+     * Seed the run's {@link ContextManager}, emit the early `session_started`
+     * event, replay the last TodoWrite snapshot on resume, kick off the LLM client
+     * handshake, and build the permission-gated {@link ToolExecutor}. Extracted
+     * verbatim from the {@link runExclusive} skeleton; the todo snapshot is read
+     * and written through the `getLatestTodos` / `setLatestTodos` accessors so the
+     * outer wrapped-onStream and TaskGuard keep observing the same buffer.
+     */
+    wireRunContextAndPermission(args) {
+        const { session, sid, options, cwd, toolCtx, runPermissionMode, messages, getLatestTodos, setLatestTodos, } = args;
+        const { contextManager, ctxSeed } = createRunContextManager({
+            maxTokens: this.resolveMaxContextTokens(),
+            ratios: this.resolveContextRatios(),
+            persistedAnchor: session.state.contextUsageAnchor,
+            llmProvider: this.config.llm.provider,
+            llmModel: this.config.llm.model,
+            messages,
+            needsCtxSeed: !this.ctxSeedSent.has(sid),
+        });
+        this.lastContextManager = contextManager;
+        if (!this.ctxSeedSent.has(sid))
+            this.ctxSeedSent.add(sid);
+        // Tell the client the sid *now* instead of waiting for run() to resolve.
+        // The user wants `/sid` to work mid-turn; without this, the client only
+        // learns the sid when the run completes.
+        options?.onStream?.({
+            type: "session_started",
+            sessionId: sid,
+            promptTokens: ctxSeed.tokens,
+            promptTokensSource: ctxSeed.source,
+            promptTokensConfidence: ctxSeed.confidence,
+        });
+        // Replay the last TodoWrite snapshot on resume so the UI's pinned
+        // task panel re-hydrates without the LLM needing to call TodoWrite
+        // again. Scans the resumed transcript newest-first (and tolerates
+        // legacy TaskCreate/Update events for sessions recorded against
+        // the pre-2026-05-24 API). New sessions have no transcript yet so
+        // readLastTodoSnapshot returns null and nothing is emitted.
+        if (options?.sessionId) {
+            const snap = readLastTodoSnapshot(session.transcript.getEvents());
+            if (snap && snap.length > 0) {
+                setLatestTodos(snap);
+                options?.onStream?.({ type: "task_update", tasks: snap });
+            }
+        }
+        // Kick off LLM client creation early (network handshake)
+        const llmClientPromise = createLLMClient(this.config.llm, this.config.clientDefaults);
+        // MCP connection below may keep us from awaiting this promise for a while.
+        // Observe rejection immediately so a fast client-init failure cannot become
+        // an unhandledRejection during that gap; Promise.all still receives the
+        // original promise and routes the same error through the lifecycle catch.
+        void llmClientPromise.catch(() => { });
+        const mode = runPermissionMode;
+        const { toolExecutor } = buildRunPermissionPipeline({
+            permissionController: this.permissionController,
+            mode,
+            cwd,
+            approvalRouter: toolCtx.approvalRouter,
+            sessionId: session.state.sessionId,
             toolRegistry: this.toolRegistry,
-            toolContext: this.buildToolContext(),
-            projectDir: opts.projectDir,
-            sessionId: opts.sessionId,
-            onUsage: opts.recordBilledUsage,
+            hooks: this.hooks,
+            toolCtx,
+            signal: options?.signal,
+            readOnlySession: this.config.readOnlySession === true,
+            headless: this.config.headless === true,
+            getLatestTodos: () => getLatestTodos(),
+            onApprovalPhase: (waiting, toolName) => {
+                options?.onAgentProgress?.({
+                    type: "phase",
+                    phase: waiting ? "waiting-permission" : "tool",
+                    toolName,
+                });
+            },
+            emitNotificationHook: (payload) => {
+                void this.emitHook("notification", payload);
+            },
+        });
+        return { contextManager, llmClientPromise, toolExecutor };
+    }
+    /**
+     * Resolve the run sandbox, construct the child sub-agent spawner (the sole
+     * `new Engine(...)` call path, kept in engine.ts so the protocol bypass guard
+     * stays satisfied), and assemble the per-run {@link ToolContext}. Extracted
+     * verbatim from the {@link runExclusive} skeleton; the session bundle is read
+     * lazily via `getSession` because it is opened after this wiring runs.
+     */
+    async wireRunSandboxToolContext(args) {
+        const { options, cwd, runPermissionMode, runPlanMode, profile, profileParams, sessionProfileOverrides, profileMemoryDir, getSession, reportResult, } = args;
+        // Resolve before constructing the child spawner: a parent sandbox may come
+        // solely from project/user settings rather than config.sandbox, while a
+        // child intentionally skips project settings. Passing the complete
+        // effective config is what makes undefined role sandbox mean inherit.
+        const sandboxConfig = this.runEnvironmentResolver.resolveSandboxConfig(cwd);
+        // Build the per-Engine ToolContext that will be threaded through every
+        // tool call. Replaces the old module-level singleton setters used by
+        // built-ins and product capabilities.
+        const subAgentSpawner = createSubAgentSpawner({
+            parentConfig: this.config,
+            parentSandbox: sandboxConfig,
+            presetName: this.preset.name,
+            cwd,
+            permissionMode: runPermissionMode,
+            modelPool: this.modelPool,
+            parentStream: options?.onStream,
+            appendParentSubagent: (agentId, description) => {
+                getSession().transcript.appendSubagent(agentId, undefined, description);
+            },
+            sessionExists: (sessionId) => this.sessionManager.exists(sessionId),
+            getSessionParentId: (sessionId) => this.sessionManager.readParentSessionId(sessionId),
+            childRunner: {
+                createChild: (config) => new Engine(config),
+                runChild: async (config, childTask, childOptions) => {
+                    const child = new Engine(config);
+                    return child.run(childTask, childOptions);
+                },
+            },
+        });
+        // 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
+        // previous behavior — catching the throw inside the hot turn and
+        // silently downgrading to "off" — was the leak A2 closes. The
+        // `auto` mode handles its own downgrade with a one-time warning
+        // inside resolveSandboxBackend; explicit modes do not.
+        //
+        // Backend is cached per runtime/engine so the capability probe runs once
+        // per (mode, cwd) instead of every turn.
+        const sandboxBackend = await this.runEnvironmentResolver.resolveSandbox(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,
+        });
+        const toolCtx = buildRunToolContext({
+            base: this.buildToolContext(cwd, sessionProfileOverrides, profileMemoryDir),
+            options,
+            configApprovalRouter: this.config.approvalRouter,
+            runPermissionMode,
+            runPlanMode,
+            subAgentSpawner,
+            agentDefinitions: this.getAgentDefinitions(cwd, sessionProfileOverrides),
+            sandbox: sandboxBackend.name === "off"
+                ? sandboxBackend
+                : { ...sandboxBackend, network: sandboxConfig.network },
+            cwd,
+            shellEnv: this.runEnvironmentResolver.readShellEnv(cwd),
+            profile,
+            profileParams,
+            reportResult,
+        });
+        return toolCtx;
+    }
+    /**
+     * Wire every run-scoped dependency the turn loop needs: usage accounting +
+     * summarizer, the {@link ModelFacade}, the file-history hook, the
+     * `on_agent_start` hook, goal resolution / arming, the {@link TurnLoop} itself,
+     * and the goal-termination applier. Extracted verbatim from the
+     * {@link runExclusive} skeleton; the goal slots, judge-context buffer and usage
+     * baseline are fully local here — only the values the try/finally + finalize
+     * phases consume cross back out.
+     */
+    async wireRunLoop(args) {
+        const { session, sid, task, cwd, options, toolCtx, toolExecutor, contextManager, llmClient, auxSummaryClient, fullSystemPrompt, toolDefs, claimClientMessageId, releaseClientMessageId, freshImageMessage, dynamicContextMsg, } = args;
+        // eslint-disable-next-line prefer-const
+        let turnLoop;
+        const accounting = createRunUsageAccounting({
+            session,
+            sid,
+            resumeState: (s) => this.sessionManager.resume(s).state,
+            updatePersistedSessionState: (s, patch) => this.updatePersistedSessionState(s, patch),
+            costStore: this.config.costStore,
+            recordGoalJudgeUsage: (usage) => turnLoop.recordGoalJudgeUsage(usage),
+        });
+        const { recordCumulativeUsage, recordExternalBilledUsage } = accounting;
+        contextManager.setSummarizeFn(this.buildSummarizeFn(llmClient, recordExternalBilledUsage));
+        const { modelFacade, getRunUsage } = wireRunModelFacade({
+            llmClient,
+            auxSummaryClient,
+            transcript: session.transcript,
+            accounting,
+        });
+        // 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 };
+        const sessionDir = join(this.config.sessionStorageDir ?? sessionsRoot(), session.state.sessionId);
+        const fileHistoryHook = registerFileHistoryHook({
+            hooks: this.hooks,
+            sessionDir,
+            cwd,
+            getTurnSeq: () => session.state.turnSeq,
+            contributions: this.capabilities.flatMap((capability) => [...(capability.fileHistory ?? [])]),
+        });
+        // Hook: agent start
+        await this.emitHook("on_agent_start", {
+            sessionId: session.state.sessionId,
+            task,
+            model: this.config.llm.model,
+        }, options?.signal);
+        // Goal mode: register a GoalStopHook for the lifetime of THIS run so the
+        // turn loop keeps going until the session model judges the goal met.
+        // Registered per-run (and cleared in `finally`) so a later goal-less
+        // send doesn't inherit a stale goal. The judge runs on the primary
+        // session client; auxSummaryClient remains dedicated to low-consequence
+        // summaries/titles and retains defaults.auxText routing/fallback behavior.
+        // Normalize the raw goal (string | GoalConfig) once at the run boundary;
+        // everything inward uses the GoalConfig. normalizeGoal() returns undefined
+        // when there's effectively no goal (empty objective).
+        //
+        // PERSISTENT GOAL (CC /goal style): a goal set on one send survives across
+        // later sends and manual interrupts until met or cleared. Goal completion
+        // is a high-consequence decision, so V1 routes it to the primary session
+        // client, which is the model expected to interpret the supplied execution
+        // evidence. defaults.auxText remains in force for summaries, titles and
+        // other auxiliary work through auxSummaryClient.
+        // Resolution:
+        //   1. options.goal — this send explicitly sets/replaces the goal.
+        //   2. session.state.goalLifecycle — 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 goalSlots = {
+            getActiveRuntimeGoal: () => this.activeRuntimeGoal,
+            setActiveRuntimeGoal: (g) => {
+                this.activeRuntimeGoal = g;
+            },
+            getActivePersistedRunGoal: () => this.activePersistedRunGoal,
+            setActivePersistedRunGoal: (g) => {
+                this.activePersistedRunGoal = g;
+            },
+            getActiveGoalHook: () => this.activeGoalHook,
+            setActiveGoalHook: (h) => {
+                this.activeGoalHook = h;
+            },
+            setActiveGoalHookAttached: (a) => {
+                this.activeGoalHookAttached = a;
+            },
+        };
+        const { normalizedGoal, persistedRunGoal } = resolveRunGoal({
+            options,
+            session,
+            sessionManager: this.sessionManager,
+            configGoal: this.config.goal,
+            isSubAgent: this.config.isSubAgent === true,
+            sid,
+            onStream: options?.onStream,
+        });
+        let latestGoalJudgeContext;
+        const goalHookHandler = armRunGoalHook({
+            slots: goalSlots,
+            hooks: this.hooks,
+            llmClient,
+            isSubAgent: this.config.isSubAgent === true,
+            normalizedGoal,
+            persistedRunGoal,
+            session,
+            sessionManager: this.sessionManager,
+            persistGoalTerminal: (state, goal, reason) => this.persistGoalTerminal(state, goal, reason),
+            getJudgeContext: () => latestGoalJudgeContext,
+            recordCumulativeUsage,
+            recordGoalJudgeUsage: (usage) => turnLoop.recordGoalJudgeUsage(usage),
+        });
+        turnLoop = this.buildTurnLoop({
+            modelFacade,
+            toolExecutor,
+            contextManager,
+            session,
+            fullSystemPrompt,
+            toolDefs,
+            sid,
+            options,
+            cwd,
+            claimClientMessageId,
+            releaseClientMessageId,
+            toolCtx,
+            persistedRunGoal,
+            goalHookHandler,
+            normalizedGoal,
+            freshImageMessage,
+            dynamicContextMsg,
+            usageBaseline,
+            getRunUsage,
+            recordCumulativeUsage,
+            publishGoalJudgeContext: (context) => {
+                latestGoalJudgeContext = context;
+            },
+        });
+        toolCtx.recordBilledUsage = recordExternalBilledUsage;
+        // 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;
+        const applyGoalTermination = createGoalTerminationApplier({
+            slots: goalSlots,
+            hooks: this.hooks,
+            session,
+            persistedRunGoal,
+            goalHookHandler,
+            persistGoalTerminalOutcome: (state, goal, t) => this.persistGoalTerminalOutcome(state, goal, t),
+            readActiveGoal: (s) => this.sessionManager.readActiveGoal(s),
+            onStream: options?.onStream,
+        });
+        return {
+            turnLoop,
+            applyGoalTermination,
+            goalHookHandler,
+            fileHistoryHook,
+            getRunUsage,
+            recordExternalBilledUsage,
+            accounting,
+            usageBaseline,
+        };
+    }
+    /**
+     * Record the session start and fire the once-per-run `on_session_start` and
+     * per-turn `user_prompt_submit` / `agent_direction_submit` hooks, applying any
+     * `updatedPrompt` rewrite in place on `messages`. Extracted verbatim from the
+     * {@link runExclusive} skeleton; returns the combined hook-injected messages
+     * for {@link assembleRunMessages}.
+     */
+    async runSessionStartHooks(args) {
+        const { session, task, cwd, runPermissionMode, resumedFromDisk, options, taskText, messages } = args;
+        recordSessionStart(session.state.sessionId, {
+            // Strip <codeshell-image> base64 payloads before they reach
+            // <repo>/log/. Reader still sees the marker + byte count, just
+            // not the bytes. Transcript persistence keeps the full payload.
+            task: sanitizeTaskString(task),
+            cwd,
+            model: this.config.llm.model,
+            provider: this.config.llm.provider,
+            permissionMode: runPermissionMode,
+            resumed: resumedFromDisk,
+        });
+        // Session-level hook: fired once per Engine.run() entry, regardless of
+        // cold-start vs resume. Handlers can return `messages` to inject a
+        // <system-reminder> at the head of the conversation (between
+        // userContext and the new user prompt). Used by the built-in
+        // superpowers injector to surface the `using-superpowers` ruleset.
+        const sessionStartHook = await this.emitHook("on_session_start", {
+            sessionId: session.state.sessionId,
+            cwd,
+            resumed: resumedFromDisk,
+            source: resumedFromDisk ? "resume" : "startup",
+        }, options?.signal);
+        // Per-turn hook: fired every time a new user prompt enters the loop.
+        // Equivalent to CC's UserPromptSubmit. Handlers can inject lightweight
+        // reminders that should accompany each user turn (e.g. "skills
+        // available — check before acting").
+        const promptSubmitHook = await this.emitHook(options?.agentDirection ? "agent_direction_submit" : "user_prompt_submit", {
+            sessionId: session.state.sessionId,
+            // Pass the text-only portion. Handlers reading the prompt for keyword
+            // detection / classification (e.g. superpowers' "did the user ask
+            // about X?") don't gain anything from megabytes of base64 inlined here,
+            // and silently leaking attachment bytes through hooks is the kind of
+            // exfiltration risk a curious user-installed shell hook shouldn't carry.
+            prompt: taskText,
+            resumed: resumedFromDisk,
+            ...(options?.agentDirection
+                ? {
+                    source: "agent-direction",
+                    authority: "agent",
+                    envelopeIds: options.agentDirection.envelopeIds,
+                    correlationIds: options.agentDirection.correlationIds,
+                }
+                : {}),
+        }, options?.signal);
+        // updatedPrompt: handler rewrote the user's prompt text. Replace the
+        // last user message we just pushed (cold-start: line ~511; resume:
+        // line ~500). Original prompt is in the transcript already — we log
+        // the rewrite so audit chains know a hook touched user input.
+        if (typeof promptSubmitHook.updatedPrompt === "string") {
+            const lastIdx = messages.length - 1;
+            const last = messages[lastIdx];
+            if (last && last.role === "user" && typeof last.content === "string") {
+                logger.info("hook.updated_prompt", {
+                    sessionId: session.state.sessionId,
+                    originalChars: last.content.length,
+                    updatedChars: promptSubmitHook.updatedPrompt.length,
+                });
+                messages[lastIdx] = { role: "user", content: promptSubmitHook.updatedPrompt };
+            }
+        }
+        return [...(sessionStartHook.messages ?? []), ...(promptSubmitHook.messages ?? [])];
+    }
+    /**
+     * Resolve goal visibility, disabled skill/plugin lists, build the
+     * {@link PromptComposer}, connect MCP, and assemble the visibility-filtered
+     * tool defs for this run. Extracted verbatim from the {@link runExclusive}
+     * skeleton; the intermediate visibility/disabled/mcp values are fully local to
+     * this method — only the composer and tool defs cross back out.
+     */
+    async wireRunTooling(args) {
+        const { options, session, cwd, toolCtx, profile, profileParams, runWorkspaceProfile, profileMemoryDir, sessionProfileOverrides, runPlanMode, } = args;
+        const visibilityExplicitGoal = normalizeGoal(options?.goal);
+        const visibilityLifecycle = session.state.goalLifecycle;
+        const visibilityStoredGoal = visibilityLifecycle && isGoalLifecycleCurrent(visibilityLifecycle)
+            ? goalConfigFromLifecycle(visibilityLifecycle)
+            : undefined;
+        const visibilityDefaultGoal = normalizeGoal(this.config.goal);
+        const hasRunnableGoal = this.config.isSubAgent !== true &&
+            ((visibilityExplicitGoal !== undefined && visibilityExplicitGoal.paused !== true) ||
+                (visibilityStoredGoal !== undefined && visibilityStoredGoal.paused !== true) ||
+                (visibilityDefaultGoal !== undefined && visibilityDefaultGoal.paused !== true));
+        const { disabledSkills, disabledPlugins } = this.readDisabledLists(cwd, sessionProfileOverrides);
+        const promptComposer = new PromptComposer(buildPromptComposerConfig({
+            cwd,
+            model: this.config.llm.model,
+            preset: this.preset,
+            customSystemPrompt: this.config.customSystemPrompt,
+            appendSystemPrompt: [this.config.appendSystemPrompt, profile?.systemPromptAppend]
+                .filter(Boolean)
+                .join("\n\n") || undefined,
+            responseLanguage: this.config.responseLanguage,
+            userProfile: this.config.userProfile,
+            workspaceProfile: runWorkspaceProfile,
+            // Read from the Session's own persisted state, so every turn — not just
+            // the first — carries the standing brief.
+            sessionBrief: session.state.sessionBrief,
+            profileMemoryDir,
+            instructionCompatFileNames: compatFileNamesFrom(this.config.instructions),
+            instructionBoundaryFinder: (scanCwd) => resolveInstructionBoundary(scanCwd, this.capabilities),
+            disabledSkills,
+            disabledPlugins,
+            skillAllowlist: this.config.skillAllowlist,
+            memoriesMaxAgeDays: this.readMemoriesConfig()?.maxAge,
+            goalToolState: { hasGoal: hasRunnableGoal },
+            capabilityPromptSections: this.capabilityPromptSections,
+            dynamicContextProviders: this.capabilityDynamicContextProviders,
+            getSettingsManager: () => this.getSettingsManager(),
+            toolCatalog: this.toolCatalog,
+        }));
+        const mcpServers = this.config.mcpServers ?? {};
+        const mcpDisabled = profile?.disableMcp === true;
+        await connectRunMcp({
+            mcpServers,
+            mcpDisabled,
+            getManager: () => this.mcpManager,
+            setManager: (m) => {
+                this.mcpManager = m;
+            },
+            runtimePool: this.runtime?.mcpPool,
+            toolRegistry: this.toolRegistry,
+            engineForConnect: this,
+            emitNotificationHook: (payload) => {
+                void this.emitHook("notification", payload);
+            },
+        });
+        // Parallelize slow initialization:
+        //   1. createLLMClient — network handshake (started earlier)
+        //   2. buildSystemPrompt — cacheable prompt assembled from generic sections
+        //   3. buildSystemContext — reads environment context
+        // Inject the live available-agent-types listing into the Agent tool's
+        // description. The registry is per-engine (loaded from .code-shell/agents
+        // for this cwd), so it can't live in the static tool def — without this
+        // the model never learns the reusable roles exist and spawns nameless
+        // ad-hoc agents instead (the Core A/B/C incident).
+        // The Agent tool is always available: with configured roles, an omitted
+        // agent_type falls back to one of them (see resolveAgentTypeOverrides); with
+        // no roles configured it runs a true ephemeral agent, so workflows that need
+        // sub-agents (e.g. superpowers) work in any project.
+        // Availability guard (tool-visibility): a gated builtin (WebSearch needs a
+        // search provider, GenerateImage needs an OpenAI provider) is hidden from
+        // the toolDefs the model sees when its credential isn't configured for this
+        // cwd. Recomputed every message, so configuring a key takes effect on the
+        // NEXT message without a restart. Tools with no guard entry are always kept.
+        const toolDefs = assembleRunToolDefs({
+            toolRegistry: this.toolRegistry,
+            toolCtx,
+            guardCwd: toolCtx.cwd,
+            hasRunnableGoal,
+            settingsScope: this.config.settingsScope ?? "project",
+            builtinToolHost: this.config.builtinToolHost,
+            isSubAgent: this.config.isSubAgent === true,
+            behaviorProfileId: profile?.id ?? options?.behaviorMode,
+            profileMeta: profile?.buildVisibilityMeta?.(profileParams),
+            builtinOverride: this.readBuiltinOverride(toolCtx.cwd, sessionProfileOverrides),
+            mcpServers: this.config.mcpServers ?? {},
+            mcpDisabled,
+            featureFlags: this.readFeatureFlags(),
+            toolGuards: this.toolGuards,
+            toolRewriters: this.toolRewriters,
+            toolFeatureFlags: TOOL_FEATURE_FLAGS,
+            applyBuiltinOverrideVisibility,
+            profileAllowedToolNames: profile?.allowedToolNames,
+            runPlanMode,
+        });
+        return { promptComposer, toolDefs };
+    }
+    /**
+     * Assemble the run-scoped {@link TurnLoop} (its dependency object + option
+     * object) from the per-run locals gathered in {@link runExclusive}. Extracted
+     * verbatim from the orchestration skeleton so `runExclusive` stays a readable
+     * sequence of phase calls; the buffered-compaction `let` lives entirely inside
+     * here now, and the only value crossing back out is the goal-judge context,
+     * published through the `publishGoalJudgeContext` callback.
+     */
+    buildTurnLoop(args) {
+        const { modelFacade, toolExecutor, contextManager, session, fullSystemPrompt, toolDefs, sid, options, cwd, claimClientMessageId, releaseClientMessageId, toolCtx, persistedRunGoal, goalHookHandler, normalizedGoal, freshImageMessage, dynamicContextMsg, usageBaseline, getRunUsage, recordCumulativeUsage, publishGoalJudgeContext, } = args;
+        // Surface compaction events to the UI so the user knows when context was trimmed.
+        // Buffer the most recent event so TurnLoop can drain it and emit the
+        // post_compact hook on the next turn (ContextManager itself doesn't
+        // know about HookRegistry — the buffer is the seam).
+        let pendingCompactInfo = null;
+        contextManager.setOnCompact((info) => {
+            pendingCompactInfo = info;
+            options?.onStream?.({ type: "context_compact", ...info });
+        });
+        // Run turn loop
+        const turnLoop = new TurnLoop({
+            model: modelFacade,
+            toolExecutor,
+            contextManager,
+            hooks: this.hooks,
+            transcript: session.transcript,
+            systemPrompt: fullSystemPrompt,
+            tools: toolDefs,
+            sessionId: sid,
+            isSubAgent: this.config.isSubAgent === true,
+            consumePendingCompactInfo: () => {
+                const info = pendingCompactInfo;
+                pendingCompactInfo = null;
+                return info;
+            },
+            consumeSteer: (source) => this.consumeSteer(sid, source),
+            consumeAgentDirections: this.config.isSubAgent === true
+                ? () => notificationQueue.drain(sid, (envelope) => envelope.kind === "direction" &&
+                    envelope.runtimeGeneration === options?.runtimeGeneration)
+                : undefined,
+            onAgentControlState: this.config.isSubAgent === true
+                ? (state) => {
+                    this.agentControlStateListener?.(state);
+                    if (state === "model") {
+                        options?.onAgentProgress?.({ type: "phase", phase: "model" });
+                    }
+                    else if (state === "tool-batch") {
+                        options?.onAgentProgress?.({ type: "phase", phase: "tool" });
+                    }
+                }
+                : undefined,
+            onAgentDirectionsDelivered: this.config.isSubAgent === true
+                ? (envelopeIds) => this.agentDirectionsDeliveredListener?.(envelopeIds)
+                : undefined,
+            restoreSteer: (items) => this.restoreSteer(sid, items),
+            buildSteerUserMessageContent: async (item) => {
+                const steerImageInput = await prepareRunImageInput({
+                    task: item.text,
+                    cwd,
+                    llm: this.config.llm,
+                    sessionId: sid,
+                    attachments: item.attachments,
+                });
+                if (!steerImageInput.ok) {
+                    throw new Error(steerImageInput.result.text);
+                }
+                return buildRunUserMessageContent(steerImageInput.parsedTask, cwd, steerImageInput.taskText);
+            },
+            claimClientMessageId: (clientMessageId, source) => claimClientMessageId(session, clientMessageId, source),
+            releaseClientMessageId,
+            setOriginClientMessageId: (clientMessageId) => {
+                toolCtx.originClientMessageId = clientMessageId;
+            },
+            recordCumulativeUsage,
+            onAgentUsage: (usage) => options?.onAgentProgress?.({ type: "usage", usage }),
+            recordCacheReadDiagnostics: (sample) => {
+                this.recordCacheReadDiagnostics(sid, sample);
+            },
+            recordContextUsageAnchor: (anchor) => {
+                session.state.contextUsageAnchor = {
+                    ...anchor,
+                    provider: this.config.llm.provider,
+                    model: this.config.llm.model,
+                };
+            },
+            // Clear the persisted goal for a self-reported completion / confirmed
+            // cancel. Clears the in-RAM session's activeGoal (so THIS run's later
+            // turns don't re-arm) AND persists it, and drops the in-flight stop
+            // hook so nothing re-blocks the stop we're about to return.
+            clearPersistedGoal: (reason) => {
+                const runGoal = this.activePersistedRunGoal ?? persistedRunGoal;
+                if (runGoal && !this.persistGoalTerminal(session.state, runGoal, reason)) {
+                    return false;
+                }
+                if (goalHookHandler) {
+                    this.hooks.unregister("on_stop", goalHookHandler);
+                    if (this.activeGoalHook === goalHookHandler) {
+                        this.activeGoalHook = null;
+                        this.activeGoalHookAttached = false;
+                        this.activeRuntimeGoal = null;
+                        this.activePersistedRunGoal = null;
+                    }
+                }
+                return true;
+            },
+            publishGoalJudgeContext: (context) => {
+                publishGoalJudgeContext(context);
+            },
+            // A background_notification yield parks the run until the Session is
+            // woken by the completion notification. Only a top-level interactive
+            // session can be woken (server refuses headless; sub-agent sessions
+            // are not in chatManager) — everywhere else honouring the yield would
+            // end the run early and orphan the background result, so the loop
+            // never sees the request and the model keeps its full turn.
+            ...(this.isHeadless() || this.config.isSubAgent === true
+                ? {}
+                : {
+                    peekToolRunYield: () => toolCtx.runYield?.peek?.(),
+                    consumeToolRunYield: () => toolCtx.runYield?.consume(),
+                }),
+            ctxOverheadStore: {
+                get: (s) => this.ctxOverheadBySid.get(s) ?? 0,
+                set: (s, n) => {
+                    this.ctxOverheadBySid.set(s, n);
+                },
+            },
+        }, {
+            // 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,
+            volatileContextMessages: dynamicContextMsg ? [dynamicContextMsg] : 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,
+            // Heartbeat: flush turnCount + tokens to state.json after every turn
+            // so external observers (other CLI processes, /sid, the session list)
+            // see live progress instead of a stale snapshot from the last
+            // completed run.
+            onTurnBoundary: (turnCount) => {
+                session.state.turnCount = turnCount;
+                // baseline + this run's running total (idempotent per boundary,
+                // accumulates across runs; carries cacheRead/cacheCreation too).
+                session.state.tokenUsage = foldRunUsage(usageBaseline, getRunUsage());
+                // 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,
+                    promptTokensSource: "session_cumulative",
+                    promptTokensConfidence: "high",
+                    cumulativePromptTokens: cumulative.cumulativePromptTokens,
+                    cumulativeCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                    cumulativeCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                    ...(cumulativeHitRate !== undefined
+                        ? { cumulativeCacheHitRate: cumulativeHitRate }
+                        : {}),
+                    sessionPromptTokens: cumulative.cumulativePromptTokens,
+                    sessionCacheReadTokens: cumulative.cumulativeCacheReadTokens,
+                    sessionCacheCreationTokens: cumulative.cumulativeCacheCreationTokens,
+                });
+                if (this.config.costStore) {
+                    session.state.costState = this.config.costStore.serialize();
+                }
+                this.persistRunProgress(session.state);
+            },
         });
-        return ran;
+        return turnLoop;
+    }
+    buildSummarizeFn(auxSummaryClient, recordCumulativeUsage) {
+        return this.auxiliaryPipeline.buildSummarizeFn(auxSummaryClient, recordCumulativeUsage);
+    }
+    async resolveAuxClient(fallback) {
+        return this.auxiliaryPipeline.resolveAuxClient(fallback);
+    }
+    async runMemoryPipeline(transcript, sessionId, cwd, primaryClient, recordBilledUsage) {
+        return this.auxiliaryPipeline.runMemoryPipeline(transcript, sessionId, cwd, primaryClient, recordBilledUsage);
     }
     getToolRegistry() {
         return this.toolRegistry;
     }
+    /** Registry suitable for constructing EngineRuntime; excludes local capabilities. */
+    getRuntimeToolRegistry() {
+        return this.runtimeToolRegistry;
+    }
     /**
      * Switch the active model by pool key. Takes effect on the next run() call.
      * Returns the new model entry.
@@ -2428,14 +2224,18 @@ export class Engine {
      * only live in memory and every restart reverts to the previously persisted
      * defaults.text.
      */
-    switchModel(key) {
+    switchModel(key, opts) {
         const entry = this.modelPool.switch(key);
         // LLMConfig is pure model identity now — rotate it wholesale. Cross-model
         // runtime knobs (temperature/timeout/retryMaxAttempts/imageDetail) live on
         // this.config.clientDefaults and survive the switch untouched.
         const nextLlm = this.modelPool.toLLMConfig(entry);
         this.config = { ...this.config, llm: nextLlm };
-        this.persistActiveModel(entry);
+        // persist: false is the per-session path (ChatSession) — switching one
+        // session's model must not rewrite settings.defaults.text, the boot
+        // default every future session inherits.
+        if (opts?.persist !== false)
+            this.persistActiveModel(entry);
         return entry;
     }
     /**
@@ -2452,9 +2252,14 @@ export class Engine {
         // 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);
+                if (this.activeRunSession?.state.sessionId === sessionId) {
+                    this.sessionManager.saveStateOrUpdateFields(this.activeRunSession.state, {
+                        tokenUsage: { ...zero },
+                    });
+                }
+                else {
+                    this.sessionManager.updateSessionState(sessionId, { tokenUsage: { ...zero } });
+                }
             }
             catch {
                 // Session not resumable (never persisted yet) — the in-memory reset
@@ -2534,6 +2339,94 @@ export class Engine {
     getSessionManager() {
         return this.sessionManager;
     }
+    /**
+     * Apply a field-level disk update and rebase this Engine's matching live
+     * bundle onto the returned revision so its next whole-state CAS can proceed.
+     */
+    updatePersistedSessionState(sessionId, partial) {
+        const stateRevision = this.sessionManager.updateSessionState(sessionId, partial);
+        if (this.activeRunSession?.state.sessionId !== sessionId)
+            return;
+        Object.assign(this.activeRunSession.state, partial, { stateRevision });
+    }
+    /**
+     * Adopt the exact persisted snapshot that won a Goal-control CAS without
+     * discarding counters which the current run has advanced since its previous
+     * heartbeat. Merely copying the new stateRevision is unsafe: the next
+     * whole-state save would then be allowed to publish stale title/workspace
+     * metadata over a concurrent field-level writer.
+     */
+    rebaseActiveRunAfterGoalUpdate(live, persisted) {
+        const runOwned = {
+            status: live.status,
+            summary: live.summary,
+            tokenUsage: live.tokenUsage,
+            contextUsageAnchor: live.contextUsageAnchor,
+            cumulativePromptTokens: live.cumulativePromptTokens,
+            cumulativeCacheReadTokens: live.cumulativeCacheReadTokens,
+            cumulativeCacheCreationTokens: live.cumulativeCacheCreationTokens,
+            turnCount: live.turnCount,
+            turnSeq: live.turnSeq,
+            completedThroughEventId: live.completedThroughEventId,
+            completedSnapshotVersion: live.completedSnapshotVersion,
+            invokedSkills: live.invokedSkills,
+            costState: live.costState,
+        };
+        // Optional fields deleted by another writer must disappear locally too;
+        // clear before assigning rather than leaving stale own-properties behind.
+        for (const key of Object.keys(live)) {
+            delete live[key];
+        }
+        Object.assign(live, persisted, runOwned);
+    }
+    persistGoalTerminal(state, goal, reason) {
+        return this.persistGoalTerminalOutcome(state, goal, reason) !== "failed";
+    }
+    persistGoalTerminalOutcome(state, goal, reason) {
+        const outcome = this.sessionManager.saveGoalTerminalOutcome(state, goal, reason);
+        if (outcome === "failed") {
+            logger.warn("session.goal_terminal_persist_failed", {
+                sessionId: state.sessionId,
+                goalId: goal.goalId,
+                reason,
+            });
+        }
+        return outcome;
+    }
+    persistFinalRunState(state) {
+        const finalFields = {
+            status: state.status,
+            turnCount: state.turnCount,
+            turnSeq: state.turnSeq,
+            tokenUsage: state.tokenUsage,
+            cumulativePromptTokens: state.cumulativePromptTokens,
+            cumulativeCacheReadTokens: state.cumulativeCacheReadTokens,
+            cumulativeCacheCreationTokens: state.cumulativeCacheCreationTokens,
+            contextUsageAnchor: state.contextUsageAnchor,
+            costState: state.costState,
+            completedSnapshotVersion: state.completedSnapshotVersion,
+            completedThroughEventId: state.completedThroughEventId,
+        };
+        if (!this.sessionManager.saveStateOrUpdateFields(state, finalFields)) {
+            logger.warn("session.final_state_persist_failed", { sessionId: state.sessionId });
+        }
+    }
+    persistRunProgress(state) {
+        const progressFields = {
+            status: state.status,
+            turnCount: state.turnCount,
+            turnSeq: state.turnSeq,
+            tokenUsage: state.tokenUsage,
+            cumulativePromptTokens: state.cumulativePromptTokens,
+            cumulativeCacheReadTokens: state.cumulativeCacheReadTokens,
+            cumulativeCacheCreationTokens: state.cumulativeCacheCreationTokens,
+            contextUsageAnchor: state.contextUsageAnchor,
+            costState: state.costState,
+        };
+        if (!this.sessionManager.saveStateOrUpdateFields(state, progressFields)) {
+            logger.warn("session.run_progress_persist_failed", { sessionId: state.sessionId });
+        }
+    }
     getConfig() {
         return this.config;
     }
@@ -2559,7 +2452,7 @@ export class Engine {
      * the main user-visible preset effect and it IS hot. The toolRegistry's
      * builtin tool SET, however, is ctor-frozen (and may be shared via runtime):
      * it is NOT rebuilt here. So a preset change that alters the builtin tool set
-     * (e.g. general → terminal-coding adds LSP/Brief) only takes effect on the
+     * (e.g. switching to a capability-contributed preset adds tools) only takes effect on the
      * next session restart; we log a warning when that case is detected.
      *
      * disk-default-vs-slice caveat (#8): the patch carries pure DISK-default
@@ -2581,13 +2474,14 @@ export class Engine {
         // (rebuilt per turn from this.preset) reflects the new preset's system
         // prompt / behavior. Only when the preset actually changed.
         if (patch.preset !== undefined && patch.preset !== prevPresetName) {
-            const nextPreset = resolveAgentPreset(this.config.preset);
+            const nextPreset = resolveAgentPreset(this.config.preset, this.capabilities);
             // 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,
                 host: this.config.builtinToolHost,
+                capabilities: this.capabilities,
             })
                 .slice()
                 .sort()
@@ -2595,6 +2489,7 @@ export class Engine {
             const nextTools = resolveBuiltinToolNames({
                 preset: nextPreset.name,
                 host: this.config.builtinToolHost,
+                capabilities: this.capabilities,
             })
                 .slice()
                 .sort()
@@ -2637,7 +2532,7 @@ export class Engine {
      * 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
+     * persistent goal lives only in state.goalLifecycle 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.
@@ -2645,43 +2540,185 @@ export class Engine {
     getGoal(sessionId) {
         return this.sessionManager.readActiveGoal(sessionId);
     }
+    /** True when the current run was built with Goal prompt/tools and can resume in place. */
+    canResumeGoalInPlace(sessionId) {
+        return (this.activeTurnLoop !== null &&
+            this.activeRunSession?.state.sessionId === sessionId &&
+            this.activeRuntimeGoal !== null &&
+            this.activeGoalHook !== null);
+    }
+    /**
+     * Edit or pause/resume a persisted goal. Mid-run edits use the same step-gap
+     * delivery seam as Steer: the current model/tool call is not aborted, and the
+     * updated objective is injected before the next model step. Pausing detaches
+     * the goal judge and stops this run before another model request is started.
+     */
+    updateGoal(sessionId, patch) {
+        if (!sessionId || !this.sessionManager.exists(sessionId))
+            return undefined;
+        const live = this.activeRunSession?.state.sessionId === sessionId ? this.activeRunSession : null;
+        const liveLifecycle = live?.state.goalLifecycle;
+        const before = liveLifecycle && isGoalLifecycleCurrent(liveLifecycle)
+            ? goalConfigFromLifecycle(liveLifecycle)
+            : this.sessionManager.readActiveGoal(sessionId);
+        if (!before)
+            return undefined;
+        if (patch.expectedGoalId !== undefined && before.goalId !== patch.expectedGoalId) {
+            return undefined;
+        }
+        if (patch.expectedRevision !== undefined && (before.revision ?? 1) !== patch.expectedRevision) {
+            return undefined;
+        }
+        const updated = this.sessionManager.updateActiveGoal(sessionId, {
+            ...patch,
+            expectedGoalId: patch.expectedGoalId ?? before.goalId,
+            expectedRevision: patch.expectedRevision ?? before.revision ?? 1,
+        });
+        if (!updated)
+            return undefined;
+        const next = updated.goal;
+        if (live) {
+            this.rebaseActiveRunAfterGoalUpdate(live.state, updated.state);
+        }
+        const resumesDormantGoal = this.activeTurnLoop !== null &&
+            live !== null &&
+            before.paused === true &&
+            next.paused !== true &&
+            this.activeRuntimeGoal === null &&
+            this.activeGoalHook !== null;
+        if (resumesDormantGoal) {
+            // This ordinary run was constructed while the persisted Goal was paused:
+            // its system prompt, visible tools and ToolContext are goal-less and
+            // cannot be safely hot-swapped. Stop it at the next step boundary; the
+            // protocol's conditional resume turn will rebuild a fully Goal-capable
+            // run from the now-unpaused persisted state.
+            this.activeTurnLoop.updateGoal(undefined);
+        }
+        const controlsThisRun = this.activeTurnLoop !== null &&
+            live !== null &&
+            isSameGoalVersion(before, this.activeRuntimeGoal ?? undefined);
+        if (controlsThisRun) {
+            if (this.activeRuntimeGoal) {
+                Object.assign(this.activeRuntimeGoal, next);
+                if (next.paused !== true)
+                    delete this.activeRuntimeGoal.paused;
+            }
+            if (this.activePersistedRunGoal) {
+                Object.assign(this.activePersistedRunGoal, next);
+                if (next.paused !== true)
+                    delete this.activePersistedRunGoal.paused;
+            }
+            if (next.paused === true) {
+                if (this.activeGoalHook && this.activeGoalHookAttached) {
+                    this.hooks.unregister("on_stop", this.activeGoalHook);
+                    this.activeGoalHookAttached = false;
+                }
+                this.activeTurnLoop.updateGoal(undefined);
+            }
+            else {
+                const objectiveChanged = before.objective !== next.objective;
+                const resumed = before.paused === true;
+                this.activeTurnLoop.updateGoal(next, objectiveChanged
+                    ? `目标已编辑。新的目标：${next.objective}`
+                    : resumed
+                        ? `目标已恢复：${next.objective}`
+                        : undefined, {
+                    maxTurns: resolveMaxTurns(this.config.maxTurns, next),
+                    maxStopBlocks: resolveMaxStopBlocks(this.config.maxStopBlocks, next),
+                });
+                if (this.activeGoalHook && !this.activeGoalHookAttached) {
+                    this.hooks.register("on_stop", this.activeGoalHook, 0, "goal-stop");
+                    this.activeGoalHookAttached = true;
+                }
+            }
+        }
+        return next;
+    }
     /**
      * 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
+     * `state.goalLifecycle` (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) {
+    clearGoal(sessionId, expected) {
         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.
+        // Prefer the LIVE run's bundle when it's this session so the domain update
+        // rebases the exact state object used by subsequent progress writes.
         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;
+        const lifecycle = session.state.goalLifecycle;
+        const currentGoal = lifecycle && isGoalLifecycleCurrent(lifecycle)
+            ? goalConfigFromLifecycle(lifecycle)
+            : undefined;
+        const had = currentGoal !== undefined;
+        let controlsThisRun = false;
+        if (had &&
+            ((expected?.goalId !== undefined && currentGoal?.goalId !== expected.goalId) ||
+                (expected?.revision !== undefined && (currentGoal?.revision ?? 1) !== expected.revision))) {
+            return false;
+        }
         if (had) {
-            session.state.activeGoal = undefined;
-            this.sessionManager.saveState(session.state);
+            const clearedGoal = currentGoal;
+            controlsThisRun =
+                this.activeTurnLoop !== null &&
+                    live !== null &&
+                    isSameGoalVersion(clearedGoal, this.activeRuntimeGoal ?? undefined);
+            if (!this.persistGoalTerminal(session.state, clearedGoal, "user_cleared"))
+                return false;
+            // A cross-writer edit may have won between the expected-version check
+            // above and saveGoalTerminal's conflict merge. In that case the old
+            // revision's tombstone is durable but the newer active revision remains;
+            // report a stale delete, and never stop/detach the run that owns it.
+            if (session.state.goalLifecycle && isGoalLifecycleCurrent(session.state.goalLifecycle)) {
+                return false;
+            }
+            // A paused Goal inherited by an ordinary run is only dormant persisted
+            // state; deleting it must not cancel that unrelated conversation.
+            if (controlsThisRun)
+                this.activeTurnLoop.updateGoal(undefined);
         }
         // 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);
+        if (had &&
+            this.activeGoalHook &&
+            this.lastSessionId === sessionId &&
+            (controlsThisRun || this.activeRuntimeGoal === null)) {
+            if (this.activeGoalHookAttached)
+                this.hooks.unregister("on_stop", this.activeGoalHook);
             this.activeGoalHook = null;
+            this.activeGoalHookAttached = false;
+            this.activeRuntimeGoal = null;
+            this.activePersistedRunGoal = null;
         }
         return had;
     }
+    /**
+     * Persist a workspace pointer through the Engine that owns the live bundle.
+     * Host-side workspace actions use this RPC-facing seam so advancing the disk
+     * revision also rebases the active run before its next progress write.
+     */
+    setSessionWorkspace(sessionId, workspace) {
+        if (!sessionId || !this.sessionManager.exists(sessionId))
+            return null;
+        try {
+            const stateRevision = this.sessionManager.setSessionWorkspace(sessionId, workspace);
+            if (this.activeRunSession?.state.sessionId === sessionId) {
+                Object.assign(this.activeRunSession.state, { workspace, stateRevision });
+            }
+            return workspace;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Reset a session's workspace pointer back to its main root. If the session is
      * actively running, mutate that live SessionBundle first so the run's next
@@ -2690,32 +2727,13 @@ export class Engine {
     releaseSessionWorkspace(sessionId) {
         if (!sessionId || !this.sessionManager.exists(sessionId))
             return null;
-        const mainRoot = this.sessionManager.readCwd(sessionId) ??
+        const mainRoot = this.sessionManager.readSessionMainRoot(sessionId) ??
             (this.activeRunSession?.state.sessionId === sessionId
                 ? this.activeRunSession.state.cwd
                 : undefined);
         if (!mainRoot)
             return null;
-        const workspace = { root: mainRoot, kind: "main" };
-        if (this.activeRunSession?.state.sessionId === sessionId) {
-            this.activeRunSession.state.workspace = workspace;
-        }
-        try {
-            const bundle = this.activeRunSession?.state.sessionId === sessionId
-                ? this.activeRunSession
-                : this.sessionManager.resume(sessionId);
-            bundle.state.workspace = workspace;
-            this.sessionManager.saveState(bundle.state);
-        }
-        catch {
-            try {
-                this.sessionManager.setSessionWorkspace(sessionId, workspace);
-            }
-            catch {
-                return null;
-            }
-        }
-        return workspace;
+        return this.setSessionWorkspace(sessionId, { root: mainRoot, kind: "main" });
     }
     injectContext(sessionId, content) {
         const session = this.sessionManager.resume(sessionId);
@@ -2740,6 +2758,42 @@ export class Engine {
         const session = this.sessionManager.resume(effectiveSessionId);
         const sourceMessages = this.compactedMessagesBySession.get(effectiveSessionId) ?? session.transcript.toMessages();
         const before = estimateTokens(sourceMessages);
+        const contextManager = await this.prepareContextManagerForSession(effectiveSessionId, session, sourceMessages, "force_compact");
+        // 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;
+        });
+        const compacted = await contextManager.forceSummarize(sourceMessages);
+        const after = estimateTokens(compacted);
+        this.compactedMessagesBySession.set(effectiveSessionId, compacted);
+        this.lastSessionId = effectiveSessionId;
+        this.lastMessages = compacted;
+        return {
+            before,
+            after,
+            strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
+        };
+    }
+    /**
+     * Lazily build (or reuse) the ContextManager for a resumed session and wire a
+     * PRIMARY-model summarizeFn onto it. Shared by forceCompact and
+     * archiveTurnRange: both need a summarizer on a session that may have been
+     * resumed-but-never-run (so no run wired one), and both bill compaction usage
+     * against the session.
+     *
+     * The PRIMARY model is used deliberately — automatic background compaction
+     * routes to the cheap aux model, but a user-/host-initiated compaction or
+     * range archival is low-frequency and demands fidelity (a dropped decision =
+     * the conversation "forgets"). Client-construction failure is logged and
+     * swallowed so the caller degrades gracefully (forceSummarize falls back to
+     * snip/window; summarizeRange returns the input untouched).
+     */
+    async prepareContextManagerForSession(effectiveSessionId, session, sourceMessages, op) {
         let contextManager = this.lastContextManager;
         if (!contextManager || this.lastSessionId !== effectiveSessionId) {
             contextManager = new ContextManager({
@@ -2750,88 +2804,86 @@ export class Engine {
             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);
+                this.sessionManager.recordAuxiliaryUsage(effectiveSessionId, usage, this.config.costStore?.serialize());
+                const latest = this.sessionManager.resume(effectiveSessionId).state;
+                const next = normalizeCumulativeUsageCounters(latest, latest.tokenUsage);
+                Object.assign(session.state, next, {
+                    tokenUsage: latest.tokenUsage,
+                    costState: latest.costState,
+                    stateRevision: latest.stateRevision,
+                });
                 return next;
             };
             contextManager.setSummarizeFn(this.buildSummarizeFn(primaryClient, recordCompactUsage));
         }
         catch (err) {
-            logger.warn("engine.force_compact_client_failed", {
+            logger.warn(`engine.${op}_client_failed`, {
                 error: err.message,
             });
         }
-        const compacted = await contextManager.forceSummarize(sourceMessages);
-        const after = estimateTokens(compacted);
-        this.compactedMessagesBySession.set(effectiveSessionId, compacted);
-        this.lastSessionId = effectiveSessionId;
-        this.lastMessages = compacted;
-        return {
-            before,
-            after,
-            strategy: after >= before ? "no compaction needed" : (compactStrategy ?? "compacted"),
-        };
+        return contextManager;
     }
-    stripInjectedContextMessages(messages, userContextMsg, dynamicContextMsg) {
-        const withoutDynamicContext = dynamicContextMsg
-            ? messages.filter((msg) => msg !== dynamicContextMsg)
-            : [...messages];
-        if (!userContextMsg || messages[0] !== userContextMsg) {
-            return withoutDynamicContext;
-        }
-        return withoutDynamicContext.slice(1);
+    /**
+     * Archive a caller-chosen contiguous message-index window `[range.start,
+     * range.end)` of a session into a single anchored summary, leaving everything
+     * outside the window untouched, and cache the result so a later
+     * forceCompact/resume reads the archived history. This is a generic
+     * range-archival facade over ContextManager.summarizeRange — the caller
+     * decides which span to collapse (the range is a half-open message-index
+     * window, matching summarizeRange). Returns token stats before/after; equal
+     * before/after means the window was empty or the summary was rejected.
+     */
+    async archiveTurnRange(sessionId, range) {
+        const effectiveSessionId = sessionId || this.lastSessionId;
+        if (!effectiveSessionId)
+            return { before: 0, after: 0 };
+        const session = this.sessionManager.resume(effectiveSessionId);
+        const sourceMessages = this.compactedMessagesBySession.get(effectiveSessionId) ?? session.transcript.toMessages();
+        const before = estimateTokens(sourceMessages);
+        const contextManager = await this.prepareContextManagerForSession(effectiveSessionId, session, sourceMessages, "archive_range");
+        // Range archival is initiated deliberately, not by a pressure heuristic;
+        // don't let a stale run callback retained on lastContextManager double-emit.
+        contextManager.setOnCompact(() => { });
+        const archived = await contextManager.summarizeRange(sourceMessages, range);
+        const after = estimateTokens(archived);
+        this.compactedMessagesBySession.set(effectiveSessionId, archived);
+        this.lastSessionId = effectiveSessionId;
+        this.lastMessages = archived;
+        return { before, after };
     }
-    recordCacheReadDiagnostics(sessionId, usage) {
-        const current = usage.cacheReadTokens;
-        if (current === undefined || !Number.isFinite(current))
-            return;
-        const previous = this.lastCacheReadBySid.get(sessionId);
-        this.lastCacheReadBySid.delete(sessionId);
-        this.lastCacheReadBySid.set(sessionId, current);
-        if (this.lastCacheReadBySid.size > CACHE_READ_DIAGNOSTIC_MAX_SESSIONS) {
-            const oldestSessionId = this.lastCacheReadBySid.keys().next().value;
-            if (oldestSessionId !== undefined)
-                this.lastCacheReadBySid.delete(oldestSessionId);
-        }
-        if (previous === undefined || previous < CACHE_READ_DROP_MIN_PREVIOUS_TOKENS)
+    recordCacheReadDiagnostics(sessionId, sample) {
+        const result = this.promptCacheDiagnostics.record(sessionId, sample);
+        if (result.kind === "scope_changed") {
+            logger.info("engine.cache_scope_changed", {
+                sessionId,
+                cacheScopeHash: sample.fingerprint.cacheScopeHash,
+            });
             return;
-        const dropRatio = previous > 0 ? current / previous : 1;
-        if (current <= CACHE_READ_DROP_MAX_CURRENT_TOKENS && dropRatio <= CACHE_READ_DROP_RATIO) {
-            logger.warn("engine.cache_read_drop", {
+        }
+        if (result.kind === "schema_changed") {
+            logger.info("engine.cache_diagnostic_schema_changed", {
                 sessionId,
-                previousCacheReadTokens: previous,
-                currentCacheReadTokens: current,
-                dropRatio,
-                hint: "Prompt cache read tokens dropped sharply. Check for changed cacheable prefix, stale dynamic context in history, tool/schema changes, or provider cache eviction.",
+                version: sample.fingerprint.version,
             });
+            return;
         }
+        if (result.kind !== "drop")
+            return;
+        logger.warn("engine.cache_read_drop", {
+            sessionId,
+            previousCacheReadTokens: result.previous.cacheReadTokens,
+            currentCacheReadTokens: result.current.cacheReadTokens,
+            dropRatio: result.dropRatio,
+            cause: result.attribution.cause,
+            changedPrefixes: result.attribution.changedPrefixes,
+            previousPrefix: result.previous.fingerprint,
+            currentPrefix: result.current.fingerprint,
+            hint: promptCacheDropHint(result.attribution),
+        });
     }
     getSettingsManager() {
         if (!this.settingsManager) {
@@ -2846,7 +2898,7 @@ export class Engine {
         this.getSettingsManager().saveUserSetting(key, value);
     }
     /**
-     * Read a settings value by dotted key (e.g. "arena.participants").
+     * Read a settings value by dotted key (e.g. "capabilities.foo.enabled").
      * Returns undefined if any segment is missing.
      */
     readSetting(key) {
@@ -2860,82 +2912,6 @@ export class Engine {
         }
         return target;
     }
-    buildPermissionConfig(mode, cwd, approvalRouter) {
-        const rules = [...this.preset.defaultPermissionRules];
-        // Memory tools: dream scope is the LLM's own workspace, so save/delete
-        // there go through without prompting. user-scope save/delete have no
-        // explicit allow rule here, so default-mode classifier fallback asks the
-        // user to confirm modifications. RegisteredTool.permissionDefault is only
-        // UI/metadata and is not read by the classifier.
-        rules.push({
-            tool: "MemorySave",
-            argsPattern: { scope: "^dream$" },
-            decision: "allow",
-            reason: "Dream scope is the LLM's auto-consolidation workspace",
-        });
-        rules.push({
-            tool: "MemoryDelete",
-            argsPattern: { scope: "^dream$" },
-            decision: "allow",
-            reason: "Dream scope is the LLM's auto-consolidation workspace",
-        });
-        if (mode === "acceptEdits" || mode === "bypassPermissions") {
-            rules.push({ tool: "Write", decision: "allow" });
-            rules.push({ tool: "Edit", decision: "allow" });
-        }
-        if (mode === "bypassPermissions") {
-            rules.push({ tool: "Bash", decision: "allow" });
-        }
-        try {
-            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);
-            }
-        }
-        catch {
-            // Settings not available — defaults only
-        }
-        let backend;
-        if (this.config.approvalBackend) {
-            backend =
-                mode === "auto"
-                    ? new AutoApprovalBackend(this.config.approvalBackend)
-                    : this.config.approvalBackend;
-        }
-        else if (mode === "auto") {
-            backend = new AutoApprovalBackend();
-        }
-        else {
-            // If a host installed an InteractiveApprovalBackend prompt fn
-            // (agent-server-stdio does this on boot via setInteractiveApprovalFn),
-            // use it so the UI gets a chance to approve/deny. Without this,
-            // every `ask` permission silently fell through to deny-all and
-            // the user saw "Permission denied by user" with NO modal — exactly
-            // the bug that motivated this fix.
-            let interactive;
-            if (approvalRouter) {
-                interactive =
-                    this.interactiveBackends.get(approvalRouter) ??
-                        new InteractiveApprovalBackend(approvalRouter);
-                this.interactiveBackends.set(approvalRouter, interactive);
-            }
-            else {
-                interactive = getInteractiveApprovalBackend();
-            }
-            if (interactive.hasPromptFn()) {
-                backend = interactive;
-            }
-            else {
-                backend = new HeadlessApprovalBackend(mode === "bypassPermissions"
-                    ? "approve-all"
-                    : mode === "dontAsk"
-                        ? "deny-all"
-                        : "deny-all");
-            }
-        }
-        return { rules, backend };
-    }
     /**
      * Switch permission mode at runtime. Idle updates apply immediately; busy
      * updates are committed atomically when the current run settles, so its
@@ -2943,34 +2919,10 @@ export class Engine {
      * Session-only — does not persist to settings.
      */
     setPermissionMode(mode) {
-        if (this.runInProgress) {
-            this.pendingPermissionMode = mode;
-            this.pendingPlanMode = mode === "plan";
-            return;
-        }
-        this.applyPermissionState(mode, mode === "plan");
-    }
-    applyPermissionState(mode, planMode) {
-        this.config = { ...this.config, permissionMode: mode };
-        this.permissionMode = mode;
-        this.planMode = planMode;
-        if (this.activePermission) {
-            const cwd = this.config.cwd ?? process.cwd();
-            const { rules, backend } = this.buildPermissionConfig(mode, cwd, this.activeApprovalRouter);
-            this.activePermission.reconfigure(mode, backend, rules);
-        }
-    }
-    applyPendingPermissionState() {
-        if (this.pendingPermissionMode === null)
-            return;
-        const mode = this.pendingPermissionMode;
-        const planMode = this.pendingPlanMode ?? mode === "plan";
-        this.pendingPermissionMode = null;
-        this.pendingPlanMode = null;
-        this.applyPermissionState(mode, planMode);
+        this.permissionController.setPermissionMode(mode);
     }
     getPermissionMode() {
-        return this.config.permissionMode ?? "acceptEdits";
+        return this.permissionController.getPermissionMode();
     }
     /**
      * Extend the in-flight run's turn ceiling and/or goal budgets (TODO 3.1 —
@@ -2990,20 +2942,14 @@ export class Engine {
      * rule set buildPermissionConfig does, without constructing a backend.
      */
     getPermissionRules() {
-        return this.buildPermissionConfig(this.getPermissionMode(), this.config.cwd ?? process.cwd(), this.activeApprovalRouter).rules;
+        return this.permissionController.getPermissionRules();
     }
     /**
      * Toggle plan mode directly. Called by the Plan tool (Task 7) via ToolContext.engine.
      * Also syncs permissionMode to keep both fields consistent.
      */
     setPlanMode(value) {
-        if (value) {
-            this.setPermissionMode("plan");
-        }
-        else if ((this.pendingPermissionMode ?? this.permissionMode) === "plan") {
-            // Leaving plan mode: drop back to the default.
-            this.setPermissionMode("acceptEdits");
-        }
+        this.permissionController.setPlanMode(value);
     }
     /**
      * Block until a background agent's state changes (finishes / its result is
@@ -3071,9 +3017,9 @@ export class Engine {
      * directory is read once rather than every turn. A new cwd (e.g. via
      * run({ cwd })) reloads.
      */
-    getAgentDefinitions(cwd) {
-        const disabledAgents = this.readDisabledAgents(cwd);
-        const disabledPlugins = this.readDisabledLists().disabledPlugins;
+    getAgentDefinitions(cwd, explicitProfileOverrides) {
+        const disabledAgents = this.readDisabledAgents(cwd, explicitProfileOverrides);
+        const disabledPlugins = this.readDisabledLists(cwd, explicitProfileOverrides).disabledPlugins;
         const disabledKey = [...disabledAgents, "::", ...disabledPlugins].slice().sort().join(" ");
         if (this.agentDefsCache?.cwd !== cwd || this.agentDefsCache.disabledKey !== disabledKey) {
             this.agentDefsCache = {
@@ -3093,14 +3039,12 @@ export class Engine {
      * (getForScope) so inherit survives. No cwd / no overlay → baseline
      * unchanged. Mirrors readDisabledLists (skills/plugins).
      */
-    readDisabledAgents(cwd) {
+    readDisabledAgents(cwd, explicitProfileOverrides) {
         try {
             const sm = this.getSettingsManager();
             const settings = sm.get();
             const baseline = Array.isArray(settings.disabledAgents) ? settings.disabledAgents : [];
-            const overrides = cwd
-                ? sm.getForScope("project", cwd).capabilityOverrides
-                : undefined;
+            const overrides = effectiveProjectOverrides(sm, cwd, explicitProfileOverrides);
             return effectiveDisabledList(baseline, overrides?.agents);
         }
         catch {
@@ -3114,12 +3058,11 @@ export class Engine {
      * are already narrowed by resolveChildToolScope. No cwd / error → undefined,
      * so the caller's baseline builtin lists pass through unchanged.
      */
-    readBuiltinOverride(cwd) {
+    readBuiltinOverride(cwd, explicitProfileOverrides) {
         if (this.config.isSubAgent === true || !cwd)
             return undefined;
         try {
-            const overrides = this.getSettingsManager().getForScope("project", cwd)
-                .capabilityOverrides;
+            const overrides = effectiveProjectOverrides(this.getSettingsManager(), cwd, explicitProfileOverrides);
             return overrides?.builtin;
         }
         catch {
@@ -3131,171 +3074,32 @@ export class Engine {
      * overlays turn-specific fields like sandbox and subAgentSpawner) and
      * by tests that want a ToolContext without a full run() cycle.
      */
-    resolveSandboxWithoutRuntime(config, cwd) {
-        const key = sandboxCacheKey(config, cwd);
-        let cached = this.sandboxCache.get(key);
-        if (!cached) {
-            cached = resolveSandboxBackend(config, cwd);
-            // Mirror EngineRuntime.resolveSandbox: don't cache a rejection, or an
-            // explicit-mode probe that throws stays sticky until process restart even
-            // after the user fixes the config.
-            cached.catch(() => {
-                if (this.sandboxCache.get(key) === cached)
-                    this.sandboxCache.delete(key);
+    buildToolContext(cwd = this.config.cwd ?? process.cwd(), explicitProfileOverrides, profileMemoryDir) {
+        const { disabledSkills, disabledPlugins } = this.readDisabledLists(cwd, explicitProfileOverrides);
+        const capabilityServices = Object.fromEntries(this.capabilities.flatMap((capability) => {
+            if (!capability.createToolService)
+                return [];
+            const service = capability.createToolService({
+                isSubAgent: this.config.isSubAgent === true,
+                settings: this.getSettingsManager(),
+                resolveSandbox: (cwd) => this.runEnvironmentResolver.resolveSandbox(cwd),
+                readShellEnv: (cwd) => this.runEnvironmentResolver.readShellEnv(cwd),
+                getSessionManager: () => this.sessionManager,
             });
-            this.sandboxCache.set(key, cached);
-        }
-        return cached;
-    }
-    resolveSandboxConfigForCwd(cwd) {
-        // Priority: config.sandbox → project settings.sandbox → global → per-run
-        // default. Read UNMERGED per-scope (getForScope) so a project that wrote no
-        // sandbox genuinely follows global, rather than inheriting global's mode and
-        // looking like it set one. Fixes "项目级配了不生效" + the scope model.
-        let projectSandbox;
-        let globalSandbox;
-        try {
-            const sm = this.getSettingsManager();
-            if (this.config.isSubAgent !== true) {
-                projectSandbox = sm.getForScope("project", cwd).sandbox;
-            }
-            globalSandbox = sm.getForScope("user").sandbox;
-        }
-        catch {
-            // settings unavailable → fall through to per-run default
-        }
-        return resolveSandboxConfig(this.config.sandbox, projectSandbox, globalSandbox, this.config.headless === true);
-    }
-    /**
-     * Build the shell env layered onto the Bash tool / background shells (see
-     * mergeShellEnv). Three user-configured sources, merged lowest → highest:
-     *
-     *   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(getCredentialAccess().envExposures(cwd, 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;
-        }
-    }
-    readWorktreeBranchPrefix(cwd) {
-        if (this.config.isSubAgent === true || !cwd)
-            return undefined;
-        try {
-            const settings = this.getSettingsManager().get();
-            return settings.worktree?.branchPrefix;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    async resolveWorktreeSetupSandbox(cwd) {
-        if (!cwd)
-            return undefined;
-        const sandboxConfig = this.resolveSandboxConfigForCwd(cwd);
-        const sandboxBackend = this.runtime
-            ? await this.runtime.resolveSandbox(sandboxConfig, cwd)
-            : await this.resolveSandboxWithoutRuntime(sandboxConfig, cwd);
-        return sandboxBackend.name === "off"
-            ? sandboxBackend
-            : { ...sandboxBackend, network: sandboxConfig.network };
-    }
-    readWorktreeSetupShellEnv(cwd) {
-        return this.readShellEnv(cwd);
-    }
-    buildToolContext() {
-        const { disabledSkills, disabledPlugins } = this.readDisabledLists();
+            return [[capability.id, service]];
+        }));
         const ctx = {
-            shellEnv: this.readShellEnv(this.config.cwd),
-            cwd: this.config.cwd ?? process.cwd(),
+            shellEnv: this.runEnvironmentResolver.readShellEnv(cwd),
+            cwd,
+            profileMemoryDir,
             llmConfig: this.config.llm,
             modelPool: this.modelPool,
             toolRegistry: this.toolRegistry,
+            capabilityServices,
             askUser: this.config.askUser,
             browser: this.config.browserBridge,
             workspace: this.config.workspaceBridge,
+            panels: this.config.panelBridge,
             injectCredentialToBrowser: this.config.injectCredentialToBrowser,
             isSubAgent: this.config.isSubAgent === true,
             // Credential tools narrow their disk reads to this scope: a project/
@@ -3332,7 +3136,7 @@ export class Engine {
      * reads — the prompt composer and the tool context will always see
      * the same snapshot.
      */
-    readDisabledLists() {
+    readDisabledLists(cwd = this.config.cwd, explicitProfileOverrides) {
         if (this.config.isSubAgent === true) {
             return { disabledSkills: [], disabledPlugins: [], disabledPluginHooks: [] };
         }
@@ -3340,7 +3144,7 @@ export class Engine {
         // 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);
+        return computeEffectiveDisabledLists(this.getSettingsManager(), cwd, explicitProfileOverrides);
     }
     /**
      * Public view of the folded disabled lists, for hosts that need the
@@ -3382,40 +3186,7 @@ export class Engine {
      * falls back to its built-in defaults.
      */
     readMemoriesConfig() {
-        try {
-            const settings = this.getSettingsManager().get();
-            return settings.memories;
-        }
-        catch {
-            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);
+        return this.auxiliaryPipeline.readMemoriesConfig();
     }
 }
 /**