@caupulican/pi-adaptative 0.81.42 → 0.81.43

package/dist/core/agent-session.js

@@ -11,6 +11,7 @@ import { buildForegroundEnvelope, formatForegroundEnvelopeObservation } from "./
 import { evaluateToolGate } from "./autonomy/gates.js";
 import { AutonomyTelemetry } from "./autonomy-telemetry.js";
 import { BackgroundLaneController } from "./background-lane-controller.js";
+import { BACKGROUND_TOOL_TASK_CUSTOM_TYPE, BackgroundToolTaskController, createBackgroundToolTerminalMessage, DEFAULT_BACKGROUND_TOOL_CALL_AFTER_MS, loadBackgroundToolTaskRecordsNewestFirst, } from "./background-tool-task-controller.js";
 import { BashExecutionController } from "./bash-execution-controller.js";
 import { CompactionController } from "./compaction-controller.js";
 import { CompactionSupport } from "./compaction-support.js";
@@ -60,7 +61,7 @@ import { TOOL_RECOVERY_EVENT_LOG_FILE } from "./tool-recovery-log-records.js";
 import { ToolRecoveryLogger } from "./tool-recovery-logger.js";
 import { ToolPerformanceStore } from "./tool-selection/tool-performance-store.js";
 import { formatToolSelectionReport, ToolSelectionController } from "./tool-selection/tool-selection-controller.js";
-import { disposePersistentShellSession } from "./tools/shell-session.js";
+import { disposeShellExecutionSession } from "./tools/shell-execution-session.js";
 // ============================================================================
 // Stream-idle watchdog wiring
 // ============================================================================
