@borgee/agents-host 0.2.84 → 0.2.97

package/dist/providers/claude/cli-client.js

@@ -1,8 +1,8 @@
 import { Readable, Writable } from 'node:stream';
 import { createHash } from 'node:crypto';
-import { readFileSync } from 'node:fs';
-import { createRequire } from 'node:module';
+import { existsSync, readFileSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import spawn from 'cross-spawn';
 import { DEFAULT_PROJECTION_STRATEGY, normalizeProjectionStrategy, } from '../../projection-strategy-values.js';
 import { assertClaudeCommandCompatibility, DEFAULT_CLAUDE_COMMAND, isLegacyClaudeCompatibilityAlias, } from '../../config.js';
@@ -11,10 +11,347 @@ import { HostLogger, summarizeChildStderr, summarizeError } from '../../debug.js
 import { AcpProgressCollector } from '../acp-progress-collector.js';
 import { ProviderTurnCancelledError } from '../provider-adapter.js';
 import { readClaudeActivityMetadata } from './activity-metadata.js';
+import { ClaudeBackgroundRunObserver } from './background-run-observer.js';
+import { CLAUDE_FOREGROUND_HANDOFF_METHOD, isClaudeUpdateFromIsolatedTurn, readClaudeForegroundSettledTurn, } from './foreground-handoff.js';
 import { resolveCopilotPermissionResponse } from '../../policy/copilot-permission.js';
 import { buildClaudeSessionPromptAppend } from '../../context/prompt.js';
 import { isDiscussionOnlyResolvedWorkingFolder } from '../../context/resolved-working-folder.js';
 import { IDLE_BACKEND_SHUTDOWN_DISABLED_MS, IdleBackendShutdownScheduler, } from '../idle-backend-shutdown.js';
+import { CLAUDE_TASK_CANCELLATION_METHOD, supportsClaudeTaskCancellation, } from './task-cancellation-protocol.js';
+const BACKGROUND_COMPLETION_SIGNAL_TTL_MS = 30_000;
+const MAX_BACKGROUND_COMPLETION_SIGNALS = 32;
+const AUTONOMOUS_REPLY_IDLE_FLUSH_MS = 100;
+class ClaudeSessionUpdatePump {
+    session;
+    onFailure;
+    autonomousEvents;
+    onForegroundSettledWithBackground;
+    observer;
+    activeTurn;
+    autonomousTurns = new Map();
+    backgroundCompletionSignals = [];
+    backgroundCompletionSignalExpiry;
+    autonomousTurnPending = false;
+    closed = false;
+    failure;
+    constructor(session, onFailure, onBackgroundTasksActiveChanged, autonomousEvents, onForegroundSettledWithBackground, targetedCancellationSupported) {
+        this.session = session;
+        this.onFailure = onFailure;
+        this.autonomousEvents = autonomousEvents;
+        this.onForegroundSettledWithBackground = onForegroundSettledWithBackground;
+        this.observer = new ClaudeBackgroundRunObserver(undefined, {
+            onBackgroundTasksActiveChanged,
+            targetedCancellationSupported,
+        });
+        void this.run();
+    }
+    beginTurn(onProgress, foregroundIsolationFence) {
+        if (this.closed) {
+            throw new Error('Claude ACP session update pump is closed');
+        }
+        if (this.failure) {
+            throw this.failure;
+        }
+        if (this.activeTurn) {
+            throw new Error('Claude ACP session already has an active turn');
+        }
+        const turn = {
+            queue: [],
+            foregroundIsolationFence,
+            ownedForegroundTurn: this.resolveForegroundTurn(foregroundIsolationFence),
+        };
+        this.activeTurn = turn;
+        this.observer.setOnProgress(onProgress);
+        return {
+            next: () => {
+                if (turn.failure) {
+                    return Promise.reject(turn.failure);
+                }
+                const queued = turn.queue.shift();
+                if (queued) {
+                    return Promise.resolve(queued);
+                }
+                if (this.activeTurn !== turn || this.closed) {
+                    return Promise.reject(new Error('Claude ACP turn update stream is closed'));
+                }
+                return new Promise((resolve, reject) => {
+                    turn.waiter = { resolve, reject };
+                });
+            },
+            close: () => {
+                if (this.activeTurn !== turn) {
+                    return;
+                }
+                this.activeTurn = undefined;
+                turn.waiter?.reject(new Error('Claude ACP turn update stream is closed'));
+                turn.waiter = undefined;
+                turn.queue.length = 0;
+            },
+        };
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.observer.dispose();
+        if (this.backgroundCompletionSignalExpiry) {
+            clearTimeout(this.backgroundCompletionSignalExpiry);
+            this.backgroundCompletionSignalExpiry = undefined;
+        }
+        this.backgroundCompletionSignals.length = 0;
+        for (const turn of this.autonomousTurns.values()) {
+            if (turn.flushTimer) {
+                clearTimeout(turn.flushTimer);
+            }
+            if (turn.discardTimer) {
+                clearTimeout(turn.discardTimer);
+            }
+        }
+        this.autonomousTurns.clear();
+        this.refreshAutonomousTurnPresence();
+        const turn = this.activeTurn;
+        this.activeTurn = undefined;
+        turn?.waiter?.reject(new Error('Claude ACP session update stream is closed'));
+    }
+    resolveForegroundTurn(foregroundIsolationFence) {
+        const nextForegroundTurn = foregroundIsolationFence === undefined ? 1 : foregroundIsolationFence + 1;
+        return Number.isSafeInteger(nextForegroundTurn) && nextForegroundTurn > 0
+            ? nextForegroundTurn
+            : undefined;
+    }
+    autonomousTurnFor(foregroundTurn) {
+        let turn = this.autonomousTurns.get(foregroundTurn);
+        if (turn) {
+            return turn;
+        }
+        turn = {
+            eventId: `claude-background-${foregroundTurn}`,
+            confirmed: false,
+            text: '',
+        };
+        this.autonomousTurns.set(foregroundTurn, turn);
+        return turn;
+    }
+    noteBackgroundCompletionSignal(foregroundTurn, eventId) {
+        const turn = this.autonomousTurnFor(foregroundTurn);
+        if (turn.discardTimer) {
+            clearTimeout(turn.discardTimer);
+            turn.discardTimer = undefined;
+        }
+        this.pruneBackgroundCompletionSignals();
+        const existingIndex = this.backgroundCompletionSignals.findIndex((signal) => signal.foregroundTurn === foregroundTurn);
+        if (existingIndex >= 0) {
+            this.backgroundCompletionSignals.splice(existingIndex, 1);
+        }
+        this.backgroundCompletionSignals.push({
+            eventId,
+            foregroundTurn,
+            expiresAt: Date.now() + BACKGROUND_COMPLETION_SIGNAL_TTL_MS,
+        });
+        if (this.backgroundCompletionSignals.length > MAX_BACKGROUND_COMPLETION_SIGNALS) {
+            this.backgroundCompletionSignals.splice(0, this.backgroundCompletionSignals.length - MAX_BACKGROUND_COMPLETION_SIGNALS);
+        }
+        this.scheduleBackgroundCompletionSignalExpiry();
+        turn.confirmed = true;
+        turn.eventId = eventId;
+        if (turn.text.trim()) {
+            this.scheduleAutonomousReplyFlush(foregroundTurn, turn);
+        }
+        this.refreshAutonomousTurnPresence();
+        return turn;
+    }
+    consumeAutonomousLifecycle(update) {
+        if (update.update.sessionUpdate !== 'session_info_update') {
+            return;
+        }
+        const provider = asObject(update.update._meta)?.claudeCode;
+        const lifecycle = asObject(asObject(provider)?.taskLifecycle);
+        if (lifecycle?.event !== 'notification' || lifecycle?.status !== 'completed') {
+            return;
+        }
+        const foregroundTurn = asObject(provider)?.foregroundTurn;
+        if (!Number.isSafeInteger(foregroundTurn) || foregroundTurn <= 0) {
+            return;
+        }
+        const taskId = typeof lifecycle.taskId === 'string' ? lifecycle.taskId : 'task';
+        this.noteBackgroundCompletionSignal(foregroundTurn, `${taskId}:completed`);
+    }
+    consumeAutonomousUpdate(update) {
+        if (update.update.sessionUpdate !== 'agent_message_chunk' || update.update.content.type !== 'text') {
+            return;
+        }
+        const provider = asObject(update.update._meta)?.claudeCode;
+        const foregroundTurn = asObject(provider)?.foregroundTurn;
+        if (!Number.isSafeInteger(foregroundTurn) || foregroundTurn <= 0) {
+            return;
+        }
+        const lane = asObject(provider)?.foregroundLane;
+        const activeForegroundTurn = this.activeTurn?.ownedForegroundTurn;
+        if (foregroundTurn === activeForegroundTurn) {
+            return;
+        }
+        if (lane !== 'background' && !this.backgroundCompletionSignals.some((signal) => signal.foregroundTurn === foregroundTurn)) {
+            return;
+        }
+        const turn = this.autonomousTurnFor(foregroundTurn);
+        turn.text += update.update.content.text;
+        if (turn.confirmed) {
+            this.scheduleAutonomousReplyFlush(foregroundTurn, turn);
+        }
+    }
+    scheduleAutonomousReplyFlush(foregroundTurn, turn) {
+        if (turn.flushTimer) {
+            clearTimeout(turn.flushTimer);
+        }
+        turn.flushTimer = setTimeout(() => {
+            turn.flushTimer = undefined;
+            this.flushAutonomousReply(foregroundTurn, turn);
+        }, AUTONOMOUS_REPLY_IDLE_FLUSH_MS);
+        turn.flushTimer.unref?.();
+    }
+    flushAutonomousReply(foregroundTurn, turn) {
+        const text = turn.text.trim();
+        if (turn.confirmed && text) {
+            this.autonomousEvents.onReply?.({
+                eventId: turn.eventId,
+                text,
+            });
+        }
+        else if (turn.confirmed) {
+            turn.discardTimer = setTimeout(() => {
+                turn.discardTimer = undefined;
+                this.discardAutonomousTurn(foregroundTurn, turn);
+            }, BACKGROUND_COMPLETION_SIGNAL_TTL_MS);
+            turn.discardTimer.unref?.();
+            this.refreshAutonomousTurnPresence();
+            return;
+        }
+        this.discardAutonomousTurn(foregroundTurn, turn);
+    }
+    discardAutonomousTurn(foregroundTurn, turn) {
+        if (turn.flushTimer) {
+            clearTimeout(turn.flushTimer);
+            turn.flushTimer = undefined;
+        }
+        if (turn.discardTimer) {
+            clearTimeout(turn.discardTimer);
+            turn.discardTimer = undefined;
+        }
+        if (this.autonomousTurns.get(foregroundTurn) === turn) {
+            this.autonomousTurns.delete(foregroundTurn);
+        }
+        const signalIndex = this.backgroundCompletionSignals.findIndex((signal) => signal.foregroundTurn === foregroundTurn);
+        if (signalIndex >= 0) {
+            this.backgroundCompletionSignals.splice(signalIndex, 1);
+            this.scheduleBackgroundCompletionSignalExpiry();
+            return;
+        }
+        this.refreshAutonomousTurnPresence();
+    }
+    pruneBackgroundCompletionSignals() {
+        const now = Date.now();
+        while (this.backgroundCompletionSignals.length > 0
+            && this.backgroundCompletionSignals[0].expiresAt <= now) {
+            const expired = this.backgroundCompletionSignals.shift();
+            if (!expired) {
+                continue;
+            }
+            const turn = this.autonomousTurns.get(expired.foregroundTurn);
+            if (turn && !turn.text.trim()) {
+                this.discardAutonomousTurn(expired.foregroundTurn, turn);
+            }
+        }
+    }
+    scheduleBackgroundCompletionSignalExpiry() {
+        if (this.backgroundCompletionSignalExpiry) {
+            clearTimeout(this.backgroundCompletionSignalExpiry);
+            this.backgroundCompletionSignalExpiry = undefined;
+        }
+        this.pruneBackgroundCompletionSignals();
+        const next = this.backgroundCompletionSignals[0];
+        if (!next) {
+            this.refreshAutonomousTurnPresence();
+            return;
+        }
+        this.backgroundCompletionSignalExpiry = setTimeout(() => {
+            this.backgroundCompletionSignalExpiry = undefined;
+            this.pruneBackgroundCompletionSignals();
+            this.scheduleBackgroundCompletionSignalExpiry();
+        }, Math.max(0, next.expiresAt - Date.now()));
+        this.backgroundCompletionSignalExpiry.unref?.();
+    }
+    refreshAutonomousTurnPresence() {
+        const pending = this.autonomousTurns.size > 0 || this.backgroundCompletionSignals.length > 0;
+        if (pending === this.autonomousTurnPending) {
+            return;
+        }
+        this.autonomousTurnPending = pending;
+        this.autonomousEvents.onPendingChanged?.(pending);
+    }
+    async run() {
+        try {
+            while (!this.closed) {
+                const update = await this.session.nextUpdate();
+                if (this.closed) {
+                    return;
+                }
+                const lifecycle = update.kind === 'session_update' && this.observer.consume(update.update);
+                if (lifecycle) {
+                    this.consumeAutonomousLifecycle(update);
+                    continue;
+                }
+                if (update.kind === 'session_update') {
+                    this.consumeAutonomousUpdate(update);
+                }
+                if (update.kind === 'session_update'
+                    && isClaudeUpdateFromIsolatedTurn(update.update, this.activeTurn?.foregroundIsolationFence)) {
+                    continue;
+                }
+                const settledForegroundTurn = update.kind === 'session_update'
+                    ? readClaudeForegroundSettledTurn(update.update)
+                    : undefined;
+                const turn = this.activeTurn;
+                if (turn
+                    && settledForegroundTurn !== undefined
+                    && turn.foregroundSettledTurn !== settledForegroundTurn) {
+                    turn.foregroundSettledTurn = settledForegroundTurn;
+                    this.onForegroundSettledWithBackground(settledForegroundTurn);
+                }
+                if (!turn) {
+                    continue;
+                }
+                const waiter = turn.waiter;
+                if (waiter) {
+                    turn.waiter = undefined;
+                    waiter.resolve(update);
+                }
+                else {
+                    turn.queue.push(update);
+                }
+            }
+        }
+        catch (error) {
+            if (!this.closed) {
+                const normalized = normalizeError(error);
+                this.observer.fail();
+                this.failure = normalized;
+                const turn = this.activeTurn;
+                if (turn) {
+                    // ActiveSession mirrors prompt failures onto its update queue. Keep
+                    // that rejection scoped to this turn/session; transport failures use
+                    // the connection and child-process fatal handlers instead.
+                    turn.failure = normalized;
+                    turn.waiter?.reject(normalized);
+                    turn.waiter = undefined;
+                }
+                else {
+                    this.onFailure(normalized);
+                }
+            }
+        }
+    }
+}
 const SESSION_TAINTED_ERRORS = new WeakSet();
 const IDLE_BACKEND_STOPPED_MESSAGE = 'Claude ACP backend stopped after idle timeout';
 /**
@@ -32,7 +369,6 @@ const DEFAULT_SESSION_CAPABILITIES = {
     resumeSession: false,
 };
 const CLAUDE_SDK_COMPACTION_EXPERIMENT_CONTEXT_TOKEN_THRESHOLD_ENV = 'CLAUDE_SDK_COMPACTION_EXPERIMENT_CONTEXT_TOKEN_THRESHOLD';
-const require = createRequire(import.meta.url);
 const CLAUDE_CANCELLED_REPLY_TEXT = 'Info: Operation cancelled by user';
 const DEFAULT_RUNTIME = {
     spawn,
@@ -283,7 +619,12 @@ function isSessionTainted(error) {
     return error instanceof Error && SESSION_TAINTED_ERRORS.has(error);
 }
 function resolveBundledClaudeAdapterPath() {
-    return require.resolve('@agentclientprotocol/claude-agent-acp/dist/index.js');
+    const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..');
+    const adapterPath = resolve(packageRoot, 'dist', 'vendor', 'claude-agent-acp', 'dist', 'index.js');
+    if (!existsSync(adapterPath)) {
+        throw new Error(`Shipped Claude ACP adapter is missing at ${adapterPath}; reinstall @borgee/agents-host`);
+    }
+    return adapterPath;
 }
 function isRelativePathLike(value) {
     return value.startsWith('./') || value.startsWith('../');
@@ -489,16 +830,45 @@ export class ClaudeCliClient {
     imageInputConfig;
     runtime;
     channels = new Map();
+    channelWorkerRoutes = new Map();
+    targetedBackgroundRunCancellationConfigured;
     /**
      * The provider session currently bound to channelId, or undefined before a
      * turn has opened one. Surfaced so agents-host can record which session
      * worked a task without the agent being asked to report its own id.
      */
     sessionIdForChannel(channelId) {
-        return this.channels.get(channelId)?.session?.sessionId;
+        return this.channelWorkerRoutes.get(channelId)?.state.session?.sessionId
+            ?? this.channels.get(channelId)?.session?.sessionId;
+    }
+    async handoffForegroundTurn(channelId) {
+        const state = this.channelWorkerRoutes.get(channelId)?.state ?? this.channels.get(channelId);
+        const session = state?.session;
+        if (!state?.activeTurn || !session || !this.connection) {
+            return { outcome: 'not_found' };
+        }
+        const response = await this.connection.agent.request(CLAUDE_FOREGROUND_HANDOFF_METHOD, { sessionId: session.sessionId });
+        const result = asObject(response);
+        const outcome = result?.outcome;
+        if (outcome === 'admitted' || outcome === 'released') {
+            const foregroundTurn = result?.foregroundTurn;
+            if (!Number.isSafeInteger(foregroundTurn)
+                || foregroundTurn <= 0) {
+                throw new Error('Claude ACP foreground handoff omitted its ownership fence');
+            }
+            if (state.session !== session) {
+                return { outcome: 'admitted' };
+            }
+            state.foregroundIsolationFence = Math.max(state.foregroundIsolationFence ?? 0, foregroundTurn);
+            return { outcome: 'admitted' };
+        }
+        if (outcome === 'not_found') {
+            return { outcome: 'not_found' };
+        }
+        throw new Error('Claude ACP returned an unusable foreground handoff result');
     }
     async cancelTurn(channelId) {
-        const state = this.channels.get(channelId);
+        const state = this.channelWorkerRoutes.get(channelId)?.state ?? this.channels.get(channelId);
         const session = state?.session;
         if (!state?.activeTurn || !session) {
             return false;
@@ -513,8 +883,33 @@ export class ClaudeCliClient {
         await this.connection?.agent.notify(cancelMethod, { sessionId: session.sessionId });
         return true;
     }
+    async cancelBackgroundRun(channelId, providerRunId) {
+        if (!this.targetedBackgroundRunCancellationConfigured
+            || !this.targetedBackgroundRunCancellationAvailable
+            || providerRunId.length === 0) {
+            return false;
+        }
+        const state = this.channelWorkerRoutes.get(channelId)?.state ?? this.channels.get(channelId);
+        const session = state?.session;
+        if (!state || state.channelId !== channelId || !session || !this.connection) {
+            return false;
+        }
+        this.idleBackendShutdown.cancel();
+        const response = await this.connection.agent.request(CLAUDE_TASK_CANCELLATION_METHOD, {
+            sessionId: session.sessionId,
+            taskId: providerRunId,
+        });
+        if (response?.outcome === 'accepted') {
+            return true;
+        }
+        if (response?.outcome === 'not_found' || response?.outcome === 'unsupported') {
+            return false;
+        }
+        throw new Error('Claude ACP returned an invalid targeted task cancellation response');
+    }
     persistedSessions = new Map();
     closingSessions = new WeakSet();
+    sessionUpdatePumps = new WeakMap();
     pendingSessionStarts = new Set();
     pendingSessionCloses = new Set();
     pendingSessionStoreOperations = new Set();
@@ -539,6 +934,8 @@ export class ClaudeCliClient {
     sessionStoreLoadPromise = null;
     sessionStoreWriteQueue = Promise.resolve();
     sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+    targetedBackgroundRunCancellationAvailable = false;
+    autonomousReplyHandler;
     idleBackendShutdown;
     childStderr = '';
     constructor(command, args = [], runtimeOverrides = {}, sessionStore, resolveSessionStoreAgentId = () => undefined, logger = new HostLogger(), imageInputConfig = {}) {
@@ -550,6 +947,8 @@ export class ClaudeCliClient {
         this.imageInputConfig = imageInputConfig;
         this.runtime = { ...DEFAULT_RUNTIME, ...runtimeOverrides };
         assertClaudeCommandCompatibility(command, args, 'Claude provider runtime');
+        this.targetedBackgroundRunCancellationConfigured =
+            useBundledClaudeAdapter(command, args) || useLegacyClaudeCompatibilityAlias(command, args);
         this.idleBackendShutdown = new IdleBackendShutdownScheduler({
             idleShutdownMs: this.runtime.idleBackendShutdownMs,
             isIdle: () => this.isBackendIdle(),
@@ -565,6 +964,9 @@ export class ClaudeCliClient {
         });
         void this.fatalPromise.catch(() => { });
     }
+    onAutonomousReply(handler) {
+        this.autonomousReplyHandler = handler;
+    }
     async generateReply(channelIdOrTurn, promptOrOptions, maybeOptions) {
         if (this.fatalError) {
             throw this.fatalError;
@@ -586,16 +988,17 @@ export class ClaudeCliClient {
             ? maybeOptions
             : promptOrOptions;
         const sessionRouting = resolveSessionRouting(preparedTurn);
-        const state = this.getOrCreateChannelState(sessionRouting.key, preparedTurn.channelId, sessionRouting.persistence);
+        const state = this.resolveChannelState(sessionRouting);
         this.idleBackendShutdown.cancel();
         const turn = createDeferredTurn(preparedTurn.channelId, preparedTurn, sessionRouting.persistence, options);
         state.queue.push(turn);
-        this.processChannelQueue(sessionRouting.key, state);
+        this.processChannelQueue(state);
         return turn.promise;
     }
     async dispose() {
         const error = new Error('Claude ACP backend stopped');
         this.disposing = true;
+        this.autonomousReplyHandler = undefined;
         this.idleBackendShutdown.cancel();
         this.logger?.debug('stopping Claude ACP backend');
         const closed = this.connection?.closed ?? Promise.resolve();
@@ -717,9 +1120,13 @@ export class ClaudeCliClient {
                 },
             });
             this.sessionCapabilities = readSessionCapabilities(initializeResponse);
+            this.targetedBackgroundRunCancellationAvailable =
+                this.targetedBackgroundRunCancellationConfigured
+                    && supportsClaudeTaskCancellation(initializeResponse);
             this.logger?.debug('initialized Claude ACP connection', {
                 loadSession: this.sessionCapabilities.loadSession,
                 resumeSession: this.sessionCapabilities.resumeSession,
+                targetedBackgroundRunCancellation: this.targetedBackgroundRunCancellationAvailable,
             });
         }
         catch (error) {
@@ -729,24 +1136,46 @@ export class ClaudeCliClient {
             throw normalized;
         }
     }
-    getOrCreateChannelState(channelId, resolvedChannelId, sessionPersistence) {
-        let state = this.channels.get(channelId);
+    getOrCreateChannelState(routingKey, resolvedChannelId, sessionPersistence) {
+        let state = this.channels.get(routingKey);
         if (!state) {
             state = {
+                routingKey,
                 channelId: resolvedChannelId,
                 sessionPersistence,
+                backgroundTasksActive: false,
+                backgroundContinuationPending: false,
+                sessionHasPendingAutonomousTurn: false,
+                persistentFollowUpAdopted: false,
                 processing: false,
                 queue: [],
             };
-            this.channels.set(channelId, state);
+            this.channels.set(routingKey, state);
         }
         else if (state.channelId !== resolvedChannelId
             || state.sessionPersistence !== sessionPersistence) {
-            throw new Error(`Claude session routing changed for key "${channelId}"`);
+            throw new Error(`Claude session routing changed for key "${routingKey}"`);
         }
         return state;
     }
-    processChannelQueue(channelId, state) {
+    resolveChannelState(routing) {
+        const workerRoute = this.channelWorkerRoutes.get(routing.channelId);
+        if (workerRoute) {
+            return workerRoute.state;
+        }
+        if (routing.persistence === 'ephemeral') {
+            const foregroundState = this.channels.get(routing.channelId);
+            const state = foregroundState
+                && foregroundState.channelId === routing.channelId
+                && foregroundState.sessionPersistence === 'persistent'
+                ? foregroundState
+                : this.getOrCreateChannelState(routing.key, routing.channelId, routing.persistence);
+            this.channelWorkerRoutes.set(routing.channelId, { phase: 'candidate', state });
+            return state;
+        }
+        return this.getOrCreateChannelState(routing.key, routing.channelId, routing.persistence);
+    }
+    processChannelQueue(state) {
         if (state.processing) {
             return;
         }
@@ -766,17 +1195,24 @@ export class ClaudeCliClient {
                             : 'default';
                         const sessionPromptAppend = resolveTurnSessionPromptAppend(turn.preparedTurn);
                         state.visibilityKey = resolveSessionVisibilityKey(turn.preparedTurn.promptContext, sessionPromptAppend, turn.preparedTurn.projectionStrategy);
+                        const adoptingPersistentRoute = turn.sessionPersistence === 'persistent'
+                            && state.routingKey !== state.channelId
+                            && !state.persistentFollowUpAdopted;
+                        if (adoptingPersistentRoute) {
+                            state.persistentFollowUpAdopted = true;
+                            state.sessionPersistence = 'persistent';
+                        }
                         await this.ensureStarted();
-                        await this.recycleSessionIfScopeChanged(channelId, state);
-                        const session = await this.getOrCreateSession(channelId, state, turn.preparedTurn, sessionPromptAppend);
+                        await this.recycleSessionIfScopeChanged(state.routingKey, state);
+                        const session = await this.getOrCreateSession(state, turn.preparedTurn, sessionPromptAppend);
                         let reply;
                         try {
                             const promptInput = await this.buildPromptInput(turn.preparedTurn);
-                            reply = await this.runTurn(session, promptInput, turn.options);
+                            reply = await this.runTurn(session, promptInput, turn.options, state.foregroundIsolationFence);
                         }
                         catch (error) {
                             if (isSessionTainted(error)) {
-                                this.invalidateSession(channelId, state, session);
+                                this.invalidateSession(state.routingKey, state, session);
                                 this.rejectQueuedTurnsAfterSessionTaint(state, error);
                             }
                             throw error;
@@ -793,26 +1229,17 @@ export class ClaudeCliClient {
             }
             finally {
                 state.processing = false;
-                if (state.sessionPersistence === 'ephemeral' && !this.fatalError && !this.disposing && state.queue.length === 0) {
-                    const session = state.session;
-                    state.session = undefined;
-                    state.sessionCwd = undefined;
-                    state.sessionVisibilityKey = undefined;
-                    if (session) {
-                        this.closeSession(session);
-                    }
-                    this.channels.delete(channelId);
-                }
                 if (state.queue.length > 0 && !this.fatalError) {
-                    this.processChannelQueue(channelId, state);
+                    this.processChannelQueue(state);
                 }
                 else {
+                    this.reconcileIdleChannelState(state);
                     this.idleBackendShutdown.reconcile();
                 }
             }
         })();
     }
-    async getOrCreateSession(channelId, state, turn, systemPromptAppend) {
+    async getOrCreateSession(state, turn, systemPromptAppend) {
         if (state.session) {
             return state.session;
         }
@@ -824,12 +1251,12 @@ export class ClaudeCliClient {
         }
         const cwd = state.cwd ?? this.runtime.cwd;
         const persistedSessionId = state.sessionPersistence === 'persistent'
-            ? await this.readPersistedSessionId(channelId, cwd, state.visibilityKey)
+            ? await this.readPersistedSessionId(state.channelId, cwd, state.visibilityKey)
             : undefined;
         const additionalDirectories = resolveSessionAdditionalDirectories(turn.promptContext);
         const sessionPromise = persistedSessionId
-            ? this.restoreOrCreateSession(channelId, persistedSessionId, cwd, systemPromptAppend, additionalDirectories)
-            : this.startFreshSession(channelId, cwd, systemPromptAppend, additionalDirectories);
+            ? this.restoreOrCreateSession(state.channelId, persistedSessionId, cwd, systemPromptAppend, additionalDirectories)
+            : this.startFreshSession(state.channelId, cwd, systemPromptAppend, additionalDirectories);
         this.pendingSessionStarts.add(sessionPromise);
         state.sessionPromise = sessionPromise;
         let sessionAdopted = false;
@@ -854,10 +1281,16 @@ export class ClaudeCliClient {
             state.session = session;
             state.sessionCwd = cwd;
             state.sessionVisibilityKey = state.visibilityKey;
+            if (state.sessionPersistence === 'persistent') {
+                await this.persistSessionBestEffort(state.channelId, session.sessionId, state.visibilityKey, cwd);
+            }
             return session;
         }
         catch (error) {
             state.session = undefined;
+            state.backgroundTasksActive = false;
+            state.backgroundContinuationPending = false;
+            state.foregroundIsolationFence = undefined;
             state.sessionCwd = undefined;
             state.sessionVisibilityKey = undefined;
             throw error;
@@ -874,10 +1307,6 @@ export class ClaudeCliClient {
         }
         const session = await this.connection.agent.buildSession(buildSessionRequest(cwd, systemPromptAppend, additionalDirectories)).start();
         this.logger?.debug('started fresh Claude ACP session', { channelId, cwd });
-        const state = this.channels.get(channelId);
-        if (state?.sessionPersistence === 'persistent') {
-            await this.persistSessionBestEffort(channelId, session.sessionId, state.visibilityKey, cwd);
-        }
         return session;
     }
     async restoreOrCreateSession(channelId, sessionId, cwd, systemPromptAppend, additionalDirectories) {
@@ -951,6 +1380,11 @@ export class ClaudeCliClient {
             && state.sessionVisibilityKey === state.visibilityKey) {
             return;
         }
+        if (state.backgroundTasksActive
+            || state.backgroundContinuationPending
+            || state.sessionHasPendingAutonomousTurn) {
+            throw new Error('Claude session scope cannot change while provider-owned background delivery is running');
+        }
         this.logger?.debug('recycling Claude ACP session after session scope changed', {
             channelId,
             previousCwd: state.sessionCwd,
@@ -959,57 +1393,142 @@ export class ClaudeCliClient {
             nextVisibilityKey: state.visibilityKey,
         });
         state.session = undefined;
+        state.backgroundTasksActive = false;
+        state.backgroundContinuationPending = false;
+        state.sessionHasPendingAutonomousTurn = false;
+        state.foregroundIsolationFence = undefined;
         state.sessionCwd = undefined;
         state.sessionVisibilityKey = undefined;
         if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
-            await this.clearPersistedSessionBestEffort(channelId);
+            await this.clearPersistedSessionBestEffort(state.channelId);
         }
         this.closeSession(session);
     }
-    async runTurn(session, prompt, options) {
+    async runTurn(session, prompt, options, foregroundIsolationFence) {
+        let updatePump = this.sessionUpdatePumps.get(session);
+        if (!updatePump) {
+            updatePump = new ClaudeSessionUpdatePump(session, (error) => {
+                const binding = [...this.channels.entries()].find(([, candidate]) => candidate.session === session);
+                if (binding) {
+                    const [, state] = binding;
+                    this.logger?.debug('discarding failed Claude ACP session update pump', {
+                        channelId: state.channelId,
+                        error: error.message,
+                    });
+                    this.invalidateSession(state.routingKey, state, session);
+                }
+            }, (active) => {
+                const binding = [...this.channels.entries()].find(([, candidate]) => candidate.session === session);
+                if (!binding) {
+                    return;
+                }
+                const [, state] = binding;
+                state.backgroundTasksActive = active;
+                state.backgroundContinuationPending = false;
+                if (active) {
+                    this.promoteWorkerRoute(state, session);
+                    this.idleBackendShutdown.cancel();
+                    return;
+                }
+                this.reconcileIdleChannelState(state);
+                this.idleBackendShutdown.reconcile();
+            }, {
+                onReply: (reply) => {
+                    const binding = [...this.channels.entries()].find(([, candidate]) => candidate.session === session);
+                    if (!binding) {
+                        return;
+                    }
+                    const [, state] = binding;
+                    if (state.session !== session) {
+                        return;
+                    }
+                    this.autonomousReplyHandler?.({
+                        channelId: state.channelId,
+                        eventId: reply.eventId,
+                        text: reply.text,
+                    });
+                },
+                onPendingChanged: (active) => {
+                    const binding = [...this.channels.entries()].find(([, candidate]) => candidate.session === session);
+                    if (!binding) {
+                        return;
+                    }
+                    const [, state] = binding;
+                    if (state.session !== session) {
+                        return;
+                    }
+                    state.sessionHasPendingAutonomousTurn = active;
+                    if (active) {
+                        this.promoteWorkerRoute(state, session);
+                        this.idleBackendShutdown.cancel();
+                        return;
+                    }
+                    this.reconcileIdleChannelState(state);
+                    this.idleBackendShutdown.reconcile();
+                },
+            }, (foregroundTurn) => {
+                const binding = [...this.channels.entries()].find(([, candidate]) => candidate.session === session);
+                if (!binding) {
+                    return;
+                }
+                const [, state] = binding;
+                state.backgroundContinuationPending = true;
+                state.foregroundIsolationFence = Math.max(state.foregroundIsolationFence ?? 0, foregroundTurn);
+                this.promoteWorkerRoute(state, session);
+                this.idleBackendShutdown.cancel();
+            }, this.targetedBackgroundRunCancellationAvailable);
+            this.sessionUpdatePumps.set(session, updatePump);
+        }
+        const turnUpdates = updatePump.beginTurn(options?.onProgress, foregroundIsolationFence);
         const promptPromise = this.raceWithFatal(session.prompt(prompt));
         const promptFailure = new Promise((_, reject) => {
             void promptPromise.catch((error) => reject(markSessionTainted(error)));
         });
         const collector = new AcpProgressCollector(options?.onProgress, readClaudeActivityMetadata);
         const compactionObserver = new ClaudeCompactionObserver(options?.onProgress);
-        for (;;) {
-            let update;
-            try {
-                update = await this.raceWithFatal(Promise.race([session.nextUpdate(), promptFailure]));
-            }
-            catch (error) {
-                if (this.fatalError && error === this.fatalError) {
-                    throw error;
-                }
-                throw markSessionTainted(error);
-            }
-            if (update.kind === 'stop') {
-                let response;
+        try {
+            for (;;) {
+                let update;
                 try {
-                    response = await promptPromise;
+                    update = await this.raceWithFatal(Promise.race([turnUpdates.next(), promptFailure]));
                 }
                 catch (error) {
+                    if (this.fatalError && error === this.fatalError) {
+                        throw error;
+                    }
                     throw markSessionTainted(error);
                 }
-                const output = collector.getFinalText();
-                if (response.stopReason === 'cancelled') {
-                    throw new ProviderTurnCancelledError('Claude ACP turn cancelled', {
-                        publicReplyText: hasVisibleText(output) ? output : CLAUDE_CANCELLED_REPLY_TEXT,
-                    });
+                if (update.kind === 'stop') {
+                    let response;
+                    try {
+                        response = await promptPromise;
+                    }
+                    catch (error) {
+                        throw markSessionTainted(error);
+                    }
+                    const output = collector.getFinalText();
+                    if (response.stopReason === 'cancelled') {
+                        throw new ProviderTurnCancelledError('Claude ACP turn cancelled', {
+                            publicReplyText: hasVisibleText(output) ? output : CLAUDE_CANCELLED_REPLY_TEXT,
+                        });
+                    }
+                    if (response.stopReason !== 'end_turn' && !hasVisibleText(output)) {
+                        throw new Error(`Claude ACP turn stopped with stopReason "${response.stopReason}"`);
+                    }
+                    return output;
                 }
-                if (response.stopReason !== 'end_turn' && !hasVisibleText(output)) {
-                    throw new Error(`Claude ACP turn stopped with stopReason "${response.stopReason}"`);
+                if (update.update.sessionUpdate === 'agent_message_chunk' &&
+                    update.update.content.type === 'text') {
+                    compactionObserver.consumeAnswerChunk(update.update.content.text);
                 }
-                return output;
-            }
-            if (update.update.sessionUpdate === 'agent_message_chunk' && update.update.content.type === 'text') {
-                compactionObserver.consumeAnswerChunk(update.update.content.text);
-            }
-            if (update.update.sessionUpdate === 'usage_update') {
-                compactionObserver.consumeUsageUpdate(update.update.used, update.update.size);
+                if (update.update.sessionUpdate === 'usage_update') {
+                    compactionObserver.consumeUsageUpdate(update.update.used, update.update.size);
+                }
+                collector.consume(update);
             }
-            collector.consume(update);
+        }
+        finally {
+            turnUpdates.close();
         }
     }
     async raceWithFatal(promise) {
@@ -1035,15 +1554,21 @@ export class ClaudeCliClient {
                 this.closeSession(state.session);
             }
             state.session = undefined;
+            state.backgroundTasksActive = false;
+            state.backgroundContinuationPending = false;
+            state.sessionHasPendingAutonomousTurn = false;
+            state.foregroundIsolationFence = undefined;
             state.sessionCwd = undefined;
             state.sessionVisibilityKey = undefined;
             state.sessionPromise = undefined;
             state.activeTurn = undefined;
+            state.persistentFollowUpAdopted = false;
             if (!state.processing) {
                 this.channels.delete(channelId);
             }
         }
         this.channels.clear();
+        this.channelWorkerRoutes.clear();
         this.shutdownPromise = this.shutdownBackend(error);
     }
     handlePermissionRequest(params) {
@@ -1062,13 +1587,103 @@ export class ClaudeCliClient {
     invalidateSession(channelId, state, session) {
         if (state.session === session) {
             state.session = undefined;
+            state.backgroundTasksActive = false;
+            state.backgroundContinuationPending = false;
+            state.sessionHasPendingAutonomousTurn = false;
+            state.foregroundIsolationFence = undefined;
             state.sessionCwd = undefined;
             state.sessionVisibilityKey = undefined;
+            state.persistentFollowUpAdopted = false;
         }
         this.logger?.debug('discarding tainted Claude ACP session', { channelId });
         this.closeSession(session);
         if (!this.disposing && !this.backendClosed && state.sessionPersistence === 'persistent') {
-            void this.clearPersistedSessionBestEffort(channelId);
+            void this.clearPersistedSessionBestEffort(state.channelId);
+        }
+    }
+    promoteWorkerRoute(state, session) {
+        this.channelWorkerRoutes.set(state.channelId, {
+            phase: 'promoted',
+            state,
+        });
+        state.sessionPersistence = 'persistent';
+        void (async () => {
+            if (!await this.ensureSessionStoreLoaded()) {
+                return;
+            }
+            const route = this.channelWorkerRoutes.get(state.channelId);
+            if (route?.state !== state
+                || route.phase !== 'promoted'
+                || state.session !== session
+                || (!state.backgroundTasksActive && !state.sessionHasPendingAutonomousTurn && !state.persistentFollowUpAdopted)) {
+                return;
+            }
+            await this.persistSessionBestEffort(state.channelId, session.sessionId, state.visibilityKey, state.sessionCwd ?? state.cwd ?? this.runtime.cwd);
+        })().catch((error) => {
+            this.logger.error('failed to initialize Claude session persistence for background work', {
+                agentId: this.loadedSessionStoreAgentId,
+                channelId: state.channelId,
+                sessionId: session.sessionId,
+                error: summarizeError(error),
+            });
+        });
+    }
+    releaseWorkerRoute(state, clearPersistent = false) {
+        const route = this.channelWorkerRoutes.get(state.channelId);
+        if (route?.state !== state) {
+            return;
+        }
+        this.channelWorkerRoutes.delete(state.channelId);
+        if (clearPersistent && state.session) {
+            void this.clearPersistedSessionBestEffort(state.channelId);
+        }
+    }
+    reconcileIdleChannelState(state) {
+        if (this.channels.get(state.routingKey) !== state
+            || this.disposing
+            || this.fatalError
+            || this.backendClosed
+            || state.processing
+            || state.activeTurn
+            || state.queue.length > 0
+            || state.sessionPromise) {
+            return;
+        }
+        const route = this.channelWorkerRoutes.get(state.channelId);
+        if (route?.state === state
+            && route.phase === 'promoted'
+            && !state.backgroundTasksActive
+            && !state.backgroundContinuationPending
+            && !state.sessionHasPendingAutonomousTurn) {
+            if (state.routingKey === state.channelId) {
+                this.releaseWorkerRoute(state);
+            }
+            else if (!state.persistentFollowUpAdopted) {
+                state.sessionPersistence = 'ephemeral';
+                this.releaseWorkerRoute(state, true);
+            }
+        }
+        else if (route?.state === state
+            && route.phase === 'candidate'
+            && (state.routingKey === state.channelId
+                || state.sessionPersistence === 'ephemeral')) {
+            this.releaseWorkerRoute(state);
+        }
+        if (state.sessionPersistence !== 'ephemeral'
+            || state.backgroundTasksActive
+            || state.backgroundContinuationPending
+            || state.sessionHasPendingAutonomousTurn) {
+            return;
+        }
+        const session = state.session;
+        state.session = undefined;
+        state.foregroundIsolationFence = undefined;
+        state.sessionCwd = undefined;
+        state.sessionVisibilityKey = undefined;
+        this.releaseWorkerRoute(state);
+        this.channels.delete(state.routingKey);
+        if (session) {
+            this.closeSession(session);
         }
     }
     closeSession(session) {
@@ -1076,6 +1691,8 @@ export class ClaudeCliClient {
             return;
         }
         this.closingSessions.add(session);
+        this.sessionUpdatePumps.get(session)?.close();
+        this.sessionUpdatePumps.delete(session);
         const agent = this.connection?.agent;
         const closeMethod = this.runtime.methods.agent.session?.close;
         const closePromise = typeof agent?.closeSession === 'function'
@@ -1261,10 +1878,16 @@ export class ClaudeCliClient {
                 sessions.push(state.session);
             }
             state.session = undefined;
+            state.backgroundTasksActive = false;
+            state.backgroundContinuationPending = false;
+            state.sessionHasPendingAutonomousTurn = false;
+            state.foregroundIsolationFence = undefined;
             state.sessionCwd = undefined;
             state.sessionVisibilityKey = undefined;
+            state.persistentFollowUpAdopted = false;
             this.channels.delete(channelId);
         }
+        this.channelWorkerRoutes.clear();
         this.logger?.debug('stopping idle Claude ACP backend', {
             channels: sessions.length,
             idleShutdownMs: this.runtime.idleBackendShutdownMs,
@@ -1276,6 +1899,7 @@ export class ClaudeCliClient {
             this.startPromise = undefined;
             this.childExitPromise = undefined;
             this.sessionCapabilities = DEFAULT_SESSION_CAPABILITIES;
+            this.targetedBackgroundRunCancellationAvailable = false;
             this.idleShutdownPromise = undefined;
         });
         this.idleShutdownPromise = idleShutdownPromise;
@@ -1292,7 +1916,13 @@ export class ClaudeCliClient {
             return false;
         }
         for (const state of this.channels.values()) {
-            if (state.activeTurn || state.queue.length > 0 || state.sessionPromise || state.processing) {
+            if (state.activeTurn ||
+                state.backgroundTasksActive ||
+                state.backgroundContinuationPending ||
+                state.sessionHasPendingAutonomousTurn ||
+                state.queue.length > 0 ||
+                state.sessionPromise ||
+                state.processing) {
                 return false;
             }
         }