@getpaseo/server 0.1.15 → 0.1.17

package/dist/server/server/agent/providers/claude-agent.js

@@ -6,22 +6,16 @@ import os from "node:os";
 import path from "node:path";
 import { query, } from "@anthropic-ai/claude-agent-sdk";
 import { mapClaudeCanceledToolCall, mapClaudeCompletedToolCall, mapClaudeFailedToolCall, mapClaudeRunningToolCall, } from "./claude/tool-call-mapper.js";
+import { isTaskNotificationUserContent, mapTaskNotificationSystemRecordToToolCall, mapTaskNotificationUserContentToToolCall, } from "./claude/task-notification-tool-call.js";
+import { buildClaudeModelFamilyAliases, buildClaudeSelectableModelIds, listClaudeCatalogModels, } from "./claude/model-catalog.js";
+import { buildToolCallDisplayModel } from "../../../shared/tool-call-display.js";
 import { applyProviderEnv, isProviderCommandAvailable, } from "../provider-launch-config.js";
 import { getOrchestratorModeInstructions } from "../orchestrator-instructions.js";
 const fsPromises = promises;
-function normalizeClaudeModelLabel(model) {
-    const fallback = model.displayName?.trim() || model.value;
-    const prefix = model.description?.split(/[·•]/)[0]?.trim() || "";
-    if (!prefix)
-        return fallback;
-    // Prefer concrete versioned labels from description (e.g. "Opus 4.6",
-    // "Sonnet 4.5"), especially when displayName is generic like
-    // "Default (recommended)".
-    if (/\d/.test(prefix)) {
-        return prefix;
-    }
-    return fallback;
-}
+const CLAUDE_SETTING_SOURCES = [
+    "user",
+    "project",
+];
 function normalizeModelIdCandidate(modelId) {
     if (typeof modelId !== "string") {
         return null;
@@ -36,6 +30,28 @@ function pickSupportedModelId(supportedModelIds, candidate) {
     }
     return supportedModelIds.has(normalizedCandidate) ? normalizedCandidate : null;
 }
+function inferClaudeModelFamilyFromText(text) {
+    if (typeof text !== "string") {
+        return null;
+    }
+    const lowerText = text.toLowerCase();
+    if (lowerText.includes("sonnet")) {
+        return "sonnet";
+    }
+    if (lowerText.includes("opus")) {
+        return "opus";
+    }
+    if (lowerText.includes("haiku")) {
+        return "haiku";
+    }
+    return null;
+}
+function pickFamilyAliasModelId(familyAliases, family) {
+    if (!familyAliases) {
+        return null;
+    }
+    return normalizeModelIdCandidate(familyAliases.get(family) ?? null);
+}
 export function normalizeClaudeRuntimeModelId(options) {
     const runtimeModel = options.runtimeModelId.trim();
     if (!runtimeModel) {
@@ -45,31 +61,43 @@ export function normalizeClaudeRuntimeModelId(options) {
     if (!supportedModelIds || supportedModelIds.size === 0) {
         return runtimeModel;
     }
-    const lowerRuntimeModel = runtimeModel.toLowerCase();
-    if (lowerRuntimeModel.includes("sonnet")) {
+    if (supportedModelIds.has(runtimeModel)) {
+        return runtimeModel;
+    }
+    const runtimeFamily = inferClaudeModelFamilyFromText(runtimeModel);
+    const familyAlias = runtimeFamily
+        ? pickFamilyAliasModelId(options.supportedModelFamilyAliases, runtimeFamily)
+        : null;
+    if (runtimeFamily === "sonnet") {
         const explicitSonnet = pickSupportedModelId(supportedModelIds, "sonnet");
         if (explicitSonnet) {
             return explicitSonnet;
         }
+        if (familyAlias && supportedModelIds.has(familyAlias)) {
+            return familyAlias;
+        }
         const defaultAlias = pickSupportedModelId(supportedModelIds, "default");
         if (defaultAlias) {
             return defaultAlias;
         }
     }
-    if (lowerRuntimeModel.includes("opus")) {
+    if (runtimeFamily === "opus") {
         const alias = pickSupportedModelId(supportedModelIds, "opus");
         if (alias) {
             return alias;
         }
+        if (familyAlias && supportedModelIds.has(familyAlias)) {
+            return familyAlias;
+        }
     }
-    if (lowerRuntimeModel.includes("haiku")) {
+    if (runtimeFamily === "haiku") {
         const alias = pickSupportedModelId(supportedModelIds, "haiku");
         if (alias) {
             return alias;
         }
-    }
-    if (supportedModelIds.has(runtimeModel)) {
-        return runtimeModel;
+        if (familyAlias && supportedModelIds.has(familyAlias)) {
+            return familyAlias;
+        }
     }
     const configuredModelId = pickSupportedModelId(supportedModelIds, options.configuredModelId);
     if (configuredModelId) {
@@ -79,6 +107,15 @@ export function normalizeClaudeRuntimeModelId(options) {
     if (currentModelId) {
         return currentModelId;
     }
+    // If Claude reports a concrete family ID we can't map directly, prefer the
+    // provider default alias for unconfigured sessions so UI model/thinking state
+    // can still reconcile against the current model catalog.
+    const defaultAlias = pickSupportedModelId(supportedModelIds, "default");
+    const hasConfiguredModel = normalizeModelIdCandidate(options.configuredModelId) !== null;
+    const hasCurrentModel = normalizeModelIdCandidate(options.currentModelId) !== null;
+    if (runtimeFamily && defaultAlias && !hasConfiguredModel && !hasCurrentModel) {
+        return defaultAlias;
+    }
     return runtimeModel;
 }
 const CLAUDE_CAPABILITIES = {
@@ -118,6 +155,7 @@ const REWIND_COMMAND = {
     description: "Rewind tracked files to a previous user message",
     argumentHint: "[user_message_uuid]",
 };
+const INTERRUPT_TOOL_USE_PLACEHOLDER = "[Request interrupted by user for tool use]";
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
 function resolveClaudeBinary() {
     try {
@@ -150,6 +188,149 @@ function resolveClaudeSpawnCommand(spawnOptions, runtimeSettings) {
         args: [...commandConfig.argv.slice(1), ...spawnOptions.args],
     };
 }
+function applyRuntimeSettingsToClaudeOptions(options, runtimeSettings) {
+    const hasEnvOverrides = Object.keys(runtimeSettings?.env ?? {}).length > 0;
+    const commandMode = runtimeSettings?.command?.mode;
+    const needsCustomSpawn = hasEnvOverrides || commandMode === "append" || commandMode === "replace";
+    if (!needsCustomSpawn) {
+        return options;
+    }
+    return {
+        ...options,
+        spawnClaudeCodeProcess: (spawnOptions) => {
+            const resolved = resolveClaudeSpawnCommand(spawnOptions, runtimeSettings);
+            return spawn(resolved.command, resolved.args, {
+                cwd: spawnOptions.cwd,
+                env: applyProviderEnv(spawnOptions.env, runtimeSettings),
+                signal: spawnOptions.signal,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        },
+    };
+}
+const MAX_RECENT_STDERR_CHARS = 4000;
+function summarizeClaudeOptionsForLog(options) {
+    const systemPromptRaw = options.systemPrompt;
+    const systemPromptSummary = (() => {
+        if (!systemPromptRaw) {
+            return { mode: "none", preset: null };
+        }
+        if (typeof systemPromptRaw === "string") {
+            return { mode: "string", preset: null };
+        }
+        const prompt = systemPromptRaw;
+        const promptType = typeof prompt.type === "string" ? prompt.type : "custom";
+        return {
+            mode: promptType === "preset"
+                ? "preset"
+                : "custom",
+            preset: typeof prompt.preset === "string" && prompt.preset.length > 0
+                ? prompt.preset
+                : null,
+        };
+    })();
+    const mcpServerNames = options.mcpServers
+        ? Object.keys(options.mcpServers).sort()
+        : [];
+    return {
+        cwd: typeof options.cwd === "string" ? options.cwd : null,
+        permissionMode: typeof options.permissionMode === "string"
+            ? options.permissionMode
+            : null,
+        model: typeof options.model === "string" ? options.model : null,
+        includePartialMessages: options.includePartialMessages === true,
+        settingSources: Array.isArray(options.settingSources)
+            ? options.settingSources
+            : [],
+        enableFileCheckpointing: options.enableFileCheckpointing === true,
+        hasResume: typeof options.resume === "string" && options.resume.length > 0,
+        maxThinkingTokens: typeof options.maxThinkingTokens === "number"
+            ? options.maxThinkingTokens
+            : null,
+        hasEnv: !!options.env,
+        envKeyCount: Object.keys(options.env ?? {}).length,
+        hasMcpServers: mcpServerNames.length > 0,
+        mcpServerNames,
+        systemPromptMode: systemPromptSummary.mode,
+        systemPromptPreset: systemPromptSummary.preset,
+        hasCanUseTool: typeof options.canUseTool === "function",
+        hasSpawnOverride: typeof options.spawnClaudeCodeProcess === "function",
+        hasStderrHandler: typeof options.stderr === "function",
+    };
+}
+function isToolResultTextBlock(value) {
+    return (!!value &&
+        typeof value === "object" &&
+        value.type === "text" &&
+        typeof value.text === "string");
+}
+function normalizeForDeterministicString(value, seen) {
+    if (value === null ||
+        typeof value === "string" ||
+        typeof value === "number" ||
+        typeof value === "boolean") {
+        return value;
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    if (typeof value === "function") {
+        return "[function]";
+    }
+    if (typeof value === "symbol") {
+        return value.toString();
+    }
+    if (typeof value === "undefined") {
+        return "[undefined]";
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeForDeterministicString(entry, seen));
+    }
+    if (typeof value === "object") {
+        const objectValue = value;
+        if (seen.has(objectValue)) {
+            return "[circular]";
+        }
+        seen.add(objectValue);
+        const record = value;
+        const normalized = {};
+        for (const key of Object.keys(record).sort()) {
+            normalized[key] = normalizeForDeterministicString(record[key], seen);
+        }
+        seen.delete(objectValue);
+        return normalized;
+    }
+    return String(value);
+}
+function deterministicStringify(value) {
+    if (typeof value === "undefined") {
+        return "";
+    }
+    try {
+        const normalized = normalizeForDeterministicString(value, new WeakSet());
+        if (typeof normalized === "string") {
+            return normalized;
+        }
+        return JSON.stringify(normalized);
+    }
+    catch {
+        try {
+            return String(value);
+        }
+        catch {
+            return "[unserializable]";
+        }
+    }
+}
+function coerceToolResultContentToString(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    if (Array.isArray(content) && content.every((block) => isToolResultTextBlock(block))) {
+        return content.map((block) => block.text).join("");
+    }
+    return deterministicStringify(content);
+}
 export function extractUserMessageText(content) {
     if (typeof content === "string") {
         const normalized = content.trim();
@@ -179,10 +360,18 @@ export function extractUserMessageText(content) {
     const combined = parts.join("\n\n").trim();
     return combined.length > 0 ? combined : null;
 }
-const DEFAULT_PERMISSION_TIMEOUT_MS = 120000;
+const MAX_SUB_AGENT_LOG_ENTRIES = 200;
+const MAX_SUB_AGENT_SUMMARY_CHARS = 160;
 function isMetadata(value) {
     return typeof value === "object" && value !== null;
 }
+function readTrimmedString(value) {
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
 function isMcpServerConfig(value) {
     if (!isMetadata(value)) {
         return false;
@@ -312,6 +501,440 @@ function resolvePermissionKind(toolName, input) {
     }
     return "tool";
 }
+const ACTIVE_RUN_STATES = new Set([
+    "queued",
+    "awaiting_response",
+    "streaming",
+    "finalizing",
+]);
+class RunTracker {
+    constructor() {
+        this.runs = new Map();
+        this.runByTaskId = new Map();
+        this.runByParentMessageId = new Map();
+        this.runByMessageId = new Map();
+    }
+    createRun(input) {
+        const run = {
+            id: input.id,
+            owner: input.owner,
+            queue: input.queue,
+            state: "queued",
+            promptReplaySeen: input.promptReplaySeen ?? true,
+            taskIds: new Set(),
+            parentMessageIds: new Set(),
+            messageIds: new Set(),
+        };
+        this.runs.set(run.id, run);
+        return run;
+    }
+    getRun(runId) {
+        return this.runs.get(runId) ?? null;
+    }
+    getForegroundRun() {
+        for (const run of this.runs.values()) {
+            if (run.owner === "foreground" && this.isActive(run.state)) {
+                return run;
+            }
+        }
+        return null;
+    }
+    listActiveRuns(owner) {
+        const runs = [];
+        for (const run of this.runs.values()) {
+            if (!this.isActive(run.state)) {
+                continue;
+            }
+            if (owner && run.owner !== owner) {
+                continue;
+            }
+            runs.push(run);
+        }
+        return runs;
+    }
+    hasActiveRuns(owner) {
+        for (const run of this.runs.values()) {
+            if (!this.isActive(run.state)) {
+                continue;
+            }
+            if (owner && run.owner !== owner) {
+                continue;
+            }
+            return true;
+        }
+        return false;
+    }
+    getLatestActiveRun(owner) {
+        let latest = null;
+        for (const run of this.runs.values()) {
+            if (!this.isActive(run.state)) {
+                continue;
+            }
+            if (owner && run.owner !== owner) {
+                continue;
+            }
+            latest = run;
+        }
+        return latest;
+    }
+    isRunActive(run) {
+        if (!run) {
+            return false;
+        }
+        return this.isActive(run.state);
+    }
+    resolveByIdentifiers(identifiers) {
+        if (identifiers.taskId) {
+            const run = this.resolveMappedRun(this.runByTaskId, identifiers.taskId);
+            if (run) {
+                return { run, reason: "task_id" };
+            }
+        }
+        if (identifiers.parentMessageId) {
+            const run = this.resolveMappedRun(this.runByParentMessageId, identifiers.parentMessageId);
+            if (run) {
+                return { run, reason: "parent_message_id" };
+            }
+        }
+        if (identifiers.messageId) {
+            const run = this.resolveMappedRun(this.runByMessageId, identifiers.messageId);
+            if (run) {
+                return { run, reason: "message_id" };
+            }
+        }
+        return { run: null, reason: "metadata" };
+    }
+    bindIdentifiers(run, identifiers) {
+        if (identifiers.taskId) {
+            run.taskIds.add(identifiers.taskId);
+            this.runByTaskId.set(identifiers.taskId, run.id);
+        }
+        if (identifiers.parentMessageId) {
+            run.parentMessageIds.add(identifiers.parentMessageId);
+            this.runByParentMessageId.set(identifiers.parentMessageId, run.id);
+        }
+        if (identifiers.messageId) {
+            run.messageIds.add(identifiers.messageId);
+            this.runByMessageId.set(identifiers.messageId, run.id);
+        }
+    }
+    transition(run, nextState) {
+        run.state = nextState;
+    }
+    complete(run, terminalState) {
+        run.state = terminalState;
+        this.clearRunIndex(run);
+    }
+    deriveLifecycle(pendingPermissionCount) {
+        for (const run of this.runs.values()) {
+            if (this.isActive(run.state)) {
+                return "running";
+            }
+        }
+        if (pendingPermissionCount > 0) {
+            return "permission";
+        }
+        for (const run of this.runs.values()) {
+            if (run.state === "error") {
+                return "error";
+            }
+        }
+        return "idle";
+    }
+    resolveMappedRun(mapping, identifier) {
+        const runId = mapping.get(identifier);
+        if (!runId) {
+            return null;
+        }
+        const run = this.runs.get(runId);
+        if (!run || !this.isActive(run.state)) {
+            mapping.delete(identifier);
+            return null;
+        }
+        return run;
+    }
+    clearRunIndex(run) {
+        for (const taskId of run.taskIds) {
+            this.runByTaskId.delete(taskId);
+        }
+        for (const parentMessageId of run.parentMessageIds) {
+            this.runByParentMessageId.delete(parentMessageId);
+        }
+        for (const messageId of run.messageIds) {
+            this.runByMessageId.delete(messageId);
+        }
+        run.taskIds.clear();
+        run.parentMessageIds.clear();
+        run.messageIds.clear();
+    }
+    isActive(state) {
+        return ACTIVE_RUN_STATES.has(state);
+    }
+}
+class TimelineAssembler {
+    constructor() {
+        this.messages = new Map();
+        this.activeMessageByRun = new Map();
+        this.syntheticMessageCounter = 0;
+    }
+    consume(input) {
+        if (input.message.type === "assistant") {
+            return this.consumeAssistantMessage(input.message, input.runId, input.messageIdHint ?? null);
+        }
+        if (input.message.type === "stream_event") {
+            return this.consumeStreamEvent(input.message, input.runId, input.messageIdHint ?? null);
+        }
+        return [];
+    }
+    consumeAssistantMessage(message, runId, messageIdHint) {
+        const messageId = this.readMessageIdFromAssistantMessage(message) ??
+            messageIdHint ??
+            this.resolveMessageId({ runId, createIfMissing: true, messageId: null });
+        if (!messageId) {
+            return [];
+        }
+        const state = this.ensureMessageState(messageId, runId);
+        const fragments = this.extractFragments(message.message?.content);
+        return this.applyAbsoluteFragments(state, fragments);
+    }
+    consumeStreamEvent(message, runId, messageIdHint) {
+        const event = message.event;
+        const eventType = readTrimmedString(event.type);
+        const streamEventMessageId = this.readMessageIdFromStreamEvent(event) ?? messageIdHint;
+        if (eventType === "message_start") {
+            const messageId = this.resolveMessageId({
+                runId,
+                createIfMissing: true,
+                messageId: streamEventMessageId,
+            });
+            if (!messageId) {
+                return [];
+            }
+            this.ensureMessageState(messageId, runId);
+            return [];
+        }
+        if (eventType === "message_stop") {
+            const messageId = this.resolveMessageId({
+                runId,
+                createIfMissing: false,
+                messageId: streamEventMessageId,
+            });
+            if (!messageId) {
+                return [];
+            }
+            return this.finalizeMessage(messageId, runId);
+        }
+        if (eventType === "content_block_start") {
+            return this.consumeDeltaContent(event.content_block, runId, streamEventMessageId);
+        }
+        if (eventType === "content_block_delta") {
+            return this.consumeDeltaContent(event.delta, runId, streamEventMessageId);
+        }
+        return [];
+    }
+    consumeDeltaContent(content, runId, messageIdHint) {
+        const fragments = this.extractFragments(content);
+        if (fragments.length === 0) {
+            return [];
+        }
+        const messageId = this.resolveMessageId({
+            runId,
+            createIfMissing: true,
+            messageId: messageIdHint,
+        });
+        if (!messageId) {
+            return [];
+        }
+        const state = this.ensureMessageState(messageId, runId);
+        return this.appendFragments(state, fragments);
+    }
+    appendFragments(state, fragments) {
+        for (const fragment of fragments) {
+            if (fragment.kind === "assistant") {
+                state.assistantText += fragment.text;
+            }
+            else {
+                state.reasoningText += fragment.text;
+            }
+        }
+        return this.emitNewContent(state);
+    }
+    applyAbsoluteFragments(state, fragments) {
+        const assistantText = fragments
+            .filter((fragment) => fragment.kind === "assistant")
+            .map((fragment) => fragment.text)
+            .join("");
+        const reasoningText = fragments
+            .filter((fragment) => fragment.kind === "reasoning")
+            .map((fragment) => fragment.text)
+            .join("");
+        if (assistantText.length > 0) {
+            if (!assistantText.startsWith(state.assistantText)) {
+                state.emittedAssistantLength = 0;
+            }
+            state.assistantText = assistantText;
+        }
+        if (reasoningText.length > 0) {
+            if (!reasoningText.startsWith(state.reasoningText)) {
+                state.emittedReasoningLength = 0;
+            }
+            state.reasoningText = reasoningText;
+        }
+        return this.emitNewContent(state);
+    }
+    finalizeMessage(messageId, runId) {
+        const state = this.messages.get(messageId);
+        if (!state) {
+            return [];
+        }
+        state.stopped = true;
+        const items = this.emitNewContent(state);
+        if (runId && this.activeMessageByRun.get(runId) === messageId) {
+            this.activeMessageByRun.delete(runId);
+        }
+        return items;
+    }
+    emitNewContent(state) {
+        const items = [];
+        const nextAssistantText = state.assistantText.slice(state.emittedAssistantLength);
+        if (nextAssistantText.length > 0 &&
+            nextAssistantText !== INTERRUPT_TOOL_USE_PLACEHOLDER) {
+            state.emittedAssistantLength = state.assistantText.length;
+            items.push({ type: "assistant_message", text: nextAssistantText });
+        }
+        const nextReasoningText = state.reasoningText.slice(state.emittedReasoningLength);
+        if (nextReasoningText.length > 0) {
+            state.emittedReasoningLength = state.reasoningText.length;
+            items.push({ type: "reasoning", text: nextReasoningText });
+        }
+        return items;
+    }
+    ensureMessageState(messageId, runId) {
+        const existing = this.messages.get(messageId);
+        if (existing) {
+            existing.stopped = false;
+            if (runId) {
+                this.activeMessageByRun.set(runId, messageId);
+            }
+            return existing;
+        }
+        const created = {
+            id: messageId,
+            assistantText: "",
+            reasoningText: "",
+            emittedAssistantLength: 0,
+            emittedReasoningLength: 0,
+            stopped: false,
+        };
+        this.messages.set(messageId, created);
+        if (runId) {
+            this.activeMessageByRun.set(runId, messageId);
+        }
+        return created;
+    }
+    resolveMessageId(input) {
+        if (input.messageId) {
+            return input.messageId;
+        }
+        if (input.runId) {
+            const active = this.activeMessageByRun.get(input.runId);
+            if (active) {
+                return active;
+            }
+        }
+        if (!input.createIfMissing) {
+            return null;
+        }
+        const synthetic = `synthetic-message-${++this.syntheticMessageCounter}`;
+        if (input.runId) {
+            this.activeMessageByRun.set(input.runId, synthetic);
+        }
+        return synthetic;
+    }
+    extractFragments(content) {
+        if (typeof content === "string") {
+            if (content.length === 0) {
+                return [];
+            }
+            return [{ kind: "assistant", text: content }];
+        }
+        const blocks = Array.isArray(content) ? content : [content];
+        const fragments = [];
+        for (const rawBlock of blocks) {
+            if (!isClaudeContentChunk(rawBlock)) {
+                continue;
+            }
+            if ((rawBlock.type === "text" || rawBlock.type === "text_delta") &&
+                typeof rawBlock.text === "string" &&
+                rawBlock.text.length > 0) {
+                fragments.push({ kind: "assistant", text: rawBlock.text });
+            }
+            if ((rawBlock.type === "thinking" || rawBlock.type === "thinking_delta") &&
+                typeof rawBlock.thinking === "string" &&
+                rawBlock.thinking.length > 0) {
+                fragments.push({ kind: "reasoning", text: rawBlock.thinking });
+            }
+        }
+        return fragments;
+    }
+    readMessageIdFromAssistantMessage(message) {
+        const candidate = message;
+        return readTrimmedString(candidate.message_id) ??
+            readTrimmedString(candidate.message?.id) ??
+            null;
+    }
+    readMessageIdFromStreamEvent(event) {
+        const message = event.message;
+        return (readTrimmedString(event.message_id) ??
+            readTrimmedString(message?.id) ??
+            null);
+    }
+}
+function isMetadataOnlySdkMessage(message) {
+    if (message.type === "system") {
+        return true;
+    }
+    if (message.type !== "user") {
+        return false;
+    }
+    if (isSyntheticUserEntry(message)) {
+        return true;
+    }
+    return isTaskNotificationUserContent(message.message?.content);
+}
+function isSyntheticUserEntry(entry) {
+    if (!entry || typeof entry !== "object") {
+        return false;
+    }
+    return entry.isSynthetic === true;
+}
+export function readEventIdentifiers(message) {
+    const root = message;
+    const messageType = readTrimmedString(root.type);
+    const streamEvent = root.event;
+    const streamEventMessage = streamEvent?.message;
+    const messageContainer = root.message;
+    return {
+        taskId: readTrimmedString(root.task_id) ??
+            readTrimmedString(streamEvent?.task_id) ??
+            readTrimmedString(streamEventMessage?.task_id) ??
+            readTrimmedString(messageContainer?.task_id) ??
+            null,
+        parentMessageId: readTrimmedString(root.parent_message_id) ??
+            readTrimmedString(streamEvent?.parent_message_id) ??
+            readTrimmedString(streamEventMessage?.parent_message_id) ??
+            readTrimmedString(messageContainer?.parent_message_id) ??
+            null,
+        messageId: readTrimmedString(root.message_id) ??
+            readTrimmedString(streamEvent?.message_id) ??
+            readTrimmedString(streamEventMessage?.id) ??
+            readTrimmedString(streamEventMessage?.message_id) ??
+            readTrimmedString(messageContainer?.id) ??
+            readTrimmedString(messageContainer?.message_id) ??
+            (messageType === "user" ? readTrimmedString(root.uuid) : null) ??
+            null,
+    };
+}
 export class ClaudeAgentClient {
     constructor(options) {
         this.provider = "claude";
@@ -326,26 +949,6 @@ export class ClaudeAgentClient {
             this.claudePath = null;
         }
     }
-    applyRuntimeSettings(options) {
-        const hasEnvOverrides = Object.keys(this.runtimeSettings?.env ?? {}).length > 0;
-        const commandMode = this.runtimeSettings?.command?.mode;
-        const needsCustomSpawn = hasEnvOverrides || commandMode === "append" || commandMode === "replace";
-        if (!needsCustomSpawn) {
-            return options;
-        }
-        return {
-            ...options,
-            spawnClaudeCodeProcess: (spawnOptions) => {
-                const resolved = resolveClaudeSpawnCommand(spawnOptions, this.runtimeSettings);
-                return spawn(resolved.command, resolved.args, {
-                    cwd: spawnOptions.cwd,
-                    env: applyProviderEnv(spawnOptions.env, this.runtimeSettings),
-                    signal: spawnOptions.signal,
-                    stdio: ["pipe", "pipe", "pipe"],
-                });
-            },
-        };
-    }
     async createSession(config) {
         const claudeConfig = this.assertConfig(config);
         return new ClaudeAgentSession(claudeConfig, {
@@ -371,45 +974,8 @@ export class ClaudeAgentClient {
             logger: this.logger,
         });
     }
-    async listModels(options) {
-        const prompt = (async function* empty() { })();
-        const claudeOptions = {
-            cwd: options?.cwd ?? process.cwd(),
-            permissionMode: "plan",
-            includePartialMessages: false,
-            ...(this.claudePath ? { pathToClaudeCodeExecutable: this.claudePath } : {}),
-        };
-        const claudeQuery = query({
-            prompt,
-            options: this.applyRuntimeSettings(claudeOptions),
-        });
-        try {
-            const models = await claudeQuery.supportedModels();
-            return models.map((model) => ({
-                provider: "claude",
-                id: model.value,
-                label: normalizeClaudeModelLabel(model),
-                description: model.description,
-                thinkingOptions: [
-                    { id: "off", label: "Off", isDefault: true },
-                    { id: "on", label: "On" },
-                ],
-                defaultThinkingOptionId: "off",
-                metadata: {
-                    description: model.description,
-                },
-            }));
-        }
-        finally {
-            if (typeof claudeQuery.return === "function") {
-                try {
-                    await claudeQuery.return();
-                }
-                catch {
-                    // ignore shutdown errors
-                }
-            }
-        }
+    async listModels(_options) {
+        return listClaudeCatalogModels();
     }
     async listPersistedAgents(options) {
         const configDir = process.env.CLAUDE_CONFIG_DIR ?? path.join(os.homedir(), ".claude");
@@ -456,28 +1022,32 @@ class ClaudeAgentSession {
         this.toolUseIndexToId = new Map();
         this.toolUseInputBuffers = new Map();
         this.pendingPermissions = new Map();
-        this.eventQueue = null;
+        this.activeForegroundTurn = null;
+        this.liveEventQueue = new Pushable();
+        this.runTracker = new RunTracker();
+        this.timelineAssembler = new TimelineAssembler();
         this.persistedHistory = [];
         this.historyPending = false;
-        this.turnCancelRequested = false;
-        // NOTE: streamedAssistantTextThisTurn and streamedReasoningThisTurn were removed
-        // These flags are now tracked per-turn via TurnContext to prevent race conditions
-        // when multiple stream() calls overlap (e.g., interrupt + new message)
+        this.turnState = "idle";
+        this.preReplayMetadataSeen = false;
+        this.pendingAutonomousWakeReservations = 0;
+        this.nextRunOrdinal = 1;
         this.cancelCurrentTurn = null;
-        // Track the pending interrupt promise so we can await it in processPrompt
-        // This ensures the interrupt's response is consumed before we call query.next()
         this.pendingInterruptPromise = null;
-        // Track the current turn ID and active turn promise to serialize concurrent stream() calls
-        // and prevent race conditions where two processPrompt() loops run against the same query
-        this.currentTurnId = 0;
         this.activeTurnPromise = null;
         this.cachedRuntimeInfo = null;
         this.lastOptionsModel = null;
-        this.selectableModelIds = null;
+        this.selectableModelIds = buildClaudeSelectableModelIds();
+        this.selectableModelFamilyAliases = buildClaudeModelFamilyAliases();
         this.activeSidechains = new Map();
         this.compacting = false;
+        this.queryPumpPromise = null;
         this.queryRestartNeeded = false;
         this.userMessageIds = [];
+        this.localUserMessageIds = new Set();
+        this.suppressLocalReplayActivity = false;
+        this.recentStderr = "";
+        this.closed = false;
         this.handlePermissionRequest = async (toolName, input, options) => {
             const requestId = `permission-${randomUUID()}`;
             const kind = resolvePermissionKind(toolName, input);
@@ -520,19 +1090,6 @@ class ClaudeAgentSession {
                         }
                     }
                 };
-                const timeout = setTimeout(() => {
-                    this.pendingPermissions.delete(requestId);
-                    cleanup();
-                    const error = new Error("Permission request timed out");
-                    this.pushEvent({
-                        type: "permission_resolved",
-                        provider: "claude",
-                        requestId,
-                        resolution: { behavior: "deny", message: "timeout" },
-                    });
-                    reject(error);
-                }, DEFAULT_PERMISSION_TIMEOUT_MS);
-                cleanupFns.push(() => clearTimeout(timeout));
                 const abortHandler = () => {
                     this.pendingPermissions.delete(requestId);
                     cleanup();
@@ -640,81 +1197,125 @@ class ClaudeAgentSession {
     }
     async *stream(prompt, options) {
         void options;
-        // Increment turn ID to invalidate any in-flight processPrompt() loops from previous turns.
-        // This prevents race conditions where an interrupted turn's events get mixed with the new turn.
-        const turnId = ++this.currentTurnId;
-        // Cancel the previous turn if one exists. The caller of interrupt() is responsible
-        // for awaiting completion - the new turn just signals cancellation and proceeds.
         if (this.cancelCurrentTurn) {
             this.cancelCurrentTurn();
         }
-        // Reset cancel flag at the start of each turn to prevent stale state from previous turns
-        this.turnCancelRequested = false;
+        this.suppressLocalReplayActivity = false;
+        this.pendingAutonomousWakeReservations = 0;
         const slashCommand = this.resolveSlashCommandInvocation(prompt);
         if (slashCommand?.commandName === REWIND_COMMAND_NAME) {
             yield* this.streamRewindCommand(slashCommand);
             return;
         }
+        await this.awaitPendingInterruptPromise();
+        if (this.turnState === "autonomous" &&
+            this.runTracker.hasActiveRuns("autonomous")) {
+            await this.transitionAutonomousToForeground();
+        }
         const sdkMessage = this.toSdkUserMessage(prompt);
         const queue = new Pushable();
-        this.eventQueue = queue;
+        const run = this.createRun("foreground", queue);
+        this.runTracker.bindIdentifiers(run, {
+            taskId: null,
+            parentMessageId: null,
+            messageId: typeof sdkMessage.uuid === "string" ? sdkMessage.uuid : null,
+        });
+        const foregroundTurn = {
+            runId: run.id,
+            queue,
+        };
+        this.activeForegroundTurn = foregroundTurn;
+        this.preReplayMetadataSeen = false;
+        this.transitionTurnState("foreground", "foreground stream started");
+        this.clearRecentStderr();
         let finishedNaturally = false;
         let cancelIssued = false;
+        let queueDrainedWithoutTerminal = false;
+        const turnPromise = Promise.resolve();
+        this.activeTurnPromise = turnPromise;
         const requestCancel = () => {
             if (cancelIssued) {
                 return;
             }
             cancelIssued = true;
-            this.turnCancelRequested = true;
-            // Store the interrupt promise so processPrompt can await it before calling query.next()
-            this.pendingInterruptPromise = this.interruptActiveTurn().catch((error) => {
-                this.logger.warn({ err: error }, "Failed to interrupt during cancel");
-            });
-            this.flushPendingToolCalls();
-            // Push turn_canceled before ending the queue so consumers get proper lifecycle signals
-            queue.push({
+            if (this.activeForegroundTurn?.runId === run.id) {
+                this.activeForegroundTurn = null;
+            }
+            if (this.cancelCurrentTurn === requestCancel) {
+                this.cancelCurrentTurn = null;
+            }
+            this.rejectAllPendingPermissions(new Error("Permission request aborted"));
+            this.cancelRun(run, {
                 type: "turn_canceled",
                 provider: "claude",
                 reason: "Interrupted",
             });
-            queue.end();
+            this.pendingInterruptPromise = this.interruptActiveTurn().catch((error) => {
+                this.logger.warn({ err: error }, "Failed to interrupt during cancel");
+            });
         };
         this.cancelCurrentTurn = requestCancel;
-        // Start forwarding events and track the promise so future turns can wait for completion
-        const forwardPromise = this.forwardPromptEvents(sdkMessage, queue, turnId);
-        this.activeTurnPromise = forwardPromise;
-        forwardPromise.catch((error) => {
-            this.logger.error({ err: error }, "Unexpected error in forwardPromptEvents");
-        });
+        try {
+            await this.ensureQuery();
+            if (!this.input) {
+                throw new Error("Claude session input stream not initialized");
+            }
+            this.startQueryPump();
+            this.input.push(sdkMessage);
+        }
+        catch (error) {
+            this.failRun(run, error instanceof Error ? error.message : "Claude stream failed");
+            finishedNaturally = true;
+        }
         try {
             for await (const event of queue) {
-                yield event;
-                if (event.type === "turn_completed" ||
+                const isTerminalEvent = event.type === "turn_completed" ||
                     event.type === "turn_failed" ||
-                    event.type === "turn_canceled") {
+                    event.type === "turn_canceled";
+                if (isTerminalEvent) {
                     finishedNaturally = true;
+                }
+                yield event;
+                if (isTerminalEvent) {
                     break;
                 }
             }
+            if (!finishedNaturally && !cancelIssued) {
+                queueDrainedWithoutTerminal = true;
+            }
         }
         finally {
-            if (!finishedNaturally && !cancelIssued) {
+            if (!finishedNaturally && !cancelIssued && !queueDrainedWithoutTerminal) {
                 requestCancel();
             }
-            if (this.eventQueue === queue) {
-                this.eventQueue = null;
+            if (this.activeForegroundTurn === foregroundTurn) {
+                this.activeForegroundTurn = null;
             }
             if (this.cancelCurrentTurn === requestCancel) {
                 this.cancelCurrentTurn = null;
             }
-            // Clear the active turn promise if it's still ours
-            if (this.activeTurnPromise === forwardPromise) {
+            if (this.activeTurnPromise === turnPromise) {
                 this.activeTurnPromise = null;
             }
         }
     }
     async interrupt() {
-        this.cancelCurrentTurn?.();
+        if (this.cancelCurrentTurn) {
+            this.cancelCurrentTurn();
+            return;
+        }
+        const autonomousRuns = this.runTracker.listActiveRuns("autonomous");
+        if (autonomousRuns.length > 0) {
+            this.flushPendingToolCalls();
+            for (const run of autonomousRuns) {
+                this.emitRunEvent(run, {
+                    type: "turn_canceled",
+                    provider: "claude",
+                    reason: "Interrupted",
+                });
+            }
+        }
+        await this.interruptActiveTurn();
     }
     async *streamHistory() {
         if (!this.historyPending || this.persistedHistory.length === 0) {
@@ -727,6 +1328,14 @@ class ClaudeAgentSession {
             yield { type: "timeline", item, provider: "claude" };
         }
     }
+    async *streamLiveEvents() {
+        if (this.claudeSessionId) {
+            this.startQueryPump();
+        }
+        for await (const event of this.liveEventQueue) {
+            yield event;
+        }
+    }
     async getAvailableModes() {
         return this.availableModes;
     }
@@ -841,12 +1450,30 @@ class ClaudeAgentSession {
         return this.persistence;
     }
     async close() {
+        this.logger.trace({
+            claudeSessionId: this.claudeSessionId,
+            turnState: this.turnState,
+            hasQuery: Boolean(this.query),
+            hasInput: Boolean(this.input),
+            hasActiveForegroundTurn: Boolean(this.activeForegroundTurn),
+        }, "Claude session close: start");
+        this.closed = true;
         this.rejectAllPendingPermissions(new Error("Claude session closed"));
+        this.cancelCurrentTurn?.();
+        this.activeForegroundTurn?.queue.end();
+        this.activeForegroundTurn = null;
+        this.cancelCurrentTurn = null;
+        this.turnState = "idle";
+        this.suppressLocalReplayActivity = false;
+        this.pendingAutonomousWakeReservations = 0;
+        this.liveEventQueue.end();
+        this.activeTurnPromise = null;
         this.input?.end();
-        await this.query?.interrupt?.();
-        await this.query?.return?.();
+        await this.awaitWithTimeout(this.query?.interrupt?.(), "close query interrupt");
+        await this.awaitWithTimeout(this.query?.return?.(), "close query return");
         this.query = null;
         this.input = null;
+        this.logger.trace({ claudeSessionId: this.claudeSessionId, turnState: this.turnState }, "Claude session close: completed");
     }
     async listCommands() {
         const q = await this.ensureQuery();
@@ -1081,20 +1708,6 @@ class ClaudeAgentSession {
         }
         this.userMessageIds.push(messageId);
     }
-    async primeSelectableModelIds(query) {
-        try {
-            const models = await query.supportedModels();
-            const ids = models
-                .map((model) => model.value?.trim())
-                .filter((id) => typeof id === "string" && id.length > 0);
-            this.selectableModelIds = new Set(ids);
-            this.logger.debug({ modelIds: ids }, "Primed Claude selectable model IDs");
-        }
-        catch (error) {
-            this.selectableModelIds = null;
-            this.logger.warn({ err: error }, "Failed to prime Claude selectable model IDs");
-        }
-    }
     async ensureQuery() {
         if (this.query && !this.queryRestartNeeded) {
             return this.query;
@@ -1111,13 +1724,35 @@ class ClaudeAgentSession {
         }
         const input = new Pushable();
         const options = this.buildOptions();
-        this.logger.debug({ options }, "claude query");
+        this.logger.debug({ options: summarizeClaudeOptionsForLog(options) }, "claude query");
         this.input = input;
         this.query = query({ prompt: input, options });
-        await this.primeSelectableModelIds(this.query);
-        await this.query.setPermissionMode(this.currentMode);
+        // Do not kick off background control-plane queries here. Methods like
+        // supportedCommands()/setPermissionMode() may execute immediately after
+        // ensureQuery() (for listCommands()/setMode()), and sharing the same query
+        // control plane can cause those calls to wait behind supportedModels().
         return this.query;
     }
+    async awaitWithTimeout(promise, label) {
+        if (!promise) {
+            this.logger.trace({ label }, "Claude query operation skipped (no promise)");
+            return;
+        }
+        const startedAt = Date.now();
+        this.logger.trace({ label }, "Claude query operation wait start");
+        try {
+            await Promise.race([
+                promise,
+                new Promise((_, reject) => {
+                    setTimeout(() => reject(new Error("timeout")), 3000);
+                }),
+            ]);
+            this.logger.trace({ label, durationMs: Date.now() - startedAt }, "Claude query operation settled");
+        }
+        catch (error) {
+            this.logger.warn({ err: error, label }, "Claude query operation did not settle cleanly");
+        }
+    }
     buildOptions() {
         const configuredThinkingOptionId = this.config.thinkingOptionId;
         const thinkingOptionId = configuredThinkingOptionId && configuredThinkingOptionId !== "default"
@@ -1150,8 +1785,9 @@ class ClaudeAgentSession {
                 preset: "claude_code",
                 append: appendedSystemPrompt,
             },
-            settingSources: ["user", "project"],
+            settingSources: CLAUDE_SETTING_SOURCES,
             stderr: (data) => {
+                this.captureStderr(data);
                 this.logger.error({ stderr: data.trim() }, "Claude Agent SDK stderr");
             },
             env: {
@@ -1181,24 +1817,7 @@ class ClaudeAgentSession {
         return this.applyRuntimeSettings(base);
     }
     applyRuntimeSettings(options) {
-        const hasEnvOverrides = Object.keys(this.runtimeSettings?.env ?? {}).length > 0;
-        const commandMode = this.runtimeSettings?.command?.mode;
-        const needsCustomSpawn = hasEnvOverrides || commandMode === "append" || commandMode === "replace";
-        if (!needsCustomSpawn) {
-            return options;
-        }
-        return {
-            ...options,
-            spawnClaudeCodeProcess: (spawnOptions) => {
-                const resolved = resolveClaudeSpawnCommand(spawnOptions, this.runtimeSettings);
-                return spawn(resolved.command, resolved.args, {
-                    cwd: spawnOptions.cwd,
-                    env: applyProviderEnv(spawnOptions.env, this.runtimeSettings),
-                    signal: spawnOptions.signal,
-                    stdio: ["pipe", "pipe", "pipe"],
-                });
-            },
-        };
+        return applyRuntimeSettingsToClaudeOptions(options, this.runtimeSettings);
     }
     normalizeMcpServers(servers) {
         const result = {};
@@ -1226,191 +1845,828 @@ class ClaudeAgentSession {
                 }
             }
         }
-        else {
-            content.push({ type: "text", text: prompt });
+        else {
+            content.push({ type: "text", text: prompt });
+        }
+        const messageId = randomUUID();
+        this.rememberUserMessageId(messageId);
+        this.localUserMessageIds.add(messageId);
+        return {
+            type: "user",
+            message: {
+                role: "user",
+                content,
+            },
+            parent_tool_use_id: null,
+            uuid: messageId,
+            session_id: this.claudeSessionId ?? "",
+        };
+    }
+    async awaitPendingInterruptPromise() {
+        if (!this.pendingInterruptPromise) {
+            return;
+        }
+        await this.pendingInterruptPromise;
+        this.pendingInterruptPromise = null;
+    }
+    createRun(owner, queue) {
+        const runId = `${owner}-run-${this.nextRunOrdinal++}`;
+        const run = this.runTracker.createRun({
+            id: runId,
+            owner,
+            queue,
+            promptReplaySeen: owner === "autonomous",
+        });
+        this.logger.debug({ runId, owner, state: run.state }, "Created Claude run");
+        return run;
+    }
+    transitionTurnState(next, reason) {
+        if (this.turnState === next) {
+            return;
+        }
+        this.logger.debug({ from: this.turnState, to: next, reason }, "Claude turn state transition");
+        this.turnState = next;
+    }
+    transitionTurnStateFromActiveRuns(reason) {
+        if (this.runTracker.hasActiveRuns("foreground")) {
+            this.transitionTurnState("foreground", reason);
+            return;
+        }
+        if (this.runTracker.hasActiveRuns("autonomous")) {
+            this.transitionTurnState("autonomous", reason);
+            return;
+        }
+        this.transitionTurnState("idle", reason);
+    }
+    failRun(run, errorMessage) {
+        this.emitRunEvent(run, this.buildTurnFailedEvent(errorMessage));
+    }
+    buildTurnFailedEvent(errorMessage) {
+        const normalized = errorMessage.trim() || "Claude run failed";
+        const exitCodeMatch = normalized.match(/\bcode\s+(\d+)\b/i);
+        const code = exitCodeMatch ? exitCodeMatch[1] : undefined;
+        const diagnostic = this.getRecentStderrDiagnostic();
+        return {
+            type: "turn_failed",
+            provider: "claude",
+            error: normalized,
+            ...(code ? { code } : {}),
+            ...(diagnostic ? { diagnostic } : {}),
+        };
+    }
+    captureStderr(data) {
+        const text = data.trim();
+        if (!text) {
+            return;
+        }
+        const combined = this.recentStderr ? `${this.recentStderr}\n${text}` : text;
+        this.recentStderr = combined.slice(-MAX_RECENT_STDERR_CHARS);
+    }
+    clearRecentStderr() {
+        this.recentStderr = "";
+    }
+    getRecentStderrDiagnostic() {
+        const text = this.recentStderr.trim();
+        return text.length > 0 ? text : undefined;
+    }
+    cancelRun(run, event) {
+        this.flushPendingToolCalls();
+        this.emitRunEvent(run, event);
+    }
+    emitRunEvent(run, event) {
+        if (event.type === "turn_started" ||
+            event.type === "turn_completed" ||
+            event.type === "turn_failed" ||
+            event.type === "turn_canceled") {
+            this.logger.trace({
+                runId: run.id,
+                owner: run.owner,
+                runState: run.state,
+                eventType: event.type,
+                routedTo: run.owner === "foreground" && run.queue ? "foreground_queue" : "live_queue",
+            }, "Claude run event emitted");
+        }
+        if (run.owner === "foreground" && run.queue) {
+            run.queue.push(event);
+            if (event.type === "turn_completed" ||
+                event.type === "turn_failed" ||
+                event.type === "turn_canceled") {
+                run.queue.end();
+            }
+        }
+        else {
+            this.liveEventQueue.push(event);
+        }
+        this.handleRunTerminalEvent(run, event);
+    }
+    handleRunTerminalEvent(run, event) {
+        if (event.type === "turn_completed") {
+            this.runTracker.complete(run, "completed");
+        }
+        else if (event.type === "turn_failed") {
+            this.runTracker.complete(run, "error");
+        }
+        else if (event.type === "turn_canceled") {
+            this.runTracker.complete(run, "interrupted");
+        }
+        else {
+            return;
+        }
+        if (this.activeForegroundTurn?.runId === run.id) {
+            this.activeForegroundTurn = null;
+            this.preReplayMetadataSeen = false;
+        }
+        this.logger.trace({
+            runId: run.id,
+            owner: run.owner,
+            eventType: event.type,
+            runState: run.state,
+            hasActiveForegroundTurn: Boolean(this.activeForegroundTurn),
+        }, "Claude run terminal event handled");
+        this.transitionTurnStateFromActiveRuns(`run ${run.id} terminal`);
+    }
+    async transitionAutonomousToForeground() {
+        const autonomousRuns = this.runTracker.listActiveRuns("autonomous");
+        if (autonomousRuns.length === 0) {
+            this.transitionTurnStateFromActiveRuns("no autonomous runs to transition");
+            return;
+        }
+        this.logger.debug({ runIds: autonomousRuns.map((run) => run.id) }, "Transitioning autonomous runs to foreground ownership");
+        this.flushPendingToolCalls();
+        for (const run of autonomousRuns) {
+            this.emitRunEvent(run, {
+                type: "turn_canceled",
+                provider: "claude",
+                reason: "Interrupted by foreground prompt",
+            });
+        }
+        this.pendingInterruptPromise = this.interruptActiveTurn().catch((error) => {
+            this.logger.warn({ err: error }, "Failed to interrupt autonomous run during foreground transition");
+        });
+        await this.awaitPendingInterruptPromise();
+        this.transitionTurnStateFromActiveRuns("autonomous interrupted for foreground");
+    }
+    routeMessage(normalized) {
+        if (normalized.metadataOnly) {
+            if (normalized.message.type === "user" &&
+                isTaskNotificationUserContent(normalized.message.message?.content)) {
+                this.reserveAutonomousWake("task_notification");
+            }
+            this.notePreReplayMetadata(normalized.message);
+            return { run: null, reason: "metadata" };
+        }
+        const hasIdentifiers = Boolean(normalized.identifiers.taskId ||
+            normalized.identifiers.parentMessageId ||
+            normalized.identifiers.messageId);
+        const byIdentifiers = this.runTracker.resolveByIdentifiers(normalized.identifiers);
+        if (byIdentifiers.run) {
+            return byIdentifiers;
+        }
+        if (this.turnState === "autonomous") {
+            const activeAutonomousRun = this.runTracker.getLatestActiveRun("autonomous");
+            if (activeAutonomousRun) {
+                return { run: activeAutonomousRun, reason: "unbound_autonomous" };
+            }
+        }
+        const foregroundRun = this.activeForegroundTurn
+            ? this.runTracker.getRun(this.activeForegroundTurn.runId)
+            : null;
+        // A previously unseen task_id during foreground ownership is deterministic
+        // evidence of a distinct autonomous wake/run, not foreground response text.
+        if (this.turnState === "foreground" &&
+            foregroundRun &&
+            normalized.identifiers.taskId) {
+            const incomingTaskId = normalized.identifiers.taskId;
+            // Foreground must claim its first task_id; otherwise early foreground
+            // result events can be misrouted to autonomous fallback runs.
+            if (foregroundRun.taskIds.size === 0) {
+                if (foregroundRun.state !== "finalizing") {
+                    return { run: foregroundRun, reason: "foreground" };
+                }
+            }
+            else if (foregroundRun.taskIds.has(incomingTaskId)) {
+                return { run: foregroundRun, reason: "foreground" };
+            }
+            const autonomousRun = this.createRun("autonomous", null);
+            this.emitRunEvent(autonomousRun, { type: "turn_started", provider: "claude" });
+            return { run: autonomousRun, reason: "task_id_new" };
+        }
+        if (this.turnState === "foreground" &&
+            foregroundRun &&
+            this.shouldPreferForegroundRun({
+                run: foregroundRun,
+                message: normalized.message,
+            })) {
+            return { run: foregroundRun, reason: "foreground" };
         }
-        const messageId = randomUUID();
-        this.rememberUserMessageId(messageId);
-        return {
-            type: "user",
-            message: {
-                role: "user",
-                content,
-            },
-            parent_tool_use_id: null,
-            uuid: messageId,
-            session_id: this.claudeSessionId ?? "",
-        };
+        if (!hasIdentifiers) {
+            if (this.pendingAutonomousWakeReservations > 0) {
+                const reservedAutonomousRun = this.claimOrCreateAutonomousRun("reservation_unbound");
+                return {
+                    run: reservedAutonomousRun,
+                    reason: "unbound_autonomous",
+                };
+            }
+            const activeAutonomousRun = this.runTracker.getLatestActiveRun("autonomous");
+            if (activeAutonomousRun) {
+                return { run: activeAutonomousRun, reason: "unbound_autonomous" };
+            }
+        }
+        if (this.pendingAutonomousWakeReservations > 0) {
+            const reservedAutonomousRun = this.claimOrCreateAutonomousRun("reservation_fallback");
+            return { run: reservedAutonomousRun, reason: "fallback" };
+        }
+        const autonomousRun = this.createRun("autonomous", null);
+        this.emitRunEvent(autonomousRun, { type: "turn_started", provider: "claude" });
+        return { run: autonomousRun, reason: "fallback" };
+    }
+    shouldPreferForegroundRun(input) {
+        const { run, message } = input;
+        if (run.state === "completed" ||
+            run.state === "interrupted" ||
+            run.state === "error") {
+            return false;
+        }
+        // Before prompt replay is observed, prefer foreground by default so the
+        // first turn cannot be stranded in autonomous fallback. If metadata churn
+        // was observed pre-replay, stay conservative and wait for replay.
+        if (!run.promptReplaySeen) {
+            if (this.isToolUseBoundaryStreamEvent(input.message)) {
+                return true;
+            }
+            // Keep pre-replay result events with the foreground run so stale result
+            // bursts cannot consume autonomous wake reservations.
+            if (message.type === "result") {
+                return true;
+            }
+            if (message.type === "assistant" ||
+                message.type === "stream_event" ||
+                message.type === "tool_progress") {
+                return !this.preReplayMetadataSeen;
+            }
+            return true;
+        }
+        if (run.state === "finalizing" &&
+            (message.type === "assistant" || message.type === "stream_event")) {
+            return false;
+        }
+        return true;
     }
-    async *processPrompt(sdkMessage, turnId) {
-        // If there's a pending interrupt, await it BEFORE calling ensureQuery().
-        // interruptActiveTurn() clears this.query after interrupt() returns,
-        // so we must wait for it to complete before we try to get the query.
-        if (this.pendingInterruptPromise) {
-            await this.pendingInterruptPromise;
-            this.pendingInterruptPromise = null;
+    isToolUseBoundaryStreamEvent(message) {
+        if (message.type !== "stream_event") {
+            return false;
+        }
+        const event = message.event;
+        if (!event || event.type !== "message_delta") {
+            return false;
         }
-        // Check if we were superseded while waiting for the interrupt
-        if (this.currentTurnId !== turnId) {
+        const delta = "delta" in event && event.delta && typeof event.delta === "object"
+            ? event.delta
+            : null;
+        return delta?.stop_reason === "tool_use";
+    }
+    notePreReplayMetadata(message) {
+        if (this.turnState !== "foreground") {
             return;
         }
-        const query = await this.ensureQuery();
-        if (!this.input) {
-            throw new Error("Claude session input stream not initialized");
+        const foregroundRun = this.activeForegroundTurn
+            ? this.runTracker.getRun(this.activeForegroundTurn.runId)
+            : null;
+        if (!foregroundRun || foregroundRun.promptReplaySeen) {
+            return;
         }
-        this.input.push(sdkMessage);
-        while (true) {
-            // Check if this turn has been superseded by a new one.
-            if (this.currentTurnId !== turnId) {
-                break;
+        if (message.type === "system" && message.subtype === "init") {
+            return;
+        }
+        this.preReplayMetadataSeen = true;
+    }
+    reserveAutonomousWake(reason) {
+        this.pendingAutonomousWakeReservations += 1;
+        this.logger.debug({
+            reason,
+            pendingAutonomousWakeReservations: this.pendingAutonomousWakeReservations,
+        }, "Reserved autonomous wake");
+    }
+    claimOrCreateAutonomousRun(reason) {
+        const existing = this.runTracker.getLatestActiveRun("autonomous");
+        if (existing) {
+            if (this.pendingAutonomousWakeReservations > 0) {
+                this.pendingAutonomousWakeReservations -= 1;
+            }
+            this.logger.debug({
+                reason,
+                runId: existing.id,
+                pendingAutonomousWakeReservations: this.pendingAutonomousWakeReservations,
+            }, "Claimed autonomous wake reservation on existing run");
+            return existing;
+        }
+        const run = this.createRun("autonomous", null);
+        this.emitRunEvent(run, { type: "turn_started", provider: "claude" });
+        if (this.pendingAutonomousWakeReservations > 0) {
+            this.pendingAutonomousWakeReservations -= 1;
+        }
+        this.logger.debug({
+            reason,
+            runId: run.id,
+            pendingAutonomousWakeReservations: this.pendingAutonomousWakeReservations,
+        }, "Claimed autonomous wake reservation with new run");
+        return run;
+    }
+    startQueryPump() {
+        if (this.closed || this.queryPumpPromise) {
+            return;
+        }
+        const pump = this.runQueryPump().catch((error) => {
+            this.logger.warn({ err: error }, "Claude query pump exited unexpectedly");
+        });
+        this.queryPumpPromise = pump;
+        pump.finally(() => {
+            if (this.queryPumpPromise === pump) {
+                this.queryPumpPromise = null;
             }
-            const { value, done } = await query.next();
-            if (done) {
-                break;
+        });
+    }
+    async runQueryPump() {
+        while (!this.closed) {
+            if (!this.claudeSessionId && !this.activeForegroundTurn && !this.query) {
+                await this.waitForLiveHistoryPoll();
+                continue;
             }
-            if (!value) {
+            let q;
+            try {
+                q = await this.ensureQuery();
+            }
+            catch (error) {
+                this.logger.warn({ err: error }, "Failed to initialize Claude query pump");
+                await this.waitForLiveHistoryPoll();
                 continue;
             }
-            // Double-check turn ID after awaiting, in case a new turn started while we waited
-            if (this.currentTurnId !== turnId) {
-                break;
+            let next;
+            try {
+                next = await q.next();
+                this.logger.info({ claudeSessionId: this.claudeSessionId, next }, "Claude query pump raw next()");
             }
-            yield value;
-            if (value.type === "result") {
-                break;
+            catch (error) {
+                this.logger.warn({ err: error }, "Claude query pump next() failed");
+                for (const run of this.runTracker.listActiveRuns()) {
+                    this.failRun(run, error instanceof Error ? error.message : "Claude stream failed");
+                }
+                this.input?.end();
+                await this.awaitWithTimeout(q.return?.(), "query pump return after failure");
+                if (this.query === q) {
+                    this.query = null;
+                    this.input = null;
+                }
+                await this.waitForLiveHistoryPoll();
+                continue;
             }
-        }
-    }
-    async forwardPromptEvents(message, queue, turnId) {
-        // Create a turn-local context to track streaming state.
-        // This prevents race conditions when a new stream() call interrupts a running one.
-        const turnContext = {
-            streamedAssistantTextThisTurn: false,
-            streamedReasoningThisTurn: false,
-        };
-        let completedNormally = false;
-        try {
-            for await (const sdkEvent of this.processPrompt(message, turnId)) {
-                // Check if this turn has been superseded before pushing events
-                if (this.currentTurnId !== turnId) {
-                    break;
+            if (next.done) {
+                this.logger.trace({
+                    claudeSessionId: this.claudeSessionId,
+                    activeRunCount: this.runTracker.listActiveRuns().length,
+                }, "Claude query pump next() returned done");
+                this.input?.end();
+                await this.awaitWithTimeout(q.return?.(), "query pump return on done");
+                if (this.query === q) {
+                    this.query = null;
+                    this.input = null;
                 }
-                const events = this.translateMessageToEvents(sdkEvent, turnContext);
-                for (const event of events) {
-                    queue.push(event);
-                    if (event.type === "turn_completed") {
-                        completedNormally = true;
+                const activeRuns = this.runTracker.listActiveRuns();
+                if (activeRuns.length > 0) {
+                    for (const run of activeRuns) {
+                        this.failRun(run, "Claude stream ended before terminal result");
                     }
                 }
+                await this.waitForLiveHistoryPoll();
+                continue;
             }
-        }
-        catch (error) {
-            if (!this.turnCancelRequested && this.currentTurnId === turnId) {
-                queue.push({
-                    type: "turn_failed",
-                    provider: "claude",
-                    error: error instanceof Error ? error.message : "Claude stream failed",
-                });
+            const sdkMessage = next.value;
+            if (!sdkMessage) {
+                continue;
+            }
+            try {
+                this.routeSdkMessageFromPump(sdkMessage);
+            }
+            catch (error) {
+                this.logger.warn({ err: error }, "Failed to route Claude SDK message from query pump");
             }
         }
-        finally {
-            // Emit terminal event for superseded turns so consumers get proper lifecycle signals.
-            // Use turn_canceled (not turn_failed) to distinguish intentional interruption from errors.
-            // Only emit if not already emitted by requestCancel() (indicated by turnCancelRequested).
-            const wasSuperseded = this.currentTurnId !== turnId;
-            if (wasSuperseded && !completedNormally && !this.turnCancelRequested) {
-                this.flushPendingToolCalls();
-                queue.push({
-                    type: "turn_canceled",
-                    provider: "claude",
-                    reason: "Interrupted by new message",
-                });
+    }
+    routeSdkMessageFromPump(message) {
+        if (this.shouldSuppressLocalReplayActivity(message)) {
+            return;
+        }
+        const identifiers = readEventIdentifiers(message);
+        const metadataOnly = isMetadataOnlySdkMessage(message);
+        const route = this.routeMessage({
+            message,
+            identifiers,
+            metadataOnly,
+        });
+        const suppressTerminalEvents = this.shouldSuppressReplayResultTerminal({
+            run: route.run,
+            message,
+        });
+        this.logger.trace({
+            claudeSessionId: this.claudeSessionId,
+            messageType: message.type,
+            routeReason: route.reason,
+            runId: route.run?.id ?? null,
+            runOwner: route.run?.owner ?? null,
+            suppressTerminalEvents,
+            metadataOnly,
+        }, "Claude query pump routed SDK message");
+        if (route.run) {
+            this.transitionTurnStateFromActiveRuns(`routed via ${route.reason}`);
+            this.runTracker.bindIdentifiers(route.run, identifiers);
+            if (!suppressTerminalEvents) {
+                this.updateRunLifecycleForMessage(route.run, message, identifiers);
+            }
+        }
+        const messageEvents = this.translateMessageToEvents(message, {
+            suppressAssistantText: true,
+            suppressReasoning: true,
+            suppressTerminalEvents,
+        });
+        const assistantTimelineItems = this.timelineAssembler.consume({
+            message,
+            runId: route.run?.id ?? null,
+            messageIdHint: identifiers.messageId,
+        });
+        const assistantTimelineEvents = assistantTimelineItems.map((item) => ({
+            type: "timeline",
+            item,
+            provider: "claude",
+        }));
+        const events = [...messageEvents, ...assistantTimelineEvents];
+        if (events.length === 0) {
+            return;
+        }
+        if (!route.run) {
+            this.dispatchMetadataEvents(events);
+            return;
+        }
+        for (const event of events) {
+            this.emitRunEvent(route.run, event);
+        }
+    }
+    shouldSuppressReplayResultTerminal(input) {
+        const { run, message } = input;
+        if (!run || run.owner !== "foreground" || message.type !== "result") {
+            return false;
+        }
+        if (run.promptReplaySeen) {
+            return false;
+        }
+        if (run.state === "streaming" || run.state === "finalizing") {
+            return false;
+        }
+        const resultSubtype = "subtype" in message && typeof message.subtype === "string"
+            ? message.subtype
+            : null;
+        // Pre-replay success results are stale in practice (leftover from an
+        // earlier query segment) and must not end the current foreground run.
+        if (resultSubtype === "success") {
+            this.logger.trace({
+                runId: run.id,
+                runOwner: run.owner,
+                runState: run.state,
+                promptReplaySeen: run.promptReplaySeen,
+                resultSubtype,
+            }, "Suppressing pre-replay foreground success result terminal event");
+            return true;
+        }
+        // For non-success results, keep the metadata-churn guard to avoid
+        // suppressing legitimate hard failures.
+        return this.preReplayMetadataSeen;
+    }
+    dispatchMetadataEvents(events) {
+        for (const event of events) {
+            this.pushEvent(event);
+        }
+    }
+    updateRunLifecycleForMessage(run, message, identifiers) {
+        const previousState = run.state;
+        if (message.type === "user" &&
+            identifiers.messageId &&
+            run.messageIds.has(identifiers.messageId)) {
+            run.promptReplaySeen = true;
+            this.preReplayMetadataSeen = false;
+        }
+        if (run.state === "queued") {
+            this.runTracker.transition(run, "awaiting_response");
+        }
+        if (message.type === "assistant" ||
+            message.type === "stream_event" ||
+            message.type === "tool_progress") {
+            this.runTracker.transition(run, "streaming");
+            return;
+        }
+        if (message.type === "result") {
+            this.runTracker.transition(run, "finalizing");
+        }
+        else {
+            return;
+        }
+        if (run.state !== previousState) {
+            this.logger.trace({
+                runId: run.id,
+                owner: run.owner,
+                messageType: message.type,
+                previousState,
+                nextState: run.state,
+                taskId: identifiers.taskId,
+                parentMessageId: identifiers.parentMessageId,
+                messageId: identifiers.messageId,
+            }, "Updated Claude run lifecycle from SDK message");
+        }
+    }
+    shouldSuppressLocalReplayActivity(message) {
+        const localReplay = this.isLocalReplayUserMessage(message);
+        if (!this.activeForegroundTurn && localReplay) {
+            this.suppressLocalReplayActivity = true;
+            this.logger.debug({ uuid: message.uuid }, "Suppressing local replay user message from live pump");
+            return true;
+        }
+        if (!this.suppressLocalReplayActivity) {
+            return false;
+        }
+        // Suppress only replay scaffolding. Do not suppress autonomous
+        // assistant/result events; otherwise task-notification replies can be dropped.
+        if (localReplay) {
+            return true;
+        }
+        if (message.type === "system") {
+            return true;
+        }
+        const identifiers = readEventIdentifiers(message);
+        const hasIdentifiers = Boolean(identifiers.taskId || identifiers.parentMessageId || identifiers.messageId);
+        if (message.type !== "user" && !hasIdentifiers) {
+            if (this.pendingAutonomousWakeReservations > 0) {
+                this.suppressLocalReplayActivity = false;
+                return false;
             }
-            this.turnCancelRequested = false;
-            queue.end();
+            return true;
+        }
+        if (message.type === "user") {
+            this.suppressLocalReplayActivity = false;
+            return false;
         }
+        this.suppressLocalReplayActivity = false;
+        return false;
+    }
+    isLocalReplayUserMessage(message) {
+        if (message.type !== "user") {
+            return false;
+        }
+        const uuid = readTrimmedString(message.uuid);
+        if (!uuid) {
+            return false;
+        }
+        return this.localUserMessageIds.has(uuid);
     }
     async interruptActiveTurn() {
         const queryToInterrupt = this.query;
         if (!queryToInterrupt || typeof queryToInterrupt.interrupt !== "function") {
-            this.logger.info("interruptActiveTurn: no query to interrupt");
+            this.logger.debug("interruptActiveTurn: no query to interrupt");
             return;
         }
         try {
-            this.logger.info("interruptActiveTurn: calling query.interrupt()...");
+            this.logger.debug("interruptActiveTurn: calling query.interrupt()...");
             const t0 = Date.now();
             await queryToInterrupt.interrupt();
-            this.logger.info({ durationMs: Date.now() - t0 }, "interruptActiveTurn: query.interrupt() returned");
+            this.logger.debug({ durationMs: Date.now() - t0 }, "interruptActiveTurn: query.interrupt() returned");
             // After interrupt(), the query iterator is done (returns done: true).
             // Clear it so ensureQuery() creates a fresh query for the next turn.
             // Also end the input stream and call return() to clean up the SDK process.
             this.input?.end();
-            this.logger.info("interruptActiveTurn: calling query.return()...");
+            this.logger.debug("interruptActiveTurn: calling query.return()...");
             const t1 = Date.now();
             await queryToInterrupt.return?.();
-            this.logger.info({ durationMs: Date.now() - t1 }, "interruptActiveTurn: query.return() returned");
+            this.logger.debug({ durationMs: Date.now() - t1 }, "interruptActiveTurn: query.return() returned");
             this.query = null;
             this.input = null;
             this.queryRestartNeeded = false;
         }
         catch (error) {
             this.logger.warn({ err: error }, "Failed to interrupt active turn");
+            // If interrupt fails, the SDK iterator may remain in an indeterminate state.
+            // Force a teardown/recreate path so the next turn cannot reuse stale query state.
+            this.queryRestartNeeded = true;
         }
     }
     handleSidechainMessage(message, parentToolUseId) {
-        let toolName;
-        if (message.type === "assistant") {
-            const content = message.message?.content;
-            if (Array.isArray(content)) {
-                for (const block of content) {
-                    if (isClaudeContentChunk(block) &&
-                        (block.type === "tool_use" || block.type === "mcp_tool_use" || block.type === "server_tool_use") &&
-                        typeof block.name === "string") {
-                        toolName = block.name;
-                        break;
-                    }
-                }
-            }
-        }
-        else if (message.type === "stream_event") {
-            const event = message.event;
-            if (event.type === "content_block_start") {
-                const cb = isClaudeContentChunk(event.content_block) ? event.content_block : null;
-                if (cb?.type === "tool_use" && typeof cb.name === "string") {
-                    toolName = cb.name;
-                }
+        const state = this.activeSidechains.get(parentToolUseId) ??
+            {
+                actions: [],
+                actionKeys: [],
+                nextActionIndex: 1,
+                actionIndexByKey: new Map(),
+            };
+        this.activeSidechains.set(parentToolUseId, state);
+        const contextUpdated = this.updateSubAgentContextFromTaskInput(state, parentToolUseId);
+        const actionCandidates = this.extractSubAgentActionCandidates(message);
+        let actionUpdated = false;
+        for (const action of actionCandidates) {
+            if (this.appendSubAgentAction(state, action)) {
+                actionUpdated = true;
             }
         }
-        else if (message.type === "tool_progress") {
-            toolName = message.tool_name;
-        }
-        if (!toolName) {
-            return [];
-        }
-        const prev = this.activeSidechains.get(parentToolUseId);
-        if (prev === toolName) {
+        if (!contextUpdated && !actionUpdated) {
             return [];
         }
-        this.activeSidechains.set(parentToolUseId, toolName);
         const toolCall = mapClaudeRunningToolCall({
             name: "Task",
             callId: parentToolUseId,
             input: null,
             output: null,
-            metadata: { subAgentActivity: toolName },
         });
         if (!toolCall) {
             return [];
         }
+        const detail = {
+            type: "sub_agent",
+            ...(state.subAgentType ? { subAgentType: state.subAgentType } : {}),
+            ...(state.description ? { description: state.description } : {}),
+            log: state.actions
+                .map((action) => action.summary
+                ? `[${action.toolName}] ${action.summary}`
+                : `[${action.toolName}]`)
+                .join("\n"),
+            actions: state.actions.map((action) => ({
+                index: action.index,
+                toolName: action.toolName,
+                ...(action.summary ? { summary: action.summary } : {}),
+            })),
+        };
         return [
             {
                 type: "timeline",
-                item: toolCall,
+                item: {
+                    ...toolCall,
+                    detail,
+                },
                 provider: "claude",
             },
         ];
     }
-    translateMessageToEvents(message, turnContext) {
+    updateSubAgentContextFromTaskInput(state, parentToolUseId) {
+        const taskInput = this.toolUseCache.get(parentToolUseId)?.input;
+        const nextSubAgentType = this.normalizeSubAgentText(taskInput?.subagent_type);
+        const nextDescription = this.normalizeSubAgentText(taskInput?.description);
+        let changed = false;
+        if (nextSubAgentType && nextSubAgentType !== state.subAgentType) {
+            state.subAgentType = nextSubAgentType;
+            changed = true;
+        }
+        if (nextDescription && nextDescription !== state.description) {
+            state.description = nextDescription;
+            changed = true;
+        }
+        return changed;
+    }
+    normalizeSubAgentText(value) {
+        const normalized = readTrimmedString(value)?.replace(/\s+/g, " ");
+        if (!normalized) {
+            return undefined;
+        }
+        if (normalized.length <= MAX_SUB_AGENT_SUMMARY_CHARS) {
+            return normalized;
+        }
+        return `${normalized.slice(0, MAX_SUB_AGENT_SUMMARY_CHARS)}...`;
+    }
+    extractSubAgentActionCandidates(message) {
+        if (message.type === "assistant") {
+            const content = message.message?.content;
+            if (!Array.isArray(content)) {
+                return [];
+            }
+            const actions = [];
+            for (const block of content) {
+                if (!isClaudeContentChunk(block) ||
+                    !(block.type === "tool_use" ||
+                        block.type === "mcp_tool_use" ||
+                        block.type === "server_tool_use") ||
+                    typeof block.name !== "string") {
+                    continue;
+                }
+                const key = readTrimmedString(block.id) ??
+                    `assistant:${block.name}:${actions.length}`;
+                actions.push({
+                    key,
+                    toolName: block.name,
+                    input: block.input ?? null,
+                });
+            }
+            return actions;
+        }
+        if (message.type === "stream_event") {
+            const event = message.event;
+            if (event.type !== "content_block_start") {
+                return [];
+            }
+            const block = isClaudeContentChunk(event.content_block)
+                ? event.content_block
+                : null;
+            if (!block ||
+                !(block.type === "tool_use" ||
+                    block.type === "mcp_tool_use" ||
+                    block.type === "server_tool_use") ||
+                typeof block.name !== "string") {
+                return [];
+            }
+            const key = readTrimmedString(block.id) ??
+                `stream:${block.name}:${typeof event.index === "number" ? event.index : 0}`;
+            return [
+                {
+                    key,
+                    toolName: block.name,
+                    input: block.input ?? null,
+                },
+            ];
+        }
+        if (message.type === "tool_progress") {
+            const toolName = readTrimmedString(message.tool_name);
+            if (!toolName) {
+                return [];
+            }
+            const key = readTrimmedString(message.tool_use_id) ?? `progress:${toolName}`;
+            return [{ key, toolName, input: null }];
+        }
+        return [];
+    }
+    appendSubAgentAction(state, candidate) {
+        const normalizedToolName = readTrimmedString(candidate.toolName);
+        if (!normalizedToolName) {
+            return false;
+        }
+        const summary = this.deriveSubAgentActionSummary(normalizedToolName, candidate.input);
+        const existingIndex = state.actionIndexByKey.get(candidate.key);
+        if (existingIndex !== undefined) {
+            const existing = state.actions[existingIndex];
+            if (!existing) {
+                return false;
+            }
+            const nextSummary = existing.summary ?? summary;
+            const unchanged = existing.toolName === normalizedToolName &&
+                existing.summary === nextSummary;
+            if (unchanged) {
+                return false;
+            }
+            state.actions[existingIndex] = {
+                ...existing,
+                toolName: normalizedToolName,
+                ...(nextSummary ? { summary: nextSummary } : {}),
+            };
+            return true;
+        }
+        const nextEntry = {
+            index: state.nextActionIndex,
+            toolName: normalizedToolName,
+            ...(summary ? { summary } : {}),
+        };
+        state.nextActionIndex += 1;
+        state.actions.push(nextEntry);
+        state.actionKeys.push(candidate.key);
+        this.trimSubAgentTail(state);
+        this.rebuildSubAgentActionIndex(state);
+        return true;
+    }
+    trimSubAgentTail(state) {
+        while (state.actions.length > MAX_SUB_AGENT_LOG_ENTRIES) {
+            state.actions.shift();
+            state.actionKeys.shift();
+        }
+    }
+    rebuildSubAgentActionIndex(state) {
+        state.actionIndexByKey.clear();
+        for (let index = 0; index < state.actionKeys.length; index += 1) {
+            const key = state.actionKeys[index];
+            if (key) {
+                state.actionIndexByKey.set(key, index);
+            }
+        }
+    }
+    deriveSubAgentActionSummary(toolName, input) {
+        const runningToolCall = mapClaudeRunningToolCall({
+            name: toolName,
+            callId: `sub-agent-summary-${toolName}`,
+            input,
+            output: null,
+        });
+        if (!runningToolCall) {
+            return undefined;
+        }
+        const display = buildToolCallDisplayModel({
+            name: runningToolCall.name,
+            status: runningToolCall.status,
+            error: runningToolCall.error,
+            detail: runningToolCall.detail,
+            metadata: runningToolCall.metadata,
+        });
+        return this.normalizeSubAgentText(display.summary);
+    }
+    translateMessageToEvents(message, options) {
         const parentToolUseId = "parent_tool_use_id" in message
             ? message.parent_tool_use_id
             : null;
@@ -1418,6 +2674,14 @@ class ClaudeAgentSession {
             return this.handleSidechainMessage(message, parentToolUseId);
         }
         const events = [];
+        const fallbackThreadSessionId = this.captureSessionIdFromMessage(message);
+        if (fallbackThreadSessionId) {
+            events.push({
+                type: "thread_started",
+                provider: "claude",
+                sessionId: fallbackThreadSessionId,
+            });
+        }
         switch (message.type) {
             case "system":
                 if (message.subtype === "init") {
@@ -1442,20 +2706,33 @@ class ClaudeAgentSession {
                     }
                 }
                 else if (message.subtype === "compact_boundary") {
-                    const meta = message.compact_metadata;
+                    const compactMetadata = readCompactionMetadata(message);
                     events.push({
                         type: "timeline",
                         item: {
                             type: "compaction",
                             status: "completed",
-                            trigger: meta?.trigger === "manual" ? "manual" : "auto",
-                            preTokens: meta?.pre_tokens,
+                            trigger: compactMetadata?.trigger === "manual" ? "manual" : "auto",
+                            preTokens: compactMetadata?.preTokens,
                         },
                         provider: "claude",
                     });
                 }
+                else if (message.subtype === "task_notification") {
+                    const taskNotificationItem = mapTaskNotificationSystemRecordToToolCall(message);
+                    if (taskNotificationItem) {
+                        events.push({
+                            type: "timeline",
+                            item: taskNotificationItem,
+                            provider: "claude",
+                        });
+                    }
+                }
                 break;
             case "user": {
+                if (isSyntheticUserEntry(message)) {
+                    break;
+                }
                 if (this.compacting) {
                     this.compacting = false;
                     break;
@@ -1465,6 +2742,18 @@ class ClaudeAgentSession {
                     : undefined;
                 this.rememberUserMessageId(messageId);
                 const content = message.message?.content;
+                const taskNotificationItem = mapTaskNotificationUserContentToToolCall({
+                    content,
+                    messageId,
+                });
+                if (taskNotificationItem) {
+                    events.push({
+                        type: "timeline",
+                        item: taskNotificationItem,
+                        provider: "claude",
+                    });
+                    break;
+                }
                 if (typeof content === "string" && content.length > 0) {
                     // String content from user messages (e.g., local command output)
                     events.push({
@@ -1478,7 +2767,7 @@ class ClaudeAgentSession {
                     });
                 }
                 else if (Array.isArray(content)) {
-                    const timelineItems = this.mapBlocksToTimeline(content, { turnContext });
+                    const timelineItems = this.mapBlocksToTimeline(content);
                     for (const item of timelineItems) {
                         if (item.type === "user_message" && messageId && !item.messageId) {
                             events.push({
@@ -1495,9 +2784,8 @@ class ClaudeAgentSession {
             }
             case "assistant": {
                 const timelineItems = this.mapBlocksToTimeline(message.message.content, {
-                    turnContext,
-                    suppressAssistantText: turnContext.streamedAssistantTextThisTurn,
-                    suppressReasoning: turnContext.streamedReasoningThisTurn,
+                    suppressAssistantText: options?.suppressAssistantText ?? false,
+                    suppressReasoning: options?.suppressReasoning ?? false,
                 });
                 for (const item of timelineItems) {
                     events.push({ type: "timeline", item, provider: "claude" });
@@ -1505,13 +2793,19 @@ class ClaudeAgentSession {
                 break;
             }
             case "stream_event": {
-                const timelineItems = this.mapPartialEvent(message.event, turnContext);
+                const timelineItems = this.mapPartialEvent(message.event, {
+                    suppressAssistantText: options?.suppressAssistantText ?? false,
+                    suppressReasoning: options?.suppressReasoning ?? false,
+                });
                 for (const item of timelineItems) {
                     events.push({ type: "timeline", item, provider: "claude" });
                 }
                 break;
             }
             case "result": {
+                if (options?.suppressTerminalEvents) {
+                    break;
+                }
                 const usage = this.convertUsage(message);
                 if (message.subtype === "success") {
                     events.push({ type: "turn_completed", provider: "claude", usage });
@@ -1520,7 +2814,7 @@ class ClaudeAgentSession {
                     const errorMessage = "errors" in message && Array.isArray(message.errors) && message.errors.length > 0
                         ? message.errors.join("\n")
                         : "Claude run failed";
-                    events.push({ type: "turn_failed", provider: "claude", error: errorMessage });
+                    events.push(this.buildTurnFailedEvent(errorMessage));
                 }
                 break;
             }
@@ -1529,6 +2823,31 @@ class ClaudeAgentSession {
         }
         return events;
     }
+    captureSessionIdFromMessage(message) {
+        const msg = message;
+        const sessionIdRaw = typeof msg.session_id === "string"
+            ? msg.session_id
+            : typeof msg.sessionId === "string"
+                ? msg.sessionId
+                : typeof msg.session?.id === "string"
+                    ? msg.session.id
+                    : "";
+        const sessionId = sessionIdRaw.trim();
+        if (!sessionId) {
+            return null;
+        }
+        if (this.claudeSessionId === null) {
+            this.claudeSessionId = sessionId;
+            this.persistence = null;
+            return sessionId;
+        }
+        if (this.claudeSessionId === sessionId) {
+            return null;
+        }
+        throw new Error(`CRITICAL: Claude session ID overwrite detected! ` +
+            `Existing: ${this.claudeSessionId}, New: ${sessionId}. ` +
+            `This indicates a session identity corruption bug.`);
+    }
     handleSystemMessage(message) {
         if (message.subtype !== "init") {
             return null;
@@ -1572,6 +2891,7 @@ class ClaudeAgentSession {
             const normalizedModel = normalizeClaudeRuntimeModelId({
                 runtimeModelId: message.model,
                 supportedModelIds: this.selectableModelIds,
+                supportedModelFamilyAliases: this.selectableModelFamilyAliases,
                 configuredModelId: this.config.model ?? null,
                 currentModelId: this.lastOptionsModel,
             });
@@ -1608,6 +2928,7 @@ class ClaudeAgentSession {
             }
         }
         this.toolUseCache.clear();
+        this.activeSidechains.clear();
     }
     pushToolCall(item, target) {
         if (!item) {
@@ -1620,9 +2941,19 @@ class ClaudeAgentSession {
         this.enqueueTimeline(item);
     }
     pushEvent(event) {
-        if (this.eventQueue) {
-            this.eventQueue.push(event);
+        const foregroundTurn = this.activeForegroundTurn;
+        if (foregroundTurn) {
+            const run = this.runTracker.getRun(foregroundTurn.runId);
+            if (run &&
+                run.owner === "foreground" &&
+                run.queue === foregroundTurn.queue &&
+                this.runTracker.isRunActive(run)) {
+                foregroundTurn.queue.push(event);
+                return;
+            }
+            this.activeForegroundTurn = null;
         }
+        this.liveEventQueue.push(event);
     }
     normalizePermissionUpdates(updates) {
         if (!updates || updates.length === 0) {
@@ -1638,6 +2969,9 @@ class ClaudeAgentSession {
             this.pendingPermissions.delete(id);
         }
     }
+    waitForLiveHistoryPoll() {
+        return new Promise((resolve) => setTimeout(resolve, 250));
+    }
     loadPersistedHistory(sessionId) {
         try {
             const historyPath = this.resolveHistoryPath(sessionId);
@@ -1687,20 +3021,15 @@ class ClaudeAgentSession {
         return path.join(dir, `${sessionId}.jsonl`);
     }
     convertHistoryEntry(entry) {
-        return convertClaudeHistoryEntry(entry, (content) => this.mapBlocksToTimeline(content, { context: "history" }));
+        return convertClaudeHistoryEntry(entry, (content) => this.mapBlocksToTimeline(content));
     }
     mapBlocksToTimeline(content, options) {
-        const context = options?.context ?? "live";
-        const turnContext = options?.turnContext;
         const suppressAssistant = options?.suppressAssistantText ?? false;
         const suppressReasoning = options?.suppressReasoning ?? false;
         if (typeof content === "string") {
-            if (!content || content === "[Request interrupted by user for tool use]") {
+            if (!content || content === INTERRUPT_TOOL_USE_PLACEHOLDER) {
                 return [];
             }
-            if (context === "live" && turnContext) {
-                turnContext.streamedAssistantTextThisTurn = true;
-            }
             if (suppressAssistant) {
                 return [];
             }
@@ -1711,10 +3040,7 @@ class ClaudeAgentSession {
             switch (block.type) {
                 case "text":
                 case "text_delta":
-                    if (block.text && block.text !== "[Request interrupted by user for tool use]") {
-                        if (context === "live" && turnContext) {
-                            turnContext.streamedAssistantTextThisTurn = true;
-                        }
+                    if (block.text && block.text !== INTERRUPT_TOOL_USE_PLACEHOLDER) {
                         if (!suppressAssistant) {
                             items.push({ type: "assistant_message", text: block.text });
                         }
@@ -1723,9 +3049,6 @@ class ClaudeAgentSession {
                 case "thinking":
                 case "thinking_delta":
                     if (block.thinking) {
-                        if (context === "live" && turnContext) {
-                            turnContext.streamedReasoningThisTurn = true;
-                        }
                         if (!suppressReasoning) {
                             items.push({ type: "reasoning", text: block.thinking });
                         }
@@ -1797,6 +3120,7 @@ class ClaudeAgentSession {
         }
         if (typeof block.tool_use_id === "string") {
             this.toolUseCache.delete(block.tool_use_id);
+            this.activeSidechains.delete(block.tool_use_id);
         }
     }
     buildToolOutput(block, entry) {
@@ -1805,7 +3129,7 @@ class ClaudeAgentSession {
         }
         const server = entry?.server ?? block.server ?? "tool";
         const tool = entry?.name ?? block.tool_name ?? "tool";
-        const content = typeof block.content === "string" ? block.content : "";
+        const content = coerceToolResultContentToString(block.content);
         const input = entry?.input;
         // Build structured result based on tool type
         const structured = this.buildStructuredToolResult(server, tool, content, input);
@@ -1894,7 +3218,7 @@ class ClaudeAgentSession {
         }
         return undefined;
     }
-    mapPartialEvent(event, turnContext) {
+    mapPartialEvent(event, options) {
         if (event.type === "content_block_start") {
             const block = isClaudeContentChunk(event.content_block) ? event.content_block : null;
             if (block?.type === "tool_use" && typeof event.index === "number" && typeof block.id === "string") {
@@ -1920,10 +3244,18 @@ class ClaudeAgentSession {
         switch (event.type) {
             case "content_block_start":
                 return isClaudeContentChunk(event.content_block)
-                    ? this.mapBlocksToTimeline([event.content_block], { turnContext })
+                    ? this.mapBlocksToTimeline([event.content_block], {
+                        suppressAssistantText: options?.suppressAssistantText,
+                        suppressReasoning: options?.suppressReasoning,
+                    })
                     : [];
             case "content_block_delta":
-                return isClaudeContentChunk(event.delta) ? this.mapBlocksToTimeline([event.delta], { turnContext }) : [];
+                return isClaudeContentChunk(event.delta)
+                    ? this.mapBlocksToTimeline([event.delta], {
+                        suppressAssistantText: options?.suppressAssistantText,
+                        suppressReasoning: options?.suppressReasoning,
+                    })
+                    : [];
             default:
                 return [];
         }
@@ -2122,6 +3454,24 @@ function hasToolLikeBlock(block) {
     const type = typeof block.type === "string" ? block.type.toLowerCase() : "";
     return type.includes("tool");
 }
+function readCompactionMetadata(source) {
+    const candidates = [
+        source.compact_metadata,
+        source.compactMetadata,
+        source.compactionMetadata,
+    ];
+    for (const candidate of candidates) {
+        if (!candidate || typeof candidate !== "object") {
+            continue;
+        }
+        const metadata = candidate;
+        const trigger = typeof metadata.trigger === "string" ? metadata.trigger : undefined;
+        const preTokensRaw = metadata.preTokens ?? metadata.pre_tokens;
+        const preTokens = typeof preTokensRaw === "number" ? preTokensRaw : undefined;
+        return { trigger, preTokens };
+    }
+    return null;
+}
 function normalizeHistoryBlocks(content) {
     if (Array.isArray(content)) {
         const blocks = content.filter((entry) => isClaudeContentChunk(entry));
@@ -2134,16 +3484,26 @@ function normalizeHistoryBlocks(content) {
 }
 export function convertClaudeHistoryEntry(entry, mapBlocks) {
     if (entry.type === "system" && entry.subtype === "compact_boundary") {
+        const compactMetadata = readCompactionMetadata(entry);
         return [{
                 type: "compaction",
                 status: "completed",
-                trigger: entry.compactMetadata?.trigger === "manual" ? "manual" : "auto",
-                preTokens: entry.compactMetadata?.preTokens,
+                trigger: compactMetadata?.trigger === "manual" ? "manual" : "auto",
+                preTokens: compactMetadata?.preTokens,
             }];
     }
+    if (entry.type === "system") {
+        const taskNotificationItem = mapTaskNotificationSystemRecordToToolCall(entry);
+        if (taskNotificationItem) {
+            return [taskNotificationItem];
+        }
+    }
     if (entry.isCompactSummary) {
         return [];
     }
+    if (entry.type === "user" && isSyntheticUserEntry(entry)) {
+        return [];
+    }
     const message = entry?.message;
     if (!message || !("content" in message)) {
         return [];
@@ -2154,17 +3514,26 @@ export function convertClaudeHistoryEntry(entry, mapBlocks) {
         ? content
         : normalizedBlocks;
     const hasToolBlock = normalizedBlocks?.some((block) => hasToolLikeBlock(block)) ?? false;
+    const userMessageId = entry.type === "user" && typeof entry.uuid === "string" && entry.uuid.length > 0
+        ? entry.uuid
+        : null;
+    if (entry.type === "user") {
+        const taskNotificationItem = mapTaskNotificationUserContentToToolCall({
+            content,
+            messageId: userMessageId,
+        });
+        if (taskNotificationItem) {
+            return [taskNotificationItem];
+        }
+    }
     const timeline = [];
     if (entry.type === "user") {
         const text = extractUserMessageText(content);
         if (text) {
-            const messageId = typeof entry.uuid === "string" && entry.uuid.length > 0
-                ? entry.uuid
-                : undefined;
             timeline.push({
                 type: "user_message",
                 text,
-                ...(messageId ? { messageId } : {}),
+                ...(userMessageId ? { messageId: userMessageId } : {}),
             });
         }
     }
@@ -2306,6 +3675,9 @@ async function parseClaudeSessionDescriptor(filePath, mtime) {
         if (entry?.isSidechain) {
             continue;
         }
+        if (entry?.type === "user" && isSyntheticUserEntry(entry)) {
+            continue;
+        }
         if (!sessionId && typeof entry.sessionId === "string") {
             sessionId = entry.sessionId;
         }