@@ -99,124 +100,126 @@ import { RUNAWAY_STOP_CUSTOM_TYPE, TOOL_VALIDATION_ESCALATION_CUSTOM_TYPE } from
 // AgentSession Class
 // ============================================================================
 export class AgentSession {
-    agent;
-    sessionManager;
-    settingsManager;
-    capabilityEnvelope;
-    _scopedModels;
-    // Event subscription state
-    _unsubscribeAgent;
-    _eventListeners = [];
-    _extensionsChangedListeners = [];
-    _steeringMessages = [];
-    _followUpMessages = [];
-    _queuedExtensionCommands = [];
-    _pendingNextTurnMessages = [];
-    _streamingPromptSubmissionTail = Promise.resolve();
-    /**
-     * The last tool set requested via setActiveToolsByName BEFORE model-capability filtering, so
-     * switching from a small-window model back to a large one restores the full requested set.
-     */
-    _requestedActiveToolNames;
-    _unboundToolGrantWarnings = [];
-    _branchSummaryAbortController = undefined;
-    _modelSelection;
-    _bash;
-    _profileFilter;
-    _toolGate;
-    _toolSelection;
-    _extensionRunner;
-    _turnIndex = 0;
-    _currentForegroundEnvelope;
-    _resourceLoader;
-    _customTools;
-    _cwd;
-    /** Per-agent persistent shell session identity: stable across runtime reloads, disposed with the session. */
-    _shellSessionKey = `agent:${randomUUID()}`;
-    _agentDir;
-    _collectWorkspaceSources;
-    _localRuntimeController;
-    _toolProtocol;
-    _prefixWarmer;
-    _completedPrefixWarms = new Set();
-    /** Assembles the session's base system prompt from live session state (see
-     * system-prompt-builder.ts); owns the paired _baseSystemPromptOptions. */
-    _systemPromptBuilder;
-    /** Autonomy telemetry sink + status/diagnostic snapshots (see autonomy-telemetry.ts); owns
-     * the latest gate outcome and the bounded gate-outcome history. */
-    _autonomyTelemetry;
-    /** Goal auto-continue + research lane + profile-bound worker delegation + model-fitness probe (see
-     * background-lane-controller.ts); owns the lane timers/guards, the last research-lane skip
-     * reason, the live LaneTracker, and the in-flight research/worker abort controllers. */
-    _backgroundLanes;
-    _humanInput;
-    /** Plug-and-play memory subsystem (see memory-controller.ts); owns the OKF retrieval provider, the
-     * latest retrieval/prompt-inclusion reports, the reload-safe MemoryManager, the recall
-     * effectiveness tracker, and the extension-contributed pending providers. */
-    _memory;
-    _compactionSupport;
-    _compaction;
-    /** Per-turn context-shaping subsystem (see context-pipeline.ts); owns the latest
-     * audit/policy/correlation/enforcement/gc reports, the brain-curation sidecar + its skip reasons,
-     * and the tool-output artifact store. Invoked stage-by-stage from the context transform. */
-    _pipeline;
-    _extensionRunnerRef;
-    _initialActiveToolNames;
-    _allowedToolNames;
-    _excludedToolNames;
-    _toolProfileFilter;
-    _isExplicitModel;
-    _isExplicitThinking;
-    _gatewayRegistry = new GatewayRegistry();
-    /** Usage/cost/stats accounting, /context estimate, and session export (see session-analytics.ts);
-     * owns the spawned-usage and daily-usage memo caches. */
-    _analytics;
-    _treeNavigator;
-    _lastCostGuardDecision;
-    /**
-     * `getSpawnedUsage().cost` snapshotted at the start of the CURRENT foreground prompt cycle (see
-     * `_promptUnserialized`), so the cost guard can attribute only background/spawned spend since THIS
-     * turn began, not the session's entire lifetime spend. Reset on every new user prompt; every
-     * round-trip within the same turn (tool-call iterations) shares this one baseline.
-     */
-    _costGuardTurnBaselineUsd = 0;
-    /** Per-turn model-router subsystem (see model-router-controller.ts); owns the transient route/intent,
-     * the cheap-turn session buffer, the escalation/retry flags, and the sticky last-decision/skip-reason
-     * used by the status report. Its parallel routed drive path delegates every turn back to
-     * {@link _runAgentPrompt} so the drive loop stays host-side. */
-    _modelRouter;
-    _foregroundRecovery;
-    _failureCorpus;
-    _toolRecoveryLogger;
-    _toolRecoveryEventLogPath;
-    _skillCuratorInstance;
-    _disposed = false;
-    _disposeCompletion;
-    _reflectionAbort = new AbortController();
-    /** Native reflection engine + learning-apply/rollback path (see reflection-controller.ts); owns no
-     * session state, applies durable writes through the bundled memory tool and the session log. */
-    _reflection;
-    /** Durable goal lifecycle, accounting, and raw continuation loop. */
-    _goals;
-    _isChildSession;
-    _baseToolsOverride;
-    _sessionStartEvent;
-    _extensionUIContext;
-    _extensionMode = "print";
-    _extensionCommandContextActions;
-    _extensionAbortHandler;
-    _extensionShutdownHandler;
-    _extensionErrorListener;
-    _extensionErrorUnsubscriber;
-    _modelRegistry;
-    /** Tool-registry assembly + the self-modification-safe extension reload (see runtime-builder.ts);
-     * owns the base/wrapped tool definitions, the live tool registry, and the per-tool prompt
-     * snippet/guideline maps. The reload snapshot spans host/agent state reached through its deps. */
-    _runtimeBuilder;
-    // Base system prompt (without extension appends) - used to apply fresh appends each turn.
-    // The paired _baseSystemPromptOptions and their construction live in SystemPromptBuilder.
-    _baseSystemPrompt = "";
     constructor(config) {
+        this._eventListeners = [];
+        this._extensionsChangedListeners = [];
+        this._steeringMessages = [];
+        this._followUpMessages = [];
+        this._queuedExtensionCommands = [];
+        this._pendingNextTurnMessages = [];
+        this._streamingPromptSubmissionTail = Promise.resolve();
+        this._unboundToolGrantWarnings = [];
+        this._branchSummaryAbortController = undefined;
+        this._turnIndex = 0;
+        /** Per-agent persistent shell session identity: stable across runtime reloads, disposed with the session. */
+        this._shellSessionKey = `agent:${randomUUID()}`;
+        this._completedPrefixWarms = new Set();
+        this._gatewayRegistry = new GatewayRegistry();
+        /**
+         * `getSpawnedUsage().cost` snapshotted at the start of the CURRENT foreground prompt cycle (see
+         * `_promptUnserialized`), so the cost guard can attribute only background/spawned spend since THIS
+         * turn began, not the session's entire lifetime spend. Reset on every new user prompt; every
+         * round-trip within the same turn (tool-call iterations) shares this one baseline.
+         */
+        this._costGuardTurnBaselineUsd = 0;
+        this._disposed = false;
+        this._reflectionAbort = new AbortController();
+        this._extensionMode = "print";
+        // Base system prompt (without extension appends) - used to apply fresh appends each turn.
+        // The paired _baseSystemPromptOptions and their construction live in SystemPromptBuilder.
+        this._baseSystemPrompt = "";
+        /**
+         * User messages already painted to the UI by an early, synthetic `message_start` fired from
+         * `_promptUnserialized` — before the model-router judge's bounded LLM call — so the prompt
+         * appears immediately instead of hanging until routing finishes. The real agent-loop run emits
+         * its own authoritative `message_start` for the SAME message object once the turn actually
+         * starts; `_handleAgentEvent` consumes (deletes) it from this set to suppress that one duplicate
+         * listener notification. Persistence is untouched: it stays keyed off `message_end`, which is
+         * never added here and never suppressed.
+         */
+        this._earlyDisplayedUserMessages = new Set();
+        /** Internal handler for agent events - shared by subscribe and reconnect */
+        this._handleAgentEvent = async (event) => {
+            // When a user message starts, check if it's from either queue and remove it BEFORE emitting
+            // This ensures the UI sees the updated queue state
+            if (event.type === "message_start" && event.message.role === "user") {
+                this._compaction.resetOverflowRecovery();
+                const messageText = this._getUserMessageText(event.message);
+                if (messageText) {
+                    // Check steering queue first
+                    const steeringIndex = this._steeringMessages.indexOf(messageText);
+                    if (steeringIndex !== -1) {
+                        this._steeringMessages.splice(steeringIndex, 1);
+                        this._emitQueueUpdate();
+                    }
+                    else {
+                        // Check follow-up queue
+                        const followUpIndex = this._followUpMessages.indexOf(messageText);
+                        if (followUpIndex !== -1) {
+                            this._followUpMessages.splice(followUpIndex, 1);
+                            this._emitQueueUpdate();
+                        }
+                    }
+                }
+            }
+            // Emit to extensions first
+            await this._emitExtensionEvent(event);
+            const suppressRetryPromptEvent = this._modelRouter.isRetryInFlight() &&
+                (event.type === "message_start" || event.type === "message_end") &&
+                (event.message.role === "user" || event.message.role === "custom");
+            // This is the authoritative message_start for a user message already painted early (see
+            // _promptUnserialized). Set#delete both tests and consumes membership in one step, so only
+            // this one duplicate is suppressed and a later, unrelated user message is never affected.
+            const suppressAlreadyDisplayedUserMessage = event.type === "message_start" &&
+                event.message.role === "user" &&
+                this._earlyDisplayedUserMessages.delete(event.message);
+            // Notify all listeners
+            if (!suppressRetryPromptEvent && !suppressAlreadyDisplayedUserMessage) {
+                this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
+            }
+            // Handle session/context retention. Tool result details are UI/log metadata,
+            // not provider-visible content, and large graph/search payloads can otherwise
+            // accumulate until the interactive Node process hits the V8 heap limit.
+            if (event.type === "message_end") {
+                compactToolResultDetailsForRetention(event.message);
+                let messagePersisted = false;
+                // While a cheap routed turn is buffering, its messages are captured for later flush/discard
+                // instead of persisted here (see ModelRouterController.captureSessionMessage).
+                if (this._modelRouter.captureSessionMessage(event.message)) {
+                    // buffered by the router; persistence is deferred to the routed-turn flush
+                }
+                // Check if this is a custom message from extensions
+                else if (event.message.role === "custom") {
+                    // Persist as CustomMessageEntry
+                    this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
+                    messagePersisted = true;
+                }
+                else if (event.message.role === "user" ||
+                    event.message.role === "assistant" ||
+                    event.message.role === "toolResult") {
+                    // Regular LLM message - persist as SessionMessageEntry
+                    this.sessionManager.appendMessage(event.message);
+                    messagePersisted = true;
+                }
+                // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
+                // Track the response for ordered retry/failover/compaction handling after agent_end.
+                if (event.message.role === "assistant") {
+                    const assistantMsg = event.message;
+                    if (messagePersisted) {
+                        this._pipeline.observeProviderUsage(this.agent.state.messages, assistantMsg);
+                    }
+                    this._foregroundRecovery.observeAssistant(assistantMsg);
+                }
+            }
+            if (event.type === "agent_end" && !this._willRetryAfterAgentEnd(event)) {
+                const contextHeadroomPct = Math.max(0, 100 - (this.getContextUsage()?.percent ?? 0));
+                const reflectionTurn = this._reflection.scheduleFromTurn(event.messages, contextHeadroomPct);
+                // The shared projection excludes raw tool-result payloads and bounds both roles before any
+                // provider sees the turn. Synchronization is serialized in the background by MemoryController.
+                this._memory.scheduleTurnSync(reflectionTurn.userText, reflectionTurn.assistantText);
+                this._humanInput.schedulePendingWorkerInputs();
+            }
+        };
         this.agent = config.agent;
         // Bound every provider stream this session starts against a silently dead connection: a
         // stall aborts the inner request and surfaces as a retryable "stream stalled" error, which
@@ -445,6 +448,25 @@ export class AgentSession {
             addSpawnedUsage: (usage, opts) => this.addSpawnedUsage(usage, opts),
             runIsolatedCompletion: (opts) => this.runIsolatedCompletion(opts),
         });
+        this._backgroundToolTasks = new BackgroundToolTaskController({
+            getSessionId: () => this.sessionManager.getSessionId(),
+            getArtifactStore: () => this._getToolArtifactStore(),
+            loadPersistedRecordsNewestFirst: () => loadBackgroundToolTaskRecordsNewestFirst(this.sessionManager),
+            persist: (record) => this.sessionManager.appendCustomEntry(BACKGROUND_TOOL_TASK_CUSTOM_TYPE, record),
+            notifyTerminal: (record, options) => this._notifyBackgroundToolTerminal(record, options.wakeParent),
+            onLiveTasksChanged: (tasks) => this._emit({ type: "background_tools", tasks }),
+            recordUsage: (taskId, usage) => {
+                this.addSpawnedUsage(usage, {
+                    label: "background-tool",
+                    sourceSessionId: this.sessionManager.getSessionId(),
+                    reportId: `background-tool:${this.sessionManager.getSessionId()}:${taskId}`,
+                });
+            },
+            onError: (message, error) => this._emit({
+                type: "warning",
+                message: `${message}: ${error instanceof Error ? error.message : String(error)}`,
+            }),
+        });
         const failureCorpusPath = stateFile(this._agentDir, "failure-corpus.jsonl");
         this._toolRecoveryEventLogPath = stateFile(this._agentDir, TOOL_RECOVERY_EVENT_LOG_FILE);
         const toolRepairSettings = this._toolProtocol.getRepairSettings();
@@ -471,6 +493,7 @@ export class AgentSession {
             emit: (event) => this._emit(event),
             estimateCurrentContextTokens: (messages) => this._pipeline.estimateCurrentContextTokens(messages),
             buildPreDigest: () => this._buildCompactionPreDigest(),
+            getMemoryPreCompressInsight: () => this._memory.onPreCompress(),
             refreshAfterCompaction: () => this._refreshAfterCompaction(),
             getFailureCorpus: () => this._failureCorpus,
             measureLiveContextTokens: () => this._measureLiveContextTokensForCompaction(),
@@ -613,6 +636,7 @@ export class AgentSession {
             reapplyActiveProfileModelSettings: () => this._profileFilter.reapplyActiveProfileModelSettings(),
             notifyExtensionsChanged: () => this._notifyExtensionsChanged(),
             getToolArtifactStore: () => this._getToolArtifactStore(),
+            getToolTaskDependencies: () => this._backgroundToolTasks,
             getSessionImageStore: () => this._getSessionImageStore(),
             getMemoryManager: () => this._memory.getMemoryManager(),
             getMemoryAuditDiagnostics: () => this._memory.getMemoryAuditDiagnostics(),
@@ -1229,6 +1253,7 @@ export class AgentSession {
         return [
             this._toolProtocol.formatRepairHealth(this._toolRecoveryLogger.getStats()),
             formatToolSelectionReport(this._toolSelection.getReport()),
+            this._toolSelection.formatTimingReport(),
         ].join("\n\n");
     }
     async flushToolRecoveryLogsForTests(timeoutMs = 1000) {
@@ -1286,6 +1311,9 @@ export class AgentSession {
     _installAgentToolHooks() {
         this.agent.beforeToolCall = this._toolGate.beforeToolCall;
         this.agent.afterToolCall = this._toolGate.afterToolCall;
+        this.agent.backgroundToolCallAfterMs = DEFAULT_BACKGROUND_TOOL_CALL_AFTER_MS;
+        this.agent.handoffToolCall = (context) => this.getActiveToolNames().includes("tool_task") ? this._backgroundToolTasks.handoff(context) : undefined;
+        this.agent.subscribeToolCallHandoffRequest = (toolCallId, request) => this._backgroundToolTasks.subscribeHandoffRequest(toolCallId, request);
         this.agent.onRunawayStop = (info) => this._handleRunawayStop(info);
         this.agent.onToolValidationEscalation = (event) => this._handleToolValidationEscalation(event);
     }
@@ -1407,6 +1435,19 @@ export class AgentSession {
             details: { records: included },
         }, { triggerTurn: !ownerQuestionWillWakeParent, deliverAs: "followUp" });
     }
+    async _notifyBackgroundToolTerminal(record, wakeParent) {
+        if (!wakeParent)
+            return;
+        if (this._disposed)
+            throw new Error("Session disposed before background tool terminal handoff was delivered");
+        await this.agent.waitForIdle();
+        if (this._disposed)
+            throw new Error("Session disposed before background tool terminal handoff was delivered");
+        await this.sendCustomMessage(createBackgroundToolTerminalMessage(record), {
+            triggerTurn: true,
+            deliverAs: "followUp",
+        });
+    }
     _emitQueueUpdate() {
         this._emit({
             type: "queue_update",
@@ -1415,93 +1456,6 @@ export class AgentSession {
             commands: [...this._queuedExtensionCommands],
         });
     }
-    /**
-     * User messages already painted to the UI by an early, synthetic `message_start` fired from
-     * `_promptUnserialized` — before the model-router judge's bounded LLM call — so the prompt
-     * appears immediately instead of hanging until routing finishes. The real agent-loop run emits
-     * its own authoritative `message_start` for the SAME message object once the turn actually
-     * starts; `_handleAgentEvent` consumes (deletes) it from this set to suppress that one duplicate
-     * listener notification. Persistence is untouched: it stays keyed off `message_end`, which is
-     * never added here and never suppressed.
-     */
-    _earlyDisplayedUserMessages = new Set();
-    /** Internal handler for agent events - shared by subscribe and reconnect */
-    _handleAgentEvent = async (event) => {
-        // When a user message starts, check if it's from either queue and remove it BEFORE emitting
-        // This ensures the UI sees the updated queue state
-        if (event.type === "message_start" && event.message.role === "user") {
-            this._compaction.resetOverflowRecovery();
-            const messageText = this._getUserMessageText(event.message);
-            if (messageText) {
-                // Check steering queue first
-                const steeringIndex = this._steeringMessages.indexOf(messageText);
-                if (steeringIndex !== -1) {
-                    this._steeringMessages.splice(steeringIndex, 1);
-                    this._emitQueueUpdate();
-                }
-                else {
-                    // Check follow-up queue
-                    const followUpIndex = this._followUpMessages.indexOf(messageText);
-                    if (followUpIndex !== -1) {
-                        this._followUpMessages.splice(followUpIndex, 1);
-                        this._emitQueueUpdate();
-                    }
-                }
-            }
-        }
-        // Emit to extensions first
-        await this._emitExtensionEvent(event);
-        const suppressRetryPromptEvent = this._modelRouter.isRetryInFlight() &&
-            (event.type === "message_start" || event.type === "message_end") &&
-            (event.message.role === "user" || event.message.role === "custom");
-        // This is the authoritative message_start for a user message already painted early (see
-        // _promptUnserialized). Set#delete both tests and consumes membership in one step, so only
-        // this one duplicate is suppressed and a later, unrelated user message is never affected.
-        const suppressAlreadyDisplayedUserMessage = event.type === "message_start" &&
-            event.message.role === "user" &&
-            this._earlyDisplayedUserMessages.delete(event.message);
-        // Notify all listeners
-        if (!suppressRetryPromptEvent && !suppressAlreadyDisplayedUserMessage) {
-            this._emit(event.type === "agent_end" ? { ...event, willRetry: this._willRetryAfterAgentEnd(event) } : event);
-        }
-        // Handle session/context retention. Tool result details are UI/log metadata,
-        // not provider-visible content, and large graph/search payloads can otherwise
-        // accumulate until the interactive Node process hits the V8 heap limit.
-        if (event.type === "message_end") {
-            compactToolResultDetailsForRetention(event.message);
-            let messagePersisted = false;
-            // While a cheap routed turn is buffering, its messages are captured for later flush/discard
-            // instead of persisted here (see ModelRouterController.captureSessionMessage).
-            if (this._modelRouter.captureSessionMessage(event.message)) {
-                // buffered by the router; persistence is deferred to the routed-turn flush
-            }
-            // Check if this is a custom message from extensions
-            else if (event.message.role === "custom") {
-                // Persist as CustomMessageEntry
-                this.sessionManager.appendCustomMessageEntry(event.message.customType, event.message.content, event.message.display, event.message.details);
-                messagePersisted = true;
-            }
-            else if (event.message.role === "user" ||
-                event.message.role === "assistant" ||
-                event.message.role === "toolResult") {
-                // Regular LLM message - persist as SessionMessageEntry
-                this.sessionManager.appendMessage(event.message);
-                messagePersisted = true;
-            }
-            // Other message types (bashExecution, compactionSummary, branchSummary) are persisted elsewhere
-            // Track the response for ordered retry/failover/compaction handling after agent_end.
-            if (event.message.role === "assistant") {
-                const assistantMsg = event.message;
-                if (messagePersisted) {
-                    this._pipeline.observeProviderUsage(this.agent.state.messages, assistantMsg);
-                }
-                this._foregroundRecovery.observeAssistant(assistantMsg);
-            }
-        }
-        if (event.type === "agent_end" && !this._willRetryAfterAgentEnd(event)) {
-            this._humanInput.schedulePendingWorkerInputs();
-        }
-    };
     _willRetryAfterAgentEnd(event) {
         return this._foregroundRecovery.willRetryAfterAgentEnd(event);
     }
@@ -1717,22 +1671,29 @@ export class AgentSession {
         safely(() => this.abortCompaction());
         safely(() => this.abortBranchSummary());
         safely(() => this.abortBash());
-        safely(() => disposePersistentShellSession(this._shellSessionKey));
+        safely(() => disposeShellExecutionSession(this._shellSessionKey));
         safely(() => this._cancelPrefixWarm());
         safely(() => this.agent.abort());
         track(() => this._gatewayRegistry.stop());
+        track(() => this._backgroundToolTasks.shutdown());
+        safely(() => this._reflection.cancelScheduled());
         safely(() => this._reflectionAbort.abort());
         safely(() => this._backgroundLanes.abortInFlightLanes());
         safely(() => {
             this.agent.afterToolCall = undefined;
+            this.agent.handoffToolCall = undefined;
+            this.agent.subscribeToolCallHandoffRequest = undefined;
             this.agent.transformContext = undefined;
         });
         safely(() => this._extensionRunner.invalidate());
         safely(() => this._disconnectFromAgent());
         this._eventListeners = [];
-        // Best-effort memory cleanup (release locks/handles). Write-side onSessionEnd is wired on a
-        // true session-end hook; file-store shutdown is a no-op.
-        track(() => this._memory.getMemoryManager().shutdownAll());
+        // Let an aborted in-flight reflection reach its terminal state, then flush session-owned write
+        // hooks before releasing provider locks/handles. This prevents a late write racing shutdown.
+        track(async () => {
+            await this._reflection.waitForActivePass();
+            await this._memory.shutdown();
+        });
         track(() => this._toolRecoveryLogger.shutdown());
         safely(() => cleanupSessionResources(this.sessionId));
         // Best-effort final sweep for any grep/find artifact already released (reference
@@ -1834,6 +1795,8 @@ export class AgentSession {
      * end up active while still being handed an artifact store (gated on "allowed" in
      * `_buildRuntime`) with no active tool able to resolve the resulting
      * "Full output: artifact tool-output:<id>" handle.
+     * Other tools, including tool_task, activate only when explicitly requested (or present in the
+     * shared default request) and after surviving model-capability filtering.
      */
     setActiveToolsByName(toolNames) {
         // Model capability: small-window models get a reduced tool surface derived from the model's
@@ -1872,6 +1835,12 @@ export class AgentSession {
         this.agent.state.systemPrompt = this._baseSystemPrompt;
         this._checkContextWindowUsageWarning();
     }
+    /** Request immediate transfer of one or all currently-running foreground tool calls. */
+    backgroundRunningToolCalls(toolCallId) {
+        if (!this.getActiveToolNames().includes("tool_task"))
+            return 0;
+        return this._backgroundToolTasks.requestHandoff(toolCallId);
+    }
     /** Whether compaction or branch summarization is currently running */
     get isCompacting() {
         return this._compaction.isRunning() || this._branchSummaryAbortController !== undefined;
@@ -2105,6 +2074,15 @@ export class AgentSession {
                 expandedText = this._expandSkillCommand(expandedText);
                 expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
             }
+            if (!options?.internalContextType) {
+                const admission = this._goals.admitExplicitChatGoal(expandedText);
+                if (admission.status === "unfinished_goal_exists") {
+                    this._emit({
+                        type: "warning",
+                        message: `Explicit chat goal was not started because unfinished goal '${admission.state.goalId}' is ${admission.state.status}. Complete, clear, or explicitly replace it first.`,
+                    });
+                }
+            }
             // If streaming — or waiting out a retry backoff, which is still an active
             // operation — queue via steer() or followUp() instead of starting a
             // concurrent run that would race the pending retry continuation.
@@ -2379,6 +2357,13 @@ export class AgentSession {
             return text; // Return original on error
         }
     }
+    /** Reject extension commands, then expand a queued message through the shared skill/template path. */
+    _prepareQueuedMessageText(text) {
+        if (text.startsWith("/")) {
+            this._throwIfExtensionCommand(text);
+        }
+        return expandPromptTemplate(this._expandSkillCommand(text), [...this.promptTemplates]);
+    }
     /**
      * Queue a steering message while the agent is running.
      * Delivered after the current assistant turn finishes executing its tool calls,
@@ -2388,14 +2373,7 @@ export class AgentSession {
      * @throws Error if text is an extension command
      */
     async steer(text, images) {
-        // Check for extension commands (cannot be queued)
-        if (text.startsWith("/")) {
-            this._throwIfExtensionCommand(text);
-        }
-        // Expand skill commands and prompt templates
-        let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-        await this._queueSteer(expandedText, images);
+        await this._queueSteer(this._prepareQueuedMessageText(text), images);
     }
     /**
      * Queue a follow-up message to be processed after the agent finishes.
@@ -2405,14 +2383,7 @@ export class AgentSession {
      * @throws Error if text is an extension command
      */
     async followUp(text, images) {
-        // Check for extension commands (cannot be queued)
-        if (text.startsWith("/")) {
-            this._throwIfExtensionCommand(text);
-        }
-        // Expand skill commands and prompt templates
-        let expandedText = this._expandSkillCommand(text);
-        expandedText = expandPromptTemplate(expandedText, [...this.promptTemplates]);
-        await this._queueFollowUp(expandedText, images);
+        await this._queueFollowUp(this._prepareQueuedMessageText(text), images);
     }
     /**
      * Internal: Queue a steering message (already expanded, no extension command check).
@@ -2663,6 +2634,19 @@ export class AgentSession {
     async compact(customInstructions) {
         return this._compaction.compact(customInstructions);
     }
+    /** Start extension-requested compaction without blocking its event or shortcut handler. */
+    compactForExtension(options) {
+        void (async () => {
+            try {
+                const result = await this.compact(options?.customInstructions);
+                options?.onComplete?.(result);
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                options?.onError?.(err);
+            }
+        })();
+    }
     /**
      * Cancel in-progress compaction (manual or auto).
      */
@@ -2901,18 +2885,7 @@ export class AgentSession {
                 this._extensionShutdownHandler?.();
             },
             getContextUsage: () => this.getContextUsage(),
-            compact: (options) => {
-                void (async () => {
-                    try {
-                        const result = await this.compact(options?.customInstructions);
-                        options?.onComplete?.(result);
-                    }
-                    catch (error) {
-                        const err = error instanceof Error ? error : new Error(String(error));
-                        options?.onError?.(err);
-                    }
-                })();
-            },
+            compact: (options) => this.compactForExtension(options),
             reload: () => {
                 if (this.isStreaming) {
                     return Promise.reject(new Error("ctx.reload() cannot run while the agent is streaming or a tool call is active. Wait for ctx.isIdle(), queue a follow-up /reload, or use an idle command/event handler so hot reload cannot destabilize the UI."));